This document gives a brief introduction to the special features of Jabka's version of the Scheme programming language that provide support needed for object-oriented graphics. Central to providing this support is the addition to Scheme the new atom type object. This document describes how objects are created in Jabka and outlines the Jabka ojbect heirarchy. Other Jabka Scheme extensions meant specifically to support graphics are described in a separate document entitled the Jabka Graphics Programming Reference.

Overview of Objects in Jabka

• classes and instances
• prototypes
• class prototypes

The Jabka Object Class Hierarchy

Creating, Naming, and Destroying Objects

Using Objects

Class and Method Descriptions

Overview of Objects in Jabka

Jabka is an object-oriented graphics system. This means that the various components of the system can be thought of as objects that you can create and destroy on command, and to which you can send commands, known as messages, asking them to perform certain actions. Each object keeps track of certain information about itself, and knows about a collection of associated procedures or methods to use to operate on this information. For example, you might want to create a camera, tell it how to position itself and adjust its zoom lens, and then finally to take a picture. The camera is the object, and you would send it messages like pan and raise to position it, zoom to adjust the lens, and finally shoot to take the picture.

classes and instances

Objects are of different types, and the type of an object is called its class. We say that a particular object is an instance of that class. Object classes are hierarchically organized, with the top level in the hierarchy providing overall structure, and lower level objects providing specialization. For example, in Jabka there is a class Device, which provides the basic structure for outputting a graphic image to an external medium. Device has several subclasses, File, Framebuffer, Bitmap and Pixmap which provide further specializations that are needed to handle output to an external disc file, to a hardware framebuffer, or to a monochrome or color window on the screen. File, in turn, has subclasses GIFFile, JabkaFile, PictureFile, and PPMFile to handle output to files in various image file formats. We say that a JabkaFile object is a kind of File object, which is in turn a kind of Device. Or, we can say that Device is a superclass of File, and File is a superclass of JabkaFile. A subclass shares all of the data-structures and methods of its superclass, but may add data structures and methods of its own, or may provide modifications or extensions to the methods of its superclass.

prototypes

Beyond class heirarchy, there is the notion in Jabka of an object's prototype. When an object is created in Jabka, it is actually formed as an image of a prototype object. The object initially borrows all of its attributes from its prototype. An object can be specialized from its prototype by sending it a message that modifys or sets one of its attributes to be different from that of the prototype. For example, one of the standard predefined material objects in Jabka is called plastic, that when rendered looks like white plastic. If a new object is created with plastic as its prototype, it will also render as white plastic. However, if a message is sent to the new object to set its color to a lemon yellow, it will then render as lemon yellow plastic. In other words, it still keeps the attributes of the prototype that make it look like plastic, but now takes on its own specialized color. However, prototyping in Jabka is even more powerful than the kind of "cloning" mechanism just described.

All of an object's attributes that have not been explicitly set continue to be derived from the prototype. What this means is that each object derived from a prototype that has not explicitly modified a certain attribute will dynamically take on any change to that attribute when it is made to the prototype. For example, suppose that you have made six different materials, all with plastic as their prototype, but all specialized with their own color. And, suppose that many of the objects in a scene have been made from these six materials. Now, you might want to experiment with changing the shininess of all of your plastic objects. Since all of the plastics share plastic as a prototype, it is a simple matter to send plastic a message to change its specularity (shininess), and this change will automatically affect all six of the materials sharing plastic as a prototype. On the other hand, changing the color of the prototype plastic will not affect the color of the derived materials, since each of them has been given its own specific color and no longer derives its color from the prototype.

class prototypes

The notions of class and prototype come together in the following way in Jabka. There is a fixed class heirarchy, built into Jabka, that defines the base set of objects from which prototypes can be formed. When Jabka is started up, a prototype object is automatically created corresponding to each class in the object heirarchy. You could call this base set of objects the class prototypes. Further specialized objects are automatically created by prototyping them from this base set. Finally, the user is free to create new objects using any existing object as a prototype.

The Jabka Object Class Hierarchy

The complete object hierarchy in Jabka is outlined below. Subclasses are indented below their superclasses. Class prototype objects have the same name as the class. Capitalization is as in the original C++ code which Jabka is written in. The scheme interface ignores case, and the usual convention is to use all lower case for names.

Glob Global object -- superclass of all Jabka graphics objects
  Device Device -- system dependent device for storing an image
    BitmapDev Bitmap -- monochrome on-board image frame store
    File File -- for writing an image to a disk file
      GIFFile GIF File -- 8-bit GIF formated file
      JabkaFile Jabka File -- Jabka's 24 bit raster format
      PictureFile Picture File -- Jabka's picture format
      PPMFile PPM File -- Portable Pixmap formated file
    FrameBuffer Framebuffer -- off-board RAM storage for an image
    PixmapDev Color Pixmap -- color on-board image frame store
  Filter Image Filter Operator -- defines a transformation of an image
    BoxFilter Box Shaped Filter -- Box Shaped Convolution Filter
    BrushFilter Brush Filter -- Brush Texturing Filter
  Image Image -- system independent off-screen storage for an image
    Picture Picture -- image is collection of 2D objects (draw mode)
    Raster Raster -- image is a full color raster (paint mode)
  Material Material Description -- describes surface properties of object
  ModelingObj Modeling Object -- element of 3D model
    Camera Camera -- virtural camera Light Light -- light source
    Part Part -- internal node in model geometry hierarchy
    Primitive Primitive -- leaf in model geometry hierarchy
      Polyline Polyline -- connected line segments in 3 space
      Surface Surface -- surface in 3 space
        BezPatch Bezier Surface -- surface formed by 4 cubic Bezier curves
        Polysurface Polygonal Surface -- surface formed from polygons
      Solid Solid -- 3 dimensional solid
        Quadric Quadric -- 3 dimensional quadric solid
        Superquadric Superquadric -- 3 dimensional superquadric solid
  Nametable Name Table -- hashed symbol table for object system
  Pane Window Pane -- framework for a screen window
    GWindow Graphic Output Window -- basic color graphics window
  Reader File Reader -- for reading an image from a disk file
    GIFReader GIF Reader -- reads 8-bit GIF format image file
    JabkaReader Jabka Reader -- reads Jabka raster format image file
    PictureReader Picture Reader -- reads Jabka picture format image file
    PPMReader PPM Reader -- reads Portable Pixmap format image file
  Renderer Renderer -- basic framework for all renderers
    BSPRenderer Binary Space-Partitioning-Tree Renderer
    RayTracer Ray Tracing Renderer
    Scanline Scanline Renderer
    Wireframe Wireframe Renderer -- usually used as previewer
  Shader Shader -- given a point on surface determines color (shade)
  TextureMap Texture Map -- texture maps for use in defining materials
    ColorMap Color Map -- texture geometric shapes and color gradients

