CS4451B Fall 2002: Assignment 3

Purpose
	To implement a simple, object-oriented, hierarchical retained mode graphics library of the sort discussed in class. A Conceptual Model for Object-oriented Graphics The conceptual model of our object-oriented retained-mode library is based on two simple and powerful concepts: graphical objects for building graphical scenes and properties for specifying the behavior of the graphical objects. The library uses the "damage-repair model": whenever a graphical object or property changes (is damaged), the image is repaired without programmer intervention. Graphical objects (GOs) represent all the logical entities in the graphical scene: geometry (e.g., lines, polygons, spheres, etc.), lights and cameras of various sorts, and groups of other GOs. One special type of group, the root GO, represents a viewport into which graphics are rendered. GOs can be grouped together in any valid directed acyclic graph (DAG). In particular, any subgraph rooted at a group GO can be linked into any number of other scene graphs as a child of some other group GO. Each property is a defined by some value that specifies how some attribute of the graphical scene changes over time. A property could either be a constant value, or a time-variant function that takes the current time and returns a value. Associated with each GO g is a partial mapping of properties to values determined by the properties that have been set on g. A property that has been set on g affects not only g but all the descendants of g that do not override the property. A root GO sets an initial default value for each named property. The Simplified JOOGL Model JOOGL simplifies the conceptual model somewhat. In particular, there are only a small set of GOs and properties in the system, and not all property values inherit down the scene graph. The few properties that do inherit were chosen either because inheritance is necessary (in the case of transformations), or because it was easy to implement (see below). Properties that do not inherit are hard coded into the appropraite nodes. Those that do inherit have actual objects to implement them. Furthermore, only the properties that inherit can be specified as time-variant functions (ie. most properties can only have simple, constant values). Finally, the set of properties and GOs, and the choice of which properties can be time-variant functions, where chosen so that JOOGL is sufficiently powerful to implement assignments #4 and #5 in a straightforward manner.
Task
	Write a Java library that provides a retained mode library on top of GL4Java. This is a simple library based on the concept of an object-oriented library that uses a DAG of group nodes to structure the scene, and has properties (possibly time-based) attached to the nodes to specify the behavior of the scene. The stripped down class files for the library are here. These class files implement some of the nitty-gritty methods that would be tedious and are tangential to the assignment. Pay very close attention to the comments and the structure of the code; some internal methods have been left in (although empty) to guide you. A collection of test programs using this library, and images of what the resulting graphics should look like, are here. Additional test programs may be posted to the class swiki.
Turn in
	Your submission should consist of a collection of java class files which implement the library. The TAs will evaluate it using the test programs provided, as well as other test programs that may not have been provided (which may test parts of the library not explicitely tested by the posted programs). Your source files should be commented with the usual comments. Your submission MUST be submitted using WebWork, as discussed in class. If you are unsure of how to submit using WebWork, talk to the TAs BEFORE THE ASSIGNMENT IS DUE. IMPORTANT: If the TA has to edit your files to compile your code, you will lose up to 25% of the grade you could have gotten.
Due date
	This program is due at 9am on Friday October 18th. This means it must be received by 8:59am EDT on Friday to not be considered late.
