Obj3d programmer's reference
-----
last update: 4/16/99
version 2.0


* Obj3d and lib3d memory map:

|-|x|--|x|---------------|xxxx|------|xxxxxx|------|xxxx|-------------------|
  |    |                 |           |             |
  $41  $0200             $4F00       $8400         $C000


$41-$49         Orientation matrix
$4A-$52         Viewpoint matrix
$53,$54         Xoffset, Yoffset (screen offsets -- where 0,0 is on screen)
$55-$72         Various temporary pointers and variables
$60-$67		X1,Y1,X2,Y2 -- signed 16-bit coordinates for PLOT and DRAWLINE
$8B-$8E		PLISTZLO, PLISTZHI -- pointers to rotated z-coordaintes
$A3-$AE         CXLO, CXHI, CYLO, CYHI, CZLO, CZHI -- Pointers to rotated
                centers.
$AF-$B0         ROTMATH -- pointer to rotation math table
$B1-$B8         MULTLO1 LO2 HI1 HI2 -- pointers to multiplcation tables
$B9             Bitmap (high byte)
$BB-$BC         FILLPAT -- pointer to fill pattern (not table)
$BD-$C4         PLISTXLO, XHI, YLO, YHI -- pointers to rotated/projected points
		(PLISTZLO = $8B, above)

$0200           Point queue
$4F00		LINELO -- Record drawn lines in wireframe
$4F68		LINEHI
$4FD0		OBLETS -- Sorted oblet list
$5000           obj3d
$5600-$5D00     obj3d tables:
	$5600	OBJLO  -- Object list (pointers)
	$5680	OBJHI
	$5700	VISOBJ -- Visible object list
	$5781	OBCEN  -- Center object number
	$5800	CX	- Translated rotated centers
	$5880	HCX	- (high byte)
	$5900	CY
	$5980	HCY
	$5A00	CZ
	$5A80	HCZ
	$5B00	PLISTX	- Point list (projected)
	$5B80	(high bytes)
	$5C00	PLISTY
	$5C80	(high byte PLISTY)
	$5D00	PLISTZ
	$5D80	high byte
$5E00-$5FFF     ROTMATH -- rotation table (relocatable, pointed to by $AF)
$8400-$9FFF     lib3d
$C000-$C2FF     MULTLO, pointed to by $F7-$F8 and $F9-$FA
$C300-$C5FF     MULTHI, pointed to by $FB-$FC and $FD-$FE
$C600-$CFFF     More tables (nonrelocatable, see lib3d.text)

				----------------

So, to put it another way, free areas of RAM are:

$02-$40
$55-$72 (temporary only; library work variables)
$90-$A2
$C5-$FF

$02xx-$4FFF
$6000-$83FF
$A000-$BFFF
$D000-$FFFF

|-|x|--|x|---------------|xxxx|------|xxxxxx|------|xxxx|-------------------|
  |    |                 |           |             |
  $41  $0200             $4F00       $8400         $C000

Moreover, the range $C000-$C5FF can be made available by relocating the
tables there.  This way, $E000 may be used as a bitmap, with enough extra
room for 8 sprite definitions.  Thus, bitmaps are available in all banks.


* Object record

ObjCX    = 0		;Center, X-coord (signed 16-bit)
ObjCY    = 2		;Y-coord
ObjCZ    = 4		;z-coord
ObjData  = 6		;Pointer to structure data
ObjID    = 8		;User bytes
ObjUser	 = 9
ObCenPos = 10		;Position in center list
ObjCXRem = 11		;Center remainders
ObjCYRem = 12
ObjCZRem = 13
ObjMat   = 14		;Viewpoint matrix, int + rem
ObjSize  = 32           ;32 bytes total


* Jump table

Init3D      = $5000          	;Initialize lib3d
AddObj      = Init3D+3       	;Add object to object list
DelObj      = AddObj+3       	;Delete object from list
SetCurOb    = DelObj+3       	;Set current object
GetCurOb    = SetCurOb+3     	;Get current object
GetNextOb   = GetCurOb+3    	;Get next object in list
GetObj      = GetNextOb+3    	;Get pointer to object

SetMat      = GetObj+3       	;Calculate and set object matrix
Pitch       = SetMat+3       	;Pitch - rotate object around x-axis
Yaw         = Pitch+3        	;Yaw - rotate around y-axis
Roll        = Yaw+3          	;Roll - rotate around z-axis
MoveSide    = Roll+3         	;Move object
MoveUp      = MoveSide+3
MoveForwards = MoveUp+3
GetSideVec  = MoveForwards+3 	;Orientation vectors
GetUpVec    = GetSideVec+3   	;(length=64)
GetFrontVec = GetUpVec+3

SetParms    = GetFrontVec+3  	;Set rendering parameters

SetVisParms = SetParms+3	;Set visibility parameters
CalcView    = SetVisParms+3  	;Set viewpoint = object
SortVis     = CalcView+3     	;Compute and sort visible objects
DrawAllVis  = SortVis+3    	;Draw all visible objects
GetNextVis  = DrawAllVis+3 	;Draw next objesible object list
RotDraw     = GetNextVis+3  	;Rotate and draw object
DrawFace    = RotDraw+3		;Draw single face (polygon)

* lib3d stuff

