Chapter 1. Getting Acquainted with OpenGL Performer
Prev | Part I. Overview of OpenGL Performer | Next

## Chapter 1. Getting Acquainted with OpenGL Performer

This chapter provides a hands-on example of an OpenGL Performer application, Perfly, to introduce you to the features of OpenGL Performer. If you are already familiar with OpenGL Performer or visual simulation in general, you might like to skip to the overview in Chapter 2, “OpenGL Performer Basics”.

## Installing the Software

Follow the instructions in the OpenGL Performer release notes to install the software. This process places the appropriate libraries, header files, sample databases, man pages, online books, and demonstration programs on your system.

| Note: For the IRIX operating system, use `grelnotes` to read the release notes. For the Linux operating system, the release notes are located in `/usr/doc/performer-3.0.` The release notes are located in `%PFROOT%/Doc/performer-3.0` for Windows systems.

## Exploring the OpenGL Performer Sample Scenes with Perfly

This section introduces you to basic OpenGL Performer functionality through the Perfly demo application . Perfly is a basic visual simulation application that can load, store, and display scene databases in many common formats. Using the following subsections, this section describes how to use Perfly to look at several sample databases provided with OpenGL Performer:

- “Locations of Perfly and Example Source Code”

- “Starting and Quitting Perfly”

- “Basic Perfly Controls”

- “Looking Around”

- “Approaching the Building”

- “More Controls”

- “Other Motion Models”

- “The Use of Instances”

### Locations of Perfly and Example Source Code

The Perfly application is the sample OpenGL Performer application included with the installation. For the IRIX operating system, it is installed in `/usr/sbin`. For the Linux operating system, it is installed in `/usr/X11R6/bin.`On Windows systems, you can find Perfly in the directory `%PFROOT%/Bin`.

For IRIX and Linux systems, source code for Perfly is provided in `/usr/share/Performer/src/sample`/C in the `perfly` and `common` directories so that you can incorporate parts of these programs into your own applications. A C++ version can be found in the `/usr/share/Performer/src/sample`/C++ directory. On Windows systems, these locations are `%PFROOT%/Src/sample/C` and `%PFROOT%/Src/sample/C++`, respectively.

The Perfly demo is a good demonstration of OpenGL Performer in action because it is a complete application. It is, however, a large and complex piece of code. A better place to start exploring programming with OpenGL Performer is the sample code provided in `/usr/share/Performer/src/sample/pguide`. On Windows systems, this is located in `%PFROOT%/Src/pguide`. Under this directory, you can find examples for programming many of the features available in each of the libraries that make up OpenGL Performer, using either C or C++. Not all example programs appear in both directories, so you will want to look at both the C and C++ directories.

### Starting and Quitting Perfly

To launch Perfly, enter the following:

    CHIEF% perfly -d chamber.0.lsa

The Perfly program allows several motion models; the `–d` on the command line tells the program to start in the Drive model, which provides an easy way to drive or walk through a scene while maintaining a fixed height above the ground. A command-line entry of `perfly` `–h` displays a list of the command-line options.

When you want to quit Perfly, either press the `Esc` key or click the Quit button on the Perfly graphical user interface (GUI).

### Basic Perfly Controls

The Perfly demo provides a GUI with which you can control many of the visual simulation features that are described in this guide, such as time-of-day selection, haze density, and so on. These options all default to reasonable values; so, you do not need to learn about them before using Perfly.

You can operate the control panel using the mouse buttons and the keyboard. Many other keys on the keyboard are active and can be used to control Perfly even when the control panel is not displayed. The `perfly` man page contains a list of these keys sequences and their effects as well as details on motion models.

### Looking Around

Look around the scene using the mouse. First, place the cursor in the center of the simulation window. Now depress the middle mouse button and move the mouse to the left or right to turn in place; you will continue to pivot until you place the cursor back in the center of the screen.

Do not worry if you inadvertently start moving around, lose sight of the building, or otherwise lose position or control. Just move the cursor into the control panel area and click the Reset All button on the control panel to get back to the original setup.

### Approaching the Building

To approach the City Hall model, turn until you are facing it (if you are not already facing it) and then center the mouse in the screen. Depress the left mouse button briefly to start accelerating forward. When you release the button, you will continue gliding forward at constant speed and can hold down the middle mouse button to steer. The Perfly application shows you how the basic visual simulation tools work. This example uses a section of the New Jerusalem City Hall (see Figure 1-1).

