gDEBugger User Guide

Introduction to gDEBugger

Welcome to gDEBugger – a professional OpenGL debugger and profiler! gDEBugger traces application activity on top of OpenGL to provide application behavior information necessary for finding bugs and optimizing application performance.

With gDEBugger, you can peer inside your OpenGL usage to see the affect individual commands have on application behavior.

There are multiple ways to use the analytic capabilities of gDEBugger - from locating bugs to removing redundant calls and errors to performing regression tests.

Whether your goal is to shorten debugging time, improve application quality or optimize application performance, gDEBugger displays the information you‘re looking for.

© 2004 - 2005 Graphic Remedy. All Rights Reserved.


Toolbars

Debug toolbar

Interactive Mode toolbar

Layout toolbar

OpenGL Calls History toolbar

Performance Analysis toolbar

Raster Mode toolbar

Threads and Contexts Toolbar

Viewers toolbar


Debug toolbar

The Debug Toolbar allows quick access to debug commands such as: Start debugging, Step, Break and Stop debugging.

Go (F5)

Go Start/resume debugging the debugged application with gDEBugger.

Step (F10)

Step Advance the application process to the next OpenGL function call.

Break (F6)

Break Suspend the application process run at the next OpenGL function call.

Stop debugging (Shift-F5)

Stop debugging Stop the debugged session.


Interactive Mode Toolbar

The Interactive Mode Toolbar lets you view your graphic scene as it is being rendered, in full speed or in slow motion mode.

Interactive Mode Toolbar

Interactive Mode Combo Box

Normal Mode The Interactive Mode Combo Box lets you to choose from the following three options:

    • Normal Mode - Disable the interactive mode option.
    • Front Buffer - Force OpenGL to draw into the front color buffer.
    • Front Interactive - Force OpenGL to draw into the front color buffer and execute glFlush after each executed OpenGL command.

Slow Motion Mode Check Box

Slow Motion Checkbox The Slow Motion Mode Check Box enables/disables the slow motion mode.

Slow Motion Spin Control

Slow Motion Delay In the Slow-Motion Spin Control, you choose the unit amount for the slow-motion delay time. The delay will occurs after every OpenGL function execution.


Layout Toolbar

The Layout toolbar allows quick access to saved and predefined gDEBugger views and toolbars layouts.

Predefined Layouts

Default layout - contains all the gDEBugger views and toolbars.
Debugger layout - contains gDEBugger debugging views and toolbars.
Profiler layout - contains the gDEBugger profiling set of views and toolbars.

Saved Layouts

gDEBugger allows you to save the application layouts using the File menu. Use the combo box in the toolbar to choose the saved layout.


OpenGL Calls History Toolbar

The OpenGL Calls History Toolbar lets you access the Calls History Commands.

OpenGL calls history toolbar

Context Combo Box

Context comobox The Context Combo Box allows you to choose the context displayed in the OpenGL Function Calls History view.

Start / stop Recording

Start recording Start / stop recording the OpenGL calls log to a file.
The files are recorded to the directory as defined in the Debug Settings dialog.

Display log file

Display log file Display log file – Open the the active context recorded HTML log file.

Next Marker

Scroll the OpenGL Calls History View to the next string marker function call.

Previous Marker

Scroll the OpenGL Calls History View to the previous string marker function call.

String markers are text messages that can be embedded in the OpenGL calls history log of your application. This is done by using the GL_GREMEDY_string_marker OpenGL extension.

String markers help you make the OpenGL calls history log more readable: you can mark any logical operation / section executed by your application with a marker string.

Example:

glStringMarkerGREMEDY(17, "Setting up lights");

glStringMarkerGREMEDY(20, "Drawing object no 10");

Notice:

The use of the OpenGL extensions mechanism enables you to add, permanently, the string markers code into your source code. This code will be activated only when you run your application with gDEBugger.

Tip:

You can put a breakpoint on the glStringMarkerGREMEDY function. This allows you to break the application run before it starts to execute the next marked logical operation / section.


Performance Analysis Toolbar

The gDEBugger “Performance Analysis” toolbar offers tools that enable you to identify your application’s graphic pipeline bottlenecks.

To identify performance bottlenecks:

  1. Enter the “Profiling Mode“: the profiling mode removes CPU intensive logging operations performed by the gDEBugger OpenGL implementation. Such operations include "Textures Data Logging" and "OpenGL Calls History Logging".
  2. Turn on the “FPS Heads-up Display”: the FPS (Frames per second) Heads-up Display displays the debugged application's rendering performance.
  3. Turn off the graphic pipeline stages one after the other.

If performance improves after turning off a certain stage, you have found a graphic pipeline bottleneck.

Performance Analysis toolbar commands

Performance Analysis Toolbar

Profiling Mode

Profiling Mode The profiling mode removes CPU intensive logging operations performed by the gDEBugger OpenGL implementation. Such operations include "Textures Data Logging" and "OpenGL Calls History Logging".

Save Collected Profiling Graph Data

Save profiling data The Collected Profiling graph data can be saved in a file (.csv) using this button or from the File menu.
Saving the data in a file enables you to run performance and regression tests for your application using different hardware and driver configurations or to compare the performance of two versions of your application.

“Turning off” Graphic Pipeline Stages

The following toolbar commands enables “Turning off” graphic pipeline stages:

Eliminate all Draw Commands