Creating, Naming, and Destroying Objects

• (object name prototype [message ...]) The first argument must be a symbol, and the second the name of a currently existing object that will be used as the new object's prototype. One or more optional additional arguments may be provided -- these arguments must all be valid messages that may be sent to an object of the class of the prototype. Creates and returns a new named object with the given name and derived from the given prototype. If any optional messages are present, they are sent, in turn, to the object. The new object initially derives all of its settings from the prototype, except for settings that are changed by the messages. example: (object bulb light) ==> #<OBJECT(bulb light)> an object named bulb, prototyped from the "class prototype" light.
  
• (destroy-obj object) The argument must be an object. Destroys the object. Returns #t. After this procedure is called, the name of the object becomes simply an unbound symbol. It is rarely necessary for the user to use the destroy-obj procedure, because Scheme's garbage-collection will automatically destroy any object that is no longer being used. (destroy-obj bulb) ==> #t the object named bulb is destroyed.
  
• (create-obj prototype) The prototype argument must be the name of a currently existing object that will be used as the new object's prototype. Creates and returns a new unnamed object derived from the given prototype. The new object initially derives all of its settings from the prototype. (create-obj light) ==> #<OBJECT(#002E74D4 light)> an unnamed object prototyped from the "class object" light. Since the object has no name, it is assigned a unique identifier for internal use by the system (#002E74D4 in this example).

Using Objects

Once an object is created, you give it commands by sending it messages. The methods that are understood by each class are described below. Messages are sent to an object using a syntax that looks identical to a function call in Scheme: (obj message ...) where obj must be a Jabka object, and as many messages as are desired may be provided. Each of the messages has the format (method argument ...) where method must be a valid method name for the class of the object obj, and the correct number and type of arguments for that method must be provided. Messages are sent to the object, and processed by the object in the order of their occurance in the call to the object. The result of the application of the final method in the sequence is returned. For example, if a named light has been created using the command (object bulb light), the command (bulb (setcolor yellow) (gettype)) will first set the color of the light to yellow, and then return its type (either lightbulb or striplight).

Class and Method Descriptions

The following lists the classes and methods that the user will most likely need in constructing 3D models and rendering images in Jabka, when using the Scheme interface. Remember that each subclass inherits the methods of all of its superclasses, so in the following listing only the methods unique to a subclass appear. The notation x::y used below means that x is a subclass of y, or equivalently y is the superclass of x.

Glob Global object -- superclass of all graphics system objects

• (Describe) Prints a description of the object to standard output. Returns #t.
  
• (GetClass) Returns a string giving the name of the class of this object
  
• (Methods) Returns a list of strings, containing the names of all methods understood by the object.
  
• (GetName) Returns a string giving the name the object was given when it was created.
  
• (GetPrototype) Returns the object that is the prototype of this object.

Device::Glob Device -- system dependent device for storing an image

• (GetDeviceDepth) Returns an integer number of bits per pixel stored by this device.
  
• (SetGamma gamma) gamma is a real number to be used as the gamma value for gamma correction. Returns #t.
  
• (GetGamma) Returns a real number giving the gamma value currently being used for gamma correction.
  
• (GammaCorrectOn) Turns gamma correction on for this device. Returns #t.
  
• (GammaCorrectOff) Turns gamma correction off for this device. Returns #t.

BitmapDev::Device Bitmap -- one bit per pixel on-board monochrome image frame store

File::Device File -- for writing an image to a disk file

• (SetFileName name) name is a string giving the file name to be used when opening the file. Returns #t.
  
• (GetFileName) Returns a string giving the name of the file.

GIFFile::File GIF File -- 8-bit GIF formated file

JabkaFile::File Jabka File -- Jabka's 24 bit raster format

PictureFile::File Picture File -- Jabka's picture format

PPMFile::File PPM File -- Portable Pixmap formated file

FrameBuffer::Device Framebuffer -- off-board RAM storage for an image

PixmapDev::Device Color Pixmap -- variable bits per pixel on-board image frame store

Filter::Glob Image Filter Operator -- defines a transformation of an image

BoxFilter::Filter Box Shaped Filter -- Box Shaped Convolution Filter

• (SetNandDContribution N D) N and D are real numbers to be used to set the 4-connected neighbor and diagonal weights of a 3x3 box convolution filter. The central weight of the filter will be set to [1.0 - 4(N + D)]. Returns #t.
  
• (GetNandDContribution) Returns a two element list giving the 4-connected neighbor and diagonal components currently being used for the box filter.

BrushFilter::Filter Brush Filter -- Brush Texturing Filter

• (SetStrokeSize width height) width and height are integer numbers to be used to set the horizontal width and vertical height of a brush texturing element. Returns #t.
  
• (GetStrokeSize) Returns a two element list giving the width and height currently being used for the brush texturing element.

Image::Glob Image -- system independent off-screen storage for an image

• (SetImageSize width height) width and height are positive integers to be used to set the width and height of the image. Returns #t.
  
