TSShapeInstance
Engine/source/ts/tsShapeInstance.h
An instance of a 3space shape.
Classes:
These are set up by default based on shape data.
Base class for all renderable objects, including mesh objects and decal objects.
Reference Transform Vectors
unused until first transition
Workspace for Node Transforms
Threads
keep track of who controls what on currently animating shape
Ground Transform Data
Transition nodes
keep track of nodes that are involved in a transition
note:this only tracks nodes we're transitioning from... nodes we're transitioning to are implicitly handled (i.e., we don't need to keep track of them)
Node Masking
set node masking...
setNodeAnimationState(S32 nodeIndex, U32 animationState, TSCallback * callback)
getNodeAnimationState(S32 nodeIndex)
Trigger states
check trigger value
bool
getTriggerState(U32 stateNum, bool clearState)
setTriggerState(U32 stateNum, bool on)
setTriggerStateBit(U32 stateBit, bool on)
Debris Management
AlphaAlways
AlphaAlways allows the entire model to become translucent at the same value
Public User Defined
renderDebugNormals(F32 normalScalar, S32 dl)
Debugging.
Render all node transforms as small axis gizmos.
listMeshes(const String & state)
Print mesh data to the console, valid String parameters are Visible, Hidden, or All.
Animation Scale
Query about animated scale
bool
bool
bool
bool
bool
Ground Transforms
The animator of a model can make the bounding box animate along with the object.
Doing so will move the object with the bounding box. The ground transform turns the world bounding box into the post-animation bounding box when such a technique is used. However, few models actually use this technique.
clears previous ground transform
Thread Control
Threads! In order to animate an object, first you need to have an animation in the object.
Then, you need to get the TSShape of the object:
TSShape* shape = mShapeInstance->getShape());Next, get the sequence and store::
S32 seq = shape->findSequence("foo"));Create a new thread (if needed):
TSThread* thread = mShapeInstance->addThread();Finally, set the position in the sequence:
mShapeInstance->setSequence(thread, seq, 0)
destroyThread(TSThread * thread)
Destroy a thread!
How many threads are there?
setSequence(TSThread * , S32 seq, F32 pos)
Get the thread a sequence.
transitionToSequence(TSThread * , S32 seq, F32 pos, F32 duration, bool continuePlay)
Transition to a sequence.
Stop transitions.
getSequence(TSThread * )
Get the sequence of the thread.
setBlendEnabled(TSThread * , bool blendOn)
Set whether or not the thread will blend.
bool
Does this thread blend?
setPriority(TSThread * , F32 priority)
Set thread priority.
getPriority(TSThread * thread)
Get thread priority.
bool
isInTransition(TSThread * thread)
Is this thread in transition?
getTimeScale(TSThread * thread)
Get the time scale of the thread.
setTimeScale(TSThread * thread, F32 )
Set the time scale of the thread.
getDuration(TSThread * thread)
Get the duration of the thread.
getScaledDuration(TSThread * thread)
Get the duration of the thread with the scale factored in.
getKeyframeCount(TSThread * thread)
Get the number of keyframes.
getKeyframeNumber(TSThread * thread)
Get which keyframe the thread is on.
setKeyframeNumber(TSThread * thread, S32 kf)
Set which keyframe the thread is on.
advanceTime(F32 delta, TSThread * )
advance time on a particular thread
advanceTime(F32 delta)
advance time on all threads
advancePos(F32 delta, TSThread * )
advance pos on a particular thread
advancePos(F32 delta)
advance pos on all threads
Private animation methods
These are private methods for setting up and affecting animation
handleDefaultScale(S32 a, S32 b, TSIntegerSet & scaleBeenSet)
updateTransitionNodeTransforms(TSIntegerSet & transitionNodes)
handleTransitionNodes(S32 a, S32 b)
handleNodeScale(S32 a, S32 b)
handleAnimatedScale(TSThread * , S32 a, S32 b, TSIntegerSet & )
handleMaskedPositionNode(TSThread * , S32 nodeIndex, S32 offset)
handleBlendSequence(TSThread * , S32 a, S32 b)
Public Types
_Anonymous_ { MaskNodeRotation = 0x01 MaskNodePosX = 0x02 MaskNodePosY = 0x04 MaskNodePosZ = 0x08 MaskNodeBlend = 0x10 MaskNodeAll = MaskNodeRotation|MaskNodePosX|MaskNodePosY|MaskNodePosZ|MaskNodeBlend MaskNodeAllButBlend = MaskNodeRotation|MaskNodePosX|MaskNodePosY|MaskNodePosZ MaskNodeAllButRotation = MaskNodePosX|MaskNodePosY|MaskNodePosZ|MaskNodeBlend MaskNodeAllButPosX = MaskNodeRotation|MaskNodePosY|MaskNodePosZ|MaskNodeBlend MaskNodeAllButPosY = MaskNodeRotation|MaskNodePosX|MaskNodePosZ|MaskNodeBlend MaskNodeAllButPosZ = MaskNodeRotation|MaskNodePosX|MaskNodePosY|MaskNodeBlend MaskNodeHandsOff = 0x20 MaskNodeCallback = 0x40 }
_Anonymous_ { TransformDirty = BIT(0) VisDirty = BIT(1) FrameDirty = BIT(2) MatFrameDirty = BIT(3) ThreadDirty = BIT(4) AllDirtyMask = TransformDirty | VisDirty | FrameDirty | MatFrameDirty | ThreadDirty }
Public Friends
Public Attributes
by default, points to hShape material list
storage space for node transforms
Public Static Attributes
Scale pixel size by this amount when selecting detail levels.
For debugging / metrics.
never choose detail level number below this value (except if only way to get a visible detail)
If this is set to a positive pixel value shapes with a smaller pixel size than this will skip rendering entirely.
Protected Attributes
bool
0-1, how far along from current to next (higher) detail level...
Nodes that aren't animated through threads automatically.
keep track of nodes with animation restrictions put on them
bool
Does this own the material list pointer?
TSShape *
This should always point to a valid shape and should equal mShapeResource if it was created from a resource.
This is only valid when the instance was created from a resource.
Vertex buffer used for software skinning this instance.
state variables
bool
bool
Force using our own copy of the vertex buffer.
Public Functions
TSShapeInstance(const Resource< TSShape > & shape, bool loadMaterials)
TSShapeInstance(TSShape * pShape, bool loadMaterials)
animateFrame(S32 ss)
animateMatFrame(S32 ss)
animateNodes(S32 ss)
animateNodeSubtrees(bool forceFull)
animateSubtrees(bool forceFull)
animateVisibility(S32 ss)
bool
bufferNeedsUpdate(S32 objectDetail, S32 start, S32 end)
bool
buildInstanceData(TSShape * , bool loadMaterials)
bool
buildPolyList(AbstractPolyList * , S32 dl)
bool
buildPolyListOpcode(S32 dl, AbstractPolyList * polyList, const Box3F & box)
clearDirty(U32 dirty)
cloneMaterialList(const FeatureSet * features)
Call this to own the material list – i.e., we'll make a copy of the currently set material list and be responsible for deleting it.
computeBounds(S32 dl, Box3F & bounds)
uses current transforms to compute bounding box around a detail level see like named method on shape if you want to use default transforms
bool
getFeatures(const MatrixF & mat, const Point3F & n, ConvexFeature * , S32 dl)
Get the number of material targets in this shape instance.
getTargetName(S32 mapToNameIndex)
Get the indexed material target (may differ from the base TSShape material list if this instance has been reskinned).
bool
initMaterialList(const FeatureSet * features)
Initializes or re-initializes the material list with an optional feature set.
bool
bool
render(const TSRenderState & rdata)
setCurrentDetail(S32 dl, F32 intraDL)
setDetailFromDistance(const SceneRenderState * state, F32 scaledDist)
Selects the current detail level using the scaled distance between your object and the camera.
setDetailFromPosAndScale(const SceneRenderState * state, const Point3F & pos, const Point3F & scale)
Helper function which internally calls setDetailFromDistance.
setDetailFromScreenError(F32 errorTOL)
Sets the current detail level using the legacy screen error metric.
setMaterialList(TSMaterialList * matList)
Set the material list without taking ownership.
setMeshForceHidden(const char * meshName, bool hidden)
Sets the 'forceHidden' state on the named mesh.
setMeshForceHidden(S32 meshIndex, bool hidden)
Sets the 'forceHidden' state on a mesh.
Detailed Description
An instance of a 3space shape.
Introduction
A 3space model represents a significant amount of data. There are multiple meshes, skeleton information, as well as animation data. Some of this, like the skeletal transforms, are unique for each instance of the model (as different instances are likely to be in different states of animation), while most of it, like texturing information and vertex data, is the same amongst all instances of the shape.
To keep this data from being replicated for every instance of a 3shape object, Torque uses the ResManager to instantiate and track TSShape objects. TSShape handles reading and writing 3space models, as well as keeping track of static model data, as discussed above. TSShapeInstance keeps track of all instance specific data, such as the currently playing sequences or the active node transforms.
TSShapeInstance contains all the functionality for 3space models, while TSShape acts as a repository for common data.
What Does TSShapeInstance Do?
TSShapeInstance handles several areas of functionality:
Rendering.
Animation.
Updating skeletal transforms.
Ballooning (see setShapeBalloon() and getShapeBalloon())
For an excellent example of how to render a TSShape in game, see TSStatic. For examples of how to procedurally animate models, look at Player::updateLookAnimation().
Reference Transform Vectors
unused until first transition
Vector< Quat16 > mNodeReferenceRotations
Vector< Point3F > mNodeReferenceTranslations
Vector< F32 > mNodeReferenceUniformScales
Vector< Point3F > mNodeReferenceScaleFactors
Vector< Quat16 > mNodeReferenceArbitraryScaleRots
Workspace for Node Transforms
Vector< QuatF > smNodeCurrentRotations
Vector< Point3F > smNodeCurrentTranslations
Vector< F32 > smNodeCurrentUniformScales
Vector< Point3F > smNodeCurrentAlignedScales
Vector< TSScale > smNodeCurrentArbitraryScales
Vector< MatrixF > smNodeLocalTransforms
TSIntegerSet smNodeLocalTransformDirty
Threads
keep track of who controls what on currently animating shape
Vector< TSThread * > smRotationThreads
Vector< TSThread * > smTranslationThreads
Vector< TSThread * > smScaleThreads
Ground Transform Data
MatrixF mGroundTransform
TSThread * mGroundThread
Transition nodes
keep track of nodes that are involved in a transition
note:this only tracks nodes we're transitioning from... nodes we're transitioning to are implicitly handled (i.e., we don't need to keep track of them)
TSIntegerSet mTransitionRotationNodes
TSIntegerSet mTransitionTranslationNodes
TSIntegerSet mTransitionScaleNodes
Node Masking
set node masking...
setNodeAnimationState(S32 nodeIndex, U32 animationState, TSCallback * callback)
getNodeAnimationState(S32 nodeIndex)
Trigger states
check trigger value
getTriggerState(U32 stateNum, bool clearState)
setTriggerState(U32 stateNum, bool on)
setTriggerStateBit(U32 stateBit, bool on)
Debris Management
incDebrisRefCount()
decDebrisRefCount()
getDebrisRefCount()
AlphaAlways
AlphaAlways allows the entire model to become translucent at the same value
setAlphaAlways(F32 value)
getAlphaAlwaysValue()
getAlphaAlways()
Public User Defined
renderDebugNormals(F32 normalScalar, S32 dl)
Debugging.
Renders the vertex normals assuming the GFX state is setup for rendering in model space.
renderDebugNodes()
Render all node transforms as small axis gizmos.
It is recommended that prior to calling this, shapeInstance::animate is called so that nodes are in object space and that the GFX state is setup for rendering in model space.
listMeshes(const String & state)
Print mesh data to the console, valid String parameters are Visible, Hidden, or All.
Animation Scale
Query about animated scale
animatesScale()
animatesUniformScale()
animatesAlignedScale()
animatesArbitraryScale()
scaleCurrentlyAnimated()
Ground Transforms
The animator of a model can make the bounding box animate along with the object.
Doing so will move the object with the bounding box. The ground transform turns the world bounding box into the post-animation bounding box when such a technique is used. However, few models actually use this technique.
animateGround()
clears previous ground transform
getGroundTransform()
deltaGround(TSThread * , F32 start, F32 end, MatrixF * mat)
deltaGround1(TSThread * , F32 start, F32 end, MatrixF & mat)
Thread Control
Threads! In order to animate an object, first you need to have an animation in the object.
Then, you need to get the TSShape of the object:
TSShape* shape = mShapeInstance->getShape());Next, get the sequence and store::
S32 seq = shape->findSequence("foo"));Create a new thread (if needed):
TSThread* thread = mShapeInstance->addThread();Finally, set the position in the sequence:
mShapeInstance->setSequence(thread, seq, 0)
addThread()
Create a new thread.
getThread(S32 threadNumber)
note:threads can change order, best to hold onto a thread from the start
destroyThread(TSThread * thread)
Destroy a thread!
threadCount()
How many threads are there?
setSequence(TSThread * , S32 seq, F32 pos)
Get the thread a sequence.
transitionToSequence(TSThread * , S32 seq, F32 pos, F32 duration, bool continuePlay)
Transition to a sequence.
clearTransition(TSThread * )
Stop transitions.
getSequence(TSThread * )
Get the sequence of the thread.
setBlendEnabled(TSThread * , bool blendOn)
Set whether or not the thread will blend.
getBlendEnabled(TSThread * )
Does this thread blend?
setPriority(TSThread * , F32 priority)
Set thread priority.
getPriority(TSThread * thread)
Get thread priority.
getTime(TSThread * thread)
Get how long the thread has been playing.
getPos(TSThread * thread)
Get the position in the thread.
setTime(TSThread * thread, F32 time)
Set how long into the thread to use.
setPos(TSThread * thread, F32 pos)
Set the position of the thread.
isInTransition(TSThread * thread)
Is this thread in transition?
getTimeScale(TSThread * thread)
Get the time scale of the thread.
setTimeScale(TSThread * thread, F32 )
Set the time scale of the thread.
getDuration(TSThread * thread)
Get the duration of the thread.
getScaledDuration(TSThread * thread)
Get the duration of the thread with the scale factored in.
getKeyframeCount(TSThread * thread)
Get the number of keyframes.
getKeyframeNumber(TSThread * thread)
Get which keyframe the thread is on.
setKeyframeNumber(TSThread * thread, S32 kf)
Set which keyframe the thread is on.
advanceTime(F32 delta, TSThread * )
advance time on a particular thread
advanceTime(F32 delta)
advance time on all threads
advancePos(F32 delta, TSThread * )
advance pos on a particular thread
advancePos(F32 delta)
advance pos on all threads
Private animation methods
These are private methods for setting up and affecting animation
sortThreads()
updateTransitions()
handleDefaultScale(S32 a, S32 b, TSIntegerSet & scaleBeenSet)
updateTransitionNodeTransforms(TSIntegerSet & transitionNodes)
handleTransitionNodes(S32 a, S32 b)
handleNodeScale(S32 a, S32 b)
handleAnimatedScale(TSThread * , S32 a, S32 b, TSIntegerSet & )
handleMaskedPositionNode(TSThread * , S32 nodeIndex, S32 offset)
handleBlendSequence(TSThread * , S32 a, S32 b)
checkScaleCurrentlyAnimated()
Public Types
@210
Enumerator
- MaskNodeRotation = 0x01
- MaskNodePosX = 0x02
- MaskNodePosY = 0x04
- MaskNodePosZ = 0x08
- MaskNodeBlend = 0x10
- MaskNodeAll = MaskNodeRotation|MaskNodePosX|MaskNodePosY|MaskNodePosZ|MaskNodeBlend
- MaskNodeAllButBlend = MaskNodeRotation|MaskNodePosX|MaskNodePosY|MaskNodePosZ
- MaskNodeAllButRotation = MaskNodePosX|MaskNodePosY|MaskNodePosZ|MaskNodeBlend
- MaskNodeAllButPosX = MaskNodeRotation|MaskNodePosY|MaskNodePosZ|MaskNodeBlend
- MaskNodeAllButPosY = MaskNodeRotation|MaskNodePosX|MaskNodePosZ|MaskNodeBlend
- MaskNodeAllButPosZ = MaskNodeRotation|MaskNodePosX|MaskNodePosY|MaskNodeBlend
- MaskNodeHandsOff = 0x20
meaning, don't even set to default, programmer controls it (blend still applies)
- MaskNodeCallback = 0x40
meaning, get local transform via callback function (see setCallback) callback data2 is node index, callback return value is pointer to local transform Note: won't get this callback everytime you animate...application responsibility to make sure matrix pointer continues to point to valid and updated local transform
@211
Enumerator
- TransformDirty = BIT(0)
- VisDirty = BIT(1)
- FrameDirty = BIT(2)
- MatFrameDirty = BIT(3)
- ThreadDirty = BIT(4)
- AllDirtyMask = TransformDirty | VisDirty | FrameDirty | MatFrameDirty | ThreadDirty
Public Friends
Public Attributes
void * mData
available for use by app...initialized to 0
U32 * mDirtyFlags
TSMaterialList * mMaterialList
by default, points to hShape material list
Vector< MeshObjectInstance > mMeshObjects
Vector< MatrixF > mNodeTransforms
storage space for node transforms
Public Static Attributes
F32 smDetailAdjust
Scale pixel size by this amount when selecting detail levels.
F32 smLastPixelSize
F32 smLastScaledDistance
F32 smLastScreenErrorTolerance
For debugging / metrics.
S32 smNumSkipRenderDetails
never choose detail level number below this value (except if only way to get a visible detail)
F32 smSmallestVisiblePixelSize
If this is set to a positive pixel value shapes with a smaller pixel size than this will skip rendering entirely.
Protected Attributes
U32 debrisRefCount
bool mAlphaAlways
F32 mAlphaAlwaysValue
TSIntegerSet mCallbackNodes
S32 mCurrentDetailLevel
F32 mCurrentIntraDetailLevel
0-1, how far along from current to next (higher) detail level...
0=at this dl, 1=at higher detail level, where higher means bigger size on screen for dl=0, we use twice detail level 0's size as the size of the "next" dl
TSIntegerSet mDisableBlendNodes
TSIntegerSet mHandsOffNodes
Nodes that aren't animated through threads automatically.
TSIntegerSet mMaskPosXNodes
TSIntegerSet mMaskPosYNodes
TSIntegerSet mMaskPosZNodes
TSIntegerSet mMaskRotationNodes
keep track of nodes with animation restrictions put on them
Vector< TSCallbackRecord > mNodeCallbacks
bool mOwnMaterialList
Does this own the material list pointer?
bool mScaleCurrentlyAnimated
TSShape * mShape
This should always point to a valid shape and should equal mShapeResource if it was created from a resource.
Resource< TSShape > mShapeResource
This is only valid when the instance was created from a resource.
Else it is null.
TSVertexBufferHandle mSoftwareVertexBuffer
Vertex buffer used for software skinning this instance.
Vector< TSThread * > mThreadList
Vector< TSThread * > mTransitionThreads
U32 mTriggerStates
state variables
bool mUseOverrideTexture
bool mUseOwnBuffer
Force using our own copy of the vertex buffer.
Protected Functions
addPath(TSThread * gt, F32 start, F32 end, MatrixF * mat)
initGround()
Public Functions
TSShapeInstance(const Resource< TSShape > & shape, bool loadMaterials)
TSShapeInstance(TSShape * pShape, bool loadMaterials)
~TSShapeInstance()
animate()
animate(S32 dl)
animateFrame(S32 ss)
animateMatFrame(S32 ss)
animateNodes(S32 ss)
animateNodeSubtrees(bool forceFull)
animateSubtrees(bool forceFull)
animateVisibility(S32 ss)
bufferNeedsUpdate(S32 objectDetail, S32 start, S32 end)
buildConvexOpcode(const MatrixF & objMat, const Point3F & objScale, S32 objectDetail, const Box3F & bounds, Convex * c, Convex * list)
buildInstanceData(TSShape * , bool loadMaterials)
buildPolyList(AbstractPolyList * , S32 dl)
buildPolyListOpcode(S32 dl, AbstractPolyList * polyList, const Box3F & box)
castRay(const Point3F & start, const Point3F & end, RayInfo * , S32 dl)
castRayOpcode(S32 objectDetail, const Point3F & start, const Point3F & end, RayInfo * )
castRayRendered(const Point3F & start, const Point3F & end, RayInfo * , S32 dl)
clearDirty(U32 dirty)
cloneMaterialList(const FeatureSet * features)
Call this to own the material list – i.e., we'll make a copy of the currently set material list and be responsible for deleting it.
You can pass an optional feature set for initializing the cloned materials.
computeBounds(S32 dl, Box3F & bounds)
uses current transforms to compute bounding box around a detail level see like named method on shape if you want to use default transforms
dump(Stream & )
dumpNode(Stream & , S32 level, S32 nodeIndex, Vector< S32 > & detailSizes)
getCurrentDetail()
getCurrentIntraDetail()
getFeatures(const MatrixF & mat, const Point3F & n, ConvexFeature * , S32 dl)
getMaterialList()
getNumDetails()
getShape()
getTargetCount()
Get the number of material targets in this shape instance.
getTargetName(S32 mapToNameIndex)
Get the indexed material target (may differ from the base TSShape material list if this instance has been reskinned).
getTriggerStateMask()
hasAccumulation()
initMaterialList(const FeatureSet * features)
Initializes or re-initializes the material list with an optional feature set.
initMeshObjects()
initNodeTransforms()
inTransition()
ownMaterialList()
prepCollision()
quickLOS(const Point3F & start, const Point3F & end, S32 dl)
render(const TSRenderState & rdata)
render(const TSRenderState & rdata, S32 dl, F32 intraDL)
resetMaterialList()
reSkin(String newBaseName, String oldBaseName)
setCurrentDetail(S32 dl, F32 intraDL)
setDetailFromDistance(const SceneRenderState * state, F32 scaledDist)
Selects the current detail level using the scaled distance between your object and the camera.
setDetailFromPosAndScale(const SceneRenderState * state, const Point3F & pos, const Point3F & scale)
Helper function which internally calls setDetailFromDistance.
setDetailFromScreenError(F32 errorTOL)
Sets the current detail level using the legacy screen error metric.
setDirty(U32 dirty)
setMaterialList(TSMaterialList * matList)
Set the material list without taking ownership.
setMeshForceHidden(const char * meshName, bool hidden)
Sets the 'forceHidden' state on the named mesh.
setMeshForceHidden(S32 meshIndex, bool hidden)
Sets the 'forceHidden' state on a mesh.
setUseOwnBuffer()
support(const Point3F & v, S32 dl)