From: mlab2@kuhub.cc.ukans.edu
Newsgroups: comp.sys.mac.programmer
Subject: Graf3D and What I Discovered ThereIn - part 1
Date: 26 Nov 90 23:49:04 GMT
Organization: University of Kansas Academic Computing Services

Some UseNetter's thought this might be beneficial to the net, so, here goes the
first installment of "Graf3D and What I Discovered Therein."  Feel free to
correct and dispute anything I say.  I'm not an expert programmer and only
stumbled through Graf3D a year and a half ago.  Also, sorry, I don't know C.

"Graf3D and What I Discovered Therein - Part1"
==============================================
Here are the following functions/procedures and data types that Graf3D defines:

Data Types:
  Fixed    (Essentially a LongInt <32-Bit> number where the high 16 bits
            represent the integer portion of the number and the low 16 bits
            represent the fractional portion of the number.  HiWord and LoWord
            can be used to extract said portions.  To convert a LongInt to a
            Fixed type, divide the LongInt by 65536 <2^16>)

  Point3D   = RECORD
               x:Fixed;
               y:Fixed;
               z:Fixed;
            END;
           (Note: Unlike the Point type, h and v are called x and y <and z>
            and are of type Fixed instead of Integer.)

  Point2D   = RECORD
               x:Fixed;
               y:Fixed;
            END;
           (Note: Why a Point2D and not just Point?  a- It uses the Fixed type
            variable, and b- It is thus easy to convert between a Point3D and
            Point2D for screen display.)

  XfMatrix  = ARRAY [0..3, 0..3] of Fixed;
           (This is the transformation matrix that Graf3D uses to rotate and
            translate points.  If your familiar with the concepts and lingo
            used in 3D graphics, you'll know all about the transformation
            matrix.)

  Port3DPtr = ^Port3D;
  Port3D    = RECORD
                GrPort: GrafPtr;
                viewRect: Rect;
                xLeft, yTop, xRight, yBottom: Fixed;
                pen, penPrime, eye: Point3D;
                hSize, vSize: Fixed;
                hCenter, vCenter: Fixed;
                xCotan, yCotan: Fixed;
                ident: Boolean;
                xForm: XfMatrix;
              END;

           (I'll discuss each of these fields to the Port3D in the next
            installment.)

  (Functions and Procedures)

PROCEDURE InitGraf3D (GlobalPtr: Ptr);

PROCEDURE Open3DPort (port: Port3DPtr);

PROCEDURE SetPort3D (port: Port3DPtr);

PROCEDURE GetPort3D (VAR port: Port3DPtr);

PROCEDURE MoveTo2D (x, y: Fixed);

PROCEDURE MoveTo3D (x, y, z: Fixed);

PROCEDURE Move2D (dx, dy: Fixed);

PROCEDURE Move3D (dx, dy, dz: Fixed);

PROCEDURE LineTo2D (x, y: Fixed);

PROCEDURE LineTo3D (x, y, z: Fixed);

PROCEDURE Line2D (dx, dy: Fixed);

PROCEDURE Line3D (dx, dy, dz: Fixed);

FUNCTION Clip3D(src1, src2: Point3D; VAR dst1, dst2: Point);

PROCEDURE SetPt3D (VAR pt3D: Point3D; x, y, z: Fixed);

PROCEDURE SetPt2D (VAR pt2D: Point2D; x, y: Fixed);

PROCEDURE ViewPort (r: Rect);

PROCEDURE LookAt (left, top, right, bottom: Fixed);

PROCEDURE ViewAngle (angle: Fixed);

PROCEDURE Identity;

PROCEDURE Scale (xFactor, yFactor, zFactor: Fixed);

PROCEDURE Translate (dx, dy, dz: Fixed);

PROCEDURE Pitch (xAngle: Fixed);

PROCEDURE Yaw (yAngle: Fixed);

PROCEDURE Roll (zAngle: Fixed);

PROCEDURE Skew (zAngle: Fixed);

PROCEDURE Transform (src: Point3D; VAR dst: Point3D);

Whew!  That's it.  Most of this has come straight from the MPW documentation. 
I'll discuss each of these in following installments.  For now, you might note
that many of these have direct QuickDraw counterparts (SetPt, InitGraf, etc...)
that should make many of the procedures and functions almost self explanatory.

Well, all for now!

john calhoun