DigitalSpaces::DIOGREEntity Struct Reference
[Ogre]

#include <OGREInterfaces.h>

Inherits DigitalSpaces::DIObjectBase.

Public Member Functions
DIOGREMesh *	GetMesh (void)
	Gets the Mesh that this Entity is based on.
DIOGRESubEntity *	GetSubEntity (unsigned int index)
	Gets a pointer to a SubEntity, ie a part of an Entity.
DIOGRESubEntity *	GetSubEntity (const char *name)
	Gets a pointer to a SubEntity by name.
unsigned int	GetNumSubEntities (void)
	Retrieves the number of SubEntity objects making up this entity.
DIOGREEntity *	Clone (const char *newName)
	Clones this entity and returns a pointer to the clone.
void	SetMaterialName (const char *name)
	Sets the material to use for the whole of this entity.
DIOGREAnimationState *	GetAnimationState (const char *name)
	For entities based on animated meshes, gets the AnimationState object for a single animation.
void	SetDisplaySkeleton (bool display)
	For entities based on animated meshes, gets the AnimationState objects for all animations.
bool	GetDisplaySkeleton (void)
	Returns whether or not the entity is currently displaying its skeleton.
void	SetMeshLodBias (float factor)
	Sets a level-of-detail bias for the mesh detail of this entity.
void	SetMeshLodBias (float factor, unsigned short maxDetailIndex, unsigned short minDetailIndex)
void	SetMaterialLodBias (float factor)
	Sets a level-of-detail bias for the material detail of this entity.
void	SetMaterialLodBias (float factor, unsigned short maxDetailIndex, unsigned short minDetailIndex)
void	SetPolygonModeOverrideable (bool renderDetailOverrideable)
	Sets whether the rendering detail of this entire entity may be overridden by the camera detail settings.
DIOGRETagPoint *	AttachObjectToBone (const char *boneName, DIOGREMovableObject *pMovable)
	Attaches another object to a certain bone of the skeleton which this entity uses.
DIOGRETagPoint *	AttachObjectToBone (const char *boneName, DIOGREMovableObject *pMovable, in_Quaternionf *offsetOrientation, in_Vector3f *offsetPosition)
DIOGREMovableObject *	DetachObjectFromBone (const char *movableName)
	detach a MovableObject previously attached using attachObjectToBone
void	DetachObjectFromBone (DIOGREMovableObject *obj)
	Detaches an object by pointer.
void	DetachAllObjectsFromBone (void)
	Detach all MovableObjects previously attached using attachObjectToBone.
void	SetNormaliseNormals (bool normalise)
	Gets an iterator to the list of objects attached to bones on this entity.
bool	GetNormaliseNormals (void)
	Returns true if this entity has auto-normalisation of normals set.
bool	HasSkeleton (void)
	Returns whether or not this entity is skeletally animated.
DIOGRESkeletonInstance *	GetSkeleton (void)
	Get this Entity's personal skeleton instance.
bool	IsHardwareAnimationEnabled (void)
	Returns whether or not hardware skinning is enabled.
int	GetSoftwareAnimationRequests (void)
	Returns the number of requests that have been made for software skinning.
int	GetSoftwareAnimationNormalsRequests (void)
	Returns the number of requests that have been made for software skinning of normals.
void	AddSoftwareAnimationRequest (bool normalsAlso)
	Add a request for software skinning.
void	RemoveSoftwareAnimationRequest (bool normalsAlso)
	Removes a request for software skinning.
void	ShareSkeletonInstanceWith (DIOGREEntity *entity)
	Shares the SkeletonInstance with the supplied entity.
void	StopSharingSkeletonInstance (void)
	Stops sharing the SkeletonInstance with other entities.
bool	SharesSkeletonInstance ()
	Returns whether this entity shares it's SkeltonInstance with other entity instances.
void	RefreshAvailableAnimationState (void)
	Returns a pointer to the set of entities which share a SkeletonInstance.

---

Member Function Documentation

DIOGREMesh* DigitalSpaces::DIOGREEntity::GetMesh

(

void

)

