Particle emitters FCOLLADA extension

Extension information
Purpose: unstated Company(s): [[Feeling Software]] Product(s): [[FCollada]] Last updated: unstated Contact for technical issues:
This article is part of the COLLADA extensions directory
Adding to the extensions directory

Particle emitters extension

This extension has two parts: the emitter description and the instance-specific information. The behavior is only loosely defined.

Particle emitter entity

This is a non-standard entity type extra emitter type, contained within a <emitter> entity of a <library_emitters> at the <COLLADA> level is used to emit particles.

FCollada currently support only one type of particle emitter: <type_spray>, which covers the large majority of cases. The spray particle emitter may define an area in which the particles are created. The particle emitter has a birth rate and defines how to generate the particles. This information applies to both billboard-style particles and geometry-style particles. See the instance description for more information on billboard-style particles and geometry-style particles, since the emitter instance determines the final look of the emitted particle.

Emitted particles are created with a linear velocity, which may be zero and may be modified by forces. See Particle forces FCOLLADA extension for more information on forces. Emitted particles have a material, an independent color, a lifetime and a scale factor. The color and scale factors may change according to the lifetime of the particle.

<type_spray>

Element	Attributes	Description
<life>	variance, sid	Contains one floating point value: the average lifetime of emitted particles. The variance attribute adds randomness. A variance of zero implies a constant lifetime for all emitted particles. The sid attribute can be used to animate this parameter.
<size>	variance, sid	Contains one floating-point value: the average size, in world units, of emitted particles. For flake geometries, this implies a scale factor. The variance attribute adds randomness. The sid attribute can be used to animate this parameter.
<speed>	variance, sid	Contains one floating-point value: the average size, in world units, of emitted particles. For flake geometries, this implies a scale factor. The variance attribute adds randomness. The sid attribute can be used to animate this parameter.
<color>	sid	Contains four floating-point values: one factor for each component of a typical color value. The sid attribute can be used to animate this parameter.
<color_var>	sid	Contains four floating-point values: one variance for each component of the color value. The sid attribute can be used to animate this parameter.
<spawn_multiplier>	variance, sid	Contains one floating-point value. The variance attribute adds randomness. The sid attribute can be used to animate this parameter.
<spawn_count>		Contains one integer value.
<spawn_percent>		Contains one floating-point value.
<direction_chaos>	sid	Contains one floating-point value. Adds randomness to the initial velocity of new particles. The standard direction of new particles is given by the orientation of the scene node containing the emitter instance. The sid attribute can be used to animate this parameter.
<speed_chaos>	sid	Contains one floating-point value. Adds randomness to the initial speed of new particles. The sid attribute can be used to animate this parameter.
<birth_rate>		Contains one floating-point value: the number of particles to emit per seconds. The sid attribute can be used to animate this parameter.
<modifier_list>		Complex element. Contains a list of complex particle modifiers. More information on this below.
<emit_pos>		Complex element. Contains the analytical geometry in which particles are created. If this element is missing or empty, all particles are created one point: the world position of the emitter instance. More information on this below.
<emit_orient>		Complex element. Describes how to orient the initial velocity of new particles. More information of this below.

<modifier_list>

Element	Description
<rotation_basic>	Contains the parameters for a simple rotation modifier. The particles will rotate around a given axis at an animatable rate.
<rotation>	Contains the parameters for a complex rotation modifier. Either or both the velocity and the orientation of particles can be rotated around a given or random axis.
<velocity_align>	Contains the parameters for an aligning modifier. The particles will rotate to follow the path of their velocity. This modifier is mutually exclusive with the <rotation> and the <rotation_basic> modifiers.
<random_offset>	Contains the parameters for a random translation modifier. The particles will translate by a random amount within a given interval, at random times.
<random_accel>	Contains the parameters for a random acceleration modifier. The particles will accelerate by a random amount within a given interval, at random times.
<generation_size>	Contains the parameters for a lifetime-based size modifier. The size of each particles will be scaled according to its lifetime and a given factor.
<colour_tint>	Contains the parameters for a particle color modifier. The material of each emitted particles will be blended, according to a given blend mode, with a given animatable color.

<basic_rotation>

Element	Attributes	Description
<speed>	sid	Contains one floating point value: the speed at which the particles will rotate around the given axis. The sid attribute can be used to animate this parameter.
<axis>		Contains three floating point value: the 3D vector around which the particles rotate, in local space.

<rotation>

