CoreInterfaces/Scenegraph.h File Reference

Detailed Description

This file defines the scenegraph related DInterfaces.

#include "Common.h"


Namespaces
namespace	DigitalSpaces
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...
struct	DISGRepresentative
	This DInterface should be implemented by a component wishing to duplicate or prodice objects to the scenegraph, as managed by the DISGManager implementation. More...
struct	DISGManager
	This DInterface should only be implemented by one component (SGManager), and is responsible for management of the scenegraph, by co-ordinating all the DISGRepresentative's. More...
Functions
	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.
	DInterfaceWithParent (DISGHeirachalRepr, DISGBaseRepr) DISGBaseRepr GetChild(const char name
	Retreive a pre-existing child object representation.
bool	AttachChild (DISGBase *child)
	Add a child object.
bool	DetachChild (const char *name)
	Remove a child node representation.
void	GetChildNamesAndTypes (DIStringPairList *names)
	Return the names and types of all the children this representation has.
	DInterfaceWithParent (DISGMovable, DISGBase) void SetPosition(in_Vector3f *pos)
	Set the position of the node.
void	GetPosition (out_Vector3f *pos)
	Retreive the position of the node.
void	SetOrientation (in_Quaternionf *orient)
	Set the orientation of the node.
void	GetOrientation (out_Quaternionf *orient)
	Retreive the orientation of the node.
void	SetScale (in_Vector3f *scale)
	Set the scale to be applied to the render objects attached to the node.
void	GetScale (out_Vector3f *scale)
	Retreive the scale applied to render objects attached to the node.
	DInterfaceWithParent (DISGMovableRepr, DISGBaseRepr) void SetPosition(in_Vector3f *pos)
	Set the position of the node representation.
bool	UseWorldPosition ()
	Discover if the implementation wants and provides position in world coordinates or relative to its parent.
bool	UseWorldOrientation ()
	Discover if the implementation wants and provides orientation in world coordinates or relative to its parent.
bool	UseWorldScale ()
	Discover if the implementation wants and provides scale in world coordinates or relative to its parent.
bool	IsSelfAnimatingPosition ()
	Inspect if the object implementation alters its position independent of SetPosition.
bool	IsSelfAnimatingOrientation ()
	Inspect if the object implementation alters its orientation independent of SetOrientation.
bool	IsSelfAnimatingScale ()
	Inspect if the object implementation alters its scale independent of SetScale.
	DInterfaceWithParent (DISGAnimated, DISGBase) void PlayAnimation(const char *sAnimationName
	Used for scene-graph objects that can control animations by name.
void	PlayAnimationTarget (const char *sAnimationName, double dTarget)
	Sets a target time at which the spcified animation will stop advancing (ie, speed will be set to 0).
void	StopAnimation (const char *sAnimationName)
	Stops the animation time advancing.
void	SetAnimationApplied (const char *sAnimationName, bool bEnabled)
	Applies the animation, but does not advance it automatically.
void	SetAnimationLoop (const char *sAnimationName, bool bLoop)
	Controls if the specified animation should loop when reaching its length.
void	SetAnimationWeight (const char *sAnimationName, double dWeight)
	Set animation weight.
void	SetAnimationWeightChange (const char *sAnimationName, double dWeightChange)
	Sets the rate at which the animations weight should change.
void	SetAnimationWeightChangeTarget (const char *sAnimationName, double dWeightTarget)
	Sets the point at which animation weight change will be automatically set to 0.0 (the animation weight will become constant).
void	SetAnimationTimePosition (const char *sAnimationName, double dTime)
	Jumps the animation to a specific point in time.
void	SetAnimationSpeed (const char *sAnimationName, double dSpeed)
	Sets the playback speed of the spcified animation.
void	GetAllAnimations (DIStringList1 *iList)
	Retreive a list of all the animation names supported by this object.
float	GetAnimationLength (const char *sName)
	Retreives the timeline length of the specified animation.
float	GetAnimationSpeed (const char *sAnimationName)
	Retreives the multiplier applied to the animations timeline advancement.
bool	GetAnimationApplied (const char *sAnimationName)
	Retreive if the specified animation is being applied to this object.
bool	GetAnimationLoop (const char *sAnimationName)
	Retreive if the animation should continue from the other end of the timeline when reaching an end.
float	GetAnimationWeight (const char *sAnimationName)
	Retreive the weight multiplier being used when applying the specified animation.
float	GetAnimationTimePosition (const char *sAnimationName)
	Retrieve the point along the specified animations timeline that is currently being applied.
	DInterfaceWithParent (DISGAnimatedRepr, DISGBaseRepr) bool HasAnimation(const char *sAnimationName)
	The DInterface implemented by the representations (who implement DISGRepresentative).
Variables
const char *	DigitalSpaces::type
const char DIXMLNode1 *	DigitalSpaces::configuration
const char *	type
double	dSpeed

Function Documentation

bool AttachChild ( DISGBase * child )

Add a child object.

This is used to implement DISGHeirachal::AddChild, allowing the implementation to query the DISGBase for an appropriate (internal) implementation and represent the addition internally.

Returns:: True if sucessfully added, false otherwise. False is not neccessarily an error, as not all representations will represent every part of the heirachy.

bool DetachChild ( const char * name )

Remove a child node representation.

Used to implement DISGHeirachal::RemoveChild.

Parameters:

name

Name of the child node representation to remove.

Returns:: True if sucessful, false otherwise. False is not neccessarily an error, as not all representations will represent every part of the heirachy.

DInterfaceWithParent	(	DISGAnimatedRepr	,
		DISGBaseRepr
	)			const

The DInterface implemented by the representations (who implement DISGRepresentative).

Contains the functionality to control a self animating render object. An example of this is a skeletally animated model.

This is a subset of the functionality provided by DISGAnimatedRenderObject, needed to implement that larger functionality.

This DInterface should only be implemented if implementing a DISGRepresentative, and should only be called from the DISGManager implementation. Test if the resentation supports the specified animation.

Parameters:

sAnimationName

Name of the animation.

Returns:: True if the specified name is supported, false otherwise.

DInterfaceWithParent	(	DISGAnimated	,
		DISGBase
	)			const

Used for scene-graph objects that can control animations by name.

E.G. OGRE Entities (via AnimationStates).

The name used for the animation is implementation dependant. For example, there may be an alias system. Currently the only system that uses this is the Ogre::Entity, where sAnimationName matches the name of the animation in the skeleton.

An "animation" is expected to have a set length, and to be able to be set to any position along its length. Animations start at time 0.0, and progress to their end, where they may loop, returning to time 0.0 . Enables and begins playing an animation. This is equivalent to:

                                SetAnimationApplied( sAnimationName, true);
                                SetAnimationSpeed( sAnimationName, dSpeed );

Parameters:

	sAnimationName	Name of the animation.
	dSpeed	Speed multiplier. E.g. Setting this to 2 will cause the animation to play at twice the rate, finishing in half the time. A setting of 0.5 will cause the animation to play at half the rate, finishing in double the time.

DInterfaceWithParent	(	DISGMovableRepr	,
		DISGBaseRepr
	)

Set the position of the node representation.

Parameters:

pos

New position of the node. Depending on the results of UseWorldPosition, this may be in world coordinates or parent coordinates.

DInterfaceWithParent	(	DISGMovable	,
		DISGBase
	)

Set the position of the node.

Parameters:

pos

New position of the node. This is relative to its parent.

DInterfaceWithParent	(	DISGHeirachalRepr	,
		DISGBaseRepr
	)			const

Retreive a pre-existing child object representation.

Todo:: Add a function that allows the Repr to inform the SGManager of child objects it didn't specifically request created. An example of this is a skeleton rigged Ogre Entity.

This is called during object creation, to find representations created from other sources, such as Ogre Skeleton's. This will work with the (to be added) function to get a list of all child objects that were not specifically requested.

Parameters:

	name	Name of the child node representation.
	type	The type of the child representation.

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

void GetAllAnimations ( DIStringList1 * iList )

Retreive a list of all the animation names supported by this object.

Parameters:

	iList	String List to have the animation names appended to. The implementation does not clear the list before appending the animation names.
	iList	String List to have the animation names appended to. The implementation does not clear the list before appending the animation names.

See also:: DISGAnimatedRenderObject::GetAllAnimations

bool GetAnimationApplied ( const char * sAnimationName )

Retreive if the specified animation is being applied to this object.

Parameters:

sAnimationName

Name of the animation

Returns:: True if applied, false otherwise. If the specified animation name is not recognised, false is returned.

Note:: The error condition return value is a valid return value.

float GetAnimationLength ( const char * sName )

Retreives the timeline length of the specified animation.

Parameters:

sName

Name of the animation

Returns:: Length of the animation timeline. This is equivalent to the time needed to play the animation, in seconds, when speed is 1.0. If the specified animation name is not recognised, 0.0 is returned.

Note:: The error condition return value is a valid return value, although unlikely.

bool GetAnimationLoop ( const char * sAnimationName )

Retreive if the animation should continue from the other end of the timeline when reaching an end.

Default value is true.

Parameters:

sAnimationName

Name of the animation

Returns:: True if the animation will loop, false otherwise. If the specified animation name is not recognised, false is returned.

Note:: The error condition return value is a valid return value.

float GetAnimationSpeed ( const char * sAnimationName )

Retreives the multiplier applied to the animations timeline advancement.

E.g. a value of 0.5 will make the animation play at half the speed (take twice as long to complete), and a value of 2.0 will make the animation play at double the speed (take half as long to complete).

Parameters:

sAnimationName

Name of the animation.

Returns:: Multiplier being applied to the animation playback speed. If the specified animation name is not recognised, 0.0 is returned.

Note:: The error condition return value is a valid return value.

See also:: SetAnimationSpeed

float GetAnimationTimePosition ( const char * sAnimationName )

Retrieve the point along the specified animations timeline that is currently being applied.

Parameters:

sAnimationName

Name of the animation

Returns:: Point along the animation timeline that is currently applied. Values range from 0.0 to the length of the animation timeline (see GetAnimationLength). If the specified animation name is not recognised, 0.0 is returned.

Note:: The error condition return value is a valid return value.

float GetAnimationWeight ( const char * sAnimationName )

Retreive the weight multiplier being used when applying the specified animation.

Parameters:

sAnimationName

Name of the animation

Returns:: Weight multiplier factor being used for the specified animation. If the specified animation name is not recognised, 0.0 is returned.

Note:: The error condition return value is a valid return value.

void GetChildNamesAndTypes ( DIStringPairList * names )

Return the names and types of all the children this representation has.

This is called after creation of child objects through the SGManager. It is intended that the representation can inform the SGManager of any children it has that it didn't specifically request. And example of this in use is: Ogre Entity returns <bones> (Ogre Skeleton Instance) Ogre Skeleton Instance returns a collection of <bone> (Ogre Bone) Ogre Bone returns a collection of <bone> (Ogre Bone)

void GetOrientation ( out_Quaternionf * orient )

Retreive the orientation of the node.

Retreive the orientation of the node representation.

Parameters:

[out] orient Quaternion to be filled with the orientation of the node. This is relative to it's parent.

Only called if IsSelfAnimatingOrientation is true.

Parameters:

[out] orient Quaternion to be filled with the orientation of the node. Depending on the results of UseWorldOrientation, this may be in world coordinates or parent coordinates.

void GetPosition ( out_Vector3f * pos )

Retreive the position of the node.

Retreive the position of the node representation.

Parameters:

[out] pos Vector to be filled with the position of the node. This is relative to its parent.

Only called if IsSelfAnimatingPosition is true.

Parameters:

[out] pos Vector to be filled with the position of the node. Depending on the results of UseWorldPosition, this may be in world coordinates or parent coordinates.

void GetScale ( out_Vector3f * scale )

Retreive the scale applied to render objects attached to the node.

Parameters:

[out] scale Vector to be filled with the per-axis multiplier.

Only called if IsSelfAnimatingScale is true.

Parameters:

[out] scale Vector to be filled with the per-axis multiplier. Depending on the results of UseWorldScale, this may be in world coordinates or parent coordinates.

bool IsSelfAnimatingOrientation ( )

Inspect if the object implementation alters its orientation independent of SetOrientation.

Examples of this are a mesh skeleton that has animations, or a physics body. This is used by the SGManager implementation to update any other representations.

Returns:: True if the heirachal object is being altered from within the component that created it, false otherwise.

Note:: In the case where more then one DISGMovableRepr returns true for this, which one is used is undefined.

bool IsSelfAnimatingPosition ( )

Inspect if the object implementation alters its position independent of SetPosition.

Examples of this are a mesh skeleton that has animations, or a physics body. This is used by the SGManager implementation to update any other representations.

Returns:: True if the heirachal object is being altered from within the component that created it, false otherwise.

Note:: In the case where more then one DISGMovableRepr returns true for this, which one is used is undefined.

bool IsSelfAnimatingScale ( )

Inspect if the object implementation alters its scale independent of SetScale.

An example of this is a mesh skeleton that has animations. This is used by the SGManager implementation to update any other representations.

Returns:: True if the heirachal object is being altered from within the component that created it, false otherwise.

Note:: In the case where more then one DISGMovableRepr returns true for this, which one is used is undefined.

void PlayAnimationTarget	(	const char *	sAnimationName,
		double	dTarget
	)

Sets a target time at which the spcified animation will stop advancing (ie, speed will be set to 0).

Parameters:

	sAnimationName	Name of the animation.
	dTarget	Time on the animation timeline at which the animation will stop. Valid values are from 0.0 to the length of the animation. The target is relative to the beginning of the animation, not the current time position of the animation. It is affected by the animation speed that has been set.

void SetAnimationApplied	(	const char *	sAnimationName,
		bool	bEnabled
	)

Applies the animation, but does not advance it automatically.

Controls if the specified animation should be applied or not.

This is equivalent to DISGAnimatedRenderObject::SetAnimationApplied.

Parameters:

	sAnimationName	Name of the animation. If the aniamtion name is not supported, nothing will occur.
	bEnabled	True if the animation should be applied

void SetAnimationLoop	(	const char *	sAnimationName,
		bool	bLoop
	)

Controls if the specified animation should loop when reaching its length.

By default, this is true.

Parameters:

	sAnimationName	Name of the animation.
	bLoop	True if the animation should loop, otherwise false.

void SetAnimationSpeed	(	const char *	sAnimationName,
		double	dSpeed
	)

Sets the playback speed of the spcified animation.

This is a multiplier applied to the advancement of the animation along its timeline. E.g. a value of 0.5 will make the animation play at half the speed (take twice as long to complete), and a value of 2.0 will make the animation play at double the speed (take half as long to complete).

Parameters:

	sAnimationName	Name of the animation.
	dSpeed	Multiplier that is applied to the animations advancement along its timeline. Both positive and negative values are valid.

void SetAnimationTimePosition	(	const char *	sAnimationName,
		double	dTime
	)

Jumps the animation to a specific point in time.

Sets the specific point of an animations timeline that will be used to modify the object.

This is the point along the animation timeline, from the beginning of the animation. This is consistent with animation speed, so the value will represent the same point of the animation, regardless of the currently specified speed.

Parameters:

	sAnimationName	Name of the animation.
	dTime	If set to less then 0, or greater then the length of the animation, behaviour is undefined.

See also:: DISGAnimatedRenderObject::SetAnimationTimePosition

void SetAnimationWeight	(	const char *	sAnimationName,
		double	dWeight
	)

Set animation weight.

Set the multiplier the animation should be applied with.

Animation weight is a multiplier applied to the animations offsets from the original position/keyframe. This is as relative to total weights. E.G.: Having 3 animations applied, each with a weight of 1, will result in each animation being applied by 1/3 (each bone position/orientation with be an equal average of each animation).

Parameters:

	sAnimationName	Name of the animation
	dWeight	Multiplier to use. This is scaled against the total weight set across all animations. Values below 0.0 are invalid.

See also:: DISGAnimatedRenderObject::SetAnimationWeight

void SetAnimationWeightChange	(	const char *	sAnimationName,
		double	dWeightChange
	)

Sets the rate at which the animations weight should change.

Parameters:

	sAnimationName	Name of the animation
	dWeightChange	The number supplied is the total change that will be applied in a second of time. If this is positive, the animation weight will increase. If negative, it will decrease.

Note:: This does not provide any automatic limitation by default, and will allow the weight to increase infinately (to the limit of the floating point), or go below 0.0. As per SetAnimationWeight, weight below 0.0 is undefined. See SetAnimationWeightChangeTarget to limit the weight change, rather then polling with GetAnimationWeight, then calling this function with a 0.0 parameter.

void SetAnimationWeightChangeTarget	(	const char *	sAnimationName,
		double	dWeightTarget
	)

Sets the point at which animation weight change will be automatically set to 0.0 (the animation weight will become constant).

This is used as a control to SetAnimationWeightChange, avoiding the need to poll. This also prevents overruns, as the check is done at the same time as the advance, ensuring the weight does not go past the limit, even for a single heartbeat. The implementation correctly handles both positive and negative animation weight change rates.

Parameters:

	sAnimationName	Name of the animation
	dWeightTarget	The value that the current rate change will be stopped at.

void SetOrientation ( in_Quaternionf * orient )

Set the orientation of the node.

Set the orientation of the node representation.

Parameters:

	orient	New orientation of the node. This is relative to the parent.
	orient	New orientation of the node. Depending on the results of UseWorldOrientation, this may be in world coordinates or parent coordinates.

void SetScale ( in_Vector3f * scale )

Set the scale to be applied to the render objects attached to the node.

Parameters:

scale

Per-axis multiplier to be applied to the attached render objects.

Note:: By default scale is inherited. (I think.)

Parameters:

scale

Per-axis multiplier to be applied to the attached render objects. Depending on the results of UseWorldScale, this may be in world coordinates or parent coordinates.

void StopAnimation ( const char * sAnimationName )

Stops the animation time advancing.

The animation is still applied, however. This is equivalent to SetAnimationSpeed( sAnimationName, 0.0 );

bool UseWorldOrientation ( )

Discover if the implementation wants and provides orientation in world coordinates or relative to its parent.

Returns:: True if using world coordinates, false if using relative to its parent.

bool UseWorldPosition ( )

Discover if the implementation wants and provides position in world coordinates or relative to its parent.

Returns:: True if using world coordinates, false if using relative to its parent.

bool UseWorldScale ( )

Discover if the implementation wants and provides scale in world coordinates or relative to its parent.

Returns:: True if using world coordinates, false if using relative to its parent.

Variable Documentation

double dSpeed

const char* type

CoreInterfaces/Scenegraph.h File Reference

Detailed Description

Namespaces

Data Structures

Functions

Variables

Function Documentation

Variable Documentation