Name MESA_trace Name Strings GL_MESA_trace Contact Bernd Kreimeier, Loki Entertainment, bk 'at' lokigames.com Brian Paul, VA Linux Systems, Inc., brianp 'at' valinux.com Status Obsolete. Version $Id: MESA_trace.spec,v 1.4 2004/03/25 01:42:42 brianp Exp $ Number none yet Dependencies OpenGL 1.2 is required. The extension is written against the OpenGL 1.2 Specification Overview Provides the application with means to enable and disable logging of GL calls including parameters as readable text. The verbosity of the generated log can be controlled. The resulting logs are valid (but possibly incomplete) C code and can be compiled and linked for standalone test programs. The set of calls and the amount of static data that is logged can be controlled at runtime. The application can add comments and enable or disable tracing of GL operations at any time. The data flow from the application to GL and back is unaffected except for timing. Application-side implementation of these features raises namespace and linkage issues. In the driver dispatch table a simple "chain of responsibility" pattern (aka "composable piepline") can be added. IP Status The extension spec is in the public domain. The current implementation in Mesa is covered by Mesa's XFree86-style copyright by the authors above. This extension is partially inspired by the Quake2 QGL wrapper. Issues (1) Is this Extension obsolete because it can be implemented as a wrapper DLL? RESOLVED: No. While certain operating systems (Win32) provide linkers that facilitate this kind of solution, other operating systems (Linux) do not support hierarchical linking, so a wrapper solution would result in symbol collisions. Further, IHV's might have builtin support for tracing GL execution that enjoys privileged access, or that they do not wish to separate the tracing code from their driver code base. (2) Should the Trace API explicitely support the notion of "frames? This would require hooking into glXSwapBuffers calls as well. RESOLVED: No. The application can use NewTraceMESA/EndTraceMESA and TraceComment along with external parsing tools to split the trace into frames, in whatever way considered adequate. (2a) Should GLX calls be traced? PBuffers and other render-to-texture solutions demonstrate that context level commands beyond SwapBuffers might have to be traced. The GL DLL exports the entry points, so this would not be out of the question. (3) Should the specification mandate the actual output format? RESOLVED: No. It is sufficient to guarantee that all data and commands will be traced as requested by Enable/DisableTraceMESA, in the order encountered. Whether the resulting trace is available as a readable text file, binary metafile, compilable source code, much less which indentation and formatting has been used, is up to the implementation. For the same reason this specification does not enforce or prohibit additional information added to the trace (statistics, profiling/timing, warnings on possible error conditions). (4) Should the comment strings associated with names and pointer (ranges) be considered persistent state? RESOLVED: No. The implementation is not forced to use this information on subsequent occurences of name/pointer, and is free to consider it transient state. (5) Should comment commands be prohibited between Begin/End? RESOLVED: Yes, with the exception of TraceCommentMESA. TraceCommentMESA is transient, the other commands might cause storage of persistent data in the context. There is no need to have the ability mark names or pointers between Begin and End. New Procedures and Functions void NewTraceMESA( bitfield mask, const ubyte * traceName ) void EndTraceMESA( void ) void EnableTraceMESA( bitfield mask ) void DisableTraceMESA( bitfield mask ) void TraceAssertAttribMESA( bitfield attribMask ) void TraceCommentMESA( const ubyte* comment ) void TraceTextureMESA( uint name, const ubyte* comment ) void TraceListMESA( uint name, const ubyte* comment ) void TracePointerMESA( void* pointer, const ubyte* comment ) void TracePointerRangeMESA( const void* first, const void* last, const ubyte* comment ) New Tokens Accepted by the <mask> parameter of EnableTrace and DisableTrace: TRACE_ALL_BITS_MESA 0xFFFF TRACE_OPERATIONS_BIT_MESA 0x0001 TRACE_PRIMITIVES_BIT_MESA 0x0002 TRACE_ARRAYS_BIT_MESA 0x0004 TRACE_TEXTURES_BIT_MESA 0x0008 TRACE_PIXELS_BIT_MESA 0x0010 TRACE_ERRORS_BIT_MESA 0x0020 Accepted by the <pname> parameter of GetIntegerv, GetBooleanv, GetFloatv, and GetDoublev: TRACE_MASK_MESA 0x8755 Accepted by the <pname> parameter to GetString: TRACE_NAME_MESA 0x8756 Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) None. Additions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation) None. Additions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation) None. Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) Add a new section: 5.7 Tracing The tracing facility is used to record the execution of a GL program to a human-readable log. The log appears as a sequence of GL commands using C syntax. The primary intention of tracing is to aid in program debugging. A trace is started with the command void NewTraceMESA( bitfield mask, const GLubyte * traceName ) <mask> may be any value accepted by PushAttrib and specifies a set of attribute groups. The state values included in those attribute groups is written to the trace as a sequence of GL commands. <traceName> specifies a name or label for the trace. It is expected that <traceName> will be interpreted as a filename in most implementations. A trace is ended by calling the command void EndTraceMESA( void ) It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End. The commands void EnableTraceMESA( bitfield mask ) void DisableTraceMESA( bitfield mask ) enable or disable tracing of different classes of GL commands. <mask> may be the union of any of TRACE_OPERATIONS_BIT_MESA, TRACE_PRIMITIVES_BIT_MESA, TRACE_ARRAYS_BIT_MESA, TRACE_TEXTURES_BIT_MESA, and TRACE_PIXELS_BIT_MESA. The special token TRACE_ALL_BITS_MESA indicates all classes of commands are to be logged. TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of Begin/End, including Begin/End. TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of Begin/End, including Begin/End. TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer, NormalPointer, ColorPointer, IndexPointer, TexCoordPointer and EdgeFlagPointer commands. TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, and TexSubImage3D commands. TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by Bitmap and DrawPixels commands. TRACE_ERRORS_BIT_MESA controls logging of all errors. If this bit is set, GetError will be executed whereever applicable, and the result will be added to the trace as a comment. The error returns are cached and returned to the application on its GetError calls. If the user does not wish the additional GetError calls to be performed, this bit should not be set. The command void TraceCommentMESA( const ubyte* comment ) immediately adds the <comment> string to the trace output, surrounded by C-style comment delimiters. The commands void TraceTextureMESA( uint name, const ubyte* comment ) void TraceListMESA( uint name, const ubyte* comment ) associates <comment> with the texture object or display list specified by <name>. Logged commands which reference the named texture object or display list will be annotated with <comment>. If IsTexture(name) or IsList(name) fail (respectively) the command is quietly ignored. The commands void TracePointerMESA( void* pointer, const ubyte* comment ) void TracePointerRangeMESA( const void* first, const void* last, const ubyte* comment ) associate <comment> with the address specified by <pointer> or with a range of addresses specified by <first> through <last>. Any logged commands which reference <pointer> or an address between <first> and <last> will be annotated with <comment>. The command void TraceAssertAttribMESA( bitfield attribMask ) will add GL state queries and assertion statements to the log to confirm that the current state at the time TraceAssertAttrib is executed matches the current state when the trace log is executed in the future. <attribMask> is any value accepted by PushAttrib and specifies the groups of state variables which are to be asserted. The commands NewTraceMESA, EndTraceMESA, EnableTraceMESA, DisableTraceMESA, TraceAssertAttribMESA, TraceCommentMESA, TraceTextureMESA, TraceListMESA, TracePointerMESA and TracePointerRangeMESA are not compiled into display lists. Examples: The command NewTraceMESA(DEPTH_BUFFER_BIT, "log") will query the state variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE to get the values <test>, <func>, <mask>, and <clear> respectively. Statements equivalent to the following will then be logged: glEnable(GL_DEPTH_TEST); (if <test> is true) glDisable(GL_DEPTH_TEST); (if <test> is false) glDepthFunc(<func>); glDepthMask(<mask>); glClearDepth(<clear>); The command TraceAssertAttribMESA(DEPTH_BUFFER_BIT) will query the state variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE to get the values <test>, <func>, <mask>, and <clear> respectively. The resulting trace might then look will like this: { GLboolean b; GLint i; GLfloat f; b = glIsEnabled(GL_DEPTH_TEST); assert(b == <test>); glGetIntegerv(GL_DEPTH_FUNC, &i); assert(i == <func>); glGetIntegerv(GL_DEPTH_MASK, &i); assert(i == <mask>); glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f); assert(f == <clear>); } Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State Requests) Querying TRACE_MASK_MESA with GetIntegerv, GetFloatv, GetBooleanv or GetDoublev returns the current command class trace mask. Querying TRACE_NAME_MESA with GetString returns the current trace name. Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance) The MESA_trace extension can be used in a way that does not affect data flow from application to OpenGL, as well as data flow from OpenGL to application, except for timing, possible print I/O. TRACE_ERRORS_BIT_MESA will add additional GetError queries. Setting a trace mask with NewTraceMESA as well as use of TraceAssertAttribMESA might cause additional state queries. With the possible exception of performance, OpenGL rendering should not be affected at all by a properly chosen logging operation. Additions to the AGL/GLX/WGL Specifications None. GLX Protocol None. The logging operation is carried out client-side, by exporting entry points to the wrapper functions that execute the logging operation. Errors INVALID_OPERATION is generated if any trace command except TraceCommentMESA is called between Begin and End. New State The current trace name and current command class mask are stored per-context. New Implementation Dependent State None. Revision History * Revision 0.1 - Initial draft from template (bk000415) * Revision 0.2 - Draft (bk000906) * Revision 0.3 - Draft (bk000913) * Revision 0.4 - Reworked text, fixed typos (bp000914) * Revision 0.5 - Assigned final GLenum values (bp001103) * Revision 0.6 - TRACE_ERRORS_BIT_MESA (bk000916) * Revision 0.7 - Added MESA postfix (bk010126)