Eliminate all draw commands This command causes the gDEBugger OpenGL implementation to ignore all OpenGL function calls that push primitives or raster data into OpenGL (glVertexXX, glDrawElements, glDrawPixels, etc). When this command is on, the CPU execution and bus transactions are active. However, most GPU actions are inactive since they are activated per primitive/ raster data.
This command helps identify CPU and bus transactions bottlenecks. If when eliminating all draw commands, application performance does not improve significantly, then your application is CPU or bus transactions limited.

Force Single Pixel View Port

Force single pixel view-port This command forces the gDEBugger OpenGL implementation to use a 1X1 pixels view port instead of the application-defined view port.
OpenGL raster operations are triggered per fragment / pixel. Forcing OpenGL to use a single pixel view port removes most the executions performed by raster operations. Consequently, using the “Force Single Pixel View Port” command enables the identification of raster operation related bottlenecks. If when forcing a single pixel view port, application performance improves, then your application is raster operations limited.

Render using no lights

Force No Lights This command forces the gDEBugger OpenGL implementation to render using no lights instead of the application-defined lights. This command enables the identification of lights related computations performance bottlenecks. If when forcing the render using no lights, application performance improves, then your application is lights related computations limited.

Force Stub Textures

Force stub textures This command forces the gDEBugger OpenGL implementation to use a 2X1 (1D), 2X2 (2D), 2X2X2 (3D) and 2X2 x 6 (cube map) textures instead of the application-defined textures. Forcing the use of such small textures guarantees that the textures data constantly remains in the textures memory cache. Texture cache fetch operations occur when the used textures data does not reside in the textures cache and, consequently, must be fetched into it. Using the “Force Stub Textures” command enables the identification of texture cache fetch performance bottlenecks. If when forcing stub textures, application performance improves, then your application is texture data fetch limited.

Force Stub Fragment Shader

Force stub Fragment Shaders This command forces the gDEBugger OpenGL implementation to use a very simple fragment shader instead of the application-defined fragment shader. This command enables the identification of fragment shader related performance bottlenecks. If when forcing the use of a stub fragment shader, application performance improves, then your application is fragment shader limited.

See also:
How Do I Find Performance Bottlenecks?


Raster Mode

gDEBugger User Guide

Raster Mode Toolbar

The Raster Mode Toolbar enables you to force the OpenGL polygon raster mode.

Raster Mode Toolbar

Points

Force points polygon raster mode (GL_POINT).

Wireframe

Force wire polygon raster mode (GL_LINE).

Fill

Force fill polygon raster mode (GL_FILL).


Threads and Contexts Toolbar

The Threads and Contexts Toolbar allows quick navigation between the contexts and threads, gDEBugger viewes will display the relevant thread/context information.

Threads and Contexts Toolbar

Threads Combo Box

Threads comobox The Threads Combo Box allows you to choose the thread to be displayed. The related information will be shown in the gDEBugger views.

Context Combo Box

Context comobox The Context Combo Box allows you to choose the context to be displayed. Related information will be shown in the gDEBugger views.


Viewers Toolbar

The Viewers Toolbar allows quick access to gDEBugger viewers.

Raster Mode Toolbar

Source Code Viewer

Show/Hide the Source Code Viewer.

Shaders Source Code Viewer

Shaders Source Code Viewer Icon Show/Hide the Shaders Source Code Viewer.

Textures Viewer

Show/Hide the Textures Viewer.


Views

Call stack view

OpenGL function Calls history view

Performance Dashboard view

Performance Graph view

Process events view

Properties view

State variables view


Call Stack View

The Call Stack view displays the thread call stack that led to the function call suspending the debugged process run.

Call stack view

The thread call stack is displayed as a list. Each list item represents a stack frame and displays the details of the function call that formed the stack frame.
The items (function calls) are ordered bottom up: a function is placed directly above the function that called it.

Displaying Function Call Properties

Selecting a list item will present the properties it represents in the Properties view.

The details include:

Function name

The name of the selected function.

File path

The source code file path in which this function code resides.

Line number

The line number in the above source code file where a call to the next stack frame function appears.

Module name

The name of the module containing the selected function binary code.

Instruction counter address

The address, in debugged process virtual address space, from which a call to the next stack frame function appears.

Function address

The address, in debugged process virtual address space, in which the selected function binary code starts.

Notice:

The availability of the above fields depends on the type of debug information the debugged process uses. The best results are obtained when debugging a process compiled in debug configuration and generating a .pdb (program database) file.

Displaying Function Call Source Code

Double clicking on a list line opens the Source Code Viewer, presenting the appropriate function call source code. The source code line where a call to the next stack frame function appears is highlighted.


gDEBugger User Guide

OpenGL Function Calls History View

The OpenGL Function Calls History view displays a log of OpenGL, OpenGL extensions and WGL function calls executed in each render context.

OpenGL Calls History view

Function Calls List:

The function calls are displayed as a list, ordered by the time in which they were called.
Each list line represents a single function call and contains: the called function name, its arguments values and the function type (as an icon).

Available Function Type Icons:

- A native OpenGL function
- A WGL function
- An OpenGL extension function
- A function that have an associated texture
- A function that have an associated shader
String Marker - A glStringMarkerGREMEDY function

The Viewed Render Context:

The viewed render context and the amount of functions executed in it are displayed in the list title bar.
By default, the viewed render context is the context of the thread that caused the debugged process suspension.
Use the OpenGL Calls History toolbar Viewed Context combo box to change the viewed context.

“Breaked On” Function

