AlexIndustrial/mesa
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: move specs to a separate folder

Browse Source 
Handle legacy/obsolete specs as well
List all specs in extensions.html
Mark 'OLD' extensions as obsolete in extensions.html
Update the spec location in old relnotes

Signed-off-by: Emil Velikov <emil.l.velikov@gmail.com>
Reviewed-by: Brian Paul <brianp@vmware.com>
This commit is contained in:
Emil Velikov
2013-04-12 12:41:50 +01:00
committed by Brian Paul
parent 5fd3b3b085
commit cf9bf1d4a6
25 changed files with 25 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/specs/OLD/MESA_packed_depth_stencil.spec
+230
View File
@@ -0,0 +1,230 @@
Name
MESA_packed_depth_stencil
Name Strings
GL_MESA_packed_depth_stencil
Contact
Keith Whitwell, VA Linux Systems Inc. (keithw 'at' valinux.com)
Brian Paul, VA Linux Systems Inc. (brianp 'at' valinux.com)
Status
Obsolete.
Version
Number
???
Dependencies
EXT_abgr affects the definition of this extension
SGIS_texture4D affects the definition of this extension
EXT_cmyka affects the definition of this extension
ARB_packed_pixels affects the definition of this extension
Overview
Provides a mechanism for DrawPixels and ReadPixels to efficiently
transfer depth and stencil image data. Specifically, we defined new
packed pixel formats and types which pack both stencil and depth
into one value.
Issues:
1. Is this the right way to distinguish between 24/8 and 8/24
pixel formats? Should we instead provide both:
GL_DEPTH_STENCIL_MESA
GL_STENCIL_DEPTH_MESA
And perhaps just use GL_UNSIGNED_INT, GL_UNSIGNED_SHORT ?
2. If not, is it correct to use _REV to indicate that stencil
preceeds depth in the 1_15 and 8_24 formats?
3. Do we really want the GL_UNSIGNED_SHORT formats?
New Procedures and Functions
None.
New Tokens
Accepted by the <format> parameter of ReadPixels and DrawPixels:
GL_DEPTH_STENCIL_MESA 0x8750
Accepted by the <type> parameter of ReadPixels and DrawPixels:
GL_UNSIGNED_INT_24_8_MESA 0x8751
GL_UNSIGNED_INT_8_24_REV_MESA 0x8752
GL_UNSIGNED_SHORT_15_1_MESA 0x8753
GL_UNSIGNED_SHORT_1_15_REV_MESA 0x8754
Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation)
None
Additions to Chapter 3 of the 1.1 Specification (Rasterization)
One entry is added to table 3.5 (DrawPixels and ReadPixels formats).
The new table is:
Target
Format Name Buffer Element Meaning and Order
----------- ------ -------------------------
COLOR_INDEX Color Color index
STENCIL_INDEX Stencil Stencil index
DEPTH_COMPONENT Depth Depth component
RED Color R component
GREEN Color G component
BLUE Color B component
ALPHA Color A component
RGB Color R, G, B components
RGBA Color R, G, B, A components
BGRA Color B, G, R, A components
ABGR_EXT Color A, B, G, R components
CMYK_EXT Color Cyan, Magenta, Yellow, Black components
CMYKA_EXT Color Cyan, Magenta, Yellow, Black, A components
LUMINANCE Color Luminance component
LUMINANCE_ALPHA Color Luminance, A components
DEPTH_STENCIL Depth, Depth component, stencil index.
Stencil
Table 3.5: DrawPixels and ReadPixels formats. The third column
gives a description of and the number and order of elements in a
group.
Add to the description of packed pixel formats:
<type> Parameter Data of Matching
Token Name Type Elements Pixel Formats
---------------- ---- -------- -------------
UNSIGNED_BYTE_3_3_2 ubyte 3 RGB
UNSIGNED_BYTE_2_3_3_REV ubyte 3 RGB
UNSIGNED_SHORT_5_6_5 ushort 3 RGB
UNSIGNED_SHORT_5_6_5_REV ushort 3 RGB
UNSIGNED_SHORT_4_4_4_4 ushort 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT
UNSIGNED_SHORT_4_4_4_4_REV ushort 4 RGBA,BGRA
UNSIGNED_SHORT_5_5_5_1 ushort 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT
UNSIGNED_SHORT_1_5_5_5_REV ushort 4 RGBA,BGRA
UNSIGNED_INT_8_8_8_8 uint 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT
UNSIGNED_INT_8_8_8_8_REV uint 4 RGBA,BGRA
UNSIGNED_INT_10_10_10_2 uint 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT
UNSIGNED_INT_2_10_10_10_REV uint 4 RGBA,BGRA
UNSIGNED_SHORT_15_1_MESA ushort 2 DEPTH_STENCIL_MESA
UNSIGNED_SHORT_1_15_REV_MESA ushort 2 DEPTH_STENCIL_MESA
UNSIGNED_SHORT_24_8_MESA ushort 2 DEPTH_STENCIL_MESA
UNSIGNED_SHORT_8_24_REV_MESA ushort 2 DEPTH_STENCIL_MESA
UNSIGNED_INT_8_24:
31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+-----------------------+-----------------------------------------------------------------------+
| | |
+-----------------------+-----------------------------------------------------------------------+
first second
element element
UNSIGNED_INT_24_8:
31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+----------------------------------------------------------------------+------------------------+
| | |
+----------------------------------------------------------------------+------------------------+
first second
element element
UNSIGNED_SHORT_15_1:
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+-----------------------------------------------------------+---+
| | |
+-----------------------------------------------------------+---+
first second
element element
UNSIGNED_SHORT_1_15_REV:
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+---+-----------------------------------------------------------+
| | |
+---+-----------------------------------------------------------+
second first
element element
The assignment of elements to fields in the packed pixel is as
described in the table below:
First Second Third Fourth
Format Element Element Element Element
------ ------- ------- ------- -------
RGB red green blue
RGBA red green blue alpha
BGRA blue green red alpha
ABGR_EXT alpha blue green red
CMYK_EXT cyan magenta yellow black
DEPTH_STENCIL_MESA depth stencil
Additions to Chapter 4 of the 1.1 Specification (Per-Fragment Operations
and the Frame Buffer)
The new format is added to the discussion of Obtaining Pixels from the
Framebuffer. It should read " If the <format> is one of RED, GREEN,
BLUE, ALPHA, RGB, RGBA, ABGR_EXT, LUMINANCE, or LUMINANCE_ALPHA, and
the GL is in color index mode, then the color index is obtained."
The new format is added to the discussion of Index Lookup. It should
read "If <format> is one of RED, GREEN, BLUE, ALPHA, RGB, RGBA,
ABGR_EXT, LUMINANCE, or LUMINANCE_ALPHA, then the index is used to
reference 4 tables of color components: PIXEL_MAP_I_TO_R,
PIXEL_MAP_I_TO_G, PIXEL_MAP_I_TO_B, and PIXEL_MAP_I_TO_A."
Additions to Chapter 5 of the 1.1 Specification (Special Functions)
None
Additions to Chapter 6 of the 1.1 Specification (State and State Requests)
None
Additions to the GLX Specification
None
GLX Protocol
TBD
Errors
None
New State
None
Revision History
Version 1.0 - 23 Sep 2000
Keith's original version.
Version 1.1 - 3 Nov 2000
Brian's edits, assigned values to new enums.
docs/specs/OLD/MESA_program_debug.spec
+356
View File
@@ -0,0 +1,356 @@
Name
MESA_program_debug
Name Strings
GL_MESA_program_debug
Contact
Brian Paul (brian.paul 'at' tungstengraphics.com)
Status
XXX - Not complete yet!!!
Version
Last Modified Date: July 20, 2003
Author Revision: 1.0
Number
TBD
Dependencies
OpenGL 1.4 is required
The extension is written against the OpenGL 1.4 specification.
ARB_vertex_program or ARB_fragment_program or NV_vertex_program
or NV_fragment_program is required.
Overview
The extension provides facilities for implementing debuggers for
vertex and fragment programs.
The concept is that vertex and fragment program debuggers will be
implemented outside of the GL as a utility package. This extension
only provides the minimal hooks required to implement a debugger.
There are facilities to do the following:
1. Have the GL call a user-specified function prior to executing
each vertex or fragment instruction.
2. Query the current program string's execution position.
3. Query the current values of intermediate program values.
The main feature is the ProgramCallbackMESA function. It allows the
user to register a callback function with the GL. The callback will
be called prior to executing each vertex or fragment program instruction.
From within the callback, the user may issue Get* commands to
query current GL state. The GetProgramRegisterfvMESA function allows
current program values to be queried (such as temporaries, input
attributes, and result registers).
There are flags for enabling/disabling the program callbacks.
The current execution position (as an offset from the start of the
program string) can be queried with
GetIntegerv(GL_FRAGMENT_PROGRAM_POSITION_MESA, &pos) or
GetIntegerv(GL_VERTEX_PROGRAM_POSITION_MESA, &pos).
IP Status
None
Issues
1. Is this the right model for a debugger?
It seems prudent to minimize the scope of this extension and leave
it up to the developer (or developer community) to write debuggers
that layer on top of this extension.
If the debugger were fully implemented within the GL it's not
clear how terminal and GUI-based interfaces would work, for
example.
2. There aren't any other extensions that register callbacks with
the GL. Isn't there another solution?
If we want to be able to single-step through vertex/fragment
programs I don't see another way to do it.
3. How do we prevent the user from doing something crazy in the
callback function, like trying to call glBegin (leading to
recursion)?
The rule is that the callback function can only issue glGet*()
functions and no other GL commands. It could be difficult to
enforce this, however. Therefore, calling any non-get GL
command from within the callback will result in undefined
results.
4. Is this extension amenable to hardware implementation?
Hopefully, but if not, the GL implementation will have to fall
back to a software path when debugging. This may be acceptable
for debugging.
5. What's the <data> parameter to ProgramCallbackMESA for?
It's a common programming practice to associate a user-supplied
value with callback functions.
6. Debuggers often allow one to modify intermediate program values,
then continue. Does this extension support that?
No.
New Procedures and Functions (and datatypes)
typedef void (*programcallbackMESA)(enum target, void *data)
void ProgramCallbackMESA(enum target, programcallbackMESA callback,
void *data)
void GetProgramRegisterfvMESA(enum target, sizei len,
const ubyte *registerName, float *v)
New Tokens
Accepted by the <cap> parameter of Enable, Disable, IsEnabled,
GetBooleanv, GetDoublev, GetFloatv and GetIntegerv:
FRAGMENT_PROGRAM_CALLBACK_MESA 0x8bb1
VERTEX_PROGRAM_CALLBACK_MESA 0x8bb4
Accepted by the <pname> parameter GetBooleanv, GetDoublev,
GetFloatv and GetIntegerv:
FRAGMENT_PROGRAM_POSITION_MESA 0x8bb0
VERTEX_PROGRAM_POSITION_MESA 0x8bb4
Accepted by the <pname> parameter of GetPointerv:
FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA 0x8bb2
FRAGMENT_PROGRAM_CALLBACK_DATA_MESA 0x8bb3
VERTEX_PROGRAM_CALLBACK_FUNC_MESA 0x8bb6
VERTEX_PROGRAM_CALLBACK_DATA_MESA 0x8bb7
Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation)
None.
Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization)
None.
Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment
Operations and the Frame Buffer)
None.
Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions)
In section 5.4 "Display Lists", page 202, add the following command
to the list of those that are not compiled into display lists:
ProgramCallbackMESA.
Add a new section 5.7 "Callback Functions"
The function
void ProgramCallbackMESA(enum target, programcallbackMESA callback,
void *data)
registers a user-defined callback function with the GL. <target>
may be FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB. The enabled
callback functions registered with these targets will be called
prior to executing each instruction in the current fragment or
vertex program, respectively. The callbacks are enabled and
disabled by calling Enable or Disable with <cap>
FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB.
The callback function's signature must match the typedef
typedef void (*programcallbackMESA)(enum target, void *data)
When the callback function is called, <target> will either be
FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB to indicate which
program is currently executing and <data> will be the value
specified when ProgramCallbackMESA was called.
From within the callback function, only the following GL commands
may be called:
GetBooleanv
GetDoublev
GetFloatv
GetIntegerv
GetProgramLocalParameter
GetProgramEnvParameter
GetProgramRegisterfvMESA
GetProgramivARB
GetProgramStringARB
GetError
Calling any other command from within the callback results in
undefined behaviour.
Additions to Chapter 6 of the OpenGL 1.4 Specification (State and
State Requests)
Add a new section 6.1.3 "Program Value Queries":
The command
void GetProgramRegisterfvMESA(enum target, sizei len,
const ubyte *registerName,
float *v)
Is used to query the value of program variables and registers
during program execution. GetProgramRegisterfvMESA may only be
called from within a callback function registered with
ProgramCallbackMESA.
<registerName> and <len> specify the name a variable, input
attribute, temporary, or result register in the program string.
The current value of the named variable is returned as four
values in <v>. If <name> doesn't exist in the program string,
the error INVALID_OPERATION is generated.
Additions to Appendix A of the OpenGL 1.4 Specification (Invariance)
None.
Additions to the AGL/GLX/WGL Specifications
None.
GLX Protocol
XXX TBD
Dependencies on NV_vertex_program and NV_fragment_program
If NV_vertex_program and/or NV_fragment_program are supported,
vertex and/or fragment programs defined by those extensions may
be debugged as well. Register queries will use the syntax used
by those extensions (i.e. "v[X]" to query vertex attributes,
"o[X]" for vertex outputs, etc.)
Errors
INVALID_OPERATION is generated if ProgramCallbackMESA is called
between Begin and End.
INVALID_ENUM is generated by ProgramCallbackMESA if <target> is not
a supported vertex or fragment program type.
Note: INVALID_OPERAION IS NOT generated by GetProgramRegisterfvMESA,
GetBooleanv, GetDoublev, GetFloatv, or GetIntegerv if called between
Begin and End when a vertex or fragment program is currently executing.
INVALID_ENUM is generated by ProgramCallbackMESA,
GetProgramRegisterfvMESA if <target> is not a program target supported
by ARB_vertex_program, ARB_fragment_program (or NV_vertex_program or
NV_fragment_program).
INVALID_VALUE is generated by GetProgramRegisterfvMESA if <registerName>
does not name a known program register or variable.
INVALID_OPERATION is generated by GetProgramRegisterfvMESA when a
register query is attempted for a program target that's not currently
being executed.
New State
XXX finish
(table 6.N, p. ###)
Initial
Get Value Type Get Command Value Description Sec. Attribute
--------- ---- ----------- ----- ----------- ---- ---------
FRAGMENT_PROGRAM_CALLBACK_MESA B IsEnabled FALSE XXX XXX enable
VERTEX_PROGRAM_CALLBACK_MESA B IsEnabled FALSE XXX XXX enable
FRAGMENT_PROGRAM_POSITION_MESA Z+ GetIntegerv -1 XXX XXX -
VERTEX_PROGRAM_POSITION_MESA Z+ GetIntegerv -1 XXX XXX -
FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA P GetPointerv NULL XXX XXX -
VERTEX_PROGRAM_CALLBACK_FUNC_MESA P GetPointerv NULL XXX XXX -
FRAGMENT_PROGRAM_CALLBACK_DATA_MESA P GetPointerv NULL XXX XXX -
VERTEX_PROGRAM_CALLBACK_DATA_MESA P GetPointerv NULL XXX XXX -
XXX more?
New Implementation Dependent State
None.
Revision History
8 July 2003
Initial draft. (Brian Paul)
11 July 2003
Second draft. (Brian Paul)
20 July 2003
Third draft. Lots of fundamental changes. (Brian Paul)
23 July 2003
Added chapter 5 and 6 spec language. (Brian Paul)
Example Usage
The following is a very simple example of how this extension may
be used to print the values of R0, R1, R2 and R3 while executing
vertex programs.
/* This is called by the GL when the vertex program is executing.
* We can only make glGet* calls from within this function!
*/
void DebugCallback(GLenum target, GLvoid *data)
{
GLint pos;
GLuint i;
/* Get PC and current instruction string */
glGetIntegerv(GL_VERTEX_PROGRAM_POSITION_ARB, &pos);
printf("Current position: %d\n", pos);
printf("Current temporary registers:\n");
for (i = 0; i < 4; i++) {
GLfloat v[4];
char s[10];
sprintf(s, "R%d", i);
glGetProgramRegisterfvMESA(GL_VERTEX_PROGRAM_ARB, strlen(s), s, v);
printf("R%d = %g, %g, %g, %g\n", i, v[0], v[1], v[2], v[3]);
}
}
/*
* elsewhere...
*/
/* Register our debugger callback function */
glProgramCallbackMESA(GL_VERTEX_PROGRAM_ARB, DebugCallback, NULL);
glEnable(GL_VERTEX_PROGRAM_CALLBACK_MESA);
/* define/bind a vertex program */
glEnable(GL_VERTEX_PROGRAM);
/* render something */
glBegin(GL_POINTS);
glVertex2f(0, 0);
glEnd();
docs/specs/OLD/MESA_sprite_point.spec
+190
View File
@@ -0,0 +1,190 @@
Name
MESA_sprite_point
Name Strings
GL_MESA_sprite_point
Contact
Brian Paul, VA Linux Systems Inc. (brianp 'at' valinux.com)
Status
Obsolete - see GL_ARB_point_sprite.
Version
Number
???
Dependencies
GL_EXT_point_parameters effects the definition of this extension
GL_ARB_multitexture effects the definition of this extension
Overview
This extension modifies the way in which points are rendered,
specifically when they're textured. When SPRITE_POINT_MESA is enabled
a point is rendered as if it were a quadrilateral with unique texture
coordinates at each vertex. This extension effectively turns points
into sprites which may be rendered more easily and quickly than using
conventional textured quadrilaterals.
When using point size > 1 or attenuated points this extension is an
effective way to render many small sprite images for particle systems
or other effects.
Issues:
1. How are the texture coordinates computed?
The lower-left corner has texture coordinate (0,0,r,q).
The lower-right, (1,0,r,q). The upper-right, (1,1,r,q).
The upper-left, (0,1,r,q).
2. What about texgen and texture matrices?
Texgen and the texture matrix have no effect on the point's s and t
texture coordinates. The r and q coordinates may have been computed
by texgen or the texture matrix. Note that with a 3D texture and/or
texgen that the r coordinate could be used to select a slice in the
3D texture.
3. What about point smoothing?
When point smoothing is enabled, a triangle fan could be rendered
to approximate a circular point. This could be problematic to
define and implement so POINT_SMOOTH is ignored when drawing sprite
points.
Smoothed points can be approximated by using an appropriate texture
images, alpha testing and blending.
POLYGON_SMOOTH does effect the rendering of the quadrilateral, however.
4. What about sprite rotation?
There is none. Sprite points are always rendered as window-aligned
squares. One could define rotated texture images if desired. A 3D
texture and appropriate texture r coordinates could be used to
effectively specify image rotation per point.
5. What about POLYGON_MODE?
POLYGON_MODE does not effect the rasterization of the quadrilateral.
6. What about POLYGON_CULL?
TBD. Polygon culling is normally specified and implemented in the
transformation stage of OpenGL. However, some rasterization hardware
implements it later during triangle setup.
Polygon culling wouldn't be useful for sprite points since the
quadrilaterals are always defined in counter-clockwise order in
window space. For that reason, polygon culling should probably be
ignored.
7. Should sprite points be alpha-attenuated if their size is below the
point parameter's threshold size?
8. Should there be an advertisized maximum sprite point size?
No. Since we're rendering the point as a quadrilateral there's no
need to limit the size.
New Procedures and Functions
None.
New Tokens
Accepted by the <pname> parameter of Enable, Disable, IsEnabled,
GetIntegerv, GetBooleanv, GetFloatv and GetDoublev:
SPRITE_POINT_MESA 0x????
MAX_SPRITE_POINT_SIZE_MESA 0x???? (need this?)
Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation)
None
Additions to Chapter 3 of the 1.1 Specification (Rasterization)
Section ???.
When SPRITE_POINT_MESA is enabled points are rasterized as screen-
aligned quadrilaterals. If the four vertices of the quadrilateral
are labeled A, B, C, and D, starting at the lower-left corner and moving
counter-clockwise around the quadrilateral, then the vertex and
texture coordinates are computed as follows:
vertex window coordinate texture coordinate
A (x-r, y-r, z, w) (0, 0, r, q)
B (x+r, y-r, z, w) (1, 0, r, q)
C (x+r, y+r, z, w) (1, 1, r, q)
D (x-r, y+r, z, w) (0, 1, r, q)
where x, y, z, w are the point's window coordinates, r and q are the
point's 3rd and 4th texture coordinates and r is half the point's
size. The other vertex attributes (such as the color and fog coordinate)
are simply duplicated from the original point vertex.
Point size may either be specified with PointSize or computed
according to the EXT_point_parameters extension.
The new texture coordinates are not effected by texgen or the texture
matrix. Note, however, that the texture r and q coordinates are passed
unchanged and may have been computed with texgen and/or the texture
matrix.
If multiple texture units are present the same texture coordinate is
used for all texture units.
The point is then rendered as if it were a quadrilateral using the
normal point sampling rules. POLYGON_MODE does not effect the
rasterization of the quadrilateral but POLYGON_SMOOTH does.
POINT_SMOOTH has no effect when SPRITE_POINT_MESA is enabled.
Additions to Chapter 4 of the 1.1 Specification (Per-Fragment Operations
and the Frame Buffer)
None.
Additions to Chapter 5 of the 1.1 Specification (Special Functions)
None
Additions to Chapter 6 of the 1.1 Specification (State and State Requests)
None
Additions to the GLX Specification
None
GLX Protocol
TBD
Errors
None
New State
Add boolean variable SPRITE_POINT_MESA to the point attribute group.
Revision History
Version 1.0 - 4 Dec 2000
Original draft.
docs/specs/OLD/MESA_trace.spec
+359
View File
@@ -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)