Struct fyrox::scene::particle_system::ParticleSystem

pub struct ParticleSystem {
    pub emitters: InheritableVariable<Vec<Emitter>>,
    /* private fields */
}

Particle system used to create visual effects that consists of many small parts, this can be smoke, fire, dust, sparks, etc. Particle system optimized to operate on many small parts, so it is much efficient to use particle system instead of separate scene nodes. Downside of particle system is that there almost no way to control separate particles, all particles controlled by parameters of particle emitters.

Emitters

Particle system can contain multiple particle emitters, each emitter has its own set of properties and it defines law of change of particle parameters over time.

Performance

In general particle system can be considered as heavy visual effect, but total impact on performance defined by amount of particles and amount of pixels they take to render. A rule of thumb will be to decrease amount of particles until effect will look good enough, alternatively amount of particles can be defined by some coefficient based on graphics quality settings.

Example

Simple smoke effect can be create like so:

fn create_smoke(graph: &mut Graph, resource_manager: &mut ResourceManager, pos: Vector3<f32>) {
    let mut material = Material::standard_particle_system();
    material
        .set_property(
            &ImmutableString::new("diffuseTexture"),
            PropertyValue::Sampler {
                value: Some(
                    resource_manager
                        .request::<Texture>(Path::new("data/particles/smoke_04.tga")),
                ),
                fallback: Default::default(),
            },
        )
        .unwrap();

    ParticleSystemBuilder::new(
        BaseBuilder::new()
            .with_lifetime(5.0)
            .with_local_transform(TransformBuilder::new().with_local_position(pos).build()),
    )
    .with_acceleration(Vector3::new(0.0, 0.0, 0.0))
    .with_color_over_lifetime_gradient({
        let mut gradient = ColorGradient::new();
        gradient.add_point(GradientPoint::new(0.00, Color::from_rgba(150, 150, 150, 0)));
        gradient.add_point(GradientPoint::new(
            0.05,
            Color::from_rgba(150, 150, 150, 220),
        ));
        gradient.add_point(GradientPoint::new(
            0.85,
            Color::from_rgba(255, 255, 255, 180),
        ));
        gradient.add_point(GradientPoint::new(1.00, Color::from_rgba(255, 255, 255, 0)));
        gradient
    })
    .with_emitters(vec![SphereEmitterBuilder::new(
        BaseEmitterBuilder::new()
            .with_max_particles(100)
            .with_spawn_rate(50)
            .with_x_velocity_range(-0.01..0.01)
            .with_y_velocity_range(0.02..0.03)
            .with_z_velocity_range(-0.01..0.01),
    )
    .with_radius(0.01)
    .build()])
    .with_material(MaterialResource::new_ok(Default::default(), material))
    .build(graph);
}

Fields

emitters: InheritableVariable<Vec<Emitter>>

List of emitters of the particle system.

Implementations

impl ParticleSystem

pub const BASE: &'static str = "base"

pub const EMITTERS: &'static str = "emitters"

pub const MATERIAL: &'static str = "material"

pub const ACCELERATION: &'static str = "acceleration"

pub const COLOR_OVER_LIFETIME: &'static str = "color_over_lifetime"

pub const IS_PLAYING: &'static str = "is_playing"

pub const RNG: &'static str = "rng"

impl ParticleSystem

pub fn acceleration(&self) -> Vector3<f32>

Returns current acceleration for particles in particle system.

pub fn set_acceleration(&mut self, accel: Vector3<f32>) -> Vector3<f32>

Set new acceleration that will be applied to all particles, can be used to change “gravity” vector of particles.

pub fn set_color_over_lifetime_gradient( &mut self, gradient: ColorGradient ) -> ColorGradient

Sets new “color curve” that will evaluate color over lifetime.

pub fn play(&mut self, is_playing: bool) -> bool

Plays or pauses the particle system. Paused particle system remains in “frozen” state until played again again. You can manually reset state of the system by calling Self::clear_particles.

pub fn is_playing(&self) -> bool