The function call that caused the debugged process suspension is marked using a yellow arrow.
Notice that the process is suspended by gDEBugger before the suspending function is executed. This lets you use Step Forward to observe the effect its execution has on the OpenGL state machine and the rendered image.

Frame Terminators Effect:

When the workspace Debug Settings specifies Frame Terminator functions, every time a Frame Terminator function is executed the render context list in which it was executed is cleared and the function calls count is initialized.

Displaying Function Call Properties

Selecting a list line presents the appropriate function call detailed in the Properties view.

Saving OpenGL Function Calls in a File

You can save the OpenGL function calls in a log file using the Record button.
After pressing the Record button, a log file is created for each active render context. The log file details appear as a debug string process event in the Process Events view. You can pause and resume recording at any given time by pressing the Stop Recording and Record buttons.


gDEBugger User Guide

Performance Dashboard View

The Performance Dashboard view displays performance counters values as continuously changing vertical performance bars. These counters include: gDEBugger, operating system, and vendor specific graphic boards (NVIDIA and 3DLabs currently). For example: CPU/GPU idle, graphic memory consumption, vertex and fragment processors utilizations, number of function calls per frame, frame per second, etc...

Performance Dashboard view
By using the Performance Counters dialog, you can select the displayed counters and bar color.
gDEBugger periodically updates the performance counters sampled values (every 500 milliseconds by default).


gDEBugger User Guide

Performance Graph View

The Performance Graph view contains counters graphs of: gDEBugger, operating system, and vendor specific graphic boards (NVIDIA and 3DLabs currently). For example: CPU/GPU idle, graphic memory consumption, vertex and fragment processors utilizations, number of function calls per frame, frame per second, etc...

Performance Graph view

Graph View:

The Graph view displays counter values as continuous line graphs. You can select the color and line width for each line graph to distinguish it from the other graphs. Data samples are added at the graph's right side, pushing old samples left. Use the Graph view scroll bar to view old data samples that have been pushed out of the current graph view.
gDEBugger queries and reports the performance counters periodically. (Every 500 milliseconds by default). The elapsed time, measured in seconds, from the debugged application launch time is displayed as the scroll bar maximal (right) value.
The performance graph logged data can be saved in a file (.csv) from the Performance Analysis toolbar or from the file menu.

List View:

The List view displays the name, the latest sampled value and the latest scaled value (latest sampled value multiplied by the scale factor) of each performance counter. The font color of the counter name is the same as the line in the Graph view. Selecting a counter highlights the selected graph in the Graph view.
Double clicking on an item opens the Performance Counters dialog where you can add new counters and set the attributes of each counter.
Available Counter Type Icons:

gDEBugger counter - A gDEBugger performance counter.
3Dlabs counter - A 3Dlabs performance counter.
NVIDIA counter - An NVIDIA performance counter.
Win32 Counter - A Win32 performance counter.

Saving Performance Data Counters in a File

The performance data can be saved in a file (.csv) from the Performance Analysis toolbar or from the File menu. Saving performance data in a file enables you to compare performance tests for your application using different hardware and driver configurations or to perform regression tests (compare the performance of two versions of your application).

Performance Tip:

The gDEBugger Performance Analysis toolbar enables you to pinpoint application performance bottlenecks quickly and easily. The toolbar contains commands which allow you to disable stages of the graphics pipeline one by one. These commands include: eliminate all OpenGL draw commands, force single pixel view port, render using no lights, force 2x2 stub textures and force a stub fragment shader. If the performance metrics improves when a certain stage has been turned off, then you have found a graphics pipeline bottleneck!


Process Events View

The Process Events view displays events that occur during the debugged process execution.

Process events view

The debugged process events are displayed as a list, ordered by the time in which they occurred.

The displayed events are:

Process Created

The debugged process was created in the operating system.

Process Run Started

The debugged process run was started.

DLL Loaded

A dynamic linked library was loaded and mapped into the debugged process address space.

DLL Unloaded

A dynamic linked library was unmapped from the debugged process address space.

OpenGL Error

An OpenGL error occurred.

Second Chance Exception

A debugged process thread threw an exception. During the search for structured exception handlers, either no handler was found or the exception was continued. The process is about to exit

Breakpoint Hit

A debugged process thread hit a breakpoint.

Output Debug String

The debugged process sent a debug string to its debugger. This is usually done using the Win32 OutputDebugString function.

Step

The debugged process was advanced to the next OpenGL function call using the Step button.

Break

The debugged process execution was suspended using the Break button.

Displaying Function Call Properties

Selecting a list line presents the appropriate debugged process event detailed in the Properties view.

Foreign Breakpoints

A foreign breakpoint is a breakpoint exception not initiated by gDEBugger. Such breakpoints are usually triggered by calling the Win32 DebugBreak function or calling the assembly command int 3 on Intel CPUs.


Properties View

The Properties view displays detailed information about items appearing in other gDEBugger views.

Example:

Clicking the GL_PROJECTION_MATRIX state variable line in the State Variable view displays the current projection matrix value.


State Variables view

gDEBugger User Guide

OpenGL State Variables View

The OpenGL State Variables view lets you watch OpenGL state variables values.

Adding a State Variable Watch

To add a state variable watch type the state variable OpenGL enumerator name or select it from the Enumerator Names combo box and then press the Add button.

Tip:

Type the first few letters of the enumerator name (example: GL_MOD) and press the down arrow. The combo box opens on the first enumerator name beginning with these letters.

