18e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulName 28e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 38e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul MESA_trace 48e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 58e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulName Strings 68e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 7d3b09fe29b112ddf114d14849e917befafd8387aBrian Paul GL_MESA_trace 88e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 98e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulContact 108e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 118e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Bernd Kreimeier, Loki Entertainment, bk 'at' lokigames.com 128e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Brian Paul, VA Linux Systems, Inc., brianp 'at' valinux.com 138e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 148e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulStatus 158e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 16361a9ac9663205b10ae78022ed777dfeda2a8ea4Brian Paul Obsolete. 178e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 188e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulVersion 198e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 208e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 218e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulNumber 228e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 23d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul none yet 248e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 258e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulDependencies 268e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 278e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul OpenGL 1.2 is required. 288e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul The extension is written against the OpenGL 1.2 Specification 298e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 308e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulOverview 318e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 328e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Provides the application with means to enable and disable logging 338e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul of GL calls including parameters as readable text. The verbosity 348e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul of the generated log can be controlled. The resulting logs are 358e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul valid (but possibly incomplete) C code and can be compiled and 368e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul linked for standalone test programs. The set of calls and the 378e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul amount of static data that is logged can be controlled at runtime. 388e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul The application can add comments and enable or disable tracing of GL 398e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul operations at any time. The data flow from the application to GL 408e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul and back is unaffected except for timing. 418e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 428e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Application-side implementation of these features raises namespace 438e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul and linkage issues. In the driver dispatch table a simple 448e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul "chain of responsibility" pattern (aka "composable piepline") 458e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul can be added. 468e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 478e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulIP Status 488e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 498e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul The extension spec is in the public domain. The current implementation 508e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul in Mesa is covered by Mesa's XFree86-style copyright by the authors above. 518e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul This extension is partially inspired by the Quake2 QGL wrapper. 528e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 538e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulIssues 548e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 55d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 56d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul (1) Is this Extension obsolete because it can 57d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul be implemented as a wrapper DLL? 58d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 59d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul RESOLVED: No. While certain operating systems (Win32) provide linkers 60d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul that facilitate this kind of solution, other operating systems 61d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul (Linux) do not support hierarchical linking, so a wrapper solution 62d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul would result in symbol collisions. 63d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul Further, IHV's might have builtin support for tracing GL execution 64d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul that enjoys privileged access, or that they do not wish to separate 65d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul the tracing code from their driver code base. 66d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 67d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul (2) Should the Trace API explicitely support the notion of "frames? 68d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul This would require hooking into glXSwapBuffers calls as well. 69d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 70d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul RESOLVED: No. The application can use NewTraceMESA/EndTraceMESA 71d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul and TraceComment along with external parsing tools to split the 72d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul trace into frames, in whatever way considered adequate. 73d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 74d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul (2a) Should GLX calls be traced? 75d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 76d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul PBuffers and other render-to-texture solutions demonstrate that 77d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul context level commands beyond SwapBuffers might have to be 78d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul traced. The GL DLL exports the entry points, so this would not 79d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul be out of the question. 80d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 81d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul (3) Should the specification mandate the actual output format? 82d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 83d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul RESOLVED: No. It is sufficient to guarantee that all data and commands 84d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul will be traced as requested by Enable/DisableTraceMESA, in the order 85d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul encountered. Whether the resulting trace is available as a readable 86d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul text file, binary metafile, compilable source code, much less which 87d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul indentation and formatting has been used, is up to the implementation. 88d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul For the same reason this specification does not enforce or prohibit 89d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul additional information added to the trace (statistics, profiling/timing, 90d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul warnings on possible error conditions). 91d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 92d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul (4) Should the comment strings associated with names and pointer (ranges) 93d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul be considered persistent state? 94d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 95d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul RESOLVED: No. The implementation is not forced to use this information 96d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul on subsequent occurences of name/pointer, and is free to consider it 97d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul transient state. 98d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 99d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul (5) Should comment commands be prohibited between Begin/End? 100d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 101d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul RESOLVED: Yes, with the exception of TraceCommentMESA. TraceCommentMESA 102d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul is transient, the other commands might cause storage of persistent 103d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul data in the context. There is no need to have the ability mark names 104d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul or pointers between Begin and End. 105d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 1068e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1078e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulNew Procedures and Functions 1088e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 109d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul void NewTraceMESA( bitfield mask, const ubyte * traceName ) 1108e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1118e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void EndTraceMESA( void ) 1128e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1138e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void EnableTraceMESA( bitfield mask ) 1148e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1158e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void DisableTraceMESA( bitfield mask ) 1168e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1178e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void TraceAssertAttribMESA( bitfield attribMask ) 1188e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 119d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul void TraceCommentMESA( const ubyte* comment ) 1208e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 121d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul void TraceTextureMESA( uint name, const ubyte* comment ) 1228e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 123d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul void TraceListMESA( uint name, const ubyte* comment ) 1248e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 125d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul void TracePointerMESA( void* pointer, const ubyte* comment ) 1268e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 127d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul void TracePointerRangeMESA( const void* first, 128d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul const void* last, 129d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul const ubyte* comment ) 1308e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1318e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulNew Tokens 1328e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1338e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Accepted by the <mask> parameter of EnableTrace and DisableTrace: 1348e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 135d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul TRACE_ALL_BITS_MESA 0xFFFF 136d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul TRACE_OPERATIONS_BIT_MESA 0x0001 137d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul TRACE_PRIMITIVES_BIT_MESA 0x0002 138d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul TRACE_ARRAYS_BIT_MESA 0x0004 139d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul TRACE_TEXTURES_BIT_MESA 0x0008 140d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul TRACE_PIXELS_BIT_MESA 0x0010 141d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul TRACE_ERRORS_BIT_MESA 0x0020 1428e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1438e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Accepted by the <pname> parameter of GetIntegerv, GetBooleanv, 1448e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul GetFloatv, and GetDoublev: 1458e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1468e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul TRACE_MASK_MESA 0x8755 1478e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1488e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Accepted by the <pname> parameter to GetString: 1498e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1508e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul TRACE_NAME_MESA 0x8756 1518e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 152d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 1538e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulAdditions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) 1548e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1558e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul None. 1568e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1578e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulAdditions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation) 1588e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1598e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul None. 1608e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1618e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulAdditions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation) 1628e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1638e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul None. 1648e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1658e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulAdditions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 1668e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1678e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Add a new section: 1688e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1698e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 5.7 Tracing 1708e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1718e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul The tracing facility is used to record the execution of a GL program 1728e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul to a human-readable log. The log appears as a sequence of GL commands 1738e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul using C syntax. The primary intention of tracing is to aid in program 1748e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul debugging. 1758e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1768e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul A trace is started with the command 1778e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1788e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void NewTraceMESA( bitfield mask, const GLubyte * traceName ) 1798e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1808e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul <mask> may be any value accepted by PushAttrib and specifies a set of 1818e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul attribute groups. The state values included in those attribute groups 1828e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul is written to the trace as a sequence of GL commands. 1838e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1848e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul <traceName> specifies a name or label for the trace. It is expected 1858e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul that <traceName> will be interpreted as a filename in most implementations. 1868e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1878e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul A trace is ended by calling the command 1888e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1898e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void EndTraceMESA( void ) 1908e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 191d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End. 1928e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1938e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul The commands 1948e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1958e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void EnableTraceMESA( bitfield mask ) 1968e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void DisableTraceMESA( bitfield mask ) 1978e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 1988e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul enable or disable tracing of different classes of GL commands. 1998e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul <mask> may be the union of any of TRACE_OPERATIONS_BIT_MESA, 2008e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul TRACE_PRIMITIVES_BIT_MESA, TRACE_ARRAYS_BIT_MESA, TRACE_TEXTURES_BIT_MESA, 2018e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul and TRACE_PIXELS_BIT_MESA. The special token TRACE_ALL_BITS_MESA 2028e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul indicates all classes of commands are to be logged. 2038e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2048e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of 2058e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Begin/End, including Begin/End. 2068e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2078e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of 2088e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Begin/End, including Begin/End. 209d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 2108e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer, NormalPointer, 2118e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul ColorPointer, IndexPointer, TexCoordPointer and EdgeFlagPointer commands. 2128e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2138e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by 2148e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, and 2158e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul TexSubImage3D commands. 2168e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2178e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by 2188e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Bitmap and DrawPixels commands. 2198e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 220d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul TRACE_ERRORS_BIT_MESA controls logging of all errors. If this bit is 221d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul set, GetError will be executed whereever applicable, and the result will 222d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul be added to the trace as a comment. The error returns are cached and 223d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul returned to the application on its GetError calls. If the user does not 224d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul wish the additional GetError calls to be performed, this bit should not 225d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul be set. 226d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 2278e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul The command 2288e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2298e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void TraceCommentMESA( const ubyte* comment ) 2308e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2318e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul immediately adds the <comment> string to the trace output, surrounded 2328e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul by C-style comment delimiters. 2338e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2348e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul The commands 2358e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2368e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void TraceTextureMESA( uint name, const ubyte* comment ) 2378e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void TraceListMESA( uint name, const ubyte* comment ) 2388e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2398e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul associates <comment> with the texture object or display list specified 2408e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul by <name>. Logged commands which reference the named texture object or 2418e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul display list will be annotated with <comment>. If IsTexture(name) or 2428e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul IsList(name) fail (respectively) the command is quietly ignored. 2438e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2448e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul The commands 2458e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2468e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void TracePointerMESA( void* pointer, const ubyte* comment ) 2478e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 248d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul void TracePointerRangeMESA( const void* first, 249d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul const void* last, 250d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul const ubyte* comment ) 2518e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2528e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul associate <comment> with the address specified by <pointer> or with 2538e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul a range of addresses specified by <first> through <last>. 2548e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Any logged commands which reference <pointer> or an address between 2558e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul <first> and <last> will be annotated with <comment>. 2568e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2578e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul The command 2588e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2598e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul void TraceAssertAttribMESA( bitfield attribMask ) 2608e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2618e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul will add GL state queries and assertion statements to the log to 2628e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul confirm that the current state at the time TraceAssertAttrib is 2638e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul executed matches the current state when the trace log is executed 2648e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul in the future. 2658e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2668e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul <attribMask> is any value accepted by PushAttrib and specifies 2678e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul the groups of state variables which are to be asserted. 2688e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 269d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul The commands NewTraceMESA, EndTraceMESA, EnableTraceMESA, DisableTraceMESA, 270d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul TraceAssertAttribMESA, TraceCommentMESA, TraceTextureMESA, TraceListMESA, 271d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul TracePointerMESA and TracePointerRangeMESA are not compiled into display lists. 2728e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2738e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2748e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Examples: 2758e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 276d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul The command NewTraceMESA(DEPTH_BUFFER_BIT, "log") will query the state 2778e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE 2788e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul to get the values <test>, <func>, <mask>, and <clear> respectively. 2798e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Statements equivalent to the following will then be logged: 2808e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2818e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul glEnable(GL_DEPTH_TEST); (if <test> is true) 2828e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul glDisable(GL_DEPTH_TEST); (if <test> is false) 2838e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul glDepthFunc(<func>); 2848e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul glDepthMask(<mask>); 2858e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul glClearDepth(<clear>); 2868e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2878e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 288d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul The command TraceAssertAttribMESA(DEPTH_BUFFER_BIT) will query the state 2898e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE 2908e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul to get the values <test>, <func>, <mask>, and <clear> respectively. 291d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul The resulting trace might then look will like this: 2928e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 2938e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul { 2948e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul GLboolean b; 2958e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul GLint i; 2968e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul GLfloat f; 2978e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul b = glIsEnabled(GL_DEPTH_TEST); 2988e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul assert(b == <test>); 2998e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul glGetIntegerv(GL_DEPTH_FUNC, &i); 3008e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul assert(i == <func>); 3018e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul glGetIntegerv(GL_DEPTH_MASK, &i); 3028e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul assert(i == <mask>); 3038e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f); 3048e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul assert(f == <clear>); 3058e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul } 3068e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3078e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3088e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulAdditions to Chapter 6 of the OpenGL 1.2.1 Specification 3098e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul (State and State Requests) 3108e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3118e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Querying TRACE_MASK_MESA with GetIntegerv, GetFloatv, GetBooleanv or 3128e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul GetDoublev returns the current command class trace mask. 3138e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3148e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul Querying TRACE_NAME_MESA with GetString returns the current trace name. 3158e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 316d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 3178e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulAdditions to Appendix A of the OpenGL 1.2.1 Specification (Invariance) 3188e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 319d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul The MESA_trace extension can be used in a way that does not affect data 320d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul flow from application to OpenGL, as well as data flow from OpenGL to 321d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul application, except for timing, possible print I/O. TRACE_ERRORS_BIT_MESA 322d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul will add additional GetError queries. Setting a trace mask with NewTraceMESA 323d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul as well as use of TraceAssertAttribMESA might cause additional state queries. 324d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul With the possible exception of performance, OpenGL rendering should not be 325d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul affected at all by a properly chosen logging operation. 3268e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3278e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulAdditions to the AGL/GLX/WGL Specifications 3288e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3298e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul None. 3308e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3318e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulGLX Protocol 3328e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3338e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul None. The logging operation is carried out client-side, by exporting 3348e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul entry points to the wrapper functions that execute the logging operation. 3358e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3368e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulErrors 3378e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 338d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul INVALID_OPERATION is generated if any trace command except TraceCommentMESA 3398e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul is called between Begin and End. 3408e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3418e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulNew State 3428e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3438e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul The current trace name and current command class mask are stored 3448e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul per-context. 3458e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3468e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulNew Implementation Dependent State 3478e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3488e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul None. 3498e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 3508e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian PaulRevision History 3518e4fa8c3e690ef106c3ec8944b9202716fb1e193Brian Paul 352d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul * Revision 0.1 - Initial draft from template (bk000415) 353d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul * Revision 0.2 - Draft (bk000906) 354d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul * Revision 0.3 - Draft (bk000913) 355d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul * Revision 0.4 - Reworked text, fixed typos (bp000914) 356d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul * Revision 0.5 - Assigned final GLenum values (bp001103) 357d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul * Revision 0.6 - TRACE_ERRORS_BIT_MESA (bk000916) 358d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul * Revision 0.7 - Added MESA postfix (bk010126) 359d6dd0fceb15d65fd82efd15a5a18a906c6a79e3eBrian Paul 360