Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

Ogre::Entity Class Reference

Defines an instance of a discrete, movable object based on a Mesh. More...

#include <OgreEntity.h>

Inheritance diagram for Ogre::Entity:

Ogre::MovableObject List of all members.

Public Methods

 ~Entity ()
 Default destructor. More...

MeshgetMesh (void)
 Gets the Mesh that this Entity is based on. More...

SubEntitygetSubEntity (unsigned int index)
 Gets a pointer to a SubEntity, ie a part of an Entity. More...

unsigned int getNumSubEntities (void)
 Retrieves the number of SubEntity objects making up this entity. More...

Entity * clone (const String &newName)
 Clones this entity and returns a pointer to the clone. More...

void setMaterialName (const String &name)
 Sets the material to use for the whole of this entity. More...

void _notifyCurrentCamera (Camera *cam)
 Overridden - see MovableObject. More...

const AxisAlignedBoxgetBoundingBox (void) const
 Overridden - see MovableObject. More...

void _updateRenderQueue (RenderQueue *queue)
 Overridden - see MovableObject. More...

const StringgetName (void) const
 Overridden from MovableObject. More...

const String getMovableType (void) const
 Overridden from MovableObject. More...

AnimationStategetAnimationState (const String &name)
 For entities based on animated meshes, gets the AnimationState object for a single animation. More...

AnimationStateSetgetAllAnimationStates (void)
 For entities based on animated meshes, gets the AnimationState objects for all animations. More...

void setDisplaySkeleton (bool display)
 Tells the Entity whether or not it should display it's skeleton, if it has one. More...

void setLodBias (Real factor=1.0, ushort maxDetailIndex=0, ushort minDetailIndex=99)
 Sets a level-of-detail bias on this entity. More...

void setRenderDetail (SceneDetailLevel renderDetail)
 Sets the rendering detail of this entire entity (solid, wireframe etc). More...

virtual SceneNodegetParentNode (void)
 Returns the node to which this object is attached. More...

virtual void _notifyAttached (SceneNode *parent)
 Internal method called to notify the object that it has been attached to a node. More...

virtual bool isAttached (void) const
 Returns true if this object is attached to a SceneNode. More...

virtual void setVisible (bool visible)
 Tells this object whether to be visible or not, if it has a renderable component. More...

virtual bool isVisible (void) const
 Returns whether or not this object is supposed to be visible or not. More...

virtual void setUserObject (UserDefinedObject *obj)
 Call this to associate your own custom user object instance with this MovableObject. More...

virtual UserDefinedObjectgetUserObject (void)
 Retrieves a pointer to a custom application object associated with this movable by an earlier call to setUserObject. More...

virtual void setRenderQueueGroup (RenderQueueGroupID queueID)
 Sets the render queue group this entity will be rendered through. More...

virtual RenderQueueGroupID getRenderQueueGroup (void)
 Gets the queue group for this entity, see setRenderQueueGroup for full details. More...


Protected Attributes

SceneNodemParentNode
 node to which this object is attached. More...

bool mVisible
 Is this object visible? More...

UserDefinedObjectmUserObject
 User defined object which is linked to this object. More...

RenderQueueGroupID mRenderQueueID
 The render queue to use when rendering this object. More...


Private Types

typedef std::vector< SubEntity * > SubEntityList
 List of SubEntities (point to SubMeshes). More...

typedef std::vector< SubEntityList * > LODSubEntityList
 List of SubEntity lists (for manual LODs). More...


Private Methods

 Entity ()
 Private constructor (instances cannot be created directly). More...

 Entity (const String &name, Mesh *mesh, SceneManager *creator)
 Private constructor - specify name (the usual constructor used). More...

void cacheBoneMatrices (void)
 Private method to cache bone matrices from skeleton. More...

void buildSubEntityList (Mesh *mesh, SubEntityList *sublist)
 Builds a list of SubEntities based on the SubMeshes contained in the Mesh. More...


Private Attributes

String mName
 Name of the entity; used for location in the scene. More...

MeshmMesh
 The Mesh that this Entity is based on. More...

SubEntityList mSubEntityList
SceneManagermCreatorSceneManager
 Pointer back to the SceneManager that created this instance, for notification purposes. More...

AnimationStateSet mAnimationState
 State of animation for animable meshes. More...

Matrix4mBoneMatrices
 Cached bone matrices, including any world transform. More...

unsigned short mNumBoneMatrices
bool mDisplaySkeleton
 Flag determines whether or not to display skeleton. More...

ushort mMeshLodIndex
 The LOD number of the mesh to use, calculated by _notifyCurrentCamera. More...

