Enum Node 

pub enum Node {
    Base(Base),
    Light(Light),
    Camera(Camera),
    Mesh(Mesh),
    Sprite(Sprite),
    ParticleSystem(ParticleSystem),
    Terrain(Terrain),
    Decal(Decal),
    RigidBody(RigidBody),
    Collider(Collider),
    Joint(Joint),
    RigidBody2D(RigidBody),
    Collider2D(Collider),
    Joint2D(Joint),
    Rectangle(Rectangle),
}

Node is the basic building block for 3D scenes. It has multiple variants, but all of them share some common functionality:

• Local and global transform
• Info about connections with other nodes in scene
• Visibility state - local and global
• Name and tags
• Level of details
• Physics binding mode

The exact functionality depends on variant of the node, check the respective docs for a variant you interested in.

Hierarchy

Nodes can be connected with other nodes, so a child node will be moved/rotate/scaled together with parent node. This has some analogy in real world - imagine a pen with a cap. The pen will be the parent node in the hierarchy and the cap will be child node. When you moving the pen, the cap moves with it only if it attached to the pen. The same principle works with scene nodes.

Transform

The node has two kinds of transform - local and global. Local transform defines where the node is located (translation) relative to origin, how much it is scaled (in percent) and rotated (around any arbitrary axis). Global transform is almost the same, but it also includes the whole chain of transforms of parent nodes. In the previous example with the pen, the cap has its own local transform which tells how much it should be moved from origin to be exactly on top of the pen. But global transform of the cap includes transform of the pen. So if you move the pen, the local transform of the cap will remain the same, but global transform will include the transform of the pen.

Name and tag

The node can have arbitrary name and tag. Both could be used to search the node in the graph. Unlike the name, tag could be used to store some gameplay information about the node. For example you can place a Mesh node that represents health pack model and it will have a name “HealthPack”, in the tag you could put additional info like “MediumPack”, “SmallPack”, etc. So 3D model will not have “garbage” in its name, it will be stored inside tag.

Visibility

The now has two kinds of visibility - local and global. As with transform, everything here is pretty similar. Local visibility defines if the node is visible as if it would be rendered alone, global visibility includes the combined visibility of entire chain of parent nodes.

Please keep in mind that “visibility” here means some sort of a “switch” that tells the renderer whether to draw the node or not. To fetch actual visibility of the node from a camera’s perspective, use visibility cache of the camera.

Level of details

The node could control which children nodes should be drawn based on the distance to a camera, this is so called level of detail functionality. There is a separate article about LODs, it can be found here.

Variants

Base(Base)

A node that offers basic functionality, every other node shares this functionality.

For more info see Base node docs.

Light(Light)

A node that represents various light sources.

For more info see Light node docs.

Camera(Camera)

A node that could be described as “our eyes in the world”, a scene should have at least one camera for you to be able to see anything.

For more info see Camera node docs.

Mesh(Mesh)

A node that is used for any kind of 3D models.

For more info see Mesh node docs.

Sprite(Sprite)

Special variation of Mesh variant which ensures that a rectangular face (billboard) is always rotated in way so it always faces the camera.

For more info see Sprite node docs.

ParticleSystem(ParticleSystem)

Collections of particles that is used to simulate clouds of particles, usually it is used to simulate dust, smoke, sparks etc in scenes.

For more info see ParticleSystem node docs.

Terrain(Terrain)

A heightmap with multiple layers.

For more info see Terrain node docs.

Decal(Decal)

A node that paints on other nodes using a texture. It is used to simulate cracks in concrete walls, damaged parts of the road, blood splatters, bullet holes, etc.

For more info see Decal node docs.

RigidBody(RigidBody)

See RigidBody node docs.

Collider(Collider)

See Collider node docs.

Joint(Joint)

See Joint node docs.

RigidBody2D(RigidBody)

See dim2::rigidbody::RigidBody node docs.

Collider2D(Collider)

See dim2::collider::Collider node docs.

Joint2D(Joint)

See dim2::joint::Joint node docs.

Rectangle(Rectangle)

Rectangle node. See Rectangle node docs.

Implementations

impl Node

pub fn local_bounding_box(&self) -> AxisAlignedBoundingBox

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

