TSShape

Engine/source/ts/tsShape.h

TSShape stores generic data for a 3space model.

More...

Classes:

class

Details are used for render detail selection.

class

Nodes hold the transforms in the shape's tree. They are the bones of the skeleton.

class

Objects hold renderable items (in particular meshes).

class

Describes state of an individual object.

class

A Sequence holds all the information necessary to perform a particular animation (sequence).

class

When time on a sequence advances past a certain point, a trigger takes effect and changes one of the state variables to on or off.

Public User Defined

These are set up at load time, but memory is allocated along with loaded data.

Alpha Vectors

these vectors describe how to transition between detail levels using alpha.

"alpha-in" next detail as intraDL goes from alphaIn+alphaOut to alphaOut. "alpha-out" current detail level as intraDL goes from alphaOut to 0.

note:

  • intraDL is at 1 when if shape were any closer to us we'd be at dl-1

  • intraDL is at 0 when if shape were any farther away we'd be at dl+1

Alpha Transitions

These control default values for alpha transitions between detail levels

Version Info

Most recent version...the one we write.

Version currently being read, only valid during read.

Persist Helper Functions

fixEndian(S32 * , S16 * , S8 * , S32 , S32 , S32 )

Collision Accelerators

For speeding up buildpolylist and support calls.

Lookup Animation Info

indexed by keyframe number and offset (which object/node/decal of the animated objects/nodes/decals you want information for).

getRotation(const Sequence & seq, S32 keyframeNum, S32 rotNum, QuatF * )
getTranslation(const Sequence & seq, S32 keyframeNum, S32 tranNum)
getUniformScale(const Sequence & seq, S32 keyframeNum, S32 scaleNum)
getAlignedScale(const Sequence & seq, S32 keyframeNum, S32 scaleNum)
getArbitraryScale(const Sequence & seq, S32 keyframeNum, S32 scaleNum, TSScale * )
getObjectState(const Sequence & seq, S32 keyframeNum, S32 objectNum)

Lookup Methods

Returns index into the name vector that equals the passed name.

getName(S32 nameIndex)

Returns name string at the passed name vector index.

getMeshName(S32 meshIndex)

Returns name string for mesh at the passed index.

getNodeName(S32 nodeIndex)

Returns name string for node at the passed index.

getSequenceName(S32 seqIndex)

Returns name string for sequence at the passed index.

getTargetName(S32 mapToNameIndex)
findNode(S32 nameIndex)
findObject(S32 nameIndex)
findDetail(S32 nameIndex)
findSequence(S32 nameIndex)
getSubShapeDetails(S32 subShapeIndex, Vector< S32 > & validDetails)
getNodeKeyframe(S32 nodeIndex, const TSShape::Sequence & seq, S32 keyframe, MatrixF * mat)
getNodeObjects(S32 nodeIndex, Vector< S32 > & nodeObjects)
getNodeChildren(S32 nodeIndex, Vector< S32 > & nodeChildren)
getObjectDetails(S32 objIndex, Vector< S32 > & objDetails)
bool
findMeshIndex(const String & meshName, S32 & objIndex, S32 & meshIndex)
findMesh(const String & meshName)

Persist Methods

Methods for saving/loading shapes to/from streams

bool

Determine whether we can write this shape in TSTPRO compatible format.

write(Stream * , bool saveOldFormat)
bool
readOldShape(Stream * s, S32 *& , S16 *& , S8 *& , S32 & , S32 & , S32 & )
writeName(Stream * , S32 nameIndex)
readName(Stream * , bool addName)

Initializes our TSShape to be ready to receive put mesh data.

exportSequence(Stream * s, const TSShape::Sequence & seq, bool saveOldFormat)
bool
importSequences(Stream * , const String & sequencePath)

Memory Buffer Transfer Methods

uses TSShape::Alloc structure

Shape Editing

