Imagine 3.0 Object Format

Converted to HTML by IanSmith@ncinter.net
A non-HTML version is also available.

Disclaimer:
All information contained herein is subject to change without notice. Knowledge is dangerous - use at your own risk. No warranties are made or implied, and no liability or responsibility is assumed. Good luck.

Contents

Scope - General Info - Data Types - Sub Sub Chunks - DESC Notes - PC Notes - IFF Notes
ANID - AXIS - BBOX - BBSG - BRS4 - CLST - COLR - EDGE - EFLG - FACE - FGR2 - FOGL - FOR2 - INT1 - NAME - PART - PNTS - POSI - PRP1 - PTFN - PTH2 - REFL - RLST - SBSG - SHP2 - SIZE - SPC1 - STDT - STID - STND - TLST - TRAN - TXT3 -

SCOPE:

GENERAL INFO:

The TDDD file is stored in Amiga (680x0) format, and conforms to the "IFF" file format on that computer. On IBM (80x86) based machines, much of the data refered to below will have to be byte reversed before it makes sense.

The IFF (interchange file format) format stores data in packets called "chunks." Each chunk begins with a long word identifier <ID> in ascii format. This identifier is immediately followed by a long word data-size. The data-size is measured in bytes and descrbes how much data, following the data-size long word, is part of the chunk identified by the <ID>. Imagine's IFF structure supports nesting of these chunks. For more info on the IFF standard, see the "Amiga ROM Kernal Reference Manual: Devices (3rd Edition)."

Currently, in "standard IFF" terms, a FORM TDDD has only one supported chunk type: an OBJ chunk describing the object heirarchy.

The OBJ chunk, in turn, is made up of smaller chunks with the standard IFF structure: <ID> <data-size> <data>.

The OBJ "sub-chunks" support object heirarchies. Currently, there are 2 types of supported OBJ sub-chunks: A DESC chunk, describing one node of a heirarchy; and a TOBJ chunk marking the end of a heirarchy chain. For each DESC chunk, there must be a corresponding TOBJ chunk.

In Imagine, the structure of the object heirarchy is as follows: Each heirarchy has a head (parent) object. The parent may have child objects. The children may have grandchildren, and so on. An object with children is a "grouped" object within Imagine.

Each object heirarchy is written in an OBJ chunk, along with all its descendants. The descendant heirarchy is supported as follows:

starting with the head (parent) object,

1) A DESC chunk is written, describing the object.
2) If the object in 1) has children, steps 1) thru 3) are performed for each child.
3) A TOBJ chunk is written, marking the end of the object description.

Reader software WILL FOLLOW the standard IFF procedure of skipping over any un-recognized chunks -- and "sub-chunks" or "sub-sub-chunks". The <data-size> field indicates how many bytes to skip. In addition it WILL OBSERVE the IFF rule that an odd <data-size> may appear, in which case the corredponding <data> field will be padded at the end with one extra byte to give it an even size.

DATA TYPES:

Second, there are several color (or RGB) fields in the data. They are always stored as three UBYTEs representing the red, green and blue components of the color. Red is always first, followed by green, and then blue. For some of the data chunks, Imagine reads the color field into the 24 LSB's of a LONGword. In such cases, the 3 RGB bytes are preceded by a zero byte in the file.

The three basic data types that will be refered to herein are:

    BYTE        :  a single byte of data (char) 

    WORD        :  a two byte data field (short) 

    LONG        :  a four byte data field (long) 

A "U" (ie. UBYTE) means unsigned.