CALCMAT  EQU $8800
ACCROTX  EQU $8803
ACCROTY  EQU $8806
ACCROTZ  EQU $8809
GLOBROT  EQU $880C
ROTPROJ  EQU $880F
POLYFILL EQU $8812
PLOT     EQU $8815
DRAWLINE EQU $8818
VERSION  EQU $881B


Routine descriptions
--------------------

Init3D
  On entry: .AY = pointer to object record storage area
  On exit:

  This routine is used to initialize various obj3d and lib3d pointers and
  variables, and should be called before any other routines are called.
  Note that if e.g. tables or the screen center are moved around, the
  corresponding variables should be set *after* calling Init3D.

AddObj
  On entry: .AY = pointer to object structure data
            .X  = optional user ID byte
  On exit:  .AY = pointer to object
            .X  = object number
            C set indicates error (e.g. too many objects!)

  AddObj is used to add objects into the world.  It places the object at
  the first empty spot in the active object list, and allocates a 
  corresponding portion of memory in the object storage area, as passed
  to Init3D.

SetCurOb
  On entry: .X  = object number
  On exit:  .AY = pointer to object
            .X  = object number

  SetCurOb is used to set the current object.  The "object number" is
  a number returned by AddObj.  This routine is used before calling
  e.g. the movement routines, which act on the current object.

GetCurOb
  On entry:
  On exit:  .AY = pointer to object
            .X  = object number

  GetCurOb is used to get the current object number and pointer.

GetOb
  On entry: .X  = object number
  On exit:  .AY = pointer to object

  GetOb gets a pointer to an object without setting that object to
  be the current object.

DelObj
  On entry: .X  = object number
  On exit:  C set means rather nasty error

  DelObj is used to delete an object from the active object list.

GetNextOb
  On entry:
  On exit: .X  = object number
           .AY = object pointer
           C = 1 -> error

  GetNextOb gets the next object in the active object list, starting from
  the current object.  On exit, the current object is set to .X.  This
  routine may be used to cycle through the list of active objects.


* Object manipulation routines


SetMat
  On entry: .X  = angle around x-axis
            .Y  = angle around y-axis
	    .A  = angle around z-axis
  On exit:

  SetMat is used to set a rotation matrix for the current object.  Angles
  go from 0..127.  Note that SetMat rotates around the fixed _world_ axis, 
  not an object's local coordinate axis; use Yaw/Pitch/Roll to rotate about
  the local axis.

Yaw
Pitch
Roll
  On entry: C clear -> positive rotation
            C set   -> negative rotation
  On exit:
  
  Yaw, Pitch, and Roll rotate an object by a fixed amount (3 degrees or so)
  about the local coordinate axis.  (The local coordinate axis rotates
  with the object).

MoveUp
MoveSide
MoveForwards
  On entry: .A  = distance (signed)
  On exit:

  MoveUp/Side/Forwards are used to move an object along its local coordinate
  axis, by an amount proportional to .A; negative values of .A will move in
  the opposite direction.

GetUpVec
GetSideVec
GetFrontVec
  On entry:
  On exit: (.X,.Y,.A) = signed (x,y,z) coordinates of orientation vector

  GetVec is used to figure out what direction the current object is
  pointing in.  The vectors are signed, and of length 64.


* Visualization routines


SetParms
  On entry: .AY = pointer to pattern table
	    .X  = Bitmap address (high byte)
	    C set   -> solid polygons
	    C clear -> wireframe
  On exit:

  SetParms is used to set certain rendering parameters.  The pattern table
  consists of a list of 8x8 patterns.

SetVisParms
  On entry: .AY = Maximum object range
	    .X  = Minimum object range
  On exit:

  SetVisParms is used to set the range in which an object is considered
  "visible".  An object's center z-coordinate is compared to these values;
  the range is not a radius.

CalcView
  On entry: .X  = Viewpoint object
  On exit:

  CalcView computes the view from the viewpoint object, by translating
  and rotating centers relative to the viewpoint object.  The relative
  centers are stored in the CX HCX etc. lists; the ObCenPos element in
  the object record is an index into this list.

SortVis
  On entry:
  On exit:

  SortVis computes a sorted list of visible objects.  Objects are visible
  if they are within a 45 degree cone forwards of the viewpoint object,
  and within the min/max visibility range, which may be changed with
  SetVisParms.  CalcView must be called before calling this routine.
  Sorting is necessary to ensure that objects overlap one another
  correctly on the screen.  On exit, the current object is set to the
  first object in this list.

DrawAllVis
  On entry:
  On exit:

  DrawAllVis draws all visible objects, in order, as determined by SortVis.

GetNextVis
  On entry:
  On exit:  .X  = Current object
	    .AY = Pointer to object
	    N set -> at end of list

  GetNextVis fetches the next object in the visible object list, setting
  it to the current object.  This routine is used to draw one object at
  a time, but in the proper order.

RotDraw
  On entry: .X = Object number
  On exit: Cool rendered polygon

  RotDraw renders an object to the screen, by rotating and projecting
  the object vertices and then drawing faces, either wireframe or solid.
  On exit, the rotated and projected points, i.e. the screen coordinates
  of the object, are stored in PLISTX and PLISTY; PLISTZ contains the
  rotated (but not projected) z-coordinates.

DrawFace
  On entry: .AY = pointer to face data
  On exit:  .AY = pointer to next face

  DrawFace renders a polygon to the screen, either wireframe or solid.
  It would be an awfully good idea to have the rotated points in PLIST,
  i.e. to call RotDraw before calling this routine.