Element	Attributes	Description
<flags>		Contains one masked enumerated type value: USE_DEFINED_AXIS = 2 Whether to apply rotations around the given axis, instead of a random axis. FLIP_STARTING_COORDS = 4 Whether to randomly multiply the rotation axis by -1. Meant to be used with USE_DEFINED_AXIS. APPLY_WORLD_TRANSFORM = 8 Apply the rotation in world-space instead of rotating in local space. APPLY_TO_ORIENTATION = 16 Whether to apply the rotation to the screen-facing of the particles. APPLY_TO_VELOCITY = 32 Whether to apply the rotation to the velocity of the particles At least one of APPLY_TO_ORIENTATION and APPLY_TO_VELOCITY should be set.
<initial>	sid	Contains one floating point value: the rotation angle to give to newly emitted particles. The sid attribute can be used to animate this parameter.
<initial_var>	sid	Contains one floating point value: the variance in rotation angles for newly emitted particles. This parameters defaults to 2*PI, which implies doubly-fully random angles. The sid attribute can be used to animate this parameter.
<speed>	sid	Contains one floating point value: the speed at which the particles will rotate around the given axis. The speed is given in rads per seconds. The sid attribute can be used to animate this parameter.
<speed_var>	sid	Contains one floating point value: the variance in rotation speeds. This parameters defaults to PI. The sid attribute can be used to animate this parameter.
<axis>	sid	Contains three floating point values: the 3D vector around which the particles rotate, in local space. The sid attribute can be used to animate this parameter.
<axis_var>	sid	Contains one floating point values: the variance in 3D rotation axis. This value is in radians and represent the possible derivation of the rotation axis on the unit sphere. The sid attribute can be used to animate this parameter. [editor] Is this a square or a circular derivation?

<velocity_align>

Element	Attributes	Description
<up_axis>	sid	Contains three floating point values: the up vector to completely orient the particles. This 3D vector will be used to generate a roll value, while the direction of the velocity will set the orientation of the particles. The sid attribute can be used to animate this parameter.

<random_offset>

Element	Attributes	Description
<min>	sid	Contains one floating point value: the minimum length of the random displacement of each particles. The sid attribute can be used to animate this parameter.
<max>	sid	Contains one floating point value: the maximum length of the random displacement of each particles. The sid attribute can be used to animate this parameter.
<freq>	sid	Contains one floating point value: the frequency at which to randomly translate each particles. The sid attribute can be used to animate this parameter.

<random_accel>

Element	Attributes	Description
<accel_scale>	sid	Contains one floating point value: the length of the maximum acceleration to randomly set to each particle. The minimum acceleration to randomly set on each particle in always no acceleration. The sid attribute can be used to animate this parameter.
<accel_freq>	sid	Contains one floating point value: the frequency at which to randomly set each particle's acceleration. The sid attribute can be used to animate this parameter.

<generation_size>

Element	Attributes	Description
<size>	sid	Contains one floating point value: the size factor for the particles. The sid attribute can be used to animate this parameter. [editor] Not sure what formula is implied here.

<colour_tint>

Element	Attributes	Description
<color>	sid	Contains four floating point values: four factors to apply to the final color component channels, in the typical COLLADA order: Red, Green, Blue and Alpha. The sid attribute can be used to animate this parameter.
<blend_mode>		Contains an enumerated type value: it indicates how to apply the color factors: multiply, add and substract are self-explanatory. A value of set will replace the material color value by the color factors.

<emit_orient>

Element	Attributes	Description
<area>		Complex element. Emits particles out of a 3D quad.
<box>		Complex element. Emits particles inside an axis-aligned box.
<sphere>		Complex element. Emits particles inside a shell.
<object>	url	Complex element. Emits particles at the vertices of a referenced mesh. The url attribute is used to identify the geometry definition to emit from. As with morph controllers, the vertices of the geometry are necessary and sufficient.

<emit_pos><area>

Element	Attributes	Description
<width>	sid	Contains one floating point value: the width of the emitting 3D quad. This parameter is animatable using the sid attribute.
<length>	sid	Contains one floating point value: the length of the emitting 3D quad. This parameter is animatable using the sid attribute.
		The emitting quad is axis-aligned and is defined by the following min/max coordinates: (-width/2, 0, -length/2) and (width/2, 0, length/2). Its default orientation is along the positive Y axis. The probability of emission is uniformly distributed inside the 3D quad.

<emit_pos><box>