The following "typedef"s are used below:

    typedef LONG    FRACT;                /* 4 bytes */ 

    typedef UBYTE   COLOR[3];             /* 3 bytes */
 

    typedef struct vectors { 

    

    

        FRACT X;          /* 4 bytes */ 

        FRACT Y;          /* 4 bytes */ 

        FRACT Z;          /* 4 bytes */ 

    
 

    } VECTOR;             /* 12 bytes total */ 

 

    typedef struct matrices { 

    
 

        VECTOR I;         /* 12 bytes */ 

        VECTOR J;         /* 12 bytes */ 

        VECTOR K;         /* 12 bytes */ 

    
 

    } MATRIX;             /* 36 bytes total */ 

 

    typedef struct _tform { 

    
 

        VECTOR r;         /* 12 bytes - position */ 

        VECTOR a;         /* 12 bytes - x axis */ 

        VECTOR b;         /* 12 bytes - y axis */ 

        VECTOR c;         /* 12 bytes - z axis */ 

        VECTOR s;         /* 12 bytes - size */ 

    
 

    } TFORM;              /*  60 bytes total */ 

 

    typedef struct _pthd { 

    
 

        TFORM   PData;    /* axis data */ 

        UWORD   inFrom;   /* previous axis number */ 

        UWORD   outTo;    /* next axis number */ 

        UWORD   flags;    /* flags for this axis */ 

                          /*   Bit 0 - reserved - zero for "Detail Editor" paths 

                          /*   Bit 1 - an axis connects in to this axis 

                          /*   Bit 2 - an axis connects out of this axis 

                          /*   Bits 3 thru 15 - reserved 

        UWORD   pad;      /* reserved */ 

    
 

    } PTHD; 

DESC SUB-SUB-CHUNKS:

NAME - size 18

    BYTE    Name[18]        ; a name for the object.

Object's name as it appears in the attributes requester. Used for tracking, etc.

SHP2 - size 4

    WORD    Shape;          ; number indicating object type 

    WORD    Lamp;           ; bit field indicating lamp type 

Valid shape numbers are:
0 - Sphere
2 - Axis ; custom objects with points/faces
5 - Ground
1, 3, and 4 are reserved, and should never appear in TDDD files.

Perfect spheres have thier radius set by the X size parameter (see SIZE chunk). A ground object is an infinte plane perpendicular to the world Z axis. Its Z coordinate sets its height, and the X and Y coordinates are only relevant to the position of the "hot point" used in selecting the object in the editor (see POSI chunk). Custom objects have points, edges and triangles associated with them. Imagine's primative objects are cumstom (type 2) objects. The size fields are relevant only for drawing the object axes in the editor.

Lamp numbers are composed of several bit fields:

Bit 0 - Point light source.
Bit 1 - Parallel light source.
Bit 2 - Round shape.
Bit 3 - Rectangular shape.

Bit 4 - No Lens Flare FX flag.
Bit 5 - 1/R Diminishing intensity.
Bit 6 - Controlled falloff.
Bit 7 - Cast Shadows.

Bits 8 to 14 - reserved.
Bit 15 - Bright object.

For a light casting object, bit 0 or 1 must be set - all other bits are optional. All lights emminate from the object's axes (see POSI, SIZE, and AXIS chunk) and shadow casting lights will be blocked by faces that have neither fog nor transparent attributes.

POSI - size 12

    VECTOR  Position;       ; the object's position.

This is the position (in world coordinates) of the object's axes. Legal coordinates are in the range -32768 to 32767 and 65535/65536.

AXIS - size 36

    VECTOR  XAxis; 

    VECTOR  YAxis; 

    VECTOR  ZAxis;

These are direction vectors for the object coordinate system. They must be "orthogonal unit vectors" (ortho-normal) - i.e. the sum of the squares of the vector components must equal one (or close to it), and the vectors must be perpendicular.

SIZE - size 12

    VECTOR  Size;       ; object size info

See SHP2 chunk above. The sizes are used in a variety of ways depending on the object shape. For custom objects and lights, they are the lengths of the coordinate axes drawn in the editor.

BBOX - size 24

    FRACT bounds[6];           ;bounding box data

The descriptions of the bounds array is as follows:

bounds[0] - negative X boundary (relative to object axis position)
bounds[1] - negative Y boundary
bounds[2] - negative Z boundary
bounds[3] - posative X boundary
bounds[4] - posative Y boundary
bounds[5] - posative Z boundary

This chunk contains the objects bounding box info for use in improving redraw and loading speed when using Imagine's quick stage mode.

STND - variable size

The data in an STND chunk consists only of smaller sub-chunks. STID and STDT are the only types defined so far.

This is Imagine's state data chunk. There is a STND chunk for each (named) state in an object. Each STND chunk will contain a STID (state ID) chunk followed by one or several STDT (state data) chunks. (see STID and STDT chunks)

