Extensions:Uni-Verse/Simple Renderer

Introduction

This document is the user's guide for a computer program called "Verse Simple Renderer". This program is based on the Verse platform for networked 3D graphics applications, and provides a way to visualize the contents of a host process by rendering it to a screen.

The "simple" in the name of the application is meant to convey that, in the context of the capabilities of the underlying Verse platform, the renderer described here is rather limited. Still, it has plenty of uses, as will be described by this document.

The text is organized into sections, describing (in order) the installation of the application, how it is started and controlled when running, and finally some of its limitations are detailed.

Installation

To run the simple renderer, you must first get hold of it in a runnable state on your particular machine. How to do this varies with the platform you are using, and a detailed explanation would be a bit outside the scope of this document.

Requirements

In order to be able to run the simple renderer, your environment must provide all of the other software components on which it depends. If you are using a pre-compiled ("binary") version of the renderer, most of these will have to have been taken care of already, by whoever built the program for you.

The dependencies are:

Verse: Hopefully not too surprisingly, you will need the core Verse system. You do not have to be running a host on your own machine, but you will need the API implementation in order to compile the renderer. If using a pre-compiled version, you probably do not need to have Verse itself installed at all.

The Verse core is available at the main Verse site.

glib: glib is a utility library for C programmers. It is part of the GTK+ user interface toolkit, but does not do anything graphical at all. It contains useful data structures and other functionality that makes it easier to write larger programs.

The use of glib in the simple renderer is a mild annoyance, and it might be phased out over time.

The glib library is available on the main GTK+ web site. Boinary versions for Win32 are published by Tor Lillqvist.

OpenGL: OpenGL is the industry-standard programming interface for 3D graphics. It is what the simple renderer uses to get the graphics on screen. Most modern computers should already have OpenGL installed, or easily available. The simple renderer uses only very basic OpenGL facilities, and should work with almost any version.

More information about OpenGL is on the the official site.

GLU: GLU is an OpenGL utility library that makes writing OpenGL applications a bit easier. It is used by the simple renderer for camera control and perspective projection matrix initializations.

GLU is almost always installed at the same time as OpenGL itself, so separate installation should not be necessary.

GLUT: GLUT is a toolkit library that helps programmers tie OpenGL to the underlying operating system. It handles otherwise system-dependent tasks such as opening windows, reading keyboard and mouse input, and so on.

GLUT has a page on the official OpenGL site. For Windows, success has been had with Nate Robins' implementation, for instance.

Obtaining the Software

Once the dependencies are in place (see above), the next step is to retreive the actual software. How to do this can vary with the platform. For Unix-type platforms, the recommended way to get a running version of the simple renderer is to compile it from the source code. For Windows and Macintosh environments, downloading pre-compiled binaries might be an easier choice. This section assumes you are building from source code; hopefully there will be links to pre-compiled versions later on.

Obtaining the software in source code form currently requires the use of CVS, the Concurrent Versions System. This is a revision-control software system, that is used to maintain the source code of the Verse core as well as many applications, including the simple renderer.

Assuming you have CVS installed, the commands to retrieve the source code are:

 $ cvs -d:pserver:anonymous@cvs.blender.org:/cvsroot/verse login
 $ cvs -z3 -d:pserver:anonymous@cvs.blender.org:/cvsroot/verse co verse-tests

The first of these logs you into the CVS server. It will ask for a password, but since you're logging in as an anonymous user, no password is used. Just press Return, entering an empty password. The second command checks out ("co") the verse-tests CVS module, in which the source code for the simple renderer resides. You will get a directory called verse-tests, holding the code.

Building the Renderer

How to go aboout compiling the source code retreived in the step above depends on the platform. On a POSIX-compliant (read "Unix-like") platform with command-line tools, you would issue a command like the following:

 $ make render

Here, "render" is the name of the simple renderer in the Makefile that controls the compilation of this particular module.

This command should result in a binary, executable version of the program, called "render" or perhaps "render.exe" (depending on your platform).

Running the Simple Renderer

This section describes how to run the simple renderer. It assumes you have a working, compiled, version of the code on your local machine. The name of the program is further assumed to be "render"; the suffix ".exe" present on e.g. Windows is omitted for brevity.

To simply start the client, and have it automatically connect to a Verse server on your local machine, issue the following command:

 $ render

If you want to connect to a Verse server running on some address other than the default of localhost:4950, use something like this:

 $ render -ip=verse.example.org:4711

Of course, the colon and the port number that follows it are optional; if omitted the default port is used. The next section details all the command-line options supported by the client.

Command-Line Options

For completeness, the command-line options supported are:

-ip=HOST[:PORT]: Sets the address of the Verse host to connect to. HOST is either a regular human-readable host name such as localhost or verse.example.net, or an IP address in dotted-decimal form (such as 127.0.0.1). PORT, which if present must be separated from HOST by a colon, is a port number in decimal format, such as 4950 or 32011.

