ThreeDBasics.mesa
Copyright © 1984, 1986 by Xerox Corporation. All rights reserved.
Last Edited by: Crow, March 15, 1989 5:03:12 pm PST
Bloomenthal, September 26, 1988 12:04:57 pm PDT
DIRECTORY
Rope     USING [ ROPE ],
Atom     USING [ PropList ],
Terminal    USING [ Virtual ],
ViewerClasses  USING [ Viewer ],
Imager    USING [ Context, Rectangle ],
ImagerPixel   USING [ PixelMap ],
ImagerSample  USING [ Box ],
ImagerColor   USING [ RGB ],
G3dBasic,
G3dMatrix;
ThreeDBasics: CEDAR DEFINITIONS
~ BEGIN
Basic Types
Error:       SIGNAL [reason: ErrorDesc];
ErrorDesc:      TYPE ~ RECORD [code: ATOM, explanation: Rope.ROPE];
RGB:        TYPE ~ ImagerColor.RGB;
RGBSequence:    TYPE ~ RECORD [
length:        NAT ← 0,
s:          SEQUENCE maxLength: NAT OF RGB];
NatRGB:      TYPE ~ RECORD [r, g, b: NAT];
NatRGBSequence:    TYPE ~ RECORD [
length:        NAT ← 0,
s:          SEQUENCE maxLength: NAT OF NatRGB];
PixelPart:      TYPE ~ { r, g, b, a, z };     -- addressing within Pixels
Pixel:        TYPE ~ ARRAY PixelPart OF CARDINAL; -- r, g, b, alpha, z (depth)
RealSequence:    TYPE ~ G3dBasic.RealSequenceRep;
IntegerSequence:    TYPE ~ G3dBasic.IntegerSequenceRep;
IntSequence:      TYPE ~ G3dBasic.IntSequenceRep;
NatSequence:     TYPE ~ G3dBasic.NatSequenceRep;
NatTable:      TYPE ~ G3dBasic.NatTableRep;
Pair:       TYPE ~ G3dBasic.Pair;     -- RECORD [x, y: REAL];
PairSequence:    TYPE ~ G3dBasic.PairSequenceRep;
IntegerPair:     TYPE ~ G3dBasic.IntegerPair;   -- RECORD [x, y: INTEGER];
IntegerPairSequence:  TYPE ~ G3dBasic.IntegerPairSequenceRep;
Triple:      TYPE ~ G3dBasic.Triple;     -- RECORD [x, y, z: REAL];
TripleSequence:    TYPE ~ G3dBasic.TripleSequenceRep;
Quad:       TYPE ~ G3dBasic.Quad;     -- RECORD [x, y, z, w: REAL];
QuadSequence:    TYPE ~ G3dBasic.QuadSequenceRep;
Box:       TYPE ~ ImagerSample.Box; -- [min, max: [s, f: INTEGER] ← zeroVec]
Rectangle:      TYPE ~ Imager.Rectangle; -- RECORD [x, y, w, h: REAL]
Xfm3D:       TYPE ~ G3dMatrix.Matrix; -- REF 4 by 4 ARRAY OF REAL
Xfm3DRep:      TYPE ~ G3dMatrix.MatrixRep;
ScaleAndAddXfm:    TYPE ~ RECORD[scaleX, scaleY, scaleZ, addX, addY, addZ: REAL];
SixSides:      TYPE ~ {Left, Right, Bottom, Top, Near, Far};
OutCode:      TYPE ~ RECORD [left, right, bottom, top, near, far: BOOLEAN];
NoneOut:      OutCode ~ [FALSE, FALSE, FALSE, FALSE, FALSE, FALSE];
AllOut:      OutCode ~ [TRUE, TRUE, TRUE, TRUE, TRUE, TRUE];
Pixel Shading Definitions
Spot: TYPE ~ RECORD[
coverage: REAL ← 1.0,       -- percentage of pixel area covered by surface
mask: BYTE ← 255,       -- coding for covered area (default, all covered)
partShiny: REAL ← 1.0,      -- how much of shiny surface shows (1.0 = all)
val: REF RealSequence ← NIL,    -- interpolated values for shading
yIncr: REF RealSequence ← NIL,    -- vertical increments for interpolated values
xIncr: REF RealSequence ← NIL,    -- horizontal increments for interpolated values
xySwapped: BOOLEAN,       -- if TRUE, xincr and yincr are swapped
props: Atom.PropList ← NIL     -- catchall
];
SpotProc: TYPE ~ PROC[ context: REF Context, shading: REF ShadingClass, spot: REF Spot,
       data: REF ANY ← NIL ];
