VIS- und Uni-Logo
Blindenversion home uni uni suche suche sitemap sitemap kontakt kontakt
unilogo Universität Stuttgart
Institut für Visualisierung und Interaktive Systeme

OpenGL GLSL Debugger

 

Screenshots     Usage     Known Issues     FAQ     Downloads     References     Contact
glslDevil glslDevil is a tool for debugging the OpenGL shader pipeline, supporting GLSL vertex and fragment programs plus the recent geometry shader extension. By transparently instrumenting the host application it allows for debugging GLSL shaders in arbitrary OpenGL programs without the need to recompile or even having the source code of the host program available. The debug data is directly retrieved from the hardware pipeline and can be used for visual debugging and program analysis.

   Screenshots     
Screenshot - Debug fragment shader

Screenshot of a typical debug session for GLSL fragment shaders. The top right window shows the debugged application with a final rendering. The currently debugged shader statement is a loop condition, which results in the bottom right view of the fragments leaving or continuing the loop iteration.

Screenshot - Debug geometry shader

Example view of a debug session of a GLSL geometry shader. The main list shows detailed information about each input primitive, the current data values, and the already emitted as well as later emitted (marked with an '?') output vertices. The program debugged is a marching cubes implementation done by Cyril Crassin, which can be found here.

Screenshot - Scatter plot

Debugging the same program as above using the scatter plot functionality for visualizing data from the geometry shader. The color coding depicts the marching cube index derived for the corresponding cells. The original frame currently debugged shows an iso-surface of a sphere.
   Usage     
OpenGL Trace:
This window acts as interface to the debugged application and provides functionality to control the program execution. It shows the OpenGL command stream as issued by the application during execution and allows single stepping, jumping, and editing of OpenGL functions and their parameters. Several background operation modes exist to allow for an interactive usage of the debugged application. The source code of the currently bound GLSL shaders is shown in the Shader Source widget.
Shader debugging is performed on a per-draw-call level, of which all issued elements are debugged in parallel. Therefore, to enable GLSL shader debugging, the current position of the OpenGL trace must be a debuggable draw call and a GLSL shader must be bound.
Buttons:
glTraceExecute Execute target application and start debugging. The program stops at the first occurrence of an OpenGL, GLX, or WGL call. (Shortcut: F5)
glTraceKill Kill target application and close active debug session. (Shortcut: F5)
glTraceStep Execute the current call as issued from the target application and step to the next call.
glTraceJump Do not execute the current call and jump to the next call.
glTraceEdit Edit parameters of current function call.
glTraceJumpDrawCall Execute application until the next debuggable draw call. (Shortcut: F7)
glTraceJumpShaderSwitch Execute application until the next GLSL shader switch. (Shortcut: F6)
glTraceJumpUserDef Execute application until the next occurrence of a user-specified GL/GLX/WGL function call. (Shortcut: Alt+F8)
glTraceRun Execute application until further user interaction. (Shortcut: F8)
glTracePause Pause execution of the debugged application at the next GL/GLX/WGL function call. (Shortcut: Alt+Break)
glTraceHaltOnError If checked, the debugger forces the target application to stop immediately after an OpenGL error occurred.
glTraceNoTrace If checked, no debug data is transmitted to the debugger until the target application stops again. This is the fastest execution mode, but does not collect OpenGL trace data.
glTraceSettings Configure which GL/GLX/WGL functions are shown in the OpenGL Trace. See OpenGL Trace Settings for more information.
Function list icons:
glTraceIconArrow Call is the current debug position. This function call was not executed so far.
glTraceIconOk Call was successfully executed as issued by the debugged application.
glTraceIconEdit Call was executed with altered parameters.
glTraceIconJump Call was not executed by user request.
glTraceIconRecord Call is part of a recorded draw call for shader debugging.
Settings:
The configuration widget allows to setup for each GL/GLX/WGL function if it should be shown or hidden in the OpenGL Trace list. Only checked functions are shown in the OpenGL trace. Should the program be interrupted at a hidden function call, this list entry is shown in grey colors. Changes to the configuration of the OpenGL Trace list are applied to the complete history of the recorded list, which allows for subsequently show or hide already called functions.
The list includes all extensions that export functions and are supported by glslDevil. The icons indicate whether a specific extension is supported on the current platform. Note that extensions that do not export any functions are not listed.
glTrace glTraceSettingsWidget

