From: Brian Paul Date: Mon, 18 Aug 2008 22:49:33 +0000 (-0600) Subject: mesa: move old/obsolete MESA extensions specs to OLD/ directory X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=2848b55ed5cfa3afc00937baa967fd7765fc5613;p=mesa.git mesa: move old/obsolete MESA extensions specs to OLD/ directory --- diff --git a/docs/MESA_packed_depth_stencil.spec b/docs/MESA_packed_depth_stencil.spec deleted file mode 100644 index 4f7ab1e28cf..00000000000 --- a/docs/MESA_packed_depth_stencil.spec +++ /dev/null @@ -1,231 +0,0 @@ -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/MESA_program_debug.spec b/docs/MESA_program_debug.spec deleted file mode 100644 index 391d39fa70a..00000000000 --- a/docs/MESA_program_debug.spec +++ /dev/null @@ -1,357 +0,0 @@ -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/MESA_sprite_point.spec b/docs/MESA_sprite_point.spec deleted file mode 100644 index 9422ff57295..00000000000 --- a/docs/MESA_sprite_point.spec +++ /dev/null @@ -1,191 +0,0 @@ -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/MESA_trace.spec b/docs/MESA_trace.spec deleted file mode 100644 index f0a79c7df99..00000000000 --- a/docs/MESA_trace.spec +++ /dev/null @@ -1,360 +0,0 @@ -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) - 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) +