Texture Definitions
TextureFunction: TYPE ~ RECORD[name: ATOM, proc: SpotProc, props: Atom.PropList];
TextureMap: TYPE ~ RECORD[type: ATOM, pixels: REF ANY, props: Atom.PropList];
SummedTexture: TYPE ~ RECORD[SEQUENCE length: NAT OF REF SumSequence];
SumSequence: TYPE ~ RECORD[SEQUENCE length: NAT OF REF IntSequence];
Vertex Definitions
Vertex: TYPE ~ RECORD[
x,y,z: REAL ← 0.0,     -- object coordinates
ex, ey, ez: REAL ← 0.0,   -- eyespace coordinates
sx, sy, sz: REAL ← 0.0,    -- screen coordinates
clip: OutCode ← NoneOut  -- clip code
];
VertexSequence: TYPE ~ RECORD[
length: CARDINAL ← 0,
entry: SEQUENCE maxLength: CARDINAL OF REF Vertex
];
ShadingValue: TYPE ~ RECORD[
xn,yn,zn: REAL ← 0.0,   -- normal vector to surface
exn,eyn,ezn: REAL ← 0.0,   -- normal in eyespace
r,g,b: REAL ← 1.0,     -- vertex color (default white) scaled by object color
t: REAL ← 1.0,     -- original transmittance
er,eg,eb,et: REAL ← 0.0 -- computed color and transmittance (for current lights, view, etc.)
];
ShadingSequence: TYPE ~ RECORD[
length: CARDINAL ← 0,
entry: SEQUENCE maxLength: CARDINAL OF REF ShadingValue
];
VertexInfo: TYPE ~ RECORD[coord: Vertex, shade: ShadingValue, props: Atom.PropList,
  aux: REF ANY];
VertexInfoSequence: TYPE ~ RECORD [
length: CARDINAL ← 0,
entry: SEQUENCE maxLength: CARDINAL OF REF VertexInfo
];
VertexInfoProc: TYPE ~ PROC[ context: REF Context, vtx: VertexInfo, data: REF ANY ← NIL ]
       RETURNS[VertexInfo];
VtxToRealSeqProc: TYPE ~ PROC[ dest: REF RealSequence, source: VertexInfo,
          data: REF ANY ← NIL ]
        RETURNS[REF RealSequence];
Patch Definitions
FacingDir: TYPE ~ { front, back, undetermined };
Patch: TYPE ~ RECORD[type: ATOM ← NIL, oneSided: BOOLEAN ← TRUE, nVtces: NAT ← 0,
       clipState: ClipState ← undetermined, dir: FacingDir ← undetermined,
      props: Atom.PropList ← NIL, vtx: SEQUENCE maxLength: NAT OF VertexInfo];
Implemented Patch types: $ConvexPolygon, $Bezier
Standard uses for Props: $Shape (parent shape)
PatchSequence: TYPE ~ RECORD [
length: CARDINAL ← 0,
entry: SEQUENCE maxLength: CARDINAL OF REF Patch
];
PtrPatch: TYPE ~ RECORD[type: ATOM ← NIL, oneSided: BOOLEAN ← TRUE, nVtces: NAT ← 0,
        clipState: ClipState ← undetermined, dir: FacingDir ← undetermined,
        props: Atom.PropList ← NIL, vtxPtr: REF NatSequence];
PtrPatchSequence: TYPE ~ RECORD[
length: CARDINAL ← 0,
entry: SEQUENCE maxLength: CARDINAL OF REF PtrPatch
];
PatchProc: TYPE ~ PROC[ context: REF Context, patch: REF Patch, data: REF ANY ← NIL ]
      RETURNS[REF Patch];
PtrPatchProc: TYPE ~ PROC[ context: REF Context, patch: REF PtrPatch, data: REF ANY ← NIL ]
       RETURNS[REF PtrPatch]; 
