Difference between revisions of "Debugging Tools"

From OpenGL Wiki
Jump to: navigation, search
m (GL_ARB_debug_output: typo)
(NVIDIA NSight)
 
(21 intermediate revisions by 8 users not shown)
Line 1: Line 1:
 
There are several tools that can aid in the debugging of your OpenGL program.
 
There are several tools that can aid in the debugging of your OpenGL program.
  
===  BuGLe ===
+
== Debug Output ==
Home page: https://www.opengl.org/sdk/tools/BuGLe/
+
:: {{main|Debug Output}}
 +
 
 +
'''Description:'''
 +
 
 +
Debug Output is an OpenGL feature that makes debugging and optimizing OpenGL applications easier.  It is a core feature of GL 4.3 (described specifically in {{extref|debug|KHR}}).  Ancestor GL extensions are available for older OpenGL implementations.
 +
 
 +
In a nutshell, it allows your application to be notified via a callback function when "interesting events" occur.  For instance, this allows the GL driver to notify your application:
 +
* when a GL error has occurred (and to provide extended information about why that error occurred),
 +
* when your app is using a slow path in the GL driver,
 +
* when (based on your usage) the GL driver has a performance tip to offer for improving your app's performance, or
 +
* when some important state change has occurred in the driver that you might want to know about. 
 +
Catching GL errors with this method is much easier than by using [[Error Checking|glGetError() error checking]].  Your application is also able to annotate GL objects with human-readable names and insert its own debugging messages into the event stream.
 +
 
 +
{{extref|debug|KHR}} (part of core OpenGL 4.3) provides a convenient way to {{apifunc|glEnable|()}} this debug output support from within a normal GL context.
 +
 
 +
== RenderDoc ==
 +
 
 +
: https://renderdoc.org/
 +
 
 +
'''Description:'''
 +
