GLRex Documentation

GLRex allows a maximum of 70 objects in a scene and 80 control points in an outline for a NURBS surface.

GLRex will autosave your session every time you create an object. The session is saved as backup.ses.

There are 2 GLRex windows - the main Display window and a Curve drawing window for creating NURB extrusions and surfaces of revolution.
 
 

Display Window

 

The viewer is always looking at the origin of the world coordinate system. The world coordinate axes are the x-axis (red), y-axis (green), and z-axis (blue). The eye position is controlled by six keys. Conceptually the viewer is on the surface of a sphere and can change latitude and longitude and distance from the origin. The keys controlling the eye position are:

<- and ->	left arrow, right arrow control longitude
/|\  and  \l/	up arrow, down arrow control latitude
. and /	Period and slash control distance from the origin

 

The display window has subwindows in each of its corners:
 
 

Subwindow	Main Use
Upper Left (UL)	Object and light properties
Lower Left (LL)	Palette
Upper Right (UR)	Light Controls
Lower Right (LR)	Object list

 

GLRex has two pull-down menus located at the top middle of the display window, labeled “misc” and “I/O menu”.

The miscellaneous menu has the following options:
 
 

Option	Use
Show/hide light sources	Toggle visibility of light sources locations
Delete all objects	Delete all objects from the scene
View current cluster	Only objects in the current cluster are visible
Copy color properties	Copy color and shine of the current object to the clipboard
Paste color properties	Paste color and shine on the clipboard onto the current object
Copy silhouette	Copy silhouette associated with current object onto clipboard – only applies to NURB surfaces
Paste silhouette	Paste silhouette on clipboard onto current object

The Input/Output menu has the following options:
 

Option	Use
Reset home dir	Change home directory used in I/O Dialog Box
Load session	Load a .ses file. Resume saved session
Save session	Save current session to .ses file
Save to rib	Export the current scene as a RIB file
Save to gl	Export the current scene as an OpenGL based .c file
Load code segment file	Load a .rcf file.

 

Left-clicking on an I/O menu option opens the appropriate I/O dialog box.

GLRex imports two file types:

.ses	text files for saving and reloading work sessions
.rcf	RenderMan RIB code to be spliced into exported .rib files

GLRex exports two file types in addition to .ses files:

.rib	RenderMan Interface Binary files, which can be rendered by a RenderMan  compliant  renderer.
.c	C programs code which will recreate the current scene using OpenGL and the windows API glut.

 

Left mouse clicks in the middle of the Display Window will move the current object (or cluster if in cluster mode) to a location above the point clicked on in the grid. Right mouse clicks in the middle of the Display Window will toggle the visibility of the corner windows. This is useful if you want to screen captures the window.

UL Window

The window is used to create objects and to position, shape, and color them. The type, position, scale, color, and rotation values for the current object are displayed in the UL window. 

The current object is chosen by clicking on an object's name in the LR window

Clicking on box, sphere, cylinder, revolution, extrusion, cone will create a new object of that type. Surfaces of revolution and extrusions are created as NURB surfaces and their outline must be drawn in the Curve Window.  (See curve window). If you click on ext you will be given a choice between unit and separates. “Unit” is an extrusion with the side surface created by the extrusion and front and back caps treated as one object. Caps and sides will always have the same color. Choosing “separates” will create 3 separate objects - the side surface created by the extrusion (which appears in the object list in the LR window as openext), and the front and back caps (which appear in the LL window list as two caps).

To create an open extrusion alone, i.e. just the extruded side , without caps, choose separates and then delete the front and back caps. To create a cap (without sides) again choose “separates” and delete the openext and one of the caps. 

When a new object is created, it becomes the current object, and is initialized with the position, scale, and rotation of the previous current object. If the current object is a sphere and you create another sphere, the new object will not appear immediately since it will coincide with the previous sphere. You will see it if you move it from its initial position.

An object's properties can be changed by clicking the mouse on the appropriate property display:

mouse click	action
left	decrements
right	increments

 

The change per click can be toggled between 1 unit and 10 units by clicking on the string “inc/dec" or “inc/dec*10” near the bottom of the UL window.

 

There are two coordinate systems to keep in mind when using the Display Window - the world coordinate system and the object’s coordinate system. (The visibility of these axes is controlled from the UR window. Remember the x-axis is always red, the y-axis is always green, and the z-axis is blue.)

 

Position is always relative to the world coordinate system.
Rotation is always relative to a hybrid coordinate system. See "UR Window" below.
Scale is always relative to the object coordinate system.