Gets the Mesh that this Entity is based on.

DIOGRESubEntity* DigitalSpaces::DIOGREEntity::GetSubEntity

(

unsigned int

index

)

Gets a pointer to a SubEntity, ie a part of an Entity.

DIOGRESubEntity* DigitalSpaces::DIOGREEntity::GetSubEntity

(

const char *

name

)

Gets a pointer to a SubEntity by name.

Remarks:

- names should be initialized during a Mesh creation.

unsigned int DigitalSpaces::DIOGREEntity::GetNumSubEntities

(

void

)

Retrieves the number of SubEntity objects making up this entity.

DIOGREEntity* DigitalSpaces::DIOGREEntity::Clone

(

const char *

newName

)

Clones this entity and returns a pointer to the clone.

Remarks:

Useful method for duplicating an entity. The new entity must be given a unique name, and is not attached to the scene in any way so must be attached to a SceneNode to be visible (exactly as entities returned from SceneManager::createEntity).

Parameters:

newName

Name for the new entity.

void DigitalSpaces::DIOGREEntity::SetMaterialName

(

const char *

name

)

Sets the material to use for the whole of this entity.

Remarks:

This is a shortcut method to set all the materials for all subentities of this entity. Only use this method is you want to set the same material for all subentities or if you know there is only one. Otherwise call getSubEntity() and call the same method on the individual SubEntity.

DIOGREAnimationState* DigitalSpaces::DIOGREEntity::GetAnimationState

(

const char *

name

)

For entities based on animated meshes, gets the AnimationState object for a single animation.

Remarks:

You animate an entity by updating the animation state objects. Each of these represents the current state of each animation available to the entity. The AnimationState objects are initialised from the Mesh object.

void DigitalSpaces::DIOGREEntity::SetDisplaySkeleton

(

bool

display

)

For entities based on animated meshes, gets the AnimationState objects for all animations.

Returns:

In case the entity is animated, this functions returns the pointer to a AnimationStateSet containing all animations of the entries. If the entity is not animated, it returns 0.

Remarks:

You animate an entity by updating the animation state objects. Each of these represents the current state of each animation available to the entity. The AnimationState objects are initialised from the Mesh object. Tells the Entity whether or not it should display it's skeleton, if it has one.

bool DigitalSpaces::DIOGREEntity::GetDisplaySkeleton

(

void

)

Returns whether or not the entity is currently displaying its skeleton.

void DigitalSpaces::DIOGREEntity::SetMeshLodBias

(

float

factor

)

Sets a level-of-detail bias for the mesh detail of this entity.

Remarks:

Level of detail reduction is normally applied automatically based on the Mesh settings. However, it is possible to influence this behaviour for this entity by adjusting the LOD bias. This 'nudges' the mesh level of detail used for this entity up or down depending on your requirements. You might want to use this if there was a particularly important entity in your scene which you wanted to detail better than the others, such as a player model.

There are three parameters to this method; the first is a factor to apply; it defaults to 1.0 (no change), by increasing this to say 2.0, this model would take twice as long to reduce in detail, whilst at 0.5 this entity would use lower detail versions twice as quickly. The other 2 parameters are hard limits which let you set the maximum and minimum level-of-detail version to use, after all other calculations have been made. This lets you say that this entity should never be simplified, or that it can only use LODs below a certain level even when right next to the camera.

