home *** CD-ROM | disk | FTP | other *** search
/ Collection of Hack-Phreak Scene Programs / cleanhpvac.zip / cleanhpvac / ISTG.ZIP / ISTG.DOC < prev   
Text File  |  1997-08-23  |  39KB  |  875 lines
  1. name: ISTG.DOC
  2.  
  3.                                  FORM ISTG
  4.                                  ---------
  5.                    Unofficial Imagine Staging File Format
  6.  
  7.                         Rev 1.1  20-08-97 G. Scibilia
  8.  
  9.  
  10.         This is the Unofficial Staging File Format document for the
  11.         Imagine raytracer (Copyright Impulse Inc., Mpls, MN 55444).
  12.         This document is sent every so often to answer general questions
  13.         that users of the 3D rendering software, Imagine by Impulse
  14.         Inc. may have.  It is aimed toward all users, especially coders
  15.         of third party add-ons or for users who have created their own
  16.         real time renderer.
  17.  
  18.         If you find any errors or have answers to other frequently asked
  19.         questions that you would like to have included in this document,
  20.         please send e-mail to:
  21.  
  22.                     minix@arsenio.disi.unige.it (The Gant at ArtNouveaU)
  23.  
  24.         or, via Fidonet, to:
  25.                                         2:332/211.24 (Gabriele Scibilia)
  26.  
  27.             - Gabriele Scibilia
  28.               <G>SZ ~ ArtNouveaU
  29.               Imagine Mailing List, IML FAQer
  30.  
  31. ========================================================================
  32.  
  33. First Version   : March 6, 1995
  34. Last Update     : August 20, 1997
  35. Revision Number : 1.1
  36.  
  37. CONTENTS:
  38. ========
  39.  
  40.     SECTION 1 - Scope of this document
  41.     SECTION 2 - General informations
  42.     SECTION 3 - Data types
  43.     SECTION 4 - ISTG sub-chunks
  44.     SECTION 5 - SOBJ sub-sub-chunks
  45.     SECTION 6 - PC (80x86 CPU) notes
  46.     SECTION 7 - IFF file format notes
  47.  
  48.     CLOSING - Closing statements and Disclaimer
  49.  
  50. ========================================================================
  51.                    SECTION 1 - Scope of this document
  52. ========================================================================
  53.  
  54. This text will describe Imagine's staging file format.  It is beyond the
  55. scope of this text to describe any of the file formats used for basic object,
  56. spline objects, deform tool, or any other object types not mentioned below.
  57. However, some of the data described below may apply to some of these
  58. undocumented object formats.  It is also not the intent of this document to
  59. explain the implementation of the information contained in the ISTG files
  60. (ie. what equations Impulse programmers use to represent Imagine's paths -
  61. lighting models - forms geometry - tweening algorithms, etc.).
  62.  
  63. ========================================================================
  64.                     SECTION 2 - General informations
  65. ========================================================================
  66.  
  67. FORM ISTG is used by Impulse's Imagine for keyframe animation system data.
  68. ISTG stands for "Imagine staging".  The files contain keyframe actors
  69. definitions, and can be extended to describe different types of actor
  70. information.
  71.  
  72. The ISTG file is stored in Amiga (680x0) format, and conforms to the "IFF"
  73. file format on that computer.  On IBM (80x86) based machines, much of the
  74. data refered to below will have to be byte reversed before it makes sense.
  75.  
  76. The IFF (interchange file format) format stores data in packets called
  77. "chunks."  Each chunk begins with a long word identifier <ID> in ascii
  78. format.  This identifier is immediately followed by a long word data-size.
  79. The data-size is measured in bytes and descrbes how much data, following
  80. the data-size long word, is part of the chunk identified by the <ID>.
  81. Imagine's IFF structure supports nesting of these chunks.  For more info on
  82. the IFF standard, see the "Amiga ROM Kernal Reference Manual: Devices (3rd
  83. Edition)."
  84.  
  85. Currently, in "standard IFF" terms, a FORM ISTG has only three supported
  86. chunk types:  a MAXF chunk, a LOOP chunk and a SOBJ chunk describing a
  87. staging object data.
  88.  
  89. The FORM has one (obligatory) MAXF chunk followed by one (obligatory) LOOP
  90. chunk followed by some number of SOBJ chunks.
  91.  
  92. The SOBJ chunk, in turn, is made up of smaller chunks with the standard IFF
  93. structure:  <ID> <data-size> <data>.
  94.  
  95. The MAXF and LOOP "sub-chunks" are relatively straightforward to interpret.
  96.  
  97. The SOBJ "sub-chunks" support staging objects and are slightly more
  98. difficult to interpret.  Currently, there are many types of supported SOBJ
  99. sub-chunks.
  100.  
  101. In Imagine, the structure of the staging object is written in a SOBJ chunk
  102. as follows:
  103.  
  104.     1)  A NAME chunk is written, naming the object.
  105.     2)  A STGF chunk and a LYR0 is written, marking the start of the
  106.         object description.
  107.     3)  Each LYR0 chunk is followed by one or more (or no one) CAMR (camera
  108.         actor) or GLB? (globals) or FIL? (object actor) or LIT? (light
  109.         source actor) or AXIS (track axis actor) chunks, describing the
  110.         object type.
  111.     4)  Follow these chunks some number of position chunks, alignment,
  112.         size, association and special effects ones (depending on the choice
  113.         made when the Specify Type requester was called).
  114.  
  115. Reader software WILL FOLLOW the standard IFF procedure of skipping over any
  116. un-recognized chunks -- and "sub-chunks" or "sub-sub-chunks".  The
  117. <data-size> field indicates how many bytes to skip.  In addition it WILL
  118. OBSERVE the IFF rule that an odd <data-size> may appear, in which case the
  119. corredponding <data> field will be padded at the end with one extra byte to
  120. give it an even size.
  121.  
  122. ========================================================================
  123.                          SECTION 3 - Data types
  124. ========================================================================
  125.  
  126. Now, on with the details (from an official Impulse text that describe
  127. FORM TDDD, used by Impulse's Turbo Silver for 3D rendering data and by
  128. Imagine for basic object file format).
  129.  
  130. First, there are several numerical fields appearing in the data, describing
  131. actor positions, rotation angles, scaling factors, etc.  They are stored as
  132. "32-bit fractional" numbers, such that the true number is the 32-bit number
  133. divided by 65536.  So as an example, the number 3.14159 is stored as
  134. (hexadecimal) 0x0003243F (ie. 0x0003243F / 65536 = 3.14159).  This allows
  135. the data to be independant of any particular floating point format.  Numbers
  136. stored in this format are typedef'ed as "FRACT"s below.
  137.  
  138. Second, there are several color (or RGB) fields in the data.  They are
  139. always stored as three UBYTEs representing the red, green and blue
  140. components of the color.  Red is always first, followed by green, and then
  141. blue.
  142.  
  143. The three basic data types that will be refered to herein are:
  144.  
  145.     BYTE        :  a single byte of data (char)
  146.     WORD        :  a two byte data field (short)
  147.     LONG        :  a four byte data field (long)
  148.  
  149.     A "U" (ie. UBYTE) means unsigned.
  150.  
  151. The following "typedef"s are used below:
  152.  
  153.     typedef LONG    FRACT;                /* 4 bytes */
  154.     typedef UBYTE   COLOR[3];             /* 3 bytes */
  155.  
  156.     typedef struct vectors {
  157.         FRACT X;          /* 4 bytes */
  158.         FRACT Y;          /* 4 bytes */
  159.         FRACT Z;          /* 4 bytes */
  160.     } VECTOR;             /* 12 bytes total */
  161.  
  162. ========================================================================
  163.                       SECTION 4 - ISTG sub-chunks
  164. ========================================================================
  165.  
  166. MAXF - size 2
  167.  
  168.     UWORD   MaxFrame;       ; total frames in animation
  169.  
  170.     Highest frame number as it appears in the Action editor.
  171.  
  172. LOOP - size 2
  173.  
  174.     UWORD   Looping;        ; loop flags
  175.                             ;   Bit  0         - loop animation
  176.                             ;   Bits 1 thru 15 - reserved
  177.  
  178. ========================================================================
  179.                     SECTION 5 - SOBJ sub-sub-chunks
  180. ========================================================================
  181.  
  182. NAME - size 18
  183.  
  184.     UBYTE   Name[18];       ; a name for the staging actor (NULL terminated)
  185.  
  186.     Object's name as it appears in the Name & Layer requester (objects are
  187.     also called actors as they move about on the stage).  Used for tracking,
  188.     etc.  There is a NAME chunk for each (named) actor.  Each NAME chunk is
  189.     followed by one STGF chunk.
  190.  
  191. STGF - size 2
  192.  
  193.     UWORD   Flags;          ; "stage only" object flags
  194.                             ;   Bit  0         - bounding box
  195.                             ;   Bit  1         - quick edges
  196.                             ;   Bits 2 thru 5  - reserved
  197.                             ;   Bit  6         - axis
  198.                             ;   Bit  7         - light source
  199.                             ;   Bits 8 thru 15 - reserved
  200.  
  201.     There is a STGF chunk for each (named) actor.  Each STGF chunk is
  202.     followed by one LYR0 (layer number, IM30+) chunk (see below).
  203.  
  204. LYR0 - size 2, IM30+
  205.  
  206.     UWORD   Layer;          ; number indicating actor layer
  207.  
  208.     Actor's layer as it appears in the Name & Layer requester.  Each LYR0
  209.     chunk is followed by one or more (or no one) CAMR (camera actor) or GLB?
  210.     (globals) or FIL? (object actor) or LIT? (light source actor) or AXIS
  211.     (axis actor) chunks (see CAMR, GLB?, FIL?, LIT? and AXIS chunks).
  212.  
  213. GLB2 - variale size, IM20+
  214.  
  215.     UWORD   Flags;          ; globals flags
  216.                             ;   Bit  0         - genlock sky
  217.                             ;   Bits 1 thru 15 - reserved
  218.     UWORD   StartFrame;     ; starting frame
  219.     UWORD   EndFrame;       ; ending frame
  220.     UWORD   Flags;          ; reserved
  221.     UWORD   Blending;       ; sky blending factor
  222.     FRACT   Density;        ; star field density
  223.     UWORD   Flags;          ; reserved
  224.     UWORD   Transition;     ; transition frame count
  225.     VECTOR  Ambient;        ; ambient color
  226.     VECTOR  Horizon;        ; horizon color
  227.     VECTOR  PlusZenith;     ; +zenith color
  228.     VECTOR  MinusZenith;    ; -zenith color
  229.     VECTOR  Fog;            ; fog color
  230.     FRACT   FogBottom;      ; fog bottom
  231.     FRACT   FogTop;         ; fog top
  232.     FRACT   FogLength;      ; fog length
  233.     UWORD   Flags;          ; reserved
  234.     UWORD   Seq0;           ; global brush max seq.
  235.     UWORD   Flags;          ; reserved
  236.     UWORD   Seq1;           ; backdrop picture max seq.
  237.     UBYTE   Backdrop[256];  ; backdrop picture file name
  238.     UBYTE   Length;         ; length of global brush file name
  239.     UBYTE   Global[Length]; ; global brush file name (not NULL terminated)
  240.     UBYTE   OptionalPad     ; if name has even length (see FILE description)
  241.  
  242.     Please note that the above color values are stored as FRACT's and are
  243.     not limited to the 0 to 255 range of the usual UBYTE color values.
  244.     The "genlock sky" flag controls whether the sky will be colored, or set
  245.     to the genlock color (color 0 - black) in the final picture.
  246.  
  247. GLB3 - variale size, IM30+
  248.  
  249.     UWORD   Flags;          ; reserved
  250.     UWORD   StartFrame;     ; starting frame
  251.     UWORD   EndFrame;       ; ending frame
  252.     UWORD   Flags;          ; reserved
  253.     UWORD   Seq0;           ; global brush max seq.
  254.     FRACT   Density;        ; star field density
  255.     UWORD   Flags;          ; reserved
  256.     UWORD   Transition;     ; transition frame count
  257.     VECTOR  Ambient;        ; ambient color
  258.     VECTOR  Horizon;        ; horizon color
  259.     VECTOR  PlusZenith;     ; +zenith color
  260.     VECTOR  MinusZenith;    ; -zenith color
  261.     VECTOR  Fog;            ; fog color
  262.     FRACT   FogBottom;      ; fog bottom
  263.     FRACT   FogTop;         ; fog top
  264.     FRACT   FogLength;      ; fog length
  265.     UWORD   Flags;          ; reserved
  266.     UWORD   Seq1;           ; backdrop picture max seq.
  267.     UBYTE   Backdrop[256];  ; backdrop picture file name
  268.     UBYTE   Length;         ; length of global brush file name
  269.     UBYTE   Global[Length]; ; global brush file name (not NULL terminated)
  270.     UBYTE   OptionalPad     ; if name has even length (see FILE description)
  271.  
  272.     Same as above GLB2 chunk.
  273.  
  274. CAMR - size 22, IM30+
  275.  
  276.     UWORD   Flags;          ; camera flags
  277.                             ;   Bit  0         - Y size is focus distance
  278.                             ;   Bit  1         - Y size is screen distance
  279.                             ;   Bit  2         - ap. size is DOF width mult.
  280.                             ;   Bit  3         - ap. size is actual size
  281.                             ;   Bit  4         - eye sep. is screen width
  282.                             ;   Bit  5         - eye sep. is actual size
  283.                             ;   Bits 6 thru 15 - reserved
  284.     UWORD   StartFrame;     ; starting frame
  285.     UWORD   EndFrame;       ; ending frame
  286.     FRACT   Multiplier;     ; distance multiplier
  287.     FRACT   Aperture;       ; aperture size DOF
  288.     FRACT   Separation;     ; eye separation 3DS
  289.     UWORD   Flags;          ; reserved
  290.     UWORD   Transition;     ; transition frame count
  291.  
  292.     This chunk contains the camera informations as them appear in the Camera
  293.     requester.  The camera looks down its own Y axis, with the top of the
  294.     picture in the direction of the Z axis.  The rotations are performed in
  295.     the order ZXY about the camera axes.  A positive angle rotates Y toward
  296.     Z, Z toward X, and X toward Y for rotations about the X, Y, and Z axes
  297.     respectively.  In Imagine, the lens focal length is altered changing the
  298.     length of the Y axis.  To understand the focal length, imagine a 320 x
  299.     200 pixel rectangle perpendicular to, and centered on the camera's Y
  300.     axis.  Any objects in the infinite rectangular cone defined by the
  301.     camera position and the 4 corners of the rectangle will appear in the
  302.     picture.
  303.  
  304. FILE - variable size
  305.  
  306.     UWORD   Flags;          ; actor flags
  307.                             ;   Bit  0         - reverse cycle motion
  308.                             ;   Bits 1 thru 15 - reserved
  309.     UWORD   StartFrame;     ; starting frame
  310.     UWORD   EndFrame;       ; ending frame
  311.     UWORD   Transition;     ; transition frame count
  312.     UBYTE   Length;         ; length of object file name
  313.     UBYTE   Name[Length];   ; object file name (not NULL terminated)
  314.     UBYTE   OptionalPad;    ; appears only if the name string has an even
  315.                             ; length -- so the total length of the name
  316.                             ; "block" (length + name + pad?) comes out even
  317.  
  318.     Specifies the actor (normal object) informations.
  319.  
  320. FIL3 - variable size, IM30+
  321.  
  322.     UWORD   Flags;          ; actor flags
  323.                             ;   Bit  0         - reverse cycle motion
  324.                             ;   Bit  1         - spline interpolation
  325.                             ;   Bit  2         - discontinuous knot
  326.                             ;   Bits 3 thru 15 - reserved
  327.     UWORD   StartFrame;     ; starting frame
  328.     UWORD   EndFrame;       ; ending frame
  329.     FRACT   Cyc0;           ; number of cycles to perform
  330.     FRACT   Cyc1;           ; initial cycle phase
  331.     FRACT   Vel0;           ; velocity scaling #0
  332.     FRACT   Vel1;           ; velocity scaling #1
  333.     UBYTE   Length;         ; length of object file name
  334.     UBYTE   Name[Length];   ; object file name (not NULL terminated)
  335.     UBYTE   State[18]       ; state name (NULL terminated)
  336.     UBYTE   OptionalPad     ; if name has even length (see FILE description)
  337.  
  338.     Note that velocity scaling sets Imagine to adjust the velocity of
  339.     objects at the beginning and the end of key frame positions, entering
  340.     different values from 0 to 2 will make objects ease in and ease out.
  341.  
  342.  
  343. LITE - size 22
  344.  
  345.     UWORD   Flags;          ; light source flags
  346.                             ;   Bit  0         - spherical
  347.                             ;   Bit  1         - cylindrical
  348.                             ;   Bit  2         - conical
  349.                             ;   Bit  3         - cast shadows
  350.                             ;   Bit  4         - diminish intensity
  351.                             ;   Bits 5 thru 15 - reserved
  352.     UWORD   StartFrame;     ; starting frame
  353.     UWORD   EndFrame;       ; ending frame
  354.     VECTOR  Intensity;      ; light intensity
  355.     UWORD   Flags;          ; reserved
  356.     UWORD   Transition;     ; transition frame count
  357.  
  358.     This has seperate R, G & B intensities for the light actors.  Note
  359.     that these color values are stored as FRACT's and are not limited to
  360.     the 0 to 255 range of the usual UBYTE color values so lights can be
  361.     brighter than 255 255 255.
  362.  
  363. LIT2 - size 22, IM30+
  364.  
  365.     UWORD   Flags;          ; light source flags
  366.                             ;   Bit  0         - point source
  367.                             ;   Bit  1         - parallel rays
  368.                             ;   Bit  2         - round shape
  369.                             ;   Bit  3         - rectangular
  370.                             ;   Bit  4         - cast shadows
  371.                             ;   Bit  5         - diminish intensity
  372.                             ;   Bit  6         - controlled falloff
  373.                             ;   Bit  7         - no lens flare
  374.                             ;   Bits 8 thru 15 - reserved
  375.     UWORD   StartFrame;     ; starting frame
  376.     UWORD   EndFrame;       ; ending frame
  377.     VECTOR  Intensity;      ; light intensity
  378.     UWORD   Flags;          ; reserved
  379.     UWORD   Transition;     ; transition frame count
  380.  
  381.     See above LITE chunk.
  382.  
  383. AXIS - size 6
  384.  
  385.     UWORD   Flags;          ; reserved
  386.     UWORD   StartFrame;     ; starting frame
  387.     UWORD   EndFrame;       ; ending frame
  388.  
  389.     Defines start and end where the track object will appear.  The Axis
  390.     actor can be used as an invisible tracked object.
  391.  
  392. POSN - size 12
  393.  
  394.     VECTOR  Position;       ; the actor's position
  395.  
  396.     This is the end frame position (in world-space coordinates) of the
  397.     actor's axes as it appears in the Tween Position requester.  Legal
  398.     coordinates are in the range -32768 to 32767 and 65535/65536.
  399.     Currently, the ray-tracer only sees objects in the -1024 to 1024 range.
  400.     Light sources, and the camera may be placed outside that range, however.
  401.  
  402. POS2 - size 26, IM30+
  403.  
  404.     UWORD   Flags;          ; position flags
  405.                             ;   Bit  0         - spline interpolation
  406.                             ;   Bit  1         - discontinuous knot
  407.                             ;   Bits 2 thru 15 - reserved
  408.     UWORD   StartFrame;     ; starting frame
  409.     UWORD   EndFrame;       ; ending frame
  410.     VECTOR  Position;       ; the actor's position
  411.     FRACT   Vel0;           ; velocity scaling #0
  412.     FRACT   Vel1;           ; velocity scaling #1
  413.  
  414.     See POSN description, this chunk replaces old POSN ones.
  415.  
  416. PTH2 - variable size, IM20+
  417.  
  418.     UWORD   Flags;          ; reserved
  419.     UWORD   StartFrame;     ; starting frame
  420.     UWORD   EndFrame;       ; ending frame
  421.     UWORD   Flags;          ; reserved
  422.     UWORD   AccFrames       ; (de)acceleration frames
  423.     FRACT   StartSpeed      ; starting speed (units / frames)
  424.     UWORD   Flags;          ; reserved
  425.     UWORD   DecFrames       ; (ac)deceleration frames
  426.     FRACT   EndSpeed        ; ending speed (units / frames)
  427.     UBYTE   Length;         ; length of path name
  428.     UBYTE   Name[Length];   ; path name (not NULL terminated)
  429.     UBYTE   OptionalPad     ; if name has even length (see FILE description)
  430.  
  431.     This chunk contains the path name as it appears in the Follow Path
  432.     requester.
  433.  
  434. ALGN - size 18
  435.  
  436.     UWORD   Flags;          ; reserved
  437.     UWORD   StartFrame;     ; starting frame
  438.     UWORD   EndFrame;       ; ending frame
  439.     VECTOR  Alignment;      ; the actor's alignment angles
  440.  
  441.     The rotation angles are in degrees, and specify rotations around the
  442.     X, Y, and Z axes.  If they are all zero, the actor's axes are aligned
  443.     with the world coordinate axes.
  444.  
  445. ALN2 - size 26, IM30+
  446.  
  447.     UWORD   Flags;          ; alignment flags
  448.                             ;   Bit  0         - spline interpolation
  449.                             ;   Bit  1         - discontinuous knot
  450.                             ;   Bits 2 thru 15 - reserved
  451.     UWORD   StartFrame;     ; starting frame
  452.     UWORD   EndFrame;       ; ending frame
  453.     VECTOR  Alignment;      ; the actor's alignment
  454.     FRACT   Vel0;           ; velocity scaling #0
  455.     FRACT   Vel1;           ; velocity scaling #1
  456.  
  457.     Replaces old ALGN chunks, sets object's rotation over time.
  458.  
  459. PALN - size 6
  460.  
  461.     UWORD   Flags;          ; alignment flags
  462.                             ;   Bit  0         - keep Y horizontal
  463.                             ;   Bit  1         - conform group to path
  464.                             ;   Bit  2         - conform object to path
  465.                             ;   Bits 3 thru 15 - reserved
  466.     UWORD   StartFrame;     ; starting frame
  467.     UWORD   EndFrame;       ; ending frame
  468.  
  469.     The object is made to follow a pre-defined path as it moves, rotates
  470.     and scales from one key frame to the next.
  471.  
  472. TALN - variable size
  473.  
  474.     UWORD   Flags;          ; reserved
  475.     UWORD   StartFrame;     ; starting frame
  476.     UWORD   EndFrame;       ; ending frame
  477.     FRACT   StartRot;       ; initial Y rotation
  478.     FRACT   EndRot;         ; final Y rotation
  479.     UBYTE   Length;         ; length of track name
  480.     UBYTE   Name[Length];   ; track name (not NULL terminated)
  481.     UBYTE   OptionalPad     ; if name has even length (see FILE description)
  482.  
  483.     This chunk specifies the name of an object that the actor is "tracked"
  484.     to as it moves, rotates or scales as it appears in the Track Object
  485.     requester.  If the name is NULL, the actor doesn't track.
  486.  
  487. OSIZ - size 18
  488.  
  489.     UWORD   Flags;          ; reserved
  490.     UWORD   StartFrame;     ; starting frame
  491.     UWORD   EndFrame;       ; ending frame
  492.     VECTOR  Size;           ; actor size info
  493.  
  494.     The sizes are used in a variety of ways depending on the actor type.
  495.     For custom objects, they are the lengths of the coordinate axes drawn
  496.     in the editor.
  497.  
  498. OSZ2 - size 26
  499.  
  500.     UWORD   Flags;          ; size flags
  501.                             ;   Bit  0         - spline interpolation
  502.                             ;   Bit  1         - discontinuous knot
  503.                             ;   Bits 2 thru 15 - reserved
  504.     UWORD   StartFrame;     ; starting frame
  505.     UWORD   EndFrame;       ; ending frame
  506.     VECTOR  Size;           ; actor size info
  507.     FRACT   Vel0;           ; velocity scaling #0
  508.     FRACT   Vel1;           ; velocity scaling #1
  509.  
  510.     See above OSIZ chunk.
  511.  
  512. HING - variable size
  513.  
  514.     UWORD   Flags;          ; reserved
  515.     UWORD   StartFrame;     ; starting frame
  516.     UWORD   EndFrame;       ; ending frame
  517.     UBYTE   Length;         ; length of hinge name
  518.     UBYTE   Name[Length];   ; hinge name (not NULL terminated)
  519.     UBYTE   OptionalPad     ; if name has even length (see FILE description)
  520.  
  521.     This is Imagine's hinge data as it appears in the Hinge requester.
  522.  
  523. ASSC - variable size, IM30+
  524.  
  525.     UWORD   Flags;          ; reserved
  526.     UWORD   StartFrame;     ; starting frame
  527.     UWORD   EndFrame;       ; ending frame
  528.     UBYTE   Length;         ; length of associate name
  529.     UBYTE   Name[Length];   ; associate name (not NULL terminated)
  530.     UBYTE   OptionalPad     ; if name has even length (see FILE description)
  531.  
  532.     Causes object to tack onto the associated object and keep its relative
  533.     distance, rotation and so on.  This replaces old HING chunks.
  534.  
  535. SPFX - variable size
  536.  
  537.     UWORD   Flags;          ; see below
  538.     UWORD   StartFrame;     ; starting frame
  539.     UWORD   EndFrame;       ; ending frame
  540.     UBYTE   Length;         ; length of effect name
  541.     UBYTE   Name[Length];   ; effect name (not NULL terminated)
  542.     UBYTE   OptionalPad     ; if name has even length (see FILE description)
  543.     UBYTE   FxData[size];   ; effect data - variable size
  544.  
  545.     This is the effect 1 data chunk.  The Name string describes what kind of
  546.     information is actually stored within the FxData[] array.  This one and
  547.     the Flags are interpreted as follows depending upon the effect type:
  548.  
  549.         animbrsh - animated brush effect
  550.  
  551.                             ; animbrsh flags
  552.                             ;   Bits 0 thru 15 - reserved
  553.     UWORD   Flags;          ; reserved
  554.     UWORD   FirstFrame;     ; first frame
  555.     UWORD   Flags;          ; reserved
  556.     UWORD   LastFrame;      ; last frame
  557.     UBYTE   Brush[256];     ; brush name
  558.     (264 bytes total)
  559.  
  560.         baloon - ballon effect
  561.  
  562.                             ; baloon flags
  563.                             ;   Bit  0         - inside within object
  564.                             ;   Bit  1         - circumscribe about object
  565.                             ;   Bit  2         - use average radius
  566.                             ;   Bit  3         - set radius to
  567.                             ;   Bit  4         - use average radius
  568.                             ;   Bit  5         - reverse baloon timing
  569.                             ;   Bit  6         - return to original shape
  570.                             ;   Bits 7 thru 15 - reserved
  571.     FRACT   Radius;         ; ballon radius
  572.     (4 bytes total)
  573.  
  574.         boing2 - boing effect
  575.  
  576.                             ; boing flags
  577.                             ;   Bit  0         - squash to +(XY or Z)
  578.                             ;   Bit  1         - squash to center
  579.                             ;   Bit  2         - squash to -(XY or Z)
  580.                             ;   Bit  3         - X axis
  581.                             ;   Bit  4         - Y axis
  582.                             ;   Bit  5         - Z axis
  583.                             ;   Bits 6 thru 15 - reserved
  584.     FRACT   Shrink;         ; shrink factor
  585.     LONG    Count;          ; number of times
  586.     (8 bytes total)
  587.  
  588.         explode - explode effect
  589.  
  590.                             ; explode flags
  591.                             ;   Bit  0         - spherical
  592.                             ;   Bit  1         - radial
  593.                             ;   Bit  2         - linear
  594.                             ;   Bit  3         - X axis
  595.                             ;   Bit  4         - Y axis
  596.                             ;   Bit  5         - Z axis
  597.                             ;   Bit  6         - return to original positions
  598.                             ;   Bit  7         - reverse explosion timing
  599.                             ;   Bits 8 thru 15 - reserved
  600.     FRACT   Distance;       ; explosion distance
  601.     FRACT   Angle;          ; explosion angle
  602.     FRACT   Scaling;        ; triangle scaling
  603.     FRACT   MinRotations;   ; minimum number of triangle rotations
  604.     FRACT   MaxRotations;   ; maximum number of triangle rotations
  605.     LONG    Seed;           ; random number seed
  606.     (24 bytes total)
  607.  
  608.         firewrks - fireworks effect
  609.  
  610.                             ; explode flags
  611.                             ;   Bit  0         - spherical
  612.                             ;   Bit  1         - radial
  613.                             ;   Bit  2         - linear
  614.                             ;   Bit  3         - X axis
  615.                             ;   Bit  4         - Y axis
  616.                             ;   Bit  5         - Z axis
  617.                             ;   Bit  6         - make faces sparkle
  618.                             ;   Bits 7 thru 15 - reserved
  619.     FRACT   Distance;       ; explosion distance
  620.     FRACT   Angle;          ; expansion angle
  621.     FRACT   Scaling;        ; triangle scaling
  622.     FRACT   MinRotations;   ; minimum number of triangle rotations
  623.     FRACT   MaxRotations;   ; maximum number of triangle rotations
  624.     FRACT   Count;          ; frame count for expansion
  625.     FRACT   Fall;           ; distance to fall by end
  626.     LONG    Seed;           ; random number seed
  627.     (32 bytes total)
  628.  
  629.         flash - flash effect
  630.  
  631.                             ; flash flags
  632.                             ;   Bit  0         - start on
  633.                             ;   Bit  1         - start off
  634.                             ;   Bits 2 thru 15 - reserved
  635.     UWORD   Flags;          ; reserved
  636.     UWORD   OnFrames;       ; on frames
  637.     UWORD   Flags;          ; reserved
  638.     UWORD   OffFrames;      ; off frames
  639.     (8 bytes total)
  640.  
  641.         grow - grow effect
  642.  
  643.                             ; grow flags
  644.                             ;   Bit  0         - align Y topath direction
  645.                             ;   Bit  1         - keep X in path's XY plane
  646.                             ;   Bit  2         - mirror ends
  647.                             ;   Bit  3         - time reversed
  648.                             ;   Bit  4         - sharp extrusion
  649.                             ;   Bits 5 thru 15 - reserved
  650.     FRACT   YRotation;      ; Y rotation
  651.     FRACT   XScaling;       ; X scaling
  652.     FRACT   ZScaling;       ; Z scaling
  653.     FRACT   XTranslate;     ; X translate
  654.     FRACT   ZTranslate;     ; Z translate
  655.     (20 bytes total)
  656.  
  657.         particle - particle effect
  658.  
  659.                             ; particle flags
  660.                             ;   Bit  0         - delayed
  661.                             ;   Bit  1         - rain
  662.                             ;   Bit  2         - bounce
  663.                             ;   Bit  3         - taper
  664.                             ;   Bit  4         - emission
  665.                             ;   Bit  5         - reverse timing
  666.                             ;   Bit  6         - return to original positions
  667.                             ;   Bits 7 thru 15 - reserved
  668.     FRACT   Distance;       ; travel distance
  669.     FRACT   Scaling;        ; triangle scaling
  670.     FRACT   Delay;          ; scaling delay
  671.     FRACT   MinRotations;   ; minimum number of rotations
  672.     FRACT   MaxRotations;   ; maximum number of rotations
  673.     FRACT   HVelocity;      ; time to terminal horizontal velocity
  674.     FRACT   Gravity;        ; gravitational constant
  675.     LONG    Seed;           ; random number seed
  676.     FRACT   Elasticity;     ; elasticity
  677.     FRACT   ZVelocity;      ; time to terminal Z velocity
  678.     FRACT   Ground;         ; ground Z coordinate
  679.     FRACT   Speed;          ; speed factor
  680.     FRACT   MinAngleZ;      ; minimum angle from Z
  681.     FRACT   MaxAngleZ;      ; maximum angle from Z
  682.     FRACT   MinAngleX;      ; minimum angle from X
  683.     FRACT   MaxAngleX;      ; maximum angle from X
  684.     FRACT   WindSpeed;      ; wind speed
  685.     FRACT   WindAngle;      ; wind angle
  686.     FRACT   WindStart;      ; wind start
  687.     FRACT   WindStop;       ; wind stop
  688.     FRACT   Emission;       ; emission amount
  689.     UBYTE   Subgroup[18];   ; subgroup name (NULL terminated)
  690.     UWORD   Flags;          ; reserved
  691.     (108 bytes total)
  692.  
  693.         ripple - ripple effect
  694.  
  695.                             ; ripple flags
  696.                             ;   Bit  0         - radial around Z
  697.                             ;   Bit  1         - linear along X
  698.                             ;   Bits 2 thru 15 - reserved
  699.     FRACT   Length;         ; wave length
  700.     FRACT   Amplitude;      ; Z amplitude
  701.     FRACT   Distance;       ; travel distance
  702.     LONG    Ripples;        ; ripple count
  703.     (16 bytes total)
  704.  
  705.         rotate2 - rotate effect
  706.  
  707.                             ; rotate2 flags
  708.                             ;   Bit  0         - X axis
  709.                             ;   Bit  1         - Y axis
  710.                             ;   Bit  2         - Z axis
  711.                             ;   Bits 3 thru 15 - reserved
  712.     FRACT   Degrees;        ; rotation degrees
  713.     (4 bytes total)
  714.  
  715.         shredder - shredder effect
  716.  
  717.                             ; shredder flags
  718.                             ;   Bit  0         - whole object as parts
  719.                             ;   Bit  1         - use def. subgroups as parts
  720.                             ;   Bit  2         - la machine
  721.                             ;   Bit  3         - bounce particle
  722.                             ;   Bit  4         - flip on bounce
  723.                             ;   Bit  5         - use maximal bounding sphere
  724.                             ;   Bit  6         - use minimal bounding sphere
  725.                             ;   Bit  7         - use average bounding sphere
  726.                             ;   Bits 8 thru 15 - reserved
  727.     LONG    MaxTriangles;   ; maximum number of triangles in group
  728.     UBYTE   Subgroup[18];   ; subgroup name (NULL terminated)
  729.     UWORD   Flags;          ; reserved
  730.     FRACT   StartTime;      ; start time
  731.     FRACT   EndTime;        ; end time
  732.     FRACT   ExplosionDelay; ; explosion timing delay
  733.     LONG    HoldAt;         ; hold at
  734.     FRACT   Ground;         ; ground Z position
  735.     FRACT   MinElasticity;  ; minimum elasticity
  736.     FRACT   MaxElasticity;  ; maximum elasticity
  737.     FRACT   MinVelocity;    ; minimum initial velocity range
  738.     FRACT   MaxVelocity;    ; maximum initial velocity range
  739.     FRACT   MinRotations;   ; minimum triangle rotations
  740.     FRACT   MaxRotations;   ; maximum triangle rotations
  741.     FRACT   MinTrajectory;  ; minimum particle trajectory
  742.     FRACT   MaxTrajectory;  ; maximum particle trajectory
  743.     FRACT   MinScaling;     ; minimum final scaling factor range
  744.     FRACT   MaxScaling;     ; maximum final scaling factor range
  745.     FRACT   Acceleration;   ; gravitational acceleration
  746.     FRACT   UnitsPerMeter;  ; Imagine units per meter
  747.     LONG    Seed;           ; random number seed
  748.     (96 bytes total)
  749.  
  750.         spike - spike effect
  751.  
  752.                             ; spike flags
  753.                             ;   Bit  0         - linearly along Z
  754.                             ;   Bit  1         - cylindrically around Z
  755.                             ;   Bit  2         - radially from axis
  756.                             ;   Bit  3         - restrict to integral cycles
  757.                             ;   Bit  4         - reverse spike timing
  758.                             ;   Bit  5         - return to starting shape
  759.                             ;   Bits 6 thru 15 - reserved
  760.     FRACT   MinDistance;    ; minimum spike distance
  761.     FRACT   MaxDistance;    ; maximum spike distance
  762.     FRACT   MinCycles;      ; minimum spike cycles
  763.     FRACT   MaxCycles;      ; maximum spke cycles
  764.     FRACT   Dispersion;     ; dispersion adjust
  765.     LONG    Seed;           ; random number seed
  766.     (24 bytes total)
  767.  
  768.         sway - group sway effect
  769.  
  770.                             ; sway flags
  771.                             ;   Bit  0         - random axis
  772.                             ;   Bit  1         - Z axis
  773.                             ;   Bit  2         - X axis
  774.                             ;   Bit  3         - Y axis
  775.                             ;   Bit  4         - restrict to int. gyrations
  776.                             ;   Bits 5 thru 15 - reserved
  777.     FRACT   MinGyrations;   ; minimum number of gyrations
  778.     FRACT   MaxGyrations;   ; maximum number of gyrations
  779.     FRACT   MinAngle;       ; minimum gyration angle
  780.     FRACT   MaxAngle;       ; maximum gyration angle
  781.     LONG    Seed;           ; random number seed
  782.     (20 bytes total)
  783.  
  784.         tumble - tumble effect
  785.  
  786.                             ; tumble flags
  787.                             ;   Bit  0         - random axis
  788.                             ;   Bit  1         - Z axis
  789.                             ;   Bits 2 thru 15 - reserved
  790.     FRACT   MinRotations;   ; minimum number of rotations
  791.     FRACT   MaxRotations;   ; maximum number of rotations
  792.     LONG    Seed;           ; random number seed
  793.     (12 bytes total)
  794.  
  795. S?FX - variable size
  796.  
  797.     See SPFX above chunk.  Up to four special effects can be applied to an
  798.     object at one time.
  799.  
  800. ========================================================================
  801.                     SECTION 6 - PC (80x86 CPU) notes
  802. ========================================================================
  803.  
  804. The IFF file format originated on machines in which the byte order for
  805. LONG (4 byte) and WORD (2 byte) data is "most significant byte first".
  806. This concept has been preserved in the "PC" versions of Imagine.
  807.  
  808. What it means, is that if you are writing code for the "other" type of CPU
  809. (80386 code, for example), you will need to reverse the byte ordering in
  810. (U)LONG, FRACT, and (U)WORD data wherever it appears (eg. the FRACTs in
  811. a VECTOR structure must be (separatly) byte reversed... the size field
  812. following a chunk identifier is another good example).
  813.  
  814. From the Imagine Object File Format document, by Scotty Kirvan.
  815.  
  816. ========================================================================
  817.                    SECTION 7 - IFF file format notes
  818. ========================================================================
  819.  
  820. In case you are unfamiliar with the IFF file structure, the ISTG files
  821. have the following (simple, "single FORM") IFF structure (again, from the
  822. description of Turbo Silver TDDD chunk):
  823.  
  824.  
  825. form_ID           4 characters:  'F','O','R','M'
  826. form_size         LONG size   : -- MSB(yte) first
  827. form_type         4 characters:  'I','S','T','G'
  828. chunks:
  829.     chunk_ID      4 characters: eg. 'S','O','B','J'
  830.     chunk_size    LONG size   : -- byte reversed if appropriate
  831.     chunk_data    'size' bytes:
  832.     chunk_pad     0 or 1 bytes: -- pad to even length if 'size' is odd
  833.  
  834. Note: The "form_size" field appearing after the "form_ID" is the total
  835.       length of the data that FOLLOWS it, INCLUDING the 4-byte (ISTG) id.
  836.       Also the "chunk_size" fields list the size of the data in the
  837.       "chunk_data" blocks that follow.  In other words, the size fields
  838.       when rounded up to an even number, always list the number of bytes
  839.       (after the size field) to skip forward in the file if, based on the
  840.       ID field preceding the size, the reader can not or does not wish to
  841.       interpret the data... so, in particular, the sizes that appear DO NOT
  842.       include the length of the ID and size fields themselves, and the
  843.       'form_size' DOES include 4 bytes for the 'form_type' field that
  844.       follows it.
  845.  
  846. ========================================================================
  847.               CLOSING -  Closing statements and Disclaimer
  848. ========================================================================
  849.  
  850. Hopefully this document is useful to people out there.  Once again, if
  851. there is anything you want added/changed/deleted, please e-mail as listed
  852. at the top of the document.
  853.  
  854. The information presented herein
  855.  
  856. What follows is a small disclaimer so no one gets sued for information
  857. that is harmful or accidentally incorrect or misleading (if you find a
  858. mistake... please send e-mail so it can be fixed).
  859.  
  860.       Disclaimer: There is no guarantee regarding any information
  861.                   presented in this document.  The information may not
  862.                   be correct, useful or helpful.  Knowledge is
  863.                   dangerous - use at your own risk.  No warranties are
  864.                   made or implied, and no liability or responsibility
  865.                   is assumed.  Good luck and enjoy.
  866.  
  867. ========================================================================
  868. END OF ISTG.DOC
  869.  
  870.  /\_
  871. |   | "Gabriele Scibilia aka <G>SZ ~ ArtNouveaU"
  872. | O | "minix@arsenio.disi.unige.it"
  873. |   | "2:332/211.24@FidoNet.org"
  874. | O | "Imagine Mailing List,IML FAQer"                         ae(-_^)ue
  875. |___|                            _    __   ___  ______Wizard signing off