1Name
2
3     MESA_trace
4
5Name Strings
6
7     GL_MESA_trace
8
9Contact
10    
11    Bernd Kreimeier, Loki Entertainment, bk 'at' lokigames.com
12    Brian Paul, VA Linux Systems, Inc., brianp 'at' valinux.com
13
14Status
15
16    Obsolete.
17
18Version
19
20
21Number
22
23    none yet
24
25Dependencies
26
27    OpenGL 1.2 is required.
28    The extension is written against the OpenGL 1.2 Specification
29
30Overview
31
32    Provides the application with means to enable and disable logging
33    of GL calls including parameters as readable text. The verbosity
34    of the generated log can be controlled. The resulting logs are
35    valid (but possibly incomplete) C code and can be compiled and 
36    linked for standalone test programs. The set of calls and the 
37    amount of static data that is logged can be controlled at runtime. 
38    The application can add comments and enable or disable tracing of GL 
39    operations at any time. The data flow from the application to GL
40    and back is unaffected except for timing.
41
42    Application-side implementation of these features raises namespace
43    and linkage issues. In the driver dispatch table a simple
44    "chain of responsibility" pattern (aka "composable piepline")
45    can be added.
46
47IP Status
48
49    The extension spec is in the public domain.  The current implementation
50    in Mesa is covered by Mesa's XFree86-style copyright by the authors above.
51    This extension is partially inspired by the Quake2 QGL wrapper.
52
53Issues
54
55 
56    (1) Is this Extension obsolete because it can
57    be implemented as a wrapper DLL?
58
59      RESOLVED: No. While certain operating systems (Win32) provide linkers 
60      that facilitate this kind of solution, other operating systems
61      (Linux) do not support hierarchical linking, so a wrapper solution
62      would result in symbol collisions.
63      Further, IHV's might have builtin support for tracing GL execution 
64      that enjoys privileged access, or that they do not wish to separate
65      the tracing code from their driver code base.
66
67    (2) Should the Trace API explicitely support the notion of "frames? 
68    This would require hooking into glXSwapBuffers calls as well.
69
70      RESOLVED: No. The application can use NewTraceMESA/EndTraceMESA
71      and TraceComment along with external parsing tools to split the 
72      trace into frames, in whatever way considered adequate.
73
74    (2a) Should GLX calls be traced?
75
76      PBuffers and other render-to-texture solutions demonstrate that
77      context level commands beyond SwapBuffers might have to be
78      traced. The GL DLL exports the entry points, so this would not
79      be out of the question. 
80
81    (3) Should the specification mandate the actual output format?
82
83      RESOLVED: No. It is sufficient to guarantee that all data and commands 
84      will be traced as requested by Enable/DisableTraceMESA, in the order
85      encountered. Whether the resulting trace is available as a readable 
86      text file, binary metafile, compilable source code, much less which 
87      indentation and formatting has been used, is up to the implementation. 
88      For the same reason this specification does not enforce or prohibit
89      additional information added to the trace (statistics, profiling/timing, 
90      warnings on possible error conditions).
91
92    (4) Should the comment strings associated with names and pointer (ranges) 
93    be considered persistent state?
94
95      RESOLVED: No. The implementation is not forced to use this information 
96      on subsequent occurences of name/pointer, and is free to consider it 
97      transient state.
98 
99    (5) Should comment commands be prohibited between Begin/End?
100
101      RESOLVED: Yes, with the exception of TraceCommentMESA. TraceCommentMESA 
102      is transient, the other commands might cause storage of persistent
103      data in the context. There is no need to have the ability mark names 
104      or pointers between Begin and End.
105
106
107New Procedures and Functions
108 
109    void NewTraceMESA( bitfield mask, const ubyte * traceName )
110
111    void EndTraceMESA( void )
112
113    void EnableTraceMESA( bitfield mask )
114
115    void DisableTraceMESA( bitfield mask )
116
117    void TraceAssertAttribMESA( bitfield attribMask )
118
119    void TraceCommentMESA( const ubyte* comment )
120
121    void TraceTextureMESA( uint name, const ubyte* comment )
122
123    void TraceListMESA( uint name, const ubyte* comment )
124
125    void TracePointerMESA( void* pointer, const ubyte* comment )
126
127    void TracePointerRangeMESA( const void* first, 
128                                const void* last, 
129                                const ubyte* comment ) 
130
131New Tokens
132 
133    Accepted by the <mask> parameter of EnableTrace and DisableTrace:
134
135       TRACE_ALL_BITS_MESA           0xFFFF
136       TRACE_OPERATIONS_BIT_MESA     0x0001
137       TRACE_PRIMITIVES_BIT_MESA     0x0002
138       TRACE_ARRAYS_BIT_MESA         0x0004
139       TRACE_TEXTURES_BIT_MESA       0x0008
140       TRACE_PIXELS_BIT_MESA         0x0010
141       TRACE_ERRORS_BIT_MESA         0x0020
142
143    Accepted by the <pname> parameter of GetIntegerv, GetBooleanv,
144    GetFloatv, and GetDoublev:
145
146       TRACE_MASK_MESA               0x8755
147
148    Accepted by the <pname> parameter to GetString:
149
150       TRACE_NAME_MESA               0x8756
151
152
153Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
154
155    None.
156
157Additions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation)
158
159    None.
160
161Additions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation)
162
163    None.
164
165Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)
166
167    Add a new section:
168
169    5.7 Tracing
170
171    The tracing facility is used to record the execution of a GL program
172    to a human-readable log.  The log appears as a sequence of GL commands
173    using C syntax.  The primary intention of tracing is to aid in program
174    debugging.
175
176    A trace is started with the command
177
178      void NewTraceMESA( bitfield mask, const GLubyte * traceName )
179
180    <mask> may be any value accepted by PushAttrib and specifies a set of
181    attribute groups.  The state values included in those attribute groups
182    is written to the trace as a sequence of GL commands.
183
184    <traceName> specifies a name or label for the trace.  It is expected
185    that <traceName> will be interpreted as a filename in most implementations.
186
187    A trace is ended by calling the command
188
189      void EndTraceMESA( void )
190
191    It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End. 
192
193    The commands
194
195      void EnableTraceMESA( bitfield mask )
196      void DisableTraceMESA( bitfield mask )
197
198    enable or disable tracing of different classes of GL commands.
199    <mask> may be the union of any of TRACE_OPERATIONS_BIT_MESA,
200    TRACE_PRIMITIVES_BIT_MESA, TRACE_ARRAYS_BIT_MESA, TRACE_TEXTURES_BIT_MESA,
201    and TRACE_PIXELS_BIT_MESA.  The special token TRACE_ALL_BITS_MESA
202    indicates all classes of commands are to be logged.
203
204    TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of
205    Begin/End, including Begin/End.
206  
207    TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of
208    Begin/End, including Begin/End.
209 
210    TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer, NormalPointer,
211    ColorPointer, IndexPointer, TexCoordPointer and EdgeFlagPointer commands.
212
213    TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by
214    TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, and
215    TexSubImage3D commands.
216
217    TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by
218    Bitmap and DrawPixels commands.
219
220    TRACE_ERRORS_BIT_MESA controls logging of all errors. If this bit is 
221    set, GetError will be executed whereever applicable, and the result will 
222    be added to the trace as a comment. The error returns are cached and 
223    returned to the application on its GetError calls. If the user does not 
224    wish the additional GetError calls to be performed, this bit should not
225    be set.
226    
227    The command
228
229      void TraceCommentMESA( const ubyte* comment )
230
231    immediately adds the <comment> string to the trace output, surrounded
232    by C-style comment delimiters.
233
234    The commands
235
236      void TraceTextureMESA( uint name, const ubyte* comment )
237      void TraceListMESA( uint name, const ubyte* comment )
238
239    associates <comment> with the texture object or display list specified
240    by <name>.  Logged commands which reference the named texture object or
241    display list will be annotated with <comment>.  If IsTexture(name) or
242    IsList(name) fail (respectively) the command is quietly ignored.
243
244    The commands
245
246      void TracePointerMESA( void* pointer, const ubyte* comment )
247
248      void TracePointerRangeMESA( const void* first, 
249                                  const void* last,
250                                  const ubyte* comment ) 
251
252    associate <comment> with the address specified by <pointer> or with
253    a range of addresses specified by <first> through <last>.
254    Any logged commands which reference <pointer> or an address between
255    <first> and <last> will be annotated with <comment>.
256
257    The command
258
259      void TraceAssertAttribMESA( bitfield attribMask )
260
261    will add GL state queries and assertion statements to the log to
262    confirm that the current state at the time TraceAssertAttrib is
263    executed matches the current state when the trace log is executed
264    in the future.
265
266    <attribMask> is any value accepted by PushAttrib and specifies
267    the groups of state variables which are to be asserted.
268
269    The commands NewTraceMESA, EndTraceMESA, EnableTraceMESA, DisableTraceMESA,
270    TraceAssertAttribMESA, TraceCommentMESA, TraceTextureMESA, TraceListMESA, 
271    TracePointerMESA and TracePointerRangeMESA are not compiled into display lists.
272
273
274    Examples:
275
276    The command NewTraceMESA(DEPTH_BUFFER_BIT, "log") will query the state
277    variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE
278    to get the values <test>, <func>, <mask>, and <clear> respectively.
279    Statements equivalent to the following will then be logged:
280
281       glEnable(GL_DEPTH_TEST);   (if <test> is true)
282       glDisable(GL_DEPTH_TEST);  (if <test> is false)
283       glDepthFunc(<func>); 
284       glDepthMask(<mask>);
285       glClearDepth(<clear>);
286   
287
288    The command TraceAssertAttribMESA(DEPTH_BUFFER_BIT) will query the state
289    variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE
290    to get the values <test>, <func>, <mask>, and <clear> respectively.
291    The resulting trace might then look will like this:
292
293    {
294      GLboolean b;
295      GLint i;
296      GLfloat f;
297      b = glIsEnabled(GL_DEPTH_TEST);
298      assert(b == <test>);
299      glGetIntegerv(GL_DEPTH_FUNC, &i);
300      assert(i == <func>);
301      glGetIntegerv(GL_DEPTH_MASK, &i);
302      assert(i == <mask>);
303      glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f);
304      assert(f == <clear>);
305    }
306
307
308Additions to Chapter 6 of the OpenGL 1.2.1 Specification 
309    (State and State Requests)
310
311    Querying TRACE_MASK_MESA with GetIntegerv, GetFloatv, GetBooleanv or
312    GetDoublev returns the current command class trace mask.
313
314    Querying TRACE_NAME_MESA with GetString returns the current trace name.
315
316
317Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance)
318
319    The MESA_trace extension can be used in a way that does not affect data 
320    flow from application to OpenGL, as well as data flow from OpenGL to 
321    application, except for timing, possible print I/O. TRACE_ERRORS_BIT_MESA
322    will add additional GetError queries. Setting a trace mask with NewTraceMESA
323    as well as use of TraceAssertAttribMESA might cause additional state queries.
324    With the possible exception of performance, OpenGL rendering should not be
325    affected at all by a properly chosen logging operation.
326
327Additions to the AGL/GLX/WGL Specifications
328
329    None.
330
331GLX Protocol
332
333    None. The logging operation is carried out client-side, by exporting
334    entry points to the wrapper functions that execute the logging operation.
335
336Errors
337
338    INVALID_OPERATION is generated if any trace command except TraceCommentMESA
339    is called between Begin and End.
340
341New State
342
343    The current trace name and current command class mask are stored
344    per-context.
345
346New Implementation Dependent State
347
348    None.
349
350Revision History
351
352  * Revision 0.1 - Initial draft from template (bk000415)
353  * Revision 0.2 - Draft (bk000906)
354  * Revision 0.3 - Draft (bk000913)
355  * Revision 0.4 - Reworked text, fixed typos (bp000914)
356  * Revision 0.5 - Assigned final GLenum values (bp001103)
357  * Revision 0.6 - TRACE_ERRORS_BIT_MESA (bk000916)
358  * Revision 0.7 - Added MESA postfix (bk010126)
359
360