-glinfo: Prints some information about the OpenGL in use. It prints the version, vendor, and extensions strings, as reported to the application by the OpenGL implementation.

-loudkeys: Enables a mode where keyboard input is echoed to the terminal window from which the application was started. Mostly useful during development of the client.
-modmouse: Enables a specialized mode where the ↵ Enter key makes the LMB toggle between movement and panning. This is sometimes useful on PDA-type devices, see below.

-tiny: Starts the renderer with a smaller window size, intended for environments with small screens, such as PDAs. The size in this mode is "QVGA", 240x320, with a portrait orientation. If not specified, the default size is "VGA", or 640x480 pixels.

[-]help: Prints brief usage information to the terminal window. The dash is not required, any argument that contains the word "help" (that is not one of the above-mentioned options) will trigger this behavior. This means that there should be no problem specifying a host name containing "help" using the -ip option, for instance.

The Window

The image in Figure 1 shows how the simple renderer's main window looks in a Linux environment. The window is dominated by a perspective rendering of the data found on the Verse host it is running against. Objects are rendered as raw polygon meshes, with random colors applied to individual polygons to make borders very obvious.

Figure 1. A screenshot of the Simple Renderer's main (and only) window, showing a car model.

The blue plane is a local artifact, it is not imported from the server but added by the simple renderer to provide a reference "ground" plane. The same goes for the red, green and blue lines that indicate the directions of the X, Y and Z axis, respectively. Both of these features can be turned off if they are interferring negatively with the data being viewed, see Section 3.3.3 below.

Not visible in this image are any object names. The renderer will render the name of each object at its center, as a textual label. The label will be colored blue for all objects, except if one object is the currently selected one, in which case it will be yellow. See below for details on how to select an object.

The odd-looking graph in the bottom left corner shows the size of the outgoing Verse command queue. This is not something that is immediately meaningful to the majority of users; it's a developer feature, and can also be turned off.

The number in the bottom right corner shows the number of polygons rendered in the current frame. It is updated on a per-frame basis. It does not include any client-side graphics added by the client, like the ground plane and the axis.

Note: If you see rendering errors that seem to happen to individual pixels, for instance that one of the axis lines is dashed rather than solid, you might be experiencing something called Z fighting. Make sure that your computer is running at maximum supported color depth (in Windows, use 32-bit color, not 16).

Controls

The simple renderer is written for two standard input devices: a three-button mouse, and a keyboard. Descriptions on how to use these devices to control the renderer are given below.

Mouse Controls

The mouse is used to control the position and orientation of the viewpoint, i.e. to move and to look around. There is also a small pop-up menu which is accessed using the mouse.

To move using the mouse, simply click with the LMB anywhere in the window. While still keeping the button pressed, move the mouse up and down, to move forward and backward, respectively. The view will continue to move for as long as you keep the button pressed, with the speed set by the vertical distance between the mouse pointer and the point where you first clicked. To stop moving, just release the button.

To change the direction in which you're looking, click the MMB and drag. The viewpoint will shift towards the direction in which you're dragging. To stop, release the mouse button.

The Pop-Up Menu

By clicking the RMB anywhere in the window, you can access a simple pop-up menu. The menu consists of two submenus, labelled "Objects" and "Camera" respectively.

