 |
OGRE-Next
4.0.0unstable
Object-Oriented Graphics Rendering Engine
|
|
OGRE-Next
4.0.0unstable
Object-Oriented Graphics Rendering Engine
|
Particle scripts allow you to define particle systems to be instantiated in your code without having to hard-code the settings themselves in your source code, allowing a very quick turnaround on any changes you make. Particle systems which are defined in scripts are used as templates, and multiple actual systems can be created from them at runtime.
Once scripts have been parsed, your code is free to instantiate systems based on them using either the Ogre::SceneManager::createParticleSystem() method which can take both a name for the new system, and the name of the template to base it on (this template name is in the script) or the Ogre::SceneManager::createParticleSystem2() if you're using the ParticleFX2 Plugin.
A system can have top-level attributes set using the scripting commands available, such as ’quota’ to set the maximum number of particles allowed in the system. Emitters (which create particles) and affectors (which modify particles) are added as nested definitions within the script. The parameters available in the emitter and affector sections are entirely dependent on the type of emitter / affector.
For a detailed description of the core particle system attributes, see the list below:
This section describes to attributes which you can set on every particle system using scripts. All attributes have default values so all settings are optional in your script.
Sets the maximum number of particles this system is allowed to contain at one time. When this limit is exhausted, the emitters will not be allowed to emit any more particles until some destroyed (e.g. through their time_to_live running out). Note that you will almost always want to change this, since it defaults to a very low value (particle pools are only ever increased in size, never decreased).
Sets the name of the material which all particles in this system will use. All particles in a system use the same material, although each particle can tint this material through the use of it’s colour property.
Sets the width of particles in world coordinates. Note that this property is absolute when billboard_type (see below) is set to ’point’ or ’perpendicular_self’, but is scaled by the length of the direction vector when billboard_type is ’oriented_common’, ’oriented_self’ or ’perpendicular_common’.
Sets the height of particles in world coordinates. Note that this property is absolute when billboard_type (see below) is set to ’point’ or ’perpendicular_self’, but is scaled by the length of the direction vector when billboard_type is ’oriented_common’, ’oriented_self’ or ’perpendicular_common’.
All particle systems are culled by the bounding box which contains all the particles in the system. This is normally sufficient for fairly locally constrained particle systems where most particles are either visible or not visible together. However, for those that spread particles over a wider area (e.g. a rain system), you may want to actually cull each particle individually to save on time, since it is far more likely that only a subset of the particles will be visible. You do this by setting the cull_each parameter to true.
Particle systems do not render themselves, they do it through ParticleRenderer classes. Those classes are registered with a manager in order to provide particle systems with a particular ’look’. OGRE comes configured with a default billboard-based renderer, but more can be added through plugins. Particle renders are registered with a unique name, and you can use that name in this attribute to determine the renderer to use. The default is ’billboard’.
Particle renderers can have attributes, which can be passed by setting them on the root particle system.
By default, particles are not sorted. By setting this attribute to ’true’, the particles will be sorted with respect to the camera, furthest first. This can make certain rendering effects look better at a small sorting expense.
By default, particles are emitted into world space, such that if you transform the node to which the system is attached, it will not affect the particles (only the emitters). This tends to give the normal expected behaviour, which is to model how real world particles travel independently from the objects they are emitted from. However, to create some effects you may want the particles to remain attached to the local space the emitter is in and to follow them directly. This option allows you to do that.
Usually particle systems are updated based on the frame rate; however this can give variable results with more extreme frame rate ranges, particularly at lower frame rates. You can use this option to make the update frequency a fixed interval, whereby at lower frame rates, the particle update will be repeated at the fixed interval until the frame time is used up. A value of 0 means the default frame time iteration.
Sets when the particle system should stop updating after it hasn’t been visible for a while. By default, visible particle systems update all the time, even when not in view. This means that they are guaranteed to be consistent when they do enter view. However, this comes at a cost, updating particle systems can be expensive, especially if they are perpetual. This option lets you set a ’timeout’ on the particle system, so that if it isn’t visible for this amount of time, it will stop updating until it is next visible. A value of 0 disables the timeout and always updates.
These are actually attributes of the billboard particle renderer (the default), but can be passed to a particle renderer by declaring them directly within the system declaration. Particles using the default renderer are rendered using billboards, which are rectangles formed by 2 triangles which rotate to face the given direction.
There is more than 1 way to orient a billboard. The classic approach is for the billboard to directly face the camera: this is the default behaviour. However this arrangement only looks good for particles which are representing something vaguely spherical like a light flare. For more linear effects like laser fire, you actually want the particle to have an orientation of it’s own.
The options for this parameter are:
The default arrangement, this approximates spherical particles and the billboards always fully face the camera.
Particles are oriented around a common, typically fixed direction vector (see common_direction), which acts as their local Y axis. The billboard rotates only around this axis, giving the particle some sense of direction. Good for rainstorms, starfields etc where the particles will traveling in one direction - this is slightly faster than oriented_self (see below).
Particles are oriented around their own direction vector, which acts as their local Y axis. As the particle changes direction, so the billboard reorients itself to face this way. Good for laser fire, fireworks and other ’streaky’ particles that should look like they are traveling in their own direction.
Particles are perpendicular to a common, typically fixed direction vector (see common_direction), which acts as their local Z axis, and their local Y axis coplanar with common direction and the common up vector (see common_up_vector). The billboard never rotates to face the camera, you might use double-side material to ensure particles never culled by back-facing. Good for aureolas, rings etc where the particles will perpendicular to the ground - this is slightly faster than perpendicular_self (see below).
Particles are perpendicular to their own direction vector, which acts as their local Z axis, and their local Y axis coplanar with their own direction vector and the common up vector (see common_up_vector). The billboard never rotates to face the camera, you might use double-side material to ensure particles never culled by back-facing. Good for rings stack etc where the particles will perpendicular to their traveling direction.
This setting controls the fine tuning of where a billboard appears in relation to it's position. It could be that a billboard's position represents it's center (e.g. for fireballs), it could mean the center of the bottom edge (e.g. a tree which is positioned on the ground), the top-left corner (e.g. a cursor).
The options for this parameter are:
Billboard particles will rotate the vertices around their facing direction to according with particle rotation. Rotate vertices guarantee texture corners exactly match billboard corners, thus has advantage mentioned above, but should take more time to generate the vertices.
Billboard particles will rotate the texture coordinates to according with particle rotation. Rotate texture coordinates is faster than rotate vertices, but has some disadvantage mentioned above.
Billboard particles will not rotate. This saves performance if rotation is not needed.
Only required if billboard_type is set to oriented_common or perpendicular_common, this vector is the common direction vector used to orient all particles in the system.
Only required if billboard_type is set to perpendicular_self or perpendicular_common, this vector is the common up vector used to orient all particles in the system.
This sets whether or not the BillboardSet will use point rendering rather than manually generated quads.
| enabled | True to enable point rendering, false otherwise |
This sets whether or not the BillboardSet will use a slower but more accurate calculation for facing the billboard to the camera. By default it uses the camera direction, which is faster but means the billboards don’t stay in the same orientation as you rotate the camera. The ’accurate_facing on’ option makes the calculation based on a vector from each billboard to the camera, which means the orientation is constant even whilst the camera rotates.
accurate_facing is forced on for all systems.Thus, if the texture size is 512x512 and 'stacks' is 4 and 'slices' is 8, each sub-rectangle of the texture would be 128 texels tall and 64 texels wide.
Particle emitters are classified by ’type’ e.g. ’Point’ emitters emit from a single point whilst ’Box’ emitters emit randomly from an area. New emitters can be added to Ogre by creating plugins. You add an emitter to a system by nesting another section within it, headed with the keyword ’emitter’ followed by the name of the type of emitter (case sensitive). Ogre currently supports ’Point’, ’Box’, ’Cylinder’, ’Ellipsoid’, ’HollowEllipsoid’ and ’Ring’ emitters.
It is possible to ’emit emitters’ - that is, have new emitters spawned based on the position of particles,, for example to product ’firework’ style effects.
This is controlled via the following directives:
This parameter is a system-level parameter telling the system how many emitted emitters may be in use at any one time. This is just to allow for the space allocation process.
This parameter is an emitter-level parameter, giving a name to an emitter. This can then be referred to in another emitter as the new emitter type to spawn.
This is an emitter-level parameter, and if specified, it means that the particles spawned by this emitter, are themselves emitters of the named type.
This section describes the common attributes of all particle emitters. Specific emitter types may also support their own extra attributes.
Sets the maximum angle (in degrees) which emitted particles may deviate from the direction of the emitter (see direction). Setting this to 10 allows particles to deviate up to 10 degrees in any direction away from the emitter’s direction. A value of 180 means emit in any direction, whilst 0 means emit always exactly in the direction of the emitter.
Sets a static colour for all particle emitted. Also see the colour_range_start and colour_range_end attributes for setting a range of colours. The format of the colour parameter is "r g b a", where each component is a value from 0 to 1, and the alpha value is optional (assumes 1 if not specified).
As the ’colour’ attribute, except these 2 attributes must be specified together, and indicate the range of colours available to emitted particles. The actual colour will be randomly chosen between these 2 values.
Sets the direction of the emitter. This is relative to the SceneNode which the particle system is attached to, meaning that as with other movable objects changing the orientation of the node will also move the emitter.
Sets the position reference of the emitter. This supersedes direction when present. The last parameter must be 1 to enable it, 0 to disable. You may still want to set the direction to setup orientation of the emitter’s dimensions. When present, particles direction is calculated at the time of emission by doing (particlePosition - referencePosition); therefore particles will travel in a particular direction or in every direction depending on where the particles are originated, and the location of the reference position. Note angle still works to apply some randomness after the direction vector is generated. This parameter is specially useful to create explosions and implosions (when velocity is negative) best paired with HollowEllipsoid and Ring emitters. This is relative to the SceneNode which the particle system is attached to, meaning that as with other movable objects changing the orientation of the node will also move the emitter.
Sets how many particles per second should be emitted. The specific emitter does not have to emit these in a continuous manner - this is a relative parameter and the emitter may choose to emit all of the second’s worth of particles every half-second for example, the behaviour depends on the emitter. The emission rate will also be limited by the particle system’s ’quota’ setting.
Sets the position of the emitter relative to the SceneNode the particle system is attached to.
Sets a constant velocity for all particles at emission time. See also the velocity_min and velocity_max attributes which allow you to set a range of velocities instead of a fixed one.
As ’velocity’ except these attributes set a velocity range and each particle is emitted with a random velocity within this range.
Sets the number of seconds each particle will ’live’ for before being destroyed. NB it is possible for particle affectors to alter this in flight, but this is the value given to particles on emission. See also the time_to_live_min and time_to_live_max attributes which let you set a lifetime range instead of a fixed one.
As time_to_live, except this sets a range of lifetimes and each particle gets a random value in-between on emission.
Sets the number of seconds the emitter is active. The emitter can be started again, see repeat_delay. See also the duration_min and duration_max attributes which let you set a duration range instead of a fixed one.
emission_rate of particles are emitted once in the next frame.As duration, except these attributes set a variable time range between the min and max values each time the emitter is started.
Sets the number of seconds to wait before the emission is repeated when stopped by a limited duration. See also the repeat_delay_min and repeat_delay_max attributes which allow you to set a range of repeat_delays instead of a fixed one.
As repeat_delay, except this sets a range of repeat delays and each time the emitter is started it gets a random value in-between.
Ogre comes preconfigured with a few particle emitters. New ones can be added by creating plugins: see the Plugin_ParticleFX project as an example of how you would do this (this is where these emitters are implemented).
Particle emitter which emits particles from a single point.
This emitter has no additional attributes over an above the standard emitter attributes.
To create a point emitter, include a section like this within your particle system script:
Particle emitter which emits particles randomly from points inside a box.
It’s extra attributes are:
Sets the width of the box (this is the size of the box along it’s local X axis, which is dependent on the ’direction’ attribute which forms the box’s local Z).
Sets the height of the box (this is the size of the box along it’s local Y axis, which is dependent on the ’direction’ attribute which forms the box’s local Z).
Sets the depth of the box (this is the size of the box along it’s local Z axis, which is the same as the ’direction’ attribute).
To create a box emitter, include a section like this within your particle system script:
Particle emitter which emits particles randomly from points inside a cylinder.
This emitter has exactly the same parameters as the Box Emitter so there are no additional parameters to consider here - the width and height determine the shape of the cylinder along it’s axis (if they are different it is an ellipsoid cylinder), the depth determines the length of the cylinder.
This emitter emits particles from within an ellipsoid shaped area, i.e. a sphere or squashed-sphere area. The parameters are again identical to the Box Emitter, except that the dimensions describe the widest points along each of the axes.
This emitter is just like Ellipsoid Emitter except that there is a hollow area in the center of the ellipsoid from which no particles are emitted.
Therefore it has 3 extra parameters in order to define this area:
The width of the inner area which does not emit any particles.
The height of the inner area which does not emit any particles.
The depth of the inner area which does not emit any particles.
This emitter emits particles from a ring-shaped area, i.e. a little like Hollow Ellipsoid Emitter except only in 2 dimensions.
The width of the inner area which does not emit any particles.
The height of the inner area which does not emit any particles.
Particle affectors modify particles over their lifetime. They are classified by ’type’ e.g. ’LinearForce’ affectors apply a force to all particles, whilst ’ColourFader’ affectors alter the colour of particles in flight. New affectors can be added to Ogre by creating plugins. You add an affector to a system by nesting another section within it, headed with the keyword ’affector’ followed by the name of the type of affector (case sensitive).
Particle affectors actually have no universal attributes; they are all specific to the type of affector.
Ogre comes preconfigured with a few particle affectors. New ones can be added by creating plugins: see the Plugin_ParticleFX project as an example of how you would do this (this is where these affectors are implemented).
This class defines a ParticleAffector which applies a linear force to particles in a system.
It’s extra attributes are:
Sets the vector for the force to be applied to every particle. The magnitude of this vector determines how strong the force is.
Sets the way in which the force vector is applied to particle momentum.
The options are:
The resulting momentum is the average of the force vector and the particle’s current motion. Is self-stabilising but the speed at which the particle changes direction is non-linear.
The resulting momentum is the particle’s current motion plus the force vector. This is traditional force acceleration but can potentially result in unlimited velocity.
To create a linear force affector, include a section like this within your particle system script:
This plugin subclass of ParticleAffector allows you to alter the colour of particles.
It’s extra attributes are:
Sets the adjustment to be made to the red component of the particle colour per second.
Sets the adjustment to be made to the green component of the particle colour per second.
Sets the adjustment to be made to the blue component of the particle colour per second.
Sets the adjustment to be made to the alpha component of the particle colour per second.
To create a colour fader affector, include a section like this within your particle system script:
This affector is similar to the ColourFader Affector, except it introduces two states of colour changes as opposed to just one. The second colour change state is activated once a specified amount of time remains in the particles life.
Sets the adjustment to be made to the red component of the particle colour per second for the first state.
Sets the adjustment to be made to the green component of the particle colour per second for the first state.
Sets the adjustment to be made to the blue component of the particle colour per second for the first state.
Sets the adjustment to be made to the alpha component of the particle colour per second for the first state.
Sets the adjustment to be made to the red component of the particle colour per second for the second state.
Sets the adjustment to be made to the green component of the particle colour per second for the second state.
Sets the adjustment to be made to the blue component of the particle colour per second for the second state.
Sets the adjustment to be made to the alpha component of the particle colour per second for the second state.
When a particle has this much time left to live, it will switch to state 2.
To create a ColourFader2 affector, include a section like this within your particle system script:
This plugin subclass of ParticleAffector allows you to alter the scale of particles.
It’s extra attributes are:
How we should scale. When false, every tick we do:
When true, every tick we do:
Multiply mode is useful for particles that always grow at a constant rate. Non-multiply mode is useful if you want the growth rate to slow down over time (e.g. 10 + 100 makes the particle grow by 10x, but on the next tick 100 + 100 means the particle grows by 2x).
To create a scale affector, include a section like this within your particle system script:
This plugin subclass of ParticleAffector allows you to alter the rotation of particles.
It’s extra attributes are:
The start of a range of rotation speeds to be assigned to emitted particles.
The end of a range of rotation speeds to be assigned to emitted particles.
The start of a range of rotation angles to be assigned to emitted particles.
The end of a range of rotation angles to be assigned to emitted particles.
To create a rotate affector, include a section like this within your particle system script:
Similar to the ColourFader and ColourFader2 Affectors, this affector modifies the colour of particles in flight, except it has a variable number of defined stages. It swaps the particle colour for several stages in the life of a particle and interpolates between them.
It’s extra attributes are:
The point in time of stage 0. Must be in range [0; 1].
The colour at stage 0.
The point in time of stage 1. Must be in range [0; 1].
The colour at stage 1
The point in time of stage 2. Must be in range [0; 1].
The colour at stage 2.
To create a colour interpolation affector, include a section like this within your particle system script:
This is another affector that modifies the colour of particles in flight, but instead of programmatically defining colours, the colours are taken from a specified image file. The range of colour values begins from the left side of the image and move to the right over the lifetime of the particle, therefore only the horizontal dimension of the image is used.
Its extra attributes are:
The start of a range of rotation speed to be assigned to emitted particles.
To create a ColourImage affector, include a section like this within your particle system script:
This class defines a ParticleAffector which deflects particles.
The attributes are:
A point on the deflector plane. Together with the normal vector it defines the plane.
The normal vector of the deflector plane. Together with the point it defines the plane.
The amount of bouncing when a particle is deflected. 0 means no deflection and 1 stands for 100 percent reflection.
This class defines a ParticleAffector which applies randomness to the movement of the particles.
Its extra attributes are:
1.9.1