gDEBugger GL Tutorial| gDEBugger GL Tutorial |
This section of the tutorial will guide you through your first steps in using gDEBugger.
gDEBugger CL supports the following platforms, for both the i386 (32 bit) and x86_64 (64 bit) architectures:
Windows: go to the Graphic Remedy website, and choose "Download" from the menu on the left hand side.
Click the "download here" link.
After the download has finished, double click the installer (.msi file) and follow its instructions.
Linux: go to the Graphic Remedy website, and choose "Download" then "Linux" from the menu on the left hand side.
Click the "download here" link next the computer configuration you'd like to use (if you are unsure of the right configuration, read the explanation at the bottom of the download page).
After the download has finished, extract the archive to your preferred install location.
Mac: go to the Graphic Remedy website, and choose "Download" then "Mac OS X" from the menu on the left hand side.
Click the "download here" link.
After the download has finished, open the downloaded disk image (.dmg file) and copy all application bundles to your Applications folder.
After installing gDEBugger, if you already have a license, install it following the instructions in the website.
If you don't, gDEBugger will prompt you to acquire a Trial License the first time you run it (requires internet connection).
When you are done installing the license, double-click the gDEBugger icon in the installation directory to start up gDEBugger.
When you start up gDEBugger, you will be presented with the startup dialog. In this dialog, choose "Create new project..." to bring up the Create New Workspace Wizard (If you wish to return to this wizard later, choose New from the gDEBugger File menu).
First select the executable file you wish to debug using gDEBugger, by pressing the browse button. It is recommended to use an executable with debug information (a debug build), unless you want to make performance measurements, in which case you might wish to use a release build for more accurate results.
 |
 |
After choosing the executable, press Next and input the working directory and any application arguments you wish to use in the next two screens.
On the fourth screen, choose the log files and texture dumps directory and press Next again.
 |
In the final screen, specify whether this is an OpenGL or OpenCL project and select at least one of the frame terminators (A typical selection is the SwapBuffers option). You may also choose OpenGL function breakpoints by pressing "Select Breakpoints".
When you have completed inputting your choices, press the "Finish" button to create the gDEBugger project.
 |
