• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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