The 3D library use a file not included in the 3d library:
- loader.cpp  --> class to load texture and 3d object files asynchronously

To get the latest file ask Scott Randolph

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

2. Additional setup/cleanup required

- The 3D library doesn't maintain a display list. If you disabled zbuffer,
  you have to maintain your own display list, i.e: sort all 3d objects and 
  display them based on the distance.
- The 3D library doesn't setup/cleanup the 3DR and DirectDraw. You have to 
  setup and cleanup the 3DR and DirectDraw yourself. 3DR must be setup and
  cleanup using the 'context' class.


To enable perspective texture, filtering, or palettized texture:
context.SetupMPRState (flag);

where flag bit values: (can be ored together)
ENABLE_FILTERING_STATE - enable filtering & perspective texture
ENABLE_PERSPECTIVE_STATE - enable perspective texture
ENABLE_PALETTIZED_TEXTURE_STATE - enable palettized texture


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

3. 3D setup/cleanup

- setup:
glSetUp3D (objectlistfile, colorlistfile, texturelistfile, palettelistfile);
Note: If return value is not 0, abort the program!
objectlistfile is file created by RegisObj tool
colorlistfile is file created by RegisCol tool
texturelistfile is file created by RegisTex tool
palettelistfile is file created by RegisPal tool
Note: palettelistfile must be specified to enable palettized texture. If it is
not specified then do not enable palettized texture mode.

- Set the 3d objects and textures location:
glSetObjectDirectory (objectdirectory);
glSetTextureDirectory (texturedirectory);

- To delete texture from memory immediately
glDeleteTexture (textureid, 1); // 1 is a flag to indicate to remove texture
                                // from memory immediately

Note: Texture will be deleted when all objects using the texture have been
deleted. Use this function if you want to delete the texture but don't want
to wait until objects got deleted. Make sure the texture deleted are not used
by any objects, or else the texture wil be loaded again when any polygons
using the texture are displayed.

- To replace texture with another:
glReplaceTexture (textureid, replacementid);

- To restore texture to the original texture before replacement:
glRestoreTexture (textureid);

These texture functions are provided so that user can have control over which
texture to be used on polygons. Textures must be defined in every object that
might use them or else the texture reference counter might mess up.

- cleanup:
glCleanUp3D ();

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

4. Setup camera:

- Define camera object with GLViewport class

- Setup viewport:
  glSetViewport (3drcontext, left, top, right, bottom, hScale, vScale);
  Note: 
  - hScale and vScale is used to scale object radius during object culling
    hScale and vScale can be calculated using function:
    glCalculateViewScale (&hScale, &vScale, cameraangle, scrwidth, scrheight);
  - Center of projection is assumed to be the center of the viewport. It was
    done this way to speed up the process.
  - Because 3DR use subpixel, right and bottom are at position + 1.
    i.e: For 640x480 viewport size, right is 640, bottom is 480

- Setup camera location and matrix:
  glSetCameraPosition (coord);
  camera coordinate use 'Screen Coordinate' --> north = z, east = x, down = y

  glSetCameraMatrix (cameramatrix, billboardroll, billboardpitchroll);
  matrix use 'Falcon4 Coordinate' --> north = x, east = y, down = z
  cameramatrix = camera matrix
  billboardroll = matrix used for billboard type object (yaw and pitch = 0)
  billboardpitchroll = matrix used for billboard tree type object (yaw = 0)

  To create camera matrix, you can use function glCreateInverseTransformation
  with cameraangle defaults to 90 degrees:
  glCreateInverseTransformation (yaw, pitch, roll, mat);

  To set the cameraangle other than 90 degrees, pass the camera angle, width 
  and height of the screen:
  glCreateInverseTransformation (yaw, pitch, roll, mat, angle, width, height);


The following functions are members of GLViewport class.

- Setup depth-cue color and distance if necessary:
  glSetDepthCueColor (red, green, blue);
  Call this function to set the depth cue color. Default to white (1, 1, 1)

  glSetDepthCueDistance (neardistance, fardistance);
  Call this function to set the near and far distance for depth-cueing. If
  object distance is less than near distance, there is no depth-cueing. If
  object distance is greater than far distance, object will not be displayed.
  If object distance is between the near and far distance, object color will
  be calculated based on the distance. Near and far must be positive values.

  glEnableColorMode (colormode);
  glDisableColorMode (colormode);
  Call these functions to enable or disable color mode. Default is disabled.

Color mode currently supported:
GL_MAKE_COLOR_GREEN - convert all color to shades of green

- Setup LOD Scale factor if necessary:
  glSetLODScaleFactor (scale);
  Use this only if you want to change how the lod objects processed

