OpenHarmony/third_party_mesa3d
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated spec

Browse Source
This commit is contained in:
Brian Paul
2001-01-29 16:10:18 +00:00
parent f3da389ae0
commit d6dd0fceb1
1 changed files with 104 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
docs/MESA_trace.spec
View File

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