OpenGL Buffer View:
This widget provides the basic functionality for showing the content of the currently bound color buffer for pixel reads. In many applications this can be used to see the current status of the frame being processed. The automatic mode updates the data after each draw call and provides insight about the stepwise frame creation at the cost of slower program execution.
Buttons:
glBufferCapture Capture the content of the color buffer currently used for OpenGL pixel reads.
glBufferCaptureAuto If checked, a buffer read is performed automatically after each OpenGL call that possibly alters the buffer content.
glBufferSave Save the current displayed image to a file.
glBufferView

Shader Source:
The source code of the currently bound GLSL vertex, geometry, and fragment shader is shown in this widget. When a debug session is started, the currently selected shader type is debugged and its first target statement is highlighted. Step In and Step Over functionality can be used to follow the program execution. During a debug session the Shader Variables widget provides information about the variable scope and recently changed variables. The debug environment for fragment shaders can be further configured using the Fragment Operations widget.
Independently of the selected GLSL shader type shader debugging is performed in parallel with respect to the input elements. In detail, for vertex programs all input vertices are debugged at the same time. For geometry shaders debugging is performed concurrently for each input or input sub-primitive. In case of fragment programs all fragments are processed in parallel. Due to this parallelism, special dialogs, i.e. the Selection dialog and the Loop dialog, are shown at dynamic flow control statements during debugging to support the user's debug decisions.
Buttons:
glslSourceExecute Start debugging the selected shader. Only available if the current OpenGL function call is a debuggable draw call. (Shortcut: Ctrl+F5)
glslSourceKill Stop GLSL shader debugging and close all open watch windows. (Shortcut: Ctrl+F5)
glslSourceRestart Restart the GLSL shader debug session. All watch items and windows remain unchanged. (Shortcut: Shift+Ctrl+F5)
glslSourceStep Step into the current statement if possible, otherwise step forward to the next statement. (Shortcut: F11)
glslSourceStepOver Step to the next statement without further following the current statement. (Shortcut: F10)
glslSourceTests Configure OpenGL tests and buffer initialization for debugging. (Shortcut: F4)
glslSource

Shader Variables:

This widget provides basic information about user-defined and built-in variables of the currently debugged shader. The tabs group the variables depending on their type and the scope of the current debug statement. Additionally color coding is used to indicate possible content changes.
The Built-In list and the Scope list are used to select items for data inspection. By double-clicking an entry the selected item and all its children are added to the Watch widget.
Tabs:
glslVariablesScope
Shows all user-defined variables that are in the extended scope of the current debug statement. Any variable in this list can be debugged at the current state of the debugger.
glslVariablesBuiltIn
Shows all built-in variables for the debugged GLSL shader type. All built-ins can be debugged at any statement of the shader code.
glslVariablesAll
Shows all user-defined and built-in variables of the current GLSL shader. Variables can not be selected as watch item from this list.
List entries:
glslVariablesItemRed
Variable may have changed in between the last and the currently debugged statement. If selected as watch item, the value gets updated automatically.
glslVariablesItemBold
User-defined variable that is in the local scope of the currently debugged statement.
glslVariablesItemNormal
Built-in or user-defined variable that is not in the local scope of the currently debugged statement and was not affected by the last debug step.
glslVariables

Watch:

Variables selected for data inspection are listed in this widget and their content is updated automatically if necessary while following the shader program execution. Selected items can be grouped into new Watch Windows or can be attached to already existing windows.
In case of debugging a fragment shader, additional value inspection is possible by using the Target Tool. The position of the currently selected fragment/pixel (in case a fragment shader is debugged), the id of the currently selected vertex (in case a vertex shader is debugged) or the id of the currently selected primitive (in case a geometry shader is debugged) is shown in the upper right box and the corresponding data values are displayed in the Values column.
Buttons:
glslWatchNew Open new watch window and attach all selected watch items.
glslWatchAttach Attach the selected watch items to the currently active watch window.
glslWatchDelete Delete and detach the selected watch items.
glslWatch

Watch windows:

Depending on the type of shader, data inspection of watched variables is performed in three different widgets. All of them show the elements debugged at the current position in the GL Trace and current statement in the Shader Source widget.
glslVSWin glslGSWin glslFSWin
Vertex shader:
glslGSWinInactive Toggle display of input vertices that are currently not active anymore.
Double-click selects a vertex for additional data inspection in the Watch widget.
Geometry shader:
glslGSWinInactive Toggle display of input primitives that are currently not active anymore.
glslGSWinNoEmit Toggle display of input primitives that do not emit any vertices.
glslGSWinType Toggle data input used for the scatter plot. If checked, already emitted vertices are shown, otherwise current data from each input primitive is used.
Double-click selects a primitive for additional data inspection in the Watch widget.
Fragment shader:
glslFSWinMapping Show dialog for color mapping configuration.
glslFSWinSave Save content with the current mapping as an image file.
glslFSWinZoom Zoom tool for magnification and minification (+Crtl) of the shown data. Use (+Shift) to reset.
glslFSWinTarget Target tool for selecting a fragment for additional data inspection in the Watch widget.
glslFSWinMinMax Restrict the min/max range of the mapping configuration to a user-defined region. Use (+Crtl) to auto apply changes.
List symbols:
For vertex/geometry shaders list entries may feature special symbols to specify the current state of an element instead of showing actual debug data.
listPercent The data of this element is not valid for at the current position of the debug statement.
listMinus The variable is not defined or not in the extended scope of the current debug statement.
listQuestion Only for geometry shaders. This output vertex was not emitted yet and therefore the attached data is not determined so far.
Selection Dialog:

If shader program control during debugging reaches an ambiguous flow control decision, the user must specify which branch should be followed for further debugging. In order to support these decisions a color coding of the evaluation of the condition is used to show the behavior for all debugged elements in question in a separate widget. Additionally, statistical information of the number of active elements and the amount following each branch is given.
Color Coding:
glsldevil-green Marks items following the true branch.
glsldevil-red Marks items following the false branch.
Vertex shader:
glslVSIf
Geometry shader:
glslGSIf
Fragment shader:
glslFSIf
Loop Dialog:

If shader program control during debugging reaches an ambiguous loop flow control decision, the user must specify to break, continue, or jump to another iteration of the loop. In order to support these decisions a color coding of the evaluation of the condition is used to show the behavior for all debugged elements in question in a separate widget. Again, statistical information is given for the number of elements starting the loop (Total), the number of elements continuing with the next iteration of the loop (Active), the number of elements breaking the loop due to the evaluation of the current condition (Done), and the number of elements that already left the loop in a prior iteration(Out). A second tab provides advanced analysis of the number of active elements of all debugged loop iterations. While Jump provides fast access to later iterations, statistical data for each iteration is only collected using the Full Statistic functionality.
Color Coding:
glsldevil-green.png Marks items continue to follow the next loop iteration.
glsldevil-orange Marks items that leave the loop due to the current loop condition.
glsldevil-red Marks items already left the loop in a prior iteration.
Vertex shader:
glslVSLoop
Geometry shader:
glslGSLoop
Fragment shader:
glslFSLoop
Shortcuts:

F4 Configure OpenGL tests and buffer initialization for debugging.
F5 Execute/Kill target application.
Ctrl+F5 Start/Stop debugging the selected shader.
Shift+Ctrl+F5 Restart the GLSL shader debug session.
F6 Execute application until the next GLSL shader switch
F7 Execute application until the next debuggable draw call
F8 Execute application until further user interaction
Ctrl+F8 Execute application until the next occurrence of a user-specified GL/GLX/WGL function call
F10 Step to the next statement without further following the current statement.
F11 Step into the current statement if possible, otherwise step forward to the next statement.
Alt+Break Pause execution of the debugged application at the next GL/GLX/WGL function call.
Ctrl+O Configure target application for debugging.
   Known Issues     
Debugger version (32/64-bit) must match host application
So far, the 64-bit version of glslDevil only supports debugging of 64-bit applications. In order to debug a 32-bit executable (independent of the host system), please use the 32-bit version of the debugger.

Multi-threaded/Multi-context applications may fail to work with glslDevil
The current version does not fully support multi-threaded target applications.
   FAQ     
Which draw calls allow shader debugging?
Currently all draw calls except glCallList, glCallLists, glBitmap, and glDrawPixels are debuggable. In the case of display lists the reason for this is the possibility to compile state changes into OpenGL lists which are not tracked during the creation process yet.

What is the difference between local scope and extended scope?
The local scope contains all user-defined variables that are valid/accessible at a specific statement in the shader code. In contrast the extended scope additionally contains all variables that are valid/accessible at the position of at least one statement in the current scope stack. The extended scope stack also includes variables that may not be in the local scope due to scope hiding rules.

Vertex shader debugging is disabled. Why?
To debug vertex shaders your graphics hardware needs to support the NV_transform_feedback extension. This is currently supported for example on NVIDIA G80 based cards.

