 |
|
|
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.
|
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.
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.
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.
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:
|
Execute target application and start debugging.
The program stops at the first occurrence of an OpenGL, GLX, or WGL call.
(Shortcut: F5)
|
|
|
|
Kill target application and close active debug session.
(Shortcut: F5)
|
|
|
|
Execute the current call as issued from the target application and step to the next call.
|
|
|
|
Do not execute the current call and jump to the next call.
|
|
|
|
Edit parameters of current function call.
|
|
|
|
Execute application until the next debuggable draw call.
(Shortcut: F7)
|
|
|
|
Execute application until the next GLSL shader switch.
(Shortcut: F6)
|
|
|
|
Execute application until the next occurrence of a user-specified GL/GLX/WGL function call.
(Shortcut: Alt+F8)
|
|
|
|
Execute application until further user interaction.
(Shortcut: F8)
|
|
|
|
Pause execution of the debugged application at the next GL/GLX/WGL function call.
(Shortcut: Alt+Break)
|
|
|
|
If checked, the debugger forces the target application to stop immediately after an OpenGL error occurred.
|
|
|
|
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.
|
|
|
|
Configure which GL/GLX/WGL functions are shown in the OpenGL Trace.
See OpenGL Trace Settings for more information.
|
|
|
Function list icons:
|
Call is the current debug position. This function call was not executed so far.
|
|
|
|
Call was successfully executed as issued by the debugged application.
|
|
|
|
Call was executed with altered parameters.
|
|
|
|
Call was not executed by user request.
|
|
|
|
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.
|
|
|
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:
|
Capture the content of the color buffer currently used for OpenGL pixel reads.
|
|
|
|
If checked, a buffer read is performed automatically after each OpenGL call that possibly alters the buffer content.
|
|
|
|
Save the current displayed image to a file.
|
|
|
|
|
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:
|
|
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:
|
|
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.
|
|
|
|
|
Shows all built-in variables for the debugged GLSL shader type.
All built-ins can be debugged at any statement of the shader code.
|
|
|
|
|
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:
|
|
Variable may have changed in between the last and the currently debugged statement. If selected as watch item, the value gets updated automatically.
|
|
|
|
|
User-defined variable that is in the local scope of the currently debugged statement.
|
|
|
|
|
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.
|
|
|
|
|
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:
|
Open new watch window and attach all selected watch items.
|
|
|
|
Attach the selected watch items to the currently active watch window.
|
|
|
|
Delete and detach the selected watch items.
|
|
|
|
|
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.
|
|
|
Vertex shader:
|
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:
|
|
Toggle display of input primitives that are currently not active anymore.
|
|
|
|
Toggle display of input primitives that do not emit any vertices.
|
|
|
|
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:
|
Show dialog for color mapping configuration.
|
|
|
|
Save content with the current mapping as an image file.
|
|
|
|
Zoom tool for magnification and minification (+Crtl) of the shown data. Use (+Shift) to reset.
|
|
|
|
Target tool for selecting a fragment for additional data inspection in the Watch widget.
|
|
|
|
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.
|
The data of this element is not valid for at the current position of the debug statement.
|
|
|
|
The variable is not defined or not in the extended scope of the current debug statement.
|
|
|
|
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:
|
Marks items following the true branch.
|
|
|
|
Marks items following the false branch.
|
|
|
|
|
Vertex shader:
|
Geometry shader:
|
Fragment shader:
|
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:
|
|
Marks items continue to follow the next loop iteration.
|
|
|
|
Marks items that leave the loop due to the current loop condition.
|
|
|
|
|
Marks items already left the loop in a prior iteration.
|
|
|
|
|
Vertex shader:
|
Geometry shader:
|
Fragment shader:
|
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. |
|
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.
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.
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:
For more information, comments, questions, or bug reports, please contact glsldevil@vis.uni-stuttgart.de.
Else feel free to contact us directly:
|
|
