--- /dev/null
+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
+
+
+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)
+
projects / mesa.git / blobdiff