-XXX - Not complete yet!!!
-
Name
MESA_trace
Version
- $Id: MESA_trace.spec,v 1.1 2000/11/03 15:10:04 brianp Exp $
+ $Id: MESA_trace.spec,v 1.2 2001/01/29 16:10:18 brianp Exp $
Number
- ???
+ none yet
Dependencies
Issues
- none yet
+
+ (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 NewTraceMESA( bitfield mask, const ubyte * traceName )
void EndTraceMESA( void )
void TraceAssertAttribMESA( bitfield attribMask )
- void TraceCommentMESA( const ubyte *comment )
+ void TraceCommentMESA( const ubyte* comment )
- void TraceTextureMESA( uint name, const ubyte *comment )
+ void TraceTextureMESA( uint name, const ubyte* comment )
- void TraceListMESA( uint name, const ubyte *comment )
+ void TraceListMESA( uint name, const ubyte* comment )
- void TracePointerMESA( void *pointer, const ubyte *comment )
+ void TracePointerMESA( void* pointer, const ubyte* comment )
- void TracePointerRangeMESA( const void *first, const void *last,
- 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 0x0001
- TRACE_OPERATIONS_BIT_MESA 0x0002
- TRACE_PRIMITIVES_BIT_MESA 0x0004
- TRACE_ARRAYS_BIT_MESA 0x0008
- TRACE_TEXTURES_BIT_MESA 0x0010
- TRACE_PIXELS_BIT_MESA 0x0020
+ 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_NAME_MESA 0x8756
+
Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
None.
void EndTraceMESA( void )
- It is illegal to call NewTrace or EndTrace between Begin and End.
+ It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End.
The commands
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_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 )
void TracePointerMESA( void* pointer, const ubyte* comment )
- void TracePointerRangeMESA( const void* first, const void* last,
- 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>.
<attribMask> is any value accepted by PushAttrib and specifies
the groups of state variables which are to be asserted.
- The commands NewTrace, EndTrace, EnableTrace, DisableTrace,
- TraceAssertAttrib, TraceComment, TraceTexture, TraceList, TracePointer,
- TracePointerRange, GetTraceName and GetTraceMask are not compiled
- into display lists.
+ The commands NewTraceMESA, EndTraceMESA, EnableTraceMESA, DisableTraceMESA,
+ TraceAssertAttribMESA, TraceCommentMESA, TraceTextureMESA, TraceListMESA,
+ TracePointerMESA and TracePointerRangeMESA are not compiled into display lists.
Examples:
- The command NewTrace(DEPTH_BUFFER_BIT, "log") will query the state
+ 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:
glClearDepth(<clear>);
- The command TraceAssertAttrib(DEPTH_BUFFER_BIT) will query the state
+ 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.
- Statements equivalent to the following will then be logged:
+ The resulting trace might then look will like this:
{
GLboolean b;
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_tracelog extension 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, and sequence of GetError queries. With
- the possible exception of performance, OpenGL rendering should not be
- affect by the logging operation.
+ 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.
- ? Hooking into glXSwapBuffers() ?
GLX Protocol
Errors
- INVALID_OPERATION is generated if any trace command except TraceComment
+ INVALID_OPERATION is generated if any trace command except TraceCommentMESA
is called between Begin and End.
New State
Revision History
- * Revision 0.1 - Initial draft from template (bk000415)
- * Revision 0.2 - Draft (bk000906)
- * Revision 0.3 - Draft (bk000913)
- * Revision 0.4 - Added GetTraceName/Mask, fixed typos (bp000914)
- * Revision 0.5 - Assigned final GLenum values
+ * 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 / commitdiff