gDEBugger GL Tutorial

Additional Information

Execution Modes comparison

The following table shows a list of features available in each of gDEBugger's execution modes. gDEBugger's features not mentioned here will work in all execution modes. Features marked "IRR" under one of the modes will work in this mode, but the information they display or commands they contain will be irrelevant in this mode. See also "How do I know which execution mode to use?".

Execution Mode

Feature
Debug Mode Profile Mode Analyze Mode

Execution Speed Medium Fast Slow

Break on Detected Errors YES NO YES

Break on OpenGL Errors YES NO YES

Break on Redundant State Changes NO NO YES

Break on Memory Leaks YES NO YES

OpenGL Function Breakpoints YES NO YES

Performance Counters YES YES IRR

Slow Motion Delay YES NO IRR

Step Commands YES NO YES

Toolbars

Interactive Mode Toolbar YES YES IRR

OpenGL Calls Logging (History Toolbar) YES NO YES

Performance Toolbar YES YES IRR

Raster Mode Toolbar YES YES YES

Viewers

Statistics Viewer YES NO YES

Graphic Memory Analysis Viewer YES NO YES

State Variables Comparison Viewer YES YES YES

Source Code Viewer YES YES YES

Programs And Shaders Editor YES YES YES

Textures and Buffers Viewer YES IRR YES

Views

Calls Stack YES YES YES

OpenGL Calls History YES NO YES

OpenGL State Variables YES YES YES

Performance Dashboard YES YES IRR

Performance Graph YES YES IRR

Process Events YES YES YES

Statistics Viewer

Calls History YES NO YES

Calls Statistics YES NO YES

Function Types Statistics YES NO YES

State Change Statistics NO NO YES

Deprecated Function Statistics PARTIAL NO YES

Vertex Batch Statistics YES IRR YES

Glossary

State Variable: An OpenGL render context is a huge state machine. These state variable values can be changed by using State Change Functions. Note that attempting to change a state variable's value causes the OpenGL pipeline to revalidate which results in performance slowdown.

Redundant State Change: Using a state change function to set the state variable the same value it already has is considered a redundant state change. Note that redudant state changes cause slowdown, but have no effect on the graphic pipeline.

OpenGL Error: An OpenGL error is an error returned by the OpenGL implementation. These errors can be caused by using wrong enumerators, calling functions in times they are irrelevant and so on. Note that to avoid problems, OpenGL implementations usually ignore erroneous function calls, so those calls that cause OpenGL errors should be either fixed or removed.

Detected Error: A detected error is an error detected by the gDEBugger OpenGL server. For example, a detected error will be triggered when using a render context pixel format which is not hardware accelerated.

Graphic Memory Allocated Object: A graphic memory allocated object is an OpenGL object created by a computer program, which consumes graphic memory. An allocated object can reside in the computer's main memory (as part of the driver's used virtual memory), in the graphics hardware's internal memory, or in both. The following allocated object types are currently supported by gDEBugger:

OpenGL render contexts
OpenGL render contexts' static buffers
Texture objectss
Render buffers
Framebuffer objects (FBOs)*
Vertex buffer objects (VBOs)
Shading programs*
Shaders
Display lists**
Pixel buffer objects (PBuffers)*

* - These objects memory consumption is insignificant, but their creation and deletion is still monitored by gDEBugger.
** - Display list memory estimation is currently not supported by gDEBugger.

Graphic Memory Leak: A graphic memory allocated object which is not released by the program that created it is considered a graphic memory leak. Unused graphic memory allocated objects should be released (deleted) as soon as they are no longer needed, to reduce memory consumption and improve overall performance.

Vertex Batch: A vertex batch is a group of vertices sent to the graphic driver with a single API call. In OpenGL, this effectively means the number of vertices sent to the graphic pipeline with a single function call. For example, the function glVertex3f always generates a 1-vertex batch, while glDrawElements creates a batch of size determined by its count parameter value. The number of vertex batches sent to the driver represents the cost of drawing, while the batch size is the benefit of each function call. Drawing 200 1-vertex batches has the same benefit of drawing a single 200-vertex batch, for 200 times the cost. For this reason, it is best to draw as many vertices using as few batches as possible.

Deprecated Function, Deprecated Feature: In OpenGL 3.0, the OpenGL ARB introduced a deprecation for OpenGL. According to this model, certain OpenGL features will be marked as deprecated at certain OpenGL version, and will be entirely removed from OpenGL 3.1 in future versions. There are two types of OpenGL deprecated functions:

Fully deprecated functions are functions that will be removed entirely from OpenGL. For example, the function glVertex3f(), which belongs to the Fixed Pipeline Vertex Processing feature (deprecated at OpenGL 3.0, removed at OpenGL 3.1), should not be exported by OpenGL drivers of version 3.1 onward.
Partially deprecated functions are functions that were not removed from OpenGL, but using them in certain situations or with certain parameters is considered deprecated behavior. The most common example of this is state change functions such as glEnable() and glDisable(), which remain in OpenGL, but have many of their targets removed with different deprecated features. However, some other examples exist, such as glBindTexture, which allowed using a texture with a bind target even if that texture name was not generated by glGenTextures() - this behavior is called "Application Generated Names" - effectively, the call to glBindTexture would create the function.

Using either kind of deprecated function calls (i.e. calling a partially deprecated function in a deprecated manner or calling a fully deprecated function at all) is highly unrecommended, as there is no guarantee the application will behave as expected on machines using newer OpenGL versions.

Function Types: OpenGL functions can be divided into a few groups by their effect on the OpenGL implementation or their result. Note that an OpenGL function can belong to more than one of these groups or to none at all:

Get Functions are functions which retrieve information from the OpenGL driver.
State Change Functions are functions which change the values of OpenGL State Variables.
Draw Functions are functions which may have visible effect on the draw buffer.
Raster Functions are functions that copy pixels from or to frame buffers.
Programs and Shaders Functions are functions related to shaders and shading programs.
Texture Functions are functions that create, delete or manipulate textures.
Matrix Functions are functions related to the matrix stacks (modelview matrix, projection matrix, color matrix etc.).
Name Functions are functions related to OpenGL selection mode.
Query Functions are functions related to OpenGL query items.
Buffer Functions are functions related to OpenGL buffer objects.

To find out what groups does a given function belongs to, look for its entry in the Function Calls Statistics View (In the Statistics Viewer), and the information is displayed under the "Function Type" column. The Statistics Viewer's Function Types Statistics View displays a breakdown of your OpenGL usage by these groups as well as more detailed information about each type.

