SceneGraph
[Interfaces]

---

Detailed Description

These are very generic DInterfaces for the ordering and heirachy of rendering objects.

This generic design allows for a central place to manage a wide variety of renderable types, including models, particle systems, cameras, sounds, and physics bodies.

Standard usage is to use the DISGManager DInterface to access DISGNode and DISGRenderObject's by name (every node and render object must have a unique name, although their can be duplication between DISGNodes and DISGRenderObjects. DISGNodeRepresentation, DISGRenderObjectRepresentation and DISGAnimatedRenderObjectRepresentation are only used if your componet is implementing DISGRepresentative. Implementing these DInterfaces allows your component to contribute objects to the scene graph (or to duplicate existing objects with your implementation). An example of this is that both 3DVisuals_OGRE and Physics_ODE implement DISGRepresentative and create DISGNodeRepresentation's. 3DVisuals_OGRE creates an Ogre::SceneNode for each DISGNodeRepresentation requested, where Physics_ODE creates ODE Bodies when the body="true" attribute is present.

The SGManagers creates DISGNode, DISGRenderObject and DISGAnimatedRenderObject's by:

• At system startup, the Scenegraph Manager (which implements DISGManager), will be given a configuration chunk. This will include a scenefile to be parsed.
• Before parsing the scenefile, the sgmanager will look for all implementations of DISGRepresentative.
• The .scene file format is broken into three parts. <environment>, <external>, and <nodes>.
• The <environment> DIXMLNode1 will be passed to each of the DISGRepresentative's, to give them generic configuration. They are expected to ignore any entries they do not parse.
• The <external> tag MAY be passed to DIResourceManager's (not yet determined this point of the design).
• The <nodes> tag is where the sgmanager really starts to work. It first creates a "ROOT" Node in all DISGRepresentative's, then steps through the child DIXMLNode's of the <nodes> entry.
• Each child entry is checked for two peices of data, the type (eg the type for a <node> is "node") and the name. If name is not specified one will be generated. If the type is "node", then all DISGRepresenative's will be instructed to make a DISGNodeRepresentation, returning NULL if not supported.
• Each DISGNodeRepresentation will be dss_cast to a DIAcceptConfiguration1 and given the DIXMLNode1 that it was created to represent.

  Note:

  A DISGNodeRepresentation should not attempt to create heirachy from the information in the DIXMLNode. This will be handled by the sgmanager. Additionally, DISGNodeRepresentations are not required to read <position>, <orientation> or <scale>, as these too will be handled by the sgmanager.

• When the sgmanager encounters a tag that is not a <node>, each of the DISGRepresentative's will be instructed to make a DISGRenderObjectRepresentative of that type. A DISGRepresentative is expected to return NULL for a type it does not recognise. These DISGRenderObjectRepresentation's will then be attached to the parent DISGNode (and thus the parent DISGNodeRepresentation).

• If at least one DISGRenderObjectRepresentation is created, but none can be dss_cast to a DISGNodeRepresentation, then no further processing will occur for that DIXMLNode. However, if a DISGRenderObjectRepresentation can be dss_cast sucessfully, then the sgmanager will continue to parse the DIXMLNode1 children. In this way DISGRenderObjectRepresentations that have internal heirachies can be created/manipulated. An example of this is a billboardSet, which will be able to create billboard child DISGRenderObjectRepresentations. Another example of this is a skeletally animated mesh entity. This entity will provide access to the skeletons bones, and then allow creation of further <entity> DISGRenderObjectRepresentation's. In this way, models can be loaded already attached to bones (and through code, entities can be attached to bones as if they were simply another node).

Physics bodies will be created from <nodes> with the attribute isBody="true". Since physics bodies work in absolute co-ordinates, DISGNodeRepresentation has DISGNodeRepresentation::UseWorldPosition and similar functions that returns true for that implementation. Physics shapes will also be created as DISGNodeRepresentations but will not return true for DISGNodeRepresentation::UseWorldPosition etc. Joints also work in world coordinates. They will also return true for DISGNodeRepresentation::IsSelfAnimating.