- Setup plane XZ clipping value if necessary:
  glSetPlaneXZClipValue (value);
  Use this only if you want to clip 3d object with altitude other than 0

- Setup time inside the loop
  glSetTime (time);
  This is required in order to get real time articulation from the animation
  script files. The 'time' keyword in the ANS file use the value returned
  from this function. Call this in the beginning of the loop.

- Setup global detail mask. All 3d objects in the current viewport will be
  effected. By default, zbuffer is disabled.

  glEnableSurfaceDetail (mask);  --> enable global detail
  glDisableSurfaceDetail (mask); --> disable global detail
  glToggleSurfaceDetail (mask);  --> toggle global detail

mask bits: (Can be ored together)
GL_DETAIL_SHADING
GL_DETAIL_SMOOTH_SHADING
GL_DETAIL_TEXTURE
GL_DETAIL_TEXTURE_MASK - transparent texture/chromakey
GL_DETAIL_TRANSPARENT  - alpha blend
GL_DETAIL_GOURAUD

Note: Gouraud is not the same as Smooth Shading! Gouraud Color mode is enabled
only if all vertices on the polygons have color information. If gouraud mode
is disabled, polygon will use solid color mode.

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

5. Setup/cleanup 3d object/instance

- Add 3d object/instance
  glAdd3DObject (objectID);
  If you want to load the object right away, pass the 3dr handle:
  glAdd3DObject (objectID, rc);

- Get anim data for the current instance
  glGetObjectAnimation (objectID);
  return the pointer to animation data (Pass this to the display function)
  If there is no animation data or error in allocating memory, return 0

- Get object bounding box min max
  glGetObjectBoundingBox (objectID, &max, &min);
  return 0 if can not get object bounding box
  else return 1 and min and max contain object bounding box

- Get object radius
  glGetObjectRadius (objectID);
  return the radius of the object.

- Get object description
  glGetObjectDescription (objectID);
  return the object description.

- Get object slot offset (position)
  glGetObjectSlotOffset (objectID, slotno);
  return the pointer to slot offset, if object has no slot, return 0.

- Delete 3d object/instance
  glRemove3DObject (objectID);
  if object has anim data, pass the data returned from glGetObjectAnimation:
  glRemove3DObject (objectID, anim);
  Note: The 3D library doesn't maintain the anim data for instances. You have
  to keep track each instance and remove the instance's anim data at the end.

- disable/enable animation script
  glDisableAnimationScript (anim);
  glEnableAnimationScript (anim);


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

6. Display 3d object

There are three display functions available:
glDisplayObjectShadow (view, objectID, objectcenter, objectmat, objectscale, 
                       animdata, textureset);
glDisplayObjectClip   (view, objectID, objectcenter, objectmat, objectscale, 
                       animdata, textureset);
glDisplayObject       (view, objectID, objectcenter, objectmat, objectscale, 
                       animdata, textureset);
where:
view = pointer to viewport
objectcenter = pointer to object coordinate in 'Screen Coordinate' system
objectmat = pointer to object transformation matrix
objectscale = default to 1
animdata = pointer to data returned from glGetObjectAnimation function 
(Default to no animdata which mean there is no articulation/inserted objects)
textureset = index to the texture set to use (Default to 0)

glDisplayObjectShadow - function to display shadow object
glDisplayObjectClip   - function to display object clipped with XZ plane

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

7. Light source

- setup
  glSetAmbientIntensity (ambientintensity);
  glSetDiffuseIntensity (diffuseintensity);
  Note: total of ambient and diffuse intensity must be <= 1

  glSetPointLight (lightcoord);    --> set point light source coordinate
  glSetLightDirection (lightdir);  --> set light source direction

  Note: lightcoord and lightdir use the 'Screen Coordinate' system, where
  north = z, east = x, down = y

  glEnablePointLight ();
  Call this function to enable point light source. The default light source
  is direction light. You can only use either point light or direction light
  but not both. The used of more than one light might slow down the rendering.
  Note: Point light source method used in this library is calculated from the
  object center. So, every polygon in the current object will have the same
  light effect as the directional light. The difference is: directional light
  method will always produce the same direction for every objects but point
  light source method might produce different light direction for each object
  depending on the object and light position in the world. The correct way of
  doing point light source is to calculate the light direction from each 
  polygon's center, or preferebly from each vertices, but the additional 
  calculation might slow down the rendering, maybe significantly.

  glDisablePointLight ();
  Call this function to disable point light source method and enable the 
  directional light source method.

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

8. Math functions

