Dts format {documentation artist guide formats} - LuisAntonRebollo/Torque-3D-Wiki-Test GitHub Wiki

Contents

Introduction

DTS is the native binary format used by the Torque engine to store shape, mesh and (optionally) sequence data. This document serves as a basic specification for the DTS file format. Very little context is given to the shape, mesh and sequence data fields read from the DTS file so it is recommended that this resource be read along with the Torque 3D source code.


The DTS file format stores most data in separate buffers for 8, 16 or 32-bit sized values in order to speed up loading on non-Intel platforms. A DTS file can be read as shown below; after the 3 data buffers have been created in memory, they are read in interleaved order as needed to extract the desired values (see Data Buffers).


Note: that all values are stored as little-endian, so on non-Intel platforms you will have to handle perform endian conversion for 16 and 32-bit values.


DTS Format

Name # bytes Data Type Description
DTS version number 2 S16 DTS version of this file. Note that the current DTS version (for files saved by Torque 3D) is 26. Most DTS exporters and the ShowToolPro tool only read/write version 24.
Exporter version number 2 S16 For tracking version of the exporter that generated this file. Can usually be ignored.
sizeAll 4 S32 Size (in 32-bit words) of the 3 data buffers (sum of 8, 16 and 32-bit data buffers). The 32-bit data buffer starts at offset 0x0.
start16 4 S32 32-bit word offset into the memory buffer of the start of the 16-bit data.
start8 4 S32 32-bit word offset into the memory buffer of the start of the 8-bit data.
data32 size32 U32* Data buffer for 32-bit values. Size (in bytes) is equal to start16*4
data16 size16 U16* Data buffer for 16-bit values. Size (in bytes) is equal to (start8 - start16)*4
data8 size8 U8* Data buffer for 8-bit values. Size (in bytes) is equal to (sizeAll - start8)*4
numSequences 4 S32 Number of sequences in the shape
sequences numSequences * ? Sequence Array of numSequences Sequences - size of each sequence depends on which nodes and objects are affected etc. See Sequences for more information
matStreamType 1 S8 Type of material stream (text or binary). Should be 0x1 (binary) for DTS files
numMaterials 4 S32 Number of materials in the shape
matNames numMaterials * ? S32 and char[] Names of the materials in the shape. Each name is stored as a 4-byte length followed by the N characters in the string (terminating NULL is not included in the length or N characters).
matFlags numMaterials * 4 U32 Flags for each material*
matReflectanceMaps numMaterials * 4 S32 Index of the material to use as a reflectance map for each material* (or -1 for none)
matBumpMaps numMaterials * 4 S32 Index of the material to use as a bump map for each material* (or -1 for none)
matDetailMaps numMaterials * 4 S32 Index of the material to use as a detail map for each material* (or -1 for none)
dummy numMaterials * 4 S32 Dummy value. Only present in DTS v25.
matDetailScales numMaterials * 4 F32 Detail scale for each material*
matReflectance numMaterials * 4 F32 Reflectance value for each material*

Note: that all material settings (beside the name) are superceded by script Material definitions in T3D.

Sequences

Sequences are stored in the DTS file as follows:

Name # bytes Data Type Description
nameIndex 4 S32 The name of this sequence as in index into the names array
flags 4 U32 Sequence flags
numKeyframes 4 S32 Number of keyframes in this sequence
duration 4 F32 Duration of the sequence (in seconds)
priority 4 S32 Sequence priority
firstGroundFrame 4 S32 First ground transform keyframe in this sequence (index into the groundTranslations and groundRotation arrays)
numGroundFrames 4 S32 Number of ground transform keyframes in this sequence
baseRotation 4 S32 First node rotation keyframe in this sequence (index into the nodeRotations array)
baseTranslation 4 S32 First node translation keyframe in this sequence (index into the nodeTranslations array)
baseScale 4 S32 First node scale keyframe in this sequence (index into the nodeXXXScales arrays)
baseObjectState 4 S32 First object state keyframe in this sequence (index into the objectStates array)
baseDecalState 4 S32 First decal state keyframe in this sequence (index into the decalStates array). Note that DTS decals are deprecated, and this value should be 0.
firstTrigger 4 S32 First trigger in this sequence (index into the triggers array)
numTriggers 4 S32 Number of triggers in this sequence
toolBegin 4 F32 Value representing the start of this sequence in the exporting tool's timeline (can usually by ignored)
rotationMatters ? BitSet BitSet indicating which node rotations are animated by this sequence.
translationMatters ? BitSet BitSet indicating which node translations are animated by this sequence.
scaleMatters ? BitSet BitSet indicating which node scales are animated by this sequence.
decalMatters ? BitSet BitSet indicating which decal states are animated by this sequence. Note that DTS decals are deprecated.
iflMatters ? BitSet BitSet indicating which IFL materials are animated by this sequence.
visMatters ? BitSet BitSet indicating which object's visibility is animated by this sequence.
frameMatters ? BitSet BitSet indicating which mesh's verts are animated by this sequence.
matFrameMatters ? BitSet BitSet indicating which mesh's UV coords are animated by this sequence.


