DirectX .x templates: Mesh, Material, Frame and the rest

These are the standard templates that DirectX defines for geometry, materials and scene structure, as Microsoft’s DirectX 9 documentation lists them, with the declarations written as they would be in a file. A reader recognises a template by its UUID, not its name. The templates for animation and skinning are on Animation and skinning, and the codes inside FVFData, DeclData and VertexElement on Vertex data codes.

Basic types

template Vector {
 <3D82AB5E-62DA-11cf-AB39-0020AF71E433>
 float x;
 float y;
 float z;
}

template Coords2d {
 <F6F23F44-7686-11cf-8F52-0040333594A3>
 float u;
 float v;
}

template Matrix4x4 {
 <F6F23F45-7686-11cf-8F52-0040333594A3>
 array float matrix[16];
}

template ColorRGBA {
 <35FF44E0-6C7C-11cf-8F52-0040333594A3>
 float red;
 float green;
 float blue;
 float alpha;
}

template ColorRGB {
 <D3E16E81-7835-11cf-8F52-0040333594A3>
 float red;
 float green;
 float blue;
}

template IndexedColor {
 <1630B820-7842-11cf-8F52-0040333594A3>
 DWORD index;
 ColorRGBA indexColor;
}

template Boolean {
 <537da6a0-ca37-11d0-941c-0080c80cfa7b>
 DWORD truefalse;
}

template Boolean2d {
 <4885AE63-78E8-11cf-8F52-0040333594A3>
 Boolean u;
 Boolean v;
}

template MaterialWrap {
 <4885ae60-78e8-11cf-8f52-0040333594a3>
 Boolean u;
 Boolean v;
}

template Guid {
 <a42790e0-7810-11cf-8f52-0040333594a3>
 DWORD data1;
 WORD data2;
 WORD data3;
 array UCHAR data4[8];
}

The basic types, closed templates used inside the others.

Template	Meaning
`Vector`	A 3D vector: a position or a normal
`Coords2d`	A texture coordinate (u, v)
`Matrix4x4`	A 4 × 4 matrix of 16 floats, used for frame transforms. Files written by D3DX store it in the memory order of a D3DX matrix, row by row in Direct3D’s row-vector convention, so the translation is in elements 12, 13 and 14
`ColorRGBA`	A colour with alpha, each component normally 0 to 1
`ColorRGB`	A colour without alpha
`IndexedColor`	A colour for the vertex numbered `index`
`Boolean`	0 for false, 1 for true
`Boolean2d`	Two Booleans, one for u and one for v, used by `MeshFaceWraps`
`MaterialWrap`	The same, for texture coordinates that run from 0 to 2 instead of 0 to 1
`Guid`	A GUID in its binary form, for use inside other templates

Meshes

template Mesh {
 <3D82AB44-62DA-11CF-AB39-0020AF71E433>
 DWORD nVertices;
 array Vector vertices[nVertices];
 DWORD nFaces;
 array MeshFace faces[nFaces];
 [...]
}

template MeshFace {
 <3D82AB5F-62DA-11cf-AB39-0020AF71E433>
 DWORD nFaceVertexIndices;
 array DWORD faceVertexIndices[nFaceVertexIndices];
}

template MeshNormals {
 <F6F23F43-7686-11cf-8F52-0040333594A3>
 DWORD nNormals;
 array Vector normals[nNormals];
 DWORD nFaceNormals;
 array MeshFace faceNormals[nFaceNormals];
}

template MeshTextureCoords {
 <F6F23F40-7686-11cf-8F52-0040333594A3>
 DWORD nTextureCoords;
 array Coords2d textureCoords[nTextureCoords];
}

template MeshVertexColors {
 <1630B821-7842-11cf-8F52-0040333594A3>
 DWORD nVertexColors;
 array IndexedColor vertexColors[nVertexColors];
}

template MeshMaterialList {
 <F6F23F42-7686-11CF-8F52-0040333594A3>
 DWORD nMaterials;
 DWORD nFaceIndexes;
 array DWORD faceIndexes[nFaceIndexes];
 [Material <3D82AB4D-62DA-11CF-AB39-0020AF71E433>]
}

template MeshFaceWraps {
 <ED1EC5C0-C0A8-11D0-941C-0080C80CFA7B>
 DWORD nFaceWrapValues;
 array Boolean2d faceWrapValues[nFaceWrapValues];
}

template VertexDuplicationIndices {
 <B8D65549-D7C9-4995-89CF-53A9A8B031E3>
 DWORD nIndices;
 DWORD nOriginalVertices;
 array DWORD indices[nIndices];
}

template FaceAdjacency {
 <A64C844A-E282-4756-8B80-250CDE04398C>
 DWORD nIndices;
 array DWORD indices[nIndices];
}

The mesh and the objects that may be nested in it.