STID - size 20

    BYTE stid[18];      ; state name 

    UWORD stFlags;      ; state flags 

                        ;   Bit 0 - contains axis data (group) 

                        ;   Bit 1 - contains shape data (points) 

                        ;   Bit 2 - contains color/properties data 

                        ;   Bits 3 thru 15 - reserved 

This chunk contains the state name and a description of the type of data assiciated with this state. This chunk will only appear within a STND chunk and is usually followed by one or more STDT chunks.

STDT - variable size

    WORD tag;               ; state data type tags 

                            ;   tag values are as follows: 

                            ;   101 - contains object axis info 

                            ;   102 - contains point (vertex) data 

                            ;   103 - contains path data 

                            ;   104 - contains axis size data 

                            ;   105 - contains face color data (CLIST) 

                            ;   106 - contains face filter data (TLST) 

                            ;   107 - contains face reflect data (RLST) 

                            ;   108 - contains object attribute data 

                            ;   all other values are reserved 

    WORD flags;             ; state data flags 

    BYTE stateData[size];   ; state data - variable size 

This is the state data chunk. The tag value describes what kind of information is actually stored within the stateData[] array. This chunk will only appear within a STND chunk and will be preceded by either a STID chunk or another STDT chunk. The stateData[] array is interpreted as follows depending upon the tag type:
tag = 101 - contains object axis info - saved with grouping


            VECTOR axis_r;           ; axis position vector 

            MATRIX axis_m;           ; axis alignment vectors
        

(48 bytes total)

See AXIS and POSI chunks.

tag = 102 - contains point (vertex) data - saved with shape


            VECTOR obj_points[point_count];     ; object's points in 3 space
        

(12 * point_count bytes total)

point_count = point count for object - e.g. from PNTS chunk

tag = 103 - contains path data - saved with shape

            PTHD pdata[ACount];        ; path data for object
        

(68 * ACount bytes total)

ACount = axis count for object - e.g. from PTH2 chunk

tag = 104 - contains axis size data - saved with shape


            VECTOR size;            ; object size info
        

(12 bytes total)

See SIZE chunk.

tag = 105 - contains face color data (CLST) - saved with properties


            COLOR   colors[face_count];          ; color values
        

(face_count * 3 bytes total)

face_count = face count for object - e.g. from FACE/CLST,...

tag = 106 - contains face filter data (TLST) - saved with properties


            COLOR   filter[face_count];          ; filter values 

        

(face_count * 3 bytes total)

face_count = face count for object

tag = 107 - contains face reflect data (RLST) - saved with properties


            COLOR   reflect[face_count];          ; reflect values 

        

(face_count * 3 bytes total)

face_count = face count for object

tag = 108 - contains object attribute data - saved with properties


            UBYTE   props[8];           ; object properties (PRP1 chunk) 
 

            UWORD   lamp;               ; bit field - lamp type (SHP2 chunk) 
 

            UWORD   flags;              ; reserved 
 

            VECTOR  intensity;          ; light intensity (INT1 chunk) 
 

            FRACT   foglen;             ; value of foglength (FOGL chunk) 
 

            UBYTE   color[4];           ; object color  (COLR chunk) 
 

            UBYTE   reflect[4];         ; object reflectance (REFL chunk) 
 

            UBYTE   filter[4];          ; object transparency (TRAN chunk) 
 

            UBYTE   specular[4];        ; object specularity (SPC1 chunk) 

        

(44 bytes total) Note that the properties state does not save texture/brush info, only object base attributes. See PRP1, SHP2, INT1, FOGL, COLR, REFL, TRAN, SPC1 chunks.

PNTS - size 2 + 12 * point count

    UWORD   PCount;                    ; point count 

    VECTOR  Points[point_count];       ; points

This chunk has all the points for custom (type 2 - axis) objects. point_count is the total number of points on the object. Edges will refer to these points by thier position in the Points[] array (i.e. the point numbers appearing below run from 0 through point_count - 1).

EDGE - size 2 + 4 * edge_count

    UWORD   ECount;                   ; edge count 

    UWORD   Edges[edge_count][2];     ; edges