All these settings may be later changed in the Debug Settings dialog (find it under the gDEBugger Debug menu, or by pressing Ctrl+D).
After you have created your project, it is recommended that you save it (choose Save in gDEBugger's File menu or press Ctrl+S) so the settings will be kept for the next time you run gDEBugger.
If your program is written using a scripting language (such as Java or Python), choose the runtime environment as the debugged application and add your program (script) as a program argument. Also note that if your application uses a launcher script, it is better to debug the OpenGL script itsself than the launcher, as gDEBugger may not recognize the launched script as belonging to the same application.
To load an existing project, select it from the startup dialog, or choose Open from the gDEBugger file menu.
If you wish to simply experiment with gDEBugger's capabilities, you can open the gDEBugger teapot example from the startup dialog.
To run the debugged application, press the 
Go button (F5). To suspend the execution, press the 
Break button (F6). To terminate the debugged application, press the 
Stop button (Shift+F5).
Please note that most of the information gDEBugger displays is only available when the debugged application execution is suspended.
Also note that when you break the execution, the debugged application will only be suspended at the next OpenGL call (Debug and Analyze Modes) or at the end of the current frame (Profile Mode) and not immediately.
To advance the debugged process execution to a specific point, you should use the step buttons: Press the 
Step button (F11) to advance the debugged process to the next OpenGL call. Press the 
Draw Step button (Shift+F11) to advance to the next OpenGL draw call. Press the 
Frame Step button (Ctrl+F11) to advance to the next frame terminator call.
To break at a specific OpenGL function, you should add it as a breakpoint in the breakpoints dialog (Add/Remove Breakpoints in the Breakpoints menu or Ctrl+B). After adding the function as a breakpoint, press the Go button (F5) and the debugged process execution will break before the next call to the specific function.
gDEBugger has several execution modes which alter the availability of some of its features as well as the debugged application's performance. See "How do I know which execution mode to use?" and "Execution modes comparison".
How do I clean up my OpenGL usage? First, it is best to find and remove all OpenGL errors your application generates. OpenGL error-causing commands are usually not executed and slow down the render performance. This process is explained in this guide's Debug Mode section. After removing those, you might also want to remove detected errors. The Debug Mode section also explains how to locate detected errors. Next, you should find any unrecommended OpenGL functions, and follow the instruction gDEBugger supplies for each one. You can find an explanation on finding these functions and getting alternatives for them under the Debug Mode section. You might also want to remove any software fallbacks from your application. If you are using NVIDIA hardware with GLExpert support, you can follow the instructions presented in the Debug Mode section to locate them. When your application is clean of all problematic function calls, you should try to see if your application has any graphic memory leaks. Follow the instructions in the Debug Mode section to locate any leaking objects in your application. Drawing with small vertex batches uses up many API calls for a small visual effect, so it is a good idea to view vertex batch information as described in the Debug Mode section. If you wish your application to be compatible with future OpenGL versions, you might want to check if your application is using any deprecated functions or features. It is best to look for these deprecations in Analyze Mode, as described in this guide's Analyze Mode section.
How do I find unneeded OpenGL function calls in my code? First, you should see if your code contains any unrecommended OpenGL function calls, and follow the instructions given for each of them. This is explained in this guide's Debug Mode section. While looking at gDEBugger's OpenGL Calls Statistics View (in the Statistics viewer), you might also notice functions which are called an exceptionally high number of times. While this could be normal for draw functions, if these are state change functions, there is a good chance there are redundant calls among them. You should try to have fewer calls in either case. gDEBugger has a mechanism which makes finding redundant state changes much simpler. An explanation of how to do it is found in the Analyze Mode section. For draw functions, you might want to have a look to see how they affect the draw buffers and try to remove calls that have no effect. The Debug Mode section is an explanation on how to view each function's effect on the buffers.
How do I measure my application's performance? The best way to measure your application's performance is to use gDEBugger's performance counters. The Profile Mode Section contains an explanation on how to work with them. For the closest measurements as possible to the real results which will be obtained by your application, it is recommended to use an optimized ("release") build of your application together with gDEBugger's 
Profile Mode. By saving the performance counters' data you can compare the change in various performance metrics to perform regression test (between different versions of your application) or to test your application on different graphics hardware and driver configurations.
How do I optimize my OpenGL application performance? There are two steps to optimizing your OpenGL performance: The first is to locate OpenGL pipeline bottlenecks. The Profile Mode section explains how to do this. Since the OpenGL pipeline always runs as fast as its slowest stage, the second step is to lower the workload on the current bottleneck. Now repeat these steps until you are either satisfied with your current results or until you can not improve the performance any more.
How do I peer inside OpenGL? The OpenGL API is designed to maximize graphic performance and not to make debugging easy. When developers work with OpenGL, they see the graphic system as a "black box": the program issues thousands of API calls into it and "magically" an image comes out of the system. There are many ways gDEBugger can help you transform the debugging task into a "white box" model: gDEBugger can help you view and understand the impact of each draw function on the draw buffers. This is explained under the Debug Mode section. You can use gDEBugger to view OpenGL state variables and changes made to them. The Debug Mode section explains how. If your program uses textures or buffer objects, you can view the detailed information gDEBugger collects about them as also explained in the Debug Mode section. If your application uses shaders and shading programs, their information and source code can be viewed and changed as explained in the Debug Mode section. To get a broader view of your OpenGL usage, you might prefer to view statistical information about it, as the Debug Mode section describes. To view the details of your application's graphic memory consumption, as well as view the calls stack for the creation of any graphic memory allocated objects, follow the explanations in the Debug Mode section. Using all these features together can help you understand better how OpenGL works to create an image from the commands you give it and eliminate the "mystery" behind the works.
How do I know which execution mode to use? For most of the tasks that can be performed using gDEBugger, 
Debug Mode is the best choice of execution mode. Nearly all of gDEBugger's features are enabled in this mode, and while it slightly lowers performance, in most cases it is suitable for debugging the application. Use Profile Mode when you need the closest estimation of actual performance possible. While this mode disables many of gDEBugger's debugging features, the debugged application's performance will usually be better than in Debug Mode. Thus, Profile Mode is best suited for performance measurements and for profiling. Analyze Mode causes significant slowdown on most OpenGL applications, making it unsuitable for most tasks. Use 
Analyze Mode only for its unique features - getting information about OpenGL State change functions usage, detection of redundant state changes and getting in-depth information about deprecated function usage. Because of its "heaviness", Analyze Mode is better used on a per-frame basis, using Frame Step (Ctrl+F11) rather than Go (F5).
To find out if a certain feature is available in one of the execution modes, look at the execution modes comparison table. If you are still unsure of which of the modes suits your needs, try looking at the sections in this guide dedicated to each execution mode, to see if the task you wish to perform is found under one of them.