Template	Member	Meaning
`Mesh`	`vertices`	The positions, numbered from 0
	`faces`	Each face lists its vertex numbers; a face may have any number of corners
	`[...]`	Open: usually holds `MeshNormals`, `MeshTextureCoords`, `MeshVertexColors`, `MeshMaterialList` and the skinning and declaration templates
`MeshNormals`	`normals`	A separate list of normals
`MeshNormals`	`faceNormals`	One entry per face of the mesh, giving for each corner the number of its normal; so normals are indexed per corner, not per vertex
`MeshTextureCoords`	`textureCoords`	One coordinate per vertex of the mesh, in vertex order
`MeshVertexColors`	`vertexColors`	Colours for vertices, each naming its vertex; Microsoft’s page writes the type as `IndexColor`, a misprint for `IndexedColor`
`MeshMaterialList`	`nMaterials`	How many materials the mesh uses
	`faceIndexes`	For each face, the number of its material, from 0
	`[Material]`	The materials themselves, in order, nested or as references such as `{ RedMaterial }`
`MeshFaceWraps`	`faceWrapValues`	For each face, whether the texture wraps in u and in v. No longer used
`VertexDuplicationIndices`	`indices`	For each vertex, the number it had before vertices were duplicated at smoothing or material boundaries; equal numbers mean the same original vertex. `nOriginalVertices` is the count before duplication
`FaceAdjacency`	`indices`	Face adjacency information for the mesh. Microsoft’s page repeats the description of `VertexDuplicationIndices` here, so the exact layout is not documented; D3DX adjacency arrays hold three neighbouring face numbers per triangle

Retained Mode filled in missing parts as follows: no MeshFaceWraps, no wrapping; no MeshTextureCoords, no texture coordinates; no MeshNormals, normals computed; no MeshVertexColors, white; no MeshMaterialList, a white material.

Materials

template Material {
 <3D82AB4D-62DA-11CF-AB39-0020AF71E433>
 ColorRGBA faceColor;
 FLOAT power;
 ColorRGB specularColor;
 ColorRGB emissiveColor;
 [...]
}

template TextureFilename {
 <A42790E1-7810-11cf-8F52-0040333594A3>
 string filename;
}

A material and its optional texture.

Member	Meaning
`faceColor`	The diffuse colour, with alpha for transparency
`power`	The specular exponent
`specularColor`	The colour of highlights
`emissiveColor`	The colour the surface gives off by itself
`[...]`	Usually a `TextureFilename`; without one the faces are untextured
`filename`	The texture’s file name

The template has no ambient colour.

Frames

template Frame {
 <3D82AB46-62DA-11CF-AB39-0020AF71E433>
 [...]
}

template FrameTransformMatrix {
 <F6F23F41-7686-11cf-8F52-0040333594A3>
 Matrix4x4 frameMatrix;
}

A frame of reference and its local transform.

A Frame is a node of the scene hierarchy, and the bones of a skinned mesh are frames too. It is open; the D3DX loaders recognise a FrameTransformMatrix, Mesh objects and child Frame objects inside it, and pass other templates to the program. The matrix gives the frame’s transform relative to its parent; without one, no local transform applies. Meshes inside a frame may be written in place or as references.

Patch meshes

template Patch {
 <A3EB5D44-FC22-429D-9AFB-3221CB9719A6>
 DWORD nControlIndices;
 array DWORD controlIndices[nControlIndices];
}

template PatchMesh {
 <D02C95CC-EDBA-4305-9B5D-1820D7704BBF>
 DWORD nVertices;
 array Vector vertices[nVertices];
 DWORD nPatches;
 array Patch patches[nPatches];
 [ ... ]
}

template PatchMesh9 {
 <B9EC94E1-B9A6-4251-BA18-94893F02C0EA>
 DWORD Type;
 DWORD Degree;
 DWORD Basis;
 DWORD nVertices;
 array Vector vertices[nVertices];
 DWORD nPatches;
 array Patch patches[nPatches];
 [ ... ]
}

Meshes made of Bézier patches. PatchMesh is the older form.

Each patch lists the numbers of its control points among the mesh’s vertices, in a spiral order. The number of control points gives the kind of patch:

Control points	Patch
10	Cubic Bézier triangular patch
15	Quartic Bézier triangular patch
16	Cubic Bézier rectangular patch

The codes in PatchMesh9:

Member	Value	Name	Meaning
`Type`	1	`D3DXPATCHMESH_RECT`	Rectangle patches
	2	`D3DXPATCHMESH_TRI`	Triangle patches
	3	`D3DXPATCHMESH_NPATCH`	N-patches
`Degree`	1	`D3DDEGREE_LINEAR`	First order
	2	`D3DDEGREE_QUADRATIC`	Second order
	3	`D3DDEGREE_CUBIC`	Third order
	5	`D3DDEGREE_QUINTIC`	Fifth order (Microsoft’s page says “fourth”, a slip)
