Infographie 3D
Documentation du format de fichier Imagine (vielle version)

[ Retour ]


This documentation is a copy of the Impulse Documentation file format, the original can be found at Impulse

Informations don't reflect the last file format from Imagine for Windows, there's some new chunks (PNT2 , EDG2 , FAC2 ) ,now vertices , edges and faces count are in LONG and not INT (When Impulse stop changing object file format ?)

This file reflect the last file format version


FORM TDDD is used by Impulse's Turbo Silver 3.0 for 3D rendering data. TDDD stands for "3D data description". The files contain object and (optionally) observer data.

Turbo Silver's successor, "Imagine", uses an upgraded FORM TDDD when it reads/writes object data.

Currently, in "standard IFF" terms, a FORM TDDD has only two chunk types: an INFO chunk describing observer data; and an OBJ chunk describing an object heirarchy. The INFO chunk appears only in Turbo Silver's "cell" files, and the OBJ chunk appears in both "cell" files and "object" files.

The FORM has an (optional) INFO chunk followed by some number of OBJ chunks. (Note: OBJ is followed by a space -- ckID = "OBJ ")

The INFO and OBJ chunks, in turn, are made up of smaller chunks with the standard IFF structure: .

The INFO "sub-chunks" are relatively straightforward to interpret.

The OBJ "sub-chunks" support object heirarchies, and are slightly more difficult to interpret. Currently, there are 3 types of OBJ sub-chunks: an EXTR chunk, describing an "external" object in a seperate file; 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. And an EXTR chunk is equivalent to a DESC/TOBJ pair.

In Turbo Silver and Imagine, the structure of the object heirarchy is as follows. There is a head object, and its (sexist) brothers. Each brother may have child objects. The children may have grandchildren, and so on. The brother nodes are kept in a doubly linked list, and each node has a (possibly NULL) pointer to a doubly linked "child" list. The children point to the "grandchildren" lists, and so on. (In addition, each node has a "back" pointer to its parent).

Each of the "head" brothers is written in a seperate OBJ chunk, along with all its descendants. The descendant heirarchy is supported as follows:

for each node of a doubly linked list,

  • 1) A DESC chunk is written, describing its object.
  • 2) If it has children, steps 1) to 3) are performed for each child.
  • 3) A TOBJ chunk is written, marking the end of the children.

For "external" objects, steps 1) to 3) are not performed, but an EXTR chunk is written instead. (This means that an external object cannot have children unless they are stored in the same "external" file).

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

( "External" objects were used by Turbo Silver to allow a its "cell" data files to refer to an "object" data file that is "external" to the cell file. Imagine abandons the idea of individual cell files, and deals only in TDDD "object" files. Currently, Imagine does not support EXTR chunks in TDD files.)

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

Now, on with the details.

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) $0003243F. This allows the data to be independant of any particular floating point format. And it (actually) is the internal format used in the "integer" version of Turbo Silver. Numbers stored in this format are called 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, Turbo Silver 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 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 */

The following structure is used in generating animated cells from a single cell. It can be attached to an object or to the camera. It is also used for Turbo Silver's "extrude along a path" feature. (It is ignored & forgotten by Imagine)

    typedef struct story {                        
UBYTE Path[18]; /* 18 bytes */
VECTOR Translate; /* 12 bytes */
VECTOR Rotate; /* 12 bytes */
VECTOR Scale; /* 12 bytes */
UWORD info; /* 2 bytes */
} STORY; /* 56 bytes total */

The Path[] name refers to a named object in the cell data. The path object should be a sequence of points connected with edges. The object moves from the first point of the first edge, to the last point of the last edge. The edge ordering is important. The path is interpolated so that the object always moves an equal distance in each frame of the animation. If there is no path the Path[] field should be set to zeros.

The Translate vector is not currently used. The Rotate "vector" specifies rotation angles about the X, Y, and Z axes.

The Scale vector specfies X,Y, and Z scale factors. The "info" word is a bunch of bit flags:

