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 360
