gDEBugger GL Tutorial| gDEBugger GL Tutorial |
Debug Mode enables most of gDEBugger's features, allowing a great range of tasks.
This is gDEBugger GL's default layout for 
Debug Mode. Move your mouse over the screenshot to display the different views' names.
|
|
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Locate OpenGL Errors: To locate OpenGL errors, enable "Break on OpenGL Error" under the gDEBugger Breakpoints menu (or by pressing Ctrl+E). Then, run the application using the 
Run button or F5. If your application generates OpenGL errors, its execution will break automatically, and the last line in the Debugged Process Events View will display "OpenGL error", as well as details about the function call which caused the error. Click on this line to make the Properties View display details about the error. You can also look at the Calls Stack View to locate the source code which led to the problem. If your program has debug information, you may also double-click the Calls Stack View lines to show the appropriate code line in the 
Source Code Viewer.
Locate Detected Errors: To locate detected errors, choose the "Break on Detected Error" option in the Breakpoints menu, then repeat the process described above for "Locate OpenGL Errors".
View Graphic Memory Information: All of the graphic memory information collected by gDEBugger is displayed in the 
Graphic Memory Analysis Viewer (Ctrl+M). In this viewer, you can find a tree representing all of the debugged application's graphic memory allocated objects sorted by their render context. You can also view a list of all the objects of a given type (for example, context 1's textures), with further information relating to their memory consumption depending on the kind of objects listed. The graph view shows a breakdown of all the graphic memory consumed by the items in the current category. The properties view will display information on the selected object. To see the scenario that led to an object's creation, use the Creation Calls Stack view. If the debugged application has debug information, double-clicking on a line in the Creation Calls Stack view will open the Source Code Viewer highlighting the appropriate line in the source code.
Locate Graphic Memory Leaks: gDEBugger automatically checks for graphic memory leaks and will display an indication in the Debugged Process Events view when these checks are performed and when memory leaks are detected. To make gDEBugger break the debugged application run whenever a graphic memory leak is detected, enable gDEBugger's "Break on Memory Leaks" option in the breakpoints menu or at the bottom of the Graphic Memory Analysis viewer.
Since gDEBugger can not understand the logic behind the debugged application's operation, it can only report a memory leak when it detects a graphic memory allocated object which can no longer be accessed by the debugged application. This situation can be created when an OpenGL render context is deleted or when the debugged process exits (and is terminated normally). When a graphic memory leak is detected, gDEBugger will open the Graphic Memory Analysis viewer, and any memory leaks will be displayed with the 
memory leak warning icon. In addition, the viewer's Properties view will display the leaking objects' types and total memory size as well as a short explanation about the specific sort of memory leak that was detected. Note that if you are using render contexts data sharing (wglShareLists, glXCreateContext with the ShareLists parameter, etc.), some of the allocated objects may be under a different OpenGL render context than the one currently being deleted.
It is also recommended to periodically break the debugged application run and use the Graphic Memory Analysis viewer to search for graphic memory allocated objects that are no longer used (keeping in mind the application's logic) and that were mistakenly not deleted by the debugged application.
The leaking objects' creation stacks will display the scenario that led to their creation, allowing you to fix the debugged application so it will properly delete them when they are no longer needed. To make the most of this feature, build the debugged application to contain debug information.
When deleting an OpenGL render context, it is recommended to first delete all of its graphic memory allocated objects. In addition, specific allocated objects which are not held by a render context (such as PBuffers or the render contexts themselves) should be deleted before terminating the OpenGL application. Doing this is considered good practice and will also enable gDEBugger to detect graphic memory allocated objects that are not recognized by the debugged application and report them as graphic memory leaks.
View the Effect of OpenGL Function Calls on Draw Buffers (Draw Functions): Change the Interactive Mode Combobox value to "Front interactive". This forces the debugged application to draw directly to the front buffer rather than the back buffer. Then, using the 
Draw Step command (Shift+F11), you can view draw function calls' effect on OpenGL draw buffers as the scene is being rendered. If an object obscures your view, try using the 
Raster Mode Toolbar to force rastering by wireframe or points. An alternative to using Front interactive mode is to view buffers' contents in gDEBugger's 
Textures and Buffers viewer.
Find Unrecommended Function Calls: Open gDEBugger's 
Statistics Viewer (Ctrl+Shift+S). In the "Function Calls Statistics" tab, you might notice warning icons next to some of the function names. Click any of these functions to display an explanation of why is it unrecommended and offer an alternative to using it. If you wish to ignore OpenGL initialization functions and only view the information for functions called during frame rendering, you can click the "Clear Statistics" button after the initializations are done and run the application for a few more frames before looking at the Function Calls Statistics.
View Textures and Buffers Information: All of the textures and buffers information collected by gDEBugger is displayed in the Textures and Buffers Viewer (Ctrl+T). Using the Textures List and Buffer List, you can select the texture or buffer you wish to view information for. Selecting a texture or buffer will display it in the Image View. Further information can be seen in the Properties pane. Clicking on a pixel will sample it and keep its information in the "Last Pixel" entry in the Information Panel. Using the toolbar above the image view, you can disable some or all the channels and zoom in and out on the image. You can also invert the image's colors, convert it to grayscale and rotate it. The Data View, shown as a second tab gives you the numerical values of each pixel instead of painting the image on screen.
View Shaders and Shading Programs' Information and Edit Shaders "On the Fly": All the Shaders and Shading Programs information collected by gDEBugger is displayed in the 
Shaders' Source Code Editor. Choose a Program from the list to display its properties in the Properties pane, and its currently active uniforms in the main window. If you choose a Shader from the list, its properties will be displayed in the properties window, while its source code will be shown in the main window. You can edit the shader's source code in this view to immediately see the results and performance impact of such changes. After editing the shader's source code, you will need to build the associated shading program (F7). You can view the Compile, Link and Validate log in the window that pops up. Resume the process run ( Go or F5) to view the results immediately. Note that after manually editing the shader, any changes made to it which are generated by the application (such as adding new source code to the shader) will be ignored.
Work with OpenGL State Variables: If you wish to view the value of an OpenGL State variable at any time, double-click any item in the OpenGL State Variables View and find the desired state variable in the available state variables list. Press the Add button (or double-click it in the list) to add it to the watched state variables list. You can remove unwanted items from this list by pressing the Remove button or double-clicking on them. After adding all the state variables you wish to view, press OK to confirm your changes. The OpenGL State Variables View will now display the state variables' values. If you want a more general overview of all OpenGL State Variables, open the 
State Variables Comparison Viewer (Ctrl+Shift+V). Here you can see the current values of all OpenGL state variables. You may also choose to compare the current state variable values to the OpenGL defaults, to the last debug break or to a saved state variables snapshot file. These features are useful when something works in one part of your application but not in others seeing what OpenGL state variables are different between the two parts might help finding the source of the problem.
Work with Breakpoints: Any gDEBugger-supported OpenGL function can be set as a breakpoint in the Breakpoints dialog. Open "Add/Remove Breakpoints" from gDEBugger's Breakpoints menu (CTRL+B). The monitored functions list contains all the supported OpenGL functions. The breakpoints list contains all the currently selected function breakpoints. Each selected breakpoint has a checkbox next to it, representing whether the breakpoint is currently enabled or not. Disabling breakpoints instead of removing them saves the time of finding the function each time you want to enable the breakpoint. To add a function to the breakpoints list, select it in the monitored functions list and press Add or double-click it. To remove a breakpoint, select it in the breakpoints list and press Remove or double click it. Below the breakpoints list, you will find other (non-function) breakpoints, such as break on OpenGL errors, and the option to enable or disable all function breakpoints (this can also be done directly from the breakpoints menu or by pressing Ctrl+Shift+B). Using breakpoints can help you see the exact OpenGL status before the function is called, also allowing a comparison of the status before and after the function call (by pressing the 
Step button or F11 after the breakpoint hit). You can also use breakpoints to find where in your code each function is called, by looking at the Calls Stack View after the breakpoint is hit (If you have debug information for the stack item, you can even double-click it to see the exact location in the Source Code Viewer).
View Statistical Information about OpenGL Usage: Open gDEBugger's Statistics Viewer (Ctrl+Shift+S). The best way to overview your application's OpenGL usage is to collect the statistics for a few complete frames. First, let your application start up by pressing Go (F5). After the application has loaded and rendered a few frames, 
Break the execution (F6). Press the 
Frame Step button (Ctrl+F11) once to advance to the end of the current frame. Then, in the Statistics Viewer, press the Clear Statistics button. After clearing the Statistics, press the Frame Step button a few more times to allow the application to draw a number of complete frames. Now, you will have the clearest statistical information about your OpenGL usage.
In the Function Types Statistics tab, you can see a breakdown of your OpenGL usage by function types. The percentages here do not always add up to 100% as an OpenGL function can belong to many or none of the categories. In the Function Calls Statistics tab, you can see a breakdown to specific OpenGL functions, including the function types each function belongs to. In the Vertex Batch Statistics tab, you can see a breakdown of your application's vertex batches by size, giving an overview of the vertex sizes and occurance and the total number of vertices drawn with each batch size. See also "View State Changes Statistics" in this Guide's Analyze Mode section.
Locate Software Fallbacks: To find software fallbacks, use gDEBugger Mac's "Break on Software Fallbacks" feature (found in the Breakpoints menu and Add / Remove Breakpoints dialog).
On other platforms, to locate software fallbacks, open gDEBugger's GLExpert Settings Dialog* (in the Breakpoints menu). In this dialog, make sure "Enable GLExpert Integration" is checked. Under "Report messages from" choose any pipeline stages or object types you wish to receive reports from (it is usually best to leave all of these items checked). Under "Message Detail" clear all the boxes except "Software Fallback". Then choose "Break on GLExpert Reports" (this option can also be accessed directly from the Breakpoints menu). After making these settings, run the application using the Go button (F5). If your application causes any software fallbacks, its execution will break automatically, and the last line in the Debugged Process Events View will display "GLExpert Report", as well as details about the reason why the fallback occurred. Click on this line to make the Properties View display details about the fallback. You can also find the code that led to the software fallback by looking at the Calls Stack View (If you have debug information for the stack item, you can even double-click it to see the exact location in the Source Code Viewer).
* Note: NVIDIA hardware with GLExpert driver support is required for using this feature.