bool
addDetail(const String & dname, S32 size, S32 subShapeNum)
addImposter(const String & cachePath, S32 size, S32 numEquatorSteps, S32 numPolarSteps, S32 dl, S32 dim, bool includePoles, F32 polarAngle)
bool
renameNode(const String & oldName, const String & newName)
bool
renameObject(const String & oldName, const String & newName)
bool
renameDetail(const String & oldName, const String & newName)
bool
renameSequence(const String & oldName, const String & newName)
bool
bool
addNode(const String & name, const String & parentName, const Point3F & pos, const QuatF & rot)
bool
addObject(const String & objName, S32 subShapeIndex)
addMeshToObject(S32 objIndex, S32 meshIndex, TSMesh * mesh)
removeMeshFromObject(S32 objIndex, S32 meshIndex)
bool
setObjectNode(const String & objName, const String & nodeName)
bool
copyMesh(const TSMesh * srcMesh)
bool
addMesh(TSShape * srcShape, const String & srcMeshName, const String & meshName)
bool
addMesh(TSMesh * mesh, const String & meshName)
bool
setMeshSize(const String & meshName, S32 size)
bool
removeMesh(const String & meshName)
setDetailSize(S32 oldSize, S32 newSize)
bool
bool
addSequence(const Torque::Path & path, const String & fromSeq, const String & name, S32 startFrame, S32 endFrame, bool padRotKeys, bool padTransKeys)
bool
addTrigger(const String & seqName, S32 keyframe, S32 state)
bool
removeTrigger(const String & seqName, S32 keyframe, S32 state)
bool
setSequenceBlend(const String & seqName, bool blend, const String & blendRefSeqName, S32 blendRefFrame)
bool
bool

Public Types

enum
_Anonymous_ {
  UniformScale = BIT(0)
  AlignedScale = BIT(1)
  ArbitraryScale = BIT(2)
  Blend = BIT(3)
  Cyclic = BIT(4)
  MakePath = BIT(5)
  HasTranslucency = BIT(6)
  AnyScale = UniformScale | AlignedScale | ArbitraryScale
}

Public Attributes

User-defined data storage.

The lod lookup table where we mark down the detail level and intra-detail level for each pixel size.

hasTranslucancy

File version that this shape was read from.

Computed at load time from details vector.

bool

If enabled detail selection will use the legacy screen error method for lod.

The GFX vertex format for all detail meshes in the shape.

Public Static Attributes

bool

by default we initialize shape when we read...

Determines maximum number of bones to use in hardware skinning shaders.

don't load this many of the highest detail levels (although we always load one renderable detail if there is one)

bool

Enables hardware skinning features.

Public Functions

_buildColShapes(bool useVisibleMesh, const Point3F & scale, Vector< CollisionShapeInfo > * list, bool perMesh)

For internal use.

buildColShape(bool useVisibleMesh, const Point3F & scale)

Builds a physics collision shape at the requested scale.

buildColShapes(bool useVisibleMesh, const Point3F & scale, Vector< CollisionShapeInfo > * list)

Like buildColShape except we build one PhysicsCollision object per collision node.

bool
checkSkip(S32 meshNum, S32 & curObject, S32 skipDL)