Notice that for both scale and color there is an "all" option. Clicking on "a" will increment or decrement the other three quantities on the line simultaneously. Clicking "r" will reset Pos, Rot, Scale, or Color to their initial values.

Colors are represented using their red, green, blue components (RGB color system). The scale used is 0 - 255.

Finally, at the bottom of the UL window, clicking on "wire" or "solid" will toggle between displaying the whole scene as wireframe or as solid objects. If you have several NURB surfaces in your scene, changing eye position may be a little sluggish. Switching from "solid" to "wire" will speed things up.

LL Window

 

The color of both lights and objects can be determined in this window by left clicking in the color hexagon. (See more on lights in UR window.) The white dot in the color hexagon indicates the current color. (The RGB values of the current color will appear in the UL window.) The shine of the object is controlled by the shine scroll bar. The intensity of a color is controlled by the intensity scroll bar. If the current color refers to a light source, changing the shine will have no effect. (When the current color refers to a light source the demo sphere between the scroll bars will appear flat.)
 
 

UR Window

The current light can be selected by left clicking on the light's name. The current light's name will appear white. You can change the color of the current light just as you would the current object, either in the palette window or in the UR window. You can change the position (or direction) of the current light source in the UR window clicking on the "pos" property line. The position of a light source has different meanings depending on whether the light source is positional or directional.   

positional light - like a light bulb. All light rays eminate from the position of the light source.

directional light - like the sun. All light rays are parallel to one another and have the same direction as the vector from the position of the light source to the origin.

 

Lights can be changed between positional to directional by left clicking on "P" and "D" by the name of the light.

Lights can be turned on and off by left clicking on "on" and "off" by the name of the light. If light sources are visible and if you left click on the current light, the light and the sphere that indicates its location will toggle color to aid in identification.

You can make the light sources visible using the “misc” menu. The lights will appear as spheres with the same color and position as the corresponding light.

Extrusions and surfaces of revolution are implemented as NURB surfaces. The number of facets used to create the surfaces can be controlled by clicking on one of lw, med, hi, vh. The default is med. The surfaces look better with higher resolution but this also slows down GLRex. If this isn't a problem on your machine I would suggest using at least hi.

The next line in the window, contains controls for RIB code lists. “show/hide” controls the visibility of the current RIB code list. When visible this list appears on the left hand side of the Display Window. “reset” sets the code list back to the default empty list and removes all bindings of RIB code to objects.

There are four buttons at the bottom of the window:

w-axes	toggles visibility of world coordinate system axes
o-axes	toggle visibility of the current objects coordinate axes
grid	toggles visibility of rectangular grid of lines in the Display window
backup	saves the current session to the file backup.ses, in same directory as the GLRex executable.

If you have made the current object’s coordinate axes visible you will see one of two axis systems, depending on whether you are positioning, scaling or rotating the object. In the case of positioning or scaling the object, the standard object coordinate axes will appear. These axes are colored red, green, blue, and are mutually perpendicular. The colors coordinate with actions taken in the UL window. For example if you click on the red component of scale in the UL window, the scale of the object will change in the direction of its object coordinate system red axis.

If you are rotating the object an alternate set of axes will appear colored orange, cyan, and blue. This set of axes is not the same as the previous set but somewhat related. The blue axis is the same in both. Changing the x-rotation angle will rotate the object around the orange axis. Changing the y-rotation angle will rotate the object around the cyan axis. Changing the z-rotation axis will rotate the object around the blue axis. Note that the orange, cyan, blue axes are not perpendicular. (Going into what these axes mean is beyond the scope of the documentation. It is related mathematically to the fact that rotation matrixes do not commute.)

 
 

LR Window

GLRex works in either of two modes - "object" or "cluster". By clicking on "object " or "cluster " at the top of the LR window, GLRex will change modes. Clicking on the "+" or "-" on either side will copy or delete the current object/cluster. This can also be achieved by using the insert and delete keys on the keyboard.

GLRex does not support hierarchical modeling at this time. It does however allow the user to create temporary clusters of objects. Only one cluster can exist at a time. As a group a cluster can be copied and deleted. This will only be allowed if the current object is part of the current cluster.

 Objects can be added/removed from a cluster by left clicking on the object’s number in the LR object list. Red numerals in front of an object indicate that the object is in the current cluster, white that it is not in the cluster. In cluster mode the names of all objects in the cluster will be highlighted in green, except for the current object which is always highlighted in blue or red. F11will remove all objects from the cluster, F12 will place all objects in the scene into the cluster.

 