Returns current particle system status.

pub fn set_particles(&mut self, particles: Vec<Particle>)

Replaces the particles in the particle system with pre-generated set. It could be useful to create procedural particle effects; when particles cannot be pre-made.

pub fn particles(&self) -> &[Particle]

Returns a reference to a slice to the current set of particles, generated by the particle system.

pub fn clear_particles(&mut self)

Removes all generated particles.

pub fn set_material(&mut self, material: MaterialResource) -> MaterialResource

Sets the new material for the particle system.

pub fn texture(&self) -> MaterialResource

Returns current material used by particle system.

pub fn texture_ref(&self) -> &MaterialResource

Returns current material used by particle system by ref.

pub fn rewind(&mut self, dt: f32, time: f32)

Simulates particle system for the given time with given time step (dt). dt is usually 1.0 / 60.0.

Methods from Deref<Target = Base>

pub const NAME: &'static str = "name"

pub const LOCAL_TRANSFORM: &'static str = "local_transform"

pub const VISIBILITY: &'static str = "visibility"

pub const LIFETIME: &'static str = "lifetime"

pub const DEPTH_OFFSET: &'static str = "depth_offset"

pub const LOD_GROUP: &'static str = "lod_group"

pub const MOBILITY: &'static str = "mobility"

pub const TAG: &'static str = "tag"

pub const CAST_SHADOWS: &'static str = "cast_shadows"

pub const PROPERTIES: &'static str = "properties"

pub const FRUSTUM_CULLING: &'static str = "frustum_culling"

pub const IS_RESOURCE_INSTANCE_ROOT: &'static str = "is_resource_instance_root"

pub const RESOURCE: &'static str = "resource"

pub const SCRIPT: &'static str = "script"

pub const ENABLED: &'static str = "enabled"

pub fn set_name<N: AsRef<str>>(&mut self, name: N)

Sets name of node. Can be useful to mark a node to be able to find it later on.

pub fn name(&self) -> &str

Returns name of node.

pub fn name_owned(&self) -> String

Returns owned name of node.

pub fn local_transform(&self) -> &Transform

Returns shared reference to local transform of a node, can be used to fetch some local spatial properties, such as position, rotation, scale, etc.

pub fn local_transform_mut(&mut self) -> &mut Transform

Returns mutable reference to local transform of a node, can be used to set some local spatial properties, such as position, rotation, scale, etc.

pub fn set_local_transform(&mut self, transform: Transform)

Sets new local transform of a node.

pub fn find_properties_ref<'a>( &'a self, name: &'a str ) -> impl Iterator<Item = &'a Property>

Tries to find properties by the name. The method returns an iterator because it possible to have multiple properties with the same name.

pub fn find_first_property_ref(&self, name: &str) -> Option<&Property>

Tries to find a first property with the given name.

pub fn set_properties(&mut self, properties: Vec<Property>) -> Vec<Property>

Sets a new set of properties of the node.

pub fn set_lifetime(&mut self, time_seconds: Option<f32>) -> &mut Self

Sets lifetime of node in seconds, lifetime is useful for temporary objects. Example - you firing a gun, it produces two particle systems for each shot: one for gunpowder fumes and one when bullet hits some surface. These particle systems won’t last very long - usually they will disappear in 1-2 seconds but nodes will still be in scene consuming precious CPU clocks. This is where lifetimes become handy - you just set appropriate lifetime for a particle system node and it will be removed from scene when time will end. This is efficient algorithm because scene holds every object in pool and allocation or deallocation of node takes very little amount of time.

pub fn lifetime(&self) -> Option<f32>

Returns current lifetime of a node. Will be None if node has undefined lifetime. For more info about lifetimes see set_lifetime.

pub fn parent(&self) -> Handle<Node>

Returns handle of parent node.

pub fn children(&self) -> &[Handle<Node>]

Returns slice of handles to children nodes. This can be used, for example, to traverse tree starting from some node.

pub fn global_transform(&self) -> Matrix4<f32>

