How to use the 3D library Step-by-Step (as of May 7, 1997)
----------------------------------------------------------

I.   Create required data files (Do it in the following order)
     --------------------------
     1.  Create FLT files
     2.  Convert FLT files to HOT files (Text format)
     3.  Create Input file (objects list)
     4.  Create Texture List (Binary format)
     5.  Create Color List (Binary format)
     6.  Convert HOT files to HOB files (Binary format)
     7.  Create Objects List (Binary format)
     8.  Create Palette List (Binary format) (optional)

II.  3D library Information (Programmer's Guide)
     -------------------------------------------
     1.  Additional files required
     2.  Additional setup/cleanup required
     3.  3D setup/cleanup
     4.  Setup camera
     5.  Setup/cleanup object
     6.  Display object
     7.  Light source
     8.  Math functions
     9.  Misc functions
    10.  Object Slot
    11.  Dynamic Vertex

III. ANimation Script
     ----------------
     1.  ANS file format
     2.  ANS examples
     3.  ANS language reference

0-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-0

Note:
----
The latest 3d tools and documentation can be found in code\erickj\objtools

Tools:
-----
RegisCol - Register Color
RegisPal - Register Palette
RegisTex - Register Texture Files
RegisObj - Register Object Files
FLTtoHOT - Convert FLT to text format
HOTtoHOB - Convert HOT file to binary format
show3d   - tool to display HOB files

Additional Tools:
- GetObj   - Display the location of external reference objects in flt file
- ImgInfo  - Display Image dimension to the closest power of 2
- toLower  - Convert texture location and external reference to lower case
- StripCol - Remove the color per vertex flag from the flt file
- ReadOLst - Display the content of the object list file
- getLoc   - Display the location of certain polygons (to be used by Falcon)
- getCoord - Display the first 3 vertices of certain polygons (to be used for
  canvas stuff)
- DumpFlt  - Dump the content of the flt file

File extension:
--------------
HOT = Hierarchical Object Text
HOB = Hierarchical Object Binary
ANS = ANimation Script

0-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-0

I. Create data files required by the 3d library:

0-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-0

1. Create FLT files, sort polygon with bsp if necessary

Use GameGen to generate FLT file

FLT restriction and requirement:
-------------------------------
- DOF beads must be named dofn or dn where n is a number between 1 to max dof
- Switch beads must be named swn where n is a number between 1 to max sw
  Note: Switches in Gamegen must have unique number. In order to have switches
  with the same number, you have to use 5 digits format as follow:
  sw1XX## where:
  1 is the flag to indicate that this switch will use XX as its number
  XX is the switches number
  ## is number to make the 5 digits unique
  i.e: sw10101, sw10102, and sw10103 means all of these switches will be
  renamed sw1 during HotToHob conversion.
- The maximum number of elements in a switch bead is 32 elements
- To use transparent texture (chromakey) on polygons, set 'Fixed/Alpha' in Face
  Attribute. ChromaKey color is assumed to be color index 0 for 8 bit textures
  or 0,0,0 for 24 bit textures.
- To use billboard type polygons, set 'XYZ/Alpha' in Face Attribute.
- To use billboard tree type polygons, set 'Z/Alpha' in Face Attribute.
- Billboard type and Billboard Tree type will use transparent texture only.
- For objects that required LOD, the FLT files are special restricted files.
  The FLT file must consist only the LOD beads which must be done in a
  sequential order from LOW switchIN to HIGH switchIN. All other values in
  the LOD beads are ignored including the switchout values. The LOD beads
  can only have external reference as their children. The external reference
  beads will store the name of flt file of the curent lod.
- The first BoundingBox or BoundingSphere bead found will be used to calculate
  the object center and size. If there is no BoundingBox or BoundingSphere
  beads found, I will calculate the bounding box from the object's vertices.
- Object beads named with slotn where n is a number between 1 to max slot are
  special object beads to handle object insertion in runtime (ie: missiles)
  This object bead must have one face bead (point) child only. The point
  coordinate will be used to specify the center of objects inserted during
  the runtime.
- Alpha Blend values from Gamegen ColorTable will be ignored.
- Group, Object, Switch, DOF, BSP, BoundingBox, BoundingSphere, and polygon
  beads are required to have a child else the conversion tools will fail!
- Not all features of GameGen are supported

These are the list of FLT beads currently supported:
---------------------------------------------------
Group
Object
LongIdentifier
BSP
Polygon
VertexList
Push
Pop
Header
TextureReference
SharedVertex 
VertexCoordinate
Vertex_NormalCoordinate
Vertex_TextureCoordinate
Vertex_Normal_TextureCoordinate
ColorTable
Material
DegreeOfFreedom
Switch
BoundingBox
BoundingSphere
Subface

These beads are supported only in RegisObj tool:
LevelOfDetail --> Only used to get the switchin value
ExternalReference --> Only used to get the current LOD object filename

Note: Special keywords in the Comment bead:
Animation animationfile
VertexColorPatch vertexpatchfile
DisableMask disablebits
TextureSet totaltextureset
Scale scalefactor
DynamicVertex vertexfile

0-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-0

2. Convert FLT files to HOT files (Text format)

Use FLTtoHOT tool to convert FLT file to HOT file.

Usage: FLTtoHOT fltfile [options]
options:
-ohotfile --> where hotfile is the output file (Default file used is the
              fltfile with extension replaced with HOT)
-sScale   --> to scale up/down object (Default scale is 1)
-aAnsfile --> set the animation script file to use for automated articulation.
              Read the ANimation Script section below for more information on
              how to create ANS file.
-pcolorpatch   --> set the Vertex Color patch file if required
-vvertexfile   --> set the Dynamic Vertex file if required
-tTexSetNo     --> set the total number of texture set
-ddisablemask  --> Set disable flag for the current object (1 = disable)
-fpolylistfile --> Set any polygon found in the polylist file to info type.

DisableMask bits:
    0x01000000 --> disable shading
    0x02000000 --> disable smooth shading
    0x04000000 --> disable texture
    0x08000000 --> disable transparent texture (chromakey)
    0x10000000 --> disable alpha blend
    0x20000000 --> disable gouraud color mode --> use solid instead
    0x40000000 --> always enable perspective texture
    0x80000000 --> always enable texture for the object

Vertex Color patch file format: (color in floating point format)
------------------------------
polyvertexindex polyname red green blue alpha
polyvertexindex polyname red green blue alpha
   :
   :
-1

Dynamic Vertex file format:
--------------------------
polyvertexindex polyname
polyvertexindex polyname
   :
   :
-1

Note: Watch out for the Error messages during execution! It may indicate there
      is a problem with the input and/or output file.

0-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-0

3. Create Input file (objects list)

Create the input file to be used for RegisTex and RegisObj tools.

input file format:
-----------------
objectid fltfilename objectdescription
  :
  :

where:
objectid is the unique id number of objects.
fltfilename is the object flt file
objectdescription is the description of the object

0-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-0

4. Create Texture List

Use RegisTex tool to create texture list file. Texture List file is used by
the 3d library internally to create texture id table.

Usage: RegisTex inputfile [options]
inputfile is objects list file created in step 2 above
options:
-s            --> Input is a single flt file
-otexlistfile --> texlistfile is output file (Default is texture.lst)
-i            --> Insert textures into the existing list

Note: 
- If option '-i' is specified, the existing list will be used; otherwise,
  a new list will be created (default).
- Watch out for the Error messages during execution! It may indicate there
  is a problem with the input and/or output file.

Texture List output format: (in BINARY format)
--------------------------
maxtextureid+1
textureid texturename
   :
   :
-1

Note: Don't modify the Texture List file without RegisTex tool unless you
know what you are doing.

0-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-0

5. Create Color List

Use RegisCol tool to create color list file. Color List file is used by
the 3d library internally to create color table.

Usage: RegisCol colorlist [hotfile]
colorlist is the output color list file
hotfile is hot file to be registered (optional)
If hotfile is not specified, all hot files in the current directory will be
registered.

Note: 
- Watch out for the Error messages during execution! It may indicate there
  is a problem with the input and/or output file.

Color List output format: (in BINARY format)
-------------------------
totalcolor
color (4-bytes 'agbr' format)
   :
   :

Note: Don't modify the Color List file without RegisCol tool unless you
know what you are doing.

0-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-0

6. Convert HOT files to HOB files (Binary format)

Use HOTtoHOB tool to convert HOT file to HOB file.

Usage: HOTtoHOB hotfile [options]
options:
-ohobfile   --> where hobfile is output file (Default file used is the
                hotfile with extension replaced with HOB)
-ttexfile   --> where texfile is the texture list file (Default file used is
                texture.lst)
-ccolfile   --> where colfile is the color list file (Default file used is
                color.lst)

Note:
- All ANS files must be located in the current directory, if not the animation 
  will be disabled.
- Texture list file (default file is texture.lst) must be located in the 
  current directory, if not texture will be disabled for the object.
- Texture list file is generated by 'RegisTex' tool
- Color list file is generated by 'RegisCol' tool
- Watch out for the Error messages during execution! It may indicate there
  is a problem with the input and/or output file.

0-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-0

7. Create Objects List

Use RegisObj tool to create objects list file. Object List file is used by
the 3d library internally to create 3d object id table.

Usage: RegisObj inputfile [options]
inputfile is objects list file created in step 2 above
options:
-s            --> Input is a single flt file
-oobjlistfile --> objlistfile is output file (Default is objects.lst)
-i            --> Insert object into the existing list

Note: 
- If option '-i' is specified the existing list will be used; otherwise, 
  a new list will be created (default).
- If option '-s' is specified, you will be asked to enter objectid and desc.
- objectid must be unique id, if it is not unique, program will terminate.
- All files required (flt and hob) must be located in the current directory
  during execution.
- Watch out for the Error messages during execution! It may indicate there
  is a problem with the input and/or output file.

Object List output format: (in BINARY format)
-------------------------
maxobjectid+1
objectid
objectdescription
objectradius
maxdof maxswitch maxslot maxanim maxdynamicvertex
totallod
switchdistance flag objectname
    :
    :
-1

Note: Don't modify the Object List file without RegisObj tool unless you
know what you are doing.

0-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-0

8. Create Palette List

Use RegisPal tool to create palette list file. This step is optional and only
required if you want to use palettized texture.

Usage: RegisPal inputfile [options]
inputfile is the texture list file created by RegisTex tool or an image file
options:
-s           --> inputfile is an image file (LBM, PCX, GIF)
-ooutputfile --> specify the palette list file (Default PALETTE.LST)
-dtexturedir --> specify the location of texture (must include \ at the end)
                 (Default location is the current directory)

Note: 
- If the output palette file has already existed, the content of the file 
  will be loaded first before processing other files.
- Watch out for the Error messages during execution! It may indicate there
  is a problem with the input and/or output file.

Palette List output format: (in BINARY format)
--------------------------
maxtextureid+1
paletteid
   :
   :
totalpalette
palettelist (each palette size 256*4 bytes)
   :
   :

0-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-0

II. 3D library Information (Programmer's Guide)

The latest files can be found in code\erickj\3dlib

Assumptions used:
- Transformation matrix axes: (Falcon4 Coordinate system)
  X = north, Y = east, Z = down
  --> Rotation around x axes = roll, y axes = pitch, z axis = yaw
- Coordinate axes (Screen Coordinate system): X = east, Y = down, Z = north
- Rotation order: X -> Y -> Z -> X -> Y (counter clockwise)
- Object transformation matrix: Z X Y
- Row Matrix (vtx = vtx * mat)
- 3DR/DirectDraw is not part of the 3d library (Sample codes are available)
- C++ (Visual C++ v4.x)
- Use 4 bytes alignment
- other Visual C++ compiler options: Pentium, Multi-threaded
- Link with mpr97.lib, ddraw.lib, and winmm.lib

0-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-0

1. Additional files required