Shape Definitions (also used for lights)
ClipState: TYPE ~ { in, out, clipped, undetermined };
ShapeInstance: TYPE ~ RECORD[
class: REF ShapeClass ← NIL,     -- surface type, reloadable display procedures
shadingClass: REF ShadingClass ← NIL,  -- shading parameters and procedures
name: Rope.ROPE ← NIL,       -- local name for Shape (allows instancing)
fileName: Rope.ROPE ← NIL,      -- file name (should be on a server)
fixedProps: Atom.PropList ← NIL,    -- fixed attributes
props: Atom.PropList ← NIL,     -- catchall ($LinesList, $Hidden)
Position and Orientation
location: Triple ← [0.,0.,0.],      -- position in scene space (last transform)
orientation: Triple ← [0.,0.,1.],     -- vector defining orientation (second transform)
rotation: REAL ← 0.,        -- rotation about rotation axis (first transform)
axisBase: Triple ← [0.,0.,0.],      -- rotation axis: direction = End - Base
axisEnd: Triple ← [0.,0.,1.],      --     rotation is about base point
position: Xfm3D ← NIL,       -- transform from definition space to world space
positionInValid: BOOLEAN ← TRUE,    -- location, orientation, or rotation changed
State
insideVisible: BOOLEAN ← FALSE,    -- closed (or open) surface
clipState: ClipState ← undetermined,    -- { in, out, clipped }
shadingInValid: BOOLEAN ← TRUE,    -- true if light or object changed
vtcesInValid: BOOLEAN ← TRUE,    -- true if object or view changed
Image Extent and Bounding Sphere
centroid: Vertex,         -- bounding sphere
boundingRadius: REAL ← 0.0,
screenExtent: Box ← [[0, 0], [0, 0]],    -- extent on screen (when position valid)
Shape and Shading Data
vertex: REF VertexSequence ← NIL,   -- location and clip codes for defining points
shade: REF ShadingSequence ← NIL,    -- shading at defining points
numSurfaces: NAT ← 0,       -- number of surface elements
surface: REF ANY ← NIL,      -- surface definition using defining points
shadingProps: Atom.PropList ← NIL   -- shading status and parameters
];
Uses for ShapeInstance.fixedProps:
- $Closed, $PatchColors, $PatchColorsInFile, $PatchInfo, $PatchNormalsInFile, $PatchTransmittancesInFile, $VertexColorsInFile, $VertexNormalsInFile, $VertexTextureInFile, $VertexTransmittanceInFile
Uses for ShapeInstance.props:
- $ClippedPatches, $ClippedVertices, $Hidden, $LinesList,
Uses for ShapeInstance.shadingProps:
- $AuxiliaryVtxData, $PolygonInfoComputed, $Scale, $ShapeLerp, $TextureScale, $TxtrCoordParams, $TxtrCoordRange, $TxtrCoordType, $TxtrTranslation, $VtxInfoComputed
ShapeClass: TYPE ~ RECORD[
type: ATOM ← NIL,      -- eg. $ConvexPolygon, $Bezier, $Light, etc.
validate: ShapeProc ← NIL,    -- update vtces and shading after changes
display: ShapeProc ← NIL,    -- display whole shape (speed optimized?)
displayPatch: PatchProc ← NIL,  -- display patch (for priority display algorithms)
doBeforeFrame: LIST OF ShapeProc ← NIL -- to do before display (for animation, etc.)
];
ShadingClass: TYPE ~ RECORD[
type: ATOM ← NIL,      -- eg. $Default, $MappedAndSolidTexture
shadingType: ATOM ← NIL,   -- $Faceted or $Smooth, $Lines, or supplied ShapeProc
color: RGB ← [0.7, 0.7, 0.7],    -- whole object color, may be mixed with vtx color
shininess: REAL ← 0.0,     -- highlight power, typically 30.0-300.0, 0 means none
transmittance: REAL ← 0.0,     -- surface transmittance of object
patchShade: REF ShadingSequence ← NIL, -- shading per patch
texture: LIST OF REF ANY ← NIL,   -- TextureMap, Solid texture function, etc.
cnvrtVtx: VtxToRealSeqProc ← NIL,  -- converts vertex to sequence of reals
getColor: SpotProc ← NIL,     -- calculates shade at pixel
loadShapeAux: ShapeProc ← NIL,   -- loads extra shading info for shape
loadVtxAux: VertexInfoProc ← NIL,  -- loads extra info per vertex
lerpVtxAux: VertexInfoProc ← NIL,  -- interpolates extra info per vertex
shadeVtx: VertexInfoProc ← NIL   -- calculates shade from vertex info
];
    