`Basis`	0	`D3DBASIS_BEZIER`	The vertices are Bézier control points
	1	`D3DBASIS_BSPLINE`	The vertices are B-spline control points; the surface does not in general pass through them
	2	`D3DBASIS_CATMULL_ROM`	An interpolating basis: the surface passes through every vertex (called `D3DBASIS_INTERPOLATE` in DirectX 8)

Progressive meshes

template PMInfo {
 <B6C3E656-EC8B-4b92-9B62-681659522947>
 DWORD nAttributes;
 array PMAttributeRange attributeRanges[nAttributes];
 DWORD nMaxValence;
 DWORD nMinLogicalVertices;
 DWORD nMaxLogicalVertices;
 DWORD nVSplits;
 array PMVSplitRecord splitRecords[nVSplits];
 DWORD nAttributeMispredicts;
 array DWORD attributeMispredicts[nAttributeMispredicts];
}

template PMAttributeRange {
 <917E0427-C61E-4a14-9C64-AFE65F9E9844>
 DWORD iFaceOffset;
 DWORD nFacesMin;
 DWORD nFacesMax;
 DWORD iVertexOffset;
 DWORD nVerticesMin;
 DWORD nVerticesMax;
}

template PMVSplitRecord {
 <574CCC14-F0B3-4333-822D-93E8A8A08E4C>
 DWORD iFaceCLW;
 DWORD iVlrOffset;
 DWORD iCode;
}

D3DX’s progressive mesh data.

D3DX uses these to save a progressive mesh, one that can be refined or simplified vertex by vertex. Microsoft marks all three “not supported” and for internal use by D3DX only, and does not explain the members beyond their names: the vertex split records and the encoding of iCode are undocumented.

Effects

template EffectInstance {
 <E331F7E4-0559-4cc2-8E99-1CEC1657928F>
 STRING EffectFilename;
 [ ... ]
}

template EffectParamFloats {
 <3014B9A0-62F5-478c-9B86-E4AC9F4E418B>
 STRING ParamName;
 DWORD nFloats;
 array float Floats[nFloats];
}

template EffectParamString {
 <1DBC4C88-94C1-46ee-9076-2C28818C9481>
 STRING ParamName;
 STRING Value;
}

template EffectParamDWord {
 <E13963BC-AE51-4c5d-B00F-CFA3A9D97CE5>
 STRING ParamName;
 DWORD Value;
}

template EffectFloats {
 <F1CFE2B3-0DE3-4e28-AFA1-155A750A282D>
 DWORD nFloats;
 array float Floats[nFloats];
}

template EffectString {
 <D55B097E-BDB6-4c52-B03D-6051C89D0E42>
 STRING Value;
}

template EffectDWord {
 <622C0ED0-956E-4da9-908A-2AF94F3CE716>
 DWORD Value;
}

A material’s effect file and its parameters.

An EffectInstance names a Direct3D effect (.fx) file, and the parameter objects nested in it set the effect’s parameters by name. The last three are the older forms without a parameter name, replaced by the EffectParam… templates.

Retained Mode templates

Direct3D Retained Mode, the first user of the format, declared a few templates that are not in the DirectX 9 list. Their declarations below are as published in Paul Bourke’s copy of the original specification and in Wine’s copy of the rmxftmpl.x file; Microsoft no longer documents them, and their meaning is known only from their names unless stated.

template Header {
 <3D82AB43-62DA-11CF-AB39-0020AF71E433>
 WORD major;
 WORD minor;
 DWORD flags;
}

template Quaternion {
 <10DD46A3-775B-11cf-8F52-0040333594A3>
 FLOAT s;
 Vector v;
}

template InlineData {
 <3A23EEA0-94B1-11D0-AB39-0020AF71E433>
 [ BINARY ]
}

template Url {
 <3A23EEA1-94B1-11D0-AB39-0020AF71E433>
 DWORD nUrls;
 array STRING urls[nUrls];
}

template ProgressiveMesh {
 <8A63C360-997D-11D0-941C-0080C80CFA7B>
 [ Url, InlineData ]
}

template StringProperty {
 <7F0F21E0-BFE1-11D1-82C0-00A0C9697271>
 STRING key;
 STRING value;
}

template PropertyBag {
 <7F0F21E1-BFE1-11D1-82C0-00A0C9697271>
 [ StringProperty ]
}

template ExternalVisual {
 <98116AA0-BDBA-11D1-82C0-00A0C9697271>
 Guid guidExternalVisual;
 [ ... ]
}

template RightHanded {
 <7F5D5EA0-D53A-11D1-82C0-00A0C9697271>
 DWORD bRightHanded;
}

Retained Mode templates outside the DirectX 9 list.

Header is described on Header and compression. The original specification says Quaternion was unused. The older specification also gives different UUIDs for two templates that DirectX 9 keeps: Boolean as 4885AE61-78E8-11cf-8F52-0040333594A3 and MeshFaceWraps as 4885AE62-78E8-11cf-8F52-0040333594A3. The UUIDs given above for those two are the ones in the DirectX 9 documentation and in Wine’s template file.

.X File Format – Mesh and frame templates