gDEBugger Explorer tree view
Function Calls History view
Debugged Process Events view
Call Stack view
OpenCL Multi-Watch views
OpenGL State Variables view
The Home page provides quick access to common start tasks
Click “Create New Project” to show the New Project wizard.
Click “Open a Project” to load a previously saved project file.
Click “Load the Teapot Sample” to load a sample project debugging the gDEBugger Teapot sample application.
Click a recent project’s name to load it.
Click the documentation links to access gDEBugger’s documentation and website.
The gDEBugger Explorer tree view displays and allows navigation and access to all OpenCL and OpenGL objects during application run.
OpenCL / OpenGL Objects Tree
The Objects tree displays all the debugged application’s allocated objects, by a hierarchy of Application –> Context –> (Object Type) –> (Specific Object). Contexts marked with the sharing icon have their memory allocated objects shared by at least one other context (see the documentation of cl_khr_gl_sharing and wglShareLists, for more details about context resource sharing). Note that sharing contexts can result in objects having non-zero memory sizes even after being deleted, as long as at least one other context sharing their objects exists.
Back / Forward buttons
Use these buttons to navigate to the previously viewed objects in the tree.
Function Calls History View
The Function Calls History view displays a log of OpenCL, OpenGL, OpenGL extensions and WGL function calls executed in each context.
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).
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 context is the context of the function that caused the debugged process suspension.
Use the gDEBugger Explorer tree view to change the displayed context.
“Breaked On” Function:
The function call that caused the debugged process suspension is marked using a yellow arrow.
Note that the process is suspended by gDEBugger before the suspending function is executed. This lets you use the Step (F10) command to observe the effect its execution has on the OpenGL state machine and the rendered image.
Frame Terminators Effect:
When the Debug Settings dialog specifies Frame Terminator functions, every time a Frame Terminator function is executed the context list in which it was executed is cleared and the function calls count is reset to 0.
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 OpenCL / OpenGL function calls history in an HTML log file using the Record button.
After pressing the Record button, a log file is created for each active context. This log file will contain the details of each API function call, program and shader sources and image files for image and texture objects (if enabled in the Options dialog). To stop recording, press the record button again. To view the log file gathered so far, press the Open Current HTML Log File button.
Calls History toolbar
Use the record button on the toolbar at the top of the view to record the API calls log in all the OpenCL and OpenGL contexts (as well as “No context” function calls) to HTML files.
Select a context in the gDEBugger explorer and press the view HTML log button to Open the log file gathered so far.
Use the “Previous marker” and “Next marker” buttons to jump between glStringMarkerGREMEDY calls in the calls log for the current OpenGL context.
The Properties view displays detailed information about items appearing in other gDEBugger views.
Clicking an OpenCL Context in the gDEBugger Explorer tree will display its details.
The Breakpoints view displays all the currently selected breakpoints.
Double-click the breakpoints view to open the Breakpoints dialog, allowing selection of new breakpoints.
Enabling / Disabling breakpoints:
Click the checkbox next to a breakpoint to enable or disable it.
Select a breakpoint, right-click, and select “Delete” form the context menu to remove it.
Debugged Process Events View
The Debugged Process Events view displays events that occur during the debugged process execution.
The events are displayed in a list, starting from the earliest to the latest. The view is reset when a new debug session is initialized.
Displaying Event Properties:
Selecting a list line presents the appropriate debugged process event detailed in the Properties view.
Call Stack View
The Call Stack view displays the call stack for the location where the debugged process is currently suspended. During kernel debugging, the kernel call stack is added on top of the kernel debugging control thread’s call stack.
The 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 and Line number
- The source code file path and line number for this call stack frame.
- Module name
- The name of the module containing the selected frame address.
- 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.
The availability of the fields depends on the type of debug information the debugged process uses. The best results are obtained when debugging a process compiled in unoptimized debug configuration. In Windows, program database (.pdb) format is preferred.
Displaying Frame Source Code:
Double clicking on a list line opens the source file. The source code line where a call to the next stack frame function appears is highlighted.
During kernel debugging, the Locals view displays all the variables in the current OpenCL function’s scope.
To expand a vector / struct / union variable’s members, click the plus / arrow icon next to the variable name.
During kernel debugging, the Watch view displays the values of selected watch variables.
To expand a vector / struct / union variable’s members, click the plus / arrow icon next to the variable name.
Select the “Click to add a watch expressions” line and type in the variable name to watch it.
You can also dereference a pointer variable (“a”, “*p”) or watch specific members of a variable (“v.s0”).
Right-click a watched expressions and select “OpenCL Multi-Watch” to view it in the Multi-Watch views.
OpenCL Multi-Watch Views
The OpenCL Multi-Watch views allow you to compare the values of an OpenCL Kernel variable across the various work items and work groups.
The Multi-Watch main window displays either a graphical (image view) or spreadsheet (data view) visualization of the selected kernel variable across the various work items and work groups. This view operates very similarly to the Object views.
Variable Name Combobox
Select a variable name from the list or type a watch expression. If the expression can be parse and evaluated, the values will be updated in the main view.
Kernel Work Geometry and Selected / Hovered details
Displays the kernel work geometry (local and global work size and offset) for the current N-Dimensional kernel execution, and the location and value of the selected and hovered variable work items.
Value range slider
Shows the value range, and allows marking the valid value range. Values above and below these lines will be colored to show they are not in the selected range.
OpenGL State Variables View
The OpenGL State Variables View.
Adding a State Variable Watch:
To add a state variable to the watch view double click on the “Add State Variable…” item in the list and select the OpenGL Enumerator Name from the State Variables dialog.
Removing a State Variable Watch:
To remove a state variable watch, choose its line and press “DEL” or by right-clicking on the line in the State Variables view and select the “Remove Selected” command.
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.
Exporting OpenGL State Variable Values to a File:
The OpenGL state machine variables and values can be exported to a file (.txt) using the menu “File” –> “Export Images and Data” –> “State Variables Snapshot” command or by right-clicking on the State Variables view and selecting the “Export State Variables Snapshot” command.
Saving the Selected State Variables Watches:
The selected state variables watches are saved in the project file. You can immediately save the variables by executing the “File” –> “Save Project” command. The project is automatically saved when you replace the active project or exit gDEBugger.
gDEBugger Memory View
The gDEBugger Memory view allows you to view information about your graphic memory consumption and usage as well as detected graphic memory leaks.
Graphic Object Details View
The Graphic Object Details view lists all the graphic memory allocated objects of the selected type in the appropriate context (for example, Context 1’s textures). The columns in the list vary depending on the selected item type, displaying information relevant to the current items’ memory size.
Object Creation Calls Stack View
This view displays the calls stack when the currently selected item was created. Select a stack frame to view its information. If your application has the appropriate debug information and source code, double-clicking a stack frame will open up the source file, highlighting the appropriate line.
This view contains a breakdown of the graphic memory consumed by the objects displayed in the Graphic Objects Details view.
gDEBugger Statistics View
The Statistics view allows you to view statistical information about your OpenCL and OpenGL APIs usage.
Select an OpenCL or OpenGL context in the gDEBugger Explorer to update the statistics to that context’s information.
This view, located in the lower left hand side of the Statistics view, contains a graphical representation of the information in the Function Types, Function Calls Statistics, State Change Statistics, Deprecated Function Statistics and Vertex Batch Statistics views.
The Properties view, located in the lower right hand side of the Statistics view, displays the selected object properties. The properties include information about the object as well as an explanation of any warnings (represented by exclamation point icons next to the items).
Function Types Statistics View
The Function Types Statistics view displays a breakdown of OpenCL / OpenGL function calls to categories. Note that a function can belong to multiple or none of the categories. If you wish to know which categories does a function belong to, find it in the Function Calls Statistics view
When in the Function Types Statistics view, the Statistics view Graph view will display a bar graph decipting the part each function type takes. The grid lines represent 25, 50 and 75 percent of all function calls. Selecting a function type in the list will highlight it in the graph. Redundant State Change functions (when available) and Get functions are marked in red and orange respectively.
When in the Function Types Statistics view, the Statistics view Properties view will show informaion about the currently selected function type.
Function Calls Statistics View
The Function Calls Statistics view allows viewing the number of times each OpenCL / OpenGL function call was executed in the previously rendered frame and it’s percentage from the total functions execution.
The functions below are divided and listed by their enumerators to provide more precise information.
Exporting Function Calls Statistics Data into a file:
The Function Calls Statistics data can be exported to a file (.csv) using the right-click context menu “Export Function Calls Statistics” command.
Exporting the function calls statistics data can help you compare the function calls statistics of different frames. It also allows you to perform regression tests by comparing the function calls statistics data of two versions of your application.
The Usage of certain OpenCL and OpenGL functions is unrecommended, mostly for performance taxing reasons. These functions are noted as such in this view in varying degrees – mildly unrecommended (yellow warning sign), intermediately unrecommended (orange warning sign) and highly unrecommended (red warning sign). Click on an unrecommended function to display information about it and a better alternative to using it in the Properties view.
When in the Function Calls Statistics view, the Statistics view Graph view will display a pie chart of the OpenCL / OpenGL function calls. Each pie “slice” is one API function (or in some cases, a combination of an OpenGL function and enumerator). Selecting a function or functions in the list causes their respective slice in the graph to be highlighted. The graph can be rotated by clicking on it and dragging.
When in the Function Calls Statistics view, the Statistics view Properties view will display the function name. If the function is an unrecommended one, the Properties view will also display an explanation of why using this function is unrecommended, as well as a recommendation for an alternative to using this function.
State Change Statistics View
The State Change Statistics view, only available in Analyze Mode, displays a statistics breakdown of the usage of OpenGL state change functions – how many times was each function called, and how many of those times was the call effective.
State Change Fucntions
Each of the lines in the list displays the usage of one OpenGL State Change function (or in some cases, a combination of an OpenGL State Change Function and enumerator). The total amount of calls to this function, how many of them were effective and redundant and the percentage of the calls which were redundant are also displayed.
If a function has some percentage, a high percentage or a very high percentage of redundant calls, a warning icon (yellow, orange or red, respectively) will be displayed next to the function name.
When in the State Change Statistics view, the Statistics view Graph view displays a pie chart representing all of the OpenGL State Change function calls. The blue pie slice represents effective state changes, while the red slice represent redundant state changes. Selecting a function or functions in the list causes their part in the chart to be highlighted (both in the redundant and effective slices). The graph can be rotated by clicking on it and dragging.
When in the State Change Statistics view, the Statistics view Properties view displays the currently selected state change function’s name, as well as information about the percentage of calls to this function which are redundant and a general explanation of redundant state changes.
Deprecated Function Statistics View
The Deprecated Function Statistics view displays information about your usage of functions deprecated by any OpenCL or OpenGL version. After running the debugged application in Analyze Mode, this view also displays information about usage of deprecated features in partially deprecated functions.
Each of the lines in the list displays the usage of one Deprecated function or a combination of a partially deprecated function and a deprecated feature. The number of calls to this function or deprecated uses of this function and feature combination is displayed (as well as a percentage of the total API function calls). Finally, the OpenCL / OpenGL version when this feature was deprecated and the version it was removed (if any) are displayed.
When in the Deprecated Function Statistics view, the Statistics view Graph view displays a pie chart, representing a breakdown of the deprecated function calls per combination of deprecated function and deprecated feature.
When in the Deprecated Function Statistics view, the Statistics view Properties view displays the currently selected deprecated function’s name, as well as information about the deprecated feature it is a part of, and other functions and behaviors belonging to the same deprecated feature. A forward-compatible alternative to this feature is supplied in bold font.
Function Calls History View
This view is identical to the gDEBugger Function Calls History view.
Vertex Batch Statistics View
The Vertex Batch Statistics view displays information about your usage of OpenGL vertex drawing functions or vertex batches, divided by the batch size (i.e. how many vertices were drawn with a single OpenGL function call).
Each of the lines in the view displays statistics for a range of vertex batch sizes (normal view) or a specific batch size (detailed view). The number and percentage of batches of this size represents the “cost” of drawing with this batch size. The number and percentage of vertices represent the “benefit” gained from drawing with this batch size. Batches which are small in relation to the application (have a higher percentage of batches than is expected from their percentage of vertices) are noted with a warning icon.
Show Detailed Batch Statistics
Toggles between the Vertex Batch Statistics view’s normal (gather batch sizes into ranges by amount) and detailed (show each vertex batch size separately) views.
When in the Vertex Batch Statistics view, the Statistics view Graph view displays a bar chart, in which each bar is a range of batch sizes. The height of the bar is the number of batches drawn in this range, and the bar’s color represents the range’s position in the application’s distribution (Red bars are the smallest batches and green bars are the largest ones). The grid lines represent 25, 50 and 75 percents of vertex drawing function calls.
When the Vertex Batch Statistics shows the detailed view, this graph becomes a histogram of the vertex batch sizes.
When in the Vertex Batch Statistics view, the Statistics view Properties view displays the currently selected batch size range, the percentage statistics for this range and a short explanation about vertex batches.
The Object views – Image view and Data view – allow you to view all OpenCL buffers and images, and OpenGL textures, static buffers, VBOs (vertex buffer objects), FBOs (frame buffer objects), render buffers and pbuffers (pixel buffers).
Each object can be viewed both as an image in the Image view (except OpenCL Buffers and OpenGL VBOs) and as a spreadsheet containing the object raw data in the Data view. The object properties and parameters will appear in the properties view.
The information panel helps you make fast inqueries and adjustements to the currently viewed object pixels/texels.
The information panel is composed of a few main elements (which are only shown when relevant):
Current and previous pixel
When hovering with the mouse over the Image view, the currently highlighted pixel data is displayed as the current pixel; Both RGBA values and raw data value are displayed.
If you wish to compare between two different pixels, you can save a specific pixel value by clicking on it with the left mouse button. The pixel data will be stored as the “Selected Pixel”, allowing you to make fast comparison to another pixel.
Single channel range adjustment slider
When viewing an object that has a single component data format (“Depth” / “Luminance” / “Intensity” / etc.) the image view translates these values to grayscale values. Use the single channel range adjustment slider to adjust the data translation to grayscale values.
3D layer slider
When viewing 3D images or textures, you can scroll through the 2D images that make up the 3D image using the 3D layer slider located in the information panel.
Texture array layer slider
When viewing texture arrays, you can scroll through the textures that make up the array using the Texture array layer slider located in the information panel.
Texture mipmap slider
When viewing a texture which has automatic or manual mipmaps defined, you can scroll through the different texture levels using the Mipmap slider located inside the information panel.
OpenCL buffer / OpenGL VBO format controls
When viewing an OpenCL buffer or an OpenGL VBO, the information panel will contain several items that allow choosing how the VBO data is displayed:
- Data combobox – choose which kind of data the buffer contains. Each option in this combobox matches either the OpenCL C types or an OpenGL gl*Pointer function (“Interleaved” matches glInterleavedArrays). Choose “All” to display all formats.
An exception to this is the “Index” option which also matches the glDrawElements (and variants) function’s indices parameter and not only glIndexPointer.
- Format combobox – choose the format the data is stored in, matching the OpenCL C type the kernel uses (__global XXXX*) size and type parameters of the gl*Pointer function or the format parameter of glInterleavedArrays. The formats are named as data-components-format, for example C4UB stands for color data stored in 4 components of unsigned byte type.
- Offset spin control – choose the offset from the beginning of the VBO to the start of the data. This should match the pointer parameter of the gl*Pointer function.
- Stride spin control – choose the stride (space in bytes between the end of one vertex’s data and the next one’s) to match the stride parameter of the gl*Pointer function.
You can view an image, a buffer or a texture object loaded image using the Image view.
Images and Buffers toolbar
Use the Images and Buffers toolbar to control the Image view
You can view a buffer, image or texture object raw data using the Data view.
The grid zoom slider allows you to set the zoom level of the displayed raw data cells.
Link image and data views
When enabled, clicking on a pixel at the image view will select this pixel at the data view grid.
Show normalized values
The values showed in the grid are the original data values of the object as held by OpenCL and OpenGL. These values may be in various data formats such as OpenCL C types, or GL_FLOAT, GL_INT, GL_SHORT and GL_BYTE.
When enabled, the data view will display the values in the grid normalized to the GL_BYTE type ([0..255] range), regardless of the original data type.
Viewing OpenCL buffers and OpenGL VBOs (Vertex Buffer Objects)
These buffers can only be shown in the Data View. After choosing the VBO’s data, format, offset and stride; each vertex’s data will be shown as a separate line in the view. The column headers represent the meaning of each value – X, Y, Z, W for vertex position; Nx, Ny, Nz for normal direction; R, G, B, A for vertex color and S, T, R, Q for texture coordinates.