ABS_TRA0x0001- translate in world coorinates (not used)
ABS_ROT0x0002- rotation in world coorinates
ABS_SCL0x0004- scaling in world coorinates
LOC_TRA0x0010- translate in local coorinates (not used)
LOC_ROT0x0020- rotation in local coorinates
LOC_SCL0x0040- scaling in local coorinates
X_ALIGN0x0100- (not used)
Y_ALIGN0x0200- align Y axis to path's direction
Z_ALIGN0x0400- (not used)
FOLLOW_ME0x1000- children follow parent on path

DESC sub-sub-chunks

  • POSI - size 12
    • VECTOR Position; (1)
    • (1) the object's position. Legal coordinates are in the range -32768 to 32767 and 65535/65536. Currently, the ray-tracer only sees objects in the -1024 to 1024 range. Light sources, and the camera may be placed outside that range, however.
  • AXIS - size 36
    • VECTOR XAxis;
    • VECTOR YAxis;
    • VECTOR ZAxis;
    • These are direction vectors for the object coordinate system. They must be "orthogonal unit vectors" - i.e. the sum of the squares of the vevtor components must equal one (or close to it), and the vectors must be perpendicular.
  • SIZE - size 12
    • VECTOR Size;
    • See SHAP chunk above. The sizes are used in a variety of ways depending on the object shape. For custom objects, they are the lengths of the coordinate axes drawn in the editor. If the object has its "Quickdraw" flag set, the axes lengths are also used to set the size of a rectangular solid that is drawn rather than drawing all the points and edges.
  • PNTS - size 2 + 12 * point count
    • UWORD PCount; (1)
    • VECTOR Points[]; (2)
    • (1) ; point count
    • (2) points
      This chunk has all the points for custom objects. The are refered to by thier position in the array.
  • EDGE - size 4 + 4 * edge cout
    • UWORD ECount; (1)
    • UWORD Edges[][2]; (2)
    • (1) 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. Edges are refered to by thier position in the Edges[] array.
  • FACE - size 2 + 6 * face count
    • UWORD TCount; (1)
    • UWORD Connects[][3]; (2)
    • (1) face count
    • (2) faces
      This chunk contains the triangle (face) list for custom objects. The Connects[][3] array is triples of edge numbers that are connected by triangles.
  • PTHD - size 2 + 6 * axis count - Imagine only
    • UWORD ACount; (1)
    • TFORM PData[][3]; (2)
    • (1) axis count
    • (2) axis data
      This chunk contains the axis data for Imagine "path" objects. The PData array contains a TFORM structure for each point along the path. The "Y size" item for the last point on the path tells whether the path is closed or not. Zero means closed, non-zero means open. Otherwise the Y size field is the distance along the path to the next path point/axis.
  • COLR - size 4
  • REFL - size 4
  • TRAN - size 4
  • SPC1 - size 4 - Imagine only
    • BYTE pad; (1)
    • COLOR col; (2)
    • (1) pad byte - must be zero
    • (2) RGB color
      These are the main object RGB color, and reflection, transmission and specularity coefficients.
  • CLST - size 2 + 3 * count
  • RLST - size 2 + 3 * count
  • TLST - size 2 + 3 * count
  • TPAR - size 64 - not written by Imagine - see TXT1 below
    • FRACT Params[16]; (1)
    • (1) texture parameters
      This is the list of parameters for texture modules when texture mapping is used.
  • TXT1 - variable size - Imagine only
      This chunk contains texture data when texture mapping is used.
    • UWORD Flags; (1)
    • TFORM TForm; (2)
    • FRACT Params[16]; (3)
    • UBYTE PFlags[16]; (4)
    • UBYTE Length; (5)
    • UBYTE Name[Length]; (6)
    • UBYTE pad; (7)
    • (1) texture flags:
      1 - TXTR_CHILDREN - apply to child objs
    • (2) local coordinates of texture axes.
    • (3) texture parameters
    • (4) parameter flags (currently unused)
    • (5) length of texture file name
    • (6) texture file name (not NULL terminated)
    • (7) (if necessary to make an even length)
  • BRS1 - variable size - Imagine only (version 1.0)
  • BRS2 - variable size - Imagine only (version 1.1)
    • UWORD Flags; (1)
    • UWORD WFlags; (2)
    • TFORM TForm; (3)
    • UWORD FullScale; (4)
    • UWORD MaxSeq; (5)
    • UBYTE Length; (6)
    • UBYTE Name[Length]; (7)
    • UBYTE pad; (8)
    • (1) brush type:
      • 0 - Color
      • 1 - Reflection
      • 2 - Filter
      • 3 - Altitude
    • (2) brush wrapping flags:
      • 1 WRAP_X - wrap type
      • 2 WRAP_Z - wrap type
      • 4 WRAP_CHILDREN - apply to children
      • 8 WRAP_REPEAT - repeating brush
      • 16 WRAP_FLIP - flip with repeats
    • (3) local coordinates of brush axes.
    • (4) full scale value
    • (5) highest number for sequenced brushes
    • (6) length of brush file name
    • (7) brush file name (not NULL terminated)
    • (8) (if necessary to make an even length)
      The FullScale and MaxSeq items are in BRS2 chunks only.
  • SURF - size 5 - not written by Imagine
    • BYTE SProps[5]; (1)
    • (1) object properties
      This chunk contains object (surface) properties used by Turbo Silver.
      • SProps[0] - PRP_SURFACE
        surface type
        • 0 - normal
        • 4 - genlock
        • 5 - IFF brush
      • SProps[1] - PRP_BRUSH
        brush number (if IFF mapped)
      • SProps[2] - PRP_WRAP
        IFF brush wrapping type
        • 0 - no wrapping
        • 1 - wrap X
        • 2 - wrap Z
        • 3 - wrap X and Z
      • SProps[3] - PRP_STENCIL
        stencil number for stencil objects
      • SProps[4] - PRP_TEXTURE
        texture number if texture mapped
  • MTTR - size 2 - not written by Imagine - see PRP1 chunk.
    • UBYTE Type; (1)
    • UBYTE Index; (2)
    • (1) refraction type (0-4)
    • (2) custom index of refraction
      This chunk contains refraction data for transparent or glossy objects. If the refraction type is 4, the object has a "custom" refractive index stored in the Index field. The Index field is 100 * (true index of refraction - 1.00) -- so it must be in the range of 1.00 to 3.55. The refraction types is 0-3 specify 0) Air - 1.00, 1) Water - 1.33, 2) Glass - 1.67 or 3) Crystal 2.00.
  • SPEC - size 2 - not written by Imagine - see SPC1 above.
    • UBYTE Specularity; (1)
    • UBYTE Hardness; (2)
    • (1) range of 0-255
    • (2) specular exponent (0-31)
      This chunk contains specular information. The Specularity field is the amount of specular reflection -- 0 is none, 255 is fully specular. The "specular exponent" controls the "tightness" of the specular spots. A value of zero gives broad specular spots and a value of 31 gives smaller spots.
  • PRP0 - size 6 - not written by Imagine
    • UBYTE Props[6]; (1)
    • (1) more object properties
      This chunk contains object properties that programs other than Turbo Silver might support.
      • Props[0] - PRP_BLEND ; blending factor (0-255)
      • Props[1] - PRP_SMOOTH ; roughness factor
      • Props[2] - PRP_SHADE ; shading on/off flag
      • Props[3] - PRP_PHONG ; phong shading on/off flag
      • Props[4] - PRP_GLOSSY ; glossy on/off flag
      • Props[5] - PRP_QUICK ; Quickdraw on/off flag
      The blending factor controls the amount of dithering used on the object - 255 is fully dithered. The roughness factor controls how rough the object should appear - 0 is smooth, 255 is max roughness. The shading flag is interpreted differently depending on whether the object is a light source or not. For light sources, it sets the light to cast shadows or not. For normal objects, if the flag is set, the object is always considered as fully lit - i.e. it's color is read directly from the object (or IFF brush), and is not affected by light sources. The phong shading is on by default - a non-zero value turns it off. The glossy flag sets the object to be glossy or not. If the object is glossy, the "transmit" colors and the index of refraction control the amount of "sheen". The glossy feature is meant to simulate something like a wax coating on the object with the specified index of refraction. The trasmission coefficients control how much light from the object makes it through the wax coating. The Quickdraw flag, if set, tells the editor not to draw all the points and edges for the object, but to draw a rectanglular solid centered at the object position, and with sizes detemined by the axis lengths.
  • PRP1 - size 8 - Imagine only
    • UBYTE IProps[8]; (1)
    • (1) more object properties
      This chunk contains object properties that programs other than Imagine might support.
      • IProps[0] - IPRP_DITHER ; blending factor (0-255)
      • IProps[1] - IPRP_HARD ; hardness factor (0-255)
      • IProps[2] - IPRP_ROUGH ; roughness factor (0-255)
      • IProps[3] - IPRP_SHINY ; shinyness factor (0-255)
      • IProps[4] - IPRP_INDEX ; index of refraction
      • IProps[5] - IPRP_QUICK ; flag - Quickdraw on/off
      • IProps[6] - IPRP_PHONG ; flag - Phong shading on/off
      • IProps[7] - IPRP_GENLOCK ; flag - Genlock on/off
      The blending factor controls the amount of 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.
  • INTS - size 4 - not written by Imagine
    • FRACT Intensity; (1)
    • (1) light intensity
      This is the intensity field for light source objects. an intensity of 255 for a sun-like light fully lights object surfaces which are perpendicular to the direction to the light source. For lamp-like light sources, the necessary intensity will depend on the distance to the light.
  • INT1 - size 12 - Imagine only
    • VECTOR Intensity; (1)
    • (1) light intensity
      This is like INTS above, but has seperate R, G & B intensities.
  • STRY - size 56 - not written by Imagine
    • STORY story; (1)
    • (1) a story structure for the object.
      The story structure is described above.
  • ANID - size 64 - Imagine only
    • LONG Cellno; (1)
    • TFORM TForm; (2)
    • (1) cell number
    • (2) 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 must agree with the sequence for the head object, and the first cell number must be zero.
  • FORD - size 56 + 12 * PC - Imagine only
    • WORD NumC; (1)
    • WORD NumF; (2)
    • WORD Flags; (3)
    • WORD pad; (4)
    • MATRIX TForm; (5)
    • VECTOR Shift; (6)
    • VECTOR Points[PC]; (7)
    • (1) number of cross section points
    • (2) number of slices
    • (3) orientation flag
    • (4) reserved
    • (5) object rotation/scaling transformation
    • (6) object translation
    • (7)"Forms" editor points
      For Imagine's "Forms" objects, the "PNTS" chunk above is not written out, but this structure is written instead. The point count is PC = NumC + 4 * NumF. 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.
  • DESC notes

    Again, most of these fields are optional, and 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 SHAP chunk is not optional.

    Defaults are: Colors set to (240,240,240); reflection and transmission coefficients set to zero; illegal shape; no story or special surface types; position at (0,0,0); axes aligned to the world axes; size fields all 32.0; intensity at 300; no name; no points/edges or faces; texture parameters set to zero; refraction type 0 with index 1.00; specular, hardness and roughness set to zero; blending at 255; glossy off; phong shading on; not a light source; not brightly lit;

    In Imagine, defaults are the same, but with colors (255,255,255).

    INFO sub-chunks

    All of the INFO sub-chunks are optional, as is the INFO chunk. Default values are supplied if the chunks are not present. The defaults are: no brushes, stencils, or textures defined; no story for the camera; horizon and zenith and ambient light colors set to black; fade color set to (80,80,80); un-rotated, un-tracked camera at (-100, -100, 100); and global properties array set to [30, 0, 0, 0, 0, 100, 8, 0].

    EXTR sub-sub-chunks

    Both of these chunks are required.