1Name
2
3    EXT_debug_marker
4
5Name Strings
6
7    GL_EXT_debug_marker
8
9Contributors
10
11    Seth Sowerby
12    Benj Lipchak
13
14Contact
15
16    Benj Lipchak, Apple (lipchak 'at' apple.com)
17
18Status
19    
20    Complete
21
22Version
23
24    Date: October 7, 2013
25    Revision: 3
26
27Number
28
29    OpenGL Extension #440
30    OpenGL ES Extension #99
31
32Dependencies
33    
34    Requires OpenGL ES 1.1.
35
36    Written based on the wording of the OpenGL ES 2.0.25 Full Specification
37    (November 2, 2010).
38
39Overview
40
41    This extension defines a mechanism for OpenGL and OpenGL ES applications to
42    annotate their command stream with markers for discrete events and groups 
43    of commands using descriptive text markers. 
44    
45    When profiling or debugging such an application within a debugger or 
46    profiler it is difficult to relate the commands within the command stream 
47    to the elements of the scene or parts of the program code to which they 
48    correspond. Markers help obviate this by allowing applications to specify 
49    this link.
50    
51    The intended purpose of this is purely to improve the user experience 
52    within OpenGL and OpenGL ES development tools.
53    
54New Procedures and Functions
55
56    void InsertEventMarkerEXT(sizei length, const char *marker);
57    void PushGroupMarkerEXT(sizei length, const char *marker);
58    void PopGroupMarkerEXT();
59
60New Tokens
61
62    None
63
64Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation)
65
66    None
67
68Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization)
69
70    None
71
72Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment
73Operations and the Framebuffer)
74
75    None
76
77Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special Functions)
78
79    Add a new section titled Debug Makers
80
81    Debug markers provide a method for annotating a command stream with markers 
82    for discrete events and groups of commands using a descriptive text marker.
83    These names may then be used by a tool such as a debugger or profiler to 
84    label the command stream.
85    
86    The command
87    
88        void InsertEventMarkerEXT(sizei length, const char *marker);
89        
90    inserts an event marker string <marker> into the command stream. <length> 
91    specifies the length of the string passed in <marker>. If <marker> is a 
92    null-terminated string then <length> should not include the terminator. 
93    If <length> is 0 then <marker> is assumed to be null-terminated.
94
95    The command
96    
97        void PushGroupMarkerEXT(sizei length, const char *marker);
98        
99    pushes a group marker string <marker> into the command stream. <length> 
100    specifies the length of the string passed in <marker>. If <marker> is a 
101    null-terminated string then <length> should not include the terminator. If 
102    <length> is 0 then <marker> is assumed to be null-terminated. If <marker> 
103    is null then an empty string is pushed on the stack.
104        
105    The command
106    
107        void PopGroupMarkerEXT();
108        
109    pops the most recent group marker. If there is no group marker to pop then 
110    the PopGroupMarkerEXT command is ignored.
111    
112    Group markers are strictly hierarchical. Group marker sequences may be 
113    nested within other group markers but can not overlap.
114
115Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State
116Requests)
117
118    None
119
120Errors
121
122    None
123
124New State
125
126    None
127
128New Implementation Dependent State
129
130    None
131
132Issues
133
134    (1) Should the extension provide a method for querying markers?
135    
136    No.
137    
138    A great deal of the value of debug markers is the 'when' as well as the 
139    'what' - seeing the debug markers within the stream of all OpenGL ES 
140    commands.  This value is only available to a tool intercepting the command 
141    stream - it is not available from querying the markers.  However, the 
142    ability to query markers would make them available to developer tools 
143    attaching to an already running application.
144    
145    Querying the markers could be useful for applications to be able to dump 
146    their marker stack to their own logs.  However, this functionality does not 
147    require an extension as applications can implement their own marker stacks 
148    within their code independent of OpenGL ES.
149    
150    (2) Should a query exist for the current marker stack depth?
151    
152    No.
153    
154    This would be useful if markers are queryable but not otherwise.
155        
156    (3) Should PushGroupMarkerEXT & PopGroupMarkerEXT return the marker 
157        stack depth?
158    
159    No.
160     
161    This would be useful if markers are queryable but not otherwise.
162        
163    (4) How should a null-string passed to PushGroupMarkerEXT be treated?
164
165    Resolved: Push an empty string.
166    
167    The two possibilities are to push an empty string onto the marker stack or 
168    to ignore the call to PushGroupMarkerEXT.  Pushing an empty string 
169    maintains the marker stack depth expected by the calling application.
170    
171    (5) Should the extension support printf-style formatting?
172
173    Resolved: No.
174
175    Providing printf-style formatting would impose a much greater burden on the 
176    extension in terms of error checking the format string and arguments.  
177    Likely all languages capable of calling OpenGL ES have convenient 
178    capabilities for formatting strings so it is acceptable to rely on those.
179
180Revision History
181
182    Date 01/17/2011
183    Revision: 1
184       - draft proposal
185
186    Date 07/22/2011
187    Revision: 2
188       - rename from APPLE to EXT
189
190    Date 10/07/2013
191    Revision: 3
192       - Add support for desktop OpenGL
193