• (GetImageSize) Returns a list containing two integers giving the current width and height of the image.
  
• (GetImageTransform) Returns a transform that can be used to scale points in normalized device coordinates [(-1, 1) x (-1, 1)] to the discrete raster of the image.
  
• (OpenImage) Prepares the image to accept drawing commands. Returns #t.
  
• (CloseImage) Signals that no further drawing will be done to the image, and sends the image to its associated Device. Returns #t.
  
• (EraseImage) Image must be open. Fills the image with black. Returns #t.
  
• (FillImage color) Image must be open. Fills the image with the RGB color color. Returns #t.
  
• (AcceptPixel x y color) Image must be open. Sets the pixel at raster location (x, y) to the RGB color color. Returns #t.
  
• (AcceptRun x y n color) Image must be open. Sets the run of n pixels starting at raster location (x, y) to the RGB color color. Returns #t.
  
• (SetDevice device) device specifies the Device object to which the image will be sent upon a call to SendImageToDevice. Returns #t.
  
• (GetDevice) Returns the Device object to which the image will be sent.
  
• (SendImageToDevice) Sends the image to its associated Device. Returns #t.
  
• (SetSaveFile fileobj) Returns #t. Assigns the File object fileobj to handle a save request. The class of fileobj will determine what file format is used.
  
• (GetSaveFile) Returns the File object currently assigned to handle a save request.
  
• (Save filename) Saves the image to a file with name given by the string filename. Returns #t.
  
• (ResetFilterList) Emptys the list of filters to be applied to this image when filtering it into another image. Returns #t.
  
• (AddFilter filter) Inserts the Filter object filter into a list to be applied to this image when filtering it into another image. Returns #t.
  
• (FilterInto image) Filters the image using the image's list of filters, placing the filtered result in the Image given by image . Returns #t.

Picture::Image Picture -- image is collection of 2D objects (draw mode)

• (OutlinePolygon poly color) Draws the outline of the polygon given by poly in the RGB color color. poly is a list of triples giving the real 3D coordinates of the vertices of the polygon. The z coordinates are ignored in drawing. Returns #t.
  
• (FillPolygon poly color) Fills the the polygon given by poly with the RGB color color. poly is a list of triples giving the real 3D coordinates of the vertices of the polygon. The z coordinates are ignored in drawing. Returns #t.

Raster::Image Raster -- image is a full color raster (paint mode)

Material::Glob Material Description -- describes surface of geometric object

• (SetType type) type should be one of the predefined types: plaster-mat, plastic-mat, glass-mat, metallic, wood-mat, marble-mat, or water-mat. Sets the type of the material to type, which specifies surface reflectance and transmissive properties approriate to the given type. This is a convenience function only. The user is free to explicitly set the various material properties to get any desired reflectance and transmissive properties. In practice, the user will usually not use SetType, but will instead use prototyping to create a Material of the desired type. Returns #t.
  
• (GetType) Returns a string giving the name of the material's type.
  
• (ListTypes) Prints a list of valid material types to the standard output. Returns #t.
  
• (SetColor color) Sets the material's diffuse color to the RGB color color. Returns #t.
  
• (GetColor) Returns the material's diffuse color as an RGB color.
  
• (SetSpecularSpectrum spectrum) spectrum is a list of RGB colors sampling the viewing angles from 0 to 90 degrees from the surface normal. They give the RGB components of the specular reflection of white light from the surface. Returns #t.
  
• (SetSpecularColor color) Returns #t. Sets the material's specular color to the RGB color color.
  
• (GetSpecularColor) Returns the material's specular color as an RGB color.
  
• (SetSpecularity specularity exponent) Returns #t. Sets the strength of the specular component of the material's reflectivity to specularity, which must be a number between 0 and 1. exponent is the specular exponent.
  
• (GetSpecularity) Returns a list containing the material's specularity and specular exponent as set by SetSpecularity.
  
• (SetTransmissiveColor color) Returns #t. Sets the material's transmission color to the RGB color color.
  
• (GetTransmissiveColor) Returns the material's transmission color as an RGB color.
  
• (SetTransparency transparency exponent rindex) Sets the strength of the transmissive component of the material's reflectivity to transparency, which must be a number between 0 and 1. exponent is the transmissive exponent. rindex is the material's index of refraction. Returns #t.
  
• (GetTransparency) Returns a list containing the material's transmissivity and transmissive exponent and index of refraction as set by SetSpecularity.
  
• (SetBumpMap map) Sets the bump map for the material to the bump map map. Returns #t.
  
• (GetBumpMap) Returns the material's bump map.
  
• (SetColorMap map) Sets the color map for the material to the color map map. Returns #t.
  
• (GetColorMap) Returns the material's color map.

ModelingObj::Glob Modeling Object -- element of 3D model

• (translate dx dy dz) Concatenates a translation of (dx, dy, dz) onto the modeling object's current transform. Returns #t.
  
• (scale sx sy sz) Concatenates a scale of (sx, sy, sz) onto the modeling object's current transform. Returns #t.
  
• (rotate dx dy dz theta) Concatenates a rotation of theta degrees about the arbitrary axis [dx, dy, dz] onto the modeling object's current transform. Returns #t.
  
• (x-rot angle) Concatenates a rotation about the x-axis of angle degrees onto the modeling object's current transform. Returns #t.
  
• (y-rot angle) Concatenates a rotation about the y-axis of angle degrees onto the modeling object's current transform. Returns #t.
  
• (z-rot angle) Concatenates a rotation about the z-axis of angle degrees onto the modeling object's current transform. Returns #t.
  
• (x-shear yx zx) Concatenates a shear in the x direction onto the modeling object's current transform. Returns #t.
  
• (y-shear xy zy) Concatenates a shear in the y direction onto the modeling object's current transform. Returns #t.
  
• (z-shear xz yz) Concatenates a shear in the z direction onto the modeling object's current transform. Returns #t.
  