Returns global transform matrix, such matrix contains combined transformation of transforms of parent nodes. This is the final matrix that describes real location of object in the world.

pub fn inv_bind_pose_transform(&self) -> Matrix4<f32>

Returns inverse of bind pose matrix. Bind pose matrix - is special matrix for bone nodes, it stores initial transform of bone node at the moment of “binding” vertices to bones.

pub fn is_resource_instance_root(&self) -> bool

Returns true if this node is model resource instance root node.

pub fn resource(&self) -> Option<ModelResource>

Returns resource from which this node was instantiated from.

pub fn set_visibility(&mut self, visibility: bool) -> bool

Sets local visibility of a node.

pub fn visibility(&self) -> bool

Returns local visibility of a node.

pub fn local_bounding_box(&self) -> AxisAlignedBoundingBox

Returns current local-space bounding box. Keep in mind that this value is just a placeholder, because there is not information to calculate actual bounding box.

pub fn world_bounding_box(&self) -> AxisAlignedBoundingBox

Returns current world-space bounding box.

pub fn set_mobility(&mut self, mobility: Mobility) -> Mobility

Set new mobility for the node.

TODO. Mobility still has no effect, it was designed to be used in combined rendering (dynamic + static lights (lightmaps))

pub fn mobility(&self) -> Mobility

Return current mobility of the node.

pub fn global_visibility(&self) -> bool

Returns combined visibility of an node. This is the final visibility of a node. Global visibility calculated using visibility of all parent nodes until root one, so if some parent node upper on tree is invisible then all its children will be invisible. It defines if object will be rendered. It is not the same as real visibility from point of view of a camera. Use frustum-box intersection test instead.

pub fn original_handle_in_resource(&self) -> Handle<Node>

Handle to node in scene of model resource from which this node was instantiated from.

Notes

This handle is extensively used to fetch information about the state of node in the resource to sync properties of instance with its original in the resource.

pub fn global_position(&self) -> Vector3<f32>

Returns position of the node in absolute coordinates.

pub fn look_vector(&self) -> Vector3<f32>

Returns “look” vector of global transform basis, in most cases return vector will be non-normalized.

pub fn side_vector(&self) -> Vector3<f32>

Returns “side” vector of global transform basis, in most cases return vector will be non-normalized.

pub fn up_vector(&self) -> Vector3<f32>

Returns “up” vector of global transform basis, in most cases return vector will be non-normalized.

pub fn set_depth_offset_factor(&mut self, factor: f32) -> f32

Sets depth range offset factor. It allows you to move depth range by given value. This can be used to draw weapons on top of other stuff in scene.

Details

This value is used to modify projection matrix before render node. Element m[4][3] of projection matrix usually set to -1 to which makes w coordinate of in homogeneous space to be -z_fragment for further perspective divide. We can abuse this to shift z of fragment by some value.

pub fn depth_offset_factor(&self) -> f32

Returns depth offset factor.

pub fn set_lod_group(&mut self, lod_group: Option<LodGroup>) -> Option<LodGroup>

Sets new lod group.

pub fn take_lod_group(&mut self) -> Option<LodGroup>

Extracts lod group, leaving None in the node.

pub fn lod_group(&self) -> Option<&LodGroup>

Returns shared reference to current lod group.

pub fn lod_group_mut(&mut self) -> Option<&mut LodGroup>

Returns mutable reference to current lod group.

pub fn tag(&self) -> &str

Returns node tag.

pub fn tag_owned(&self) -> String

Returns a copy of node tag.

pub fn set_tag(&mut self, tag: String) -> String

Sets new tag.

pub fn frustum_culling(&self) -> bool

Return the frustum_culling flag

pub fn set_frustum_culling(&mut self, frustum_culling: bool) -> bool

Sets whether to use frustum culling or not

pub fn cast_shadows(&self) -> bool

Returns true if the node should cast shadows, false - otherwise.

pub fn set_cast_shadows(&mut self, cast_shadows: bool) -> bool

Sets whether the mesh should cast shadows or not.

