Dts format {documentation artist guide formats}

Contents 1 Introduction 2 DTS Format 3 Sequences 4 Bitsets 4 Data Buffers 4 Meshes 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) Home Back to Top