diff options
Diffstat (limited to 'nx-X11/extras/Mesa/docs/MESA_trace.spec')
| -rw-r--r-- | nx-X11/extras/Mesa/docs/MESA_trace.spec | 360 |
1 files changed, 0 insertions, 360 deletions
diff --git a/nx-X11/extras/Mesa/docs/MESA_trace.spec b/nx-X11/extras/Mesa/docs/MESA_trace.spec deleted file mode 100644 index 3db569d2b..000000000 --- a/nx-X11/extras/Mesa/docs/MESA_trace.spec +++ /dev/null @@ -1,360 +0,0 @@ -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 - - $Id: MESA_trace.spec,v 1.1.1.3 2004/08/12 23:43:24 anholt Exp $ - -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) - |