Element	Attributes	Description
<width>	sid	Contains one floating point value: the width of the emitting axis-aligned box. This parameter is animatable using the sid attribute.
<length>	sid	Contains one floating point value: the length of the emitting axis-aligned box. This parameter is animatable using the sid attribute.
<height>	sid	Contains one floating point value: the height of the emitting axis-aligned box. This parameter is animatable using the sid attribute.
		The emitting axis-aligned box is defined by the following min/max coordinates: (-width/2, -height/2, -length/2) and (width/2, height/2, -length/2). The probability of emission is uniformly distributed inside the 3D quad.

<emit_pos><sphere>

Element	Attributes	Description
<min_radius>	sid	Contains one floating point value: the radius of the inner sphere surface of the shell. This parameter is animatable using the sid attribute.
<max_radius>	sid	Contains one floating point value: the radius of the outer sphere surface of the shell. This parameter is animatable using the sid attribute.
		It may be easier to think that particle emission occurs within a distance interval from the emitter instance, than to imagine the shell. The emission of particles is equally likely for each value within the distance interval. This means that the probability of emission is more dense towards the inner sphere surface of the shell.

<emit_pos><object>

Element	Attributes	Description
<regular>		Reserved for future expansion. Currently always contains the string "1".

<emit_orient>

Element	Attributes	Description
<sphere>	Complex element. Orients particles using a section of the unit sphere.
<match_emitter>	Complex element. Orients particles along the instant velocity of the emitter instance.

Example

A simple, but complete emitter.

 <extra type="libraries">
   <technique profile="FCOLLADA">
     <library_emitters>
       <emitter id="Emitter">
         <type_spray>
           <life variance="0">1</life>
           <size variance="0">1</size>
           <speed variance="0">1</speed>
           <color>1 1 1 1</color>
           <color_var>0 0 0 0</color_var>
           <spawn_multiplier variance="0">1</spawn_multiplier>
           <spawn_on_death>1</spawn_on_death>
           <spawn_count>1</spawn_count>
           <spawn_percent>0.5</spawn_percent>
           <direction_chaos>0</direction_chaos>
           <speed_chaos>0</speed_chaos>
           <birth_rate>10</birth_rate>
           <modifier_list/>
         </type_spray>
       </emitter>
     </library_emitters>
   </technique>
 </extra>

An emitter with a modifier and a complex emission area.

 <emitter id="Emitter1">
   <type_spray>
     <life1</life>
     <color>1 1 1 1</color>
     <modifier_list>
       <colour_tint>
         <blend_mode>set</blend_mode>
         <color>1 1 1 1</color>
       </colour_tint>
     </modifier_list>
     <emit_pos>
       <area>
         <width>10</width>
         <length>10</length>
       </area>
     </emit_pos>
   </type_spray>
 </emitter>

Particle emitter instance

Particle emitters are a non-standard entity type. Therefore, they are not contained directly under the <node> element. For more information on how to include the <instance_emitter> element in the scene graph, see Extra entity instances FCOLLADA extension.

It is the particle emitter instance that will determine the final look and behavior of the emitted particles. There are two types of emitted particles: billboards and geometries. In the case of billboards, they should all start as camera-facing, but a rotation may be appllied to them by the particle emitter. In the case of geometry particles - also called flake geometries - you can imagine that a list of <instance_geometry> is added to the node where the emitter instance belongs.

<emitter_instance>

Element	Attributes	Description
<flake_geometry>		Complex element. Implies that the emitter instance emits geometry-style particles. This element contains may contain only one child: <instance_geometry>. See the COLLADA specification for more information on <instance_geometry>.
<sprite>		Complex element. Implies that the emitter instance emits billboard-style particles. This element may contain only one child: <instance_material>. See the COLLADA specification for more information on <instance_material>.

Example

   <node id="some_node" type="NODE">
     <extra type="instances">
       <technique profile="FCOLLADA">
         <instance_emitter url="#Emitter">
           <flake_geometry>
             <instance_geometry url="#small_mesh">
               <bind_material>
                 <technique_common>
                   <instance_material symbol="polygons1" target="#material1"/>
                 </technique_common>
               </bind_material>
             </instance_geometry>
           </flake_geometry>
         </instance_emitter>
       </technique>
     </extra>
   </node>

   <instance_emitter url="#Emitter">
      <sprite>
        <instance_material target="#small_mesh">
      </sprite>
   </instance_emitter>