BitSets

BitSets are stored in the DTS file as:

Name # bytes Data Type Description
dummy 4 S32 Dummy value
numWords 4 S32 Number of 32-bit values in the BitSet
bits 4 * numWords U32 Array of numWords 32-bit values representing the bits in the BitSet


Data Buffers

The 3space shape data is extracted from the 3 data buffers by maintaining a pointer into each buffer, then reading from the appropriate buffer in order as shown in the table below. The code sample below demonstrates how an array of structures might be read from the 3 buffers.

struct
{
S8 valueA[4];
S32 valueB;
S32 valueC;
S16 valueD;
} Object;
...
#define checkGuard() assert((*buff32++ == guard32++) && (*buff16++ == guard16++)
&& (*buff8++ == guard8++))
...
numObjects = *buff32++;
objects.resize(numObjects);
for (S32 i = 0; i < numObjects; i++)
{
for (S32 j = 0; j < 4; j++)
objects[i].valueA[j] = *buff8++;
objects[i].valueB = *buff32++;
objects[i].valueC = *buff32++;
objects[i].valueD = *buff16++;
}
checkGuard();

The GUARD entries indicate a buffer checkpoint that verifies the buffers are being accessed correctly. Each time the GUARD entry is encountered, an incrementing value should be read from each of the 3 buffers. For example, the first GUARD should read 32-bit 0x0, 16-bit 0x0 and 8-bit 0x0, the next GUARD should read 32-bit 0x1, 16-bit 0x1 and 8-bit 0x1 and so on.

