updated spec

1 files changed, 104 insertions, 41 deletions

diff --git a/docs/MESA_trace.spec b/docs/MESA_trace.spec
index 4e4fb634c4..85b5312e67 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)
+