docs/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