Parameters:

	factor	Proportional factor to apply to the distance at which LOD is changed. Higher values increase the distance at which higher LODs are displayed (2.0 is twice the normal distance, 0.5 is half).
	maxDetailIndex	The index of the maximum LOD this entity is allowed to use (lower indexes are higher detail: index 0 is the original full detail model).
	minDetailIndex	The index of the minimum LOD this entity is allowed to use (higher indexes are lower detail. Use something like 99 if you want unlimited LODs (the actual LOD will be limited by the number in the Mesh)

void DigitalSpaces::DIOGREEntity::SetMeshLodBias	(	float	factor,
		unsigned short	maxDetailIndex,
		unsigned short	minDetailIndex
	)

void DigitalSpaces::DIOGREEntity::SetMaterialLodBias

(

float

factor

)

Sets a level-of-detail bias for the material detail of this entity.

Remarks:

Level of detail reduction is normally applied automatically based on the Material settings. However, it is possible to influence this behaviour for this entity by adjusting the LOD bias. This 'nudges' the material level of detail used for this entity up or down depending on your requirements. You might want to use this if there was a particularly important entity in your scene which you wanted to detail better than the others, such as a player model.

There are three parameters to this method; the first is a factor to apply; it defaults to 1.0 (no change), by increasing this to say 2.0, this entity would take twice as long to use a lower detail material, whilst at 0.5 this entity would use lower detail versions twice as quickly. The other 2 parameters are hard limits which let you set the maximum and minimum level-of-detail index to use, after all other calculations have been made. This lets you say that this entity should never be simplified, or that it can only use LODs below a certain level even when right next to the camera.

Parameters:

	factor	Proportional factor to apply to the distance at which LOD is changed. Higher values increase the distance at which higher LODs are displayed (2.0 is twice the normal distance, 0.5 is half).
	maxDetailIndex	The index of the maximum LOD this entity is allowed to use (lower indexes are higher detail: index 0 is the original full detail model).
	minDetailIndex	The index of the minimum LOD this entity is allowed to use (higher indexes are lower detail. Use something like 99 if you want unlimited LODs (the actual LOD will be limited by the number of lod indexes used in the Material)

void DigitalSpaces::DIOGREEntity::SetMaterialLodBias	(	float	factor,
		unsigned short	maxDetailIndex,
		unsigned short	minDetailIndex
	)

void DigitalSpaces::DIOGREEntity::SetPolygonModeOverrideable

(

bool

renderDetailOverrideable

)

Sets whether the rendering detail of this entire entity may be overridden by the camera detail settings.

DIOGRETagPoint* DigitalSpaces::DIOGREEntity::AttachObjectToBone	(	const char *	boneName,
		DIOGREMovableObject *	pMovable
	)

Attaches another object to a certain bone of the skeleton which this entity uses.

Remarks:

This method can be used to attach another object to an animated part of this entity, by attaching it to a bone in the skeleton (with an offset if required). As this entity is animated, the attached object will move relative to the bone to which it is attached.

Parameters:

	boneName	The name of the bone (in the skeleton) to attach this object
	pMovable	Pointer to the object to attach
	offsetOrientation	An adjustment to the orientation of the attached object, relative to the bone.
	offsetPosition	An adjustment to the position of the attached object, relative to the bone.

DIOGRETagPoint* DigitalSpaces::DIOGREEntity::AttachObjectToBone	(	const char *	boneName,
		DIOGREMovableObject *	pMovable,
		in_Quaternionf *	offsetOrientation,
		in_Vector3f *	offsetPosition
	)

DIOGREMovableObject* DigitalSpaces::DIOGREEntity::DetachObjectFromBone

(

const char *

movableName

)

detach a MovableObject previously attached using attachObjectToBone

void DigitalSpaces::DIOGREEntity::DetachObjectFromBone

(

DIOGREMovableObject *

obj

)

Detaches an object by pointer.

Remarks:

This method is need when destroy a MovableObject which attached to a bone of this entity. But sometimes the object may be not in the child object list because it is a lod entity, this method can safely detect and ignore in this case.

void DigitalSpaces::DIOGREEntity::DetachAllObjectsFromBone

(

void

)

Detach all MovableObjects previously attached using attachObjectToBone.

void DigitalSpaces::DIOGREEntity::SetNormaliseNormals

(

bool

normalise

)

Gets an iterator to the list of objects attached to bones on this entity.

If set to true, this forces normals of this entity to be normalised dynamically by the hardware.

Remarks:

This option can be used to prevent lighting variations when scaling an Entity using a SceneNode - normally because this scaling is hardware based, the normals get scaled too which causes lighting to become inconsistent. However, this has an overhead so only do this if you really need to.

bool DigitalSpaces::DIOGREEntity::GetNormaliseNormals

(

void

)

Returns true if this entity has auto-normalisation of normals set.

bool DigitalSpaces::DIOGREEntity::HasSkeleton

(

void

)

Returns whether or not this entity is skeletally animated.

DIOGRESkeletonInstance* DigitalSpaces::DIOGREEntity::GetSkeleton

(

void

)

Get this Entity's personal skeleton instance.

bool DigitalSpaces::DIOGREEntity::IsHardwareAnimationEnabled

(

void

)

Returns whether or not hardware skinning is enabled.

Remarks:

Because fixed-function indexed vertex blending is rarely supported by existing graphics cards, hardware skinning can only be done if the vertex programs in the materials used to render an entity support it. Therefore, this method will only return true if all the materials assigned to this entity have vertex programs assigned, and all those vertex programs must support 'include_skeletal_animation true'.

int DigitalSpaces::DIOGREEntity::GetSoftwareAnimationRequests

(

void

)

Returns the number of requests that have been made for software skinning.

Remarks:

If non-zero then software skinning will be performed in updateAnimation regardless of the current setting of isHardwareSkinningEnabled. Requests for software skinning are made by calling the addSoftwareSkinningRequest() method.

int DigitalSpaces::DIOGREEntity::GetSoftwareAnimationNormalsRequests

(

void

)

Returns the number of requests that have been made for software skinning of normals.

Remarks:

If non-zero, and getSoftwareSkinningRequests() also returns non-zero, then software skinning of normals will be performed in updateAnimation regardless of the current setting of isHardwareSkinningEnabled. Currently it is not possible to force software skinning of only normals. Consequently this value is always less than or equal to that returned by getSoftwareSkinningRequests(). Requests for software skinning of normals are made by calling the addSoftwareSkinningRequest() method with 'true' as the parameter.

void DigitalSpaces::DIOGREEntity::AddSoftwareAnimationRequest

(

bool

normalsAlso

)

Add a request for software skinning.

Remarks:

Tells the entity to perform skinning calculations for skeletal animations in software, regardless of the current setting of isHardwareSkinningEnabled(). Software skinning will be performed any time one or more requests have been made. If 'normalsAlso' is 'true', then the entity will also do software blending on normal vectors, in addition to positions. This advanced method useful for situations in which access to actual mesh vertices is required, such as accurate collision detection or certain advanced shading techniques. When software skinning is no longer needed, the caller of this method should always remove the request by calling removeSoftwareSkinningRequest(), passing the same value for 'normalsAlso'.

void DigitalSpaces::DIOGREEntity::RemoveSoftwareAnimationRequest

(

bool

normalsAlso

)

Removes a request for software skinning.

Remarks:

Calling this decrements the entity's internal counter of the number of requests for software skinning. If the counter is already zero then calling this method throws an exception. The 'normalsAlso' flag if set to 'true' will also decrement the internal counter of number of requests for software skinning of normals.

void DigitalSpaces::DIOGREEntity::ShareSkeletonInstanceWith

(

DIOGREEntity *

entity

)

Shares the SkeletonInstance with the supplied entity.

Note that in order for this to work, both entities must have the same Skeleton.

void DigitalSpaces::DIOGREEntity::StopSharingSkeletonInstance

(

void

)

Stops sharing the SkeletonInstance with other entities.

bool DigitalSpaces::DIOGREEntity::SharesSkeletonInstance

(

)

Returns whether this entity shares it's SkeltonInstance with other entity instances.

void DigitalSpaces::DIOGREEntity::RefreshAvailableAnimationState

(

void

)

Returns a pointer to the set of entities which share a SkeletonInstance.

If this instance does not share it's SkeletonInstance with other instances NULL will be returned Updates the internal animation state set to include the latest available animations from the attached skeleton.

Remarks:

Use this method if you manually add animations to a skeleton, or have linked the skeleton to another for animation purposes since creating this entity.

Note:

If you have called getAnimationState prior to calling this method, the pointers will still remain valid.

---

The documentation for this struct was generated from the following file:

• OGREInterfaces/OGREInterfaces.h