From 2848b55ed5cfa3afc00937baa967fd7765fc5613 Mon Sep 17 00:00:00 2001 From: Brian Paul Date: Mon, 18 Aug 2008 16:49:33 -0600 Subject: mesa: move old/obsolete MESA extensions specs to OLD/ directory --- docs/OLD/MESA_packed_depth_stencil.spec | 231 ++++++++++++++++++++ docs/OLD/MESA_program_debug.spec | 357 +++++++++++++++++++++++++++++++ docs/OLD/MESA_sprite_point.spec | 191 +++++++++++++++++ docs/OLD/MESA_trace.spec | 360 ++++++++++++++++++++++++++++++++ 4 files changed, 1139 insertions(+) create mode 100644 docs/OLD/MESA_packed_depth_stencil.spec create mode 100644 docs/OLD/MESA_program_debug.spec create mode 100644 docs/OLD/MESA_sprite_point.spec create mode 100644 docs/OLD/MESA_trace.spec (limited to 'docs/OLD') diff --git a/docs/OLD/MESA_packed_depth_stencil.spec b/docs/OLD/MESA_packed_depth_stencil.spec new file mode 100644 index 00000000000..4f7ab1e28cf --- /dev/null +++ b/docs/OLD/MESA_packed_depth_stencil.spec @@ -0,0 +1,231 @@ +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 + + $Id: MESA_packed_depth_stencil.spec,v 1.2 2003/09/19 14:58:21 brianp Exp $ + +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 parameter of ReadPixels and DrawPixels: + + GL_DEPTH_STENCIL_MESA 0x8750 + + Accepted by the 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: + + 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 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 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. + diff --git a/docs/OLD/MESA_program_debug.spec b/docs/OLD/MESA_program_debug.spec new file mode 100644 index 00000000000..391d39fa70a --- /dev/null +++ b/docs/OLD/MESA_program_debug.spec @@ -0,0 +1,357 @@ +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 + $Date: 2004/03/25 01:42:41 $ $Revision: 1.4 $ + +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 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 parameter of Enable, Disable, IsEnabled, + GetBooleanv, GetDoublev, GetFloatv and GetIntegerv: + + FRAGMENT_PROGRAM_CALLBACK_MESA 0x8bb1 + VERTEX_PROGRAM_CALLBACK_MESA 0x8bb4 + + Accepted by the parameter GetBooleanv, GetDoublev, + GetFloatv and GetIntegerv: + + FRAGMENT_PROGRAM_POSITION_MESA 0x8bb0 + VERTEX_PROGRAM_POSITION_MESA 0x8bb4 + + Accepted by the 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. + 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 + 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, will either be + FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB to indicate which + program is currently executing and 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. + + and 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 . If 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 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 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 + 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(); + diff --git a/docs/OLD/MESA_sprite_point.spec b/docs/OLD/MESA_sprite_point.spec new file mode 100644 index 00000000000..9422ff57295 --- /dev/null +++ b/docs/OLD/MESA_sprite_point.spec @@ -0,0 +1,191 @@ +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 + + $Id: MESA_sprite_point.spec,v 1.2 2003/09/19 14:58:21 brianp Exp $ + +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 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. + + + diff --git a/docs/OLD/MESA_trace.spec b/docs/OLD/MESA_trace.spec new file mode 100644 index 00000000000..f0a79c7df99 --- /dev/null +++ b/docs/OLD/MESA_trace.spec @@ -0,0 +1,360 @@ +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.4 2004/03/25 01:42:42 brianp 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 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 parameter of GetIntegerv, GetBooleanv, + GetFloatv, and GetDoublev: + + TRACE_MASK_MESA 0x8755 + + Accepted by the 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 ) + + 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. + + specifies a name or label for the trace. It is expected + that 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. + 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 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 with the texture object or display list specified + by . Logged commands which reference the named texture object or + display list will be annotated with . 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 with the address specified by or with + a range of addresses specified by through . + Any logged commands which reference or an address between + and will be annotated with . + + 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. + + 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 , , , and respectively. + Statements equivalent to the following will then be logged: + + glEnable(GL_DEPTH_TEST); (if is true) + glDisable(GL_DEPTH_TEST); (if is false) + glDepthFunc(); + glDepthMask(); + glClearDepth(); + + + 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 , , , and respectively. + The resulting trace might then look will like this: + + { + GLboolean b; + GLint i; + GLfloat f; + b = glIsEnabled(GL_DEPTH_TEST); + assert(b == ); + glGetIntegerv(GL_DEPTH_FUNC, &i); + assert(i == ); + glGetIntegerv(GL_DEPTH_MASK, &i); + assert(i == ); + glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f); + assert(f == ); + } + + +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) + -- cgit v1.2.3