Trait SceneGraph 

pub trait SceneGraph: 'static {
    type Prefab: PrefabData<Graph = Self>;
    type NodeContainer: PayloadContainer<Element = Self::Node>;
    type Node: SceneGraphNode<SceneGraph = Self, ResourceData = Self::Prefab>;

    // Required methods
    fn summary(&self) -> String;
    fn actual_type_id(
        &self,
        handle: Handle<Self::Node>,
    ) -> Result<TypeId, PoolError>;
    fn actual_type_name(
        &self,
        handle: Handle<Self::Node>,
    ) -> Result<&'static str, PoolError>;
    fn derived_type_ids(
        &self,
        handle: Handle<Self::Node>,
    ) -> Result<Vec<TypeId>, PoolError>;
    fn root(&self) -> Handle<Self::Node>;
    fn set_root(&mut self, root: Handle<Self::Node>);
    fn try_get_node(
        &self,
        handle: Handle<Self::Node>,
    ) -> Result<&Self::Node, PoolError>;
    fn try_get_node_mut(
        &mut self,
        handle: Handle<Self::Node>,
    ) -> Result<&mut Self::Node, PoolError>;
    fn is_valid_handle(
        &self,
        handle: Handle<impl ObjectOrVariant<Self::Node>>,
    ) -> bool;
    fn add_node(&mut self, node: Self::Node) -> Handle<Self::Node>;
    fn add_node_at_handle(
        &mut self,
        node: Self::Node,
        handle: Handle<Self::Node>,
    );
    fn remove_node(
        &mut self,
        node_handle: Handle<impl ObjectOrVariant<Self::Node>>,
    );
    fn link_nodes(
        &mut self,
        child: Handle<impl ObjectOrVariant<Self::Node>>,
        parent: Handle<impl ObjectOrVariant<Self::Node>>,
    );
    fn unlink_node(
        &mut self,
        node_handle: Handle<impl ObjectOrVariant<Self::Node>>,
    );
    fn isolate_node(
        &mut self,
        node_handle: Handle<impl ObjectOrVariant<Self::Node>>,
    );
    fn pair_iter(
        &self,
    ) -> impl Iterator<Item = (Handle<Self::Node>, &Self::Node)>;
    fn linear_iter(&self) -> impl Iterator<Item = &Self::Node>;
    fn linear_iter_mut(&mut self) -> impl Iterator<Item = &mut Self::Node>;
    fn try_get<U>(&self, handle: Handle<U>) -> Result<&U, PoolError>
       where U: ObjectOrVariant<Self::Node>;
    fn try_get_mut<U>(&mut self, handle: Handle<U>) -> Result<&mut U, PoolError>
       where U: ObjectOrVariant<Self::Node>;

    // Provided methods
    fn node(&self, handle: Handle<Self::Node>) -> &Self::Node { ... }
    fn node_mut(&mut self, handle: Handle<Self::Node>) -> &mut Self::Node { ... }
    fn try_get_node_by_uuid(&self, uuid: Uuid) -> Option<&Self::Node> { ... }
    fn try_get_node_by_uuid_mut(
        &mut self,
        uuid: Uuid,
    ) -> Option<&mut Self::Node> { ... }
    fn change_hierarchy_root(
        &mut self,
        prev_root: Handle<impl ObjectOrVariant<Self::Node>>,
        new_root: Handle<impl ObjectOrVariant<Self::Node>>,
    ) -> LinkScheme<Self::Node> { ... }
    fn apply_link_scheme(&mut self, scheme: LinkScheme<Self::Node>) { ... }
    fn remove_nodes(
        &mut self,
        nodes: &[Handle<impl ObjectOrVariant<Self::Node>>],
    ) { ... }
    fn try_get_of_type<T>(
        &self,
        handle: Handle<Self::Node>,
    ) -> Result<&T, PoolError>
       where T: 'static { ... }
    fn try_get_mut_of_type<T>(
        &mut self,
        handle: Handle<Self::Node>,
    ) -> Result<&mut T, PoolError>
       where T: 'static { ... }
    fn has_component<T>(
        &self,
        handle: Handle<impl ObjectOrVariant<Self::Node>>,
    ) -> bool
       where T: 'static { ... }
    fn find_map<C, T>(
        &self,
        root_node: Handle<impl ObjectOrVariant<Self::Node>>,
        cmp: &mut C,
    ) -> Option<(Handle<Self::Node>, &T)>
       where C: FnMut(&Self::Node) -> Option<&T>,
             T: ?Sized { ... }
    fn find_up<C>(
        &self,
        root_node: Handle<impl ObjectOrVariant<Self::Node>>,
        cmp: &mut C,
    ) -> Option<(Handle<Self::Node>, &Self::Node)>
       where C: FnMut(&Self::Node) -> bool { ... }
    fn find_handle_up<C>(
        &self,
        root_node: Handle<impl ObjectOrVariant<Self::Node>>,
        cmp: &mut C,
    ) -> Handle<Self::Node>
       where C: FnMut(&Self::Node) -> bool { ... }
    fn find_component_up<T>(
        &self,
        node_handle: Handle<impl ObjectOrVariant<Self::Node>>,
    ) -> Option<(Handle<Self::Node>, &T)>
       where T: 'static { ... }
    fn find_component<T>(
        &self,
        node_handle: Handle<impl ObjectOrVariant<Self::Node>>,
    ) -> Option<(Handle<Self::Node>, &T)>
       where T: 'static { ... }
    fn find_up_map<C, T>(
        &self,
        root_node: Handle<impl ObjectOrVariant<Self::Node>>,
        cmp: &mut C,
    ) -> Option<(Handle<Self::Node>, &T)>
       where C: FnMut(&Self::Node) -> Option<&T>,
             T: ?Sized { ... }
    fn find_by_name(
        &self,
        root_node: Handle<impl ObjectOrVariant<Self::Node>>,
        name: &str,
    ) -> Option<(Handle<Self::Node>, &Self::Node)> { ... }
    fn find_up_by_name(
        &self,
        root_node: Handle<impl ObjectOrVariant<Self::Node>>,
        name: &str,
    ) -> Option<(Handle<Self::Node>, &Self::Node)> { ... }
    fn find_by_name_from_root(
        &self,
        name: &str,
    ) -> Option<(Handle<Self::Node>, &Self::Node)> { ... }
    fn find_handle_by_name_from_root(&self, name: &str) -> Handle<Self::Node> { ... }
    fn find_from_root<C>(
        &self,
        cmp: &mut C,
    ) -> Option<(Handle<Self::Node>, &Self::Node)>
       where C: FnMut(&Self::Node) -> bool { ... }
    fn find<C>(
        &self,
        root_node: Handle<impl ObjectOrVariant<Self::Node>>,
        cmp: &mut C,
    ) -> Option<(Handle<Self::Node>, &Self::Node)>
       where C: FnMut(&Self::Node) -> bool { ... }
    fn find_handle<C>(
        &self,
        root_node: Handle<impl ObjectOrVariant<Self::Node>>,
        cmp: &mut C,
    ) -> Handle<Self::Node>
       where C: FnMut(&Self::Node) -> bool { ... }
    fn relative_position(
        &self,
        child: Handle<impl ObjectOrVariant<Self::Node>>,
        offset: isize,
    ) -> Option<(Handle<Self::Node>, usize)> { ... }
    fn traverse_iter(
        &self,
        from: Handle<impl ObjectOrVariant<Self::Node>>,
    ) -> impl Iterator<Item = (Handle<Self::Node>, &Self::Node)> { ... }
    fn traverse_handle_iter(
        &self,
        from: Handle<impl ObjectOrVariant<Self::Node>>,
    ) -> impl Iterator<Item = Handle<Self::Node>> { ... }
    fn restore_integrity<F>(
        &mut self,
        instantiate: F,
    ) -> Vec<(Handle<Self::Node>, Resource<Self::Prefab>)>
       where F: FnMut(Resource<Self::Prefab>, &Self::Prefab, Handle<Self::Node>, &mut Self) -> (Handle<Self::Node>, NodeHandleMap<Self::Node>) { ... }
    fn restore_original_handles_and_inherit_properties<F>(
        &mut self,
        ignored_types: &[TypeId],
        before_inherit: F,
    )
       where F: FnMut(&Self::Node, &mut Self::Node) { ... }
    fn remap_handles(
        &mut self,
        instances: &[(Handle<Self::Node>, Resource<Self::Prefab>)],
    ) { ... }
}