Which GLSL extensions are supported by glslDevil?
Additional to GLSL version 1.2 the following extensions are supported: ARB_texture_rectangle, ARB_draw_buffers, EXT_bindable_uniform, EXT_geometry_shader4, EXT_gpu_shader4, EXT_texture_array. Further vendor specific enhancements to the GLSL compiler (i.e. additional implicit type casts, Cg compatibility, ...) are not supported in the current version.
   Downloads     
Current version: glslDevil 1.1.5
ChangeLog version 1.1.5 (02/16/10):
  • Fix: fragment shader input varyings
  • Fix: uniform struct definitions/declarations
  • Fix: do not crash on uninitialized sampler uniforms
  • Fix: varying out variables in fragment shaders
  • New: Show values of active uniforms in separate tab
  • New: Add support for vertex shader debugging using EXT_transform_feedback (Experimental)
ChangeLog version 1.1.4 (11/18/09):
  • Fix: segfault on Ubuntu 9.04 and newer
  • Fix: infinite loop in syntax highlighter on Qt 4.4 and newer
  • Fix: range mapping when min == max
  • Fix: varying out variables in fragment shaders
  • Fix: display of integer variables
  • Fix: Various other small bugfixes
  • New: Improved logging support
ChangeLog version 1.1.3b (08/29/08):
  • Fix: 64-bit debugger was broken :-/
ChangeLog version 1.1.3 (05/27/08):
  • New license!
  • Fix: Selection of vertices and primitives for inspection of values in the watch list.
  • Fix: Minor bug fixes and documentation update.
ChangeLog version 1.1.2 (04/21/08):
  • New: Added support of all missing OpenGL extensions registered at 11th April ('full support' (: ).
  • Fix: Off-by-one error in watch window pixel selection.
  • Fix: Debugging of loops in subfunctions failed.
  • Fix: Returning arrays from subfunctions failed.
  • Fix: Program termination not correctly handled in fast forward mode.
  • Fix: Few drawcalls (glDrawRangeElement*) were not recorded for debugging purposes.
  • Fix: Tri-graph code generation could result in invalid code.
ChangeLog version 1.1.1 (10/29/07):
  • Fix: Use of vertex buffer objects may cause program abort.
  • Fix: Shader code highlighting failed when using pragma #line.
  • Fix: Return from main() may cause invalid debug output.
ChangeLog version 1.1 (10/26/07):
  • New: First public release for Windows.
  • Add: Active queries do not get affected by shader debugging.
  • Add: Vector-type shader variables can be interacted with.
  • Add: Support to start glslDevil from the PATH environment.
  • Add: Visibility of GL/GLX/WGL functions in GlTrace list can be configured.
  • Add: Improved performance for GlTrace list.
  • Add: Shortcuts for often used debug features.
  • Add: Selectable region for min/max in fragment watch window.
  • Add: Verbose output command line options (-v/-vv).
  • Fix: Allow GLSL samplers to be parameters of user-defined functions.
  • Fix: Wrong handling of nested #if/#else/#endif directives.
  • Fix: Failed to generate code for sampler2DRect.
  • Fix: Possible missing data updates when using discard.
  • Fix: Various smaller bugfixes in GLSL compiler/code generator.
ChangeLog version 1.0 (08/02/07):
  • First public release for Linux.

Linux:
Requirements: Qt 4.4 needs to be installed on the system
Details: 32-bit version (.tgz)
Libc 2.9, Compiled on Ubuntu 9.10
64-bit version (.tgz)
Libc 2.9, Compiled on Ubuntu 9.10
Download: glslDevil (32- & 64-bit version)

Windows:
Requirements: None. Qt 4.4 redistributable will be installed if needed
Download: glslDevil (32-bit version)
   References     
GLSL GPU Debugger M. Strengert, T. Klein, and T. Ertl
A Hardware-Aware Debugger for the OpenGL Shading Language
ACM Siggraph/Eurographics Workshop on Graphics Hardware 2007 (GH'07)
San Diego, California, USA, pp.81-88, 2007
[ps]   |   [pdf]   |   [bibtex]
   Contact     
For more information, comments, questions, or bug reports, please contact glsldevil@vis.uni-stuttgart.de. Else feel free to contact us directly:
Thomas Klein   Thomas.Klein@vis.uni-stuttgart.de  
Magnus Strengert   Magnus.Strengert@vis.uni-stuttgart.de