Struct SceneGraph

pub struct SceneGraph<T> {
    pub root: T,
    /* private fields */
}

The core structure of scene-graph. This forms a rose tree, similar to a geneological tree. In this crate, we use geneological terms like parent, child, and sibling to describe node relationships.

A scene graph is composed of nodes, which have children, which are other nodes. Nodes additionally have siblings, which is determined by order of insertion into the graph.

You can traverse the SceneGraph by iter, to iterate downwards over the entire graph, or iter_on_node, to iterate downward from a particular node. This crate has no ability to iterate upwards, but you can use get to find a node’s parent. If iterating upwards if useful to your usecase, please file an issue. Additionally, there are mutable variants of all of these iterators available.

Fields

root: T

The root value of the scene graph.

Implementations

impl<T> SceneGraph<T>

pub const fn new(root: T) -> Self

Creates a new SceneGraph

pub fn clear(&mut self)

Clears all nodes from self, leaving the Root in place. If you want to edit the root too, just make a new SceneGraph.

Note: this method maintains the underlying container’s size, so future attaches could have some performance gains.

pub fn len(&self) -> usize

Returns the number of NON-ROOT nodes in the graph.

pub fn is_empty(&self) -> bool

Checks if the SceneGraph contains only the root.

pub fn attach_at_root(&mut self, value: T) -> NodeIndex

Attaches a node to the root node, returning a handle to it.

This is a convenience method which will never fail.

pub fn attach( &mut self, parent: NodeIndex, value: T, ) -> Result<NodeIndex, ParentNodeNotFound>

Attaches a node to another node, returning a handle to it.

pub fn attach_graph( &mut self, parent: NodeIndex, other_graph: SceneGraph<T>, ) -> Result<(NodeIndex, HashMap<NodeIndex, NodeIndex>), ParentNodeNotFound>

Attaches an entire scene graph to a place on this graph. The old root node will be at the returned NodeIndex.

pub fn detach(&mut self, node_index: NodeIndex) -> Option<SceneGraph<T>>

Removes a given node from the scene graph, returning a new SceneGraph where the given node is now the root.

Note: this always returns None when the node doesn’t exist, or when the node_index is the Root.

pub fn move_node( &mut self, moving_node_idx: NodeIndex, new_parent: NodeIndex, ) -> Result<(), NodeDoesNotExist>

Moves a node from one parent to another parent. If this operation returns Err, then nothing will have happened to the node.

pub fn remove(&mut self, node_index: NodeIndex)

Removes a node without returning anything. This can save a few allocations. This removes all of its children as well.

pub fn contains(&self, node_index: NodeIndex) -> bool

Returns true is the given node_index is valid.

pub fn get(&self, node_index: NodeIndex) -> Option<&Node<T>>

Gets a given node based on NodeIndex. Note that the Root always returns None. Simply access root_value to get the root value.

pub fn get_mut(&mut self, node_index: NodeIndex) -> Option<&mut Node<T>>

Gets a given node based on NodeIndex. Note that the Root always returns None, as it is not a true node. Use get_children to generically get children.

pub fn root(&self) -> &T

Gets the root node’s value.

pub fn root_mut(&mut self) -> &mut T

Gets the root node’s value mutably.

pub fn parent(&self, node_index: NodeIndex) -> Option<NodeIndex>

Returns the parent NodeIndex of a given Node.

This operation is O1 over the number of nodes in the SceneGraph. Note: this returns None for the Root.

pub fn iter_mut(&mut self) -> SceneGraphIterMut<'_, T>

Iterate mutably over the Scene Graph in a depth first traversal.

pub fn iter(&self) -> SceneGraphIter<'_, T>

Iterate immutably over the Scene Graph in a depth first traversal.

pub fn iter_out_of_order(&self) -> impl Iterator<Item = (NodeIndex, &T)>

Iterate immutably over the Scene Graph out of order. This is useful for speed.

pub fn iter_from_node( &self, node_index: NodeIndex, ) -> Result<SceneGraphIter<'_, T>, NodeDoesNotExist>

Iterate immutably over the Scene Graph in a depth first traversal.

pub fn iter_mut_from_node( &mut self, node_index: NodeIndex, ) -> Result<SceneGraphIterMut<'_, T>, NodeDoesNotExist>

Iterate immutably over the Scene Graph in a depth first traversal.

pub fn iter_detach_from_root(&mut self) -> SceneGraphDetachIter<'_, T>

Iterate while detaching over the Scene Graph in a depth first traversal.

Note: the root will never be detached.

pub fn iter_detach( &mut self, node_index: NodeIndex, ) -> Result<SceneGraphDetachIter<'_, T>, NodeDoesNotExist>

Iterate while detaching over the Scene Graph in a depth first traversal. This leaves the node_index given in the graph, but removes all its descendents.

pub fn iter_direct_children( &self, parent_index: NodeIndex, ) -> Result<SceneGraphChildIter<'_, T>, NodeDoesNotExist>

Iterate directly over only the direct children of parent_index.

For example, given a graph: ROOT: A B C D using iter_direct_children and passing in the parent_index for A will only yield B and C, not D. For that kind of depth first traversal, using iter_on_node.

Trait Implementations

impl<T: Debug> Debug for SceneGraph<T>

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

Formats the value using the given formatter.

impl<'a, T> IntoIterator for &'a SceneGraph<T>

type Item = (&'a T, &'a T)

The type of the elements being iterated over.

type IntoIter = SceneGraphIter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T> IntoIterator for &'a mut SceneGraph<T>

type Item = (&'a mut T, &'a mut T)

The type of the elements being iterated over.

type IntoIter = SceneGraphIterMut<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.