ShapeSequence: TYPE ~ RECORD[
length: CARDINAL ← 0,
entry: SEQUENCE maxLength: CARDINAL OF REF ShapeInstance
];
ShapeProc: TYPE ~ PROC[context: REF Context, shape: REF ShapeInstance, data: REF ANY ← NIL]
      RETURNS[REF ShapeInstance];
Context Definition
Context: TYPE ~ RECORD [
class: REF ContextClass ← NIL,
stopMe: REF BOOLEAN ← NIL,  -- stop flag for bailing out (ref for inheritance)
imageReady: BOOLEAN ← FALSE,  -- flag for useable image in display
Scene description
frameNumber: NAT ← 0,      -- current frame for animation routines
shapes: REF ShapeSequence ← NIL,   -- current collection of shapes and lights
visibleShapes: REF ShapeSequence ← NIL, -- computed by SurfaceRender.ValidateContext
lightSources: REF ShapeSequence ← NIL,  -- computed by SurfaceRender.ValidateContext
environment: Atom.PropList ← NIL,   -- for reflection map, ambient light proc, etc.
View description
viewInValid: BOOLEAN ← TRUE,     -- true whenever view parameter updated
eyePoint: Triple ← [1.0, -5.0, 2.0],    -- defines point from which view is seen
ptOfInterest: Triple ← [0.,0.,0.],    -- defines center of image and focus
rollAngle: REAL ← 0.,       -- rotational angle about direction of view
upDirection: Triple ← [0.,0.,1.],    -- defines "heads-up" direction (redundant)
fieldOfView: REAL ← 40.,      -- horizontal angle included in field of view
window: REF Rectangle ← NIL,    -- window clips field of view in eyespace
hitherLimit: REAL ← 1.,       -- anything closer to eyepoint is clipped
yonLimit: REAL ← 1000.,      -- anything further from eyepoint is clipped
clippingPlanes: ARRAY SixSides OF Quad,  -- computed clip planes
eyeSpaceXfm: Xfm3D ← NIL,     -- world space to eyespace
eyeToNdc: ScaleAndAddXfm ← [1.,1.,1., 0.,0.,0.], -- eyespace to normalized display coords
ndcToPixels: ScaleAndAddXfm ← [1.,1.,1., 0.,0.,0.], -- to screen coords
Display description
viewer: ViewerClasses.Viewer,     -- viewer record if in Viewer ELSE NIL
terminal: Terminal.Virtual ← NIL,    -- virtual terminal for this context, if displayed
displayInValid: BOOLEAN ← TRUE,    -- true whenever display parameter updated
pixels: ImagerPixel.PixelMap ← NIL,   -- where the bits are
pixelAspectRatio: REAL ← 1.0,     -- physical width/height of displayed pixel
viewPort: REF Rectangle ← NIL,    -- viewport in floating pt. display coordinates
preferredViewPort: Rectangle ← [0.,0.,65536.,65536.],  -- maximum viewport size
extentCovered: Box ← [[0, 0], [0, 0]],    -- bounds area used (while building image)
preferredRenderMode: ATOM ← NIL,   -- $Pixels, $Imager (fancy vs. device independent)
displayProps: Atom.PropList ← NIL,  -- $Depth, $Alpha (Pixel posn),
             -- $FullDisplayMemory, $ViewerAdjusted
Rendering Style
autoRedraw: BOOLEAN ← FALSE,    -- quick image hint, redraw if viewer changes
delayClear: BOOLEAN ← FALSE,    -- delay clearing buffer when rendering
doVisibly: BOOLEAN ← TRUE,     -- build image on display
antiAliasing: BOOLEAN ← FALSE,    -- flag for antialiasing and alpha buffer
depthBuffering: BOOLEAN ← FALSE,   -- buffer for cheap hidden-surface removal
depthResolution: NAT ← 8192,      -- number of buckets for depth sorting
sortSequence: REF ← NIL,      -- shapes or surfaces sorted for display
props: Atom.PropList ← NIL  -- catchall
Global uses for context.props:  - $WDir - working directory
          - $Log  - log file for messages
          - $BackGround - background color or context (for images)
          - $DitherContext - for dithering RGB to pseudocolor
          - $OutputFile - output file for interpress or animation
          - $ImagerCtx - context for Imager calls, when no viewer
          - $SortToPriority - forces priority sort, poly intersections
];
ContextClass: TYPE ~ RECORD[
displayType: ATOM ← NIL,     -- { $PseudoColor, $Gray, $FullColor,
             $ImagerGray, $ImagerDithered, $ImagerFullClr,
              $Bitmap, $Interpress }
setUpDisplayType: ContextProc,   -- makes sure there are bits to write, sets up colors
validateDisplay: ContextProc,    -- makes sure viewPort changes, etc. take effect
render: ContextProc,          -- call this to display the scene
loadBackground: ContextProc,       -- clear to background
 2d drawing primitives use normalized display coordinates (-1.0 < x < 1.0, -.75 < y < .75)
draw2DLine: PROC[context: REF Context, p1, p2: Pair, color: Pixel], -- display a line
draw2DPolygon: PROC[context: REF Context, poly: REF PairSequence, color: Pixel],
draw2DRope: PROC[context: REF Context, rope: Rope.ROPE, position: Pair,
      color: Pixel ← [255,255,128,0,0], size: REAL ← 20, font: Rope.ROPE ← NIL],
displayPolygon: PatchProc,         -- 3 dimensional shading 
drawInViewer: PROC[ context: REF Context, procRec: REF ImagerProcRec ],
updateViewer: ContextProc
];
ContextProc: TYPE ~ PROC[ context: REF Context, data: REF ANY ← NIL ];
ImagerProc: TYPE ~ PROC[ context: REF Context, imagerCtx: Imager.Context,
        data: REF ANY ← NIL ];
