Home

Have a look at the insides of the Racer file formats.

The DOF file format is used for storing 3D models. Racer v0.3 used DOF0, but has been superseded by DOF1 since 27-12-00 and really hasn't changed during the years. The format allows easy skipping of chunks that future/previous versions might not know about.

DOF's are stored in binary format and use Intel endianness (just about all processors in PC's these days use the same format). Largely inspired by the IFF format (but not completely taken over), the format contains 3 conceptual levels, all indicated by 4-character identifiers. Each chunk begins with a char[4] identifier followed by a 32-bit integer size that indicates the size (in bytes) of the chunk data that follows. No padding is used (this is different from the original IFF specifications). This allows readers to skip chunks they don't know anything about, just by skipping those bytes and trying to go on, hoping not too miss any important information.

DOF files store 3D data and basic material info. More detailed rendering information is stored in .shd (Racer shader) files. These should not be confused with GPU shaders; those can be referenced in the .shd files.

Level 1; objects

• DOF1; marks the header. It is followed by a 32-bit integer, indicating the length of the DOF1 object to come (0x1D1 in the file below).
• EDOF; marks the end of the DOF

Level 2; object components

• MATS; indicates a series of materials coming up. Following by an int indicating the chunk length. After that, another integer follows, indicating the number of materials to come.
• GEOB; indicates a series of geobs, or Geometrical Objects (I use the term Geode for Geometrical Node, loosely based on SGI's Performer's notion of constructing scene graphs). It also, like MATS, is following by 'int chunkLength, noofGeobs'.
• MAT0; a material, followed by the chunk length (skip this if you don't know about MAT0's).
  A note about strings:
  Strings are stored as; short length; char text[length].
  In the example case below, both MAT0 strings are empty (2x 0x0000).
  Also note that strings can make the alignment of the rest of the file odd (meaning a string of length 11 will align oncoming identifiers on odd (file) addresses, which may be a performance issue if you load the whole file and peek your way through).
  
• GOB1; a geob definition. Followed by the length.

Level 3; object component attributes

These you will find inside the MAT0 and GOB1 chunks. Note that each chunk is directly followed by its length, to make sure future extensions can be easily put in and out. This is with the exception of the GEND and MEND chunks (those do not have a length added)!
First a description of MAT0:

• MHDR; a header:
  qstring name,className;
  
• MCOL; a color chunk, containing:
  float ambient[4];
float diffuse[4];
float specular[4];
float emission[4];
float shininess;
• MCFL; material creation flags.
  int creationFlags;
flags&1 -> environment mapped
  Note that the envmap flag is ignored under v0.5.2; there it is the shader that defines what happens (much more flexible).
• MUVW; some UVW mapping information for texturing:
  float uvwUoffset;
float uvwVoffset;
float uvwUtiling;
float uvwVtiling;
float uvwAngle;
float uvwBlur;
float uvwBlurOffset;
• MTRA; transparency and blendMode
  float transparency; (unused)
int blendMode; (0=no blending, 1=BLEND_SRC_ALPHA=source alpha blending, 2=BLEND_CONST=constant color blending (unused))
• MTEX; textures (names only, )
  int textures;
qstring mapName[textures];
NOTE: no full paths allowed, just the filename part. Maps will be searched in the model images/ path (or from an explicitly given path).
  
• MSUB; submaterials.
  int submaterials;
MAT0[submaterials]; (recursive)
Submaterials were used mainly for Max's Multi/Sub-object materials. However, this gives some problems using indexed primitives, so I don't use it anymore. Try not to use Multi/Sub-materials but use plain materials instead (which is the most general case).
  The MAT0[] contains ofcourse the entire MAT0 specification in itself.
• MEND; ends a material definition (must be checked for; more material chunks may be added in the future). Note this doesn't have an added length attribute.
  

Next, a description of a GOB1 (geometrical definition, or geob):

• GHDR; header
  int flags; (none defined yet; actually the contents of this field are not used from v0.8.3 onwards; you still have to write them though (just use 0))
int paintFlags; (none defined yet)
int materialRef; (the material index)

• INDI; indices (indexed primitives are used in GOB1)
  int indices;
short index[indices];
The index[] array contains indices into the vertex, tvertex etc. arrays. This allows vertex data (position, normal, color etc) to be re-used, and is especially useful on T&L enabled hardware, since on that hardware you have a small cache that remembers the last few transformed & lit vertices. So locality of triangles may mean that the triangle vertices are still in the cache and don't need to be transformed & lit again.
• VERT; vertices (triangle data only)
  int vertices;
float vertex[vertices*3];

• TVER; texture coordinates (2D only)
  int tvertices;
float tvertex[tvertices*2];

• NORM; normals (optional, although they may not render without them)
  int normals;
