OFF: Our File Format for assignment 2

The new OFF is compatible with the OFF introduced in assignment 1. The additions include: This file documents the pure OFF commands only. There are some closely related useful Tcl commands which are not acceptable in a pure OFF file but are nonetheless very handy.

Drawing Commands

bgnpoly
begin a polygon definition
endpoly
end a polygon definition
bgnline
begin a polyline definition
endline
end a polyline definition
color r g b
set the current drawing color. r g b give the red, green, and blue components of the color respectively: <0.0 0.0 0.0> is black and <1.0 1.0 1.0> is white. Colors will most likely be distorted on an 8-bit display, and the more different colors are used the worse the distortion will be. Polyline colors may be specified per-vertex, while polygons will be filled with the color of the first vertex.
vertex x y z
Transform the point <x,y,z> by the current transformation and add it to the primitive being defined. If z is omitted it defaults to 0.0.

Display List Commands

Display lists are a useful way to approach the tradeoff between generality and efficiency in a graphics system. We have chosen to use Tcl as "glue" for putting graphics primitives together, an extremely general but inefficient mechanism. Display lists are a much less general but much more efficient kind of glue: they store a sequence of pure OFF commands in a quickly executable format. A display list may be created by putting a bgndlist / enddlist pair around a sequence of Tcl commands. Any drawing done within the display list definition is captured in the dlist, and can be invoked later with calldlist. Non-drawing commands (i.e. impure OFF) will not be captured in the display list: if you put some code which references a variable into a dlist, the value of that variable is effectively baked in to the dlist: changing the variable later will have no effect on the dlist. Thus, dlists are useful for static pieces of geometry: you might use one to represent a forearm, but if you plan to change the elbow angle at some point you shouldn't put the whole arm into a dlist.

Recursive use of display lists should work the "right" way: if you do a bgndlist within another display list it will create a new display list and put a calldlist command into the old one.

bgndlist id
Begin a display list with name id.
enddlist id
end the current display list. id is optional: if present it will be checked against the id of the most recently begun dlist.
calldlist id
invoke the dlist id
destroydlist id
free up the dlist named id

Transformation Commands

The OFF viewer maintains a matrix stack as discussed in class. The following commands manipulate this stack.
pushmatrix
Push the matrix stack.
popmatrix
Restore the matrix stack to its state at the time of the last pushmatrix.
translate tx ty tz
Translate subsequent graphics primitives by <tx,ty,tz>. If tz is omitted it defaults to 0.0.
skale sx sy sz
Scale subsequent graphics primitives by sx in the x direction, sy in the y direction, sz in the z direction. If sz is omitted it defaults to 1.0.
rotate axischar angle
Rotate subsequent graphics primitives counterclockwise by angle radians about the given axis, which must be "x", "y", or "z". If the axis is omitted it defaults to "z".
multmatrix matrix
Compose the matrix argument with the current transformation matrix. By giving the right argument to this command, one can achieve the same result as rotate, translate, scale, or indeed any combination of the three.
loadmatrix matrix
Set the current transformation matrix to matrix. Generally this command should not be used more than once per frame.

Display Commands

newframe
start with a blank drawing area again
showframe
show the picture just constructed

Miscellaneous

off maxfps fps
sets the maximum frame rate to fps frames per second
nix@cs.cmu.edu