Figure 1-1. Section of the New Jerusalem City Hall

Tap the middle mouse button to stop in front of the building (if you actually entered the building, remember the Reset All button). Now accelerate backward by pressing the right button. When you are as far back as you want to go, hold down the left mouse button to gradually slow down, or tap the middle mouse button to stop immediately.

Now use the left mouse button again to start moving forward and drive slowly into the model. Notice that the walls closest to you are cut away at first so you can see inside; when you are completely inside the building, those walls reappear. Drive around and explore the building. Tap the middle mouse button to stop before you run into anything (but do not worry—at this point you will bounce off any walls you hit). If the walls get in your way, you can turn off collision detection with the button labeled Collide on the control panel, or press the `c` key on the keyboard.

### More Controls

To see the underlying geometry used to create the model, click the Style button in the control panel, or press the `w` key on the keyboard. This changes the display to wireframe mode. In this mode you can more easily see how many polygons are used to represent an object. This information can be helpful when you are tuning a database, because it is important to know when the number of polygons becomes a limiting factor. To turn wireframe mode off, just click the Style button (or press `w`) again. The `W` key can be used to cycle through several different draw styles.

To close the entire control panel (and devote the entire screen to the model), click the Off button at the upper right of the control panel, or just press the `F1` key. Press the `F1` key again to restore the control panel. The GUI is part of `libpfutil`. See the following sample program:

    /usr/share/Performer/src/pguide/libpfutil/utilui.c
    (IRIX and Linux)
    %PFROOT%/Src/pguide/libpfutil/utilui.c
    (Windows)

If you click the Stats button in the control panel, a transparent panel showing scene statistics appears overlaid on the screen. The buttons next to the Stats button allow you to choose one of the available statistical displays. Try moving around in the scene while watching how the statistics change. Note in particular that the number of triangles being considered for rendering changes drastically depending on where you look; this demonstrates OpenGL Performer's use of culling to ignore objects that are completely outside the field of vision. For more information about culling, see Chapter 15, “Optimizing Performance”. For more detailed information on the statistics panels, see Chapter 18, “Statistics” in the OpenGL Performer Programmer's Guide.

The control panel's field-of-view slider can be used to select a wide angle view, up to 100 degrees.

As you travel through the building, try turning on the fog effect by clicking the Fog button. Experiment with the fog density and other controls. (Remember that if you have closed the control panel, the `F1` key restores it.)

### Other Motion Models

So far you have been driving. There are other default motion models provided through the `libpfui` library. These motion models can be subclassed to create your own models. On IRIX and Linux systems, you can find the source code for these motion models in `/usr/share/performer/src/lib/libpfui/`. On Windows systems, the source code is found in `%PFROOT%/Src/lib/lib/libpfui/`.

#### Flying

The Fly motion model provides an alternative to the Drive model. This model allows full motion in three dimensions (unlike the Drive model, which does not allow vertical motion). The mouse in the Fly model is used in much the same way to control motion, but when steering, the vertical position of the mouse in the window controls your vertical tilt. You can select this mode by pressing the right mouse button on the button marked Drive and select Fly from the menu.

As when driving, the left button makes you go forward and the right button makes you go backward. As long as either button is pressed you will continue to accelerate.

You turn by holding the middle mouse button down and moving the cursor away from the center of the simulation window. Moving the cursor left or right causes left or right turns, respectively. Moving the cursor up or down causes the view direction to tilt up or down, respectively. The rate of turning and tilting is scaled by the distance of the cursor from the center of the simulation window; that is, no change of direction occurs when the cursor is at the center and full-speed rotation occurs at the edges of the window.

If you want to maintain a steady velocity rather than accelerating, hold down the middle mouse button to steer while using the left and right buttons to control the speed. To stop, tap the middle mouse button.

#### Trackball

The trackball motion model provides a third option for controlling motion. You can select this mode by pressing the right mouse button on the Fly button and selecting Trackball from the menu.

In trackball mode, when you drag with the middle button, the object rotates about its center as if it were attached to a large trackball that fills the screen. Dragging up and down causes rotation about the horizontal axis parallel to the screen; dragging left and right causes rotation about the vertical axis parallel to the screen.