float normal[normals*3];
Note that the normals array will normally be the same length as that of VERT (since GOB1 uses indexed primitives, so for every vertex, there is 1 texture coordinate pair (tvertex) and 1 normal.
  
• VCOL; vertex colors (optional)
  int vertexColors;
float vcolor[vertexColors*3];
Note that the vertex color array will normally be the same length as that of VERT (since GOB1 uses indexed primitives, so for every vertex, there is 1 vertex color. Each color is an RGB triplet; each color varies from 0..1.
  
• BRST; burst information (bursts of equal-state triangles)
  int bursts;
int burstStart[bursts]; (start in vertex[] for the first burst vertex)
int burstCount[bursts]; (number of floats in vertex[] to use for this burst)
int burstMtlID[bursts]; (material selection for this burst)
int burstVperP[bursts]; (should always be 3 for all bursts)
Note that burstStart/burstCount has a bit of a weird counting mechanism. They don't count elements, but rather real floats, so when using glDrawElements(), you would need to specify a start of burstStart[i]/3 and a count of burstCount[i]/3. This is needed to perhaps support non-triangle data (it did before, but using only triangles is much easier on a lot of the algoritmhs involved).
  In the future, perhaps strips will be supported (making a distinction between lists/strips/fans).
  For just about any DOF out there, you can assume bursts=1, burstStart[0]=0. burstVPerP[0]=3 as well.
  The burstMtlID[0] then is the material index of the geode. burstCount[0] is the number of floating points in the vertex array, so it is vertices*3.
  Bursts>1 is used for multi/sub ASE imports, but in practice this never seems to be used (and is as such probably not even supported in Racer's graphics engine).
• GEND; ends a geob definition (must be checked for; more geob chunks will be added in the future). Note this doesn't have an added length attribute! (Racer v0.5.2 gives a warning if it detects a possible length attribute).

General notes about the file format:

• It uses little-endian integers (Intel)
• Note you could concatenate multiple DOF1's in a single file; it doesn't rely on an end-of-file to end the DOF description.
• The XYZ system used is that of OpenGL, so X+ is right, Y+ is up and Z+ is out of the screen (and righthanded).

Here's a hex dump of a small model; a rectangle generated originally from a SCGT shadow 'model':

  
  00000000: 44 4f 46 31 d1 01 00 00 4d 41 54 53 c1 00 00 00   DOF1....MATS....
  00000010: 01 00 00 00 4d 41 54 30 b5 00 00 00 4d 48 44 52   ....MAT0....MHDR
  00000020: 04 00 00 00 00 00 00 00 4d 43 4f 4c 44 00 00 00   ........MCOLD...
  00000030: cd cc 4c 3e cd cc 4c 3e cd cc 4c 3e cd cc 4c 3e   ..L>..L>..L>..L>
  00000040: 00 00 80 3f 00 00 80 3f 00 00 80 3f 00 00 80 3f   ...?...?...?...?
  00000050: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 80 3f   ...............?
  00000060: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 80 3f   ...............?
  00000070: 00 00 00 00 4d 55 56 57 1c 00 00 00 00 00 00 00   ....MUVW........
  00000080: 00 00 00 00 00 00 80 3f 00 00 80 3f 00 00 00 00   .......?...?....
  00000090: 00 00 00 00 00 00 00 00 4d 54 52 41 08 00 00 00   ........MTRA....
  000000a0: 00 00 00 00 00 00 00 00 4d 54 45 58 11 00 00 00   ........MTEX....
  000000b0: 01 00 00 00 0b 00 56 45 43 53 48 41 44 2e 42 4d   ......VECSHAD.BM
  000000c0: 50 4d 53 55 42 04 00 00 00 00 00 00 00 4d 45 4e   PMSUB........MEN
  000000d0: 44 47 45 4f 42 fc 00 00 00 01 00 00 00 47 4f 42   DGEOB........GOB
  000000e0: 31 f4 00 00 00 47 48 44 52 0c 00 00 00 00 00 00   1....GHDR.......
  000000f0: 00 00 00 00 00 00 00 00 00 49 4e 44 49 10 00 00   .........INDI...
  00000100: 00 06 00 00 00 00 00 01 00 02 00 00 00 02 00 03   ................
  00000110: 00 56 45 52 54 34 00 00 00 04 00 00 00 cc cc c9   .VERT4..........
  00000120: c2 00 00 8c c1 33 b3 4d 43 99 99 c6 42 00 00 8c   .....3.MC...B... 
  00000130: c1 33 b3 4d 43 99 99 c6 42 00 00 8c c1 66 e6 38   .3.MC...B....f.8
  00000140: c3 cc cc c9 c2 00 00 8c c1 66 e6 38 c3 54 56 45   .........f.8.TVE
  00000150: 52 24 00 00 00 04 00 00 00 00 00 80 3f 00 00 80   R$..........?...
  00000160: bf 00 00 80 3f 00 00 00 00 00 00 00 00 00 00 00   ....?...........
  00000170: 00 00 00 00 00 00 00 80 bf 4e 4f 52 4d 34 00 00   .........NORM4..
  00000180: 00 04 00 00 00 00 00 00 00 00 00 80 3f 00 00 00   ............?...
  00000190: 00 00 00 00 00 00 00 80 3f 00 00 00 00 00 00 00   ........?.......
  000001a0: 00 00 00 80 3f 00 00 00 00 00 00 00 00 00 00 80   ....?...........
  000001b0: 3f 00 00 00 00 42 52 53 54 14 00 00 00 01 00 00   ?....BRST.......
  000001c0: 00 00 00 00 00 12 00 00 00 00 00 00 00 03 00 00   ................
  000001d0: 00 47 45 4e 44 45 44 4f 46                        .GENDEDOF

(last updated July 3, 2009 )