• (concatenate xform) Concatenates the arbitrary transform xform onto the modeling object's current transform. Returns #t.
  
• (identity) Sets the modeling object's current transform to the identity transform. Returns #t.
  
• (SetTransform xform) Sets the modeling object's current transform to the arbitrary transform xform.. Returns #t.
  
• (GetTransform) Returns the modeling object's current transform.
  
• (IsIdent) Returns #t if this is the identity transform, #f otherwise.
  
• (poly-surf-approx) Returns a newly created Polysurface object that approximates the modeling object.
  
• (SetVisibility vis) vis is the keyword visible to turn visibility on, or invisible to turn it off. If visibility is off, the object will not appear when previewed or rendered. Returns #t.
  
• (GetVisibility) Returns the string "visible" if visibility is on, "invisible" if it is off.
  
• (SetMaterial mat) Sets the material of the modeling object to the Material object mat. Returns #t.
  
• (GetMaterial) Returns the Material object describing the material of the modeling object.

Camera::ModelingObj Camera -- virtural camera

• (SetPreviewer prev) Sets the renderer to be used for previewing through the camera to the renderer object prev. Returns #t if successful, #f if unsuccessful.
  
• (GetPreviewer) Returns the renderer object being used for previewing through the camera.
  
• (SetRenderer rend) Sets the renderer to be used for shooting a fully rendered image through the camera to rend. Returns #t if successful, #f if unsuccessful.
  
• (GetRenderer) Returns the renderer object being used for shooting fully rendered images through the camera.
  
• (SetRefRoot name) name is a string specifying the name of the part object that is the root of the hierarchy describing the model that is to be rendered through the camera. Returns #t if successful, #f if unsuccessful.
  
• (GetRefRoot) Returns a string giving the name of the part object that is the root of the hierarchy describing the model that is to be rendered through the camera.
  
• (Preview) Causes the camera to produce a preview rendering. Returns #t if successful, #f if unsuccessful.
  
• (RePreview) Causes the camera to repreview. For some renderers this is more efficient than a preview, if a preview has already been done and no changes have been made to the model in the meantime. RePreview will produce erroneous results if a Preview has not been previously done, or changes have been made to the model since the last call to Preview. Returns #t if successful, #f if unsuccessful.
  
• (Shoot) Causes the camera to produce a rendered image. Returns #t if successful, #f if unsuccessful.
  
• (ReShoot) Causes the camera to reshoot a fully rendered image. For some renderers this is more efficient than a shoot, if a Shoot has already been done and no changes have been made to the model in the meantime. ReShoot will produce erroneous results if a Shoot has not been previously done, or changes have been made to the model since the last call to Shoot. Returns #t if successful, #f if unsuccessful.
  
• (SetRotationMode newmode [coi]) newmode must be either the keyword free or fixed, determining the rotation mode of the camera. The optional coi paremeter specifies a point in 3D space that will be used as the camera's center-of-interest. If the coi parameter is not specified, its old value will be retained (the origin, by default). In free mode, the camera's direction vector can be rotated using the tilt and roll methods, and its position can be changed using the DeltaX, DeltaY, and DeltaZ methods. In fixed mode, the camera is always directed at the camera's center-of-interest, and its position and direction can be changed using the Raise, Pan, and Approach methods. Note that the Roll method can be used in either camera mode. Returns #t.
  
• (GetRotationMode) Returns a symbol indicating the rotation mode, either free or fixed.
  
• (SetCamera cop dir up) Sets the camera's center-of-projection to the position cop, the camera's direction of projection to the vector dir, and the camera's roll angle to up degrees from the vertical. Also places the camera in free rotation mode. Returns #t.
  
• (GetCamera) Returns a list containing the camera's position and direction parameters as specified by SetCamera.
  
• (SetCameraAlt cop coi up) Sets the camera's center-of-projection to the position cop, the camera's center-of-interest to the position coi, and the camera's roll angle to up degrees from the vertical. Also places the camera in fixed rotation mode. Returns #t.
• (GetCameraAlt) Returns a list containing the camera's position and direction parameters as specified by SetCameraAlt.
  
• (SetScreen width height hither yon) Sets the screen and view-volume for the camera. Screen width and height are given by the positive real numbers width and height. The distance of the hither and yon planes from the center-of-projection are given by hither and yon. Returns #t.
  
• (GetScreen) Returns a list giving the screen and view-volume settings for the camera, as specified by SetScreen.
  
• (Zoom percent) Simulates the effect of a zoom lens by reducing the camera's virtual screen size (width and height) by percent percent. If percent is positive the virtual screen size shrinks causing the image to expand, if negative the virtual screen grows causing the image to shrink. percent should be a number between -99 and 99. Returns #t .
  
• (tilt angle) If the camera is in free rotation mode, rotates the camera angle degrees about its own x-axis. Center of rotation is taken to be the camera's center-of-projection. Returns #t if the camera is in free mode, #f if fixed mode.
  
• (roll angle) If the camera is in free rotation mode, rotates the camera angle degrees about its own z-axis. Center of rotation is taken to be the camera's center-of-projection. Returns #t.
  
• (yaw angle) If the camera is in free rotation mode, rotates the camera angle degrees about its own y-axis. Center of rotation is taken to be the camera's center-of-projection. Returns #t if the camera is in free mode, #f if fixed mode.
  
• (DeltaX dx) If the camera is in free rotation mode, translates the camera the distance dx in the x direction of the camera's own coordinate system. Returns #t if the camera is in free mode, #f if fixed mode.
  
• (DeltaY dy) If the camera is in free rotation mode, translates the camera the distance dy in the y direction of the camera's own coordinate system. Returns #t if the camera is in free mode, #f if fixed mode.
  
• (DeltaZ dz) If the camera is in free rotation mode, translates the camera the distance dz in the z direction of the camera's own coordinate system. Returns #t if the camera is in free mode, #f if fixed mode.
  