Removing a State Variable Watch

To remove a state variable watch, choose its line and press "DEL".

State Variable Values

The watched state variables values are updated each time the debugged process is suspended. State variable values changed in the last process suspension are highlighted in blue.

Saving State Variable Values

The OpenGL state machine values can be saved to a file using the menu “File” --> “Save state variables” command.

Tip:

A useful debug approach is to compare two saved OpenGL state machine files.

Example:

Your program has a “working scenario” and a “non working” scenario. Break the program execution at appropriate places in the “working” and the “non working” scenarios and save the “working” and “non working” OpenGL state machines in two files. Compare the files to observe the differences in the state machine values.

Saving the Selected State Variables Watches

The selected state variables watches are saved in the workspace file. You can immediately save the variables by executing the “File” --> “Save workspace” command. The workspace is automatically saved when you replace the active workspace or exit gDEBugger.


Viewers

Shaders source code viewer

Source code viewer

State variables comparison viewer

Textures viewer


Shaders Source Code Viewer

The Shaders Source Code Viewer displays a list of shading programs and shaders that exist in each render context.
Displayed in the viewer are each shader's source code and parameters. Also displayed are lists of attached shaders, active uniforms and their values, and program parameters for each program.

Shaders Source Code viewer

Programs and Shaders List

The Programs and Shaders List displays programs, vertex shaders and fragment shaders that exist in each render context. Programs' attached shaders appear right-indented under the program name. The displayed render context can be selected using the "Render Contexts" combo box.

Programs and Shaders Properties View

The Programs and Shaders Properties View, located in the lower left-hand side of the Shaders Source Code Viewer, displays the selected program or shader's properties. Properties include shader or program type, whether it has been successfully compiled or linked and more.

Shaders Source Code View / Active Uniform View

When selecting a shader, the Shaders Source Code View, located in the right-hand side of the Shaders Source Code Viewer, displays the source code of the selected shader.

When selecting a program, the Shader Source Code Viewer is replaced by the Active Uniform View displaying the selected program's active uniforms names, type and values.


Source Code Viewer

The Source Code Viewer displays a call stack frame function source code file.

Source code viewer

Open the Source Code Viewer by double clicking on a stack frame line in the Call Stack view. The stack frame function source code will be loaded and displayed. The line where a call to the next stack frame function appears is highlighted.

Source Code Viewer as Editor

The Source Code Viewer can serve as a source code editor. The user can edit the source code using the available editor commands (Cut, Copy, Paste, Find, etc) and save the results in a file using the “Save” and “Save As” commands.

Printing Source Code Files

Print source code files directly from the Source Code Viewer using the “Print Setup,” “Print Preview” and “Print” commands (“File” menu).


State Variables Comparison Viewer

The State Variables Comparison Viewer allows you to inspect OpenGL state variables values. You can:

  • Save the selected context state variables values to a "state variables snapshot" file.
  • Compare two state variables snapshot files.
  • Compare the selected context state variables values to a snapshot file.
  • Compare the selected context state variables values to the values recorded at the previous debugged process suspension.

State variables comparison viewer

Toolbar commands

Show only differences

Show only differences Show all available state variables or just the variables that their values are not equal.

Go to next difference

Next difference Select the next state variable that its' value is not equal.

Go to previous difference

Previous difference Select the previous state variable that its' value is not equal.

Find

Find Find a string in the state variables list. The search covers both the state variable names and values.

Save state variable snapshot

Save Save a snapshot of the selected context state variable values to a file.


Textures viewer

gDEBugger User Guide

Texture Viewer

The Textures Viewer allows you to view all render contexts texture objects, their parameters and the texture's data as an image.

Allocated Texture Objects List

The Allocated Texture Objects list displays the textures allocated in each OpenGL render context. The displayed render context can be selected using the "Render Contexts" combo box.

Bounded textures and the active texture (the texture whose bind target is enabled) are marked.
Selecting a texture from this list displays its properties and image.

Textures Properties View

The Texture Properties view, located in the lower left hand side of the Textures viewer, displays the selected texture's properties. Properties include the texture type, dimensions, pixel format and more.

Textures Image View

The Texture Image view, located in the right hand side of the Textures viewer, displays a recorded image of the selected texture's current data.

Supported textures are 1D, 2D, 3D and cube map textures. When viewing cube map textures, the 6 cube images are displayed.

Depth Slider

When viewing 3D texture images, you can scroll through the 2D images that built the 3D image using the depth slider located under the Properties view.

All Textures

Pressing All textures in the Allocated Texture Objects list causes the texture image view to display thumbnails of all texture images allocated in the selected render context.

Pressing a texture thumbnail selects the texture and displays its properties and image.

Textures Settings

You can use the Options dialog to enable/disable the texture logging and to define which file type is used.


Dialogs

Add / Remove breakpoints

Add / Remove OpenGL state variable

Debug settings

Options

Performance counters

System information


Add / Remove breakpoints

gDEBugger User Guide

Add/Remove Breakpoints Dialog

The Breakpoint dialog lets you choose OpenGL, WGL and OpenGL extension functions breakpoints.

The debugged process execution is suspended when a debugged process thread calls a function marked as a breakpoint. The process run is suspended before the function is executed, letting you observe the effect the breakpoint function has on the OpenGL state machine and the application behavior.

Add / Remove Breakpoints

Breakpoints

Monitored Functions