Real mMeshLodFactorInv
 LOD bias factor, inverted for optimisation when calculating adjusted depth. More...

ushort mMinMeshLodIndex
 Index of minimum detail LOD (NB higher index is lower detail). More...

ushort mMaxMeshLodIndex
 Index of maximum detail LOD (NB lower index is higher detail). More...

bool mUsingManualLOD
 Flag indicating that mesh uses manual LOD and so might have multiple SubEntity versions. More...

LODSubEntityList mLodSubEntityList

Static Private Attributes

String msMovableType = "Entity"
 Shared class-level name for Movable type. More...


Friends

class SceneManager
class SubEntity

Detailed Description

Defines an instance of a discrete, movable object based on a Mesh.

Remarks:
Ogre generally divides renderable objects into 2 groups, discrete (separate) and relatively small objects which move around the world, and large, sprawling geometry which makes up generally immovable scenery, aka 'level geometry'.

The Mesh and SubMesh classes deal with the definition of the geometry used by discrete movable objects. Entities are actual instances of objects based on this geometry in the world. Therefore there is usually a single set Mesh for a car, but there may be multiple entities based on it in the world. Entities are able to override aspects of the Mesh it is defined by, such as changing material properties per instance (so you can have many cars using the same geometry but different textures for example). Because a Mesh is split into SubMeshes for this purpose, the Entity class is a grouping class (much like the Mesh class) and much of the detail regarding individual changes is kept in the SubEntity class. There is a 1:1 relationship between SubEntity instances and the SubMesh instances associated with the Mesh the Entity is based on.

Entity and SubEntity classes are never created directly. Use the createEntity method of the SceneManager (passing a model name) to create one.

Entities are included in the scene by associating them with a SceneNode, using the attachEntity method. See the SceneNode class for full information.

Note:
No functions were declared virtual to improve performance.


Member Typedef Documentation

typedef std::vector<SubEntityList*> Ogre::Entity::LODSubEntityList [private]
 

List of SubEntity lists (for manual LODs).

We don't know when the mesh is using manual LODs whether one LOD to the next will have the same number of SubMeshes, therefore we have to allow a SubEntity list with each alternate one.

typedef std::vector<SubEntity*> Ogre::Entity::SubEntityList [private]
 

List of SubEntities (point to SubMeshes).


Constructor & Destructor Documentation

Ogre::Entity::Entity   [private]
 

Private constructor (instances cannot be created directly).

Ogre::Entity::Entity const String   name,
Mesh   mesh,
SceneManager   creator
[private]
 

Private constructor - specify name (the usual constructor used).

Ogre::Entity::~Entity  
 

Default destructor.


Member Function Documentation

void Ogre::MovableObject::_notifyAttached SceneNode   parent [virtual, inherited]
 

Internal method called to notify the object that it has been attached to a node.

Reimplemented in Ogre::SimpleRenderable.

void Ogre::Entity::_notifyCurrentCamera Camera   cam [virtual]
 

Overridden - see MovableObject.

Implements Ogre::MovableObject.

void Ogre::Entity::_updateRenderQueue RenderQueue   queue [virtual]
 

Overridden - see MovableObject.

Implements Ogre::MovableObject.

void Ogre::Entity::buildSubEntityList Mesh   mesh,
SubEntityList   sublist
[private]
 

Builds a list of SubEntities based on the SubMeshes contained in the Mesh.

void Ogre::Entity::cacheBoneMatrices void    [private]
 

Private method to cache bone matrices from skeleton.

Entity * Ogre::Entity::clone const String   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.

AnimationStateSet * Ogre::Entity::getAllAnimationStates void   
 

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

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.

AnimationState * Ogre::Entity::getAnimationState const String   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.

const AxisAlignedBox & Ogre::Entity::getBoundingBox void    const [virtual]
 

Overridden - see MovableObject.

Implements Ogre::MovableObject.

Mesh * Ogre::Entity::getMesh void   
 

Gets the Mesh that this Entity is based on.

const String Ogre::Entity::getMovableType void    const [virtual]
 

Overridden from MovableObject.

Implements Ogre::MovableObject.

const String & Ogre::Entity::getName void    const [virtual]
 

Overridden from MovableObject.

Implements Ogre::MovableObject.

unsigned int Ogre::Entity::getNumSubEntities void   
 

Retrieves the number of SubEntity objects making up this entity.

SceneNode * Ogre::MovableObject::getParentNode void    [virtual, inherited]
 

Returns the node to which this object is attached.

Remarks:
An object is not visible in the scene unless attached to a SceneNode.

Attaching an object is done via the SceneNode::attachObject method.

Reimplemented in Ogre::SimpleRenderable.

