11 Bernd Kreimeier
, Loki Entertainment
, bk 'at' lokigames.com
12 Brian Paul
, VA Linux Systems
, Inc.
, brianp 'at' valinux.com
20 $Id
: MESA_trace.spec
,v
1.4 2004/03/25 01:42:42 brianp Exp $
28 OpenGL
1.2 is required.
29 The extension is written against the OpenGL
1.2 Specification
33 Provides the application with means to
enable and disable logging
34 of GL calls including parameters as readable text. The verbosity
35 of the generated log can be controlled. The resulting logs are
36 valid
(but possibly incomplete
) C code and can be compiled and
37 linked
for standalone
test programs. The
set of calls and the
38 amount of static data that is logged can be controlled at runtime.
39 The application can add comments and
enable or disable tracing of GL
40 operations at any
time. The data flow from the application to GL
41 and back is unaffected except
for timing.
43 Application
-side implementation of these features raises namespace
44 and linkage issues. In the driver dispatch table a simple
45 "chain of responsibility" pattern
(aka "composable piepline"
)
50 The extension spec is
in the public domain. The current implementation
51 in Mesa is covered by Mesa's XFree86
-style copyright by the authors above.
52 This extension is partially inspired by the Quake2 QGL wrapper.
57 (1) Is this Extension obsolete because it can
58 be implemented as a wrapper DLL?
60 RESOLVED
: No. While certain operating systems
(Win32
) provide linkers
61 that facilitate this kind of solution
, other operating systems
62 (Linux
) do not support hierarchical linking
, so a wrapper solution
63 would result
in symbol collisions.
64 Further
, IHV's might have
builtin support
for tracing GL execution
65 that enjoys privileged access
, or that they
do not wish to separate
66 the tracing code from their driver code base.
68 (2) Should the Trace API explicitely support the notion of "frames?
69 This would require hooking into glXSwapBuffers calls as well.
71 RESOLVED
: No. The application can use NewTraceMESA
/EndTraceMESA
72 and TraceComment along with external parsing tools to split the
73 trace into frames
, in whatever way considered adequate.
75 (2a
) Should GLX calls be traced?
77 PBuffers and other render
-to
-texture solutions demonstrate that
78 context level commands beyond SwapBuffers might have to be
79 traced. The GL DLL exports the entry points
, so this would not
80 be out of the question.
82 (3) Should the specification mandate the actual output format?
84 RESOLVED
: No. It is sufficient to guarantee that all data and commands
85 will be traced as requested by Enable
/DisableTraceMESA
, in the order
86 encountered. Whether the resulting trace is available as a readable
87 text file
, binary metafile
, compilable
source code
, much less which
88 indentation and formatting has been used
, is up to the implementation.
89 For the same reason this specification does not enforce or prohibit
90 additional information added to the trace
(statistics
, profiling
/timing
,
91 warnings on possible error conditions
).
93 (4) Should the comment strings associated with names and pointer
(ranges
)
94 be considered persistent state?
96 RESOLVED
: No. The implementation is not forced to use this information
97 on subsequent occurences of name
/pointer
, and is free to consider it
100 (5) Should comment commands be prohibited between Begin
/End?
102 RESOLVED
: Yes
, with the exception of TraceCommentMESA. TraceCommentMESA
103 is transient
, the other commands might cause storage of persistent
104 data
in the context. There is no need to have the ability mark names
105 or pointers between Begin and End.
108 New Procedures and Functions
110 void NewTraceMESA
( bitfield mask
, const ubyte
* traceName
)
112 void EndTraceMESA
( void
)
114 void EnableTraceMESA
( bitfield mask
)
116 void DisableTraceMESA
( bitfield mask
)
118 void TraceAssertAttribMESA
( bitfield attribMask
)
120 void TraceCommentMESA
( const ubyte
* comment
)
122 void TraceTextureMESA
( uint name
, const ubyte
* comment
)
124 void TraceListMESA
( uint name
, const ubyte
* comment
)
126 void TracePointerMESA
( void
* pointer
, const ubyte
* comment
)
128 void TracePointerRangeMESA
( const void
* first
,
130 const ubyte
* comment
)
134 Accepted by the
<mask
> parameter of EnableTrace and DisableTrace
:
136 TRACE_ALL_BITS_MESA
0xFFFF
137 TRACE_OPERATIONS_BIT_MESA
0x0001
138 TRACE_PRIMITIVES_BIT_MESA
0x0002
139 TRACE_ARRAYS_BIT_MESA
0x0004
140 TRACE_TEXTURES_BIT_MESA
0x0008
141 TRACE_PIXELS_BIT_MESA
0x0010
142 TRACE_ERRORS_BIT_MESA
0x0020
144 Accepted by the
<pname
> parameter of GetIntegerv
, GetBooleanv
,
145 GetFloatv
, and GetDoublev
:
147 TRACE_MASK_MESA
0x8755
149 Accepted by the
<pname
> parameter to GetString
:
151 TRACE_NAME_MESA
0x8756
154 Additions to Chapter
2 of the OpenGL
1.2.1 Specification
(OpenGL Operation
)
158 Additions to Chapter
3 of the OpenGL
1.2.1 Specification
(OpenGL Operation
)
162 Additions to Chapter
4 of the OpenGL
1.2.1 Specification
(OpenGL Operation
)
166 Additions to Chapter
5 of the OpenGL
1.2.1 Specification
(Special Functions
)
172 The tracing facility is used to record the execution of a GL program
173 to a human
-readable log. The log appears as a sequence of GL commands
174 using C syntax. The primary intention of tracing is to aid
in program
177 A trace is started with the
command
179 void NewTraceMESA
( bitfield mask
, const GLubyte
* traceName
)
181 <mask
> may be any value accepted by PushAttrib and specifies a
set of
182 attribute groups. The state values included
in those attribute groups
183 is written to the trace as a sequence of GL commands.
185 <traceName
> specifies a name or label
for the trace. It is expected
186 that
<traceName
> will be interpreted as a filename
in most implementations.
188 A trace is ended by calling the
command
190 void EndTraceMESA
( void
)
192 It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End.
196 void EnableTraceMESA
( bitfield mask
)
197 void DisableTraceMESA
( bitfield mask
)
199 enable or disable tracing of different classes of GL commands.
200 <mask
> may be the union of any of TRACE_OPERATIONS_BIT_MESA
,
201 TRACE_PRIMITIVES_BIT_MESA
, TRACE_ARRAYS_BIT_MESA
, TRACE_TEXTURES_BIT_MESA
,
202 and TRACE_PIXELS_BIT_MESA. The special token TRACE_ALL_BITS_MESA
203 indicates all classes of commands are to be logged.
205 TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of
206 Begin
/End
, including Begin
/End.
208 TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of
209 Begin
/End
, including Begin
/End.
211 TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer
, NormalPointer
,
212 ColorPointer
, IndexPointer
, TexCoordPointer and EdgeFlagPointer commands.
214 TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by
215 TexImage1D
, TexImage2D
, TexImage3D
, TexSubImage1D
, TexSubImage2D
, and
216 TexSubImage3D commands.
218 TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by
219 Bitmap and DrawPixels commands.
221 TRACE_ERRORS_BIT_MESA controls logging of all errors. If this bit is
222 set, GetError will be executed whereever applicable
, and the result will
223 be added to the trace as a comment. The error returns are cached and
224 returned to the application on its GetError calls. If the user does not
225 wish the additional GetError calls to be performed
, this bit should not
230 void TraceCommentMESA
( const ubyte
* comment
)
232 immediately adds the
<comment
> string to the trace output
, surrounded
233 by C
-style comment delimiters.
237 void TraceTextureMESA
( uint name
, const ubyte
* comment
)
238 void TraceListMESA
( uint name
, const ubyte
* comment
)
240 associates
<comment
> with the texture object or display list specified
241 by
<name
>. Logged commands which reference the named texture object or
242 display list will be annotated with
<comment
>. If IsTexture
(name
) or
243 IsList
(name
) fail
(respectively
) the
command is quietly ignored.
247 void TracePointerMESA
( void
* pointer
, const ubyte
* comment
)
249 void TracePointerRangeMESA
( const void
* first
,
251 const ubyte
* comment
)
253 associate
<comment
> with the address specified by
<pointer
> or with
254 a range of addresses specified by
<first
> through
<last
>.
255 Any logged commands which reference
<pointer
> or an address between
256 <first
> and
<last
> will be annotated with
<comment
>.
260 void TraceAssertAttribMESA
( bitfield attribMask
)
262 will add GL state queries and assertion statements to the log to
263 confirm that the current state at the
time TraceAssertAttrib is
264 executed matches the current state when the trace log is executed
267 <attribMask
> is any value accepted by PushAttrib and specifies
268 the groups of state variables which are to be asserted.
270 The commands NewTraceMESA
, EndTraceMESA
, EnableTraceMESA
, DisableTraceMESA
,
271 TraceAssertAttribMESA
, TraceCommentMESA
, TraceTextureMESA
, TraceListMESA
,
272 TracePointerMESA and TracePointerRangeMESA are not compiled into display lists.
277 The
command NewTraceMESA
(DEPTH_BUFFER_BIT
, "log"
) will query the state
278 variables DEPTH_TEST
, DEPTH_FUNC
, DEPTH_WRITEMASK
, and DEPTH_CLEAR_VALUE
279 to get the values
<test>, <func
>, <mask
>, and
<clear
> respectively.
280 Statements equivalent to the following will
then be logged
:
282 glEnable
(GL_DEPTH_TEST
); (if <test> is true
)
283 glDisable
(GL_DEPTH_TEST
); (if <test> is false
)
286 glClearDepth
(<clear
>);
289 The
command TraceAssertAttribMESA
(DEPTH_BUFFER_BIT
) will query the state
290 variables DEPTH_TEST
, DEPTH_FUNC
, DEPTH_WRITEMASK
, and DEPTH_CLEAR_VALUE
291 to get the values
<test>, <func
>, <mask
>, and
<clear
> respectively.
292 The resulting trace might
then look will like this
:
298 b
= glIsEnabled
(GL_DEPTH_TEST
);
300 glGetIntegerv
(GL_DEPTH_FUNC
, &i
);
302 glGetIntegerv
(GL_DEPTH_MASK
, &i
);
304 glGetFloatv
(GL_DEPTH_CLEAR_VALUE
, &f
);
305 assert
(f
== <clear
>);
309 Additions to Chapter
6 of the OpenGL
1.2.1 Specification
310 (State and State Requests
)
312 Querying TRACE_MASK_MESA with GetIntegerv
, GetFloatv
, GetBooleanv or
313 GetDoublev returns the current
command class trace mask.
315 Querying TRACE_NAME_MESA with GetString returns the current trace name.
318 Additions to Appendix A of the OpenGL
1.2.1 Specification
(Invariance
)
320 The MESA_trace extension can be used
in a way that does not affect data
321 flow from application to OpenGL
, as well as data flow from OpenGL to
322 application
, except
for timing
, possible print I
/O. TRACE_ERRORS_BIT_MESA
323 will add additional GetError queries. Setting a trace mask with NewTraceMESA
324 as well as use of TraceAssertAttribMESA might cause additional state queries.
325 With the possible exception of performance
, OpenGL rendering should not be
326 affected at all by a properly chosen logging operation.
328 Additions to the AGL
/GLX
/WGL Specifications
334 None. The logging operation is carried out client
-side
, by exporting
335 entry points to the wrapper functions that execute the logging operation.
339 INVALID_OPERATION is generated
if any trace
command except TraceCommentMESA
340 is called between Begin and End.
344 The current trace name and current
command class mask are stored
347 New Implementation Dependent State
353 * Revision
0.1 - Initial draft from template
(bk000415
)
354 * Revision
0.2 - Draft
(bk000906
)
355 * Revision
0.3 - Draft
(bk000913
)
356 * Revision
0.4 - Reworked text
, fixed typos
(bp000914
)
357 * Revision
0.5 - Assigned final GLenum values
(bp001103
)
358 * Revision
0.6 - TRACE_ERRORS_BIT_MESA
(bk000916
)
359 * Revision
0.7 - Added MESA postfix
(bk010126
)