Ogre::RibbonTrail Class Reference

Subclass of BillboardChain which automatically leaves a trail behind one or more Node instances. More...

#include <OgreRibbonTrail.h>

Inheritance diagram for Ogre::RibbonTrail:

List of all members.

Public Types

typedef std::vector
< Node * > NodeList

typedef
ConstVectorIterator
< NodeList > NodeIterator

enum TexCoordDirection { TCD_U, TCD_V }

The direction in which texture coordinates from elements of the chain are used. More...

typedef std::vector
< Element > ElementList

typedef std::vector
< ShadowRenderable * > ShadowRenderableList

typedef
VectorIterator
< ShadowRenderableList > ShadowRenderableListIterator

Public Member Functions

RibbonTrail (const String &name, size_t maxElements=20, size_t numberOfChains=1, bool useTextureCoords=true, bool useColours=true)

Constructor (don't use directly, use factory).

virtual ~RibbonTrail ()

destructor

virtual void addNode (Node *n)

Add a node to be tracked.

virtual void removeNode (Node *n)

Remove tracking on a given node.

virtual NodeIterator getNodeIterator (void) const

Get an iterator over the nodes which are being tracked.

virtual size_t getChainIndexForNode (const Node *n)

Get the chain index for a given Node being tracked.

virtual void setTrailLength (Real len)

Set the length of the trail.

virtual Real getTrailLength (void) const

Get the length of the trail.

void setMaxChainElements (size_t maxElements)

Set the maximum number of chain elements per chain.

void setNumberOfChains (size_t numChains)

Set the number of chain segments (this class can render multiple chains at once using the same material).

void clearChain (size_t chainIndex)

Remove all elements of a given chain (but leave the chain intact).

virtual void setInitialColour (size_t chainIndex, const ColourValue &col)

Set the starting ribbon colour for a given segment.

virtual void setInitialColour (size_t chainIndex, Real r, Real g, Real b, Real a=1.0)

Set the starting ribbon colour.

virtual const
ColourValue & getInitialColour (size_t chainIndex) const

Get the starting ribbon colour.

virtual void setColourChange (size_t chainIndex, const ColourValue &valuePerSecond)

Enables / disables fading the trail using colour.

virtual void setInitialWidth (size_t chainIndex, Real width)

Set the starting ribbon width in world units.

virtual Real getInitialWidth (size_t chainIndex) const

Get the starting ribbon width in world units.

virtual void setWidthChange (size_t chainIndex, Real widthDeltaPerSecond)

Set the change in ribbon width per second.

virtual Real getWidthChange (size_t chainIndex) const

Get the change in ribbon width per second.

virtual void setColourChange (size_t chainIndex, Real r, Real g, Real b, Real a)

Enables / disables fading the trail using colour.

virtual const
ColourValue & getColourChange (size_t chainIndex) const

Get the per-second fading amount.

void nodeUpdated (const Node *node)

See also:
Node::Listener::nodeUpdated

void nodeDestroyed (const Node *node)

See also:
Node::Listener::nodeDestroyed

virtual void _timeUpdate (Real time)

Perform any fading / width delta required; internal method.

const String & getMovableType (void) const

Overridden from MovableObject.

virtual size_t getMaxChainElements (void) const

Get the maximum number of chain elements per chain.

virtual size_t getNumberOfChains (void) const

Get the number of chain segments (this class can render multiple chains at once using the same material).

virtual void setUseTextureCoords (bool use)

Sets whether texture coordinate information should be included in the final buffers generated.

virtual bool getUseTextureCoords (void) const

Gets whether texture coordinate information should be included in the final buffers generated.

virtual void setTextureCoordDirection (TexCoordDirection dir)

Sets the direction in which texture coords specified on each element are deemed to run along the length of the chain.

virtual TexCoordDirection getTextureCoordDirection (void)

Gets the direction in which texture coords specified on each element are deemed to run.

virtual void setOtherTextureCoordRange (Real start, Real end)

Set the range of the texture coordinates generated across the width of the chain elements.

virtual const Real * getOtherTextureCoordRange (void) const

Get the range of the texture coordinates generated across the width of the chain elements.

virtual void setUseVertexColours (bool use)

Sets whether vertex colour information should be included in the final buffers generated.

virtual bool getUseVertexColours (void) const

Gets whether vertex colour information should be included in the final buffers generated.

virtual void setDynamic (bool dyn)

Sets whether or not the buffers created for this object are suitable for dynamic alteration.

virtual bool getDynamic (void) const

Gets whether or not the buffers created for this object are suitable for dynamic alteration.

virtual void addChainElement (size_t chainIndex, const Element &billboardChainElement)

Add an element to the 'head' of a chain.

virtual void removeChainElement (size_t chainIndex)

Remove an element from the 'tail' of a chain.

virtual void updateChainElement (size_t chainIndex, size_t elementIndex, const Element &billboardChainElement)

Update the details of an existing chain element.

virtual const Element & getChainElement (size_t chainIndex, size_t elementIndex) const

Get the detail of a chain element.

virtual size_t getNumChainElements (size_t chainIndex) const

Returns the number of chain elements.

virtual void clearAllChains (void)

Remove all elements from all chains (but leave the chains themselves intact).

virtual const String & getMaterialName (void) const

Get the material name in use.

virtual void setMaterialName (const String &name)

Set the material name to use for rendering.

void _notifyCurrentCamera (Camera *cam)

Internal method to notify the object of the camera to be used for the next rendering operation.

Real getSquaredViewDepth (const Camera *cam) const

Returns the camera-relative squared depth of this renderable.

Real getBoundingRadius (void) const

Retrieves the radius of the origin-centered bounding sphere for this object.

const AxisAlignedBox & getBoundingBox (void) const

Retrieves the local axis-aligned bounding box for this object.

const MaterialPtr & getMaterial (void) const

Retrieves a weak reference to the material this renderable object uses.

void _updateRenderQueue (RenderQueue *)

Internal method by which the movable object must add Renderable subclass instances to the rendering queue.

void getRenderOperation (RenderOperation &)

Gets the render operation required to send this object to the frame buffer.

void getWorldTransforms (Matrix4 *) const

Gets the world transform matrix / matrices for this renderable object.

const LightList & getLights (void) const

Gets a list of lights, ordered relative to how close they are to this renderable.

void visitRenderables (Renderable::Visitor *visitor, bool debugRenderables=false)

Method to allow a caller to abstractly iterate over the Renderable instances that this MovableObject will add to the render queue when asked, if any.

Parameters:

visitor Pointer to a class implementing the Renderable::Visitor interface which will be called back for each Renderable which will be queued. Bear in mind that the state of the Renderable instances may not be finalised depending on when you call this.

debugRenderables If false, only regular renderables will be visited (those for normal display). If true, debug renderables will be included too.

virtual void _notifyCreator (MovableObjectFactory *fact)

Notify the object of it's creator (internal use only).

virtual
MovableObjectFactory * _getCreator (void) const

Get the creator of this object, if any (internal use only).

virtual void _notifyManager (SceneManager *man)

Notify the object of it's manager (internal use only).

virtual SceneManager * _getManager (void) const

Get the manager of this object, if any (internal use only).

virtual const String & getName (void) const

Returns the name of this object.

virtual Node * getParentNode (void) const

Returns the node to which this object is attached.

virtual SceneNode * getParentSceneNode (void) const

Returns the scene node to which this object is attached.

virtual void _notifyAttached (Node *parent, bool isTagPoint=false)

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

virtual bool isAttached (void) const

Returns true if this object is attached to a SceneNode or TagPoint.

virtual void detatchFromParent (void)

Detaches an object from a parent SceneNode or TagPoint, if attached.

virtual bool isInScene (void) const

Returns true if this object is attached to a SceneNode or TagPoint, and this SceneNode / TagPoint is currently in an active part of the scene graph.

virtual void _notifyMoved (void)

Internal method called to notify the object that it has been moved.

virtual const
AxisAlignedBox & getWorldBoundingBox (bool derive=false) const

Retrieves the axis-aligned bounding box for this object in world coordinates.

virtual const Sphere & getWorldBoundingSphere (bool derive=false) const

Retrieves the worldspace bounding sphere for this object.

virtual void setVisible (bool visible)

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

virtual bool getVisible (void) const

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

virtual bool isVisible (void) const

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

virtual void setRenderingDistance (Real dist)

Sets the distance at which the object is no longer rendered.

virtual Real getRenderingDistance (void) const

Gets the distance at which batches are no longer rendered.

virtual void setUserObject (UserDefinedObject *obj)

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

virtual
UserDefinedObject * getUserObject (void)

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

virtual void setUserAny (const Any &anything)

Sets any kind of user value on this object.

virtual void setUserAny (const Any &anything)

Sets any kind of user value on this object.

virtual const Any & getUserAny (void) const

Retrieves the custom user value associated with this object.

virtual const Any & getUserAny (void) const

Retrieves the custom user value associated with this object.

virtual void setRenderQueueGroup (uint8 queueID)

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

virtual uint8 getRenderQueueGroup (void) const

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

virtual const Matrix4 & _getParentNodeFullTransform (void) const

return the full transformation of the parent sceneNode or the attachingPoint node

virtual void setQueryFlags (uint32 flags)

Sets the query flags for this object.

virtual void addQueryFlags (uint32 flags)

As setQueryFlags, except the flags passed as parameters are appended to the existing flags on this object.

virtual void removeQueryFlags (unsigned long flags)

As setQueryFlags, except the flags passed as parameters are removed from the existing flags on this object.

virtual uint32 getQueryFlags (void) const

Returns the query flags relevant for this object.

virtual void setVisibilityFlags (uint32 flags)

Sets the visiblity flags for this object.

virtual void addVisibilityFlags (uint32 flags)

As setVisibilityFlags, except the flags passed as parameters are appended to the existing flags on this object.

virtual void removeVisibilityFlags (uint32 flags)

As setVisibilityFlags, except the flags passed as parameters are removed from the existing flags on this object.

virtual uint32 getVisibilityFlags (void) const

Returns the visibility flags relevant for this object.

virtual void setListener (Listener *listener)

Sets a listener for this object.

virtual Listener * getListener (void) const

Gets the current listener for this object.

virtual const LightList & queryLights (void) const

Gets a list of lights, ordered relative to how close they are to this movable object.

virtual LightList * _getLightList ()

Returns a pointer to the current list of lights for this object.

EdgeData * getEdgeList (void)

Define a default implementation of method from ShadowCaster which implements no shadows.

bool hasEdgeList (void)

Define a default implementation of method from ShadowCaster which implements no shadows.

ShadowRenderableListIterator getShadowVolumeRenderableIterator (ShadowTechnique shadowTechnique, const Light *light, HardwareIndexBufferSharedPtr *indexBuffer, bool extrudeVertices, Real extrusionDist, unsigned long flags=0)

Define a default implementation of method from ShadowCaster which implements no shadows.

const AxisAlignedBox & getLightCapBounds (void) const

Overridden member from ShadowCaster.

const AxisAlignedBox & getDarkCapBounds (const Light &light, Real dirLightExtrusionDist) const

Overridden member from ShadowCaster.

void setCastShadows (bool enabled)

Sets whether or not this object will cast shadows.

bool getCastShadows (void) const

Returns whether shadow casting is enabled for this object.

Real getPointExtrusionDistance (const Light *l) const

Get the distance to extrude for a point/spot light.

virtual uint32 getTypeFlags (void) const

Get the 'type flags' for this MovableObject.

virtual void setDebugDisplayEnabled (bool enabled)

Sets whether or not the debug display of this object is enabled.

virtual bool isDebugDisplayEnabled (void) const

Gets whether debug display of this object is enabled.

const StringVector & getAnimableValueNames (void) const

Gets a list of animable value names for this object.

virtual AnimableValuePtr createAnimableValue (const String &valueName)

Create a reference-counted AnimableValuePtr for the named value.

void * operator new (size_t sz, const char *file, int line, const char *func)

operator new, with debug line info

void * operator new (size_t sz)

void * operator new (size_t sz, void *ptr)

placement operator new

void * operator new[] (size_t sz, const char *file, int line, const char *func)

array operator new, with debug line info

void * operator new[] (size_t sz)

void operator delete (void *ptr)

void operator delete (void *ptr, const char *, int, const char *)

void operator delete[] (void *ptr)

void operator delete[] (void *ptr, const char *, int, const char *)

virtual Technique * getTechnique (void) const

Retrieves a pointer to the Material Technique this renderable object uses.

virtual bool preRender (SceneManager *sm, RenderSystem *rsys)

Called just prior to the Renderable being rendered.

virtual void postRender (SceneManager *sm, RenderSystem *rsys)

Called immediately after the Renderable has been rendered.

virtual unsigned short getNumWorldTransforms (void) const

Returns the number of world transform matrices this renderable requires.

void setUseIdentityProjection (bool useIdentityProjection)

Sets whether or not to use an 'identity' projection.

bool getUseIdentityProjection (void) const

Returns whether or not to use an 'identity' projection.

void setUseIdentityView (bool useIdentityView)

Sets whether or not to use an 'identity' view.

bool getUseIdentityView (void) const

Returns whether or not to use an 'identity' view.

virtual bool getCastsShadows (void) const

Method which reports whether this renderable would normally cast a shadow.

void setCustomParameter (size_t index, const Vector4 &value)

Sets a custom parameter for this Renderable, which may be used to drive calculations for this specific Renderable, like GPU program parameters.

const Vector4 & getCustomParameter (size_t index) const

Gets the custom value associated with this Renderable at the given index.

virtual void _updateCustomGpuParameter (const GpuProgramParameters::AutoConstantEntry &constantEntry, GpuProgramParameters *params) const

Update a custom GpuProgramParameters constant which is derived from information only this Renderable knows.

virtual void setPolygonModeOverrideable (bool override)

Sets whether this renderable's chosen detail level can be overridden (downgraded) by the camera setting.

virtual bool getPolygonModeOverrideable (void) const

Gets whether this renderable's chosen detail level can be overridden (downgraded) by the camera setting.

virtual
RenderSystemData * getRenderSystemData () const

Sets render system private data.

virtual void setRenderSystemData (RenderSystemData *val) const

gets render system private data

virtual void objectDestroyed (MovableObject *)

MovableObject is being destroyed.

virtual void objectAttached (MovableObject *)

MovableObject has been attached to a node.

virtual void objectDetached (MovableObject *)

MovableObject has been detached from a node.

virtual void objectMoved (MovableObject *)

MovableObject has been moved.

virtual bool objectRendering (const MovableObject *, const Camera *)

Called when the movable object of the camera to be used for rendering.

virtual const LightList * objectQueryLights (const MovableObject *)

Called when the movable object needs to query a light list.

Static Public Member Functions

static void setDefaultQueryFlags (uint32 flags)

Set the default query flags for all future MovableObject instances.

static uint32 getDefaultQueryFlags ()

Get the default query flags for all future MovableObject instances.

static void setDefaultVisibilityFlags (uint32 flags)

Set the default visibility flags for all future MovableObject instances.

static uint32 getDefaultVisibilityFlags ()

Get the default visibility flags for all future MovableObject instances.

static void extrudeVertices (const HardwareVertexBufferSharedPtr &vertexBuffer, size_t originalVertexCount, const Vector4 &lightPos, Real extrudeDist)

Utility method for extruding vertices based on a light.

Protected Types

typedef std::vector
< size_t > IndexVector

Mapping of nodes to chain segments.

typedef std::map
< const Node *,
size_t > NodeToChainSegmentMap

typedef std::vector
< ColourValue > ColourValueList

typedef std::vector
< Real > RealList

typedef std::vector
< ChainSegment > ChainSegmentList

typedef std::map
< String,
StringVector > AnimableDictionaryMap

typedef std::map
< size_t, Vector4 > CustomParameterMap

Protected Member Functions

virtual void manageController (void)

Manage updates to the time controller.

virtual void updateTrail (size_t index, const Node *node)

Node has changed position, update.

virtual void resetTrail (size_t index, const Node *node)

Reset the tracked chain to initial state.

virtual void resetAllTrails (void)

Reset all tracked chains to initial state.

virtual void setupChainContainers (void)

Setup the STL collections.

virtual void setupVertexDeclaration (void)

Setup vertex declaration.

virtual void setupBuffers (void)

virtual void updateVertexBuffer (Camera *cam)

Update the contents of the vertex buffer.

virtual void updateIndexBuffer (void)

Update the contents of the index buffer.

virtual void updateBoundingBox (void) const

Real getExtrusionDistance (const Vector3 &objectPos, const Light *light) const

Helper method for calculating extrusion distance.

virtual void updateEdgeListLightFacing (EdgeData *edgeData, const Vector4 &lightPos)

Tells the caster to perform the tasks necessary to update the edge data's light listing.

virtual void generateShadowVolume (EdgeData *edgeData, const HardwareIndexBufferSharedPtr &indexBuffer, const Light *light, ShadowRenderableList &shadowRenderables, unsigned long flags)

Generates the indexes required to render a shadow volume into the index buffer which is passed in, and updates shadow renderables to use it.

virtual void extrudeBounds (AxisAlignedBox &box, const Vector4 &lightPos, Real extrudeDist) const

Utility method for extruding a bounding box.

virtual const String & getAnimableDictionaryName (void) const

Get the name of the animable dictionary for this class.

void createAnimableDictionary (void) const

Internal method for creating a dictionary of animable value names for the class, if it does not already exist.

StringVector & _getAnimableValueNames (void)

Get an updateable reference to animable value list.

virtual void initialiseAnimableDictionary (StringVector &) const

Internal method for initialising dictionary; should be implemented by subclasses wanting to expose animable parameters.

Protected Attributes

NodeList mNodeList

List of nodes being trailed.

IndexVector mNodeToChainSegment

Ordered like mNodeList, contains chain index.

IndexVector mFreeChains

NodeToChainSegmentMap mNodeToSegMap

Real mTrailLength

Total length of trail in world units.

Real mElemLength

length of each element

Real mSquaredElemLength

Squared length of each element.

ColourValueList mInitialColour

Initial colour of the ribbon.

ColourValueList mDeltaColour

fade amount per second

RealList mInitialWidth

Initial width of the ribbon.

RealList mDeltaWidth

Delta width of the ribbon.

Controller< Real > * mFadeController

controller used to hook up frame time to fader

ControllerValueRealPtr mTimeControllerValue

controller value for hooking up frame time to fader

size_t mMaxElementsPerChain

Maximum length of each chain.

size_t mChainCount

Number of chains.

bool mUseTexCoords

Use texture coords?

bool mUseVertexColour

Use vertex colour?

bool mDynamic

Dynamic use?

VertexData * mVertexData

Vertex data.

IndexData * mIndexData

Index data (to allow multiple unconnected chains).

bool mVertexDeclDirty

Is the vertex declaration dirty?

bool mBuffersNeedRecreating

Do the buffers need recreating?

bool mBoundsDirty

Do the bounds need redefining?

bool mIndexContentDirty

Is the index buffer dirty?

AxisAlignedBox mAABB

AABB.

Real mRadius

Bounding radius.

String mMaterialName

Material.

MaterialPtr mMaterial

TexCoordDirection mTexCoordDir

Texture coord direction.

Real mOtherTexCoordRange [2]

Other texture coord range.

ElementList mChainElementList

The list holding the chain elements.

ChainSegmentList mChainSegmentList

String mName

Name of this object.

MovableObjectFactory * mCreator

Creator of this object (if created by a factory).

SceneManager * mManager

SceneManager holding this object (if applicable).

Node * mParentNode

node to which this object is attached

bool mParentIsTagPoint

bool mVisible

Is this object visible?

bool mDebugDisplay

Is debug display enabled?

Real mUpperDistance

Upper distance to still render.

Real mSquaredUpperDistance

bool mBeyondFarDistance

Hidden because of distance?

Any mUserAny

User defined link to another object / value / whatever.

Any mUserAny

uint8 mRenderQueueID

The render queue to use when rendering this object.

bool mRenderQueueIDSet

Flags whether the RenderQueue's default should be used.

uint32 mQueryFlags

Flags determining whether this object is included / excluded from scene queries.

uint32 mVisibilityFlags

Flags determining whether this object is visible (compared to SceneManager mask).

AxisAlignedBox mWorldAABB

Cached world AABB of this object.

Sphere mWorldBoundingSphere

AxisAlignedBox mWorldDarkCapBounds

World space AABB of this object's dark cap.

bool mCastShadows

Does this object cast shadows?

bool mRenderingDisabled

Does rendering this object disabled by listener?

Listener * mListener

MovableObject listener - only one allowed (no list) for size & performance reasons. */.

LightList mLightList

List of lights for this object.

ulong mLightListUpdated

The last frame that this light list was updated in.

CustomParameterMap mCustomParameters

bool mPolygonModeOverrideable

bool mUseIdentityProjection

bool mUseIdentityView

RenderSystemData * mRenderSystemData

Static Protected Attributes

static const size_t SEGMENT_EMPTY

Chain segment has no elements.

static uint32 msDefaultQueryFlags

Default query flags.

static uint32 msDefaultVisibilityFlags

Default visibility flags.

static
AnimableDictionaryMap msAnimableDictionary

Static map of class name to list of animable value names.

Detailed Description

Subclass of BillboardChain which automatically leaves a trail behind one or more Node instances.

Remarks:: An instance of this class will watch one or more Node instances, and automatically generate a trail behind them as they move. Because this class can monitor multiple modes, it generates its own geometry in world space and thus, even though it has to be attached to a SceneNode to be visible, changing the position of the scene node it is attached to makes no difference to the geometry rendered.

: The 'head' element grows smoothly in size until it reaches the required size, then a new element is added. If the segment is full, the tail element shrinks by the same proportion as the head grows before disappearing.

: Elements can be faded out on a time basis, either by altering their colour or altering their alpha. The width can also alter over time.

: 'v' texture coordinates are fixed at 0.0 if used, meaning that you can use a 1D texture to 'smear' a colour pattern along the ribbon if you wish. The 'u' coordinates are by default (0.0, 1.0), but you can alter this using setOtherTexCoordRange if you wish.

Definition at line 65 of file OgreRibbonTrail.h.

Member Typedef Documentation

typedef std::vector<Node*> Ogre::RibbonTrail::NodeList

Definition at line 82 of file OgreRibbonTrail.h.

typedef ConstVectorIterator<NodeList> Ogre::RibbonTrail::NodeIterator

Definition at line 83 of file OgreRibbonTrail.h.

typedef std::vector<size_t> Ogre::RibbonTrail::IndexVector [protected]

Mapping of nodes to chain segments.

Definition at line 176 of file OgreRibbonTrail.h.

typedef std::map<const Node*, size_t> Ogre::RibbonTrail::NodeToChainSegmentMap [protected]

Definition at line 184 of file OgreRibbonTrail.h.

typedef std::vector<ColourValue> Ogre::RibbonTrail::ColourValueList [protected]

Definition at line 193 of file OgreRibbonTrail.h.