mem buffer transfer helper (indicate when we don't want to include a particular mesh/decal)

build LOS collision detail

computeBounds(S32 dl, Box3F & bounds)
findColDetails(bool useVisibleMesh, Vector< S32 > * outDetails, Vector< S32 > * outLOSDetails)

Used to find collision detail meshes in the DTS.

fixupOldSkins(S32 numMeshes, S32 numSkins, S32 numDetails, S32 * detFirstSkin, S32 * detailNumSkins)

Loads shape vertex data into specified buffer.

you can swap in a new material list, but call this if you do

Inits object list (no geometry buffers)

Inits basic buffer pointers on load.

Initializes the main vertex buffer.

Called from init() to calcuate the GFX vertex features for all detail meshes in the shape.

bool

called to preload and validate the materials in the mat list

Detailed Description

TSShape stores generic data for a 3space model.

TSShape and TSShapeInstance act in conjunction to allow the rendering and manipulation of a three dimensional model.

note:

The material lists are the only thing that is not loaded in TSShape. instead, they are loaded in TSShapeInstance because of a former restriction on the resource manager where only one file could be opened at a time. The resource manager restriction has been resolved, but the material lists are still loaded in TSShapeInstance.

see:

TSShapeInstance for a further discussion of the 3space system.

Shape Vector Data

Vector< Node > nodes 
Vector< Object > objects 
Vector< ObjectState > objectStates 
Vector< S32 > subShapeFirstNode 
Vector< S32 > subShapeFirstObject 
Vector< S32 > detailFirstSkin 
Vector< S32 > subShapeNumNodes 
Vector< S32 > subShapeNumObjects 
Vector< Detail > details 
Vector< Quat16 > defaultRotations 
Vector< Point3F > defaultTranslations 

Public User Defined

Vector< S32 > subShapeFirstTranslucentObject 

These are set up at load time, but memory is allocated along with loaded data.

Vector< TSMesh * > meshes 

Alpha Vectors

these vectors describe how to transition between detail levels using alpha.

"alpha-in" next detail as intraDL goes from alphaIn+alphaOut to alphaOut. "alpha-out" current detail level as intraDL goes from alphaOut to 0.

note:

  • intraDL is at 1 when if shape were any closer to us we'd be at dl-1

  • intraDL is at 0 when if shape were any farther away we'd be at dl+1

Vector< F32 > alphaIn 
Vector< F32 > alphaOut 

Resizeable vectors

Vector< Sequence > sequences 
Vector< Quat16 > nodeRotations 
Vector< Point3F > nodeTranslations 
Vector< F32 > nodeUniformScales 
Vector< Point3F > nodeAlignedScales 
Vector< Quat16 > nodeArbitraryScaleRots 
Vector< Point3F > nodeArbitraryScaleFactors 
Vector< Quat16 > groundRotations 
Vector< Point3F > groundTranslations 
Vector< Trigger > triggers 
Vector< TSLastDetail * > billboardDetails 
Vector< ConvexHullAccelerator * > detailCollisionAccelerators 
Vector< String > names 

Bounding

F32 mRadius 
F32 tubeRadius 
Point3F center 
Box3F mBounds 

Alpha Transitions

These control default values for alpha transitions between detail levels

F32 smAlphaOutLastDetail 
F32 smAlphaInBillboard 
F32 smAlphaOutBillboard 
F32 smAlphaInDefault 
F32 smAlphaOutDefault 

Version Info

S32 smVersion 

Most recent version...the one we write.

most recent version – this is the version we write

S32 smReadVersion 

Version currently being read, only valid during read.

the version currently being read...valid only during a read

const U32 smMostRecentExporterVersion 

Persist Helper Functions

fixEndian(S32 * , S16 * , S8 * , S32 , S32 , S32 )

TSShapeAlloc smTSAlloc 

Collision Accelerators

For speeding up buildpolylist and support calls.

getAccelerator(S32 dl)

Lookup Animation Info

indexed by keyframe number and offset (which object/node/decal of the animated objects/nodes/decals you want information for).

getRotation(const Sequence & seq, S32 keyframeNum, S32 rotNum, QuatF * )

getTranslation(const Sequence & seq, S32 keyframeNum, S32 tranNum)

getUniformScale(const Sequence & seq, S32 keyframeNum, S32 scaleNum)

getAlignedScale(const Sequence & seq, S32 keyframeNum, S32 scaleNum)

getArbitraryScale(const Sequence & seq, S32 keyframeNum, S32 scaleNum, TSScale * )

getObjectState(const Sequence & seq, S32 keyframeNum, S32 objectNum)

Lookup Methods

findName(const String & name)

Returns index into the name vector that equals the passed name.

getName(S32 nameIndex)

Returns name string at the passed name vector index.

getMeshName(S32 meshIndex)

Returns name string for mesh at the passed index.

getNodeName(S32 nodeIndex)

Returns name string for node at the passed index.

getSequenceName(S32 seqIndex)

Returns name string for sequence at the passed index.

getTargetCount()

getTargetName(S32 mapToNameIndex)

findNode(S32 nameIndex)

findNode(const String & name)

findObject(S32 nameIndex)

findObject(const String & name)

findDetail(S32 nameIndex)

findDetail(const String & name)

findDetailBySize(S32 size)

findSequence(S32 nameIndex)

findSequence(const String & name)

getSubShapeForNode(S32 nodeIndex)

getSubShapeForObject(S32 objIndex)

getSubShapeDetails(S32 subShapeIndex, Vector< S32 > & validDetails)

getNodeWorldTransform(S32 nodeIndex, MatrixF * mat)

getNodeKeyframe(S32 nodeIndex, const TSShape::Sequence & seq, S32 keyframe, MatrixF * mat)

getNodeObjects(S32 nodeIndex, Vector< S32 > & nodeObjects)

getNodeChildren(S32 nodeIndex, Vector< S32 > & nodeChildren)

getObjectDetails(S32 objIndex, Vector< S32 > & objDetails)

findMeshIndex(const String & meshName, S32 & objIndex, S32 & meshIndex)

findMesh(const String & meshName)

hasTranslucency()

getVertexFormat()

Persist Methods

Methods for saving/loading shapes to/from streams

canWriteOldFormat()

Determine whether we can write this shape in TSTPRO compatible format.

write(Stream * , bool saveOldFormat)

read(Stream * )

readOldShape(Stream * s, S32 *& , S16 *& , S8 *& , S32 & , S32 & , S32 & )

writeName(Stream * , S32 nameIndex)

readName(Stream * , bool addName)

createEmptyShape()

Initializes our TSShape to be ready to receive put mesh data.

exportSequences(Stream * )

exportSequence(Stream * s, const TSShape::Sequence & seq, bool saveOldFormat)

importSequences(Stream * , const String & sequencePath)

Memory Buffer Transfer Methods

uses TSShape::Alloc structure

assembleShape()

disassembleShape()

Shape Editing

addName(const String & name)

removeName(const String & name)

updateSmallestVisibleDL()

addDetail(const String & dname, S32 size, S32 subShapeNum)

addImposter(const String & cachePath, S32 size, S32 numEquatorSteps, S32 numPolarSteps, S32 dl, S32 dim, bool includePoles, F32 polarAngle)

removeImposter()

renameNode(const String & oldName, const String & newName)

renameObject(const String & oldName, const String & newName)

renameDetail(const String & oldName, const String & newName)

renameSequence(const String & oldName, const String & newName)

setNodeTransform(const String & name, const Point3F & pos, const QuatF & rot)

addNode(const String & name, const String & parentName, const Point3F & pos, const QuatF & rot)

removeNode(const String & name)

addObject(const String & objName, S32 subShapeIndex)

addMeshToObject(S32 objIndex, S32 meshIndex, TSMesh * mesh)

removeMeshFromObject(S32 objIndex, S32 meshIndex)

setObjectNode(const String & objName, const String & nodeName)

removeObject(const String & objName)

copyMesh(const TSMesh * srcMesh)

addMesh(TSShape * srcShape, const String & srcMeshName, const String & meshName)

addMesh(TSMesh * mesh, const String & meshName)

setMeshSize(const String & meshName, S32 size)

removeMesh(const String & meshName)

setDetailSize(S32 oldSize, S32 newSize)

removeDetail(S32 size)

addSequence(const Torque::Path & path, const String & fromSeq, const String & name, S32 startFrame, S32 endFrame, bool padRotKeys, bool padTransKeys)

removeSequence(const String & name)

addTrigger(const String & seqName, S32 keyframe, S32 state)

removeTrigger(const String & seqName, S32 keyframe, S32 state)

setSequenceBlend(const String & seqName, bool blend, const String & blendRefSeqName, S32 blendRefFrame)

setSequenceGroundSpeed(const String & seqName, const Point3F & trans, const Point3F & rot)

makeEditable()

needsReinit()

needsBufferUpdate()

Public Types

@208

Enumerator

UniformScale = BIT(0)
AlignedScale = BIT(1)
ArbitraryScale = BIT(2)
Blend = BIT(3)
Cyclic = BIT(4)
MakePath = BIT(5)
HasTranslucency = BIT(6)
AnyScale = UniformScale | AlignedScale | ArbitraryScale

Public Attributes

U32 data 

User-defined data storage.

TSMaterialList * materialList 
TSBasicVertexFormat mBasicVertexFormat 
Vector< LodPair > mDetailLevelLookup 

The lod lookup table where we mark down the detail level and intra-detail level for each pixel size.

U32 mExporterVersion 
U32 mFlags 

hasTranslucancy

bool mNeedReinit 
S32 mReadVersion 

File version that this shape was read from.

bool mSequencesConstructed 
S8 * mShapeData 
U32 mShapeDataSize 
TSVertexBufferHandle mShapeVertexBuffer 
TSShapeVertexArray mShapeVertexData 
GFXPrimitiveBufferHandle mShapeVertexIndices 
S32 mSmallestVisibleDL 

F32 mSmallestVisibleSize 

Computed at load time from details vector.

bool mUseDetailFromScreenError 

If enabled detail selection will use the legacy screen error method for lod.

see:

setDetailFromScreenError

GFXVertexFormat mVertexFormat 

The GFX vertex format for all detail meshes in the shape.

U32 mVertexSize 

Public Static Attributes

bool smInitOnRead 

by default we initialize shape when we read...

U32 smMaxSkinBones 

Determines maximum number of bones to use in hardware skinning shaders.

S32 smNumSkipLoadDetails 

don't load this many of the highest detail levels (although we always load one renderable detail if there is one)

bool smUseHardwareSkinning 

Enables hardware skinning features.

Public Functions

TSShape()

~TSShape()

_buildColShapes(bool useVisibleMesh, const Point3F & scale, Vector< CollisionShapeInfo > * list, bool perMesh)

For internal use.

buildColShape(bool useVisibleMesh, const Point3F & scale)

Builds a physics collision shape at the requested scale.

If using the visible mesh one or more triangle meshes are created from the first visible detail level.

If using collision meshes we look for mesh names prefixed with the following hints: "colbox" "colsphere" "colcapsule" "colmesh"

In the case of the primitives the mesh bounding box is used to generate a box, sphere, or capsule collision shape. The "colmesh" will create a concave triangle mesh for collision.

Any other named collision shape is interpreted as a regular convex hull.

return:

The collision object or NULL if no collision data could be generated.

buildColShapes(bool useVisibleMesh, const Point3F & scale, Vector< CollisionShapeInfo > * list)

Like buildColShape except we build one PhysicsCollision object per collision node.

Results are returned by filling in the CollisionShapeInfo Vector, which also specifies the collision node index for each PhysicsCollision built.

buildConvexHull(S32 dl)

checkSkip(S32 meshNum, S32 & curObject, S32 skipDL)

mem buffer transfer helper (indicate when we don't want to include a particular mesh/decal)

computeAccelerator(S32 dl)

build LOS collision detail

computeBounds(S32 dl, Box3F & bounds)

finalizeEditable()

findColDetails(bool useVisibleMesh, Vector< S32 > * outDetails, Vector< S32 > * outLOSDetails)

Used to find collision detail meshes in the DTS.

Parameters:

useVisibleMesh

If true return the highest visible detail level.

outDetails

The output detail index vector.

outLOSDetails

The optional output LOS detail vector.

fixupOldSkins(S32 numMeshes, S32 numSkins, S32 numDetails, S32 * detFirstSkin, S32 * detailNumSkins)

getSequencesConstructed()

getVertexBuffer(TSVertexBufferHandle & vb, GFXBufferType bufferType)

Loads shape vertex data into specified buffer.

init()

initMaterialList()

you can swap in a new material list, but call this if you do

initObjects()

Inits object list (no geometry buffers)

initVertexBufferPointers()

Inits basic buffer pointers on load.

initVertexBuffers()

Initializes the main vertex buffer.

initVertexFeatures()

Called from init() to calcuate the GFX vertex features for all detail meshes in the shape.

preloadMaterialList(const Torque::Path & path)

called to preload and validate the materials in the mat list

setSequencesConstructed(const bool c)

setupBillboardDetails(const String & cachePath)