GL_KHR_debug

Supported Hardware

Series5, Series5XT, Series6, Series6XE, Series6XT

Valid APIs

OpenGL ES 2.0, 3.x

Description

KHR_debug combines a number of debug features into a single package that is made consistent across OpenGL and OpenGL ES. There are three main features provided by this extension:

• Message Logging: While running in Debug mode, if the driver detects any errors, performance problems or any sort of problem, it can raise a human readable message to a log. An application is also free to add its own messages to this log. A callback API is also provided, so that the user can be notified when a message is generated. This is similar to the GL_ARB_debug_output extension.

• Group Markers: Push and Pop functions are provided to encapsulate a block of functionality with a label. This is primarily to aid tracing and other debug tools when examining a recorded call stream. This functionality is similar to that provided by EXT_debug_marker.

• Object Labels: Finally, this extension also adds the ability to tag objects with a name. Again, this is primarily for tracing tools when examining a recorded call stream, to allow users to quickly identify specific objects, rather than looking them up by their assigned identifier.

In conjunction with debug tools, this is a very useful extension as it allows users to get a better idea of how their application’s GL calls are laid out. Typical usage includes things like putting group markers around the start and end of application functions or labelling key textures or vertex buffers to match the assets they contain.

Registry Link

http://www.khronos.org/registry/gles/extensions/KHR/KHR_debug.txt

Example

// Debug callback function
void (APIENTRY) debugMessageCallback(GLenum source,
                                     GLenum type,
                                     GLuint id,
                                     GLenum severity,
                                     GLsizei length,
                                     const GLchar* message,
                                     const void* userParam)
{
    /*
        Handle the message based on severity and such. Here we're using printf to
        output a message.
        This example only handles the type, severity and message. Useful information
        can be gleaned
        from the other parameters as well but would unnecessarily clutter this
        example.
    */
    // Output the message type
    switch (type)
    {
    case GL_DEBUG_TYPE_ERROR:
        {
            printf("%s", "Error ");
            break;
        }
    case GL_DEBUG_TYPE_DEPRECATED_BEHAVIOUR:
        {
            printf("%s", "Deprecated Behaviour ");
            break;
        }
    case GL_DEBUG_TYPE_UNDEFINED_BEHAVIOUR:
        {
            printf("%s", "Undefined Behaviour ");
            break;
        }
    case GL_DEBUG_TYPE_PORTABILITY:
        {
            printf("%s", "Portability Issue ");
            break;
        }
    case GL_DEBUG_TYPE_PERFORMANCE:
        {
            printf("%s", "Performance Issue ");
            break;
        }
    case GL_DEBUG_TYPE_OTHER:
        {
            printf("%s", "Misc Message ");
            break;
        }
    case GL_DEBUG_TYPE_MARKER:
        {
            printf("%s", "Marker Hit ");
            break;
        }
    case default:
        {
            printf("%s", "Unknown Message Type ");
            break;
        }
    }
    // Output the message severity
    switch (severity)
    {
    case GL_DEBUG_SEVERITY_NOTIFICATION:
        {
            printf("%s", "(Notification): ");
            break;
        }
    case GL_DEBUG_SEVERITY_LOW:
        {
            printf("%s", "(Low Severity): ");
            break;
        }
    case GL_DEBUG_SEVERITY_MEDIUM:
        {
            printf("%s", "(Medium Severity): ");
            break;
        }
    case GL_DEBUG_SEVERITY_HIGH:
        {
            printf("%s", "(High Severity): ");
            break;
        }
    case default:
        {
            printf("%s", "(Unknown Severity): ");
            break;
        }
    }
    // Append the message and a newline.
    if (length==0)
    {
        // NULL terminated strings are easy enough
        printf("%s\n", message);
    }
    else
    {
        // Strings with a specified length are not NULL terminated
        printf("%.*s", length, message);
    }
}
void initialise()
{
    /*
        Use a debug marker to encapsulate the initialise function, to mark this group
        in a tracing tool like PVRTrace.
    */
    glPushDebugMarker(GL_DEBUG_SOURCE_APPLICATION, 0, 0, "Function 'initialise'");
    ...
    // Create and label a texture object
    GLuint importantTexture;
    glGenTextures(1, &importantTexture);
    glObjectLabel(GL_TEXTURE, importantTexture, 0, "importantTexture");
    ...
    // Pop the debug marker
    glPopDebugMarker();
}