• (Raise angle) If the camera is in fixed rotation mode, rotates the camera's center-of- projection about its center-of-interest angle degrees in the direction of the camera's y-axis. The rotation is done so that the camera's direction-of-projection is left pointing at the center-of-interest. Returns #t if the camera is in fixed mode, #f if free mode.
  
• (Pan angle) If the camera is in fixed rotation mode, rotates the camera's center-of- projection about its center-of-interest angle degrees in the direction of the camera's x-axis. The rotation is done so that the camera's direction-of-projection is left pointing at the center-of-interest. Returns #t if the camera is in fixed mode, #f if free mode.
  
• (Approach percent) If the camera is in fixed rotation mode, translates the camera's center-of- projection percent percent of the current distance between the center-of-projection and the center-of-interest. If percent is positive the translation is towards the center-of-interest, if negative the translation is away from the center-of-interest. percent should be a number between -99 and 99. Returns #t if the camera is in fixed mode, #f if free mode.
  
• (Restore) Restores the camera's position and direction to those specified by the most recent invocation of SetCamera or SetCameraAlt. Returns #t.

Light::ModelingObj Light -- light source

• (SetType type) type is either the keyword light-bulb, specifying a point light source, or strip-light, specifying a rectangular light. This is currently only of significance to the ray-tracer. Returns #t.
  
• (GetType) Returns the type of the light as a string, either "light-bulb" or "strip-light".
  
• (SetLightCoords pos dir angle) Returns #t. Positions, and aims the light. pos is a vector giving the position of the light. dir is a vector giving the direction of the light. angle is the apex angle in degrees of a conical shade over the cone (360 degrees makes a point light source).
  
• (GetLightCoords) Returns a list containing the position, direction, and angle of the light source as specified by SetLightCoords.
  
• (SetDimensions radius) This form of the call is applicable only to lights of type "light-bulb". radius is a real number giving the radius of the light itself. This is currently only of significance to the ray-tracer.
  
• (SetDimensions width height) This form of the call is applicable only to lights of type "strip-light". width and height are integer numbers giving the dimensions of the rectangular light strip. This is currently only of significance to the ray-tracer.
  
• (GetDimensions) If the light is of type "light-bulb" returns the radius of the light as a real number. If it is of type "strip-light" returns a two element list containing the width and height of the strip as real numbers.
  
• (SetIntensity intensity focus) intensity is a positive real number that determines the brightness of the light, where 1.0 is normal brightness. The color coordinates of the light are multiplied by intensity before being used in shading calculations. focus is a positive real number that will be used to determine how quickly the brightness of a spotlight falls-off from its center. focus is used as an exponent on the cosine of the angle between the light's direction vector and the vector between the light's center and a point on the surface. This result is multiplied by the light intensity. Thus focus of 0 will yield no fall-off, 1 will yield a smooth gradual fall-off, and large values like 30 will yield a sharply focused spot. Returns #t.
  
• (GetIntensity) Returns the intensity and focus of the light as a list of two real numbers.
  
• (SetColor color) color is the RGB color of the light. Returns #t.
  
• (GetColor) Returns the RGB color of the light.

Part::ModelingObj Part -- node in geometric model graph

• (AddChild obj [xform [material]]) The ModelingObj obj is attached to the part as a child using the transform xform, or the identity transform if xform is not supplied. The child's material is set to material, if it is supplied. The name of the link connecting the Part to the new child will be the same as the name of the child object, but with an appended "+" followed by an instance number. This method is used to do an additive CSG operation. Returns #t.
  
• (SubtractChild obj [xform [material]]) The ModelingObj obj is attached to the part as a child using the transform xform, or the identity transform if xform is not supplied. The child's material is set to material, if it is supplied. The name of the link connecting the Part to the new child will be the name of the child object, but with an appended "-" followed by an instance number. This method is used to do a subtractive CSG operation.
  
• (IntersectChild obj [xform [material]]) The ModelingObj obj is attached to the part as a child using the transform xform, or the identity transform if xform is not supplied. The child's material is set to material, if it is supplied. The name of the link connecting the Part to the new child will be the name of the child object, but with an appended "*" followed by an instance number. This method is used to do an intersection CSG operation.
  
• (Remove link-name) Removes the named child from the part. link-name is the name of the link connecting the Part to the child to be removed. Returns #t if successful, #f if unsuccessful.
  
• (GetNamedChild link-name) Returns the ModelingObj object connected to this Part via the named link. Returns #f if unsuccessful.
  
• (GetFirstChild) Returns the ModelingObj object representing the first child attached to this Part.
  
• (GetNextChild) Returns the ModelingObj object representing the next consecutive child of this Part, i.e. each time GetNextChild is called it returns the next child in sequence. GetNextChild returns #f when it reaches the end of the children. GetNextChild is initialized by GetFirstChild.

Primitive::ModelingObj Primitive -- leaf in model geometry hierarchy

Polyline::Primitive Polyline -- connected line segments in 3 space

• (InsertPoly poly) Inserts the outline of the polygon described by the vertex list poly into the Polyline. Returns #t.
  
• (InsertPolyline pline) Inserts the Polyline object pline into the Polyline. Returns #t.
  
• (TransformVerts xform) Transforms each vertex in the Polyline by the transform xform. Returns #t.

Surface::Primitive Surface -- surface in 3 space

BezPatch::Surface Bezier Patch -- patch surface formed by 4 cubic Bezier curves

• (SetPatch ctrl-points) Sets the control points of the Bezier patch to the 16 vectors contained in the list ctrl-points. Returns #t.
  
• (GetPatch) Returns the control points of the Bezier patch as a 16 element list of vectors.
  
• (SetApproxLevel level) Sets the approximation level of the Bezier patch to the integer number level. When approximated, the patch will be subdivided into (3x2^level x 3x2^level) polygons. Returns #t.
  