RenderQueueGroupID Ogre::MovableObject::getRenderQueueGroup void    [virtual, inherited]
 

Gets the queue group for this entity, see setRenderQueueGroup for full details.

SubEntity * Ogre::Entity::getSubEntity unsigned int    index
 

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

virtual UserDefinedObject* Ogre::MovableObject::getUserObject void    [inline, virtual, inherited]
 

Retrieves a pointer to a custom application object associated with this movable by an earlier call to setUserObject.

bool Ogre::MovableObject::isAttached void    const [virtual, inherited]
 

Returns true if this object is attached to a SceneNode.

bool Ogre::MovableObject::isVisible void    const [virtual, inherited]
 

Returns whether or not this object is supposed to be visible or not.

void Ogre::Entity::setDisplaySkeleton bool    display
 

Tells the Entity whether or not it should display it's skeleton, if it has one.

void Ogre::Entity::setLodBias Real    factor = 1.0,
ushort    maxDetailIndex = 0,
ushort    minDetailIndex = 99
 

Sets a level-of-detail bias on 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 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 Ogre::Entity::setMaterialName const String   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.

void Ogre::Entity::setRenderDetail SceneDetailLevel    renderDetail
 

Sets the rendering detail of this entire entity (solid, wireframe etc).

void Ogre::MovableObject::setRenderQueueGroup RenderQueueGroupID    queueID [virtual, inherited]
 

Sets the render queue group this entity will be rendered through.

Remarks:
Render queues are grouped to allow you to more tightly control the ordering of rendered objects. If you do not call this method, all Entity objects default to RENDER_QUEUE_MAIN which is fine for most objects. You may want to alter this if you want this entity to always appear in front of other objects, e.g. for a 3D menu system or such.

See RenderQueue for more details.

Parameters:
queueID  Enumerated value of the queue group to use.

virtual void Ogre::MovableObject::setUserObject UserDefinedObject   obj [inline, virtual, inherited]
 

Call this to associate your own custom user object instance with this MovableObject.

Remarks:
By simply making your game / application object a subclass of UserDefinedObject, you can establish a link between an OGRE instance of MovableObject and your own application classes. Call this method to establish the link.

void Ogre::MovableObject::setVisible bool    visible [virtual, inherited]
 

Tells this object whether to be visible or not, if it has a renderable component.

Reimplemented in Ogre::Light.


Friends And Related Function Documentation

friend class SceneManager [friend]
 

friend class SubEntity [friend]
 


Member Data Documentation

AnimationStateSet Ogre::Entity::mAnimationState [private]
 

State of animation for animable meshes.

Matrix4* Ogre::Entity::mBoneMatrices [private]
 

Cached bone matrices, including any world transform.

SceneManager* Ogre::Entity::mCreatorSceneManager [private]
 

Pointer back to the SceneManager that created this instance, for notification purposes.

bool Ogre::Entity::mDisplaySkeleton [private]
 

Flag determines whether or not to display skeleton.

LODSubEntityList Ogre::Entity::mLodSubEntityList [private]
 

ushort Ogre::Entity::mMaxMeshLodIndex [private]
 

Index of maximum detail LOD (NB lower index is higher detail).

Mesh* Ogre::Entity::mMesh [private]
 

The Mesh that this Entity is based on.

Real Ogre::Entity::mMeshLodFactorInv [private]
 

LOD bias factor, inverted for optimisation when calculating adjusted depth.

ushort Ogre::Entity::mMeshLodIndex [private]
 

The LOD number of the mesh to use, calculated by _notifyCurrentCamera.

ushort Ogre::Entity::mMinMeshLodIndex [private]
 

Index of minimum detail LOD (NB higher index is lower detail).

String Ogre::Entity::mName [private]
 

Name of the entity; used for location in the scene.

unsigned short Ogre::Entity::mNumBoneMatrices [private]
 

SceneNode* Ogre::MovableObject::mParentNode [protected, inherited]
 

node to which this object is attached.

RenderQueueGroupID Ogre::MovableObject::mRenderQueueID [protected, inherited]
 

The render queue to use when rendering this object.

String Ogre::Entity::msMovableType = "Entity" [static, private]
 

Shared class-level name for Movable type.

SubEntityList Ogre::Entity::mSubEntityList [private]
 

UserDefinedObject* Ogre::MovableObject::mUserObject [protected, inherited]
 

User defined object which is linked to this object.

bool Ogre::Entity::mUsingManualLOD [private]
 

Flag indicating that mesh uses manual LOD and so might have multiple SubEntity versions.

bool Ogre::MovableObject::mVisible [protected, inherited]
 

Is this object visible?

Copyright © 2002 by The OGRE Team