This chunk contins the edge list for custom objects. The Edges[][2] array is pairs of point numbers that are connected by the edges. The values of Edges[n][0] and Edges[n][1] will thus be between 0 and point_count - 1, and the Points[] array will have to be refered to to find the endpoint positions of this edge. Faces will refer to these edges by thier position in the Edges[][] array (i.e. the edge numbers appearing below run from from 0 to edge_count - 1). (See PNTS chunk)

FACE - size 2 + 6 * face count

    UWORD   FCount;         ; face count 

    UWORD   Faces[][3];     ; faces

This chunk contains the triangle (face) list for custom objects. The Faces[][3] array is triples of edge numbers that are connected to form triangles. This Back references through the Edge list and then through the Point list to find the 3 space coordinates of the face's vertexes. (See EDGE and PNTS chunks) Note: it is possible that the edge numbers given for a face would use more than 3 point numbers all together ... this should be considered as an error ... however, Imagine doesn't enforce the desired constsistency when objects are loaded. This can lead to some confusion when testing "first time" code, since Imagine sometimes uses only the first two edge numbers, assumeing that the 3rd edge is constsient with the 1st two.

PTH2 - size 2 + 68 * axis count

    UWORD   ACount;         ; axis count 

    PTHD    PData[ACount];  ; path (axis) data

This chunk contains the axis data for Imagine "path" objects. ACount is the number of axes in the path object. The PData array contains a bit of data for each point (axis) along the path. A closed path is made by setting the value of the inFrom[] variable of the first axis to the number of the last axis, and setting the outTo[] variable of the last axis to the number of the first axis (1). An open path will have to have the flags[] bits 1 (or 2) clear, showing that the first (or last) axis is only connected on one side ... the 1st axis should show a "connected out" flag, and the last axis should show a "connected in" flag only.

COLR - size 4
REFL - size 4
TRAN - size 4
SPC1 - size 4

    BYTE    pad;            ; pad byte - must be 

    COLOR   col;            ; RGB color

These are the main object RGB color, and reflection, transmission and specularity coefficients.

CLST - size 2 + 3 * face_count
RLST - size 2 + 3 * face_count
TLST - size 2 + 3 * face_count

    UWORD   face_count;                  ; number of faces 

    COLOR   colors[face_count];          ; colors

These are the color, reflection and transmission coefficients for each face in custom (type 2 - axis) objects. The face_count has to match the face count in the FACE chunk. The ordering corresponds to the face order. When the objects main attributes are altered, the new color values are copied into the whole colors[] array. Modifying color values in face mode or choosing "randomize colors" from the attributes requester will independantly alter the values in the colors[][] array. This chunk appears in all custom (type 2 - axis) objects.

TXT3 - variable size

    UWORD   Flags;          ; texture flags: 

                            ;     Bit  0         - apply to child objs 

                            ;     Bits 1 thru 15 - reserved 

    TFORM   TForm;          ; local coordinates of texture axes. 

    FRACT   Params[16];     ; texture parameters 

    UBYTE   PFlags[16];     ; parameter flags for texture requester 

                            ;   Bit 0 - alter red color in color chip 

                            ;   Bit 1 - alter green color in color chip 

                            ;   Bit 2 - alter blue color in color chip 

                            ;   Bit 3 - alter parameter when resizing object 

                            ;   Bits 4 thru 7 - reserved 

    BYTE    SubGr[18];      ; Subrgoup to restrict texture to 

    BYTE    LockState[18];  ; State name for "texture tacking" 

    UBYTE   Length;         ; length of texture file name 

    UBYTE   Name[Length];   ; texture file name (not NULL terminated) 

    UBYTE   optionalpad;    ; appears only if the name string has an even 

                            ; length -- so the total length of the name 

                            ; "block" (length + name + pad?) comes out even 

This chunk contains the texture data necessary for the renderer to communicate with Imagine's procedural texture modules and for positioning textures on objects. Subgr[], if used, restricts the texture application to the named subgroup. LockState[], if used, will lock (tack) the texture to the object's faces for object morphing without texture sliding. The values in Params[] are tweened (interpolated) internally by Imagine when morphing/animating textures. A TXT3 chunk appears for each texture applied to an object.