SceneGraph is a trait for all scene graphs to implement.

Required Associated Types

type Prefab: PrefabData<Graph = Self>

type NodeContainer: PayloadContainer<Element = Self::Node>

type Node: SceneGraphNode<SceneGraph = Self, ResourceData = Self::Prefab>

Required Methods

fn summary(&self) -> String

Generate a string that briefly summarizes the content of the graph for debugging.

fn actual_type_id( &self, handle: Handle<Self::Node>, ) -> Result<TypeId, PoolError>

Returns actual type id of the node.

fn actual_type_name( &self, handle: Handle<Self::Node>, ) -> Result<&'static str, PoolError>

Returns actual type name of the node.

fn derived_type_ids( &self, handle: Handle<Self::Node>, ) -> Result<Vec<TypeId>, PoolError>

Returns a list of derived type ids of the node.

fn root(&self) -> Handle<Self::Node>

Returns a handle of the root node of the graph.

fn set_root(&mut self, root: Handle<Self::Node>)

Sets the new root of the graph. If used incorrectly, it may create isolated sub-graphs.

fn try_get_node( &self, handle: Handle<Self::Node>, ) -> Result<&Self::Node, PoolError>

Tries to borrow a node, returns Ok(node) if the handle is valid, Err(…) - otherwise.