The monitored functions list contains OpenGL, WGL and OpenGL extensions functions supported by gDEBugger.

Breakpoints

The Breakpoints list lists the currently selected breakpoints.

Add Breakpoint

To add a breakpoint, select a function / functions from the Monitored Functions list and add it to the Breakpoints list by double clicking on it or by pressing the Add button.

Remove Breakpoint

To remove a breakpoint, select the function from the Breakpoints list and remove it by double clicking on it or by pressing the Remove button.

Remove all Breakpoints

Press the Remove All button to remove all of the breakpoints.

Settings

Break on OpenGL Errors

When this check box is selected, gDEBugger will break whenever an OpenGL Error occurs in the debugged application.

Break on Detected Errors

When this check box is selected, gDEBugger will break the application run when detected error occurs. For example: A detected error will be triggered when the application asks for an extension function pointer from one render context and then uses it in another render context.

Enable Breakpoints

gDEBugger will break on all active breakpoints when "Enable Breakpoints" is chosen.

Tip:

You can find a function easily in the Monitored Function list by putting the curser on the list and typing the first few letters of the function name. The list will scroll automatically to the first function beginning with these letters.


Add / Remove OpenGL state variable

gDEBugger User Guide

Add/Remove State Variables Dialog

The State Variables dialog lets you choose OpenGL, WGL and OpenGL extension state variables.

When the debugged process execution is suspended you will be able to see the selected state variables values in the State Variables view.

Add / Remove State Variables

State variables

Available state variables

The available state variables list contains OpenGL, WGL and OpenGL extensions variables supported by gDEBugger.

State variables

The State variables list lists the currently selected variables.

Add Variable

To add a variable, select a variable / variables from the Available state variables list and add it to the State variables list by double clicking on it or by pressing the Add button.

Remove Variable

To remove a variable, select the variable from the State variables list and remove it by double clicking on it or by pressing the Remove button.

Remove all Variables

Press the Remove All button to remove all of the variables.

Tip:

You can find a state variable easily in the Available state variables list by putting the curser on the list and typing the first few letters of the variable name. The list will scroll automatically to the first variable beginning with these letters.


Add / Remove performance counters

gDEBugger User Guide

Add/Remove Performance Counters

The Performance Counters dialog lets you choose which performance counters are displayed. You can choose from among gDEBugger's, Windows' and vendor-specific graphic boards (NVIDIA and 3DLabs currently).

Add/Remove Performance Counters

Performance Counters

Available Counters

Displays the available counters as a tree. The tree contains gDEBugger, 3Dlabs, NVIDIA and Win32 counters, those supported by gDEBugger.

When the 3Dlabs tree node is empty, either:
a. You are not using supported 3Dlabs hardware.
b. You are not using a 3DLabs supported driver.

  • All 3DLabs Wildcat Realizm hardware is supported. For more information please visit here.
  • 3DLabs Wildcat Realizm drivers version 4.05.0777 or newer are supported.

When the NVIDIA tree node is empty, either:
a. You are not using supported NVIDIA hardware.
b. You are not using the NVIDIA Instrumented driver.
c. The performance counters are not selected in the NVPerfKit.

  • See NVIDIA NVPerfKit documentation for more details.

Available Counters Description

A detailed description of each counter is available under the Available Counters tree when the counter is selected.

Add Performance Counter

To add a counter, select a counter / counters from the Available Counters tree and add it to the Active Counters list by double clicking on it or by pressing the "Add" button.

Remove Performance Counter

To remove a Performance Counter, select the counter from the Active Counters list and remove it by double clicking on it or by pressing the "Remove" button.

Remove all Performance Counters

Press the "Remove All" button to remove all of the Performance Counters.

Counter Settings

Scale

Lets you change the scale factor of the displayed counter. Changing the scale factor enables you to view counter values bigger than 100 in the Performance Graph view. Note: scaling affects the counter graph display but not the counter value.

Selecting "Auto Scale" sets the scale factor on the fly to the lowest appropriate scale, keeping the highest recorded counter value in the [0,100] range. This ensures that all recorded counter values within the Performance Graph view are displayed.

Displayed In

Performance Graph: The counter is displayed in the Performance Graph view.
Dashboard Bars: The counter is displayed in the Performance Dashboard view.
Graph and Dashboard: The counter is displayed in the Performance Graph view and in the Performance Dashboard view.

Color

Lets you choose the counter color of the Line or the bar.

Line Width

Lets you choose the line width in the Performance Graph view.


Debug Settings

gDEBugger User Guide

Debug Settings Dialog

This dialog allows you to specify the properties of the debugged application.

Debug Settings dialog

Arguments

Executable for Debug Session

The full path to the .exe file launched for a debug session.

Working Directory of the Debugged Application

The working directory of the .exe file.

Program Arguments

The debugged application's command line arguments (if there are any).

OpenGL Calls Log Directory

Log Files Directory

A directory where the OpenGL calls log files are saved.

Frame Terminators

Frame terminators are the functions that end your application render frame.
Using them enables you to view the log of a single render frame and not the entire calls log.

glFlush

glFlush is usually chosen by single buffer applications.

wglSwapBuffers

wglSwapBuffers is usually chosen by double buffered applications.


System Information

gDEBugger User Guide

System Information Dialog

The System Information dialog collects computer configuration data and OpenGL implementation details such as: the operating system, memory, graphic card and driver details, monitor details, available pixel formats, available OpenGL extensions, etc.

System View

