diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/OLD/MESA_packed_depth_stencil.spec | 230 | ||||
| -rw-r--r-- | docs/OLD/MESA_program_debug.spec | 356 | ||||
| -rw-r--r-- | docs/OLD/MESA_sprite_point.spec | 190 | ||||
| -rw-r--r-- | docs/OLD/MESA_trace.spec | 359 | ||||
| -rw-r--r-- | docs/gears.png | bin | 1608 -> 0 bytes |
5 files changed, 0 insertions, 1135 deletions
diff --git a/docs/OLD/MESA_packed_depth_stencil.spec b/docs/OLD/MESA_packed_depth_stencil.spec deleted file mode 100644 index 112b730ecc2..00000000000 --- a/docs/OLD/MESA_packed_depth_stencil.spec +++ /dev/null @@ -1,230 +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 - - -Number - - ??? - -Dependencies - - EXT_abgr affects the definition of this extension - SGIS_texture4D affects the definition of this extension - EXT_cmyka affects the definition of this extension - ARB_packed_pixels affects the definition of this extension - -Overview - - Provides a mechanism for DrawPixels and ReadPixels to efficiently - transfer depth and stencil image data. Specifically, we defined new - packed pixel formats and types which pack both stencil and depth - into one value. - -Issues: - - 1. Is this the right way to distinguish between 24/8 and 8/24 - pixel formats? Should we instead provide both: - - GL_DEPTH_STENCIL_MESA - GL_STENCIL_DEPTH_MESA - - And perhaps just use GL_UNSIGNED_INT, GL_UNSIGNED_SHORT ? - - 2. If not, is it correct to use _REV to indicate that stencil - preceeds depth in the 1_15 and 8_24 formats? - - 3. Do we really want the GL_UNSIGNED_SHORT formats? - - -New Procedures and Functions - - None. - -New Tokens - - Accepted by the <format> parameter of ReadPixels and DrawPixels: - - GL_DEPTH_STENCIL_MESA 0x8750 - - Accepted by the <type> parameter of ReadPixels and DrawPixels: - - GL_UNSIGNED_INT_24_8_MESA 0x8751 - GL_UNSIGNED_INT_8_24_REV_MESA 0x8752 - GL_UNSIGNED_SHORT_15_1_MESA 0x8753 - GL_UNSIGNED_SHORT_1_15_REV_MESA 0x8754 - -Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation) - - None - -Additions to Chapter 3 of the 1.1 Specification (Rasterization) - - One entry is added to table 3.5 (DrawPixels and ReadPixels formats). - The new table is: - - Target - Format Name Buffer Element Meaning and Order - ----------- ------ ------------------------- - COLOR_INDEX Color Color index - STENCIL_INDEX Stencil Stencil index - DEPTH_COMPONENT Depth Depth component - RED Color R component - GREEN Color G component - BLUE Color B component - ALPHA Color A component - RGB Color R, G, B components - RGBA Color R, G, B, A components - BGRA Color B, G, R, A components - ABGR_EXT Color A, B, G, R components - CMYK_EXT Color Cyan, Magenta, Yellow, Black components - CMYKA_EXT Color Cyan, Magenta, Yellow, Black, A components - LUMINANCE Color Luminance component - LUMINANCE_ALPHA Color Luminance, A components - DEPTH_STENCIL Depth, Depth component, stencil index. - Stencil - - Table 3.5: DrawPixels and ReadPixels formats. The third column - gives a description of and the number and order of elements in a - group. - - Add to the description of packed pixel formats: - - <type> Parameter Data of Matching - Token Name Type Elements Pixel Formats - ---------------- ---- -------- ------------- - - UNSIGNED_BYTE_3_3_2 ubyte 3 RGB - UNSIGNED_BYTE_2_3_3_REV ubyte 3 RGB - UNSIGNED_SHORT_5_6_5 ushort 3 RGB - UNSIGNED_SHORT_5_6_5_REV ushort 3 RGB - UNSIGNED_SHORT_4_4_4_4 ushort 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT - UNSIGNED_SHORT_4_4_4_4_REV ushort 4 RGBA,BGRA - UNSIGNED_SHORT_5_5_5_1 ushort 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT - UNSIGNED_SHORT_1_5_5_5_REV ushort 4 RGBA,BGRA - UNSIGNED_INT_8_8_8_8 uint 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT - UNSIGNED_INT_8_8_8_8_REV uint 4 RGBA,BGRA - UNSIGNED_INT_10_10_10_2 uint 4 RGBA,BGRA,ABGR_EXT,CMYK_EXT - UNSIGNED_INT_2_10_10_10_REV uint 4 RGBA,BGRA - UNSIGNED_SHORT_15_1_MESA ushort 2 DEPTH_STENCIL_MESA - UNSIGNED_SHORT_1_15_REV_MESA ushort 2 DEPTH_STENCIL_MESA - UNSIGNED_SHORT_24_8_MESA ushort 2 DEPTH_STENCIL_MESA - UNSIGNED_SHORT_8_24_REV_MESA ushort 2 DEPTH_STENCIL_MESA - - UNSIGNED_INT_8_24: - - 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 - +-----------------------+-----------------------------------------------------------------------+ - | | | - +-----------------------+-----------------------------------------------------------------------+ - - first second - element element - - - UNSIGNED_INT_24_8: - - 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 - +----------------------------------------------------------------------+------------------------+ - | | | - +----------------------------------------------------------------------+------------------------+ - - first second - element element - - UNSIGNED_SHORT_15_1: - - 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 - +-----------------------------------------------------------+---+ - | | | - +-----------------------------------------------------------+---+ - - first second - element element - - - UNSIGNED_SHORT_1_15_REV: - - 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 - +---+-----------------------------------------------------------+ - | | | - +---+-----------------------------------------------------------+ - - second first - element element - - The assignment of elements to fields in the packed pixel is as - described in the table below: - - First Second Third Fourth - Format Element Element Element Element - ------ ------- ------- ------- ------- - RGB red green blue - RGBA red green blue alpha - BGRA blue green red alpha - ABGR_EXT alpha blue green red - CMYK_EXT cyan magenta yellow black - DEPTH_STENCIL_MESA depth stencil - -Additions to Chapter 4 of the 1.1 Specification (Per-Fragment Operations -and the Frame Buffer) - - The new format is added to the discussion of Obtaining Pixels from the - Framebuffer. It should read " If the <format> is one of RED, GREEN, - BLUE, ALPHA, RGB, RGBA, ABGR_EXT, LUMINANCE, or LUMINANCE_ALPHA, and - the GL is in color index mode, then the color index is obtained." - - The new format is added to the discussion of Index Lookup. It should - read "If <format> is one of RED, GREEN, BLUE, ALPHA, RGB, RGBA, - ABGR_EXT, LUMINANCE, or LUMINANCE_ALPHA, then the index is used to - reference 4 tables of color components: PIXEL_MAP_I_TO_R, - PIXEL_MAP_I_TO_G, PIXEL_MAP_I_TO_B, and PIXEL_MAP_I_TO_A." - - -Additions to Chapter 5 of the 1.1 Specification (Special Functions) - - None - -Additions to Chapter 6 of the 1.1 Specification (State and State Requests) - - None - -Additions to the GLX Specification - - None - -GLX Protocol - - TBD - -Errors - - None - -New State - - None - -Revision History - - Version 1.0 - 23 Sep 2000 - Keith's original version. - - Version 1.1 - 3 Nov 2000 - Brian's edits, assigned values to new enums. - diff --git a/docs/OLD/MESA_program_debug.spec b/docs/OLD/MESA_program_debug.spec deleted file mode 100644 index 7694fdcc425..00000000000 --- a/docs/OLD/MESA_program_debug.spec +++ /dev/null @@ -1,356 +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 - -Number - - TBD - -Dependencies - - OpenGL 1.4 is required - The extension is written against the OpenGL 1.4 specification. - ARB_vertex_program or ARB_fragment_program or NV_vertex_program - or NV_fragment_program is required. - -Overview - - The extension provides facilities for implementing debuggers for - vertex and fragment programs. - - The concept is that vertex and fragment program debuggers will be - implemented outside of the GL as a utility package. This extension - only provides the minimal hooks required to implement a debugger. - - There are facilities to do the following: - 1. Have the GL call a user-specified function prior to executing - each vertex or fragment instruction. - 2. Query the current program string's execution position. - 3. Query the current values of intermediate program values. - - The main feature is the ProgramCallbackMESA function. It allows the - user to register a callback function with the GL. The callback will - be called prior to executing each vertex or fragment program instruction. - - From within the callback, the user may issue Get* commands to - query current GL state. The GetProgramRegisterfvMESA function allows - current program values to be queried (such as temporaries, input - attributes, and result registers). - - There are flags for enabling/disabling the program callbacks. - - The current execution position (as an offset from the start of the - program string) can be queried with - GetIntegerv(GL_FRAGMENT_PROGRAM_POSITION_MESA, &pos) or - GetIntegerv(GL_VERTEX_PROGRAM_POSITION_MESA, &pos). - - -IP Status - - None - -Issues - - 1. Is this the right model for a debugger? - - It seems prudent to minimize the scope of this extension and leave - it up to the developer (or developer community) to write debuggers - that layer on top of this extension. - - If the debugger were fully implemented within the GL it's not - clear how terminal and GUI-based interfaces would work, for - example. - - 2. There aren't any other extensions that register callbacks with - the GL. Isn't there another solution? - - If we want to be able to single-step through vertex/fragment - programs I don't see another way to do it. - - 3. How do we prevent the user from doing something crazy in the - callback function, like trying to call glBegin (leading to - recursion)? - - The rule is that the callback function can only issue glGet*() - functions and no other GL commands. It could be difficult to - enforce this, however. Therefore, calling any non-get GL - command from within the callback will result in undefined - results. - - 4. Is this extension amenable to hardware implementation? - - Hopefully, but if not, the GL implementation will have to fall - back to a software path when debugging. This may be acceptable - for debugging. - - 5. What's the <data> parameter to ProgramCallbackMESA for? - - It's a common programming practice to associate a user-supplied - value with callback functions. - - 6. Debuggers often allow one to modify intermediate program values, - then continue. Does this extension support that? - - No. - - -New Procedures and Functions (and datatypes) - - typedef void (*programcallbackMESA)(enum target, void *data) - - void ProgramCallbackMESA(enum target, programcallbackMESA callback, - void *data) - - void GetProgramRegisterfvMESA(enum target, sizei len, - const ubyte *registerName, float *v) - -New Tokens - - Accepted by the <cap> parameter of Enable, Disable, IsEnabled, - GetBooleanv, GetDoublev, GetFloatv and GetIntegerv: - - FRAGMENT_PROGRAM_CALLBACK_MESA 0x8bb1 - VERTEX_PROGRAM_CALLBACK_MESA 0x8bb4 - - Accepted by the <pname> parameter GetBooleanv, GetDoublev, - GetFloatv and GetIntegerv: - - FRAGMENT_PROGRAM_POSITION_MESA 0x8bb0 - VERTEX_PROGRAM_POSITION_MESA 0x8bb4 - - Accepted by the <pname> parameter of GetPointerv: - - FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA 0x8bb2 - FRAGMENT_PROGRAM_CALLBACK_DATA_MESA 0x8bb3 - VERTEX_PROGRAM_CALLBACK_FUNC_MESA 0x8bb6 - VERTEX_PROGRAM_CALLBACK_DATA_MESA 0x8bb7 - -Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation) - - None. - -Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization) - - None. - -Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment -Operations and the Frame Buffer) - - None. - -Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions) - - In section 5.4 "Display Lists", page 202, add the following command - to the list of those that are not compiled into display lists: - - ProgramCallbackMESA. - - - Add a new section 5.7 "Callback Functions" - - The function - - void ProgramCallbackMESA(enum target, programcallbackMESA callback, - void *data) - - registers a user-defined callback function with the GL. <target> - may be FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB. The enabled - callback functions registered with these targets will be called - prior to executing each instruction in the current fragment or - vertex program, respectively. The callbacks are enabled and - disabled by calling Enable or Disable with <cap> - FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB. - - The callback function's signature must match the typedef - - typedef void (*programcallbackMESA)(enum target, void *data) - - When the callback function is called, <target> will either be - FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB to indicate which - program is currently executing and <data> will be the value - specified when ProgramCallbackMESA was called. - - From within the callback function, only the following GL commands - may be called: - - GetBooleanv - GetDoublev - GetFloatv - GetIntegerv - GetProgramLocalParameter - GetProgramEnvParameter - GetProgramRegisterfvMESA - GetProgramivARB - GetProgramStringARB - GetError - - Calling any other command from within the callback results in - undefined behaviour. - - -Additions to Chapter 6 of the OpenGL 1.4 Specification (State and -State Requests) - - Add a new section 6.1.3 "Program Value Queries": - - The command - - void GetProgramRegisterfvMESA(enum target, sizei len, - const ubyte *registerName, - float *v) - - Is used to query the value of program variables and registers - during program execution. GetProgramRegisterfvMESA may only be - called from within a callback function registered with - ProgramCallbackMESA. - - <registerName> and <len> specify the name a variable, input - attribute, temporary, or result register in the program string. - The current value of the named variable is returned as four - values in <v>. If <name> doesn't exist in the program string, - the error INVALID_OPERATION is generated. - -Additions to Appendix A of the OpenGL 1.4 Specification (Invariance) - - None. - -Additions to the AGL/GLX/WGL Specifications - - None. - -GLX Protocol - - XXX TBD - -Dependencies on NV_vertex_program and NV_fragment_program - - If NV_vertex_program and/or NV_fragment_program are supported, - vertex and/or fragment programs defined by those extensions may - be debugged as well. Register queries will use the syntax used - by those extensions (i.e. "v[X]" to query vertex attributes, - "o[X]" for vertex outputs, etc.) - -Errors - - INVALID_OPERATION is generated if ProgramCallbackMESA is called - between Begin and End. - - INVALID_ENUM is generated by ProgramCallbackMESA if <target> is not - a supported vertex or fragment program type. - - Note: INVALID_OPERAION IS NOT generated by GetProgramRegisterfvMESA, - GetBooleanv, GetDoublev, GetFloatv, or GetIntegerv if called between - Begin and End when a vertex or fragment program is currently executing. - - INVALID_ENUM is generated by ProgramCallbackMESA, - GetProgramRegisterfvMESA if <target> is not a program target supported - by ARB_vertex_program, ARB_fragment_program (or NV_vertex_program or - NV_fragment_program). - - INVALID_VALUE is generated by GetProgramRegisterfvMESA if <registerName> - does not name a known program register or variable. - - INVALID_OPERATION is generated by GetProgramRegisterfvMESA when a - register query is attempted for a program target that's not currently - being executed. - - -New State - - XXX finish - -(table 6.N, p. ###) - Initial - Get Value Type Get Command Value Description Sec. Attribute - --------- ---- ----------- ----- ----------- ---- --------- - FRAGMENT_PROGRAM_CALLBACK_MESA B IsEnabled FALSE XXX XXX enable - VERTEX_PROGRAM_CALLBACK_MESA B IsEnabled FALSE XXX XXX enable - FRAGMENT_PROGRAM_POSITION_MESA Z+ GetIntegerv -1 XXX XXX - - VERTEX_PROGRAM_POSITION_MESA Z+ GetIntegerv -1 XXX XXX - - FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA P GetPointerv NULL XXX XXX - - VERTEX_PROGRAM_CALLBACK_FUNC_MESA P GetPointerv NULL XXX XXX - - FRAGMENT_PROGRAM_CALLBACK_DATA_MESA P GetPointerv NULL XXX XXX - - VERTEX_PROGRAM_CALLBACK_DATA_MESA P GetPointerv NULL XXX XXX - - - XXX more? - -New Implementation Dependent State - - None. - -Revision History - - 8 July 2003 - Initial draft. (Brian Paul) - 11 July 2003 - Second draft. (Brian Paul) - 20 July 2003 - Third draft. Lots of fundamental changes. (Brian Paul) - 23 July 2003 - Added chapter 5 and 6 spec language. (Brian Paul) - -Example Usage - - The following is a very simple example of how this extension may - be used to print the values of R0, R1, R2 and R3 while executing - vertex programs. - - - /* This is called by the GL when the vertex program is executing. - * We can only make glGet* calls from within this function! - */ - void DebugCallback(GLenum target, GLvoid *data) - { - GLint pos; - GLuint i; - - /* Get PC and current instruction string */ - glGetIntegerv(GL_VERTEX_PROGRAM_POSITION_ARB, &pos); - - printf("Current position: %d\n", pos); - - printf("Current temporary registers:\n"); - for (i = 0; i < 4; i++) { - GLfloat v[4]; - char s[10]; - sprintf(s, "R%d", i); - glGetProgramRegisterfvMESA(GL_VERTEX_PROGRAM_ARB, strlen(s), s, v); - printf("R%d = %g, %g, %g, %g\n", i, v[0], v[1], v[2], v[3]); - } - } - - - /* - * elsewhere... - */ - - /* Register our debugger callback function */ - glProgramCallbackMESA(GL_VERTEX_PROGRAM_ARB, DebugCallback, NULL); - glEnable(GL_VERTEX_PROGRAM_CALLBACK_MESA); - - /* define/bind a vertex program */ - - glEnable(GL_VERTEX_PROGRAM); - - /* render something */ - glBegin(GL_POINTS); - glVertex2f(0, 0); - glEnd(); - diff --git a/docs/OLD/MESA_sprite_point.spec b/docs/OLD/MESA_sprite_point.spec deleted file mode 100644 index b50d78e9e7b..00000000000 --- a/docs/OLD/MESA_sprite_point.spec +++ /dev/null @@ -1,190 +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 - - -Number - - ??? - -Dependencies - - GL_EXT_point_parameters effects the definition of this extension - GL_ARB_multitexture effects the definition of this extension - -Overview - - This extension modifies the way in which points are rendered, - specifically when they're textured. When SPRITE_POINT_MESA is enabled - a point is rendered as if it were a quadrilateral with unique texture - coordinates at each vertex. This extension effectively turns points - into sprites which may be rendered more easily and quickly than using - conventional textured quadrilaterals. - - When using point size > 1 or attenuated points this extension is an - effective way to render many small sprite images for particle systems - or other effects. - -Issues: - - 1. How are the texture coordinates computed? - - The lower-left corner has texture coordinate (0,0,r,q). - The lower-right, (1,0,r,q). The upper-right, (1,1,r,q). - The upper-left, (0,1,r,q). - - 2. What about texgen and texture matrices? - - Texgen and the texture matrix have no effect on the point's s and t - texture coordinates. The r and q coordinates may have been computed - by texgen or the texture matrix. Note that with a 3D texture and/or - texgen that the r coordinate could be used to select a slice in the - 3D texture. - - 3. What about point smoothing? - - When point smoothing is enabled, a triangle fan could be rendered - to approximate a circular point. This could be problematic to - define and implement so POINT_SMOOTH is ignored when drawing sprite - points. - - Smoothed points can be approximated by using an appropriate texture - images, alpha testing and blending. - - POLYGON_SMOOTH does effect the rendering of the quadrilateral, however. - - 4. What about sprite rotation? - - There is none. Sprite points are always rendered as window-aligned - squares. One could define rotated texture images if desired. A 3D - texture and appropriate texture r coordinates could be used to - effectively specify image rotation per point. - - 5. What about POLYGON_MODE? - - POLYGON_MODE does not effect the rasterization of the quadrilateral. - - 6. What about POLYGON_CULL? - - TBD. Polygon culling is normally specified and implemented in the - transformation stage of OpenGL. However, some rasterization hardware - implements it later during triangle setup. - - Polygon culling wouldn't be useful for sprite points since the - quadrilaterals are always defined in counter-clockwise order in - window space. For that reason, polygon culling should probably be - ignored. - - 7. Should sprite points be alpha-attenuated if their size is below the - point parameter's threshold size? - - 8. Should there be an advertisized maximum sprite point size? - - No. Since we're rendering the point as a quadrilateral there's no - need to limit the size. - - -New Procedures and Functions - - None. - -New Tokens - - Accepted by the <pname> parameter of Enable, Disable, IsEnabled, - GetIntegerv, GetBooleanv, GetFloatv and GetDoublev: - - SPRITE_POINT_MESA 0x???? - MAX_SPRITE_POINT_SIZE_MESA 0x???? (need this?) - -Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation) - - None - -Additions to Chapter 3 of the 1.1 Specification (Rasterization) - - Section ???. - - When SPRITE_POINT_MESA is enabled points are rasterized as screen- - aligned quadrilaterals. If the four vertices of the quadrilateral - are labeled A, B, C, and D, starting at the lower-left corner and moving - counter-clockwise around the quadrilateral, then the vertex and - texture coordinates are computed as follows: - - vertex window coordinate texture coordinate - A (x-r, y-r, z, w) (0, 0, r, q) - B (x+r, y-r, z, w) (1, 0, r, q) - C (x+r, y+r, z, w) (1, 1, r, q) - D (x-r, y+r, z, w) (0, 1, r, q) - - where x, y, z, w are the point's window coordinates, r and q are the - point's 3rd and 4th texture coordinates and r is half the point's - size. The other vertex attributes (such as the color and fog coordinate) - are simply duplicated from the original point vertex. - - Point size may either be specified with PointSize or computed - according to the EXT_point_parameters extension. - - The new texture coordinates are not effected by texgen or the texture - matrix. Note, however, that the texture r and q coordinates are passed - unchanged and may have been computed with texgen and/or the texture - matrix. - - If multiple texture units are present the same texture coordinate is - used for all texture units. - - The point is then rendered as if it were a quadrilateral using the - normal point sampling rules. POLYGON_MODE does not effect the - rasterization of the quadrilateral but POLYGON_SMOOTH does. - - POINT_SMOOTH has no effect when SPRITE_POINT_MESA is enabled. - -Additions to Chapter 4 of the 1.1 Specification (Per-Fragment Operations -and the Frame Buffer) - - None. - -Additions to Chapter 5 of the 1.1 Specification (Special Functions) - - None - -Additions to Chapter 6 of the 1.1 Specification (State and State Requests) - - None - -Additions to the GLX Specification - - None - -GLX Protocol - - TBD - -Errors - - None - -New State - - Add boolean variable SPRITE_POINT_MESA to the point attribute group. - -Revision History - - Version 1.0 - 4 Dec 2000 - Original draft. - - - diff --git a/docs/OLD/MESA_trace.spec b/docs/OLD/MESA_trace.spec deleted file mode 100644 index dc4166e6b6e..00000000000 --- a/docs/OLD/MESA_trace.spec +++ /dev/null @@ -1,359 +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 - - -Number - - none yet - -Dependencies - - OpenGL 1.2 is required. - The extension is written against the OpenGL 1.2 Specification - -Overview - - Provides the application with means to enable and disable logging - of GL calls including parameters as readable text. The verbosity - of the generated log can be controlled. The resulting logs are - valid (but possibly incomplete) C code and can be compiled and - linked for standalone test programs. The set of calls and the - amount of static data that is logged can be controlled at runtime. - The application can add comments and enable or disable tracing of GL - operations at any time. The data flow from the application to GL - and back is unaffected except for timing. - - Application-side implementation of these features raises namespace - and linkage issues. In the driver dispatch table a simple - "chain of responsibility" pattern (aka "composable piepline") - can be added. - -IP Status - - The extension spec is in the public domain. The current implementation - in Mesa is covered by Mesa's XFree86-style copyright by the authors above. - This extension is partially inspired by the Quake2 QGL wrapper. - -Issues - - - (1) Is this Extension obsolete because it can - be implemented as a wrapper DLL? - - RESOLVED: No. While certain operating systems (Win32) provide linkers - that facilitate this kind of solution, other operating systems - (Linux) do not support hierarchical linking, so a wrapper solution - would result in symbol collisions. - Further, IHV's might have builtin support for tracing GL execution - that enjoys privileged access, or that they do not wish to separate - the tracing code from their driver code base. - - (2) Should the Trace API explicitely support the notion of "frames? - This would require hooking into glXSwapBuffers calls as well. - - RESOLVED: No. The application can use NewTraceMESA/EndTraceMESA - and TraceComment along with external parsing tools to split the - trace into frames, in whatever way considered adequate. - - (2a) Should GLX calls be traced? - - PBuffers and other render-to-texture solutions demonstrate that - context level commands beyond SwapBuffers might have to be - traced. The GL DLL exports the entry points, so this would not - be out of the question. - - (3) Should the specification mandate the actual output format? - - RESOLVED: No. It is sufficient to guarantee that all data and commands - will be traced as requested by Enable/DisableTraceMESA, in the order - encountered. Whether the resulting trace is available as a readable - text file, binary metafile, compilable source code, much less which - indentation and formatting has been used, is up to the implementation. - For the same reason this specification does not enforce or prohibit - additional information added to the trace (statistics, profiling/timing, - warnings on possible error conditions). - - (4) Should the comment strings associated with names and pointer (ranges) - be considered persistent state? - - RESOLVED: No. The implementation is not forced to use this information - on subsequent occurences of name/pointer, and is free to consider it - transient state. - - (5) Should comment commands be prohibited between Begin/End? - - RESOLVED: Yes, with the exception of TraceCommentMESA. TraceCommentMESA - is transient, the other commands might cause storage of persistent - data in the context. There is no need to have the ability mark names - or pointers between Begin and End. - - -New Procedures and Functions - - void NewTraceMESA( bitfield mask, const ubyte * traceName ) - - void EndTraceMESA( void ) - - void EnableTraceMESA( bitfield mask ) - - void DisableTraceMESA( bitfield mask ) - - void TraceAssertAttribMESA( bitfield attribMask ) - - void TraceCommentMESA( const ubyte* comment ) - - void TraceTextureMESA( uint name, const ubyte* comment ) - - void TraceListMESA( uint name, const ubyte* comment ) - - void TracePointerMESA( void* pointer, const ubyte* comment ) - - void TracePointerRangeMESA( const void* first, - const void* last, - const ubyte* comment ) - -New Tokens - - Accepted by the <mask> parameter of EnableTrace and DisableTrace: - - TRACE_ALL_BITS_MESA 0xFFFF - TRACE_OPERATIONS_BIT_MESA 0x0001 - TRACE_PRIMITIVES_BIT_MESA 0x0002 - TRACE_ARRAYS_BIT_MESA 0x0004 - TRACE_TEXTURES_BIT_MESA 0x0008 - TRACE_PIXELS_BIT_MESA 0x0010 - TRACE_ERRORS_BIT_MESA 0x0020 - - Accepted by the <pname> parameter of GetIntegerv, GetBooleanv, - GetFloatv, and GetDoublev: - - TRACE_MASK_MESA 0x8755 - - Accepted by the <pname> parameter to GetString: - - TRACE_NAME_MESA 0x8756 - - -Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) - - None. - -Additions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation) - - None. - -Additions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation) - - None. - -Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) - - Add a new section: - - 5.7 Tracing - - The tracing facility is used to record the execution of a GL program - to a human-readable log. The log appears as a sequence of GL commands - using C syntax. The primary intention of tracing is to aid in program - debugging. - - A trace is started with the command - - void NewTraceMESA( bitfield mask, const GLubyte * traceName ) - - <mask> may be any value accepted by PushAttrib and specifies a set of - attribute groups. The state values included in those attribute groups - is written to the trace as a sequence of GL commands. - - <traceName> specifies a name or label for the trace. It is expected - that <traceName> will be interpreted as a filename in most implementations. - - A trace is ended by calling the command - - void EndTraceMESA( void ) - - It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End. - - The commands - - void EnableTraceMESA( bitfield mask ) - void DisableTraceMESA( bitfield mask ) - - enable or disable tracing of different classes of GL commands. - <mask> may be the union of any of TRACE_OPERATIONS_BIT_MESA, - TRACE_PRIMITIVES_BIT_MESA, TRACE_ARRAYS_BIT_MESA, TRACE_TEXTURES_BIT_MESA, - and TRACE_PIXELS_BIT_MESA. The special token TRACE_ALL_BITS_MESA - indicates all classes of commands are to be logged. - - TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of - Begin/End, including Begin/End. - - TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of - Begin/End, including Begin/End. - - TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer, NormalPointer, - ColorPointer, IndexPointer, TexCoordPointer and EdgeFlagPointer commands. - - TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by - TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, and - TexSubImage3D commands. - - TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by - Bitmap and DrawPixels commands. - - TRACE_ERRORS_BIT_MESA controls logging of all errors. If this bit is - set, GetError will be executed whereever applicable, and the result will - be added to the trace as a comment. The error returns are cached and - returned to the application on its GetError calls. If the user does not - wish the additional GetError calls to be performed, this bit should not - be set. - - The command - - void TraceCommentMESA( const ubyte* comment ) - - immediately adds the <comment> string to the trace output, surrounded - by C-style comment delimiters. - - The commands - - void TraceTextureMESA( uint name, const ubyte* comment ) - void TraceListMESA( uint name, const ubyte* comment ) - - associates <comment> with the texture object or display list specified - by <name>. Logged commands which reference the named texture object or - display list will be annotated with <comment>. If IsTexture(name) or - IsList(name) fail (respectively) the command is quietly ignored. - - The commands - - void TracePointerMESA( void* pointer, const ubyte* comment ) - - void TracePointerRangeMESA( const void* first, - const void* last, - const ubyte* comment ) - - associate <comment> with the address specified by <pointer> or with - a range of addresses specified by <first> through <last>. - Any logged commands which reference <pointer> or an address between - <first> and <last> will be annotated with <comment>. - - The command - - void TraceAssertAttribMESA( bitfield attribMask ) - - will add GL state queries and assertion statements to the log to - confirm that the current state at the time TraceAssertAttrib is - executed matches the current state when the trace log is executed - in the future. - - <attribMask> is any value accepted by PushAttrib and specifies - the groups of state variables which are to be asserted. - - The commands NewTraceMESA, EndTraceMESA, EnableTraceMESA, DisableTraceMESA, - TraceAssertAttribMESA, TraceCommentMESA, TraceTextureMESA, TraceListMESA, - TracePointerMESA and TracePointerRangeMESA are not compiled into display lists. - - - Examples: - - The command NewTraceMESA(DEPTH_BUFFER_BIT, "log") will query the state - variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE - to get the values <test>, <func>, <mask>, and <clear> respectively. - Statements equivalent to the following will then be logged: - - glEnable(GL_DEPTH_TEST); (if <test> is true) - glDisable(GL_DEPTH_TEST); (if <test> is false) - glDepthFunc(<func>); - glDepthMask(<mask>); - glClearDepth(<clear>); - - - The command TraceAssertAttribMESA(DEPTH_BUFFER_BIT) will query the state - variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE - to get the values <test>, <func>, <mask>, and <clear> respectively. - The resulting trace might then look will like this: - - { - GLboolean b; - GLint i; - GLfloat f; - b = glIsEnabled(GL_DEPTH_TEST); - assert(b == <test>); - glGetIntegerv(GL_DEPTH_FUNC, &i); - assert(i == <func>); - glGetIntegerv(GL_DEPTH_MASK, &i); - assert(i == <mask>); - glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f); - assert(f == <clear>); - } - - -Additions to Chapter 6 of the OpenGL 1.2.1 Specification - (State and State Requests) - - Querying TRACE_MASK_MESA with GetIntegerv, GetFloatv, GetBooleanv or - GetDoublev returns the current command class trace mask. - - Querying TRACE_NAME_MESA with GetString returns the current trace name. - - -Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance) - - The MESA_trace extension can be used in a way that does not affect data - flow from application to OpenGL, as well as data flow from OpenGL to - application, except for timing, possible print I/O. TRACE_ERRORS_BIT_MESA - will add additional GetError queries. Setting a trace mask with NewTraceMESA - as well as use of TraceAssertAttribMESA might cause additional state queries. - With the possible exception of performance, OpenGL rendering should not be - affected at all by a properly chosen logging operation. - -Additions to the AGL/GLX/WGL Specifications - - None. - -GLX Protocol - - None. The logging operation is carried out client-side, by exporting - entry points to the wrapper functions that execute the logging operation. - -Errors - - INVALID_OPERATION is generated if any trace command except TraceCommentMESA - is called between Begin and End. - -New State - - The current trace name and current command class mask are stored - per-context. - -New Implementation Dependent State - - None. - -Revision History - - * Revision 0.1 - Initial draft from template (bk000415) - * Revision 0.2 - Draft (bk000906) - * Revision 0.3 - Draft (bk000913) - * Revision 0.4 - Reworked text, fixed typos (bp000914) - * Revision 0.5 - Assigned final GLenum values (bp001103) - * Revision 0.6 - TRACE_ERRORS_BIT_MESA (bk000916) - * Revision 0.7 - Added MESA postfix (bk010126) - diff --git a/docs/gears.png b/docs/gears.png Binary files differdeleted file mode 100644 index 4052b30ed07..00000000000 --- a/docs/gears.png +++ /dev/null |