ImagerProcRec: TYPE ~ RECORD[ proc: ImagerProc, data: REF ANY ← NIL ];
Utility Procedures
RectangleFromBox: PROC[ Box ] RETURNS[ Rectangle ];
BoxFromRectangle: PROC[ Rectangle ] RETURNS[ Box ];
IntersectRectangles: PROC[ Rectangle, Rectangle ] RETURNS[ Rectangle ];
Procedures for Registering and Loading Classes
RegisterDisplayType: PROC[ class: ContextClass, type: ATOM ];
Adds class to list of registered ContextClasses, containing display-specific procs, etc.
GetDisplayType: PROC[ type: ATOM ] RETURNS[ class: ContextClass ];
Retrieves registered class for use or modification
LoadDisplayType: PROC[ context: REF Context, type: ATOM ];
Sets proper color map and rendering procs
RegisterSurfaceType: PROC[ class: ShapeClass, type: ATOM ];
Adds class to list of registered ShapeClasses, containing surface-specific procs, etc.
GetSurfaceType: PROC[ type: ATOM ] RETURNS[ class: ShapeClass ];
Retrieves registered class for use or modification
LoadSurfaceType: PROC[ shape: REF ShapeInstance, type: ATOM ← $ConvexPolygon ];
Loads ShapeClass (patch expansion and rendering procs) and ShadingClass for surface type
RegisterShadingClass: PROC[ class: ShadingClass, type: ATOM ];
Adds class to list of registered ShadingClasses, for fancy texturing procs, etc.
GetShadingClass: PROC[ type: ATOM ] RETURNS[ class: ShadingClass ];
Retrieves registered class for use or modification
LoadShadingClass: PUBLIC PROC[ shape: REF ShapeInstance, type: ATOM ← $Default ];
Puts ShadingClass in shape record
Procedures for Standard Operations
Create: PROC[] RETURNS [REF Context];
Gets context
SetView: PUBLIC PROC[context: REF Context, eyePoint, ptOfInterest: Triple,
       fieldOfView: REAL ← 40.0,
       rollAngle: REAL ← 0.0, upDirection: Triple ← [ 0., 0., 1.],
       hitherLimit: REAL ← .01, yonLimit: REAL ← 1000.0];
SetPosition: PROC[ shape: REF ShapeInstance, concat: BOOLEAN ← FALSE ];
Makes matrix from position parameters and either replaces or concatenates to the existing matrix
CloseDisplay: PROC[context: REF Context];
Shuts down display gracefully, restores standard color map
END.