Collects and displays information about the configuration of your system.

Display View

Collects and displays information about the configuration of your display system.

Graphic Card View

Collects and displays information about the configuration of your graphic accelerator system.

Pixel Format View

Collects and displays information about the supported pixel format on your system.

OpenGL Extension View

Collects and displays information about the supported OpenGL extensions on your system.


gDEBugger Options

gDEBugger User Guide

Options Dialog

The Options dialog lets you control program attributes and behavior.

Call Stack Tab

Textures Tab

Advanced Tab


gDEBugger Options - Call Stack Tab

gDEBugger User Guide

Options - Call Stack Tab

The Call Stack tab lets you specify the source code root location and additional source code directories. This enables the use of the Source Code viewer when the debugged application debug info holds partial source code paths and when the debugged application has been built on a different file system structure than your source code file structure.

Options Dialog - Call Stack Tab

Additional source code directories:

When specifying additional source code directories, If the source code file is not found at its debug information path, it will searched, by file name only, in the additional source code directories. The search is performed according to the order in which the directories are specified.

The additional source code directories are semicolon separated.

Source code root location:

When specifying a source code root location, the root location is prefixed to each source code file path. Only one source code root location can be specified.

Example:
If the source code root is "D:\Dir1\" and the debug information source code path is "\Dir2\Dir3\MyFile.cpp", the Source Code Viewer input path will be "D:\Dir1\Dir2\Dir3\MyFile.cpp".


gDEBugger Options - Textures Tab

gDEBugger User Guide

Options - Textures Tab

The Textures tab lets you control the way the texture data is logged.

Options Dialog - Textures Tab

Enable Texture Data Logging:

When the Enable Texture Data Logging check box is checked, textures data is saved in image files and is displayed in the texture viewer image view.

Textures Data File Format:

You can select the logged texture data file format by choosing the appropriate radio button. Available formats are: jpg, bmp, png, tiff. 3D textures are always stored as tiff images.


gDEBugger Options - Advanced Tab

gDEBugger User Guide

Options - Advanced Tab

The Advanced tab lets you control advanced setting of the gDEBugger applicaiton.

Options Dialog - Textures Tab

Debug log level:

The debug log level is an internal mechanism aimed to help fixing gDEBugger problems. There are three levels for the debug logging:

Error:

Log errors that rise while running gDEBugger.

Info:

Log errors and gDEBugger internal information that rise while running gDEBugger (default logging level).

Debug:

Log gDEBugger debugging information, errors and other internal information that rise while running gDEBugger (to gDEBugger support team locate a problem inside gDEBugger).

Performance counters sample interval:

The number of milliseconds elapsed between performance counters samples.

Flush log file after every OpenGL function call:

When the Flush log file after every OpenGL function call check box is checked, gDEBugger will flush the OpenGL calls history log file after every OpenGL function call instead of not use memory cached batches. This feature can help tracking the function call that led to a debugged application crash. Using this feature slows down dramatically the debugged application performance and therefore it is not recommended to be used regularly.


Wizards

gDEBugger User Guide

Wizard

New workspace wizard


gDEBugger User Guide

New Workspace Wizard

This wizard will guide you step by step in creating a debugged process workspace from scratch.

1. Select the executable file you want to debug.

Select the executable you want to debug

Browse to select the executable file you would like to debug.

2. Select the working directory.

Select the application working directory

Browse to select your application's working directory.

3. Add application arguments.

Add the application arguments

Type the application command line arguments, if any.

4. Select the application frame terminators and breackpoints.

Select the application frame terminators and breackpoints

Frame terminators are the functions ending your application render frame.
Using them enables you to view the log of a single render frame and not the entire calls log.

Pressing the Select Breakpoints button launches the Breakpoints dialog where you can add/remove breakpoints.

5. After completing this wizard, press "Go" (F5) on the gDEBugger toolbar to start debugging the application.

© 2004 - 2005 Graphic Remedy. All Rights Reserved.


Grphic Remedy's Extensions

gDEBugger User Guide

Graphic Remedy's Extensions

gDEBugger Supported Extensions

GL_GREMEDY_string_marker

GRemdeyExtensions.h


GL_GREMEDY_string_marker

Name

GREMEDY_string_marker

Name Strings

GL_GREMEDY_string_marker

Contributors

Dirk Reiners
Yaki Tebeka

Contact

Dirk Reiners, Iowa State University (dreiners 'at' iastate.edu)
Yaki Tebeka, Graphic Remedy (yaki 'at' gremedy.com)

Status

Implemented by gDEBugger (Version 1.2.1)

Version

Last Modified Date: February 1, 2005
Author Revision: 1.2

Number

XX

Dependencies

OpenGL 1.0 is required.

The extension is written against the OpenGL 1.5 Specification.

Overview

This extension defines a mechanism to insert textual markers into
the OpenGL stream.

When debugging or profiling an OpenGL application some of the most
important tools are stream loggers, which just output a list of the
called OpenGL commands, and profilers, which show at which points
the pipeline is bottlenecked for a given part of the frame. The
problem in using these is that there is a definite loss of
information between the application and the used debugger/profiler.
The application generally has a pretty good idea what is rendered
when (e.g. rendering background, landscape, building, players,
particle effects, bullets etc.), but the debugger/profiler only
sees the OpenGL stream. To analyze the stream developers have to
guess what is done when by following the program code and the log
output in parallel, which can get difficult for systems that
restructure their internal pipeline or do lazy changes.

