docs/MESA_trace.spec - fp2-dev/platform/external/mesa3d - Gitiles

 XXX - Not complete yet!!!

 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

     XXX - Not complete yet!!!

 Version

     $Id: MESA_trace.spec,v 1.1 2000/11/03 15:10:04 brianp Exp $

 Number

     ???

 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

     none yet

 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           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

     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 NewTrace or EndTrace 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.

     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 NewTrace, EndTrace, EnableTrace, DisableTrace,
     TraceAssertAttrib, TraceComment, TraceTexture, TraceList, TracePointer,
     TracePointerRange, GetTraceName and GetTraceMask are not compiled
     into display lists.


     Examples:

     The command NewTrace(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 TraceAssertAttrib(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:

     {
       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_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.

 Additions to the AGL/GLX/WGL Specifications

     None.
     ? Hooking into glXSwapBuffers() ?

 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 TraceComment
     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 - Added GetTraceName/Mask, fixed typos (bp000914)
     * Revision 0.5 - Assigned final GLenum values
	XXX - Not complete yet!!!

	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

	XXX - Not complete yet!!!

	Version

	$Id: MESA_trace.spec,v 1.1 2000/11/03 15:10:04 brianp Exp $

	Number

	???

	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

	none yet

	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 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

	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 NewTrace or EndTrace 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.

	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 NewTrace, EndTrace, EnableTrace, DisableTrace,
	TraceAssertAttrib, TraceComment, TraceTexture, TraceList, TracePointer,
	TracePointerRange, GetTraceName and GetTraceMask are not compiled
	into display lists.


	Examples:

	The command NewTrace(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 TraceAssertAttrib(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:

	{
	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_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.

	Additions to the AGL/GLX/WGL Specifications

	None.
	? Hooking into glXSwapBuffers() ?

	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 TraceComment
	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 - Added GetTraceName/Mask, fixed typos (bp000914)
	* Revision 0.5 - Assigned final GLenum values