pub fn instance_id(&self) -> SceneNodeId

Returns current instance id.

pub fn set_script(&mut self, script: Option<Script>)

Sets new script for the scene node.

pub fn has_script<T: ScriptTrait>(&self) -> bool

Checks if the node has a script of a particular type. Returns false if there is no script at all, or if the script is not of a given type.

pub fn try_get_script<T: ScriptTrait>(&self) -> Option<&T>

Tries to cast current script instance (if any) to given type and returns a shared reference to it on successful cast.

pub fn try_get_script_component<C>(&self) -> Option<&C>

where C: Any,

Tries to fetch a reference to a component of the given type from the script of the node.

pub fn try_get_script_component_mut<C>(&mut self) -> Option<&mut C>

where C: Any,

Tries to fetch a reference to a component of the given type from the script of the node.

pub fn try_get_script_mut<T: ScriptTrait>(&mut self) -> Option<&mut T>

Tries to cast current script instance (if any) to given type and returns a mutable reference to it on successful cast.

pub fn script(&self) -> Option<&Script>

Returns shared reference to current script instance.

pub fn script_mut(&mut self) -> Option<&mut Script>

Returns mutable reference to current script instance.

Important notes

Do not replace script instance using mutable reference given to you by this method. This will prevent correct script de-initialization! Use Self::set_script if you need to replace the script.

pub fn script_cloned(&self) -> Option<Script>

Returns a copy of the current script.

pub fn script_inner(&mut self) -> &mut Option<Script>

Internal. Do not use.

pub fn set_enabled(&mut self, enabled: bool)

Enables or disables scene node. Disabled scene nodes won’t be updated (including scripts) or rendered.

Important notes

Enabled/disabled state will affect children nodes. It means that if you have a node with children nodes, and you disable the node, all children nodes will be disabled too even if their Self::is_enabled method returns true.

pub fn is_enabled(&self) -> bool

Returns true if the node is enabled, false - otherwise. The return value does not include the state of parent nodes. It should be considered as “local” enabled flag. To get actual enabled state, that includes the state of parent nodes, use Self::is_globally_enabled method.

pub fn is_globally_enabled(&self) -> bool

Returns true if the node and every parent up in hierarchy is enabled, false - otherwise. This method returns “true” enabled flag. Its value could be different from the value returned by Self::is_enabled.

pub fn root_resource(&self) -> Option<ModelResource>

Returns a root resource of the scene node. This method crawls up on dependency tree until it finds that the ancestor node does not have any dependencies and returns this resource as the root resource. For example, in case of simple scene node instance, this method will return the resource from which the node was instantiated from. In case of 2 or more levels of dependency, it will always return the “top” dependency in the dependency graph.

Trait Implementations

impl Clone for ParticleSystem

fn clone(&self) -> ParticleSystem

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ParticleSystem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ParticleSystem

fn default() -> Self

Returns the “default value” for a type.

impl DerefMut for ParticleSystem

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl NodeTrait for ParticleSystem

fn query_component_ref(&self, type_id: TypeId) -> Option<&dyn Any>

Allows a node to provide access to inner components.

fn query_component_mut(&mut self, type_id: TypeId) -> Option<&mut dyn Any>

Allows a node to provide access to inner components.

fn local_bounding_box(&self) -> AxisAlignedBoundingBox

Returns axis-aligned bounding box in local space of the node.

fn world_bounding_box(&self) -> AxisAlignedBoundingBox

Returns axis-aligned bounding box in world space of the node.

fn id(&self) -> Uuid

Returns actual type id. It will be used for serialization, the type will be saved together with node’s data allowing you to create correct node instance on deserialization.