• (GetApproxLevel) Returns an integer number giving the current approximation level of the Bezier surface.

Polysurface::Surface Polygonal Surface -- surface formed from polygons

• (GetNumPolygons) Returns the number of polygons in the Polysurface.
  
• (InsertPoly poly) Inserts the polygon described by the vertex list poly into the polygonal surface. Returns #t.
  
• (InsertSmoothPoly poly normals) Inserts the smooth shaded polygon described by the vertex list poly and the surface normal list normals into the polygonal surface. Returns #t.
  
• (InsertUVPoly poly uvcoords) Inserts the polygon described by the vertex list poly and the UV-parametric coordinate list uvcoords into the polygonal surface. Returns #t.
  
• (InsertSmoothUVPoly poly normals uvcoords) Inserts the smooth shaded polygon described by the vertex list poly, the surface normal list normals and the UV-parametric coordinate list uvcoords into the polygonal surface. Returns #t.
  
• (InsertPolysurface psurf) Inserts the polygonal surface given by the polygonal surface object psurf into the polygonal surface. Returns #t.
  
• (Rescale sx sy sz) Applys the scale factors sx, sy, and sz to the vertices in the Polysurface. Returns #t.
  
• (SetDimensions maxx maxy maxz) Rescales the vertices in the Polysurface so that its x-extent is maxx, its y-extent is maxy, and its z-extent is maxz. Returns #t.
  
• (TransformVertsAndNorms xform) Transforms the vertices and the surface normals of the polygonal surface by the transform given by xform. Returns #t.
  
• (FirstPolygon) Returns the first polygon stored in the internal representation of the polysurface.
  
• (NextPolygon) Returns the next consecutive polygon stored in the internal representation of the polygon. Returns #f if there are no more polygons. This method is initialized by a call to FirstPolygon.

Solid::Primitive Solid -- 3 dimensional solid

• (SetTopMaterial material) Sets the top material of the solid to the Material object material. This material type is used for solids, like cylinders, that must be capped. This material, if it is specified, is used instead of the Solid's normal material color for the color of the top cap.
  
• (GetTopMaterial material) Returns the top material of the solid.
  
• (SetBottomMaterial material) Sets the bottom material of the solid to the Material object material. This material type is used for solids, like cylinders, that must be capped. This material, if it is specified, is used instead of the Solid's normal material color for the color of the bottom cap.
  
• (GetBottomMaterial) Returns the bottom material of the solid.

Quadric::Solid Quadric -- 3 dimensional quadric solid

• (SetType type) type may be one of the keywords ellipsoid, parabolic, conic, cylindric, frustric indicating the type of the quadric. Returns #t.
  
• (GetType) Returns the type of the quadric as a string.
  
• (SetShading shading) shading may be one of the keywords flat or smooth, indicating that either facted or smooth shading should be used in rendering the quadric. Returns #t.
  
• (GetShading) Returns the shading type for the quadric as a string.
  
• (SetDimensions sx sy sz [sh]) sx, sy, and sz are positive real numbers determining how the quadric should be scaled in the x, y, and z directions. sh should only be specified for a frustrum, since it specifies the height of the cone of the frustrum from its base to its apex before it is truncated at the height given by sy. Returns #t.
  
• (GetDimensions) Returns a list containing the scaling factors for the quadric.
  
• (SetSampleInc increment) increment is an integer number that determines the sampling resolution of the quadric for use in approximating the quadric by either a polygonal surface or polyline. A setting of 10 gives a reasonably smooth object. Higher settings increase smoothness, and lower settings decrease it. Returns #t.
  
• (GetSampleInc) Returns the quadric's sampling resolution.
  
• (SetUVCoords uvlist) uvlist is a list of UV coordinate pairs to be used for texture mapping. The first 4 pairs in uvlist are applied to the main body of the quadric, and determine its U & V extents. Paraboloids and cones must have 2 more pairs, that determine the U & V coordinate extents of the bottom end cap. Cylinders and frustrums must have 4 more pairs, that determine the U & V coordinate extents of the top and bottom end caps. Returns #t.
  
• (GetUVCoords) Returns the UV coordinates for the quadric as a list of pairs of real numbers.

Superquadric::Solid Superquadric -- 3 dimensional superquadric solid note: refer to Barr, Superquadrics and angle-preserving transforms, IEEE Computer Graphics and Applications, Jan. 1981 for a complete description of superquadric solids.

• (SetType type) Returns #t. type may be one of the keywords ellipsoid, paraboloic, hyperbolic, or toroid indicating the type of the superquadric.
  
• (GetType) Returns the type of the superquadric.
  
• (SetShading shading) Returns #t. shading must be one of the keywords flat or smooth, indicating that either smooth or facted shading should be used in rendering the superquadric.
  
• (GetShading) Returns the shading type for the superquadric as a string.
  
• (SetDimensions sx sy sz st) Returns #t. sx, sy, and sz are numbers determining how the superquadric should be scaled in the x, y, and z directions. st affects the cross-sectional diameter of the ring of a toroid.
  
• (GetDimensions) Returns a list containing the scaling factors for the superquadric.
  
• (SetRoundnessFactors ns ew) ns is a number determining the longitudinal roundness (in the north-south direction), and ew determines latitudinal roundness (in the east-west direction). Returns #t.
  
• (GetRoundnessFactors) Returns a list contining the superquadric's roundness parameters.
  
• (SetSampleInc increment) increment is an integer number that determines the sampling resolution of the superquadric for use in approximating the superquadric by either a polygonal surface or polyline. A setting of 10 gives a reasonably smooth object. Higher settings increase smoothness, and lower settings decrease it. Returns #t.
  
• (GetSampleInc) Returns the superquadric's sampling resolution.
  
• (SetUVCoords uvlist) uvlist is a list of UV coordinate pairs to be used for texture mapping. The first 4 pairs in uvlist are applied to the main body of the superquadric, and determine its U & V extents. A paraboloid must have 2 more pairs, that determine the U & V coordinate extents of its bottom endcap. A hyperboloid must have 4 more pairs, that determine the U & V extents of its top and bottom caps. Returns #t.
  