pub fn world_bounding_box(&self) -> AxisAlignedBoundingBox

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

pub fn from_id(id: u8) -> Result<Self, String>

Creates new Node based on variant id.

pub fn id(&self) -> u8

Returns actual variant id.

pub fn raw_copy(&self) -> Self

This method creates raw copy of a node, it should never be called in normal circumstances because internally nodes may (and most likely will) contain handles to other nodes. To correctly clone a node you have to use copy_node.

pub fn is_mesh(&self) -> bool

Returns true if node is instance of given type.

pub fn as_mesh(&self) -> &Mesh

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_mesh_mut(&mut self) -> &mut Mesh

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_camera(&self) -> bool

Returns true if node is instance of given type.

pub fn as_camera(&self) -> &Camera

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_camera_mut(&mut self) -> &mut Camera

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_light(&self) -> bool

Returns true if node is instance of given type.

pub fn as_light(&self) -> &Light

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_light_mut(&mut self) -> &mut Light

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_particle_system(&self) -> bool

Returns true if node is instance of given type.

pub fn as_particle_system(&self) -> &ParticleSystem

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_particle_system_mut(&mut self) -> &mut ParticleSystem

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_sprite(&self) -> bool

Returns true if node is instance of given type.

pub fn as_sprite(&self) -> &Sprite

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_sprite_mut(&mut self) -> &mut Sprite

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_terrain(&self) -> bool

Returns true if node is instance of given type.

pub fn as_terrain(&self) -> &Terrain

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_terrain_mut(&mut self) -> &mut Terrain

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_decal(&self) -> bool

Returns true if node is instance of given type.

pub fn as_decal(&self) -> &Decal

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_decal_mut(&mut self) -> &mut Decal

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_rectangle(&self) -> bool

Returns true if node is instance of given type.

pub fn as_rectangle(&self) -> &Rectangle

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_rectangle_mut(&mut self) -> &mut Rectangle

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_rigid_body(&self) -> bool

Returns true if node is instance of given type.

pub fn as_rigid_body(&self) -> &RigidBody

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_rigid_body_mut(&mut self) -> &mut RigidBody

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_collider(&self) -> bool

Returns true if node is instance of given type.

pub fn as_collider(&self) -> &Collider

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_collider_mut(&mut self) -> &mut Collider

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_joint(&self) -> bool

Returns true if node is instance of given type.

pub fn as_joint(&self) -> &Joint

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_joint_mut(&mut self) -> &mut Joint

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_rigid_body2d(&self) -> bool

Returns true if node is instance of given type.

pub fn as_rigid_body2d(&self) -> &RigidBody

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_rigid_body2d_mut(&mut self) -> &mut RigidBody

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_collider2d(&self) -> bool

Returns true if node is instance of given type.

pub fn as_collider2d(&self) -> &Collider

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_collider2d_mut(&mut self) -> &mut Collider

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_joint2d(&self) -> bool

Returns true if node is instance of given type.

pub fn as_joint2d(&self) -> &Joint

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_joint2d_mut(&mut self) -> &mut Joint

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

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 RESOURCE: &'static str = "resource"

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

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 PROPERTIES: &'static str = "properties"

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

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

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) -> &mut Self

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_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<Model>

Returns resource from which this node was instantiated from.

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

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) -> &mut Self

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. To check if object is visible from some camera, use VisibilityCache. However this still can’t tell you if object is behind obstacle or not.

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)

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)

Sets new tag.

pub fn raw_copy(&self) -> Self

Shallow copy of node data. You should never use this directly, shallow copy will produce invalid node in most cases!

pub fn frustum_culling(&self) -> bool

Return the frustum_culling flag

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

Sets whether to use frustum culling or not

Trait Implementations

impl Debug for Node

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

Formats the value using the given formatter.

impl Default for Node

fn default() -> Self

Returns the “default value” for a type.

impl DerefMut for Node

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

Mutably dereferences the value.

impl Inspect for Node

fn properties(&self) -> Vec<PropertyInfo<'_>>

Returns information about “public” properties.

impl Visit for Node

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

impl Deref for Node

type Target = Base

The resulting type after dereferencing.

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

Dereferences the value.