By dragging with the left mouse, you can translate the object in the direction you drag: left, right, up or down. By dragging with the right mouse, you can translate the object in and out of the screen. In all cases, if you release the mouse button while dragging, the motion continues on its own.

#### Motion Using Paths

There are other approaches to traveling through a scene than the models described here. For instance, you can build a specific path into the viewer to prevent the user from straying outside your model. The path model is supported by a general path-following system in the `libpfutil` library. Many simulation applications require path support for such objects as cars, trucks, and people (in driver-training software); waiting aircraft both on the ground and in the air (in flight simulation); and opposing forces in military trainers. Path support in `libpfutil` allows paths of varying speeds to be built from line segments and arcs with automatic fillet construction between segments for smooth transitions.

### The Use of Instances

The bench objects in the City Hall scene were designed using the database concept known as instancing. For example, a single geometric object such as a tree, house, car, or (in this case) bench, is used multiple times within a database at different locations and with different positions or scale factors. (In this case, the instances have been flattened to improve performance; each bench is now a separate object.) See the OpenGL Performer Programmer's Guide for information on this topic.

## Loading Databases into OpenGL Performer

Databases do not need to be converted to a standard file format before being read to an OpenGL Performer application. Rather, unique file readers are constructed for each format to be used. OpenGL Performer can thus work with data from multiple sources concurrently, using a common software interface, without needing intermediate translation or conversion steps.

The `libpfdb` library is a collection of independent loaders, each of which loads a particular file format into OpenGL Performer. Among the loaders included in the distribution are loaders for Optimizer, Inventor, VRML, OpenFlight, Designer's Workbench, Medit, and Wavefront. Each of the `libpfdb` loaders is located in its own source directory. Users can call the `libpfdu` function pfdLoadFile(), which uses the extension part of the filename to determine the file format and automatically invoke the proper loader from `libpfdb`. For example, to use the visual interface from the Perfly demo with your own databases, simply list your databases after the `perfly` command line. The `perfly` command examines the extension part of each filename to determine what format the file is in and does a run-time system lookup for a loader for that format.

| Note: Many of the database loaders are contributed by companies that are OpenGL Performer developers. In particular, the OpenFlight loader is provided by Multigen, the Designer's Workbench loader is provided by Centric Software, Inc., and the VRML 2.0 loader is provided by OpenWorlds, Inc.

You can write custom loaders for whatever formats you require in your applications.This is not a difficult task, but it does require that you understand most of OpenGL Performer. It should not be undertaken until you have completed reading this book. New loaders can be written and added at any time, and the run-time lookup mechanism can find the new loader when the new file type is encountered. To see the source code for provided loaders and more information on the companies that contributed them, look in the directories under `/usr/share/Performer/src/lib/libpfdb` on IRIX and Linux under `%PFROOT/Src/lib/libpfdb` on Windows systems.

For more information about database formats, see the section “ Geometry Builder Library (libpfdu) ” in Chapter 2.

## Going Beyond Visual Simulation

In the Perfly demo, you can view an object or scene from any angle and location, from points either inside or outside of the scene. This is the part of the visual simulation development task that OpenGL Performer helps you create: the visual part. In other words, what you see when you look out the window.

But there is more to a simulation of reality than just visuals. Purely visual simulations of travel have much the same feel whether the simulation is of a boat, a car, a plane, or a magic carpet. In such simulations there is no nonvisual sensory input at all; the user simply watches scenery move past. OpenGL Performer leaves the nonvisual aspects—the feel of the simulation—up to you. You determine the vehicle dynamics and construct an apparatus or create code to mimic its behavior. You develop a method for manifesting the physical sensation of how your simulation relates to its environment and responds to stimuli.

When you integrate physical aspects of a simulator with the real-time visuals created with OpenGL Performer, the result can be a complete sensory environment, both visual and physical—creating a convincing simulation of reality. Since OpenGL Performer puts the tools for rapid development of real-time visuals into your hands, you can spend more time developing the physical part of the simulation.

Another aspect of OpenGL Performer that lies below the surface of the demos is its ability to accelerate graphics to top-rated performance levels on SGI hardware. This means that OpenGL Performer puts a virtual SGI hardware and software expert at your fingertips, providing all the tools you need to custom-tune your graphics application for maximum performance on your system.

Prev | Table of Contents | Next
Part I. Overview of OpenGL Performer |  | Chapter 2. OpenGL Performer Basics