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.

This following sections 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 (SDK).

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 Subtype 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
"tzip" MSZip Compressed Text File
"bzip" MSZip Compressed Binary File
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. This section discusses the following aspects of a template:

Example templates are presented in Examples.

Template form

A template has the following form. 

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

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 (UUID) formatted to the Open Software Foundation's 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 as follows:

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>];

<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 for indicating an open template is three periods enclosed by square brackets. 

[ ... ]

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. 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] { [<UUID>]
<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

Name 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 for more information.

Data reference

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

{
  name |
  UUID |
  name UUID
}

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 topic 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 each data item.

For example, if a template is defined as: 

template mytemp {
DWORD myvar;
}

Then an instance of this template would look like: 

mytemp dataTemp {
1;
}

A template containing another template is defined as: 

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

Then an instance of this template 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 semicolon indicates the end of the data item, aTemp (inside container), and the second semicolon indicates the end of the container.

If an array is defined as: 

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 semicolons because they are delineated by commas. The semicolon at the end marks the end of the array.

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;;
}

Top of Page Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.