| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Written by Mårten Svanfeldt, [email protected].
Particles is a general particle rendering and simple simulation plugin. It also contains a few simpler built-in implementations of particle emitters and effectors.
The following SCF class names are used (for csLoadPlugin):
Objects in this plugin implement the following SCF interfaces (get
with scfQueryInterface):
Use the `iParticleSystemFactory' SCF interface to access settings for a particle system factory. The definition of this interface can be found in `CS/include/imesh/particles.h' and that is also the include file you need to include in your applications to use this plugin. Using this interface you can access the material, default particle billboard setup, rotation mode, emitters, effectors and various other configuration parameters for a particle system factory.
Notice that once a particle system have been created from a factory, changing the factory won't change the instance. So in the case of particle systems the factory should be viewed as a template rather than a "parent".
Use the `iParticleSystem' SCF interface to access settings for a particle system. The definition of this interface can be found in `CS/include/imesh/particles.h' and that is also the include file you need to include in your applications to use this plugin. Using this interface you can access the material, default particle billboard setup, rotation mode, emitters, effectors and various other configuration parameters for a particle system.
The factory and object loader in much recognize the same set of keywords.
<renderorientation>orientation</renderorientation>Set how the particle billboards are oriented in relation to the world and the camera. See Particle billboard setup.
<rotationmode>rotation</rotationmode>Set how rotation of the particles affect the visual output. Valid values are `none', `texcoord' and `vertex'. Default is no effect (`none').
<sortmode>sort</sortmode>Control the particle front-to-back sorting mode. Valid values are `none', `distance' and `dot'.
<integrationmode>integration</integrationmode>Velocity to position integration mode. Valid values are `none', `linear' and `both'. Default is `linear'.
<commondirection x="" y="" z="" />Set common direction. Common direction is used as a reference direction for billboard setup for a few particle billboard orientations.
<transformmode>tmode</transformmode>Set the transform mode of the particle system and thereby the coordinate systems used. Valid values are `local', `localemitter', `world'.
<individualsize>yes/no</individualsize>Determin if particle rendering should use the individual size associated with each particle, or if the global <particlesize> property should be used.
<particlesize x="" y="" />Set global particle size.
<minbb>...</minbb>Set the minimum bounding box of the particles mesh. The particle system is only rendered when the bounding box is deemed visible (within frustum), and therefore it can sometimes be required to have a bigger bounding box than the current distribution of the particles.
<emitter type="">...</emitter>Add a built-in emitter to the particles system.
<effector type="">...</effector>Add a built-in effector to the particles system.
Also see the general documentation for keywords recognized both by factory and object. See Factory and Object Loader.
<deepcreation>yes/no</deepcreation>Enable or disable deep-copy on creation of particle systems.
<material>materialName</material>Set the default material for particle system factory.
<mixmode>mixmode</mixmode>Set the default mixmode for particle system factory.
Also see the general documentation for keywords recognized both by factory and object. See Factory and Object Loader.
<factory>factoryName</factory>Set the factory to use when creating the particle system.
<material>materialName</material>Set the material for particle system.
<mixmode>mixmode</mixmode>Set the mixmode for particle system.
The particle system have three basic parts
Apart from this the particles plugin also contains some management code to keep everything together and interface the rest of Crystal Space, as well as loading and saving from/to files.
The main part of work related to particle creation and movement is done in the particle update loop. The update loop is called once per frame for every visible particle system.
The steps of the update loop are:
The second big part of particles plugin is the particle billboard setup. In computations each particle is "point-like" however for rendering you have to give it an extent.
The particles plugin provides rendering in form of rectangular (quadratile) areas of settable size and orientation relative to the camera.
The particle billboards always face the camera location, so the camera to particle vector is used as normal. The camera up vector is used as up-vector for the billboards.
The billboards are aligned with the camera plane, and camera up and right vectors are used as billboard vectors. This is the default mode and the mode most other particle systems in Crystal Space have.
Use common up direction as up vector for particle and as `camface' face the camera properly. This makes the particles look like fixed around one axis.
Approximative version of `common' mode. Common up direction is used as billboard up direction and camera forward vector as plane normal. This mode is equal to old `Rain' particle system.
Almost the same as `common' mode, but instead of using a common direction the particle linear velocity is used as up direction.
Orients particle billboard according to the coordinate base defined by the quaternion in the particle (it's internal orientation). Setup is such that xy-plane is the billboard plane and positive z-axis normal.
Same as `self' mode, however particles are always facing camera. It is equivalent to two-sided particles.
Emitters are the entities responsible for emitting new particles into the particle system. Without any emitters there won't be any particles and nothing to see.
In principle an emitter is any class implementing the interface
`iParticleEmitter', so you can implement your own emitters, however for
convenience there are a few built in emitter types. These can be accessed via
the `crystalspace.mesh.object.particles.emitter' plugin class and interface
`iParticleBuiltinEmitterFactory' interface.
The built in emitters are also loadable via the normal particle loader using
<emitter type=".."> tags. The available types are:
Many of the options are same for several of the emitter types, so below is a description of all available options for the built in emitters and which type of emitters they apply to.
Keyword | Applies to | Description |
| `all' | Should the emitter emit particles at all. |
| `all' | Start time of emitter relative to first time particle gets into view. |
| `all' | Duration for which the emitter should be active. |
| `all' | Emission rate in particles per second. |
| `all' | Initial TTL of the particles will be assigned randomly between min and max values. |
| `all' | Initial mass of the particles will be assigned randomly between min and max values. |
| `all' | Emitter center position. |
| `all' | Particle placement relative to emitter. Valid values `center', `volume', `surface'. Default is `center'. |
| `all' | Sets if all particles should have the same uniform velocity vector or if only the magnitude should be used and direction should be emitter-specific. |
| `all' | Set initial linear velocity vector. |
| `all' | Set initial angular velocity vector. |
| `sphere', `cylinder' | Radius of emitting sphere/cylinder |
| `cylinder', `cone' | Extent vector defining the cone or cylinder |
| `cone' | Cone opening angle in radians |
| `box' | Box emitter extents |
Just as emitters emit particles into the particle system, effectors put different kinds of effects on those who are already there, be it physical or non-physical effects.
In principle an emitter is any class implementing the interface
`iParticleEffector', so you can implement your own effectors, however for
convenience there are a few built in effector types. These can be accessed via
the `crystalspace.mesh.object.particles.effector' plugin class and
`iParticleBuiltinEffectorFactory' interface.
The built in effectors are also loadable via the normal particle loader using
<effector type=".."> tags. The available types are:
`Force' effector loader recognize following keywords:
<acceleration x="" y="" z="" />Add a constant acceleration to particles. Useful for example for gravity.
<force x="" y="" z="" />Add a constant force to particles.
<randomacceleration>mag</randomacceleration>Add a random acceleration with given magnitude.
<randomacceleration x="" y="" z="" />Add a random acceleration with given magnitude in the form of a vector.
`Lincolor' effector sets the color of particles based on their remaning TTL. It takes a fixed number of "keypoints" and then interpolates between them. `Lincolor' effector loader recognize following keywords:
<color red="" green="" blue="" time="">Set a keypoint color at given time.
`Velocityfield' effector is a more complicated and resource using way of giving intricate movements to the particles. It works by taking a function defining the velocity of particles as a function of position and time. It then integrates to the new particle positions. Each function can take a number of vector and scalar parameters that affects their output To be noted is that `velocityfield' effector does not change the particle velocities, so any "external" movement will be integrated as normally. `Velocityfield' effector loader recognize following keywords:
<type>field-type</type>Set the field function. Currently supported values are `spiral' and `radialpoint'.
<fparam>value</fparam>Specify a scalar parameter.
<vparam x="" y="" z="" />Specify a vector parameter.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] |
This document was generated using texi2html 1.76.