• (GetUVCoords) Returns the UV coordinates for the superquadric as a list of pairs of real numbers.

Nametable::Glob Name Table -- hashed symbol table for object system

• (InsertName name) name is a string or symbol that is to be inserted into the name table. The name is hashed into the table. Returns the symbol if successful, or #f if the symbol is already in the table.
  
• (DeleteName name) name is a string or symbol that is to be deleted from the name table. Returns #t.
  
• (GetSymbol name) name is a string or symbol that is to be searched for in the name table. The symbol is returned if it is found, otherwise returns #f.
  
• (GetNamedObject name) name is a string or symbol that is to be searched for in the name table. The Scheme object named by the symbol is returned if the symbol is found and it names an object, otherwise returns #f.
  
• (GetFirstSymbol) Returns the first symbol in the name table.
  
• (GetNextSymbol) Returns the next consecutive symbol in the name table. Returns #f when there are no more symbols. This method is initialized by a call to GetFirstSymbol, or by making another call to GetNextSymbol after it has reached the end of the names in the table.

Pane::Glob Window Pane -- framework for a screen window

GWindow::Pane Graphic Output Window -- basic color graphics window

Reader::Glob File Reader -- for reading an image from a disk file

• (SetDestinationImage image) image is the Image object to which the reader will send an image upon reading it. Returns #t.
  
• (Read) Causes the reader to read and return the image.
  
• (SetFileName name) name is a string giving the file name of the file that should be read. Returns #t.
  
• (GetFileName) Returns a string giving the file name the reader is currently using.
  
• (LoadImage) Causes the reader to read the image and place it in the Image object specified by SetDestinationImage. Returns #t.

GIFReader::Reader GIF Reader -- reads 8-bit GIF format image file

JabkaReader::Reader Jabka Reader -- reads Jabka raster format image file

PictureReader::Reader Picture Reader -- reads Jabka picture format image file

PPMReader::Reader PPM Reader -- reads Portable Pixmap format image file

Renderer::Glob Renderer -- basic framework for all renderers

• (SetOutputImage image) Sets the output image to which the renderer will send its output to the Image object image. Returns #t.
  
• (GetOutputImage) Returns the renderer's output image object.
  
• (SetAntiAliasLevel level) level is a positive integer number that determines the anti-aliasing level of the renderer. Level 0 gives no antialiasing. Currently the highest level implemented for any renderer is 3. Returns #t.
  
• (GetAntiAliasLevel) Returns the renderer's antialiasing level as an integer.
  
• (SetShader shader) shader is the Shader object that the renderer should call to compute the shade (i.e. color) of a point in the geometric model. Returns #t.
  
• (GetShader) Returns the renderer's shader object.

BSPRenderer::Renderer Binary Space-Partitioning-Tree Renderer

• (SetFlags flags) The bits set in flags are set in the BSP renderer's control flags. Returns #t.
  
• (ClearFlags flags) The bits set in flags is are cleared in the BSP renderer's control flags. Returns #t.
  
• (GetFlags) Returns the flags currently being used by the BSP renderer.

RayTracer::Renderer Ray Tracing Renderer

• (SetPattern pat) pat should be one of the keywords adaptive-grid or stochastic-box telling the raytracer how it should distribute rays for antialiasing. Returns #t.
  
• (GetPattern) Returns the type of ray distribution being used for antialiasing.
  
• (SetExposure exp) exp is a positive real number giving a mesure of the "length of exposure" to use in shading an image. Generally this will be 1.0, but if the image is too bright it can be lowered, or if it is too dark the exposure can be raised. Returns #t.
  
• (GetExposure) Returns a real number giving the exposure being used by the raytracer.
  
• (SetDepthAndTolerance depth maxattn) depth is a positive integer number giving the maximum depth of the shade tree to use when tracing a ray. maxattn is a positive real number that gives the maximum attenuation, expressed as a fraction, that a ray should undergo before discontinuing tracing the ray. Returns #t.
  
• (GetDepthAndTolerance) Returns a two element list containing the depth and attenuation being used to control the depth of the ray tree when raytracing.
  
• (SetColorThreshold thresh) thresh is a positive real number giving the percent by which shades in adjacent adaptive grid cells may differ from each other before the cell is further subdivided. Returns #t.
  
• (GetColorThreshold) Returns the color threshold as a real number.

Scanline::Renderer Scanline Renderer

• (SetBackCull on_off) If on_off is true, sets backculling of polygons on, otherwise turns backculling off. When backculling is on, polygons whose normals face away from the camera are discarded before rendering. This generally saves a good deal of rendering time. Returns #t.
  
• (GetBackCull) If backculling is on returns #t, otherwise returns #f.

Wireframe::Renderer Wireframe Renderer -- used mostly as a previewer

• (SetBackgroundColor color) Sets the background color for the wireframe image to the RGB color color. Returns #t.
  
• (GetBackgroundColor) Returns the wireframe renderer's background RGB color.
  
• (SetLineColor color) Sets the line drawing color to the RGB color color. Returns #t.
  
• (GetLineColor) Returns the line drawing RGB color.

Shader::Glob Shader -- used by renderers to determine pixel shade

• (InitShader) Initializes the shader. Must be called before rendering a new image. Returns #t.
  
• (DoneShading) Tells the shader that an image is completely shaded. Must be called at the end of rendering a new image. Returns #t.
  
• (SetAttenuation dist) dist is a positive real number that determines the unit distance for the distance attenuation calculation. Assuming that the atmospheric transmittance t as given by the shader's environment material is neither 1 nor 0, the distance attenuation multiplier is given by t[(d + dist) / dist], where d is the distance from the camera's center of projection. Returns #t.
  
• (GetAttenuation) Returns the attenuation multiplier as a real number.
  