fn try_get_node_mut( &mut self, handle: Handle<Self::Node>, ) -> Result<&mut Self::Node, PoolError>

Tries to borrow a node, returns Ok(node) if the handle is valid, Err(…) - otherwise.

fn is_valid_handle( &self, handle: Handle<impl ObjectOrVariant<Self::Node>>, ) -> bool

Checks whether the given node handle is valid or not.

fn add_node(&mut self, node: Self::Node) -> Handle<Self::Node>

Adds a new node to the graph.

fn add_node_at_handle(&mut self, node: Self::Node, handle: Handle<Self::Node>)

Adds a new node to the graph at the given handle.

fn remove_node(&mut self, node_handle: Handle<impl ObjectOrVariant<Self::Node>>)

Destroys the node and its children recursively.

fn link_nodes( &mut self, child: Handle<impl ObjectOrVariant<Self::Node>>, parent: Handle<impl ObjectOrVariant<Self::Node>>, )

Links specified child with specified parent.

fn unlink_node(&mut self, node_handle: Handle<impl ObjectOrVariant<Self::Node>>)

Unlinks specified node from its parent and attaches it to root graph node.

fn isolate_node( &mut self, node_handle: Handle<impl ObjectOrVariant<Self::Node>>, )

Detaches the node from its parent, making the node unreachable from any other node in the graph.

fn pair_iter(&self) -> impl Iterator<Item = (Handle<Self::Node>, &Self::Node)>

Creates new iterator that iterates over internal collection giving (handle; node) pairs.

fn linear_iter(&self) -> impl Iterator<Item = &Self::Node>

Creates an iterator that has linear iteration order over internal collection of nodes. It does not perform any tree traversal!

fn linear_iter_mut(&mut self) -> impl Iterator<Item = &mut Self::Node>

Creates an iterator that has linear iteration order over internal collection of nodes. It does not perform any tree traversal!

fn try_get<U>(&self, handle: Handle<U>) -> Result<&U, PoolError>

where U: ObjectOrVariant<Self::Node>,

Tries to borrow a graph node by the given handle. This method accepts both type-agnostic container (read - Self::Node) handles and the actual node type handles. For example, if the container type is Node (holds Box<dyn NodeTrait>) and there’s a SpecificNode (implements the NodeTrait), then this method can accept both Handle<Node> and Handle<SpecificNode>. Internally, this method will try to downcast the container to the specified type (which may fail).

Also, in most cases, the implementation will also provide access to inner components of the node. This means that if a node implements ComponentProvider trait and there’s a field of type T in the actual node type, then this method will at first try to downcast the node to the given type and on failure will try to find a component of the given type.

fn try_get_mut<U>(&mut self, handle: Handle<U>) -> Result<&mut U, PoolError>

where U: ObjectOrVariant<Self::Node>,

Tries to borrow a graph node by the given handle. This method accepts both type-agnostic container (read - Self::Node) handles and the actual node type handles. For example, if the container type is Node (holds Box<dyn NodeTrait>) and there’s a SpecificNode (implements the NodeTrait), then this method can accept both Handle<Node> and Handle<SpecificNode>. Internally, this method will try to downcast the container to the specified type (which may fail).