The Objects submenu lists all object nodes in the current host, by name. Picking one makes it the "current object" (it's label turns yellow in the 3D window). Many keyboard commands operate on the current object and require such a selection to exist. The first entry in this menu is labelled "<None>", and does not correspond to any object node. If picked, it will clear the selection.

The Camera submenu selects the mode in which the camera should operate. There are four such modes, not all of which work very well:

Free Flying. This is the default camera mode, in which the mouse works as described above.
Isometric. Places the camera in a fixed location, looking down at the center of the scene from the "positive octant". Does not change the actual projection mode of the camera, so it's not a true isometric view.
Satellite. Places the camera in a fixed location 2,000 units above the origin, looking straight down.
Object. Places the camera in the currently selected object, looking in a direction controlled by the mouse as in the free-flying mode.

The Free Flying mode is what works best, the others are more or less to be considered unfinished features.

Keyboard Controls

The simple renderer has a number of keyboard commands, that are simply accessed by pressing the relevant key on the keyboard. These commands are not of a "chorded" variety, so you do not need to hold down e.g. Control or some other key while issing a command. Just press the indicated key alone. When the indicated key is upper case, you do need to press it with ⇧ Shift, as usual.

w,a,s,d: Move forward, left, backward, and right respectively. These four commands provide a way to move the viewpoint without using the mouse. Since the movement is strictly limited to four directions relative to the current viewing direction, you still typically need to use the mouse though.
W,S: Move up and down, respecting the current yaw and pitch angles. This means that if you are looking straight down, moving "up" will have very little effect on the actual vertical position of the avatar.
u,j,h,k: Move the currently selected object forwards, backwards, left and right respectively. These commands work by simply adding a fixed offset to the object's current position, and issuing a command to set the position to the result.
U,J,H,K: These four commands work just like their lower-case counterparts, but move the object 10,000 times the distance. This is crude, but can be handy when a big movement is required.
p: Send a "ping" command to the Verse server, with a hard-coded message. The response (if any) will be printed to the console window from which the renderer was started.
t: Toggle texture-mapping of scene objects. Currently the underlying functionality does not work.
T: Toggle polygon rendering between ordinary, filled, style and wireframe.
g: Toggle display of the client-side ground plane.
G: Toggle display of the client-side coordinate axis.
l (lower-case 'L'): Toggle lit rendering on and off. Lighting is by the light-sources defined by the Verse data, but applied in a very simplistic way. Basically, the first N light sources found in the scene database are activated, with their color sent straight to OpenGL. N is a limit defined by the OpenGL implementation used, N=8 is common. In this mode, a generic material that is a blue-ish grey color is applied to all surfaces, Verse materials are not interpreted.
c: Toggle display of the current Verse time.
C: Toggle per-frame printout (to console window) of camera's position. A development/debugging feature.
v: Toggles labelling (by server-side ID/index) and extra indication of each vertex.
V: Toggles labelling (by coordinate values) of UV coordinate data, from the map_u and map_v geometry layers, if present.
z: Toggles the blue wireframe cubes and spheres that indicate object nodes on and off. Since the rendering can sometimes become cluttered if there are many clients connected to the server (a client's avatar generally lacks geometry, and thus gets a cube), this is a handy command. Wireframe spheres are used for geometry-less objects that are also light sources, in order to make them even less cluttering.
Z: Toggles use of backface culling on and off. Can be useful when investigating whether a model has had its surfaces flipped the wrong way (Verse defines a forward-facing face to have a clockwise winding, by the way).
+: Scale current object's vertices up by a factor of 20%. This command actually modifies the server-side state, by multiplying each vertex position by the scalar 1.2 and sending the result back to the server. It does not scale by changing the object-level transform, as is otherwise the normal way. This is testing/debugging feature.
-: Scale current object's vertices down by a factor of 20%. This command actually modifies the server-side state, by multiplying each vertex position by the scalar 0.8 and sending the result back to the server.
.: Toggle the display of the command queue graph in the bottom left corner of the display.
: Toggle the "hidden" state of the currently selected object nodes. Hidden objects are not rendered.
↵ Enter: Toggle left mouse button-drag between moving and looking around. This only works if the client was started with the -modmouse command-line option. Without that option, pressing this key does nothing and the left mouse button always controls movement. This is intended for use on systems where the left mouse button is a lot easier to use than other buttons (if even available), such as pen-based environments.
Q,Escape: Immediately disconnect from server, and exit the application.
Delete: Sends a node_destroy command to the current object node, its geometry node (if any), and its material node (if any).

Limitations

Now that we've seen a bit about how the simple renderer looks and what controls it has, it might be interesting to learn about its limitations. As the program's name emphasizes, they are several and somewhat severe. Still, the application is useful in many situations.

These are some of the most limiting drawbacks of the simple renderer, viewed from a Verse-compliance perspective:

No Subdivision: Verse's sole geometry primitive is the subdivision surface. The simple renderer does not implement any form of subdivision. Instead, what it renders is the base "control mesh" geometry, that is actually stored on the host.

While this makes the renderer unable to even approach the quality possible with Verse geometry, it is still useful and the simplicity of its rendering makes the code very short and simple. Not all geometry is subdivided, and during testing and development it is often interesting and valuable to be able to see just the objects' control meshes.
No Materials: Verse features a rather sophisticated, computation-tree based, materials system. This system is completely ignored by the simple renderer, which simply assigns each polygon a random color and renders it flat without any shading.

This limitation is purely to keep the code simple; while interpreting a Verse material tree is not particularly hard, it is still quite a lot of code, and generating the desired output while still using OpenGL 1.x is fairly difficult.
No Animation: Verse has a bone-based animation system, that allows arbitrary skeletal models to be constructed and animated. The simple renderer completely ignores all animation-related data and commands. This is another sacrifice to limit the size and complexity of the renderer's code.
No Reconnect: Many other Verse applications allow the user to disconnect from a host and then connect to some other host by specifying the desired address in some kind of graphical interface. The simple renderer does not; the only time you are allowed to specify a host address is from the command line before starting the program. To connect to a different host, you must quit the program and start it all over again with the desired address.

This limitation is not considered to be very severe, since the start-up time for the simple renderer is very short. All modern operating systems support command line histories, which makes it easy and quick to edit and re-issue the previous command.