Group Class Reference
[Scene Graph]

#include <lvt/Group.h>

Inheritance diagram for Group:

[legend]List of all members.

---

Detailed Description

Groups related scene graph nodes together.

A Group is a Node that aggregates other Nodes. Use Groups to arrange related Nodes into a single object. Groups are the building blocks of hierarchical scene graphs.

Public Member Functions
void	AddChild (Node *newChild)
	Adds a child object to the Group.
virtual bool	Animate (unsigned int deltaTime)
	Animates the Group.
void	Clear ()
	Removes all children from the Group.
int	Find (const Node *node) const
	Searches for a child Node.
virtual BoundingBox	GetBounds ()
	Returns a BoundingBox containing all of the Group's children.
	Group (const Group &g)
	Copy constructor.
	Group ()
	Default constructor.
void	InsertChild (Node *newChild, int index)
	Inserts a child object into the Group.
bool	IsSealed () const
	Returns true if the Group is sealed, false if it is not.
void	RemoveChild (int index)
	Removes a node from the Group.
virtual void	Render ()
	Renders the group.
void	Seal ()
	Seals a static group to speed rendering.
size_t	Size () const
	Returns the number of child objects in the Group.
virtual Node *	Traverse (class Traversal *t)
	Creates a new traversal (subgraph) of the node.
void	UnSeal ()
	Unseals a Group.
virtual	~Group ()
	Default destructor.
Node *	operator[] (int i)
	Returns a pointer to the ith child node.
Protected Member Functions
virtual void	PostRender ()
	Performs any cleanup necessary after rendering child objects.
virtual void	PreRender ()
	Performs any setup necessary before rendering child objects.
virtual void	RenderChildren ()
	Renders child objects.

---

Constructor & Destructor Documentation

Group (   )

Default constructor. Constructs an empty, unsealed Group.

Group (  const Group &  g  )

Copy constructor. Constructs a new Group with the same children as the argument Group. If the argument Group is sealed, the new group is compiled into a new display list.

virtual ~Group (   )  [virtual]

Default destructor. When a Group is destroyed, the reference count of each child object is decremented, and the children are destroyed, if necessary.

---

Member Function Documentation

void AddChild (  Node *  newChild  )

Adds a child object to the Group. Parameters: newChild  pointer to new child object. Adds a new child to the end of the Group. Adding a child to a Group increments its reference count.

virtual bool Animate (  unsigned int  deltaTime  )  [virtual]

Animates the Group. Calls the Animate() member function for each child Node. Note that Animate() always animates the child objects, even if the Group is sealed. Therefore, sealing a group which contains Animators (or other Nodes that implement Animate()) may cause discontinuities when the group is unsealed. Pause or disable any animation in child nodes to avoid discontinuities. Reimplemented from Node.

void Clear (   )

Removes all children from the Group. Removes all children from the Group, decrementing their reference counts, and deleting them, if necessary.

int Find (  const Node *  node  )  const

Searches for a child Node. Parameters: node  Node pointer to search for. Returns: index of the specified node in the Group, or -1 if the specified node was not found.

virtual BoundingBox GetBounds (   )  [virtual]

Returns a BoundingBox containing all of the Group's children. Reimplemented from Node.

void InsertChild (  Node *  newChild, int  index )

Inserts a child object into the Group. Parameters: newChild  pointer to the new child to add. index  position of the new child within the Group. Inserts newChild into the group at the position specified by index, and increments its reference count. If index is out of range, no action is taken.

bool IsSealed (   )  const [inline]

Returns true if the Group is sealed, false if it is not.

Node* operator[] (  int  i  )  [inline]

Returns a pointer to the ith child node.

virtual void PostRender (   )  [protected, virtual]

Performs any cleanup necessary after rendering child objects. Called by Render() after any child objects have been rendered, and after a display list is created or executed, if the Group is sealed. When deriving from Group, override this function to perform any necessary cleanup after rendering children. Reimplemented in Separator.

virtual void PreRender (   )  [protected, virtual]

Performs any setup necessary before rendering child objects. Called by Render() before any child objects are rendered, and before a display list is created or executed, if the Group is sealed. When deriving from Group, override this function to perform any necessary initialization before rendering children. Reimplemented in Separator.

void RemoveChild (  int  index  )

Removes a node from the Group. Parameters: index  position of the child to remove. Removes the node at position index from the group, and decrements its reference count, deleting the object if necessary. If index is out of range, no action is taken.

virtual void Render (   )  [virtual]

Renders the group. If the Group is sealed, Render() creates a display list, if necessary, and executes it. If the Group is not sealed, Render() calls the RenderChildren() member function to render each child. When deriving from Group, this function should not, in general, be overridden. The work is performed by PreRender(), PostRender(), and RenderChildren(), and those are the function that an implementor of a Group derived class should override. Using the Group implementation of Render() for derived objects guarantees that the behavior of sealed Groups is consistent for all Group-derived classes. Note that PreRender() and PostRender() are not compiled into the display list. Use these two functions to implement any animation, or other changes across different calls to Render(). Implements Node.

virtual void RenderChildren (   )  [protected, virtual]

Renders child objects. Renders all child objects. The default implementation iterates over the child objects in the order they were added and calls the Render() function for each child. When deriving from Group, override this function to change the behavior of child rendering. Reimplemented in Switch, and AutoSwitch.

void Seal (   )

Seals a static group to speed rendering. If a group contains objects that are static, i.e. not changing with respect to each other. An increase in performance can be gained by sealing the Group, which collects its child nodes into an OpenGL display list. Once a Group is sealed, the display list will be built on the next call to Render(). After this call, the display list will be fixed, and no changes to any child nodes will show up in successive calls to Render(). For changes to take effect, the group must be unsealed with UnSeal(), and then resealed. NOTE: Sealing a Group which contains an Animator will "freeze" the Animator in time until the Group is unsealed. This is not the recommended way to pause the animation of an Animator. Animator::Pause() is the correct way to stop an animation. Rapidly sealing and unsealing an object can be expensive. Only Groups that change infrequently should be sealed.

size_t Size (   )  const [inline]

Returns the number of child objects in the Group.

virtual Node* Traverse (  class Traversal *  t  )  [virtual]

Creates a new traversal (subgraph) of the node. Parameters: t  a reference to a Traversal object. Calls the Traversal object's Evaluate function on all child objects of this group and returns a new group object containing as children all nodes that passed the evaluation. See documentation for the Traverse class for information on creating a scene graph traversal.

void UnSeal (   )

Unseals a Group. Destroys the sealed group's associated display list and marks the Group as unsealed. A sealed group must be unsealed before any changes made to child nodes will show up in a call to Render(). Is it perfectly acceptable for a sealed or unsealed Group to contain other sealed or unsealed Groups. However, sealing a Group will effectively seal any child Groups. Modifying a child Group of a sealed Group will have no effect until the parent Group is unsealed.

---