This extension is really only useful for these debuggers and
profilers, and not for actual drivers. In fact, it is not expected
that any standard driver would ever implement this extension. The
main point of having this extension is to allow applications to have a
clean way of accessing this functionality only when they are run
under the control of a debugger/profiler, without having to
recompile or change the application.

IP Status

No known IP claims

Issues

(1) Should the extension use \0-terminated strings to simplify use?

RESOLVED: no.

OpenGL so far doesn't use \0-terminated strings anywhere. Given
that this is primarily a convenience extension it might make sense
to use \0-terminated strings here, though.

However, we expect the actual call to the functions in this
extension to be wrapped by a macro or convenience function anwyay,
which would make it easy enough to calculate the length.

The latest precendent for strings is the ProgramString(), which
defines programs as a list of ubytes with explicit length. We'll
use the same reasoning here and not use \0-terminated strings.

(2) Should it be legal to call this inside Begin/End?

RESOLVED: no.

The benefit is questionable, and it would probably add
overhead to a very critical path.

(3) Should this be supported by GLX?

UNRESOLVED

Not strictly necessary, as most debugging is done locally. It would
be cleaner, but I don't see a case for the effort.

New Procedures and Functions

void StringMarkerGREMEDY(sizei len, const void *string);

New Types

None

New Tokens

None

Additions to Chapter 2 of the OpenGL 1.5 Specification
(OpenGL Operation)

None

Additions to Chapter 3 of the OpenGL 1.5 Specification (Rasterization)

None

Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment
Operations and the Frame Buffer)

None

Additions to Chapter 5 of the OpenGL 1.5 Specification
(Special Functions)

Add section 5.7 on page 212

5.7 Markers

The command

void StringMarkerGREMEDY(sizei len, const void *string);

can be used to insert arbitrary marker strings into the command
stream that can be recorded by appropriate debugging tools / porfiling tools /
drivers. They have no influence on the rendered image or the OpenGL state.
<string> is a pointer to the array of bytes representing the marker being
inserted, which need not be null-terminated. The length of the array is given
by <len>. If <string> is null-terminated, <len> should not include the terminator.

Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State
Requests)

None

Additions to Appendix A of the OpenGL 1.5 Specification (Invariance)

None

Additions to the AGL/EGL/GLX/WGL Specifications

None

GLX Protocol

None

Dependencies on EXT_extension_name

None

Errors

The error INVALID_OPERATION is generated if any of the commands
defined in this extension is executed between the execution of Begin
and the corresponding execution of End.

New State

None

New Implementation Dependent State

None

Sample Code

None

Revision History

1.2, 02/01/05 dr: - Change the extension Status
- Change the name of the extension
1.1, 01/20/05 dr: (Thanks to Yaki Tebeka for suggestions!)
- Switched to programString style
- renamed to marker_string
1.0, 01/17/05 dr: - Initial revision


GRemdeyExtensions.h

gDEBugger User Guide

Graphic Remedy's Extensions

// ------------------------------ gRemdeyExtensions.h ------------------------------

// -----------------------------------------------------------------
// © 2004-2005 Graphic Remedy. All Rights Reserved.
// -----------------------------------------------------------------

#ifndef __GREMDEYEXTENSIONS
#define __GREMDEYEXTENSIONS

#if defined(_WIN32) && !defined(APIENTRY) && !defined(__CYGWIN__) && !defined(__SCITECH_SNAP__)
#define WIN32_LEAN_AND_MEAN 1
#include <windows.h>
#endif

#ifndef APIENTRY
#define APIENTRY
#endif

#ifndef APIENTRYP
#define APIENTRYP APIENTRY *
#endif

#ifndef GLAPI
#define GLAPI extern
#endif

#ifdef __cplusplus
extern "C" {
#endif

#ifndef GL_GREMEDY_string_marker
#define GL_GREMEDY_string_marker 1

#ifdef GL_GLEXT_PROTOTYPES
GLAPI void APIENTRY glStringMarkerGREMEDY(GLsizei len, const GLvoid *string);
#endif

typedef void (APIENTRYP PFNGLSTRINGMARKERGREMEDYPROC) (GLsizei len, const GLvoid *string);

#endif /* GL_GREMEDY_string_marker */

#ifdef __cplusplus
}
#endif

#endif /* __GREMDEYEXTENSIONS */


How do I...

Find if there are OpenGL Errors in my code

Find performance bottlenecks

Track changes of an OpenGL state variable value


gDEBugger User Guide

Find if there are OpenGL Errors in my code

  1. Turn on the "Break on OpenGL Errors" flag in the Breakpoints dialog.
  2. Start debugging. gDEBugger will break whenever an OpenGL Error occurs in the debugged application.


Find performance bottlenecks

Graphic Pipeline Bottlenecks

The graphics system generates images through a pipelined sequence of operations. A pipeline runs only as fast as its slowest stage. The slowest stage is often called the pipeline bottleneck. A single graphic primitive (for example, a triangle) has a single graphic pipeline bottleneck. However, the bottleneck may change when rendering a graphic frame that contains multiple primitives. For example, if the application first renders a group of lines and afterwards a group of lit and shaded triangles, we can expect the bottleneck to change.

The first step in optimizing graphical applications performance is to identify the slowest graphics pipeline stage. gDEBugger provides tools that enable you to identify graphic pipeline bottlenecks.

The OpenGL Pipeline

The OpenGL pipeline is an abstraction of the graphics system pipeline.

