"Fossies" - the Fresh Open Source Software Archive

Member "mesa-20.1.8/docs/specs/OLD/MESA_trace.spec" (16 Sep 2020, 12650 Bytes) of package /linux/misc/mesa-20.1.8.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) RPM Spec source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Name
    2 
    3      MESA_trace
    4 
    5 Name Strings
    6 
    7      GL_MESA_trace
    8 
    9 Contact
   10     
   11     Bernd Kreimeier, Loki Entertainment, bk 'at' lokigames.com
   12     Brian Paul, VA Linux Systems, Inc., brianp 'at' valinux.com
   13 
   14 Status
   15 
   16     Obsolete.
   17 
   18 Version
   19 
   20 
   21 Number
   22 
   23     none yet
   24 
   25 Dependencies
   26 
   27     OpenGL 1.2 is required.
   28     The extension is written against the OpenGL 1.2 Specification
   29 
   30 Overview
   31 
   32     Provides the application with means to enable and disable logging
   33     of GL calls including parameters as readable text. The verbosity
   34     of the generated log can be controlled. The resulting logs are
   35     valid (but possibly incomplete) C code and can be compiled and 
   36     linked for standalone test programs. The set of calls and the 
   37     amount of static data that is logged can be controlled at runtime. 
   38     The application can add comments and enable or disable tracing of GL 
   39     operations at any time. The data flow from the application to GL
   40     and back is unaffected except for timing.
   41 
   42     Application-side implementation of these features raises namespace
   43     and linkage issues. In the driver dispatch table a simple
   44     "chain of responsibility" pattern (aka "composable piepline")
   45     can be added.
   46 
   47 IP Status
   48 
   49     The extension spec is in the public domain.  The current implementation
   50     in Mesa is covered by Mesa's XFree86-style copyright by the authors above.
   51     This extension is partially inspired by the Quake2 QGL wrapper.
   52 
   53 Issues
   54 
   55  
   56     (1) Is this Extension obsolete because it can
   57     be implemented as a wrapper DLL?
   58 
   59       RESOLVED: No. While certain operating systems (Win32) provide linkers 
   60       that facilitate this kind of solution, other operating systems
   61       (Linux) do not support hierarchical linking, so a wrapper solution
   62       would result in symbol collisions.
   63       Further, IHV's might have builtin support for tracing GL execution 
   64       that enjoys privileged access, or that they do not wish to separate
   65       the tracing code from their driver code base.
   66 
   67     (2) Should the Trace API explicitely support the notion of "frames? 
   68     This would require hooking into glXSwapBuffers calls as well.
   69 
   70       RESOLVED: No. The application can use NewTraceMESA/EndTraceMESA
   71       and TraceComment along with external parsing tools to split the 
   72       trace into frames, in whatever way considered adequate.
   73 
   74     (2a) Should GLX calls be traced?
   75 
   76       PBuffers and other render-to-texture solutions demonstrate that
   77       context level commands beyond SwapBuffers might have to be
   78       traced. The GL DLL exports the entry points, so this would not
   79       be out of the question. 
   80 
   81     (3) Should the specification mandate the actual output format?
   82 
   83       RESOLVED: No. It is sufficient to guarantee that all data and commands 
   84       will be traced as requested by Enable/DisableTraceMESA, in the order
   85       encountered. Whether the resulting trace is available as a readable 
   86       text file, binary metafile, compilable source code, much less which 
   87       indentation and formatting has been used, is up to the implementation. 
   88       For the same reason this specification does not enforce or prohibit
   89       additional information added to the trace (statistics, profiling/timing, 
   90       warnings on possible error conditions).
   91 
   92     (4) Should the comment strings associated with names and pointer (ranges) 
   93     be considered persistent state?
   94 
   95       RESOLVED: No. The implementation is not forced to use this information 
   96       on subsequent occurences of name/pointer, and is free to consider it 
   97       transient state.
   98  
   99     (5) Should comment commands be prohibited between Begin/End?
  100 
  101       RESOLVED: Yes, with the exception of TraceCommentMESA. TraceCommentMESA 
  102       is transient, the other commands might cause storage of persistent
  103       data in the context. There is no need to have the ability mark names 
  104       or pointers between Begin and End.
  105 
  106 
  107 New Procedures and Functions
  108  
  109     void NewTraceMESA( bitfield mask, const ubyte * traceName )
  110 
  111     void EndTraceMESA( void )
  112 
  113     void EnableTraceMESA( bitfield mask )
  114 
  115     void DisableTraceMESA( bitfield mask )
  116 
  117     void TraceAssertAttribMESA( bitfield attribMask )
  118 
  119     void TraceCommentMESA( const ubyte* comment )
  120 
  121     void TraceTextureMESA( uint name, const ubyte* comment )
  122 
  123     void TraceListMESA( uint name, const ubyte* comment )
  124 
  125     void TracePointerMESA( void* pointer, const ubyte* comment )
  126 
  127     void TracePointerRangeMESA( const void* first, 
  128                                 const void* last, 
  129                                 const ubyte* comment ) 
  130 
  131 New Tokens
  132  
  133     Accepted by the <mask> parameter of EnableTrace and DisableTrace:
  134 
  135        TRACE_ALL_BITS_MESA           0xFFFF
  136        TRACE_OPERATIONS_BIT_MESA     0x0001
  137        TRACE_PRIMITIVES_BIT_MESA     0x0002
  138        TRACE_ARRAYS_BIT_MESA         0x0004
  139        TRACE_TEXTURES_BIT_MESA       0x0008
  140        TRACE_PIXELS_BIT_MESA         0x0010
  141        TRACE_ERRORS_BIT_MESA         0x0020
  142 
  143     Accepted by the <pname> parameter of GetIntegerv, GetBooleanv,
  144     GetFloatv, and GetDoublev:
  145 
  146        TRACE_MASK_MESA               0x8755
  147 
  148     Accepted by the <pname> parameter to GetString:
  149 
  150        TRACE_NAME_MESA               0x8756
  151 
  152 
  153 Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
  154 
  155     None.
  156 
  157 Additions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation)
  158 
  159     None.
  160 
  161 Additions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation)
  162 
  163     None.
  164 
  165 Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)
  166 
  167     Add a new section:
  168 
  169     5.7 Tracing
  170 
  171     The tracing facility is used to record the execution of a GL program
  172     to a human-readable log.  The log appears as a sequence of GL commands
  173     using C syntax.  The primary intention of tracing is to aid in program
  174     debugging.
  175 
  176     A trace is started with the command
  177 
  178       void NewTraceMESA( bitfield mask, const GLubyte * traceName )
  179 
  180     <mask> may be any value accepted by PushAttrib and specifies a set of
  181     attribute groups.  The state values included in those attribute groups
  182     is written to the trace as a sequence of GL commands.
  183 
  184     <traceName> specifies a name or label for the trace.  It is expected
  185     that <traceName> will be interpreted as a filename in most implementations.
  186 
  187     A trace is ended by calling the command
  188 
  189       void EndTraceMESA( void )
  190 
  191     It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End. 
  192 
  193     The commands
  194 
  195       void EnableTraceMESA( bitfield mask )
  196       void DisableTraceMESA( bitfield mask )
  197 
  198     enable or disable tracing of different classes of GL commands.
  199     <mask> may be the union of any of TRACE_OPERATIONS_BIT_MESA,
  200     TRACE_PRIMITIVES_BIT_MESA, TRACE_ARRAYS_BIT_MESA, TRACE_TEXTURES_BIT_MESA,
  201     and TRACE_PIXELS_BIT_MESA.  The special token TRACE_ALL_BITS_MESA
  202     indicates all classes of commands are to be logged.
  203 
  204     TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of
  205     Begin/End, including Begin/End.
  206   
  207     TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of
  208     Begin/End, including Begin/End.
  209  
  210     TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer, NormalPointer,
  211     ColorPointer, IndexPointer, TexCoordPointer and EdgeFlagPointer commands.
  212 
  213     TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by
  214     TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, and
  215     TexSubImage3D commands.
  216 
  217     TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by
  218     Bitmap and DrawPixels commands.
  219 
  220     TRACE_ERRORS_BIT_MESA controls logging of all errors. If this bit is 
  221     set, GetError will be executed whereever applicable, and the result will 
  222     be added to the trace as a comment. The error returns are cached and 
  223     returned to the application on its GetError calls. If the user does not 
  224     wish the additional GetError calls to be performed, this bit should not
  225     be set.
  226     
  227     The command
  228 
  229       void TraceCommentMESA( const ubyte* comment )
  230 
  231     immediately adds the <comment> string to the trace output, surrounded
  232     by C-style comment delimiters.
  233 
  234     The commands
  235 
  236       void TraceTextureMESA( uint name, const ubyte* comment )
  237       void TraceListMESA( uint name, const ubyte* comment )
  238 
  239     associates <comment> with the texture object or display list specified
  240     by <name>.  Logged commands which reference the named texture object or
  241     display list will be annotated with <comment>.  If IsTexture(name) or
  242     IsList(name) fail (respectively) the command is quietly ignored.
  243 
  244     The commands
  245 
  246       void TracePointerMESA( void* pointer, const ubyte* comment )
  247 
  248       void TracePointerRangeMESA( const void* first, 
  249                                   const void* last,
  250                                   const ubyte* comment ) 
  251 
  252     associate <comment> with the address specified by <pointer> or with
  253     a range of addresses specified by <first> through <last>.
  254     Any logged commands which reference <pointer> or an address between
  255     <first> and <last> will be annotated with <comment>.
  256 
  257     The command
  258 
  259       void TraceAssertAttribMESA( bitfield attribMask )
  260 
  261     will add GL state queries and assertion statements to the log to
  262     confirm that the current state at the time TraceAssertAttrib is
  263     executed matches the current state when the trace log is executed
  264     in the future.
  265 
  266     <attribMask> is any value accepted by PushAttrib and specifies
  267     the groups of state variables which are to be asserted.
  268 
  269     The commands NewTraceMESA, EndTraceMESA, EnableTraceMESA, DisableTraceMESA,
  270     TraceAssertAttribMESA, TraceCommentMESA, TraceTextureMESA, TraceListMESA, 
  271     TracePointerMESA and TracePointerRangeMESA are not compiled into display lists.
  272 
  273 
  274     Examples:
  275 
  276     The command NewTraceMESA(DEPTH_BUFFER_BIT, "log") will query the state
  277     variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE
  278     to get the values <test>, <func>, <mask>, and <clear> respectively.
  279     Statements equivalent to the following will then be logged:
  280 
  281        glEnable(GL_DEPTH_TEST);   (if <test> is true)
  282        glDisable(GL_DEPTH_TEST);  (if <test> is false)
  283        glDepthFunc(<func>); 
  284        glDepthMask(<mask>);
  285        glClearDepth(<clear>);
  286    
  287 
  288     The command TraceAssertAttribMESA(DEPTH_BUFFER_BIT) will query the state
  289     variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE
  290     to get the values <test>, <func>, <mask>, and <clear> respectively.
  291     The resulting trace might then look will like this:
  292 
  293     {
  294       GLboolean b;
  295       GLint i;
  296       GLfloat f;
  297       b = glIsEnabled(GL_DEPTH_TEST);
  298       assert(b == <test>);
  299       glGetIntegerv(GL_DEPTH_FUNC, &i);
  300       assert(i == <func>);
  301       glGetIntegerv(GL_DEPTH_MASK, &i);
  302       assert(i == <mask>);
  303       glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f);
  304       assert(f == <clear>);
  305     }
  306 
  307 
  308 Additions to Chapter 6 of the OpenGL 1.2.1 Specification 
  309     (State and State Requests)
  310 
  311     Querying TRACE_MASK_MESA with GetIntegerv, GetFloatv, GetBooleanv or
  312     GetDoublev returns the current command class trace mask.
  313 
  314     Querying TRACE_NAME_MESA with GetString returns the current trace name.
  315 
  316 
  317 Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance)
  318 
  319     The MESA_trace extension can be used in a way that does not affect data 
  320     flow from application to OpenGL, as well as data flow from OpenGL to 
  321     application, except for timing, possible print I/O. TRACE_ERRORS_BIT_MESA
  322     will add additional GetError queries. Setting a trace mask with NewTraceMESA
  323     as well as use of TraceAssertAttribMESA might cause additional state queries.
  324     With the possible exception of performance, OpenGL rendering should not be
  325     affected at all by a properly chosen logging operation.
  326 
  327 Additions to the AGL/GLX/WGL Specifications
  328 
  329     None.
  330 
  331 GLX Protocol
  332 
  333     None. The logging operation is carried out client-side, by exporting
  334     entry points to the wrapper functions that execute the logging operation.
  335 
  336 Errors
  337 
  338     INVALID_OPERATION is generated if any trace command except TraceCommentMESA
  339     is called between Begin and End.
  340 
  341 New State
  342 
  343     The current trace name and current command class mask are stored
  344     per-context.
  345 
  346 New Implementation Dependent State
  347 
  348     None.
  349 
  350 Revision History
  351 
  352   * Revision 0.1 - Initial draft from template (bk000415)
  353   * Revision 0.2 - Draft (bk000906)
  354   * Revision 0.3 - Draft (bk000913)
  355   * Revision 0.4 - Reworked text, fixed typos (bp000914)
  356   * Revision 0.5 - Assigned final GLenum values (bp001103)
  357   * Revision 0.6 - TRACE_ERRORS_BIT_MESA (bk000916)
  358   * Revision 0.7 - Added MESA postfix (bk010126)
  359