fn update(&mut self, context: &mut UpdateContext<'_>)

Updates internal state of the node.

fn collect_render_data(&self, ctx: &mut RenderContext<'_>)

Allows the node to emit a set of render data. This is a high-level rendering method which can only do culling and provide render data. Render data is just a surface (vertex + index buffers) and a material.

fn on_removed_from_graph(&mut self, graph: &mut Graph)

Gives an opportunity to perform clean up after the node was extracted from the scene graph (or deleted).

fn sync_native( &self, self_handle: Handle<Node>, context: &mut SyncContext<'_, '_> )

Synchronizes internal state of the node with components of scene graph. It has limited usage and mostly allows you to sync the state of backing entity with the state of the node. For example the engine use it to sync native rigid body properties after some property was changed in the crate::scene::rigidbody::RigidBody node.

fn sync_transform( &self, new_global_transform: &Matrix4<f32>, _context: &mut SyncContext<'_, '_> )

Called when node’s global transform changes.

fn is_alive(&self) -> bool

The methods is used to manage lifetime of scene nodes, depending on their internal logic.

fn debug_draw(&self, ctx: &mut SceneDrawingContext)

Allows the node to draw simple shapes to visualize internal data structures for debugging purposes.

fn validate(&self, scene: &Scene) -> Result<(), String>

Validates internal state of a scene node. It can check handles validity, if a handle “points” to a node of particular type, if node’s parameters are in range, etc. It’s main usage is to provide centralized diagnostics for scene graph.

impl Reflect for ParticleSystem

where Self: 'static, Base: Reflect, InheritableVariable<Vec<Emitter>>: Reflect, InheritableVariable<MaterialResource>: Reflect, InheritableVariable<Vector3<f32>>: Reflect, InheritableVariable<ColorGradient>: Reflect, InheritableVariable<bool>: Reflect, ParticleSystemRng: Reflect,

fn type_name(&self) -> &'static str

fn doc(&self) -> &'static str

fn fields_info(&self, func: &mut dyn FnMut(&[FieldInfo<'_, '_>]))

fn into_any(self: Box<Self>) -> Box<dyn Any>

fn set( &mut self, value: Box<dyn Reflect> ) -> Result<Box<dyn Reflect>, Box<dyn Reflect>>

fn set_field( &mut self, name: &str, value: Box<dyn Reflect>, func: &mut dyn FnMut(Result<Box<dyn Reflect>, Box<dyn Reflect>>) )

Calls user method specified with #[reflect(setter = ..)] or falls back to Reflect::field_mut

fn as_any(&self, func: &mut dyn FnMut(&dyn Any))

fn as_any_mut(&mut self, func: &mut dyn FnMut(&mut dyn Any))

fn as_reflect(&self, func: &mut dyn FnMut(&dyn Reflect))

fn as_reflect_mut(&mut self, func: &mut dyn FnMut(&mut dyn Reflect))

fn fields(&self, func: &mut dyn FnMut(&[&dyn Reflect]))

fn fields_mut(&mut self, func: &mut dyn FnMut(&mut [&mut dyn Reflect]))

fn field(&self, name: &str, func: &mut dyn FnMut(Option<&dyn Reflect>))

fn field_mut( &mut self, name: &str, func: &mut dyn FnMut(Option<&mut dyn Reflect>) )

fn as_array(&self, func: &mut dyn FnMut(Option<&(dyn ReflectArray + 'static)>))

fn as_array_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectArray + 'static)>) )

fn as_list(&self, func: &mut dyn FnMut(Option<&(dyn ReflectList + 'static)>))

fn as_list_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectList + 'static)>) )

fn as_inheritable_variable( &self, func: &mut dyn FnMut(Option<&(dyn ReflectInheritableVariable + 'static)>) )

fn as_inheritable_variable_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectInheritableVariable + 'static)>) )

fn as_hash_map( &self, func: &mut dyn FnMut(Option<&(dyn ReflectHashMap + 'static)>) )

fn as_hash_map_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectHashMap + 'static)>) )

impl TypeUuidProvider for ParticleSystem

fn type_uuid() -> Uuid

Return type UUID.

impl Visit for ParticleSystem

fn visit(&mut self, name: &str, visitor: &mut Visitor) -> VisitResult

impl Deref for ParticleSystem

type Target = Base

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.