Setting Up the Environment Variables

There are two locations that require the environment variable:

• Your shell startup file. The name of this file depends on the shell that you use: ~/.login, ~/.cshrc, ~/.bashrc, ~/.profile, and so on. Add the following to the appropriate shell file:

  setenv GL_ENABLE_DEBUG_ATTACH YES

• The OS X environment property list file (~/.MacOSX/environment.plist). The Finder uses this file to set the environment variable when it launches applications. Typically OpenGL Profiler creates this file for you the first time that you launch OpenGL Profiler on a system. The first time you launch the application you should see a dialog that asks whether you want to enable the Attach feature. Click Enable to have the property list file created for you.

  You can skip the rest of this section unless, for some reason, the property list file is missing. If that’s the case, to use the Attach feature you’ll need to create a plain text file, name it environment.plist, and enter the following into the file:

  <?xml version="1.0" encoding="UTF-8"?>

  <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

  <plist version="1.0">

  <dict>

  <key>GL_ENABLE_DEBUG_ATTACH</key>

  <string>YES</string>

  </dict>

  </plist>

  Copy the file to your ~/.MacOSX directory. If the directory does not exist, open Terminal and create the directory from within your shell.

Setting Preferences (Optional)

You can view preferences by choosing OpenGL Profiler > Preferences. You can set the following:

• Frame rate meter interval, which allows you to change the frames-per-second readout from you application. If you need a finer grain of measurement and a more immediate result, you might want to increase this value.

• The function sample interval in the statistics view

• The number of slices to keep in the statistics view. You can limit the number of timing samples that OpenGL Profiler records.

• Trace view font. You can set the font face and the font size.

• Trace data file. You can change the file location and name.

Attaching to a Running Application

To attach OpenGL Profiler to a running application:

1. Select “Attach to application.”

2. In the list that appears, select the application you want to profile.

   

3. Click Attach.

   The status changes from idle to running, and the application list dims. Now that the profiler is attached to the application, you can perform any of the tasks described in the rest of this document.

   OpenGL Profiler begins collecting data as soon as it attaches to your application. Data collection ends when you quit the application or click the Detach button in the OpenGL Profiler window. You can temporarily stop data collection by clicking Suspend.

   Detaching lets the application continue to run, which is useful for applications (like shell tools) that do not have a user interface.

Launching an Application from OpenGL Profiler

To set up OpenGL Profiler to launch an application:

1. Select “Launch application.”

2. Click the plus (+) button and navigate to the application you want to profile, then choose it.

   You can add as many applications as you’d like, but you can profile only one at a time.

3. If your application needs launch arguments, click the Launch Arguments text field and add them.

4. Click the disclosure triangle to view the optional launch settings.

   You can use these settings when you want to profile an application under specific conditions. For example, you can use a custom pixel format, simulate how the application would work using a specific graphics driver, and set additional environment variables. See Customizing Launch Settings for details.

5. Click Launch.

   The status changes from idle to running, and the application and environment variables lists dim.

   OpenGL Profiler begins collecting data as soon as it launches your application. Data collection ends when you quit the application or click the Kill button in the OpenGL Profiler window. You can temporarily stop data collection by clicking Suspend.

Setting a Custom Pixel Format

Select “Use custom pixel format” and click Edit to try out different settings for pixel format attributes. You can quickly see the results of modifying attribute values without changing the source code of the application.

Using a Driver Emulation

OpenGL Profiler contains parameters and values for a variety of OpenGL drivers, not only those available in the system that you are currently running. This feature comes in handy if you want to examine the values that OpenGL returns for a particular driver. Emulation mode does not affect the performance of your application in any way. The purpose of this feature is to help you determine whether code that depends on certain hardware features works properly. Keep in mind that OpenGL Profiler does not replace the drivers your system.

When using a driver emulation, OpenGL Profiler does changes the return values for some of the glGet functions. For example, if you enable the Rage 128 emulator for OS X v10.2 and earlier, calling glGetString(GL_RENDERER) returns "ATi Rage 128 Pro OpenGL Engine" instead of the renderer that’s actually in your system. In addition, any glGet functions that return driver-specific parameters will return the values you’d get if your application ran on the emulated card. For example, calling glGetInteger(GL_MAX_LIGHTS, &maxLights) assigns 8 to maxLights.

To set a specific driver:

1. Choose a driver from the pop-up menu.

   

2. Click View to inspect the parameters and values for the driver.

   

Apple provides a set of driver emulation files. These are property lists that you can edit yourself. You can create an emulation file for a driver not in the list by using a text editor and then saving the file in this directory:

~/Library/OpenGL Profiler/Driver Emulators

You’ll need to restart OpenGL Profiler to see the new file in the driver list.

Setting Environment Variables

You can add environment variables by clicking the plus (+) button. Then enter the variable name and its value. You can add any variable your application reads using getenv(3).

Setting a Working Directory

The working directory refers to your application’s current working directory. It’s the path returned by the function getcwd(3) and the same path that’s automatically prepended to any relative path in your application. If your application does not conform to Apple’s application wrapper scheme, you need to set the working directory so that your application can find resources such as texture maps.

For example, if you launch a nonconforming application from Finder, for this line of code to execute properly:

fopen("mytexture", "r+")

you need to set the working directory to the folder that contains "mytexture".