Name Buffer Data Type Description
numNodes 32-bit S32 Number of nodes in the shape
numObjects 32-bit S32 Number of objects in the shape
numDecals 32-bit S32 Number of decals in the shape
numSubShapes 32-bit S32 Number of subshapes in the shape
numIFLs 32-bit S32 Number of IFL materials in the shape
numNodeRotations 32-bit S32 Number of node rotation keyframes
numNodeTranslations 32-bit S32 Number of node translation keyframes
numNodeUniformScales 32-bit S32 Number of node uniform scale keyframes
numNodeAlignedScales 32-bit S32 Number of node aligned scale keyframes
numNodeArbScales 32-bit S32 Number of node arbitrary scale keyframes
numGroundFrames 32-bit S32 Number of ground transform keyframes
numObjectStates 32-bit S32 Number of object state keyframes
numDecalStates 32-bit S32 Number of decal state keyframes
numTriggers 32-bit S32 Number of triggers (all sequences)
numDetails 32-bit S32 Number of detail levels in the shape
numMeshes 32-bit S32 Number of meshes (all detail levels) in the shape
numNames 32-bit S32 Number of name strings in the shape
smallestVisibleSize 32-bit F32 Size of the smallest visible detai level
smallestVisibleDL 32-bit S32 Index of the smallest visible detail level
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
radius 32-bit F32 Shape bounding sphere radius
tubeRadius 32-bit F32 Shape bounding cylinder radius
center 32-bit Point3F { F32 x, F32 y, F32 z } Center of the shape bounds
bounds 32-bit BoxF { Point3F min, Point3F max } Shape bounding box
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
nodes 32-bit Node { S32 nameIndex, S32 parentIndex, S32 firstObject, S32 firstChild, S32 nextSibling } Array of numNodes Nodes
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
objects 32-bit Object { S32 nameIndex, S32 numMeshes, S32 startMeshIndex, S32 nodeIndex, S32 nextSibling, S32 firstDecal } Array of numObjects Objects
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
decals 32-bit Decal { S32 dummy[5] } Array of numDecals Decals. Note that decals are deprecated.
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
iflMaterials 32-bit IflMaterial { S32 nameIndex, S32 materialSlot, S32 firstFrame, S32 firstFrameOffTimeIndex, S32 numFrames } Array of numIFLs IflMaterials
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
subShapeFirstNode 32-bit S32 Array of numSubShapes ints representing the index of the first node in each subshape
subShapeFirstObject 32-bit S32 Array of numSubShapes ints representing the index of the first object in each subshape
subShapeFirstDecal 32-bit S32 Array of numSubShapes ints representing the index of the first decal in each subshape
subShapeFirstTranslucentObject 32-bit S32 Array of numSubShapes ints representing the index of the first translucent object in each subshape
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
defaultRotations 16-bit Quat16 { S16 x, S16 y, S16 z, S16 Z } Array of numNodes quaternions for default node rotations
defaultTranslations 32-bit Point3F { F32 x, F32 y, F32 z } Array of numNodes points for default node translations
nodeRotations 16-bit Quat16 { S16 x, S16 y, S16 z, S16 Z } Array of numNodeRotations quaternions for node rotation keyframes (all sequences)
nodeTranslations 32-bit Point3F { F32 x, F32 y, F32 z } Array of numNodeTranslations points for node translation keyframes (all sequences)
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
nodeUniformScales 32-bit F32 Array of numNodeUniformScales floats for node uniform scale keyframes (all sequences)
nodeAlignedScales 32-bit Point3F { F32 x, F32 y, F32 z } Array of numNodeAlignedScales points for node aligned scale keyframes (all sequences)
nodeArbScaleFactors 32-bit Point3F { F32 x, F32 y, F32 z } Array of numNodeArbScales points for node arbitrary scale factor keyframes (all sequences)
nodeArbScaleRots 16-bit Quat16 { S16 x, S16 y, S16 z, S16 w } Array of numNodeArbScales quaternions for node arbitrary scale rotation keyframes (all sequences)
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
groundTranslations 32-bit Point3F { F32 x, F32 y, F32 z } Array of numGroundFrames points for ground transform keyframes (all sequences)
groundRotations 16-bit Quat16 { S16 x, S16 y, S16 z, S16 w } Array of numGroundFrames quaternions for ground transform keyframes (all sequences)
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
objectStates 32-bit ObjectState { F32 vis, S32 frameIndex, S32 matFrame } Array of numObjectStates ObjectStates
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
decalStates 32-bit S32 Array of numDecalStates dummy integers for decal states
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
triggers 32-bit Trigger { U32 state, F32 pos } Array of numTriggers sequence triggers (all sequences)
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
details 32-bit Detail v25- { S32 nameIndex, S32 subShapeNum, S32 objectDetailNum, F32 size, F32 averageError, F32 maxError, S32 polyCount }
Detail v26+ also includes { S32 bbDimension, S32 bbDetailLevel, S32 bbEquatorSteps, S32 bbPolarSteps, F32 bbPolarAngle, bool bbIncludePoles }		 Array of numDetails Details
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
meshes ALL Mesh Array of numMeshes Meshes
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
names 8-bit char[] Array of numNames strings, stored as N characters followed by a terminating NULL for each string.
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
alphaIn 32-bit F32 Array of numDetails floats representing alpha-in value for each detail
alphaOut 32-bit F32 Array of numDetails floats representing alpha-out value for each detail


Meshes

Meshes are stored in the 3 data buffers as follows:

