| 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 <marker> into the command stream. <length> |
| specifies the length of the string passed in <marker>. If <marker> is a |
| null-terminated string then <length> should not include the terminator. |
| If <length> is 0 then <marker> is assumed to be null-terminated. |
| |
| The command |
| |
| void PushGroupMarkerEXT(sizei length, const char *marker); |
| |
| pushes a group marker string <marker> into the command stream. <length> |
| specifies the length of the string passed in <marker>. If <marker> is a |
| null-terminated string then <length> should not include the terminator. If |
| <length> is 0 then <marker> is assumed to be null-terminated. If <marker> |
| 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 |