A cluster can also be translated, rotated, and scaled in the same way that objects are - clicking on the appropriate locations in the UL window or using the F1-F4 keys. In all cases the current object must be in the cluster. In the case of rotation every object is rotated are it's own origin. GLRex does not support cluster origins at this time. Objects in a cluster will only be scaled if they initially have the same x, y, z scale values as the current object. The material properties of a cluster can also be scaled in the same way they would for a single object. Changes in color will only be applied to only those objects in the cluster that have the same color as the current object.

 

The LR window lists of all objects in a scene from 0 to 69. The current object is originally highlighted in blue. To select the current object, left click on the name of the object in the list. If you repeatedly click on the same object, the color of the object will toggle in the display window to help locate the object. The highlight of the object will also toggle from blue to red.

When an object is created, the geometrical name that describes the object appears in the object list. To give the object a different name, simply type the new name. The only keys you can use are "backspace" which moves the cursor back one space, alphanumeric keys,  "-" and "_". Backspace erases the last character in the current objects name.

Name changing can be done in cluster mode as well. All character changes will be applied to all objects in the cluster. As an example suppose you have created a left leg composed of a thigh and a calf and have labeled them as "calf-l" and "thigh-l". If you copy them in cluster mode to create another calf and thigh, the new calf and thigh will still be labeled "calf-l" and "thigh-l". But by simply hitting backspace then typing “r” you have changed both to "calf-r" and "thigh-r".

To scroll through the list use the PageUp and PageDown keys.

 

I/O Dialog Box

 

The top line in the I/O dialog box describes what action is being taken, e.g. “load ses file”. The next line gives the current directory – the directory whose contents are being displayed in the list below. Immediately under that is the “file” field. This field can be changed either by clicking on a file name in the list of files below, or directly from the keyboard. When an I/O dialog box is visible any keystrokes appear in this field. As with names in the object list the only keys you can use are "backspace" which moves the cursor back one space, alphanumeric keys,  "-" and "_". Backspace erases the last character in the current file’s name. Double clicking on the file field will cause the desired action of the dialog box to  using the file currently in this field. 

Below the file field are three buttons:

 

Button	Use
UpDir	Moves current directory up one level to parent  directory
Close	Closes dialog box
Home	Home directory becomes current directory

Below these buttons is the list of the contents of the current directory. Subdirectories are listed first (in black) and then files (in white). To scroll through the list use the PageUp and PageDown keys.

 Click once on a file and the file name will appear in the file field of the dialogue box. Double click on a file name and the action requested by the dialogue box will be performed using that file. Double click on a directory name, and that directory will become the current directory.

 

Curve Window

The Curve window represents a 2 dimensional surface for drawing outlines of extrusions and surfaces of revolution. The default origin is the bottom left hand corner of the window. This is a good position for surfaces of revolution but you will probably want to move it for extrusions. The origin can be changed using the orgn option (see below).  Curves should in general be drawn in a counterclockwise direction. For surfaces of revolution the outline you draw will be revolved around the y-axis to create the object. So in a sense you are drawing half an outline. GLRex allows a maximum of 80 points in an outline.

Left mouse clicks create control points in Add mode and reposition the current point in Edit mode. Right mouse clicks select control points.

The current point is indicated with a blue square. All other control points are indicated with black squares. There are 2 curves displayed - the control curve in black (used for creating the wireframe representation of the surface) and the NURB curve in red (used for creating the NURB surface). Notice that the red curve in general does not go through the control points except for the first and the last. If you want a quadratic NURB curve to go through a point, click twice on that point, creating two control points at the same location. For cubic NURBS click three times.

If you want an extruded surface with a top and bottom, the curve has been drawn in a counter-clockwise direction and the first and last control points must coincide. (If you are drawing a periodic NURB the first and last points will automatically coincide.)

At the top of the window is a toolbar with these options:

edit	Left click here to go between Add mode and Edit mode. Red indicates Add mode, yellow indicates Edit mode
ins	Inserts a new contol point midway between the current point and the succeeding point.
del	Deletes the current control point.
orgn	Mouse click will reposition the windows origin and x and y-axis. This is active when highlighted in green and inactive when highlighted in red.
quad/cube	Draw quadratic or cubic NURB.
open/peri	Draw open or periodic NURB.

 

Code Segment Files and Shaders

Light source and surface properties are managed in RenderMan through the use of shaders. Each light and surface has a shader associated with it.  GLRex does not generate shader related code itself, other than assigning a plastic shader to all objects, and one of two shaders, distantlight or newlight, to light sources.