Also, in most cases, the implementation will also provide access to inner components of the node. This means that if a node implements ComponentProvider trait and there’s a field of type T in the actual node type, then this method will at first try to downcast the node to the given type and on failure will try to find a component of the given type.

Provided Methods

fn node(&self, handle: Handle<Self::Node>) -> &Self::Node

Borrows a node by its handle.

fn node_mut(&mut self, handle: Handle<Self::Node>) -> &mut Self::Node

Borrows a node by its handle.

fn try_get_node_by_uuid(&self, uuid: Uuid) -> Option<&Self::Node>

Tries to borrow a node, returns Some(node) if the uuid is valid, None - otherwise.

fn try_get_node_by_uuid_mut(&mut self, uuid: Uuid) -> Option<&mut Self::Node>

Tries to borrow a node, returns Some(node) if the uuid is valid, None - otherwise.

fn change_hierarchy_root( &mut self, prev_root: Handle<impl ObjectOrVariant<Self::Node>>, new_root: Handle<impl ObjectOrVariant<Self::Node>>, ) -> LinkScheme<Self::Node>

Reorders the node hierarchy so the new_root becomes the root node for the entire hierarchy under the prev_root node. For example, if we have this hierarchy and want to set C as the new root:

Root_
     |_A_
         |_B
         |_C_
            |_D

The new hierarchy will become:

C_
  |_D
  |_A_
  |   |_B
  |_Root

This method returns an instance of LinkScheme, that could be used to revert the hierarchy back to its original. See Self::apply_link_scheme for more info.

fn apply_link_scheme(&mut self, scheme: LinkScheme<Self::Node>)

Applies the given link scheme to the graph, basically reverting graph structure to the one that was before the call of Self::change_hierarchy_root.

fn remove_nodes(&mut self, nodes: &[Handle<impl ObjectOrVariant<Self::Node>>])

Removes all the nodes from the given slice.

fn try_get_of_type<T>( &self, handle: Handle<Self::Node>, ) -> Result<&T, PoolError>

where T: 'static,

Tries to borrow a node and fetch its component of specified type.

fn try_get_mut_of_type<T>( &mut self, handle: Handle<Self::Node>, ) -> Result<&mut T, PoolError>

where T: 'static,

Tries to mutably borrow a node and fetch its component of specified type.

fn has_component<T>( &self, handle: Handle<impl ObjectOrVariant<Self::Node>>, ) -> bool

where T: 'static,

Tries to borrow a node by the given handle and checks if it has a component of the specified type.

fn find_map<C, T>( &self, root_node: Handle<impl ObjectOrVariant<Self::Node>>, cmp: &mut C, ) -> Option<(Handle<Self::Node>, &T)>

where C: FnMut(&Self::Node) -> Option<&T>, T: ?Sized,

Searches for a node down the tree starting from the specified node using the specified closure. Returns a tuple with a handle and a reference to the mapped value. If nothing is found, it returns None.

fn find_up<C>( &self, root_node: Handle<impl ObjectOrVariant<Self::Node>>, cmp: &mut C, ) -> Option<(Handle<Self::Node>, &Self::Node)>

where C: FnMut(&Self::Node) -> bool,

Searches for a node up the tree starting from the specified node using the specified closure. Returns a tuple with a handle and a reference to the found node. If nothing is found, it returns None.

fn find_handle_up<C>( &self, root_node: Handle<impl ObjectOrVariant<Self::Node>>, cmp: &mut C, ) -> Handle<Self::Node>

where C: FnMut(&Self::Node) -> bool,

The same as Self::find_up, but only returns node handle which will be Handle::NONE if nothing is found.

fn find_component_up<T>( &self, node_handle: Handle<impl ObjectOrVariant<Self::Node>>, ) -> Option<(Handle<Self::Node>, &T)>

where T: 'static,

fn find_component<T>( &self, node_handle: Handle<impl ObjectOrVariant<Self::Node>>, ) -> Option<(Handle<Self::Node>, &T)>

where T: 'static,

fn find_up_map<C, T>( &self, root_node: Handle<impl ObjectOrVariant<Self::Node>>, cmp: &mut C, ) -> Option<(Handle<Self::Node>, &T)>

where C: FnMut(&Self::Node) -> Option<&T>, T: ?Sized,

Searches for a node up the tree starting from the specified node using the specified closure. Returns a tuple with a handle and a reference to the mapped value. If nothing is found, it returns None.