Name Buffer Data Type Description
type 32-bit U32 Type of mesh
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
numFrames 32-bit S32 Number of vertex position keyframes
numMatFrames 32-bit S32 Number of vertex UV keyframes
parentMesh 32-bit S32 Index of this mesh's parent (usually -1 for none)
bounds 32-bit BoxF { Point3F min, Point3F max } Bounding box for this mesh
center 32-bit Point3F { F32 x, F32 y, F32 z } Bounds center for this mesh
radius 32-bit F32 Bounding sphere radius for this mesh
numVerts 32-bit S32 Number of vertex positions
verts 32-bit Point3F { F32 x, F32 y, F32 z } Array of numVerts vertex positions (all keyframes)
numTVerts 32-bit S32 Number of UV coordinates
tverts 32-bit Point2F { F32 u, F32 v } Array of numTVerts UV coordinates (all keyframes)
numTVerts2 32-bit S32 Number of 2nd UV coordinates (DTS v26+ only)
tverts2 32-bit Point2F { F32 u, F32 v } Array of numTVerts2 2nd UV coordinates (DTS v26+ only)
numVColors 32-bit S32 Number of vertex color values (DTS v26+ only)
colors 32-bit ColorI { U8 red, U8 green, U8 blue, U8 alpha } Array of numVColors vertex colors (DTS v26+ only)
norms 32-bit Point3F { F32 x, F32 y, F32 z } Array of numVerts vertex normals
encodedNorms 8-bit U8 Array of numVerts encoded normal indices
numPrimitives 32-bit S32 Number of mesh primitives (triangles, triangle lists etc)
primitives (v24-) 16-bit S16 Array of numPrimitives 16-bit Primitive struct data { start, numElements }
primitives (v24-) 32-bit U32 Array of numPrimitives 32-bit Primitive struct data { maxIndex }
primitives (v25+) 32-bit Primitive { S32 start, S32 numElements, U32 matIndex } Array of numPrimitives Primitives
numIndices 32-bit S32 Total number of vertex indices (all primitives)
indices (DTS v25-) 16-bit S16 Array of numIndices vertex indices
indices (DTS v25+) 32-bit S32 Array of numIndices vertex indices
numMergeIndices 32-bit S32 Number of merge indices. Note that merge indices have been deprecated.
mergeIndices 16-bit S16 Array of numMergeIndices merge indices
vertsPerFrame 32-bit S32 Number of vertices in each keyframe (position or UV)
flags 32-bit U32 Mesh flags
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)


If the mesh type is TSSkinMesh, the following data is stored in addition to the normal Mesh data:


Name Buffer Data Type Description
numInitialVerts 32-bit S32 Number of intial vert positions and normals
initialVerts 32-bit S32 Array of numInitialVerts positions
norms 32-bit Point3F { F32 x, F32 y, F32 z } Array of numInitialVerts vertex normals
encodedNorms 8-bit U8 Array of numInitialVerts encoded initial normal indices
numInitialTransforms 32-bit S32 Number of initial transforms
initialTransforms 32-bit MatrixF { F32 m[16] } Array of numInitialTransforms transforms
numVertIndices 32-bit S32 Number of vertex indices
vertIndices 32-bit S32 Array of numVertIndices vertex indices
numBoneIndices 32-bit S32 Number of bone indices
boneIndices 32-bit S32 Array of numBoneIndices bone indices
numWeights 32-bit S32 Number of weights
weights 32-bit F32 Array of numWeights bone weights
numNodeIndices 32-bit S32 Number of node indices
nodeIndices 32-bit S32 Array of node indices
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)


If the mesh type is TSSortedMesh, the following data is stored in addition to the normal Mesh data:

Name Buffer Data Type Description
numClusters 32-bit S32 Number of clusters
clusters 32-bit Cluster { S32 startPrimitive, S32 endPrimitive, Point3F normal, F32 k, S32 frontCluster, S32 backCluster } Array of numClusters Clusters
numStartClusters 32-bit S32 Number of start cluster indices
startClusters 32-bit S32 Array of numStartClusters start cluster indices
numFirstVerts 32-bit S32 Number of first vertex indices
firstVerts 32-bit S32 Array of numFirstVerts first vertex indices
numNumVerts 32-bit S32 Number of numVert counts
numVerts 32-bit S32 Array of numVert counts
numFirstTVerts 32-bit S32 Number of first TVert indices
firstTVerts 32-bit S32 Array of numFIrstTVerts first TVert indices
alwaysWriteDepth 32-bit S32 Always write depth flag
GUARD ALL S32, S16, S8 Buffer checkpoint (incrementing unit in each buffer)
⚠️ **GitHub.com Fallback** ⚠️