Forced Mode: All these commands available in the Performance Toolbar Eliminate Draw Commands Eliminate Raster Commands Eliminate Lights Operations Force Stub Textures Force Stub Geometry/Fragment Shaders Force Stub Fragment Shaders are called forced modes. When running in one of the forced modes, the gDEBugger OpenGL server will disable all the commands in the appropriate pipeline stages. Note that forced modes are independant of execution modes and will work in any of them. Also note that some actions taken during the forced mode will be ignored which might cause problems when returning to the normal mode (for example trying to change a Fragment Shader's source code while in Force Stub Fragment Shaders mode will not work, and some uniform locations may change as well). The most common use for forced modes is for locating OpenGL pipeline bottlenecks.

Raster Mode: gDEBugger's Raster Mode Toolbar has three options, which force the raster mode of polygons, like calling glPolygonMode() with GL_POINTS, GL_LINES or GL_FILL respectively. Note that this will override any calls to glPolygonMode the debugged application makes (for example, while in Fill Raster Mode a wireframe setting in your application might not work). The Raster Modes are most useful for viewing the effect of draw functions even if their pixels are not shown due to using the OpenGL depth buffer.

Software Fallback: When the application calls an OpenGL function or establishes a combination of OpenGL states that is not supported or accelerated by the graphics hardware (GPU), the driver runs these functions on the CPU in "software mode". This is called a software fallback. These fallbacks cause a significant decrease in render performance and should be avoided as much as possible. If you are using NVIDIA hardware that supports GLExpert, you can use gDEBugger's integration to locate software fallbacks.

Frame Terminator: Frame terminators are the functions that end your application render frames. gDEBugger uses frame terminators for frame per second, statistics analysis and other measurements, as well as for determining when to stop the execution when you press the Frame Step button. When choosing frame terminators for your project, make sure at least one of the functions you choose is called each frame you render. A typical selection of Frame Terminators is the SwapBuffers option.

Keyboard shortcuts

Main Window

New Project Ctrl+N

Open Project Ctrl+O

Save Project Ctrl+S

Debug Settings Ctrl+D

Go to Next String Marker Ctrl+Shift+N

Go to Previous String Marker Ctrl+Shift+P

Show/Hide Statistics Viewer Ctrl+Shift+S

Show/Hide Memory Analysis Viewer Ctrl+M

Show/Hide State Variables
Comparison Viewer Ctrl+Shift+V

Show/Hide Textures Viewer Ctrl+T

Go F5

Stop Shift+F5

Break F6

Step F11

Draw Step Shift+F11

Frame Step Ctrl+F11

Break on OpenGL Errors Ctrl+E

Add/Remove Breakpoints Ctrl+B

Enable/Disable All Breakpoints Ctrl+Shift+B

In the Shaders' Source Code Editor

Save Ctrl+S

Save as Ctrl+Shift+S

Properties Ctrl+I

Close Ctrl+Q

Toggle Current Fold Ctrl+T

Wrap Ctrl+U

Compile Shader Ctrl+F7

Build Program F7

In the Textures and Buffers Viewer

Save image Ctrl+S

Zoom In +

Zoom Out -

Original Size Alt+0

Toggle Red Channel Alt+R

Toggle Green Channel Alt+G

Toggle Blue Channel Alt+B

Toggle Alpha Channel Alt+A

Rotate Left Ctrl+L

Rotate Right Ctrl+R

* Best viewed with Internet Explorer.

Execution Mode Feature	Debug Mode	Profile Mode	Analyze Mode
Execution Speed	Medium	Fast	Slow
Break on Detected Errors	YES	NO	YES
Break on OpenGL Errors	YES	NO	YES
Break on Redundant State Changes	NO	NO	YES
Break on Memory Leaks	YES	NO	YES
OpenGL Function Breakpoints	YES	NO	YES
Performance Counters	YES	YES	IRR
Slow Motion Delay	YES	NO	IRR
Step Commands	YES	NO	YES
	Toolbars
Interactive Mode Toolbar	YES	YES	IRR
OpenGL Calls Logging (History Toolbar)	YES	NO	YES
Performance Toolbar	YES	YES	IRR
Raster Mode Toolbar	YES	YES	YES
	Viewers
Statistics Viewer	YES	NO	YES
Graphic Memory Analysis Viewer	YES	NO	YES
State Variables Comparison Viewer	YES	YES	YES
Source Code Viewer	YES	YES	YES
Programs And Shaders Editor	YES	YES	YES
Textures and Buffers Viewer	YES	IRR	YES
	Views
Calls Stack	YES	YES	YES
OpenGL Calls History	YES	NO	YES
OpenGL State Variables	YES	YES	YES
Performance Dashboard	YES	YES	IRR
Performance Graph	YES	YES	IRR
Process Events	YES	YES	YES
	Statistics Viewer
Calls History	YES	NO	YES
Calls Statistics	YES	NO	YES
Function Types Statistics	YES	NO	YES
State Change Statistics	NO	NO	YES
Deprecated Function Statistics	PARTIAL	NO	YES
Vertex Batch Statistics	YES	IRR	YES

Main Window
New Project	Ctrl+N
Open Project	Ctrl+O
Save Project	Ctrl+S
Debug Settings	Ctrl+D
Go to Next String Marker	Ctrl+Shift+N
Go to Previous String Marker	Ctrl+Shift+P
Show/Hide Statistics Viewer	Ctrl+Shift+S
Show/Hide Memory Analysis Viewer	Ctrl+M
Show/Hide State Variables Comparison Viewer	Ctrl+Shift+V
Show/Hide Textures Viewer	Ctrl+T
Go	F5
Stop	Shift+F5
Break	F6
Step	F11
Draw Step	Shift+F11
Frame Step	Ctrl+F11
Break on OpenGL Errors	Ctrl+E
Add/Remove Breakpoints	Ctrl+B
Enable/Disable All Breakpoints	Ctrl+Shift+B
In the Shaders' Source Code Editor
Save	Ctrl+S
Save as	Ctrl+Shift+S
Properties	Ctrl+I
Close	Ctrl+Q
Toggle Current Fold	Ctrl+T
Wrap	Ctrl+U
Compile Shader	Ctrl+F7
Build Program	F7
In the Textures and Buffers Viewer
Save image	Ctrl+S
Zoom In	+
Zoom Out	-
Original Size	Alt+0
Toggle Red Channel	Alt+R
Toggle Green Channel	Alt+G
Toggle Blue Channel	Alt+B
Toggle Alpha Channel	Alt+A
Rotate Left	Ctrl+L
Rotate Right	Ctrl+R