• (SetFadeColor color) Sets the color to which all colors tend as they move far away from the camera. color is an RGB color. If a fade color is not specified and color fading is being done, the background color is used for the fade color. Returns #t.
  
• (GetFadeColor) Returns the fade color as an RGB color.
  
• (SetFadeDistance dist) Sets the fade distance to the positive real number dist. Colors are interpolated to the fade color with distance according to the following formulae: f = e-(d / dist), c = f c + (1 - f) fadecolor, where d is distance from the camera's center of projection, and c is the color being interpolated. Returns #t.
  
• (GetFadeDistance) Returns the fade distance as a real number.
  
• (SetOption option) Sets the shading option specified by option. option must be either scattering or transparency. If scattering is on, surfaces reflect the ambient light color fully, otherwise only their diffuse component reflects ambient light . This has a large affect on the appearance of highly specular (shiny) materials. If transparency is on, the renderer using this shader will do transparency calculations, if it has the capability. Returns #t.
  
• (UnsetOption option) Clears the shading option specified by option. option must be either scattering or transparency. Returns #t.
  
• (GetOptions) Returns a list of symbols giving all of the shading options currently in effect.
  
• (SetEnvironment environment) Sets the shader's environment material to the Material object environment. The environment material is currently only used to determine the transmissivity of the atmosphere. Returns #t.
  
• (GetEnvironment) Returns the Material object being used as the shader's environment. Returns #t.
  
• (SetShadeLevel level) Sets the shading level. level must be either ambient, default, diffuse, phong, or fuzzy. ambient shading ignores lighting and shades objects according to their material's diffuse color only. default shading computes only diffuse shading, assuming only a single light source located at the COP of the camera, and does not attempt to smooth shade across polygons. diffuse shading takes all light sources into account, and attempts to smooth shade across polygons, but computes only the diffuse component of the shade. phong shading takes all light sources into account, attempts to smooth shade across polygons, and computes a full shade including diffuse and specular terms. fuzzy shading is only used by the raytracer. It does full shading as in phong, but also shoots diffuse reflection rays for diffuse lighting effects such as color bleeding, and samples area light sources for shadow penumbras. Returns #t.
  
• (GetShadeLevel) Returns a symbol giving the shade level.
  
• (SetAmbientRatio ratio) Sets the ratio of ambient light to light from diffuse and specular reflection. ratio is a real number from 0 to 1. Returns #t.
  
• (GetAmbientRatio) Returns the ambient ratio as a real number.
  
• (SetAmbientColor color) Sets the color of the ambient light to the RGB color color. Returns #t.
  
• (GetAmbientColor) Returns the ambient light color as an RGB color.
  
• (SetDefaultColor color) Sets the color that will be used for objects with no material color to the RGB color color. Returns #t.
  
• (GetDefaultColor) Returns the default color as an RGB color.
  
• (SetBackColor color) Sets the background color to the RGB color color. Returns #t.
  
• (GetBackColor) Returns the background color as an RGB color.

TextureMap::Glob Texture Map -- used to supply a texture to a material's surface

• (SetPattern pattype) Set the type of the texture map. pattype is either single-shot, repeated, or unbounded. singleshot means that a pattern is used only once within the unit square [0...1, 0...1] in the UV coordinate frame. repeated means that the pattern is repeated as necessary to fill the space being texture mapped, with the pattern in the unit square [0...1, 0...1] being repeated in neighboring squares. unbounded means that the pattern may be defined over the entire UV coordinate space, with no restriction to unit square boundaries. Returns #t.
  
• (GetPattern) Returns the texture pattern type as a string.

ColorMap::TextureMap Color Map -- used to supply a color pattern to a material's surface

• (AddAtoms atom-list) Add the atoms described in the list atom-list to the color map. Each atom in atom-list is itself described by a list consisting of a keyword giving the atom type, and parameters describing the atom. Valid atom types together with the arguments they require are: solid-circle color center radius, solid-box color center dims angle, solid-ellipse color center dims angle roundness, linearfade a b c fardist coltype near-color far-color, circularfade center fardist coltype near-color far-color. solid-circle describes a filled circle, solid-box describes a filled rectangle, solid-ellipse describes a filled superellipsoid (which can range in shape from a rectangle to an ellipse to a pinched diamond as in a deck of cards). linearfade describes a color fade between two colors, controlled by distance from a specified line. circularfade describes a color fade controlled by distance from a common center. color is an RGB color, center is a list giving the U and V coordinates of the center of the atom, radius is the radius of a circle, dims is a list giving the distance from the center to the boundary of the atom in the U and V directions, angle is a clockwise angle of rotation in degrees of the atom about its center, roundness is the roundness factor as used in defining a superquadric (0 = square, 0.5 = rounded, 1 = round, 2 = diamond, >2 pinched), a b, and c the coefficients of the line aU + bV + c = 0 from which a linear fade will begin starting with the color near-color, fardist is the distance at which the fade will reach the color far-color, and coltype is either the keyword hsv or rgb determining whether near-color and far-color are expressed in either HSV or RGB color coordinates. Both fades can take an optional final keyword argument unbounded, which gives them an infinite potential extent in UV space. AddAtoms returns #t.
  
• (DefineAtoms) Prints a list to the standard output, summarizing the various atom types and the formats of their descriptions. Returns #t.
  
• (SetDefaultColor color) Sets the default color to use for the color map to the RGB color color. Returns #t.
  
• (GetDefaultColor) Returns the default color as an RGB color.
  
• (SetDefaultAction action) Sets the action to be taken when there is no atom overlapping the current UV coordinates. action must be either returnnull or returndefault. If returnnull is selected, no color is returned when the color map is sampled, as if the colormap were transparent at that point. If returndefault is selected, the colormap's default color is returned when the color map is sampled. Returns #t.
  
• (ResetMap) Clears all atoms from the color map. Returns #t.