Direct3D Retained Mode Animated Header --DirectX File Format Architecture Direct3D Retained Mode Animated Header --DirectX File Format Architecture * Microsoft Direct3D Retained Mode SDK
*Index  *Topic Contents

*Previous Topic: DirectX File Format
*Next Topic: Appendix A: Templates

DirectX File Format Architecture


The Microsoft® DirectX® file format is an architecture- and context-free file format. It is template driven and is free of any usage knowledge. The file format may be used by any client application and currently is used by Microsoft® Direct3D® Retained Mode to describe geometry data, frame hierarchies and animations.

The rest of this section will deal with the content and syntax of the file format. The file format uses the extension .x when used with the DirectX Software Development Kit.

Reserved Words

The following words are reserved and must not be used:

Header

The variable length header is compulsory and must be at the beginning of the data stream. The header contains the following:

Type Sub Type Size Contents Content Meaning
Magic Number (required) 4 bytes "xof "
Version Number (required) Major Number 2 bytes 03 Major version 3
Minor Number 2 bytes 02 Minor version 2
Format Type (required) 4 bytes "txt " Text File
"bin " Binary File
"com " Compressed File
Compression Type (required 4 bytes "lzw "
if format type is compressed) "zip "
etc...
Float size (required) 4 bytes 0064 64 bit floats
0032 32 bit floats

Example

xof 0302txt 0064

Comments

Comments are only applicable in text files. Comments can occur anywhere in the data stream. A comment begins with either C++ style double-slashes "//", or a number sign "#". The comment runs to the next new line. 

# This is a comment.
// This is another comment.

Templates

Templates define how the data stream is interpreted—the data is modulated by the template definition. A template has the following form: 

template <template-name> {
<UUID>
<member 1>;
...
<member n>;
[restrictions]
}

This section discusses the following parts of a template:

Example templates are presented in Examples.

Template name

This is an alphanumeric name that may include the underscore character "_". It must not begin with a digit.

UUID

A universally unique identifier formatted to the Open Software Foundation's Distributed Distributed Computing Environment standard and surrounded by angle brackets "<" and ">". For example: <3D82AB43-62DA-11cf-AB39-0020AF71E433>

Members

Template members consist of a named data type followed by an optional name or an array of a named data type. Valid primitive data types are:

Type Size
WORD 16 bits
DWORD 32 bits
FLOAT IEEE float
DOUBLE 64 bits
CHAR 8 bits
UCHAR 8 bits
BYTE 8 bits
STRING NULL terminated string
CSTRING Formatted C-string (currently unsupported)
UNICODE UNICODE string (currently unsupported)

Additional data types defined by templates encountered earlier in the data stream can also be referenced within a template definition. No forward references are allowed.

Any valid data type can be expressed as an array in the template definition. The basic syntax is as follows: 

array <data-type> <name>[<dimension-size>];

Where <dimension-size> can either be an integer or a named reference to another template member whose value is then substituted.

Arrays may be n-dimensional, where n is determined by the number of paired square brackets trailing the statement. For example: 

array DWORD FixedHerd[24];
array DWORD Herd[nCows];
array FLOAT Matrix4x4[4][4];

Restrictions

Templates may be open, closed, or restricted. These restrictions determine which data types may appear in the immediate hierarchy of a data object defined by the template. An open template has no restrictions, a closed template rejects all data types, and a restricted template allows a named list of data types. The syntax is as follows:

Three periods enclosed by square brackets indicate an open template. 

[ ((( ]

A comma-separated list of named data types followed optionally by their UUIDs enclosed by square brackets indicates a restricted template. 

[ { data-type [ UUID ] , }... ]

The absence of either of the above indicates a closed template.

Examples

template Mesh {
<3D82AB44-62DA-11cf-AB39-0020AF71E433>
DWORD nVertices;
array Vector vertices[nVertices];
DWORD nFaces;
array MeshFace faces[nFaces];
 [ ... ]                // An open template
}
template Vector {
<3D82AB5E-62DA-11cf-AB39-0020AF71E433>
FLOAT x;
FLOAT y;
FLOAT z;
}                        // A closed template
template FileSystem {
<UUID>
STRING name;
[ Directory <UUID>, File <UUID> ]    // A restricted template
}

There is one special template—the Header template. It is recommended that each application define such a template, and use it to define application-specific information, such as version information. If present, this header will be read by the DirectX file format API, and if a flags member is available, it will be used to determine how the following data is interpreted. The flags member, if defined, should be a DWORD. One bit is currently defined—bit 0. If this bit is clear, the following data in the file is binary. If set, the following data is text. Multiple header data objects can be used to switch between binary and text within the file.

Data

Data objects contain the actual data or a reference to that data. Each has a corresponding template that specifies the data type.

Data objects have the following form: 

<Identifier> [name] {
<member 1>;
...
<member n>;
}

This section discusses the following parts of data objects:

Example templates are presented in Examples.

Identifier

This part is compulsory and must match a previously defined data type or primitive.

Name

This part is optional. (See earlier for the syntax definition.)

Members

Data members can be one of the following: data object, data reference, integer list, float list, or string list.

Data object

A nested data object. This allows the hierarchical nature of the file format to be expressed. The types of nested data objects allowed in the hierarchy may be restricted. See Templates earlier.

Data reference

A reference to a previously encountered data object. The syntax is as follows: 

{ name }

Integer list

A semicolon-separated list of integers. For example: 

1; 2; 3;

Float list

A semicolon-separated list of floats. For example: 

1.0; 2.0; 3.0;

String List

A semicolon-separated list of strings. For example: 

"Moose"; "Goats"; "Sheep";

Use of Commas and Semicolons

This is perhaps the most complex syntax issue in the file format, and it is very strict: Commas are used to separate array members; semicolons terminate every data item.

For example, if we have a template defined as: 

template mytemp {
DWORD myvar;
}

Then an instance of this would look like: 

mytemp dataTemp {
1;
}

Next, we have a template containing another template: 

template mytemp {
DWORD myvar;
DWORD myvar2;
}
template container {
FLOAT aFloat;
mytemp aTemp;
}

Then an instance of this would look like: 

container dataContainer {
1.1;
2; 3;;
}

Note that the second line that represents the mytemp inside container has two semicolons at the end of the line. The first indicates the end of the data item aTemp (inside container), and the second indicates the end of the container.

Next consider arrays. 

Template mytemp {
array DWORD myvar[3];
}

Then an instance of this would look like: 

mytemp aTemp {
1, 2, 3;
}

In the array case, there is no need for the data items to be separated by a semicolon because they are delineated by a comma. The semicolon at the end marks the end of the array.

Now consider a template that contains an array of data items defined by a template. 

template mytemp {
DWORD myvar;
DWORD myvar2;
}
template container {
DWORD count;
array mytemp tempArray[count];
}

Then an instance of this would look like: 

container aContainer {
3;
1;2;,3;4;,5;6;;
}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

*Top of Page