- glGetSinCos (sine, cosine, angle);
where: sine and cosine are pointer to double variables
       angle is a fixed point angle (16384 = 360 degree)
This function will return the sine and cosine (double values) of an angle

- glGetSine (angle);
This function will return the sine (double value) of an angle

- glGetCosine (angle);
This function will return the cosine (double value) of an angle

- glCreateTransformation (yaw, pitch, roll, matrix);
where: yaw, pitch, roll are the orientation
       matrix is pointer to 3x3 matrix
This function will create transformation matrix

- glCreateTransformationScale (yaw, pitch, roll, scale, matrix);
This function will create transformation matrix with scaling

- glQuaternionToMatrix (q, m);
where: q is pointer to quaternion structure
       m is pointer to matrix structure
This function will convert quaternion to 3x3 matrix

- glMatrixToQuaternion (q, m);
This function will convert 3x3 matrix to quaternion

- glInterpolateQuaternion (start, end, current, t, spin);
where: start is the start of quaternion
       end is the end of quaternion
	   current is the current quaternion (output)
	   t is a number between 0 to 1. 
	   If t = 0, current = start, if t = 1, current = end;
	   spin = the number of spin between quaternion
This function will interpolate quaternion from start to end based on t value.

- glInterpolateQuaternionX (start, end, current, t, spin);
This function will interpolate quaternion from start to end based on t value.
This function will also interpolate the translation and scale values linearly.

- glVectorDistance (p1, p2);
where: p1 and p2 are pointer to vertex
This function will return the distance between two 3d points

- glVectorLength (p);
This function will return the size of a vector

- glMultVertex (vtx1, vtx2, matrix);
This function will multiply a vertex by a matrix (vtx1=vtx2*matrix)

- glMultIVertex (vtx1, vtx2, matrix);
This function will multiply a vertex by an inverse matrix (vtx1=vtx2*matrix)

- glMultMatrix (mat1, mat2, mat3);
This function will multiply a matrix by a matrix (mat1=mat2*mat3)

- glMultIMatrix (mat1, mat2, mat3);
This function will multiply a matrix by an inverse matrix (mat1=mat2*mat3)

- glScaleMatrix (mat1, mat2, scale);
This function will scale a matrix (mat1 = mat2 * scale)

- glCalculateInverseMatrix (mat, invmat);
This function will calculate the inverse of a matrix

- glNormalizedVector (vtx);
- glNormalizedVector (vtxin, vtxout);
These functions will normalized a vertex

- glNormalVector (vtx1, vtx2, vtx3, vtxout);
This function will calculate the normal vector of three vertices

- glCrossProduct (vtx1, vtx2, vtxout);
This function will calculate the cross product of two vertices

- glDotProduct (vtx1, vtx2);
This function will return the dot product of two vertices

- glDotProductW (vtx1, vtx2);
This function will return the dot product of two vertices (x,y,z,w)

- glNormalizedDotProduct (vtx1, vtx2);
This function will return the normalized dot product of two vertices

- glSignOfDotProduct (vtx1, vtx2);
This function will return the sign of dot product of two vertices (-1, 1, 0)

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

9. Misc functions:

- glAllocateMemory (totalbytes, clearit);
where: totalbytes = total memory to be allocated (in bytes)
       clearit = memory clear flag, if 1, clear memory allocated (default)
This function will allocate memory and return a pointer to the memory just
allocated. If can not allocate memory, this function will return 0.

- glReleaseMemory (memptr);
This function will release memory allocated

- glConvertToRadian (fpdegree);
This function will convert fixed point degree to radian and return the result

- glConvertFromRadian (radian);
This function will convert radian to fixed point degree and return the result

- glConvertToDegree (fpdegree);
This function will convert fixed point degree to degree and return the result

- glConvertFromDegree (degree);
This function will convert degree to fixed point degree and return the result

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

10. Object Slot:

This is a feature to insert object into a slot defined in another object. This
slot is defined by naming an object bead as slotn where n is the slot number.

Functions available:
- glInsertObjectInSlot (objectID, slotno, anim);
where: anim is the instance animation structure
       objectID is object to be inserted (i.e. missile)
       slotno is the slot number the object to be inserted (start from 0)
Use this function to insert object into another object slot

- glRemoveObjectInSlot (slotno, anim);
where: anim is the instance animation structure
       slotno is the slot number the object to be removed (start from 0)
Use this function to remove object in the slot

- glSetObjectSlotMatrixVar (slotno, anim, mat);
where: anim is the instance animation structure
       slotno is the object slot number (start from 0)
       mat is the object orientation matrix
Use this function to define the object orientation matrix (which default to