Additional Instructions
	The joogl class files have been documented here. Make sure you understand the library before you start implementing it. It has been carefully designed to be powerful enough to be interesting, while being fairly straightforward to implement. In particular: The stacks to store property values have been implemented for you, and are part of the jooglProperty class. Similarly, a DAG traversal framework has been implemented, based on the idea of a Visitor object. See jooglVisitor, and the various subclasses. There are five properties in the system that support "dynamic" values: each corresponds to a class that inherits from jooglProperty, and has a constant value that can be changed explicitely from within the user program. Each of these properties in turn has a subclass that can be used to specify a dynamic property that has a value specified as a function of time. These are the material or transformation attached to a node, the shading and drawing modes, and the pickable flag (which is only needed for one of the optional parts of the assignment). Only a few simple geometric nodes have been included in the library: spheres, cubes, teapots, and polygons. These are supported directly by GLUT and OpenGL. We have included a couple of properties that control how these are displayed. The "shade model" property determines if an object is smooth or flat shaded (see glShadeModel), and the "draw mode" object determines if an object is drawn as polygons, lines or points (see glPolygonMode). There a four kinds of lights, which are directly equivalent to the OpenGL lights. None of the properties of lights inherit down the DAG, but are stored directly in the light node and used when needed. There is a base camera node, and two kinds of cameras that inherit from it, a perspective camera and an orthographic camera. These correspond to the OpenGL projections you have been using, and we have talked about. Unlike OpenGL, joogl cameras always have an aspect ratio calculated for them by joogl that is equivalent to the aspect ratio of the viewport they are rendering in. There are two kinds of group nodes (the internal nodes of the DAG): a plain group, and a root node that also serves to associate a scene graph with a viewport in a window. There is a subclass of GLAnimCanvas, jooglCanvas, that must be used for any joogl graphic window. Its display method will be used to render the jooglRoot objects attached to it. You library should do the following things: The GLAnimCanvas should initialze itself in its preInit() and init() routines, as usual for a GL4Java application. The joogl global data should be contained in the base class and initialized the first time a joogl object is created. Read the GL4Java documentation to make sure you understand how the animation canvas (GLAnimCanvas) works, and in particular how to start and stop continuous redraw. You should only redraw continuously if there are dynamic properties linked into the scene graph; otherwise, only redraw when something changes. The display routine for each jooglCanvas does the multiple graph traversals for each jooglRoot attached to it: to deal with the properties and camera and lights, and to render the opaque and then transparent objects. Each viewport has a different colored background. You need to render a single polygon, without affecting the zbuffer, to set the background for the viewport after you clear the whole window. When any non-"property" attribute of any object is changed (ie. the attributes that do not have property objects, such as the intensity of a light or the radius of a sphere), you should redraw the scenes containing the affected object (however, you can cheat and make this redraw easy to do: see the HINT below). When a property is added or removed from a node you should also redraw the scene. You do NOT have to redraw the scene when you change a non-dynamic property value. While it would be nice if the scene was redrawn when a property value was changed, it turns out to be hard to do this efficiently, especially because the property objects (especially the Transform property) are convenient to use as intermediate values in dynamic properties and in the redraw process; if the scene was redrawn each time any of these where changed, this would cause problems. You should only use display lists for the "geometry" objects (sphere, cube, teapot, polygon), and you should only use them to contain the geometry (ie. the single command to create them). Do not store any materials, lights, etc., in display lists. HINT: A simple way to handle redrawing when a change occurs is to force all windows to redraw when anything changes (by issuing repaint() to each canvas). To handle the addition of a dynamic property to a graph, mark each root window as needing to be redrawn continuously when a dynamic property is added to any node. Any time a window is redrawn, it can check to see if there are any dynamic properties attached to the scene graph in any viewport for the window, and stop the continuous redraw for that window if there are no dynamic properties. For this assignment, these unnecessary redraw of each window is acceptable; in a real system, you would keep parent pointers and explicitely compute which graphs need to be redrawn, but we don't want to keep parent pointers here. (NOTE: this means that you must keep track of all jooglCanvas objects in a place that is accessible from all joogl objects so any joogl object can tell all canvases to repaint.) Additional Comments The implementation of this library is fairly complex, and should be done incrementally. We will post more detailed information about how this will be graded as the due date grows closer, but the majority of the grading will involve compiling your library and linking it with a number of test programs: each program will test progressively more complex parts of the library. The most basic test programs are in the collection above. Pay close attention to what you need to implement in order to have that test program work. In particular, you do not need to support dynamic properties, property inheritance (of material, drawmore, shademodel or transformations), or to allow the camera or light nodes to be transformed within the scene graph for the first test program. This is a good example of where to start:  support a simple hierarchy with properties attached to the leaf nodes. Additional test programs will require your library to support property inheritance, dynamic properties, embedding the camera and lights in the graph, and so on.
EXTRA CREDIT
	There is one extra credit for this assignment, and that is to handle picking. The class files have an object (jooglPickable) and a method (jooglCanvas->pickRoot()) needed to perform picking on the scene graph, which provide the information needed to do OpenGL picking in a window. You should implement these routines.