diff options
Diffstat (limited to 'docs/OLD/MESA_trace.spec')
| -rw-r--r-- | docs/OLD/MESA_trace.spec | 359 |
1 files changed, 359 insertions, 0 deletions
diff --git a/docs/OLD/MESA_trace.spec b/docs/OLD/MESA_trace.spec new file mode 100644 index 0000000000..dc4166e6b6 --- /dev/null +++ b/docs/OLD/MESA_trace.spec @@ -0,0 +1,359 @@ +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 + + +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) + |