shader	Associated with	Source File
plastic	All objects	Plastic.sl
distantlight	Directional light source	Distantlight.sl
newlight	Positional light source	Newlight.sl

 

The source code for newlight, newlight.sl, has been provided. Newlight differs from the standard RenderMan shader pointlight in that it has no intensity fall off with distance. The other two shaders, distantantlight.sl and plastic.sl, should be provided  with your RIB file renderer.

The original purpose of GLRex was to provide the user with an interactive source of rib files to provide a basis for experimenting with shaders. Initially it was designed to allow the user to create a basic rib file where all objects are created using a “default” plastic shader. The user could then edit the file in a text editor and apply and experiment with more interesting shaders. There was a problem with this approach however. Suppose the user has added shader code to the exported rib file and then decides to change the geometry of the scene or add a new object. They can go back into GLRex and modify the scene but when they export the modified rib file all of the shader code will have to be entered again.

To solve this problem, GLRex was modified to allow the user to write shader code in a separate code segment file (.rcf) which will automatically be spliced into the exported RIB file. When GLRex generates a rib file, code for an object is created in roughly in this order:

1.Geometry related code
2.Color related code
3.Shader related code
4.Drawing code

The shader related code from the current code segment file is spliced into the exported RIB file. (Note that the user can splice in any RIB code, shader related or not, using an rcf file.)

The code segment file functions as a list of code segments that can be applied to objects in the scene. Objects can be assigned a code segment number, which acts as a pointer into the current code segment list, and when the RIB file is exported, the code segment referenced by the objects pointer, is spliced into the RIB file. Thus the same shader code can be used for several objects, and the same code segment file can be used for many scenes. Initially all objects are assigned code segment number 0, which means no code is associated and the default shader will be used.

 

Format of Code Segment Files

At the right is a simple example of a code segment file (sample2.rcf). Each code segment is of the form *shader {name} {RIB code} *end The end of the file is indicated by the line **end Number 0 in the code segment list that is displayed in GLRex is reserved for no code. The first code segment in the code segment file is assigned number 1 in the code segment list and so on.

*shader  shiny  Surface "shiny" "float Kr" .9112 *end *shader spotlight1 LightSource "spotlight" 1 "to" [0.00 0.00 0.00] "intensity" 100.00 "coneangle" 0.3 *end *shader spotlight2 LightSource "spotlight" 2   "to" [0.00 -20.00 -50.00] "intensity" 200.00 "coneangle" 0.30 *end *shader  bricks TextureCoordinates[0 1 4 1 0 0 4 0] Surface "brick" *end *shader  bricks2 TextureCoordinates[0 2 5 2 0 0 5 0] Declare "brickcolor" "color" Surface "brick" " brickcolor" [0.1 0.1 0.6] *end *shader  pointlight LightSource "pointlight" 3 "intensity" 10 *end **end

 

To load a code segment file use the “Load code segment file” option in the “Input/Output” menu. To display the names of code segments on the current code segment list, click on show in the UR Window. The list will appear on the left of the Display Window with the code segment name associated with the current object or light highlighted. Initially all objects and lights are assigned code segment number 0 – i.e. no code. To change an object’s code segment number, click on the object's name in the object list (LR Window) and then click on the appropriate segment name in the code segment list. To associate a code segment number with a light, click on the light's name in the UR Window and then click on the appropriate segment name in the code segment list.

The code segment numbers, not the code segment name, is associated with an object. Because of this you need to be careful if you want to edit a code segment file currently in use. If you want to modify the current code segment file, you can edit it in an external word editor, save the edited file, then reloaded into GLRex. If you want to add a new code segment to the current code segment file, add it at the end of the file, not in the middle. Do not delete code segments from a code segment file currently in use. Reloading a code segment file or loading a new one does not change code segment numbers assigned to objects in the scene. This is useful feature if you are reloading a code segment file that you have just edited, but is not so desirable if you want to load an entirely different code segment file. In this case you probably want to reset all of the objects’ code segment numbers back to 0. To do this 0 click on “reset” in the UR Window.

 When a session is saved, the current code segment list is saved in the session file.  You do not need to save the rcf file. When loading a session that contains a code segment list, the shader information will automatically be written to the file active.rcf, which will be put in the same directory as the GLRex executable.

If you modify a shader's source code (.sl file) during a GLRex session, you do not need to reload a code segment file that uses that shader, unless you need to modify shader related code as a result of changes to the shader’s source code.