Additional Notes on processing the unrecognized XML Nodes. There are from the SGManager implementation:

• Give each DISGRepresentation a chance to create an object of this type.
• Keep the positive results. If no positive results, don't create anything and dont further process this xmlNode.
• Create a collection (SGRenderObject) to store the DISGRepresentation's SGRenderObject's.
• Attatch the collection to the pParent.
• dss_cast the SGRenderObject to DIAcceptConfiguration and pass the xmlNode to ParseConfiguration. (This will pass on to the DISGRepresentation's SGRenderObject's as well.)
• Check if any of the postive results are also DISGNodeRepresentations. (We do this after calling ParseConfiguration so implementations have enough information to make the decision.) Create a SGNode (that doesn't attempt to create its own representations) and pass it all the DISGNodeRepresentations. Add the SGNode to the SGRenderObject for QueryInterface purposes.

This allows the end user to find a non-<node> as an attached DISGRenderObject, but if they plan to use it as a DISGNode, they can find it as that too.

Note:

The DISGRenderObject can dss_cast to the DISGNode (as this adds functionality) but not in reverse, but thats ok because all DISGRenderObject functionality is present in DISGNode. However, the DISGNode will only dss_cast into the representations that are DISGNodeRepresentations. The reason we dont have the DISGNode link back to the DISGRenderObject is to avoid looping due to forwarding QueryInterface calls.

Data Structures
struct	DigitalSpaces::DISGBase
	The base functionality common to all scene-graph objects. More...
struct	DigitalSpaces::DISGBaseRepr
	Common functionality of SG Object Representations. More...
void	DigitalSpaces::DISGBase::GetAbsolutePosition (out_Vector3f *pos)
	Convenience functions.
void	DigitalSpaces::DISGBase::GetAbsoluteOrientation (out_Quaternionf *orient)
	Retreive the orientation of the object.
void	DigitalSpaces::DISGBase::GetAbsoluteScale (out_Vector3f *scale)
	Retreive the scale applied to render objects.
Functions
const char *	DigitalSpaces::DISGBase::GetType ()
	Return the sub-type.
DISGHeirachal *	DigitalSpaces::DISGBase::GetSGParent ()
	Return the parent node.
void	DigitalSpaces::DISGBase::CreateAdditionalRepresentations (const char *type, DIXMLNode1 *configuration)
	Allows creation of additional representations (from DISGRepresentative) using different information.
	DigitalSpaces::DInterfaceWithParent (DISGHeirachal, DISGBase) DISGBase *CreateChild(const char *name
	Convenience function for DISGManager::CreateSGNode(name, type, this, configuration).
DISGBase *	DigitalSpaces::GetChild (const char *name)
	Retreive a child node.
bool	DigitalSpaces::AttachChild (DISGBase *child)
	Add a child node.
bool	DigitalSpaces::DetachChild (const char *name)
	Remove a child node.
void	DigitalSpaces::GetChildNames (DIStringList1 *names)
	Retreive a list of the names of all child nodes.
DISGBaseRepr *	DISGRepresentative::GetSGRepr (const char *name)
	Retreive a previously created scenegraph object representation.
DISGBaseRepr *	DISGRepresentative::CreateSGRepr (const char *name, const char *type, DISGHeirachal *parent, DIXMLNode1 *configuration)
	Create a new scenegraph object representation.
bool	DISGRepresentative::DestroySGRepr (const char *name)
	Destroy a previously created scenegraph node representation.
bool	DISGManager::DestroySGObject (const char *name)
	Destroy a previously created scene graph object.
DISGBase *	DISGManager::GetSGObject (const char *name)
	Retreive a previously created scene graph object.
DISGHeirachal *	DISGManager::GetSGHeirachal (const char *name)
	A convenience version of GetSGObject, that performs the type cast for you.
DISGMovable *	DISGManager::GetSGMovable (const char *name)
	A convenience version of GetSGObject, that performs the type cast for you.
DISGAnimated *	DISGManager::GetSGAnimated (const char *name)
	A convenience version of GetSGObject, that performs the type cast for you.
DISGBase *	DISGManager::CreateAdditionalRepresentationsOfObject (const char *name, const char *type, DIXMLNode1 *configuration)
	Create additional representations of the specified object, with different configuration data.
Variables
const char *	DigitalSpaces::type
const char DIXMLNode1 *	DigitalSpaces::configuration

---

Function Documentation

bool DigitalSpaces::AttachChild

(

DISGBase *

child

)

Add a child node.

This is generally used to move nodes from one point on the scene heirachy to another.

Returns:

True if sucessful, false if an error occurs.

Note:

Does calling this with an already attached node (one that hasn't been passed to RemoveChild as appropriate) work with the current implementation? What happens? - What should happen?

void DigitalSpaces::DISGBase::CreateAdditionalRepresentations	(	const char *	type,
		DIXMLNode1 *	configuration
	)			[inherited]

Allows creation of additional representations (from DISGRepresentative) using different information.

DISGBase* DISGManager::CreateAdditionalRepresentationsOfObject	(	const char *	name,
		const char *	type,
		DIXMLNode1 *	configuration
	)			[inherited]

Create additional representations of the specified object, with different configuration data.

See also:

CreateSGObject

DISGBaseRepr* DISGRepresentative::CreateSGRepr	(	const char *	name,
		const char *	type,
		DISGHeirachal *	parent,
		DIXMLNode1 *	configuration
	)			[inherited]

Create a new scenegraph object representation.

Parameters:

	name	Identifier used for the newly created node. It will (should) be unique.
	type	Subtype identifier used for the object. A commonexample is "node" however other types are permissable, assuming that a DISGRepresentative recognised the type.
	parent	Provided for context for new SG object creation. The new representation is not required to be attached to/a child of the parent, AddChild will be called on the parent after creation is complete.
	configuration	Free form XML providing configuration details to the DISGRepresentative's. Implementations are not required to understand all the information passed. The implementation should avoid doing too much work with the configuration data. Tt will also be passed to the implementation as DIAcceptConfiguration1::ParseConfiguration, where as much of the work as possible should be done. This is to allow post-creation configuration of properties that might otherwise remain unconfigurable.

Returns:

Interface to the newly created node representation, or NULL if creation did not occur. Creation not occuring is not an error, it may simply means this SGRepresentative does not wish to represent this part of the heirachy.

bool DISGManager::DestroySGObject

(

const char *

name

)

[inherited]

Destroy a previously created scene graph object.

Parameters:

name

Name used when creating the object.

Returns:

True if the object was found (and destroyed), false otherwise.

bool DISGRepresentative::DestroySGRepr

(

const char *

name

)

[inherited]

Destroy a previously created scenegraph node representation.

Parameters:

name

Name used to identify the node representation

Returns:

True if a representation was destroyed, false otherwise. Note that false is not an error condition, as this representative may not have a representation for that part of the scenegraph heirachy.

Note:

Should we add or replace with a version that takes a DISGBase. This (combined with removing GetSGRepr) would remove the need for DISGRepresentatives to track object names, which may be foreign to their design.

bool DigitalSpaces::DetachChild

(

const char *

name

)

Remove a child node.

Returns:

True if sucessful, false if an error occured (such as the specified node not being a child).

Note:

This removes the node from the heirachy, but does not destroy it. It may be attached elsewhere using AddChild.

DigitalSpaces::DInterfaceWithParent	(	DISGHeirachal	,
		DISGBase
	)			const

Convenience function for DISGManager::CreateSGNode(name, type, this, configuration).

void DigitalSpaces::DISGBase::GetAbsoluteOrientation

(

out_Quaternionf *

orient

)

[inherited]

Retreive the orientation of the object.

Parameters:

[out]

orient

Quaternion to be filled with the orientation of the node. This is in world space.

void DigitalSpaces::DISGBase::GetAbsolutePosition

(

out_Vector3f *

pos

)

[inherited]

Convenience functions.

Any object in the scenegraph has an absolute position and orientation, as long as it's part of the heirachy. Even if it's position cannot be moved, the position/orientation of it's nearest ancestor Movable is it's position/orientation. Retreive the position of the object.

Parameters:

[out]

pos

Vector to be filled with the position of the node. This is in world space.

void DigitalSpaces::DISGBase::GetAbsoluteScale

(

out_Vector3f *

scale

)

[inherited]

Retreive the scale applied to render objects.

Parameters:

[out]

scale

Vector to be filled with the per-axis multiplier.

DISGBase* DigitalSpaces::GetChild

(

const char *

name

)

Retreive a child node.

This includes attached render objects that have implementations that also implemented DISGNodeRepresentation - i.e. non-node heirachal objects or non-node positionable objects.

Returns:

Interface to the child node, or NULL if no node by that name is a direct child.

void DigitalSpaces::GetChildNames

(

DIStringList1 *

names

)

Retreive a list of the names of all child nodes.

This is not recursive, i.e it only returns the direct children.

Parameters:

names

String List that will have the names of the child nodes appended. The implementation does not clear the list before appending.

DISGAnimated* DISGManager::GetSGAnimated

(

const char *

name

)

[inherited]

A convenience version of GetSGObject, that performs the type cast for you.

Note that the returned DISGAnimated should still be able to be dss_cast to a DISGMovable or DISGHeirachal, if appropriate.

Parameters:

name

Name used when creating the object.

Returns:

Interface to the specified object, or NULL if the name is not recognised, or not of the requested type.

DISGHeirachal* DISGManager::GetSGHeirachal

(

const char *

name

)

[inherited]

A convenience version of GetSGObject, that performs the type cast for you.

Note that the returned DISGHeirachal should still be able to be dss_cast to a DISGMovable or DISGAnimated, if appropriate.

Parameters:

name

Name used when creating the object.

Returns:

Interface to the specified object, or NULL if the name is not recognised, or not of the requested type.

DISGMovable* DISGManager::GetSGMovable

(

const char *

name

)

[inherited]

A convenience version of GetSGObject, that performs the type cast for you.

Note that the returned DISGMovable should still be able to be dss_cast to a DISGHeirachal or DISGAnimated, if appropriate.

Parameters:

name

Name used when creating the object.

Returns:

Interface to the specified object, or NULL if the name is not recognised, or not of the requested type.

DISGBase* DISGManager::GetSGObject

(

const char *

name

)

[inherited]

Retreive a previously created scene graph object.

Parameters:

name

Name used when creating the object.

Returns:

Interface to the specified object, or NULL if the name is not recognised.

DISGHeirachal* DigitalSpaces::DISGBase::GetSGParent

(

)

[inherited]

Return the parent node.

Returns:

Interface to parent node, or NULL if this node is not attached to the scene graph, or is the root of the scenegraph.

DISGBaseRepr* DISGRepresentative::GetSGRepr

(

const char *

name

)

[inherited]

Retreive a previously created scenegraph object representation.

Parameters:

name

Name used when creating the node.

Returns:

Interface to the node representation, or NULL if the name is not recognised.

Note:

Is this function useful? Doesn't the SGManager keep track of these from creation to destruction?

const char* DigitalSpaces::DISGBase::GetType

(

)

[inherited]

Return the sub-type.

This should only be used as a general peice of information, attempting to dss_cast is a better way of detecting what an object is/can do

An example value is node (created from a <node>).

---

Variable Documentation

const char DIXMLNode1* DigitalSpaces::configuration

const char* DigitalSpaces::type