fn find_by_name( &self, root_node: Handle<impl ObjectOrVariant<Self::Node>>, name: &str, ) -> Option<(Handle<Self::Node>, &Self::Node)>

Searches for a node with the specified name down the tree starting from the specified node. Returns a tuple with a handle and a reference to the found node. If nothing is found, it returns None.

fn find_up_by_name( &self, root_node: Handle<impl ObjectOrVariant<Self::Node>>, name: &str, ) -> Option<(Handle<Self::Node>, &Self::Node)>

Searches for a node with the specified name up the tree starting from the specified node. Returns a tuple with a handle and a reference to the found node. If nothing is found, it returns None.

fn find_by_name_from_root( &self, name: &str, ) -> Option<(Handle<Self::Node>, &Self::Node)>

Searches for a node with the specified name down the tree starting from the graph root. Returns a tuple with a handle and a reference to the found node. If nothing is found, it returns None.

fn find_handle_by_name_from_root(&self, name: &str) -> Handle<Self::Node>

fn find_from_root<C>( &self, cmp: &mut C, ) -> Option<(Handle<Self::Node>, &Self::Node)>

where C: FnMut(&Self::Node) -> bool,

Searches node using specified compare closure starting from root. Returns a tuple with a handle and a reference to the found node. If nothing is found, it returns None.

fn find<C>( &self, root_node: Handle<impl ObjectOrVariant<Self::Node>>, cmp: &mut C, ) -> Option<(Handle<Self::Node>, &Self::Node)>

where C: FnMut(&Self::Node) -> bool,

Searches for a node down the tree starting from the specified node using the specified closure. Returns a tuple with a handle and a reference to the found node. If nothing is found, it returns None.

fn find_handle<C>( &self, root_node: Handle<impl ObjectOrVariant<Self::Node>>, cmp: &mut C, ) -> Handle<Self::Node>

where C: FnMut(&Self::Node) -> bool,

The same as Self::find, but only returns node handle which will be Handle::NONE if nothing is found.

fn relative_position( &self, child: Handle<impl ObjectOrVariant<Self::Node>>, offset: isize, ) -> Option<(Handle<Self::Node>, usize)>

Returns position of the node in its parent children list and the handle to the parent. Adds given offset to the position. For example, if you have the following hierarchy:

A_
 |B
 |C

Calling this method with a handle of C will return Some((handle_of(A), 1)). The returned value will be clamped in the 0..parent_child_count range. None will be returned only if the given handle is invalid, or it is the root node.

fn traverse_iter( &self, from: Handle<impl ObjectOrVariant<Self::Node>>, ) -> impl Iterator<Item = (Handle<Self::Node>, &Self::Node)>

Create a graph depth traversal iterator.

fn traverse_handle_iter( &self, from: Handle<impl ObjectOrVariant<Self::Node>>, ) -> impl Iterator<Item = Handle<Self::Node>>

Create a graph depth traversal iterator.

fn restore_integrity<F>( &mut self, instantiate: F, ) -> Vec<(Handle<Self::Node>, Resource<Self::Prefab>)>

where F: FnMut(Resource<Self::Prefab>, &Self::Prefab, Handle<Self::Node>, &mut Self) -> (Handle<Self::Node>, NodeHandleMap<Self::Node>),

This method checks integrity of the graph and restores it if needed. For example, if a node was added in a parent asset, then it must be added in the graph. Alternatively, if a node was deleted in a parent asset, then its instance must be deleted in the graph.

fn restore_original_handles_and_inherit_properties<F>( &mut self, ignored_types: &[TypeId], before_inherit: F, )

where F: FnMut(&Self::Node, &mut Self::Node),

fn remap_handles( &mut self, instances: &[(Handle<Self::Node>, Resource<Self::Prefab>)], )

Maps handles in properties of instances after property inheritance. It is needed, because when a property contains node handle, the handle cannot be used directly after inheritance. Instead, it must be mapped to respective instance first.

To do so, we at first, build node handle mapping (original handle -> instance handle) starting from instance root. Then we must find all inheritable properties and try to remap them to instance handles.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl SceneGraph for UserInterface

type Prefab = UserInterface

type NodeContainer = WidgetContainer

type Node = UiNode

impl SceneGraph for Graph

type Prefab = Model

type NodeContainer = NodeContainer

type Node = Node