BRS4 - variable size

    UWORD   Flags;          ; brush type: 

                            ;    0 - Color 

                            ;    1 - Reflectivity 

                            ;    2 - Filter 

                            ;    3 - Altitude 

                            ;    4 - Reflection 

    UWORD   WFlags;         ; brush wrapping flags: 

                            ;    Bit 0 - wrap x 

                            ;    Bit 1 - wrap z 

                            ;    Bit 2 - apply to children 

                            ;    Bit 3 - repeat brush 

                            ;    Bit 4 - mirror with repeats 

                            ;    Bit 5 - inverse video 

                            ;    Bit 6 - Use genlock 

    TFORM   TForm;          ; local coordinates of brush axes. 

    UWORD   FullScale;      ; full scale value 

    UWORD   MaxSeq;         ; highest number for sequenced brushes 

    BYTE    SubGr[18];      ; Subrgoup to restrict brush to 

    BYTE    LockState[18];  ; Brush lockstate 

    UBYTE   Length;         ; length of brush file name 

    UBYTE   Name[Length];   ; brush file name (not NULL terminated) 

    UBYTE   optionalpad     ; if name has even length (see TXT3 description) 

This chunk contains the brush data necessary for the renderer to load and position brush maps (texture maps) on objects. FullScale is used to map the highest color value within a brush map to full-scale 255 for Imagine's internal interpritation of the brush. Subgr[], if used, restricts the brush application to the named subgroup. LockState[], if used, will lock (tack) the brush to the object's faces for object morphing without texture sliding. The value in MaxSeq is tweened (interpolated) internally, from 1 to MaxSeq, by Imagine when animating brushes - this way, brush morphing can be accomplished. A BRS4 chunk appears for each brush map applied to an object.

FOGL - size 4

FRACT foglen; ; value of foglength attribute

This is the object foglength set in Imagine's attributes requester.

PRP1 - size 8

    UBYTE   IProps[8];       ; more object properties

The discriptions of the IProps array is as follows:

IProps[0] - dithering factor (0-255)
IProps[1] - hardness factor (0-255)
IProps[2] - roughness factor (0-255)
IProps[3] - shinyness factor (0-255)
IProps[4] - index of refraction - ir = (float)IProps[4] / 100.0 + 1.0;
IProps[5] - quickdraw type: 0=none, 1=bounding box, 2=quick edges
IProps[6] - flag - Phong shading on/off
IProps[7] - flag - Genlock on/off

The dithering factor controls the amount of color dithering used on the object - 255 is fully dithered. The hardness factor controls how tight the specular spot should be - 0 is a big soft spot, 255 is a tight hot spot The roughness factor controls how rough the object should appear - 0 is smooth, 255 is max roughness. The shiny factor in interaction with the object's filter values controls how shiny the object appears. Setting it to anything but zero forces the object to be non-transparent since then the filter values are used in the shiny (reflection) calculations. A value of 255 means maximum shinyness.

INT1 - size 12

    VECTOR  Intensity;      ; light intensity

This has seperate R, G & B intensities for the light objects. Note that these color values are stored as FRACT's and are not limited to the 0 to 255 range of the usual UBYTE color values so lights can be brighter than 255 255 255.

ANID - size 64

    LONG    Cellno;         ; cell number ("key" cell) 

    TFORM   TForm;          ; object position/axes/size in that cell.

For Imagine's "Cycle" objects, within EACH DESC chunk in the file - that is, for each object of the group, there will be a series of ANID chunks. The cell number sequences of each part of the group must agree with the sequence for the head object, and the first cell number must be zero.

FOR2 - size 56 + 12 * PC + 2 * keys

    WORD    NumC;               ; number of cross section points 

    WORD    NumF;               ; number of slices 

    WORD    Flags;              ; forms object type flag 

                                ;   Bit 0 - X-Y Cross Section 

                                ;   Bit 1 - One Former View 

                                ;   Bit 2 - One Spacer View 

                                ;   Bits 3 thru 15 - reserved 

                                ;   (bit 0 off means Y-Z Cross Section) 

                                ;   (bits 1 and 2 off means Two Former Views) 

    WORD    keys;               ; number of defined key sections 

    MATRIX  TForm;              ; object rotation/scaling transformation 

    VECTOR  Shift;              ; object translation 

    VECTOR  Points[PC];         ; "Forms" editor points 

    WORD    sexions[keys];      ; list of key sections by number 

