Imagine 3.0 Object Format

Rev 3.0 05-19-94 S.Kirvan
Copyright 1994 Impulse Inc., Mpls, MN 55444

Converted to HTML by
A non-HTML version is also available.


Scope - General Info - Data Types - Sub Sub Chunks - DESC Notes - PC Notes - IFF Notes


This text will describe Imagine 3.0's basic object file format. It is beyond the scope of this text to describe any of the file formats used for spline objects, deform tool, or any other object types not mentioned below. However, some of the data described below may apply to some of these undocumented object formats. It is also not the intent of this document to explain the implementation of the information contained in the TDDD files (ie. what equations we use to represent Imagine's paths - lighting models - forms geometry - tweening algorithms, etc.).


FORM TDDD is used by Impulse's Imagine 3.0 for 3D rendering data. TDDD stands for "3D data description". The files contain 3D object definitions, and can be extended to describe different types of object information.

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:

The TOBJ sub-chunks have zero size -- and no data. The DESC sub-chunks are made up of "sub-sub-chunks", again, with the standard IFF structure: <ID> <data-size> <data>.

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.


First, there are several numerical fields appearing in the data, describing object positions, rotation angles, scaling factors, etc. They are stored as "32-bit fractional" numbers, such that the true number is the 32-bit number divided by 65536. So as an example, the number 3.14159 is stored as (hexadecimal) 0x0003243F (ie. 0x0003243F / 65536 = 3.14159). This allows the data to be independant of any particular floating point format. Numbers stored in this format are typedef'ed as "FRACT"s below.

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.


NAME - size 18

SHP2 - size 4

POSI - size 12

AXIS - size 36

SIZE - size 12

BBOX - size 24

STND - variable size

STID - size 20

STDT - variable size

PNTS - size 2 + 12 * point count

EDGE - size 2 + 4 * edge_count

FACE - size 2 + 6 * face count

PTH2 - size 2 + 68 * axis count

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

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

TXT3 - variable size

BRS4 - variable size

FOGL - size 4

PRP1 - size 8

INT1 - size 12

ANID - size 64

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

PART - size 6

PTFN - variable size

FGR2 - variable size

BBSG - size 18

SBSG - size 18

EFLG - 2 + edge_count

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'
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


Imagine uses "extended sub-chunks" -- where for some chunk types, the data actually consists of a series of smaller chunks, in the same IFF form: ID/Size/Data/pad_byte_if_neccesary. In fact, the only "true" IFF chunk that imagine recognizes is the 'OBJ ' chunk -- which contains the complete data for a single heirarchy (group) of objects. Things are as they are, mainly for historical reasons ... once upon a time, TDDD files were also used to hold all the data for a single frame in an animation, and several 'OBJ ' chunks could appear, as well as more chunks giving data about the camera position, etc. Now, when Imagine writes a TDDD file, it contains only a single 'OBJ ' chunk. Imagine will still process a file containing multiple 'OBJ ' chunks, but in all cases, except when it loads a file into its "Detail Editor", it ignores all but the first object heirarchy.

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