Name EXT_debug_marker Name Strings GL_EXT_debug_marker Contributors Seth Sowerby Benj Lipchak Contact Benj Lipchak, Apple (lipchak 'at' apple.com) Status Complete Version Date: October 7, 2013 Revision: 3 Number OpenGL Extension #440 OpenGL ES Extension #99 Dependencies Requires OpenGL ES 1.1. Written based on the wording of the OpenGL ES 2.0.25 Full Specification (November 2, 2010). Overview This extension defines a mechanism for OpenGL and OpenGL ES applications to annotate their command stream with markers for discrete events and groups of commands using descriptive text markers. When profiling or debugging such an application within a debugger or profiler it is difficult to relate the commands within the command stream to the elements of the scene or parts of the program code to which they correspond. Markers help obviate this by allowing applications to specify this link. The intended purpose of this is purely to improve the user experience within OpenGL and OpenGL ES development tools. New Procedures and Functions void InsertEventMarkerEXT(sizei length, const char *marker); void PushGroupMarkerEXT(sizei length, const char *marker); void PopGroupMarkerEXT(); New Tokens None Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation) None Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) None Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment Operations and the Framebuffer) None Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special Functions) Add a new section titled Debug Makers Debug markers provide a method for annotating a command stream with markers for discrete events and groups of commands using a descriptive text marker. These names may then be used by a tool such as a debugger or profiler to label the command stream. The command void InsertEventMarkerEXT(sizei length, const char *marker); inserts an event marker string into the command stream. specifies the length of the string passed in . If is a null-terminated string then should not include the terminator. If is 0 then is assumed to be null-terminated. The command void PushGroupMarkerEXT(sizei length, const char *marker); pushes a group marker string into the command stream. specifies the length of the string passed in . If is a null-terminated string then should not include the terminator. If is 0 then is assumed to be null-terminated. If is null then an empty string is pushed on the stack. The command void PopGroupMarkerEXT(); pops the most recent group marker. If there is no group marker to pop then the PopGroupMarkerEXT command is ignored. Group markers are strictly hierarchical. Group marker sequences may be nested within other group markers but can not overlap. Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State Requests) None Errors None New State None New Implementation Dependent State None Issues (1) Should the extension provide a method for querying markers? No. A great deal of the value of debug markers is the 'when' as well as the 'what' - seeing the debug markers within the stream of all OpenGL ES commands. This value is only available to a tool intercepting the command stream - it is not available from querying the markers. However, the ability to query markers would make them available to developer tools attaching to an already running application. Querying the markers could be useful for applications to be able to dump their marker stack to their own logs. However, this functionality does not require an extension as applications can implement their own marker stacks within their code independent of OpenGL ES. (2) Should a query exist for the current marker stack depth? No. This would be useful if markers are queryable but not otherwise. (3) Should PushGroupMarkerEXT & PopGroupMarkerEXT return the marker stack depth? No. This would be useful if markers are queryable but not otherwise. (4) How should a null-string passed to PushGroupMarkerEXT be treated? Resolved: Push an empty string. The two possibilities are to push an empty string onto the marker stack or to ignore the call to PushGroupMarkerEXT. Pushing an empty string maintains the marker stack depth expected by the calling application. (5) Should the extension support printf-style formatting? Resolved: No. Providing printf-style formatting would impose a much greater burden on the extension in terms of error checking the format string and arguments. Likely all languages capable of calling OpenGL ES have convenient capabilities for formatting strings so it is acceptable to rely on those. Revision History Date 01/17/2011 Revision: 1 - draft proposal Date 07/22/2011 Revision: 2 - rename from APPLE to EXT Date 10/07/2013 Revision: 3 - Add support for desktop OpenGL