← Back to branch summary

~ubuntu-branches/ubuntu/trusty/mesa-lts-utopic/trusty-proposed

« back to all changes in this revision

Viewing changes to docs/specs/OLD/MESA_trace.spec

  • Committer: Package Import Robot
  • Author(s): Maarten Lankhorst
  • Date: 2015-01-06 10:38:32 UTC
  • Revision ID: package-import@ubuntu.com-20150106103832-u6rqp9wfmojb1gnu
Tags: upstream-10.3.2
Import upstream version 10.3.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/specs/OLD/MESA_trace.spec
 
1
Name
 
2
 
 
3
     MESA_trace
 
4
 
 
5
Name Strings
 
6
 
 
7
     GL_MESA_trace
 
8
 
 
9
Contact
 
10
    
 
11
    Bernd Kreimeier, Loki Entertainment, bk 'at' lokigames.com
 
12
    Brian Paul, VA Linux Systems, Inc., brianp 'at' valinux.com
 
13
 
 
14
Status
 
15
 
 
16
    Obsolete.
 
17
 
 
18
Version
 
19
 
 
20
 
 
21
Number
 
22
 
 
23
    none yet
 
24
 
 
25
Dependencies
 
26
 
 
27
    OpenGL 1.2 is required.
 
28
    The extension is written against the OpenGL 1.2 Specification
 
29
 
 
30
Overview
 
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
 
 
47
IP 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
 
 
53
Issues
 
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
 
 
107
New 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
 
 
131
New 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
 
 
153
Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
 
154
 
 
155
    None.
 
156
 
 
157
Additions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation)
 
158
 
 
159
    None.
 
160
 
 
161
Additions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation)
 
162
 
 
163
    None.
 
164
 
 
165
Additions 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
 
 
308
Additions 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
 
 
317
Additions 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
 
 
327
Additions to the AGL/GLX/WGL Specifications
 
328
 
 
329
    None.
 
330
 
 
331
GLX 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
 
 
336
Errors
 
337
 
 
338
    INVALID_OPERATION is generated if any trace command except TraceCommentMESA
 
339
    is called between Begin and End.
 
340
 
 
341
New State
 
342
 
 
343
    The current trace name and current command class mask are stored
 
344
    per-context.
 
345
 
 
346
New Implementation Dependent State
 
347
 
 
348
    None.
 
349
 
 
350
Revision 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