For Imagine's "Forms" objects, the "PNTS" chunk above is not written out, but this structure is written instead. The object's real points are then calculated from these using a proprietary algorithm. The tranformation parameters above allow the axes of the real object be moved around relative to the "Forms" points. The value, PC, is calculated as follows:
for Two Former Views:

PC = keys * NumC + 4 * NumF;

for One Former View:

PC = keys * NumC + 2 * NumF;

for One Spacer View:

PC = keys * NumC + 1 * NumF;

PART - size 6

    WORD type;          ; tells what type of particles to use 

                        ;   bits 0-3:  shape 

                        ;       0x0000 - faces (no particles) 

                        ;       0x0001 - tetrahedrons 

                        ;       0x0002 - pyramids 

                        ;       0x0003 - octahedrons 

                        ;       0x0004 - cubes 

                        ;       0x0005 - blocks 

                        ;       0x0006 - dodecahedrons 

                        ;       0x0007 - spheres 

                        ;       0x0008 - random 

                        ;       0x0009 - use object file 

                        ;   bits 4-7:  centering 

                        ;       0x0000 - inscribed 

                        ;       0x0010 - circumscribed 

                        ;       0x0020 - interpolated 

                        ;       0x0030 - barycentric 

                        ;   bits 8-11:  size 

                        ;       0x0000 - small 

                        ;       0x0100 - large 

                        ;       0x0200 - random 

                        ;       0x0300 - specify 

                        ;   bits 12-15:  alignment 

                        ;       0x0000 - to object 

                        ;       0x1000 - to face 

                        ;       0x2000 - random 

    FRACT size;         ; used with specify size 

This is the main object particalization parameters. This chunk describes the geometry of the particles to be used in place of the objects faces. The PTFN chunk contains the file name of the "use object file" type of particles, and the FGR2 chunk contains the particle geometry info for specific sub groups. Particles only work on custom (type 2 - axis) objects with faces. (see PTFN and FGR2 chunks)

PTFN - variable size

    BYTE length;                 ; number of characters in the file name 

    BYTE PartFileName[length];   ; particle file name (not null terminated) 

    BYTE optionalpad;            ; appears only if name has an even length 

                                 ; (see TXT3 description) 

For Imagine's particalized objects. This is the filename for the "use
object file" type of particlization. (see PART chunk)

FGR2 - variable size

    UWORD faceCount;            ; the number of faces in this subgroup 

    BYTE  subGrName[18];        ; the name of the subgroup 

    UWORD faceNums[faceCount];  ; the list of faces in this subgroup 

    UWORD pType;                ; subgroup particle type - see PART chunk 

    FRACT pSize;                ; subgroup particle size - see PART chunk 

    UBYTE pFNSize;              ; character count in the particle file name 

    BYTE  pFName[pFNSize];      ; particle filename - see PTFN chunk 

    BYTE  optionalpad;          ; appears only if name has an even length 

This is the Subgroup info for Imagine's custom (type 2 - axis) objects which have subgroups - the mnemonic, FGR2, stands for face group. pType, pSize, pFNSize, and pFName all deal with particalized subgroups. The faceNums[] array is a list of faces by numerical position in the face list as described in the FACE chunk. Valid face numbers run from zero through object_face_count - 1.

BBSG - size 18

    BYTE bbsg[18];      ; big bone subgroup name