GPU pipeline image

Some of the pipeline stages are executed on the CPU; other stages are executed on the GPU. Operations executed on top of the GPU may be executed in parallel.

  • Application – the graphical application, executed on the CPU and calls OpenGL API functions.
  • Driver – the graphics system driver, runs on the CPU and translates OpenGL API calls into actions executed on either the CPU or the GPU.
  • Geometric operations – the operations required to calculate vertices attributes and position within the rendered image 2D space: multiplying vertices by the model view and projection matrices, calculating vertices lighting values, executing vertex shaders, etc.
  • Raster operations – operations operating on fragments / screen pixels: reading and writing color components, reading and writing depth and stencil buffers, performing alpha blending, executing fragment shaders, etc.
  • Frame buffer – a memory area holding the rendered 2D image.

Optimizing Graphical Application Performance

The process for optimizing graphical application performance contains the following stages:

  1. Identifying the bottleneck – finding the graphic pipeline stage that is the current performance bottleneck.
  2. Optimizing – reducing the workload done in the bottleneck stage until performance stops improving or you have achieved the desired performance level.

Steps 1 and 2 should be repeated until the desired performance level is reached.

See also:
 Performance Analysis toolbar
Performance Graph view
Performance Dashboard view


Track changes of an OpenGL state variable value?

gDEBugger User Guide

Track changes of an OpenGL state variable value

There are two options for doing this:

  1. Add the state variable to your OpenGL State Variables view. When the variable's value changes, it is colored blue.
  2. Save two OpenGL state variables snapshots to a file, each from a different execution scenario of your program. Then compare the state variables snapshot files using a diff tool.


FAQ

gDEBugger does not stop on the breakpoints I defined.

What are the "Frame terminators"?

Which OpenGL extensions are supported?

Which OpenGL version is supported?


gDEBugger does not stop on the breakpoints I defined.

Check to see if the Enable Breakpoints checkbox in the Breakpoints dialog (CTRL+B) is checked.


What are the Frame terminators?

Frame terminators are the functions that end your application render frames. Using them enables you to view the log of a single render frame.


Which OpenGL extensions are supported?

Please have a look at our Supported Extensions page.


Which OpenGL version is supported?

gDEBugger currently supports OpenGL version 1.5 standard.


gDEBugger User Guide

Supported Extensions

gDEBugger currently supports OpenGL 1.5 standard and the following extensions:

   GL_ARB_depth_texture
   GL_ARB_occlusion_query
   GL_ARB_shadow
   GL_ARB_shadow_ambient
   GL_ARB_texture_border_clamp
   GL_ARB_texture_compression
   GL_ARB_texture_compression
   GL_ARB_texture_cube_map
   GL_ARB_texture_cube_map
   GL_ARB_texture_env_add
   GL_ARB_texture_env_combine
   GL_ARB_texture_env_crossbar
   GL_ARB_texture_env_dot3
   GL_ARB_texture_mirrored_repeat
   GL_ARB_texture_non_power_of_two
   GL_ARB_vertex_blend
   GL_ARB_vertex_buffer_object
   GL_EXT_bgra
   GL_EXT_blend_logic_op
   GL_EXT_blend_minmax
   GL_EXT_blend_subtract
   GL_EXT_packed_pixels
   GL_EXT_texture
   GL_EXT_texture3D
   GL_GREMEDY_string_marker
   GL_HP_occlusion_test
   GL_NV_occlusion_query
   GL_NV_primitive_restart
   GL_NV_texgen_reflection
   GL_SGIS_generate_mipmap
   GL_SGIS_texture_border_clamp
   GL_SGIS_texture_edge_clamp
   GL_SGIS_texture_lod
   GL_SGIS_texture_select
   GL_SGIX_depth_texture
   GL_SGIX_interlace
   GL_SGIX_shadow
   GL_SGIX_shadow_ambient
   WGL_I3D_genlock

If you use or plan on using an extension not currently supported by gDEBugger, send an email to the gDEBugger Support Team. Your extension support will receive higher priority.


gDEBugger User Guide

System Requirements & Installation

Minimum System Requirements to Run gDEBugger:

  • Minimal hardware requirements:
    Pentium 500 Mhz, 64 Mb RAM
  • Operating systems:
    Windows 2000 Professional + Service Pack 2 or higher
    Windows XP Professional + Service Pack 1 or higher

To install gDEBugger:

  • Make sure the hardware and software requirements are fulfilled.
  • Uninstall any previous versions of gDEBugger you may have installed on your computer.
  • Install gDEBugger by double clicking on the downloaded package and follow the installation wizard.


gDEBugger User Guide

Legal Information

Graphic Remedy disclaims all warranties and liabilities for the use of this document and the information contained herein, and assumes no responsibility for any errors which may appear in this document. Graphic Remedy makes no commitment to update the information contained herein, and may make changes at any time without notice.

This software uses the FreeImage open source image library. See http://freeimage.sourceforge.net for details.
FreeImage is used under the FIPL, version 1.0.


Contact Information

gDEBugger User Guide

Graphic Remedy Contact Information

Technical Issues

  • Search the F.A.Q page for your question.

  • Search the gDEBugger Technical Support Forum for your question.

  • Send us an email to support@gremedy.com

Other Issues

  • For sales: sales@gremedy.com
  • For all other queries: info@gremedy.com
  • Fax: +44.20.8497.1071
  • Web page www.gremedy.com