Difference between revisions of "Debugging Tools"

From OpenGL Wiki
Jump to: navigation, search
(Added references to KHR_debug, AMD GPUPerfStudio and NVIDIA NSight)
(Reorganization, adjustment, formatting and linking.)
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.
  
 +
=== Debug Output ===
 +
{{main|Debug Output}}
 +
 +
Debug Output is an OpenGL feature that makes [[Error Checking|error checking]] from functions easier. It is a core feature of GL 4.3, and available through extensions for older versions.
 +
 +
Most drivers expose this functionality only on debug contexts: context should be created with CONTEXT_DEBUG_BIT set..
 +
 +
=== RenderDoc ===
 +
Home page: 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. Linux is also supported, but currently without UI. 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 ===
 
===  BuGLe ===
 
Home page: https://www.opengl.org/sdk/tools/BuGLe/
 
Home page: https://www.opengl.org/sdk/tools/BuGLe/
Line 12: Line 25:
  
 
'''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>
+
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.
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>
+
It also supports GL_GREMEDY_string_marker http://www.opengl.org/registry/specs/GREMEDY/string_marker.txt
This is a feature rich app so check out their web page for details.<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.
 +
 
 +
This is a feature rich app so check out their web page for details.
  
 
'''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]
 
'''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]
Line 26: Line 42:
  
 
=== GLIntercept ===
 
=== GLIntercept ===
Download from http://code.google.com/p/glintercept/
+
Download from 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 44: Line 60:
  
 
=== glslDevil ===
 
=== glslDevil ===
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>
+
glslDevil is similar in concept to gDebugger, it works transparently just like gDebugger, it is free. It can debug the shaders line by line.
Linux and Windows.<br>
+
 
 +
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/
 
The source code has been opened in 2013 and actively developing Open Source fork is now available: http://glsl-debugger.github.io/
  
Line 58: Line 76:
 
[https://github.com/ValveSoftware/vogl]
 
[https://github.com/ValveSoftware/vogl]
  
=== RenderDoc ===
 
Home page: 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. Linux is also supported, but currently without UI. 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.
 
 
=== GL_ARB_debug_output ===
 
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.
 
 
=== KHR_debug ===
 
Promotion of GL_ARB_debug_output, EXT_debug_marker and EXT_debug_label.
 
The simples usage is to register a callback function that will be called when some OpenGL events occur, but functionality goes beyond that, allowing to insert GL messages that debugging tools will be able to display.
 
 
It can be used with or without a debug context:
 
* on a debug context, GL_DEBUG_OUTPUT is enabled by default.
 
* on a non-debug context, you need to call glEnable(GL_DEBUG_OUTPUT). On non-debug contexts, the implementation is not required to have any debug output, according to https://www.khronos.org/registry/OpenGL/extensions/KHR/KHR_debug.txt :
 
 
    If the context was created without the CONTEXT_FLAG_DEBUG_BIT and the
 
    DEBUG_OUTPUT is later enabled, the level of debug output logging is
 
    defined by the GL implementation, which may have zero debug output. To
 
    guarantee the full debug output support of the GL implementation the
 
    context should be created with CONTEXT_FLAG_DEBUG_BIT context flag bit
 
    set.
 
 
Example simple usage:
 
<source lang="c++">
 
glEnable(GL_DEBUG_OUTPUT);
 
glDebugMessageCallback(&debugCallback, NULL);
 
...
 
// Follow GLDEBUGPROC signature
 
void GLAPIENTRY debugCallback(
 
GLenum source, GLenum type, GLuint id,
 
GLenum severity,
 
GLsizei length,
 
const GLchar* message,
 
const void* userParam)
 
{
 
switch(severity)
 
{
 
case GL_DEBUG_SEVERITY_HIGH: // All OpenGL Errors, shader compilation/linking errors, or highly-dangerous undefined behavior
 
printf("KHR_Debug [HIGH]: %s\n", message);
 
break;
 
case GL_DEBUG_SEVERITY_MEDIUM:
 
printf("KHR_Debug [MEDIUM]: %s\n", message);
 
break;
 
case GL_DEBUG_SEVERITY_LOW:
 
printf("KHR_Debug [LOW]: %s\n", message);
 
break;
 
case GL_DEBUG_SEVERITY_NOTIFICATION:
 
printf("KHR_Debug [NOTIFICATION]: %s\n", message);
 
break;
 
}
 
}
 
 
</source>
 
 
 
 
=== AMD GPU PerfStudio ===
 
=== AMD GPU PerfStudio ===
  

Revision as of 15:15, 7 July 2017

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

Debug Output

Debug Output is an OpenGL feature that makes error checking from functions easier. It is a core feature of GL 4.3, and available through extensions for older versions.

Most drivers expose this functionality only on debug contexts: context should be created with CONTEXT_DEBUG_BIT set..

RenderDoc

Home page: 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. Linux is also supported, but currently without UI. 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

Home page: 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]

gDebugger

http://www.gremedy.com

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.

It also supports GL_GREMEDY_string_marker http://www.opengl.org/registry/specs/GREMEDY/string_marker.txt

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.

This is a feature rich app so check out their web page for details.

Note: AMD acquired Graphic Remedy in June 2011 [2]. AMD gDEBugger has been succeeded by AMD's CodeXL

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

Download from 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.

glslDevil

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

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.

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/

Xcode tools

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

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). [3]

AMD GPU PerfStudio

http://gpuopen.com/archive/gpu-perfstudio/ Supports Windows and Linux, can be used to analyze frames, see textures, buffers, shaders, etc. Also works on non-AMD hardware.

NVIDIA NSight