docs/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     $Id: MESA_trace.spec,v 1.4 2004/03/25 01:42:42 brianp Exp $
  21
  22 Number
  23
  24     none yet
  25
  26 Dependencies
  27
  28     OpenGL 1.2 is required.
  29     The extension is written against the OpenGL 1.2 Specification
  30
  31 Overview
  32
  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.
  42
  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")
  46     can be added.
  47
  48 IP Status
  49
  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.
  53
  54 Issues
  55
  56
  57     (1) Is this Extension obsolete because it can
  58     be implemented as a wrapper DLL?
  59
  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.
  67
  68     (2) Should the Trace API explicitely support the notion of "frames?
  69     This would require hooking into glXSwapBuffers calls as well.
  70
  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.
  74
  75     (2a) Should GLX calls be traced?
  76
  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.
  81
  82     (3) Should the specification mandate the actual output format?
  83
  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).
  92
  93     (4) Should the comment strings associated with names and pointer (ranges)
  94     be considered persistent state?
  95
  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
  98       transient state.
  99
 100     (5) Should comment commands be prohibited between Begin/End?
 101
 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.
 106
 107
 108 New Procedures and Functions
 109
 110     void NewTraceMESA( bitfield mask, const ubyte * traceName )
 111
 112     void EndTraceMESA( void )
 113
 114     void EnableTraceMESA( bitfield mask )
 115
 116     void DisableTraceMESA( bitfield mask )
 117
 118     void TraceAssertAttribMESA( bitfield attribMask )
 119
 120     void TraceCommentMESA( const ubyte* comment )
 121
 122     void TraceTextureMESA( uint name, const ubyte* comment )
 123
 124     void TraceListMESA( uint name, const ubyte* comment )
 125
 126     void TracePointerMESA( void* pointer, const ubyte* comment )
 127
 128     void TracePointerRangeMESA( const void* first,
 129                                 const void* last,
 130                                 const ubyte* comment )
 131
 132 New Tokens
 133
 134     Accepted by the <mask> parameter of EnableTrace and DisableTrace:
 135
 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
 143
 144     Accepted by the <pname> parameter of GetIntegerv, GetBooleanv,
 145     GetFloatv, and GetDoublev:
 146
 147        TRACE_MASK_MESA               0x8755
 148
 149     Accepted by the <pname> parameter to GetString:
 150
 151        TRACE_NAME_MESA               0x8756
 152
 153
 154 Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
 155
 156     None.
 157
 158 Additions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation)
 159
 160     None.
 161
 162 Additions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation)
 163
 164     None.
 165
 166 Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)
 167
 168     Add a new section:
 169
 170     5.7 Tracing
 171
 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
 175     debugging.
 176
 177     A trace is started with the command
 178
 179       void NewTraceMESA( bitfield mask, const GLubyte * traceName )
 180
 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.
 184
 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.
 187
 188     A trace is ended by calling the command
 189
 190       void EndTraceMESA( void )
 191
 192     It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End.
 193
 194     The commands
 195
 196       void EnableTraceMESA( bitfield mask )
 197       void DisableTraceMESA( bitfield mask )
 198
 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.
 204
 205     TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of
 206     Begin/End, including Begin/End.
 207
 208     TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of
 209     Begin/End, including Begin/End.
 210
 211     TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer, NormalPointer,
 212     ColorPointer, IndexPointer, TexCoordPointer and EdgeFlagPointer commands.
 213
 214     TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by
 215     TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, and
 216     TexSubImage3D commands.
 217
 218     TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by
 219     Bitmap and DrawPixels commands.
 220
 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
 226     be set.
 227
 228     The command
 229
 230       void TraceCommentMESA( const ubyte* comment )
 231
 232     immediately adds the <comment> string to the trace output, surrounded
 233     by C-style comment delimiters.
 234
 235     The commands
 236
 237       void TraceTextureMESA( uint name, const ubyte* comment )
 238       void TraceListMESA( uint name, const ubyte* comment )
 239
 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.
 244
 245     The commands
 246
 247       void TracePointerMESA( void* pointer, const ubyte* comment )
 248
 249       void TracePointerRangeMESA( const void* first,
 250                                   const void* last,
 251                                   const ubyte* comment )
 252
 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>.
 257
 258     The command
 259
 260       void TraceAssertAttribMESA( bitfield attribMask )
 261
 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
 265     in the future.
 266
 267     <attribMask> is any value accepted by PushAttrib and specifies
 268     the groups of state variables which are to be asserted.
 269
 270     The commands NewTraceMESA, EndTraceMESA, EnableTraceMESA, DisableTraceMESA,
 271     TraceAssertAttribMESA, TraceCommentMESA, TraceTextureMESA, TraceListMESA,
 272     TracePointerMESA and TracePointerRangeMESA are not compiled into display lists.
 273
 274
 275     Examples:
 276
 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:
 281
 282        glEnable(GL_DEPTH_TEST);   (if <test> is true)
 283        glDisable(GL_DEPTH_TEST);  (if <test> is false)
 284        glDepthFunc(<func>);
 285        glDepthMask(<mask>);
 286        glClearDepth(<clear>);
 287
 288
 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:
 293
 294     {
 295       GLboolean b;
 296       GLint i;
 297       GLfloat f;
 298       b = glIsEnabled(GL_DEPTH_TEST);
 299       assert(b == <test>);
 300       glGetIntegerv(GL_DEPTH_FUNC, &i);
 301       assert(i == <func>);
 302       glGetIntegerv(GL_DEPTH_MASK, &i);
 303       assert(i == <mask>);
 304       glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f);
 305       assert(f == <clear>);
 306     }
 307
 308
 309 Additions to Chapter 6 of the OpenGL 1.2.1 Specification
 310     (State and State Requests)
 311
 312     Querying TRACE_MASK_MESA with GetIntegerv, GetFloatv, GetBooleanv or
 313     GetDoublev returns the current command class trace mask.
 314
 315     Querying TRACE_NAME_MESA with GetString returns the current trace name.
 316
 317
 318 Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance)
 319
 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.
 327
 328 Additions to the AGL/GLX/WGL Specifications
 329
 330     None.
 331
 332 GLX Protocol
 333
 334     None. The logging operation is carried out client-side, by exporting
 335     entry points to the wrapper functions that execute the logging operation.
 336
 337 Errors
 338
 339     INVALID_OPERATION is generated if any trace command except TraceCommentMESA
 340     is called between Begin and End.
 341
 342 New State
 343
 344     The current trace name and current command class mask are stored
 345     per-context.
 346
 347 New Implementation Dependent State
 348
 349     None.
 350
 351 Revision History
 352
 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)
 360