RenderDoc is a stand-alone graphics debugging tool, released under the MIT License, that supports OpenGL 3.2+ (Core Profile only) development on Windows and Linux. Besides OpenGL, RenderDoc can also be used to debug [https://www.khronos.org/vulkan/ Vulkan] and several other graphics APIs.  Online documentation is available at https://renderdoc.org/docs/index.html.
 +
 +
==  BuGLe ==
 +
 
 +
: https://www.opengl.org/sdk/tools/BuGLe/
  
 
'''Description:''' BuGLe is a free (as in freedom) software released under the GPLv2. It is a toolkit for debugging and profiling OpenGL applications running on UNIX-like systems. It consists of two parts: a collection of filter-sets that observe and sometimes modify calls to the OpenGL API, and a graphical debugger (<tt>gldb-gui</tt>) that helps in setting breakpoints, capturing errors, and examining state (including shader code, buffers and a visual feedback of the textures, the color buffers and depth buffer).
 
'''Description:''' BuGLe is a free (as in freedom) software released under the GPLv2. It is a toolkit for debugging and profiling OpenGL applications running on UNIX-like systems. It consists of two parts: a collection of filter-sets that observe and sometimes modify calls to the OpenGL API, and a graphical debugger (<tt>gldb-gui</tt>) that helps in setting breakpoints, capturing errors, and examining state (including shader code, buffers and a visual feedback of the textures, the color buffers and depth buffer).
Line 8: Line 32:
 
'''Note:''' It was officially announced on November 23 2014 that BuGLe is no longer being developed. [https://www.opengl.org/sdk/tools/BuGLe/news.php]
 
'''Note:''' It was officially announced on November 23 2014 that BuGLe is no longer being developed. [https://www.opengl.org/sdk/tools/BuGLe/news.php]
  
=== gDebugger ===
+
== AMD CodeXL ==
http://www.gremedy.com
+
 
 +
: https://gpuopen.com/compute-product/codexl/
 +
: https://en.wikipedia.org/wiki/CodeXL
  
 
'''Description:'''
 
'''Description:'''
gDebugger is a commercial application that hooks to your application and displays info in text and graphical form in its own window. It can also show GPU utilization. You can use it to find out where the bottleneck is in your app. There are Windows and Linux versions.<br>
+
[http://gpuopen.com/compute-product/codexl/ AMD's CodeXL] is the successor to [https://www.khronos.org/news/permalink/amd-acquires-graphic-remedy-to-extend-its-technology-portfolio-and-opens-a Graphic Remedy's gDebugger].
It also supports GL_GREMEDY_string_marker http://www.opengl.org/registry/specs/GREMEDY/string_marker.txt<br>
 
GL_GREMEDY_string_marker is for leaving markers in your source code, so that it becomes easier for you to locate where the problem is.<br>
 
This is a feature rich app so check out their web page for details.<br>
 
  
'''Note:''' AMD acquired Graphic Remedy in June 2011 [https://www.khronos.org/news/permalink/amd-acquires-graphic-remedy-to-extend-its-technology-portfolio-and-opens-a]. [http://developer.amd.com/tools-and-sdks/archive/amd-gdebugger/ AMD gDEBugger] has been succeeded by [http://developer.amd.com/tools-and-sdks/opencl-zone/codexl/ AMD's CodeXL]
+
gDebugger was a commercial application that hooked into your application and displayed info in text and graphical form in its own window. It could also show GPU utilization. You could use it to find out where the bottleneck is in your app. There were Windows and Linux versions.
  
=== APITrace ===
+
It also supported [http://www.opengl.org/registry/specs/GREMEDY/string_marker.txt GL_GREMEDY_string_marker] for leaving natural language description markers in your source code, which made it easier for you to locate where in your application that GL call sequences were being executed.
https://github.com/apitrace/apitrace
+
 
 +
== APITrace ==
 +
 
 +
: https://github.com/apitrace/apitrace
  
 
'''Description:'''
 
'''Description:'''
 
APITrace is another free (as in freedom) software. It is  a toolkit for debugging and profiling OpenGL and DirectX applications running on Linux or Windows. You first run your program to generate a "trace file", and this file can then be replayed or explored using the tools provided.
 
APITrace is another free (as in freedom) software. It is  a toolkit for debugging and profiling OpenGL and DirectX applications running on Linux or Windows. You first run your program to generate a "trace file", and this file can then be replayed or explored using the tools provided.
  
=== GLIntercept ===
+
== GLIntercept ==
Download from http://code.google.com/p/glintercept/
+
 
 +
: https://github.com/dtrebilco/glintercept
  
 
'''Description:'''
 
'''Description:'''
GLIntercept is a free open sourced program intended for Windows platforms. After installing, a folder (<code>C:\Program Files\GLIntercept*_*</code> where the asterisks are the version numbers) will have been created. This folder holds several sample configuration files of interest which can be used to configure GLIntercept: <code>gliConfig.ini</code>, <code>gliConfig_AuthorStd.ini</code>, <code>gliConfig_ExtOverride.ini</code>, etc. In addition, this folder holds a version of the <code>OpenGL32.dll</code> file which acts an intermediary between your system's OpenGL implementation and GLIntercept. To utilize this functionality, copy the DLL and a customized copy of the <code>gliConfig.ini</code> file to your application's target folder (usually where the .EXE resides) and run your application. All invoked OpenGL function calls will route through the DLL, allowing GLIntercept to detect:
+
GLIntercept is a free open sourced program intended for Windows platforms. After installing, a folder ({{code|C:\Program Files\GLIntercept*_*}} where the asterisks are the version numbers) will have been created. This folder holds several sample configuration files of interest which can be used to configure GLIntercept: {{code|gliConfig.ini}}, {{code|gliConfig_AuthorStd.ini}}, {{code|gliConfig_ExtOverride.ini}}, etc. In addition, this folder holds a version of the <code>OpenGL32.dll</code> file which acts an intermediary between your system's OpenGL implementation and GLIntercept. To utilize this functionality, copy the DLL and a customized copy of the {{code|gliConfig.ini}} file to your application's target folder (usually where the .EXE resides) and run your application. All invoked OpenGL function calls will route through the DLL, allowing GLIntercept to detect:
  
 
* Errors
 
* Errors
Line 43: Line 70:
 
'''Cons:''' The program is intended for applications that have a single GL context. Windows Only. It is compatible with OpenGL 3.x and above, but it will not provide the best form of logging for some of the more recent APIs and extensions.
 
'''Cons:''' The program is intended for applications that have a single GL context. Windows Only. It is compatible with OpenGL 3.x and above, but it will not provide the best form of logging for some of the more recent APIs and extensions.
  
=== glslDevil ===
+
== GLSL-Debugger ==
http://www.vis.uni-stuttgart.de/glsldevil/
+
 
 +
: http://glsl-debugger.github.io/
  
 
'''Description:'''
 
'''Description:'''
glslDevil is similar in concept to gDebugger, it works transparently just like gDebugger, it is free. It can debug the shaders line by line.<br>
+
GLSL-Debugger is similar in concept to gDebugger.  It works transparently just like gDebugger, and it can debug the shaders line by line. It is also free.  
Linux and Windows.<br>
 
The source code has been opened in 2013 and actively developing Open Source fork is now available: http://glsl-debugger.github.io/
 
  
=== Xcode tools ===
+
Linux and Windows.
 +
 
 +
The source code has been opened in 2013 and actively developing Open Source fork is now available: http://glsl-debugger.github.io/.  This is a fork of the original glslDevil project.
 +
 
 +
== Xcode tools ==
 +
 
 +
: https://developer.apple.com/xcode/
 +
 
 +
'''Description:'''
 
Under Mac OS X, Apple provides two very handy tools for debugging OpenGL applications as part of Xcode: [https://developer.apple.com/library/mac/documentation/GraphicsImaging/Conceptual/OpenGLDriverMonitorUserGuide/Introduction/Introduction.html OpenGL Driver Monitor] and [https://developer.apple.com/library/mac/documentation/GraphicsImaging/Conceptual/OpenGLProfilerUserGuide/Introduction/Introduction.html OpenGL Profiler].
 
Under Mac OS X, Apple provides two very handy tools for debugging OpenGL applications as part of Xcode: [https://developer.apple.com/library/mac/documentation/GraphicsImaging/Conceptual/OpenGLDriverMonitorUserGuide/Introduction/Introduction.html OpenGL Driver Monitor] and [https://developer.apple.com/library/mac/documentation/GraphicsImaging/Conceptual/OpenGLProfilerUserGuide/Introduction/Introduction.html OpenGL Profiler].
  
=== Vogl ===
+
== Vogl ==
Vogl is a free (as in freedom) software released under the MIT License by RAD Game Tools and Valve Software. It is an OpenGL capture / playback debugger running on Linux and Windows. There is also a Mac OS port which is not yet functional (as of Jan 10 2015).   
+
 
[https://github.com/ValveSoftware/vogl]
+
: https://github.com/ValveSoftware/vogl
 +
 
 +
'''Description:'''
 +
Vogl is a free (as in freedom) software released under the MIT License by RAD Game Tools and Valve Software. It is an OpenGL capture / playback debugger running on Linux, Windows, and Mac OSX.
 +
 
 +
== AMD GPU PerfStudio ==
 +
 
 +
: http://gpuopen.com/archive/gpu-perfstudio/
 +
 
 +
'''Description:'''
 +
Supports Windows and Linux, can be used to analyze frames, see textures, buffers, shaders, etc. Also works on non-AMD hardware.
 +
 
 +
== NVIDIA Nsight Graphics ==
 +
 
 +
: https://developer.nvidia.com/nsight-graphics
 +
 
 +
'''Description:'''
 +
 
 +
[https://developer.nvidia.com/nsight-graphics Nsight Graphics] supports stand-alone profiling and debugging of OpenGL, Vulkan, and D3D applications on both Windows and Linux, including those utilizing OpenVR, the Oculus SDK, or the Ray Tracing extensions for Vulkan or D3D.  Here's the [https://developer.nvidia.com/nsight-graphics-features Support Matrix].  As of 2019, Nsight Graphics is being actively maintained and extended.  See also: [https://developer.nvidia.com/nsight-graphics-documentation-and-support Documentation], [https://devtalk.nvidia.com/default/board/322/nsight-graphics/ Support Forum] (post questions and feature requests here).
 +
 
 +
In practice, Nsight Graphics has solid capture, debugging, and profiling support for OpenGL applications, including complete support for OpenGL [[Debug_Output]] APIsMarking sub-frame processing sections with named debug groups makes it fairly trivial to identify, examine, and profile these in frame captures.
 +
 
 +
== NVIDIA Nsight VSE ==
 +
 
 +
: https://www.nvidia.com/object/nsight.html
 +
 
 +
'''Description:'''
 +
The Nsight [https://developer.nvidia.com/nvidia-nsight-visual-studio-edition Visual Studio Edition] provides visual debugging and profiling capability for OpenGL / CUDA / D3D (and more) programs on Windows.  This is an older tool that (unlike [[#NVIDIA Nsight Graphics|Nsight Graphics]]) requires both Windows and Microsoft Visual Studio.
  
=== GL_ARB_debug_output ===
+
[https://developer.nvidia.com/nsight-eclipse-edition NSight Eclipse Edition] provides similar support for Linux and Mac OS.  
This OpenGL extension implemented in some drivers allows the GL to notify applications when various events occur that may be useful during application development and debugging. See http://www.opengl.org/registry/specs/ARB/debug_output.txt
 
Most drivers expose this extension only on debug contexts: context should be created with CONTEXT_DEBUG_BIT set, see WGL_ARB_create_context or GLX_ARB_create_context.
 
  
 
[[Category:Related Toolkits & APIs]]
 
[[Category:Related Toolkits & APIs]]

Latest revision as of 13:13, 30 September 2019

There are several tools that can aid in the debugging of your OpenGL program.

Debug Output

Description:

Debug Output is an OpenGL feature that makes debugging and optimizing OpenGL applications easier. It is a core feature of GL 4.3 (described specifically in KHR_debug). Ancestor GL extensions are available for older OpenGL implementations.

In a nutshell, it allows your application to be notified via a callback function when "interesting events" occur. For instance, this allows the GL driver to notify your application:

  • when a GL error has occurred (and to provide extended information about why that error occurred),
  • when your app is using a slow path in the GL driver,
  • when (based on your usage) the GL driver has a performance tip to offer for improving your app's performance, or
  • when some important state change has occurred in the driver that you might want to know about.

Catching GL errors with this method is much easier than by using glGetError() error checking. Your application is also able to annotate GL objects with human-readable names and insert its own debugging messages into the event stream.

KHR_debug (part of core OpenGL 4.3) provides a convenient way to glEnable() this debug output support from within a normal GL context.

RenderDoc

https://renderdoc.org/

Description: RenderDoc is a stand-alone graphics debugging tool, released under the MIT License, that supports OpenGL 3.2+ (Core Profile only) development on Windows and Linux. Besides OpenGL, RenderDoc can also be used to debug Vulkan and several other graphics APIs. Online documentation is available at https://renderdoc.org/docs/index.html.

BuGLe

https://www.opengl.org/sdk/tools/BuGLe/

Description: BuGLe is a free (as in freedom) software released under the GPLv2. It is a toolkit for debugging and profiling OpenGL applications running on UNIX-like systems. It consists of two parts: a collection of filter-sets that observe and sometimes modify calls to the OpenGL API, and a graphical debugger (gldb-gui) that helps in setting breakpoints, capturing errors, and examining state (including shader code, buffers and a visual feedback of the textures, the color buffers and depth buffer).

Note: It was officially announced on November 23 2014 that BuGLe is no longer being developed. [1]

AMD CodeXL

https://gpuopen.com/compute-product/codexl/
https://en.wikipedia.org/wiki/CodeXL

Description: AMD's CodeXL is the successor to Graphic Remedy's gDebugger.

gDebugger was a commercial application that hooked into your application and displayed info in text and graphical form in its own window. It could also show GPU utilization. You could use it to find out where the bottleneck is in your app. There were Windows and Linux versions.

It also supported GL_GREMEDY_string_marker for leaving natural language description markers in your source code, which made it easier for you to locate where in your application that GL call sequences were being executed.

APITrace

https://github.com/apitrace/apitrace

Description: APITrace is another free (as in freedom) software. It is a toolkit for debugging and profiling OpenGL and DirectX applications running on Linux or Windows. You first run your program to generate a "trace file", and this file can then be replayed or explored using the tools provided.

GLIntercept

https://github.com/dtrebilco/glintercept

Description: GLIntercept is a free open sourced program intended for Windows platforms. After installing, a folder (C:\Program Files\GLIntercept*_* where the asterisks are the version numbers) will have been created. This folder holds several sample configuration files of interest which can be used to configure GLIntercept: gliConfig.ini, gliConfig_AuthorStd.ini, gliConfig_ExtOverride.ini, etc. In addition, this folder holds a version of the OpenGL32.dll file which acts an intermediary between your system's OpenGL implementation and GLIntercept. To utilize this functionality, copy the DLL and a customized copy of the gliConfig.ini file to your application's target folder (usually where the .EXE resides) and run your application. All invoked OpenGL function calls will route through the DLL, allowing GLIntercept to detect:

  • Errors
  • Function calls before context creation
  • Resource leaks

Once you close your app, GLI dumps the above info into gliLog.txt.

You may configure GLI to output a XML log file (upon pressing [Ctrl]+[Shift]+[f]) showing all of the OpenGL functions called, problems and used shaders and textures. GLI will make a folder where your EXE is and places the XML files and all related files like screen captures and textures.

In gliConfig.ini, check out section "LogPerFrame".

Cons: The program is intended for applications that have a single GL context. Windows Only. It is compatible with OpenGL 3.x and above, but it will not provide the best form of logging for some of the more recent APIs and extensions.

GLSL-Debugger

http://glsl-debugger.github.io/

Description: GLSL-Debugger is similar in concept to gDebugger. It works transparently just like gDebugger, and it can debug the shaders line by line. It is also free.

Linux and Windows.

The source code has been opened in 2013 and actively developing Open Source fork is now available: http://glsl-debugger.github.io/. This is a fork of the original glslDevil project.

Xcode tools

https://developer.apple.com/xcode/

Description: Under Mac OS X, Apple provides two very handy tools for debugging OpenGL applications as part of Xcode: OpenGL Driver Monitor and OpenGL Profiler.

Vogl

https://github.com/ValveSoftware/vogl

Description: Vogl is a free (as in freedom) software released under the MIT License by RAD Game Tools and Valve Software. It is an OpenGL capture / playback debugger running on Linux, Windows, and Mac OSX.

AMD GPU PerfStudio

http://gpuopen.com/archive/gpu-perfstudio/

Description: Supports Windows and Linux, can be used to analyze frames, see textures, buffers, shaders, etc. Also works on non-AMD hardware.

NVIDIA Nsight Graphics

https://developer.nvidia.com/nsight-graphics

Description:

Nsight Graphics supports stand-alone profiling and debugging of OpenGL, Vulkan, and D3D applications on both Windows and Linux, including those utilizing OpenVR, the Oculus SDK, or the Ray Tracing extensions for Vulkan or D3D. Here's the Support Matrix. As of 2019, Nsight Graphics is being actively maintained and extended. See also: Documentation, Support Forum (post questions and feature requests here).

In practice, Nsight Graphics has solid capture, debugging, and profiling support for OpenGL applications, including complete support for OpenGL Debug_Output APIs. Marking sub-frame processing sections with named debug groups makes it fairly trivial to identify, examine, and profile these in frame captures.

NVIDIA Nsight VSE

https://www.nvidia.com/object/nsight.html

Description: The Nsight Visual Studio Edition provides visual debugging and profiling capability for OpenGL / CUDA / D3D (and more) programs on Windows. This is an older tool that (unlike Nsight Graphics) requires both Windows and Microsoft Visual Studio.

NSight Eclipse Edition provides similar support for Linux and Mac OS.