diff options
| -rw-r--r-- | docs/MESA_trace.spec | 145 |
1 files changed, 104 insertions, 41 deletions
diff --git a/docs/MESA_trace.spec b/docs/MESA_trace.spec index 4e4fb634c48..85b5312e676 100644 --- a/docs/MESA_trace.spec +++ b/docs/MESA_trace.spec @@ -1,5 +1,3 @@ -XXX - Not complete yet!!! - Name MESA_trace @@ -19,11 +17,11 @@ Status 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 @@ -55,11 +53,61 @@ IP Status 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 ) @@ -69,27 +117,29 @@ New Procedures and Functions 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: @@ -100,6 +150,7 @@ New Tokens TRACE_NAME_MESA 0x8756 + Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) None. @@ -138,7 +189,7 @@ Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 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 @@ -156,7 +207,7 @@ Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 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. @@ -167,6 +218,13 @@ Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 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 ) @@ -188,8 +246,9 @@ Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 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>. @@ -208,15 +267,14 @@ Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) <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: @@ -228,10 +286,10 @@ Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 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; @@ -256,18 +314,20 @@ Additions to Chapter 6 of the OpenGL 1.2.1 Specification 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 @@ -276,7 +336,7 @@ 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 @@ -290,8 +350,11 @@ New Implementation Dependent 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) + |