docs: move specs to a separate folder

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

Signed-off-by: Emil Velikov <[email protected]>
Reviewed-by: Brian Paul <[email protected]>

4 files changed, 1135 insertions, 0 deletions

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