1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
|
XXX - Not complete yet!!!
Name
MESA_trace
Name Strings
GL_MESA_TRACE
Contact
Bernd Kreimeier, Loki Entertainment, bk 'at' lokigames.com
Brian Paul, VA Linux Systems, Inc., brianp 'at' valinux.com
Status
XXX - Not complete yet!!!
Version
$Id: MESA_trace.spec,v 1.1 2000/11/03 15:10:04 brianp Exp $
Number
???
Dependencies
OpenGL 1.2 is required.
The extension is written against the OpenGL 1.2 Specification
Overview
Provides the application with means to enable and disable logging
of GL calls including parameters as readable text. The verbosity
of the generated log can be controlled. The resulting logs are
valid (but possibly incomplete) C code and can be compiled and
linked for standalone test programs. The set of calls and the
amount of static data that is logged can be controlled at runtime.
The application can add comments and enable or disable tracing of GL
operations at any time. The data flow from the application to GL
and back is unaffected except for timing.
Application-side implementation of these features raises namespace
and linkage issues. In the driver dispatch table a simple
"chain of responsibility" pattern (aka "composable piepline")
can be added.
IP Status
The extension spec is in the public domain. The current implementation
in Mesa is covered by Mesa's XFree86-style copyright by the authors above.
This extension is partially inspired by the Quake2 QGL wrapper.
Issues
none yet
New Procedures and Functions
void NewTraceMESA( bitfield mask, const ubyte *traceName )
void EndTraceMESA( void )
void EnableTraceMESA( bitfield mask )
void DisableTraceMESA( bitfield mask )
void TraceAssertAttribMESA( bitfield attribMask )
void TraceCommentMESA( const ubyte *comment )
void TraceTextureMESA( uint name, const ubyte *comment )
void TraceListMESA( uint name, const ubyte *comment )
void TracePointerMESA( void *pointer, const ubyte *comment )
void TracePointerRangeMESA( const void *first, const void *last,
const ubyte *comment )
New Tokens
Accepted by the <mask> parameter of EnableTrace and DisableTrace:
TRACE_ALL_BITS_MESA 0x0001
TRACE_OPERATIONS_BIT_MESA 0x0002
TRACE_PRIMITIVES_BIT_MESA 0x0004
TRACE_ARRAYS_BIT_MESA 0x0008
TRACE_TEXTURES_BIT_MESA 0x0010
TRACE_PIXELS_BIT_MESA 0x0020
Accepted by the <pname> parameter of GetIntegerv, GetBooleanv,
GetFloatv, and GetDoublev:
TRACE_MASK_MESA 0x8755
Accepted by the <pname> parameter to GetString:
TRACE_NAME_MESA 0x8756
Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
None.
Additions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation)
None.
Additions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation)
None.
Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)
Add a new section:
5.7 Tracing
The tracing facility is used to record the execution of a GL program
to a human-readable log. The log appears as a sequence of GL commands
using C syntax. The primary intention of tracing is to aid in program
debugging.
A trace is started with the command
void NewTraceMESA( bitfield mask, const GLubyte * traceName )
<mask> may be any value accepted by PushAttrib and specifies a set of
attribute groups. The state values included in those attribute groups
is written to the trace as a sequence of GL commands.
<traceName> specifies a name or label for the trace. It is expected
that <traceName> will be interpreted as a filename in most implementations.
A trace is ended by calling the command
void EndTraceMESA( void )
It is illegal to call NewTrace or EndTrace between Begin and End.
The commands
void EnableTraceMESA( bitfield mask )
void DisableTraceMESA( bitfield mask )
enable or disable tracing of different classes of GL commands.
<mask> may be the union of any of TRACE_OPERATIONS_BIT_MESA,
TRACE_PRIMITIVES_BIT_MESA, TRACE_ARRAYS_BIT_MESA, TRACE_TEXTURES_BIT_MESA,
and TRACE_PIXELS_BIT_MESA. The special token TRACE_ALL_BITS_MESA
indicates all classes of commands are to be logged.
TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of
Begin/End, including Begin/End.
TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of
Begin/End, including Begin/End.
TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer, NormalPointer,
ColorPointer, IndexPointer, TexCoordPointer and EdgeFlagPointer commands.
TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by
TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, and
TexSubImage3D commands.
TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by
Bitmap and DrawPixels commands.
The command
void TraceCommentMESA( const ubyte* comment )
immediately adds the <comment> string to the trace output, surrounded
by C-style comment delimiters.
The commands
void TraceTextureMESA( uint name, const ubyte* comment )
void TraceListMESA( uint name, const ubyte* comment )
associates <comment> with the texture object or display list specified
by <name>. Logged commands which reference the named texture object or
display list will be annotated with <comment>. If IsTexture(name) or
IsList(name) fail (respectively) the command is quietly ignored.
The commands
void TracePointerMESA( void* pointer, const ubyte* comment )
void TracePointerRangeMESA( const void* first, const void* last,
const ubyte* comment )
associate <comment> with the address specified by <pointer> or with
a range of addresses specified by <first> through <last>.
Any logged commands which reference <pointer> or an address between
<first> and <last> will be annotated with <comment>.
The command
void TraceAssertAttribMESA( bitfield attribMask )
will add GL state queries and assertion statements to the log to
confirm that the current state at the time TraceAssertAttrib is
executed matches the current state when the trace log is executed
in the future.
<attribMask> is any value accepted by PushAttrib and specifies
the groups of state variables which are to be asserted.
The commands NewTrace, EndTrace, EnableTrace, DisableTrace,
TraceAssertAttrib, TraceComment, TraceTexture, TraceList, TracePointer,
TracePointerRange, GetTraceName and GetTraceMask are not compiled
into display lists.
Examples:
The command NewTrace(DEPTH_BUFFER_BIT, "log") will query the state
variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE
to get the values <test>, <func>, <mask>, and <clear> respectively.
Statements equivalent to the following will then be logged:
glEnable(GL_DEPTH_TEST); (if <test> is true)
glDisable(GL_DEPTH_TEST); (if <test> is false)
glDepthFunc(<func>);
glDepthMask(<mask>);
glClearDepth(<clear>);
The command TraceAssertAttrib(DEPTH_BUFFER_BIT) will query the state
variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE
to get the values <test>, <func>, <mask>, and <clear> respectively.
Statements equivalent to the following will then be logged:
{
GLboolean b;
GLint i;
GLfloat f;
b = glIsEnabled(GL_DEPTH_TEST);
assert(b == <test>);
glGetIntegerv(GL_DEPTH_FUNC, &i);
assert(i == <func>);
glGetIntegerv(GL_DEPTH_MASK, &i);
assert(i == <mask>);
glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f);
assert(f == <clear>);
}
Additions to Chapter 6 of the OpenGL 1.2.1 Specification
(State and State Requests)
Querying TRACE_MASK_MESA with GetIntegerv, GetFloatv, GetBooleanv or
GetDoublev returns the current command class trace mask.
Querying TRACE_NAME_MESA with GetString returns the current trace name.
Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance)
The MESA_tracelog extension does not affect data flow from application
to OpenGL, as well as data flow from OpenGL to application, except for
timing, possible print I/O, and sequence of GetError queries. With
the possible exception of performance, OpenGL rendering should not be
affect by the logging operation.
Additions to the AGL/GLX/WGL Specifications
None.
? Hooking into glXSwapBuffers() ?
GLX Protocol
None. The logging operation is carried out client-side, by exporting
entry points to the wrapper functions that execute the logging operation.
Errors
INVALID_OPERATION is generated if any trace command except TraceComment
is called between Begin and End.
New State
The current trace name and current command class mask are stored
per-context.
New Implementation Dependent State
None.
Revision History
* Revision 0.1 - Initial draft from template (bk000415)
* Revision 0.2 - Draft (bk000906)
* Revision 0.3 - Draft (bk000913)
* Revision 0.4 - Added GetTraceName/Mask, fixed typos (bp000914)
* Revision 0.5 - Assigned final GLenum values
|
