MD2

.md2 File Format Specification

by "> Daniel E. Schoenblum

INTRO

This page will try and give some sort of technical documentation on the Quake2 model format (.md2).

These specs can be used freely for whatever you want. I only ask that people ">send me corrections, suggestions, etc.

Quake2 models are stored in files with the .md2 extension. This is a custom format used only by Quake2 and (probably) Quake2 mission packs. md2 files can be generated from various other file formats by tools provided freely by id, in original and modified form. A single md2 file contains the model's geometry, frame information, skin filename(s), and texture coordinates. The file is little-endian (intel byte ordering).

HEADER

The header comes right at the start of the file. The information in the header is needed to load different parts of the model.

typedef struct
{
   int [#model_magic">magic];
   int [#model_version">version];
   int [#model_skinWidth">skinWidth];
   int [#model_skinHeight">skinHeight];
   int [#model_frameSize">frameSize];
   int [#model_numSkins">numSkins];
   int [#model_numVertices">numVertices];
   int [#model_numTexCoords">numTexCoords];
   int [#model_numTriangles">numTriangles];
   int [#model_numGlCommands">numGlCommands];
   int [#model_numFrames">numFrames];
   int [#model_offsetSkins">offsetSkins];
   int [#model_offsetTexCoords">offsetTexCoords];
   int [#model_offsetTriangles">offsetTriangles];
   int [#model_offsetFrames">offsetFrames];
   int [#model_offsetGlCommands">offsetGlCommands];
   int [#model_offsetEnd">offsetEnd];
} model_t;

<a name="model_magic">]

int magic: A "magic number" used to identify the file. The magic number is 844121161 in decimal (0x32504449 in hexadecimal). The magic number is equal to the int "IDP2" (id polygon 2), which is formed by ('I' + ('D' << 8) + ('P' << 16) + ('2' << 24)).

<a target="_top" name="model_version">] int version: Version number of the file. Always 8.

<a target="_top" name="model_skinWidth">] int skinWidth: Width of the skin(s) in pixels.

<a target="_top" name="model_skinHeight">] int skinHeight: Height of the skin(s) in pixels.

<a target="_top" name="model_frameSize">] int frameSize: Size of each [#FRAMES">frame] in bytes.

<a target="_top" name="model_numSkins">] int numSkins: Number of skins associated with this model.

<a target="_top" name="model_numVertices">] int numVertices: Number of [#triangleVertex">vertices] in each frame.

<a target="_top" name="model_numTexCoords">] int numTexCoords: Number of texture coordinates (not necessarily the same as the number of vertices).

<a target="_top" name="model_numTriangles">] int numTriangles: Number of triangles in each frame.

<a target="_top" name="model_numGlCommands">] int numGlCommands: Number of dwords (4 bytes) in the gl command list.

<a target="_top" name="model_numFrames">] int numFrames: Number of [#FRAMES">frames].

<a target="_top" name="model_offsetSkins">] int offsetSkins: Offset, in bytes from the start of the file, to the list of skin names.

<a target="_top" name="model_offsetTexCoords">] int offsetTexCoords: Offset, in bytes from the start of the file, to the list of texture coordinates.

<a target="_top" name="model_offsetTriangles">] int offsetTriangles: Offset, in bytes from the start of the file, to the list of triangles.

<a target="_top" name="model_offsetFrames">] int offsetFrames: Offset, in bytes from the start of the file, to the list of [#FRAMES">frames].

<a target="_top" name="model_offsetGlCommands">] int offsetGlCommands: Offset, in bytes from the start of the file, to the gl command list.

<a target="_top" name="model_offsetEnd">] int offsetEnd: Offset, in bytes from the start of the file, to the end (size of the file).

<a name="FRAMES">]

FRAMES

Each frame contains the positions in 3D space for each vertex of each triangle that makes up the model. Quake 2 (and Quake) models contain only triangles.

<a name="triangleVertex">] typdef struct
{
   byte [#triangleVertex_vertex">vertex][3];
   byte [#triangleVertex_lightNormalIndex">lightNormalIndex];
} triangleVertex_t;


<a target="_top" name="triangleVertex_vertex">] byte vertex[3]: The three bytes represent the x, y, and z coordinates of this vertex. This is not the "real" vertex coordinate. This is a scaled version of the coordinate, scaled so that each of the three numbers fit within one byte. To scale the vertex back to the "real" coordinate, you need to first multiply each of the bytes by their respective float [#frame_scale">scale] in the [#frame">frame_t] structure, and then add the respective float [#frame_translate">translation ], also in the [#frame">frame_t] structure. This will give you the vertex coordinate relative to the model's origin, which is at the origin, (0, 0, 0).

<a target="_top" name="triangleVertex_lightNormalIndex">] byte lightNormalIndex: This is an index into a table of normals kept by Quake2. To get the table, you need to download ">this zip file (1.7 MB), released by [http://www .idsoftware.com">id], that has the source code to all of the tools they used for quake2.

typedef struct
{
   float [#frame_scale">scale][3];
   float [#frame_translate">translate][3];
   char [#frame_name">name][16];
   [#triangleVertex">triangleVertex_t] [#frame_vertices">vertices][1];
} frame_t;


frame_t is a variable sized structure, however all frame_t structures within the same file will have the same size ([#model_numVertices">numVertices] in the [#model">header])

<a target="_top" name="frame_scale">] float scale[3]: This is a scale used by the [#triangleVertex_vertex">vertex] member of the [#triangleVertex">triangleVertex_t] structure.

<a target="_top" name="frame_translate">] float translate[3]: This is a translation used by the [#triangleVertex_vertex">vertex] member of the [#triangleVertex">triangleVertex_t] structure.

<a target="_top" name="frame_name">] char name[16]: This is a name for the frame.

<a target="_top" name="frame_vertices">] [#triangleVertex">triangleVertex_t] vertices[1]: An array of [#model_numVertices">numVertices] [#triangleVertex">triangleVertex_t] structures.

<a name="TRIANGLES">]

TRIANGLES

Quake 2 models are made up of only triangles. At [#model_offsetTriangles">offsetTriangles] in the file is an array of [#triangle">triangle_t] structures. The array has [#model_numTriangles">numTriangles] structures in it.

<a name="triangle">]

typedef struct
{
   short [#triangle_vertexIndices">vertexIndices][3];
   short [#triangle_textureIndices">textureIndices][3];
} triangle_t;


<a target="_top" name="triangle_vertexIndices">] short vertexIndices: These three shorts are indices into the array of [#frame_vertices">vertices] in each [#frame">frames]. In other words, the number of triangles in a md2 file is fixed, and each triangle is always made of the same three indices into each frame's array of vertices. So, in each frame, the triangles themselves stay intact, their vertices are just moved around.

<a target="_top" name="triangle_textureIndices">] short textureIndices: These three shorts are indices into the array of [#textureCoordinate">texture coordinates].

<a name="SKINS">]

SKINS

<a name="SKINS">]

There is an array of [#model_numSkins">numSkins] skin names stored at [#model_offsetSkins">offsetSkins] into the file. Each skin name is a char[64]. The name is really a path to the skin, relative to the base game directory (baseq2 f or "standard" Quake2). The skin files are regular pcx files.

<a name="textureCoordinate">]

typedef struct
{
   short [#textureCoordinate_st">s], [#textureCoordinate_st">t];
} textureCoordinate_t;


<a target="_top" name="textureCoordinate_t">] short s, t: These two shorts are used to map a vertex onto a skin. The horizontal axis position is given by s, and the vertical axis position is given by t. The range for s is greater than or equal to 0 and less than [#model_skinWidth">skinWidth] (0 <= s < skinWidth). The range for t is greater than or equal to 0 and less than [#model_skinHeight">skinHeight] (0 <= s < skinHeight). Note that the ranges are different than in the [#glCommandVertex_s">s] and [#glCommandVertex_t">t] members of the [#glCommandVertex">glCommandVertex] structure.

<a name="GL_COMMANDS">]

GL COMMANDS

<a name="GL_COMMANDS">]At [#model_offsetGlCommands">offsetGlCommands]<a name="GL_COMMANDS">] bytes into the file, there is the gl command list, which is made up of a series of [#model_numGlCommands">numGlCommands]<a name="GL_COMMANDS">] int's and float's, organized into groups. Each group starts with an int. If it is positive, it is followed by that many [#glCommandVertex">glCommandVertex_t]<a name="GL_COMMANDS">] structures, which form a triangle strip. If it is negative, it is followed by -x [#glCommandVertex">glCommandVertex_t]<a name="GL_COMMANDS">] structures, which fo rm a triangle fan. A 0 indicates the end of the list. The list is an optimized way of issuing commands when rendering with ">OpenGl<a name="GL_COMMANDS">]. <a name="glCommandVertex">]

typedef struct
{
   float [#glCommandVertex_st">s], [#glCommandVertex_st">t];
   int [#glCommandVertex_vertexIndex">vertexIndex];
} glCommandVertex_t;


<a target="_top" name="glCommandVertex_t">] float s, t: These two floats are used to map a vertex onto a skin. The horizontal axis position is given by s, and the vertical axis position is given by t. The range for s and for t is 0.0 to 1.0. Note that the ranges are different than in the [#textureCoordinate">textureCoordinate_t]<a target="_top" name="glCommandVertex_t">] structure. They are stored as floats here because that's the way Quake2 passes them to ">OpenGl<a target="_top" name="glCommandVertex_t">].

<a target="_top" name="glCommandVertex_vertexIndex">] int vertexIndex: Index into the array of [#frame_vertices">vertices]<a target="_top" name="glCommandVertex_vertexIndex">] stored in each [#frame">frame]<a target="_top" name="glCommandVertex_vertexIndex">].

MAXIMUMS

Quake2 has some pre-defined limits, so that dynamic memory does not need to be used. You can use these to your advantage to speed up loading if you want.

• [#TRIANGLES">Triangles]: 4096
• [#triangleVertex">Vertices]: 2048
• [#textureCoordinate">Texture Coordinates]: 2048
• [#FRAMES">Frames]: 512
• [#SKINS">Skins]: 32

Quake and Quake2 are trademarks of ">id Software.
All trademarks used are properties of their respective owners.

<a name="glCommandVertex">]

<a name="textureCoordinate">]

<a name="triangle">]