This is the Big Bone SubGroup name used with the bones function in Imagine. By design, BBSG will appear in the DESC chunk of a particular bone (usually an axis), and will refer to a subgroup name in a FGR2 chunk of the parent object of this entire group. (note: the "Bones" functions also assume that a state named DEFAULT appears in the state list of the group's parent object, containing at least "shape" and "grouping" data) (also, see SBSG chunk below)

SBSG - size 18

    BYTE sbsg[18];      ; small bone subgroup name

This is the Small Bone SubGroup name used with the bones function in Imagine. By design, SBSG will appear in the DESC chunk of a particular bone (usually an axis), and will refer to a subgroup name in a FGR2 chunk of the parent of this entire group. (see BBSG chunk above)

EFLG - 2 + edge_count

    WORD    edge_count;                 ; the number of edges on the object 

    UBYTE   edgeFlag[edge_count];       ; array of edge flags for each edge 

                                        ;   Bits 0 thru 5 - reserved 

                                        ;   Bit 6 - quick edge 

                                        ;   Bit 7 - sharp edge 

This chunk contains the flag values for all the edges of custom (type 2 - axis) objects with edges. These flags currently support the quick edge and sharp edge flags. (Note: Imagine writes this chunk only if one or more edges in the object actually has bit 6 or 7 set)

DESC notes

Again, most of these fields are optional, and some defaults are supplied. However, if there is a FACE chunk, there must also be a CLST chunk, an RLST chunk and a TLST chunk -- all with matching "count" fields. The SHP2 chunk is not optional.

Your best bet in understanding the relationship between chunks (what's required, and what's not) will probably be through creating objects within Imagine, saving them out, and then interrogating and comparing the TDDD files.

The order in which the chunks appear is somewhat irrelevant. Some of the chunks contain a point count, or something similar, and some of them (STDT chunks) don't actually contain a count, but are based on a count. Imagine assigns the appropriate count based on the first occurence of a chunk whose size would depend on the count, and then enforces consitency as succeding chunks are processed.

For TXT3 and BRS4 (texture and brush) chunks, the order in which the chunks appear in the file determines the order they are listed in Imagine, and also the order in which they are applied during rendering.

For Imagine's "Quick Stage" mode, the DESC chunks are processed only until a certain minimum amount of data has been read in, and then it skips to the end of the DESC chunk. The "required" fields (in order to skip to the end) are NAME, POSI, ALGN, SIZE, SHP2 and BBOX. If state data (i.e. Bones data) is required from the object for stage animation, then it must appear before at least one of the "required" fields listed above, or it will be ignored -- similarly for cycle editor data (ANID chunks), and path (PTH2) data. For example, Imagine does the following: 1) writes all of the "required" chunks listed above except for the BBOX chunk, 2) writes ANID chunks (if any), 3) writes STND chunks (if any), 4) writes a PTH2 chunk (if reqd), 5) writes a BBOX chunk, and finally, 6) writes the rest of the data.

Unfortunately, Impulse does not have the support staff available to answer technical questions about the information included in this document. Hopefully, this will be a good starting point. How far you get with it will, most likely, be dependent upon hard work and perseverance.

Good Luck and Enjoy.

PC (80x86 CPU) notes

The IFF file format originated on machines in which the byte order for LONG (4 byte) and WORD (2 byte) data is "most significant byte first". This concept has been preserved in the "PC" versions of Imagine.

What it means, is that if you are writing code for the "other" type of CPU (80386 code, for example), you will need to reverse the byte ordering in (U)LONG, FRACT, and (U)WORD data wherever it appears (e.g. the FRACTs in a VECTOR structure must be (separatly) byte reversed ... the size field following a chunk identifier is another good example)

IFF file format notes

In case you are unfamiliar with the IFF file structure, the TDDD files have the following (simple, "single FORM") IFF structure:

form_ID           4 characters:  'F','O','R','M' 

form_size         LONG size   : -- MSB(yte) first 

form_type         4 characters:  'T','D','D','D' 

chunks: 

    chunk_ID      4 characters: e.g. 'O','B','J',' ' 

    chunk_size    LONG size   : -- byte reversed if appropriate 

    chunk_data    'size' bytes: 

    chunk_pad     0 or 1 bytes: -- pad to even length if 'size' is odd 

Note:

The "form_size" field appearing after the "form_ID" is the total length of the data that FOLLOWS it, INCLUDING the 4-byte (TDDD) id. Also the "chunk_size" fields list the size of the data in the "chunk_data" blocks that follow. In other words, the size fields when rounded up to an even number, always list the number of bytes (after the size field) to skip forward in the file if, based on the ID field preceding the size, the reader can not or does not wish to interpret the data ... so, in particular, the sizes that appear DO NOT include the length of the ID and size fields themselves, and the 'form_size' DOES include 4 bytes for the 'form_type' field that follows it.

Last Update: July 13, 1995
Back to Ian's HomePage