Merge Jose's documentation and core Mesa changes from embedded branch

104 files changed, 7646 insertions, 3773 deletions

diff --git a/src/mesa/main/accum.c b/src/mesa/main/accum.c
index 1185adbfd4..3ca7d27f83 100644
--- a/src/mesa/main/accum.c
+++ b/src/mesa/main/accum.c
@@ -85,3 +85,10 @@ _mesa_Accum( GLenum op, GLfloat value )
 
    ctx->Driver.Accum( ctx, op, value, xpos, ypos, width, height );
 }
+
+void 
+_mesa_init_accum( GLcontext *ctx )
+{
+   /* Accumulate buffer group */
+   ASSIGN_4V( ctx->Accum.ClearColor, 0.0, 0.0, 0.0, 0.0 );
+}
diff --git a/src/mesa/main/accum.h b/src/mesa/main/accum.h
index 8682525dc1..625d0bfd61 100644
--- a/src/mesa/main/accum.h
+++ b/src/mesa/main/accum.h
@@ -1,3 +1,12 @@
+/**
+ * \file accum.h
+ * Accumulation buffer operations.
+ * 
+ * \if subset
+ * (No-op)
+ *
+ * \endif
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,12 +33,14 @@
  */
 
 
+
 #ifndef ACCUM_H
 #define ACCUM_H
 
 
 #include "mtypes.h"
 
+#if _HAVE_FULL_GL
 
 extern void
 _mesa_Accum( GLenum op, GLfloat value );
@@ -38,5 +49,14 @@ _mesa_Accum( GLenum op, GLfloat value );
 extern void
 _mesa_ClearAccum( GLfloat red, GLfloat green, GLfloat blue, GLfloat alpha );
 
+extern void 
+_mesa_init_accum( GLcontext *ctx );
+
+#else
+
+/** No-op */
+#define _mesa_init_accum( c ) ((void)0)
+
+#endif
 
 #endif
diff --git a/src/mesa/main/api_loopback.c b/src/mesa/main/api_loopback.c
index 335dc32ad2..ecd701da3b 100644
--- a/src/mesa/main/api_loopback.c
+++ b/src/mesa/main/api_loopback.c
@@ -1,3 +1,9 @@
+/**
+ * \file api_loopback.c
+ *
+ * \author Keith Whitwell <keith@tungstengraphics.com>
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -20,9 +26,6 @@
  * BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- *
- * Authors:
- *    Keith Whitwell <keith@tungstengraphics.com>
  */
 
 
diff --git a/src/mesa/main/api_loopback.h b/src/mesa/main/api_loopback.h
index a4858e44f4..202261aa9c 100644
--- a/src/mesa/main/api_loopback.h
+++ b/src/mesa/main/api_loopback.h
@@ -1,4 +1,3 @@
-
 /*
  * Mesa 3-D graphics library
  * Version:  3.5
@@ -23,11 +22,14 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
+
 #ifndef API_LOOPBACK_H
 #define API_LOOPBACK_H
 
 #include "glheader.h"
 
+
 struct _glapi_table;
 
 extern void _mesa_loopback_prefer_float( struct _glapi_table *dest,
diff --git a/src/mesa/main/arbprogram.c b/src/mesa/main/arbprogram.c
index 54715e20b3..08d72fafc0 100644
--- a/src/mesa/main/arbprogram.c
+++ b/src/mesa/main/arbprogram.c
@@ -24,7 +24,7 @@
 
 /**
  * \file arbprogram.c
- * \brief ARB_vertex/fragment_program state management functions.
+ * ARB_vertex/fragment_program state management functions.
  * \author Brian Paul
  */
 
diff --git a/src/mesa/main/attrib.c b/src/mesa/main/attrib.c
index 30c0c7faff..19cee76d5d 100644
--- a/src/mesa/main/attrib.c
+++ b/src/mesa/main/attrib.c
@@ -1233,3 +1233,11 @@ _mesa_PopClientAttrib(void)
       attr = next;
    }
 }
+
+
+void _mesa_init_attrib( GLcontext *ctx )
+{
+   /* Renderer and client attribute stacks */
+   ctx->AttribStackDepth = 0;
+   ctx->ClientAttribStackDepth = 0;
+}
diff --git a/src/mesa/main/attrib.h b/src/mesa/main/attrib.h
index 722bbcf83f..8267624637 100644
--- a/src/mesa/main/attrib.h
+++ b/src/mesa/main/attrib.h
@@ -1,3 +1,13 @@
+/**
+ * \file attrib.h
+ * Attribute stacks.
+ * 
+ * \if subset
+ * (No-op)
+ *
+ * \endif
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -23,12 +33,16 @@
  */
 
 
+
 #ifndef ATTRIB_H
 #define ATTRIB_H
 
 
 #include "mtypes.h"
 
+
+#if _HAVE_FULL_GL
+
 extern void
 _mesa_PushAttrib( GLbitfield mask );
 
@@ -41,5 +55,14 @@ _mesa_PushClientAttrib( GLbitfield mask );
 extern void
 _mesa_PopClientAttrib( void );
 
+extern void 
+_mesa_init_attrib( GLcontext *ctx );
+
+#else
+
+/** No-op */
+#define _mesa_init_attrib( c ) ((void)0)
+
+#endif
 
 #endif
diff --git a/src/mesa/main/blend.c b/src/mesa/main/blend.c
index e031851f98..dad5184dd9 100644
--- a/src/mesa/main/blend.c
+++ b/src/mesa/main/blend.c
@@ -1,3 +1,7 @@
+/**
+ * \file blend.c
+ * Blending operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,6 +28,7 @@
  */
 
 
+
 #include "glheader.h"
 #include "blend.h"
 #include "colormac.h"
@@ -33,6 +38,18 @@
 #include "mtypes.h"
 
 
+/**
+ * Specify the blending operation.
+ *
+ * \param sfactor source factor operator.
+ * \param dfactor destination factor operator.
+ *
+ * \sa glBlendFunc().
+ * 
+ * Verifies the parameters and updates gl_colorbuffer_attrib.  On a change,
+ * flushes the vertices and notifies the driver via
+ * dd_function_table::BlendFunc callback.
+ */
 void
 _mesa_BlendFunc( GLenum sfactor, GLenum dfactor )
 {
@@ -113,7 +130,20 @@ _mesa_BlendFunc( GLenum sfactor, GLenum dfactor )
 }
 
 
-/* GL_EXT_blend_func_separate */
+#if _HAVE_FULL_GL
+
+/**
+ * Process GL_EXT_blend_func_separate().
+ *
+ * \param sfactorRGB RGB source factor operator.
+ * \param dfactorRGB RGB destination factor operator.
+ * \param sfactorA alpha source factor operator.
+ * \param dfactorA alpha destination factor operator.
+ *
+ * Verifies the parameters and updates gl_colorbuffer_attrib.
+ * On a change, flush the vertices and notify the driver via
+ * dd_function_table::BlendFuncSeparate.
+ */
 void
 _mesa_BlendFuncSeparateEXT( GLenum sfactorRGB, GLenum dfactorRGB,
                             GLenum sfactorA, GLenum dfactorA )
@@ -254,7 +284,6 @@ _mesa_BlendFuncSeparateEXT( GLenum sfactorRGB, GLenum dfactorRGB,
 }
 
 
-
 /* This is really an extension function! */
 void
 _mesa_BlendEquation( GLenum mode )
@@ -312,8 +341,23 @@ _mesa_BlendEquation( GLenum mode )
       (*ctx->Driver.BlendEquation)( ctx, mode );
 }
 
+#endif
 
 
+/**
+ * Set the blending color.
+ *
+ * \param red red color component.
+ * \param green green color component.
+ * \param blue blue color component.
+ * \param alpha alpha color component.
+ *
+ * \sa glBlendColor().
+ *
+ * Clamps the parameters and updates gl_colorbuffer_attrib::BlendColor.  On a
+ * change, flushes the vertices and notifies the driver via
+ * dd_function_table::BlendColor callback.
+ */
 void
 _mesa_BlendColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha )
 {
@@ -337,6 +381,16 @@ _mesa_BlendColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha )
 }
 
 
+/**
+ * Specify the alpha test function.
+ *
+ * \param func alpha comparison function.
+ * \param ref reference value.
+ *
+ * Verifies the parameters and updates gl_colorbuffer_attrib. 
+ * On a change, flushes the vertices and notifies the driver via
+ * dd_function_table::AlphaFunc callback.
+ */
 void
 _mesa_AlphaFunc( GLenum func, GLclampf ref )
 {
@@ -372,6 +426,16 @@ _mesa_AlphaFunc( GLenum func, GLclampf ref )
 }
 
 
+/**
+ * Specify a logic pixel operation for color index rendering.
+ *
+ * \param opcode operation.
+ *
+ * Verifies that \p opcode is a valid enum and updates
+gl_colorbuffer_attrib::LogicOp.
+ * On a change, flushes the vertices and notifies the driver via the
+ * dd_function_table::LogicOpcode callback.
+ */
 void
 _mesa_LogicOp( GLenum opcode )
 {
@@ -411,7 +475,7 @@ _mesa_LogicOp( GLenum opcode )
       ctx->Driver.LogicOpcode( ctx, opcode );
 }
 
-
+#if _HAVE_FULL_GL
 void
 _mesa_IndexMask( GLuint mask )
 {
@@ -427,8 +491,23 @@ _mesa_IndexMask( GLuint mask )
    if (ctx->Driver.IndexMask)
       ctx->Driver.IndexMask( ctx, mask );
 }
+#endif
 
 
+/**
+ * Enable or disable writing of frame buffer color components.
+ *
+ * \param red whether to mask writing of the red color component.
+ * \param green whether to mask writing of the green color component.
+ * \param blue whether to mask writing of the blue color component.
+ * \param alpha whether to mask writing of the alpha color component.
+ *
+ * \sa glColorMask().
+ *
+ * Sets the appropriate value of gl_colorbuffer_attrib::ColorMask.  On a
+ * change, flushes the vertices and notifies the driver via the
+ * dd_function_table::ColorMask callback.
+ */
 void
 _mesa_ColorMask( GLboolean red, GLboolean green,
                  GLboolean blue, GLboolean alpha )
@@ -457,3 +536,53 @@ _mesa_ColorMask( GLboolean red, GLboolean green,
    if (ctx->Driver.ColorMask)
       ctx->Driver.ColorMask( ctx, red, green, blue, alpha );
 }
+
+/**********************************************************************/
+/** \name Initialization */
+/*@{*/
+
+/**
+ * Initialization of the context color data.
+ *
+ * \param ctx GL context.
+ *
+ * Initializes the related fields in the context color attribute group,
+ * __GLcontextRec::Color.
+ */
+void _mesa_init_color( GLcontext * ctx )
+{
+   /* Color buffer group */
+   ctx->Color.IndexMask = 0xffffffff;
+   ctx->Color.ColorMask[0] = 0xff;
+   ctx->Color.ColorMask[1] = 0xff;
+   ctx->Color.ColorMask[2] = 0xff;
+   ctx->Color.ColorMask[3] = 0xff;
+   ctx->Color.ClearIndex = 0;
+   ASSIGN_4V( ctx->Color.ClearColor, 0, 0, 0, 0 );
+   ctx->Color.DrawBuffer = GL_FRONT;
+   ctx->Color.AlphaEnabled = GL_FALSE;
+   ctx->Color.AlphaFunc = GL_ALWAYS;
+   ctx->Color.AlphaRef = 0;
+   ctx->Color.BlendEnabled = GL_FALSE;
+   ctx->Color.BlendSrcRGB = GL_ONE;
+   ctx->Color.BlendDstRGB = GL_ZERO;
+   ctx->Color.BlendSrcA = GL_ONE;
+   ctx->Color.BlendDstA = GL_ZERO;
+   ctx->Color.BlendEquation = GL_FUNC_ADD_EXT;
+   ASSIGN_4V( ctx->Color.BlendColor, 0.0, 0.0, 0.0, 0.0 );
+   ctx->Color.IndexLogicOpEnabled = GL_FALSE;
+   ctx->Color.ColorLogicOpEnabled = GL_FALSE;
+   ctx->Color.LogicOp = GL_COPY;
+   ctx->Color.DitherFlag = GL_TRUE;
+
+   if (ctx->Visual.doubleBufferMode) {
+      ctx->Color.DrawBuffer = GL_BACK;
+      ctx->Color._DrawDestMask = BACK_LEFT_BIT;
+   }
+   else {
+      ctx->Color.DrawBuffer = GL_FRONT;
+      ctx->Color._DrawDestMask = FRONT_LEFT_BIT;
+   }
+}
+
+/*@}*/
diff --git a/src/mesa/main/blend.h b/src/mesa/main/blend.h
index d0a24afd00..a967937e68 100644
--- a/src/mesa/main/blend.h
+++ b/src/mesa/main/blend.h
@@ -1,3 +1,7 @@
+/**
+ * \file blend.h
+ * Blending functions operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,6 +28,7 @@
  */
 
 
+
 #ifndef BLEND_H
 #define BLEND_H
 
@@ -63,5 +68,7 @@ extern void
 _mesa_ColorMask( GLboolean red, GLboolean green,
                  GLboolean blue, GLboolean alpha );
 
+extern void 
+_mesa_init_color( GLcontext * ctx );
 
 #endif
diff --git a/src/mesa/main/bufferobj.c b/src/mesa/main/bufferobj.c
index f384402219..a9e66a199a 100644
--- a/src/mesa/main/bufferobj.c
+++ b/src/mesa/main/bufferobj.c
@@ -25,7 +25,7 @@
 
 /**
  * \file bufferobj.c
- * \brief Functions for the GL_ARB_vertex_buffer_object extension.
+ * Functions for the GL_ARB_vertex_buffer_object extension.
  * \author Brian Paul
  */
 
diff --git a/src/mesa/main/buffers.c b/src/mesa/main/buffers.c
index 92379a2335..6c58ed408c 100644
--- a/src/mesa/main/buffers.c
+++ b/src/mesa/main/buffers.c
@@ -1,3 +1,8 @@
+/**
+ * \file buffers.c
+ * Frame buffer management.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -25,7 +30,6 @@
 
 #include "glheader.h"
 #include "imports.h"
-#include "accum.h"
 #include "buffers.h"
 #include "colormac.h"
 #include "context.h"
@@ -36,7 +40,7 @@
 #include "mtypes.h"
 
 
-
+#if _HAVE_FULL_GL
 void
 _mesa_ClearIndex( GLfloat c )
 {
@@ -54,9 +58,23 @@ _mesa_ClearIndex( GLfloat c )
       (*ctx->Driver.ClearIndex)( ctx, ctx->Color.ClearIndex );
    }
 }
+#endif
 
 
-
+/**
+ * Specify the clear values for the color buffers.
+ *
+ * \param red red color component.
+ * \param green green color component.
+ * \param blue blue color component.
+ * \param alpha alpha component.
+ *
+ * \sa glClearColor().
+ *
+ * Clamps the parameters and updates gl_colorbuffer_attrib::ClearColor.  On a
+ * change, flushes the vertices and notifies the driver via the
+ * dd_function_table::ClearColor callback.
+ */
 void
 _mesa_ClearColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha )
 {
@@ -82,7 +100,16 @@ _mesa_ClearColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha )
 }
 
 
-
+/**
+ * Clear buffers.
+ * 
+ * \param mask bit-mask indicating the buffers to be cleared.
+ *
+ * Flushes the vertices and verifies the parameter. If __GLcontextRec::NewState
+ * is set then calls _mesa_update_state() to update gl_frame_buffer::_Xmin,
+ * etc. If the rasterization mode is set to GL_RENDER then requests the driver
+ * to clear the buffers, via the dd_function_table::Clear callback.
+ */ 
 void
 _mesa_Clear( GLbitfield mask )
 {
@@ -137,6 +164,18 @@ _mesa_Clear( GLbitfield mask )
 }
 
 
+/**
+ * Specify which color buffers to draw into.
+ *
+ * \param mode color buffer combination.
+ *
+ * \sa glDrawBuffer().
+ *
+ * Flushes the vertices and verifies the parameter and updates the
+ * gl_colorbuffer_attrib::_DrawDestMask bitfield. Marks new color state in
+ * __GLcontextRec::NewState and notifies the driver via the
+ * dd_function_table::DrawBuffer callback.
+ */
 void
 _mesa_DrawBuffer( GLenum mode )
 {
@@ -150,6 +189,28 @@ _mesa_DrawBuffer( GLenum mode )
     * Do error checking and compute the _DrawDestMask bitfield.
     */
    switch (mode) {
+      case GL_FRONT:
+         /* never an error */
+         if (ctx->Visual.stereoMode)
+            ctx->Color._DrawDestMask = FRONT_LEFT_BIT | FRONT_RIGHT_BIT;
+         else
+            ctx->Color._DrawDestMask = FRONT_LEFT_BIT;
+         break;
+      case GL_BACK:
+         if (!ctx->Visual.doubleBufferMode) {
+            _mesa_error( ctx, GL_INVALID_OPERATION, "glDrawBuffer" );
+            return;
+         }
+         if (ctx->Visual.stereoMode)
+            ctx->Color._DrawDestMask = BACK_LEFT_BIT | BACK_RIGHT_BIT;
+         else
+            ctx->Color._DrawDestMask = BACK_LEFT_BIT;
+         break;
+      case GL_NONE:
+         /* never an error */
+         ctx->Color._DrawDestMask = 0;
+         break;
+#if _HAVE_FULL_GL
       case GL_RIGHT:
          if (!ctx->Visual.stereoMode) {
             _mesa_error( ctx, GL_INVALID_OPERATION, "glDrawBuffer" );
@@ -191,16 +252,6 @@ _mesa_DrawBuffer( GLenum mode )
          else
             ctx->Color._DrawDestMask = FRONT_LEFT_BIT | BACK_LEFT_BIT;
          break;
-      case GL_BACK:
-         if (!ctx->Visual.doubleBufferMode) {
-            _mesa_error( ctx, GL_INVALID_OPERATION, "glDrawBuffer" );
-            return;
-         }
-         if (ctx->Visual.stereoMode)
-            ctx->Color._DrawDestMask = BACK_LEFT_BIT | BACK_RIGHT_BIT;
-         else
-            ctx->Color._DrawDestMask = BACK_LEFT_BIT;
-         break;
       case GL_LEFT:
          /* never an error */
          if (ctx->Visual.doubleBufferMode)
@@ -212,17 +263,6 @@ _mesa_DrawBuffer( GLenum mode )
          /* never an error */
          ctx->Color._DrawDestMask = FRONT_LEFT_BIT;
          break;
-      case GL_FRONT:
-         /* never an error */
-         if (ctx->Visual.stereoMode)
-            ctx->Color._DrawDestMask = FRONT_LEFT_BIT | FRONT_RIGHT_BIT;
-         else
-            ctx->Color._DrawDestMask = FRONT_LEFT_BIT;
-         break;
-      case GL_NONE:
-         /* never an error */
-         ctx->Color._DrawDestMask = 0;
-         break;
       case GL_AUX0:
          if (ctx->Const.NumAuxBuffers >= 1) {
             ctx->Color._DrawDestMask = AUX0_BIT;
@@ -259,6 +299,7 @@ _mesa_DrawBuffer( GLenum mode )
             return;
          }
          break;
+#endif
       default:
          _mesa_error( ctx, GL_INVALID_ENUM, "glDrawBuffer" );
          return;
@@ -275,7 +316,17 @@ _mesa_DrawBuffer( GLenum mode )
 }
 
 
-
+/**
+ * Set the color buffer source for reading pixels.
+ *
+ * \param mode color buffer.
+ *
+ * \sa glReadBuffer().
+ *
+ * Verifies the parameter and updates gl_pixel_attrib::_ReadSrcMask.  Marks
+ * new pixel state in __GLcontextRec::NewState and notifies the driver via
+ * dd_function_table::ReadBuffer.
+ */
 void
 _mesa_ReadBuffer( GLenum mode )
 {
@@ -304,6 +355,7 @@ _mesa_ReadBuffer( GLenum mode )
          }
          ctx->Pixel._ReadSrcMask = BACK_LEFT_BIT;
          break;
+#if _HAVE_FULL_GL
       case GL_FRONT_RIGHT:
       case GL_RIGHT:
          if (!ctx->Visual.stereoMode) {
@@ -355,6 +407,7 @@ _mesa_ReadBuffer( GLenum mode )
             return;
          }
          break;
+#endif
       default:
          _mesa_error( ctx, GL_INVALID_ENUM, "glReadBuffer" );
          return;
@@ -370,8 +423,11 @@ _mesa_ReadBuffer( GLenum mode )
       (*ctx->Driver.ReadBuffer)(ctx, mode);
 }
 
+#if _HAVE_FULL_GL
 
 /**
+ * GL_MESA_resize_buffers extension.
+ *
  * When this function is called, we'll ask the window system how large
  * the current window is.  If it's a new size, we'll call the driver's
  * ResizeBuffers function.  The driver will then resize its color buffers
@@ -429,7 +485,41 @@ _mesa_ResizeBuffersMESA( void )
    }
 }
 
+/*
+ * XXX move somewhere else someday?
+ */
+void
+_mesa_SampleCoverageARB(GLclampf value, GLboolean invert)
+{
+   GLcontext *ctx = _mesa_get_current_context();
 
+   if (!ctx->Extensions.ARB_multisample) {
+      _mesa_error(ctx, GL_INVALID_OPERATION, "glSampleCoverageARB");
+      return;
+   }
+
+   ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH( ctx );
+   ctx->Multisample.SampleCoverageValue = (GLfloat) CLAMP(value, 0.0, 1.0);
+   ctx->Multisample.SampleCoverageInvert = invert;
+   ctx->NewState |= _NEW_MULTISAMPLE;
+}
+
+#endif
+
+
+/**
+ * Define the scissor box.
+ *
+ * \param x, y coordinates of the scissor box lower-left corner.
+ * \param width width of the scissor box.
+ * \param height height of the scissor box.
+ *
+ * \sa glScissor().
+ *
+ * Verifies the parameters and updates __GLcontextRec::Scissor. On a
+ * change flushes the vertices and notifies the driver via
+ * the dd_function_table::Scissor callback.
+ */
 void
 _mesa_Scissor( GLint x, GLint y, GLsizei width, GLsizei height )
 {
@@ -460,23 +550,71 @@ _mesa_Scissor( GLint x, GLint y, GLsizei width, GLsizei height )
       ctx->Driver.Scissor( ctx, x, y, width, height );
 }
 
+/**********************************************************************/
+/** \name State management */
+/*@{*/
 
-/*
- * XXX move somewhere else someday?
+/**
+ * Update screen bounds.
+ *
+ * \param ctx GL context.
+ *
+ * Update gl_frame_buffer::_Xmin, and etc.
  */
-void
-_mesa_SampleCoverageARB(GLclampf value, GLboolean invert)
+void _mesa_update_buffers( GLcontext *ctx )
 {
-   GLcontext *ctx = _mesa_get_current_context();
-
-   if (!ctx->Extensions.ARB_multisample) {
-      _mesa_error(ctx, GL_INVALID_OPERATION, "glSampleCoverageARB");
-      return;
+   ctx->DrawBuffer->_Xmin = 0;
+   ctx->DrawBuffer->_Ymin = 0;
+   ctx->DrawBuffer->_Xmax = ctx->DrawBuffer->Width;
+   ctx->DrawBuffer->_Ymax = ctx->DrawBuffer->Height;
+   if (ctx->Scissor.Enabled) {
+      if (ctx->Scissor.X > ctx->DrawBuffer->_Xmin) {
+	 ctx->DrawBuffer->_Xmin = ctx->Scissor.X;
+      }
+      if (ctx->Scissor.Y > ctx->DrawBuffer->_Ymin) {
+	 ctx->DrawBuffer->_Ymin = ctx->Scissor.Y;
+      }
+      if (ctx->Scissor.X + ctx->Scissor.Width < ctx->DrawBuffer->_Xmax) {
+	 ctx->DrawBuffer->_Xmax = ctx->Scissor.X + ctx->Scissor.Width;
+      }
+      if (ctx->Scissor.Y + ctx->Scissor.Height < ctx->DrawBuffer->_Ymax) {
+	 ctx->DrawBuffer->_Ymax = ctx->Scissor.Y + ctx->Scissor.Height;
+      }
    }
-
-   ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH( ctx );
-   ctx->Multisample.SampleCoverageValue = (GLfloat) CLAMP(value, 0.0, 1.0);
-   ctx->Multisample.SampleCoverageInvert = invert;
-   ctx->NewState |= _NEW_MULTISAMPLE;
 }
+
+/*@}*/
+
 			   
+/**********************************************************************/
+/** \name Initialization */
+/*@{*/
+
+/**
+ * Initialize the context scissor data.
+ *
+ * \param ctx GL context.
+ * 
+ * Initializes the __GLcontextRec::Scissor and __GLcontextRec::Multisample
+ * attribute groups, and related constants in __GLcontextRec::Const.
+ */
+void _mesa_init_buffers( GLcontext * ctx )
+{
+   /* Scissor group */
+   ctx->Scissor.Enabled = GL_FALSE;
+   ctx->Scissor.X = 0;
+   ctx->Scissor.Y = 0;
+   ctx->Scissor.Width = 0;
+   ctx->Scissor.Height = 0;
+
+   /* Multisample */
+   ctx->Multisample.Enabled = GL_FALSE;
+   ctx->Multisample.SampleAlphaToCoverage = GL_FALSE;
+   ctx->Multisample.SampleAlphaToOne = GL_FALSE;
+   ctx->Multisample.SampleCoverage = GL_FALSE;
+   ctx->Multisample.SampleCoverageValue = 1.0;
+   ctx->Multisample.SampleCoverageInvert = GL_FALSE;
+
+}
+
+/*@}*/
diff --git a/src/mesa/main/buffers.h b/src/mesa/main/buffers.h
index dfa2131309..7c992a98ca 100644
--- a/src/mesa/main/buffers.h
+++ b/src/mesa/main/buffers.h
@@ -1,3 +1,7 @@
+/**
+ * \file buffers.h
+ * Frame buffer management functions declarations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,6 +28,7 @@
  */
 
 
+
 #ifndef BUFFERS_H
 #define BUFFERS_H
 
@@ -56,5 +61,10 @@ _mesa_Scissor( GLint x, GLint y, GLsizei width, GLsizei height );
 extern void
 _mesa_SampleCoverageARB(GLclampf value, GLboolean invert);
 
+extern void 
+_mesa_init_buffers( GLcontext * ctx );
+
+extern void 
+_mesa_update_buffers( GLcontext *ctx );
 
 #endif
diff --git a/src/mesa/main/clip.c b/src/mesa/main/clip.c
index 3050f4e379..a061980af4 100644
--- a/src/mesa/main/clip.c
+++ b/src/mesa/main/clip.c
@@ -116,3 +116,4 @@ _mesa_GetClipPlane( GLenum plane, GLdouble *equation )
    equation[2] = (GLdouble) ctx->Transform.EyeUserPlane[p][2];
    equation[3] = (GLdouble) ctx->Transform.EyeUserPlane[p][3];
 }
+
diff --git a/src/mesa/main/clip.h b/src/mesa/main/clip.h
index fffcf13e97..154e3ce948 100644
--- a/src/mesa/main/clip.h
+++ b/src/mesa/main/clip.h
@@ -1,3 +1,6 @@
+/**
+ * \file clip.h
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -25,8 +28,6 @@
 
 
 
-
-
 #ifndef CLIP_H
 #define CLIP_H
 
diff --git a/src/mesa/main/colormac.h b/src/mesa/main/colormac.h
index e26052343e..cf89a818f6 100644
--- a/src/mesa/main/colormac.h
+++ b/src/mesa/main/colormac.h
@@ -1,3 +1,7 @@
+/**
+ * \file colormac.h
+ * Color-related macros
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -25,10 +29,6 @@
 
 
 
-/*
- * Color-related macros
- */
-
 #ifndef COLORMAC_H
 #define COLORMAC_H
 
@@ -38,6 +38,42 @@
 #include "macros.h"
 
 
+/** \def BYTE_TO_CHAN
+ * Convert from GLbyte to GLchan */
+
+/** \def UBYTE_TO_CHAN
+ * Convert from GLubyte to GLchan */
+
+/** \def SHORT_TO_CHAN
+ * Convert from GLshort to GLchan */
+
+/** \def USHORT_TO_CHAN
+ * Convert from GLushort to GLchan */
+
+/** \def INT_TO_CHAN
+ * Convert from GLint to GLchan */
+
+/** \def UINT_TO_CHAN
+ * Convert from GLuint to GLchan */
+
+/** \def CHAN_TO_UBYTE
+ * Convert from GLchan to GLubyte */
+
+/** \def CHAN_TO_FLOAT
+ * Convert from GLchan to GLfloat */
+
+/** \def CLAMPED_FLOAT_TO_CHAN
+ * Convert from GLclampf to GLchan */
+
+/** \def UNCLAMPED_FLOAT_TO_CHAN
+ * Convert from GLfloat to GLchan */
+
+/** \def COPY_CHAN4
+ * Copy a GLchan[4] array */
+
+/** \def CHAN_PRODUCT
+ * Scaled product (usually approximated) between two GLchan arguments */
+
 #if CHAN_BITS == 8
 
 #define BYTE_TO_CHAN(b)   ((b) < 0 ? 0 : (GLchan) (b))
@@ -57,7 +93,6 @@
 
 #define CHAN_PRODUCT(a, b)  ((GLubyte) (((GLint)(a) * ((GLint)(b) + 1)) >> 8))
 
-
 #elif CHAN_BITS == 16
 
 #define BYTE_TO_CHAN(b)   ((b) < 0 ? 0 : (((GLchan) (b)) * 516))
@@ -77,7 +112,6 @@
 
 #define CHAN_PRODUCT(a, b) ((GLchan) ((((GLuint) (a)) * ((GLuint) (b))) / 65535))
 
-
 #elif CHAN_BITS == 32
 
 /* XXX floating-point color channels not fully thought-out */
@@ -105,9 +139,13 @@
 #endif
 
 
-
-/*
+/**
  * Convert 3 channels at once.
+ *
+ * \param dst pointer to destination GLchan[3] array.
+ * \param f pointer to source GLfloat[3] array.
+ *
+ * \sa #UNCLAMPED_FLOAT_TO_CHAN.
  */
 #define UNCLAMPED_FLOAT_TO_RGB_CHAN(dst, f)	\
 do {						\
@@ -117,8 +155,13 @@ do {						\
 } while (0)
 
 
-/*
+/**
  * Convert 4 channels at once.
+ *
+ * \param dst pointer to destination GLchan[4] array.
+ * \param f pointer to source GLfloat[4] array.
+ *
+ * \sa #UNCLAMPED_FLOAT_TO_CHAN.
  */
 #define UNCLAMPED_FLOAT_TO_RGBA_CHAN(dst, f)	\
 do {						\
@@ -130,9 +173,12 @@ do {						\
 
 
 
-/* Generic color packing macros
- * XXX We may move these into texutil.h at some point.
+/**
+ * \name Generic color packing macros
+ *
+ * \todo We may move these into texutil.h at some point.
  */
+/*@{*/
 
 #define PACK_COLOR_8888( a, b, c, d )					\
    (((a) << 24) | ((b) << 16) | ((c) << 8) | (d))
@@ -187,5 +233,7 @@ do {						\
 
 #endif	/* endianness */
 
+/*@}*/
+
 
 #endif /* COLORMAC_H */
diff --git a/src/mesa/main/colortab.c b/src/mesa/main/colortab.c
index 78ef93caa6..9a1734bf4b 100644
--- a/src/mesa/main/colortab.c
+++ b/src/mesa/main/colortab.c
@@ -92,26 +92,6 @@ base_colortab_format( GLenum format )
 }
 
 
-void
-_mesa_init_colortable( struct gl_color_table *p )
-{
-   p->FloatTable = GL_FALSE;
-   p->Table = NULL;
-   p->Size = 0;
-   p->IntFormat = GL_RGBA;
-}
-
-
-
-void
-_mesa_free_colortable_data( struct gl_color_table *p )
-{
-   if (p->Table) {
-      FREE(p->Table);
-      p->Table = NULL;
-   }
-}
-
 
 /*
  * Examine table's format and set the component sizes accordingly.
@@ -1345,3 +1325,49 @@ _mesa_GetColorTableParameteriv( GLenum target, GLenum pname, GLint *params )
          return;
    }
 }
+
+/**********************************************************************/
+/*****                      Initialization                        *****/
+/**********************************************************************/
+
+
+void
+_mesa_init_one_colortable( struct gl_color_table *p )
+{
+   p->FloatTable = GL_FALSE;
+   p->Table = NULL;
+   p->Size = 0;
+   p->IntFormat = GL_RGBA;
+}
+
+
+
+void
+_mesa_free_one_colortable( struct gl_color_table *p )
+{
+   if (p->Table) {
+      FREE(p->Table);
+      p->Table = NULL;
+   }
+}
+
+void _mesa_init_colortable( GLcontext * ctx )
+{
+   /* Color tables */
+   _mesa_init_one_colortable(&ctx->ColorTable);
+   _mesa_init_one_colortable(&ctx->ProxyColorTable);
+   _mesa_init_one_colortable(&ctx->PostConvolutionColorTable);
+   _mesa_init_one_colortable(&ctx->ProxyPostConvolutionColorTable);
+   _mesa_init_one_colortable(&ctx->PostColorMatrixColorTable);
+   _mesa_init_one_colortable(&ctx->ProxyPostColorMatrixColorTable);
+}
+
+void _mesa_free_colortable_data( GLcontext *ctx )
+{
+   _mesa_free_one_colortable( &ctx->ColorTable );
+   _mesa_free_one_colortable( &ctx->ProxyColorTable );
+   _mesa_free_one_colortable( &ctx->PostConvolutionColorTable );
+   _mesa_free_one_colortable( &ctx->ProxyPostConvolutionColorTable );
+   _mesa_free_one_colortable( &ctx->PostColorMatrixColorTable );
+   _mesa_free_one_colortable( &ctx->ProxyPostColorMatrixColorTable );
+}
diff --git a/src/mesa/main/colortab.h b/src/mesa/main/colortab.h
index e3bc76e5c3..959547e28b 100644
--- a/src/mesa/main/colortab.h
+++ b/src/mesa/main/colortab.h
@@ -1,3 +1,12 @@
+/**
+ * \file colortab.h
+ * Color tables.
+ * 
+ * \if subset
+ * (No-op)
+ *
+ * \endif
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -30,57 +39,67 @@
 
 #include "mtypes.h"
 
-
-extern void
-_mesa_init_colortable( struct gl_color_table *p );
-
-extern void
-_mesa_free_colortable_data( struct gl_color_table *p );
-
+#if _HAVE_FULL_GL
 
 extern void
 _mesa_ColorTable( GLenum target, GLenum internalformat,
                   GLsizei width, GLenum format, GLenum type,
                   const GLvoid *table );
 
-
 extern void
 _mesa_ColorSubTable( GLenum target, GLsizei start,
                      GLsizei count, GLenum format, GLenum type,
                      const GLvoid *table );
 
-
 extern void
 _mesa_CopyColorSubTable(GLenum target, GLsizei start,
                         GLint x, GLint y, GLsizei width);
 
-
 extern void
 _mesa_CopyColorTable(GLenum target, GLenum internalformat,
                      GLint x, GLint y, GLsizei width);
 
-
 extern void
 _mesa_GetColorTable( GLenum target, GLenum format,
                      GLenum type, GLvoid *table );
 
-
 extern void
 _mesa_ColorTableParameterfv(GLenum target, GLenum pname,
                             const GLfloat *params);
 
-
 extern void
 _mesa_ColorTableParameteriv(GLenum target, GLenum pname,
                             const GLint *params);
 
-
 extern void
 _mesa_GetColorTableParameterfv( GLenum target, GLenum pname, GLfloat *params );
 
-
 extern void
 _mesa_GetColorTableParameteriv( GLenum target, GLenum pname, GLint *params );
 
+extern void 
+_mesa_init_colortable( GLcontext * ctx );
+
+extern void 
+_mesa_free_colortable_data( GLcontext * ctx );
+
+extern void
+_mesa_free_one_colortable( struct gl_color_table *p );
+
+extern void
+_mesa_init_one_colortable( struct gl_color_table *p );
+
+#else
+
+/** No-op */
+#define _mesa_init_one_colortable( p ) ((void)0)
+
+/** No-op */
+#define _mesa_init_colortable( p ) ((void)0)
+
+/** No-op */
+#define _mesa_free_colortable_data( p ) ((void)0)
+
+#endif
 
 #endif
diff --git a/src/mesa/main/config.h b/src/mesa/main/config.h
index 4b4b3ef10a..ebbdeaa704 100644
--- a/src/mesa/main/config.h
+++ b/src/mesa/main/config.h
@@ -1,3 +1,8 @@
+/**
+ * \file config.h
+ * Tunable configuration parameters.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -23,12 +28,6 @@
  */
 
 
-/*
- * Tunable configuration parameters.
- */
-
-
-
 #ifndef CONFIG_H
 #define CONFIG_H
 
@@ -37,113 +36,126 @@
 #endif
 
 
-/*
- * OpenGL implementation limits
+/**
+ * \name OpenGL implementation limits
  */
+/*@{*/
 
-/* Maximum modelview matrix stack depth: */
+/** Maximum modelview matrix stack depth */
 #define MAX_MODELVIEW_STACK_DEPTH 32
 
-/* Maximum projection matrix stack depth: */
+/** Maximum projection matrix stack depth */
 #define MAX_PROJECTION_STACK_DEPTH 32
 
-/* Maximum texture matrix stack depth: */
+/** Maximum texture matrix stack depth */
 #define MAX_TEXTURE_STACK_DEPTH 10
 
-/* Maximum color matrix stack depth: */
+/** Maximum color matrix stack depth */
 #define MAX_COLOR_STACK_DEPTH 4
 
-/* Maximum attribute stack depth: */
+/** Maximum attribute stack depth */
 #define MAX_ATTRIB_STACK_DEPTH 16
 
-/* Maximum client attribute stack depth: */
+/** Maximum client attribute stack depth */
 #define MAX_CLIENT_ATTRIB_STACK_DEPTH 16
 
-/* Maximum recursion depth of display list calls: */
+/** Maximum recursion depth of display list calls */
 #define MAX_LIST_NESTING 64
 
-/* Maximum number of lights: */
+/** Maximum number of lights */
 #define MAX_LIGHTS 8
 
-/* Maximum user-defined clipping planes: */
+/** Maximum user-defined clipping planes */
 #define MAX_CLIP_PLANES 6
 
-/* Maximum pixel map lookup table size: */
+/** Maximum pixel map lookup table size */
 #define MAX_PIXEL_MAP_TABLE 256
 
-/* Number of auxillary color buffers: */
+/** Number of auxillary color buffers */
 #define NUM_AUX_BUFFERS 0
 
-/* Maximum order (degree) of curves: */
+/** Maximum order (degree) of curves */
 #ifdef AMIGA
 #   define MAX_EVAL_ORDER 12
 #else
 #   define MAX_EVAL_ORDER 30
 #endif
 
-/* Maximum Name stack depth */
+/** Maximum Name stack depth */
 #define MAX_NAME_STACK_DEPTH 64
 
-/* Min and Max point sizes and granularity */
+/** Minimum point size */
 #define MIN_POINT_SIZE 1.0
+/** Maximum point size */
 #define MAX_POINT_SIZE 20.0
+/** Point size granularity */
 #define POINT_SIZE_GRANULARITY 0.1
 
-/* Min and Max line widths and granularity */
+/** Minimum line width */
 #define MIN_LINE_WIDTH 1.0
+/** Maximum line width */
 #define MAX_LINE_WIDTH 10.0
+/** Line width granularity */
 #define LINE_WIDTH_GRANULARITY 0.1
 
-/* Max texture palette / color table size */
+/** Max texture palette / color table size */
 #define MAX_COLOR_TABLE_SIZE 256
 
-/* Number of 1D/2D texture mipmap levels */
+/** Number of 1D/2D texture mipmap levels */
 #define MAX_TEXTURE_LEVELS 12
 
-/* Number of 3D texture mipmap levels */
+/** Number of 3D texture mipmap levels */
 #define MAX_3D_TEXTURE_LEVELS 9
 
-/* Number of cube texture mipmap levels - GL_ARB_texture_cube_map */
+/** Number of cube texture mipmap levels - GL_ARB_texture_cube_map */
 #define MAX_CUBE_TEXTURE_LEVELS 12
 
-/* Maximum rectangular texture size - GL_NV_texture_rectangle */
+/** Maximum rectangular texture size - GL_NV_texture_rectangle */
 #define MAX_TEXTURE_RECT_SIZE 2048
 
-/* Number of texture units - GL_ARB_multitexture */
+/** Number of texture units - GL_ARB_multitexture */
 #define MAX_TEXTURE_UNITS 8
 
-/* New: separate numbers of texture coordinates and texture image units.
+/**
+ * \name Separate numbers of texture coordinates and texture image units.
+ *
  * These values will eventually replace most instances of MAX_TEXTURE_UNITS.
  * We should always have MAX_TEXTURE_COORD_UNITS <= MAX_TEXTURE_IMAGE_UNITS.
  * And, GL_MAX_TEXTURE_UNITS <= MAX_TEXTURE_COORD_UNITS.
  */
+/*@{*/
 #define MAX_TEXTURE_COORD_UNITS 8
 #define MAX_TEXTURE_IMAGE_UNITS 8
+/*@}*/
 
-/* Maximum viewport/image size (must accomodate all texture sizes too): */
+/** 
+ * Maximum viewport/image width. Must accomodate all texture sizes too. 
+ */
 #define MAX_WIDTH 2048
+/** Maximum viewport/image height */
 #define MAX_HEIGHT 2048
 
-/* Maxmimum size for CVA.  May be overridden by the drivers.  */
+/** Maxmimum size for CVA.  May be overridden by the drivers.  */
 #define MAX_ARRAY_LOCK_SIZE 3000
 
-/* Subpixel precision for antialiasing, window coordinate snapping */
+/** Subpixel precision for antialiasing, window coordinate snapping */
 #define SUB_PIXEL_BITS 4
 
-/* Size of histogram tables */
+/** Size of histogram tables */
 #define HISTOGRAM_TABLE_SIZE 256
 
-/* Max convolution filter sizes */
+/** Max convolution filter width */
 #define MAX_CONVOLUTION_WIDTH 9
+/** Max convolution filter height */
 #define MAX_CONVOLUTION_HEIGHT 9
 
-/* GL_ARB_texture_compression */
+/** GL_ARB_texture_compression */
 #define MAX_COMPRESSED_TEXTURE_FORMATS 25
 
-/* GL_EXT_texture_filter_anisotropic */
+/** GL_EXT_texture_filter_anisotropic */
 #define MAX_TEXTURE_MAX_ANISOTROPY 16.0
 
-/* GL_EXT_texture_lod_bias */
+/** GL_EXT_texture_lod_bias */
 #define MAX_TEXTURE_LOD_BIAS 4.0
 
 /* GL_NV_vertex_program */
@@ -175,28 +187,30 @@
 #define MAX_PROGRAM_MATRICES 8
 #define MAX_PROGRAM_MATRIX_STACK_DEPTH 4
 
+/*@}*/
 
 
-
-/*
- * Mesa-specific parameters
+/**
+ * \name Mesa-specific parameters
  */
+/*@{*/
 
 
-/*
+/**
  * Bits per accumulation buffer color component:  8, 16 or 32
  */
 #define ACCUM_BITS 16
 
-
-/*
- * Bits per depth buffer value.  Any reasonable value up to 31 will
- * work.  32 doesn't work because of integer overflow problems in the
- * rasterizer code.
+/**
+ * Bits per depth buffer value.  
+ *
+ * Any reasonable value up to 31 will work.  32 doesn't work because of integer
+ * overflow problems in the rasterizer code.
  */
 #ifndef DEFAULT_SOFTWARE_DEPTH_BITS
 #define DEFAULT_SOFTWARE_DEPTH_BITS 16
 #endif
+/** Depth buffer data type */
 #if DEFAULT_SOFTWARE_DEPTH_BITS <= 16
 #define DEFAULT_SOFTWARE_DEPTH_TYPE GLushort
 #else
@@ -204,14 +218,13 @@
 #endif
 
 
-
-/*
- * Bits per stencil value:  8
+/**
+ * Bits per stencil value: 8
  */
 #define STENCIL_BITS 8
 
 
-/*
+/**
  * Bits per color channel:  8, 16 or 32
  */
 #ifndef CHAN_BITS
@@ -221,19 +234,27 @@
 
 /*
  * Color channel component order
- * (changes will almost certainly cause problems at this time)
+ * 
+ * \note Changes will almost certainly cause problems at this time.
  */
 #define RCOMP 0
 #define GCOMP 1
 #define BCOMP 2
 #define ACOMP 3
 
-
+#ifndef _HAVE_FULL_GL
+#define _HAVE_FULL_GL 1
+#endif
 
 /*
  * Enable/disable features (blocks of code) by setting FEATURE_xyz to 0 or 1.
  */
+#if _HAVE_FULL_GL
 #define FEATURE_NV_vertex_program 1
+#define FEATURE_userclip 1
+#define FEATURE_texgen 1
+#define FEATURE_windowpos 1
+#endif
 
 #define FEATURE_NV_fragment_program 1
 
@@ -245,4 +266,12 @@
 
 #define FEATURE_ARB_occlusion_query 1
 
+/*@}*/
+
+
+#ifndef _HAVE_FULL_GL
+#define _HAVE_FULL_GL 1
+#endif
+
+
 #endif /* CONFIG_H */
diff --git a/src/mesa/main/context.c b/src/mesa/main/context.c
index cd4c666715..adcdce09cd 100644
--- a/src/mesa/main/context.c
+++ b/src/mesa/main/context.c
@@ -1,3 +1,9 @@
+/**
+ * \file context.c
+ * Mesa context/visual/framebuffer management functions.
+ * \author Brian Paul
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -23,24 +29,81 @@
  */
 
 
+/**
+ * \mainpage Mesa Core Module
+ *
+ * \section CoreIntroduction Introduction
+ *
+ * The Mesa core module consists of all the top-level files in the src
+ * directory.  The core module basically takes care of API dispatch,
+ * and OpenGL state management.
+ *
+ * For example, calls to glPolygonMode() are routed to _mesa_PolygonMode()
+ * which updates the state related to polygonmode.  Furthermore, dirty
+ * state flags related to polygon mode are set and if the device driver
+ * implements a special routine for PolygonMode, it will be called.
+ *
+ *
+ * \section AboutDoxygen About Doxygen
+ *
+ * If you're viewing this information as Doxygen-generated HTML you'll
+ * see the documentation index at the top of this page.
+ *
+ * The first line lists the Mesa source code modules.
+ * The second line lists the indexes available for viewing the documentation
+ * for each module.
+ *
+ * Selecting the <b>Main page</b> link will display a summary of the module
+ * (this page).
+ *
+ * Selecting <b>Compound List</b> will list all C structures.
+ *
+ * Selecting the <b>File List</b> link will list all the source files in
+ * the module.
+ * Selecting a filename will show a list of all functions defined in that file.
+ *
+ * Selecting the <b>Compound Members</b> link will display a list of all
+ * documented structure members.
+ *
+ * Selecting the <b>File Members</b> link will display a list
+ * of all functions, structures, global variables and macros in the module.
+ *
+ */
+
+
 #include "glheader.h"
 #include "imports.h"
+#include "accum.h"
+#include "attrib.h"
+#include "blend.h"
 #include "buffers.h"
-#include "clip.h"
+/*#include "clip.h"*/
 #include "colortab.h"
 #include "context.h"
+#include "debug.h"
+#include "depth.h"
 #include "dlist.h"
 #include "eval.h"
 #include "enums.h"
 #include "extensions.h"
+#include "feedback.h"
 #include "fog.h"
 #include "get.h"
 #include "glthread.h"
+#include "histogram.h"
+#include "hint.h"
 #include "hash.h"
 #include "light.h"
+#include "lines.h"
 #include "macros.h"
+#include "matrix.h"
+#include "pixel.h"
+#include "points.h"
+#include "polygon.h"
+#include "rastpos.h"
 #include "simple_list.h"
 #include "state.h"
+#include "stencil.h"
 #include "teximage.h"
 #include "texobj.h"
 #include "texstate.h"
@@ -54,11 +117,12 @@
 #include "nvfragprog.h"
 #endif
 #include "vtxfmt.h"
+#if _HAVE_FULL_GL
 #include "math/m_translate.h"
 #include "math/m_matrix.h"
 #include "math/m_xform.h"
 #include "math/mathmod.h"
-
+#endif
 
 #if defined(MESA_TRACE)
 #include "Trace/tr_context.h"
@@ -86,11 +150,26 @@ free_shared_state( GLcontext *ctx, struct gl_shared_state *ss );
 
 
 /**********************************************************************/
-/*****       OpenGL SI-style interface (new in Mesa 3.5)          *****/
-/**********************************************************************/
+/** \name OpenGL SI-style interface (new in Mesa 3.5)
+ *
+ * \if subset
+ * \note Most of these functions are never called in the Mesa subset.
+ * \endif
+ */
+/*@{*/
 
-/* Called by window system/device driver (via gc->exports.destroyCurrent())
- * when the rendering context is to be destroyed.
+/**
+ * Destroy context callback.
+ * 
+ * \param gc context.
+ * \return GL_TRUE on success, or GL_FALSE on failure.
+ * 
+ * \ifnot subset
+ * Called by window system/device driver (via __GLexports::destroyCurrent) when
+ * the rendering context is to be destroyed.
+ * \endif
+ *
+ * Frees the context data and the context structure.
  */
 GLboolean
 _mesa_destroyContext(__GLcontext *gc)
@@ -102,8 +181,18 @@ _mesa_destroyContext(__GLcontext *gc)
    return GL_TRUE;
 }
 
-/* Called by window system/device driver (via gc->exports.loseCurrent())
+/**
+ * Unbind context callback.
+ * 
+ * \param gc context.
+ * \return GL_TRUE on success, or GL_FALSE on failure.
+ *
+ * \ifnot subset
+ * Called by window system/device driver (via __GLexports::loseCurrent)
  * when the rendering context is made non-current.
+ * \endif
+ *
+ * No-op
  */
 GLboolean
 _mesa_loseCurrent(__GLcontext *gc)
@@ -112,8 +201,18 @@ _mesa_loseCurrent(__GLcontext *gc)
    return GL_TRUE;
 }
 
-/* Called by window system/device driver (via gc->exports.makeCurrent())
+/**
+ * Bind context callback.
+ * 
+ * \param gc context.
+ * \return GL_TRUE on success, or GL_FALSE on failure.
+ *
+ * \ifnot subset
+ * Called by window system/device driver (via __GLexports::makeCurrent)
  * when the rendering context is made current.
+ * \endif
+ *
+ * No-op
  */
 GLboolean
 _mesa_makeCurrent(__GLcontext *gc)
@@ -122,8 +221,18 @@ _mesa_makeCurrent(__GLcontext *gc)
    return GL_TRUE;
 }
 
-/* Called by window system/device driver - yadda, yadda, yadda.
- * See above comments.
+/**
+ * Share context callback.
+ * 
+ * \param gc context.
+ * \param gcShare shared context.
+ * \return GL_TRUE on success, or GL_FALSE on failure.
+ *
+ * \ifnot subset
+ * Called by window system/device driver (via __GLexports::shareContext)
+ * \endif
+ *
+ * Update the shared context reference count, gl_shared_state::RefCount.
  */
 GLboolean
 _mesa_shareContext(__GLcontext *gc, __GLcontext *gcShare)
@@ -142,6 +251,11 @@ _mesa_shareContext(__GLcontext *gc, __GLcontext *gcShare)
    }
 }
 
+
+#if _HAVE_FULL_GL
+/**
+ * Copy context callback.
+ */
 GLboolean
 _mesa_copyContext(__GLcontext *dst, const __GLcontext *src, GLuint mask)
 {
@@ -153,13 +267,21 @@ _mesa_copyContext(__GLcontext *dst, const __GLcontext *src, GLuint mask)
       return GL_FALSE;
    }
 }
+#endif
 
+/** No-op */
 GLboolean
 _mesa_forceCurrent(__GLcontext *gc)
 {
    return GL_TRUE;
 }
 
+/**
+ * Windows/buffer resizing notification callback.
+ *
+ * \param gc GL context.
+ * \return GL_TRUE on success, or GL_FALSE on failure.
+ */
 GLboolean
 _mesa_notifyResize(__GLcontext *gc)
 {
@@ -173,14 +295,27 @@ _mesa_notifyResize(__GLcontext *gc)
    return GL_TRUE;
 }
 
+/**
+ * Window/buffer destruction notification callback.
+ *
+ * \param gc GL context.
+ * 
+ * Called when the context's window/buffer is going to be destroyed. 
+ *
+ * No-op
+ */
 void
 _mesa_notifyDestroy(__GLcontext *gc)
 {
-   /* Called when the context's window/buffer is going to be destroyed. */
    /* Unbind from it. */
 }
 
-/* Called by window system just before swapping buffers.
+/**
+ * Swap buffers notification callback.
+ * 
+ * \param gc GL context.
+ *
+ * Called by window system just before swapping buffers.
  * We have to finish any pending rendering.
  */
 void
@@ -189,33 +324,48 @@ _mesa_notifySwapBuffers(__GLcontext *gc)
    FLUSH_VERTICES( gc, 0 );
 }
 
+/** No-op */
 struct __GLdispatchStateRec *
 _mesa_dispatchExec(__GLcontext *gc)
 {
    return NULL;
 }
 
+/** No-op */
 void
 _mesa_beginDispatchOverride(__GLcontext *gc)
 {
 }
 
+/** No-op */
 void
 _mesa_endDispatchOverride(__GLcontext *gc)
 {
 }
 
-/* Setup the exports.  The window system will call these functions
- * when it needs Mesa to do something.
- * NOTE: Device drivers should override these functions!  For example,
+/**
+ * \ifnot subset
+ * Setup the exports.  
+ *
+ * The window system will call these functions when it needs Mesa to do
+ * something.
+ * 
+ * \note Device drivers should override these functions!  For example,
  * the Xlib driver should plug in the XMesa*-style functions into this
  * structure.  The XMesa-style functions should then call the _mesa_*
  * version of these functions.  This is an approximation to OO design
  * (inheritance and virtual functions).
+ * \endif
+ *
+ * \if subset
+ * No-op.
+ * 
+ * \endif
  */
 static void
 _mesa_init_default_exports(__GLexports *exports)
 {
+#if _HAVE_FULL_GL
     exports->destroyContext = _mesa_destroyContext;
     exports->loseCurrent = _mesa_loseCurrent;
     exports->makeCurrent = _mesa_makeCurrent;
@@ -228,11 +378,12 @@ _mesa_init_default_exports(__GLexports *exports)
     exports->dispatchExec = _mesa_dispatchExec;
     exports->beginDispatchOverride = _mesa_beginDispatchOverride;
     exports->endDispatchOverride = _mesa_endDispatchOverride;
+#endif
 }
 
-
-
-/* exported OpenGL SI interface */
+/**
+ * Exported OpenGL SI interface.
+ */
 __GLcontext *
 __glCoreCreateContext(__GLimports *imports, __GLcontextModes *modes)
 {
@@ -249,8 +400,9 @@ __glCoreCreateContext(__GLimports *imports, __GLcontextModes *modes)
     return ctx;
 }
 
-
-/* exported OpenGL SI interface */
+/**
+ * Exported OpenGL SI interface.
+ */
 void
 __glCoreNopDispatch(void)
 {
@@ -263,28 +415,38 @@ __glCoreNopDispatch(void)
 #endif
 }
 
+/*@}*/
+
 
 /**********************************************************************/
-/***** GL Visual allocation/destruction                           *****/
+/** \name GL Visual allocation/destruction                            */
 /**********************************************************************/
+/*@{*/
 
-
-/*
+/**
  * Allocate a new GLvisual object.
- * Input:  rgbFlag - GL_TRUE=RGB(A) mode, GL_FALSE=Color Index mode
- *         dbFlag - double buffering?
- *         stereoFlag - stereo buffer?
- *         depthBits - requested bits per depth buffer value
- *                     Any value in [0, 32] is acceptable but the actual
- *                     depth type will be GLushort or GLuint as needed.
- *         stencilBits - requested minimum bits per stencil buffer value
- *         accumBits - requested minimum bits per accum buffer component
- *         indexBits - number of bits per pixel if rgbFlag==GL_FALSE
- *         red/green/blue/alphaBits - number of bits per color component
- *                                    in frame buffer for RGB(A) mode.
- *                                    We always use 8 in core Mesa though.
- * Return:  pointer to new GLvisual or NULL if requested parameters can't
- *          be met.
+ * 
+ * \param rgbFlag GL_TRUE for RGB(A) mode, GL_FALSE for Color Index mode.
+ * \param dbFlag double buffering
+ * \param stereoFlag stereo buffer
+ * \param depthBits requested bits per depth buffer value. Any value in [0, 32]
+ * is acceptable but the actual depth type will be GLushort or GLuint as
+ * needed.
+ * \param stencilBits requested minimum bits per stencil buffer value
+ * \param accumRedBits, accumGreenBits, accumBlueBits, accumAlphaBits number of bits per color component in accum buffer.
+ * \param indexBits number of bits per pixel if \p rgbFlag is GL_FALSE
+ * \param redBits number of bits per color component in frame buffer for RGB(A)
+ * mode.  We always use 8 in core Mesa though.
+ * \param greenBits same as above.
+ * \param blueBits same as above.
+ * \param alphaBits same as above.
+ * \param numSamples not really used.
+ * 
+ * \return pointer to new GLvisual or NULL if requested parameters can't be
+ * met.
+ *
+ * Allocates a GLvisual structure and initializes it via
+ * _mesa_initialize_visual().
  */
 GLvisual *
 _mesa_create_visual( GLboolean rgbFlag,
@@ -318,12 +480,15 @@ _mesa_create_visual( GLboolean rgbFlag,
    return vis;
 }
 
-
-/*
+/**
  * Initialize the fields of the given GLvisual.
- * Input:  see _mesa_create_visual() above.
- * Return: GL_TRUE = success
- *         GL_FALSE = failure.
+ * 
+ * \return GL_TRUE on success, or GL_FALSE on failure.
+ *
+ * \sa _mesa_create_visual() above for the parameter description.
+ *
+ * Makes some sanity checks and fills in the fields of the
+ * GLvisual structure with the given parameters.
  */
 GLboolean
 _mesa_initialize_visual( GLvisual *vis,
@@ -400,29 +565,43 @@ _mesa_initialize_visual( GLvisual *vis,
    return GL_TRUE;
 }
 
-
+/**
+ * Destroy a visual.
+ *
+ * \param vis visual.
+ * 
+ * Frees the visual structure.
+ */
 void
 _mesa_destroy_visual( GLvisual *vis )
 {
    FREE(vis);
 }
 
+/*@}*/
+
 
 /**********************************************************************/
-/***** GL Framebuffer allocation/destruction                      *****/
+/** \name GL Framebuffer allocation/destruction                       */
 /**********************************************************************/
+/*@{*/
 
-
-/*
- * Create a new framebuffer.  A GLframebuffer is a struct which
- * encapsulates the depth, stencil and accum buffers and related
- * parameters.
- * Input:  visual - a GLvisual pointer (we copy the struct contents)
- *         softwareDepth - create/use a software depth buffer?
- *         softwareStencil - create/use a software stencil buffer?
- *         softwareAccum - create/use a software accum buffer?
- *         softwareAlpha - create/use a software alpha buffer?
- * Return:  pointer to new GLframebuffer struct or NULL if error.
+/**
+ * Create a new framebuffer.  
+ *
+ * A GLframebuffer is a structure which encapsulates the depth, stencil and
+ * accum buffers and related parameters.
+ * 
+ * \param visual a GLvisual pointer (we copy the struct contents)
+ * \param softwareDepth create/use a software depth buffer?
+ * \param softwareStencil create/use a software stencil buffer?
+ * \param softwareAccum create/use a software accum buffer?
+ * \param softwareAlpha create/use a software alpha buffer?
+ *
+ * \return pointer to new GLframebuffer struct or NULL if error.
+ *
+ * Allocate a GLframebuffer structure and initializes it via
+ * _mesa_initialize_framebuffer().
  */
 GLframebuffer *
 _mesa_create_framebuffer( const GLvisual *visual,
@@ -441,10 +620,13 @@ _mesa_create_framebuffer( const GLvisual *visual,
    return buffer;
 }
 
-
-/*
+/**
  * Initialize a GLframebuffer object.
- * Input:  See _mesa_create_framebuffer() above.
+ * 
+ * \sa _mesa_create_framebuffer() above for the parameter description.
+ *
+ * Makes some sanity checks and fills in the fields of the
+ * GLframebuffer structure with the given parameters.
  */
 void
 _mesa_initialize_framebuffer( GLframebuffer *buffer,
@@ -484,9 +666,10 @@ _mesa_initialize_framebuffer( GLframebuffer *buffer,
    buffer->UseSoftwareAlphaBuffers = softwareAlpha;
 }
 
-
-/*
+/**
  * Free a framebuffer struct and its buffers.
+ *
+ * Calls _mesa_free_framebuffer_data() and frees the structure.
  */
 void
 _mesa_destroy_framebuffer( GLframebuffer *buffer )
@@ -497,9 +680,12 @@ _mesa_destroy_framebuffer( GLframebuffer *buffer )
    }
 }
 
-
-/*
- * Free the data hanging off of <buffer>, but not <buffer> itself.
+/**
+ * Free the data hanging off of \p buffer, but not \p buffer itself.
+ *
+ * \param buffer framebuffer.
+ *
+ * Frees all the buffers associated with the structure.
  */
 void
 _mesa_free_framebuffer_data( GLframebuffer *buffer )
@@ -539,18 +725,33 @@ _mesa_free_framebuffer_data( GLframebuffer *buffer )
    }
 }
 
+/*@}*/
 
 
 /**********************************************************************/
-/*****       Context allocation, initialization, destroying       *****/
+/** \name Context allocation, initialization, destroying
+ *
+ * The purpose of the most initialization functions here is to provide the
+ * default state values according to the OpenGL specification.
+ */
 /**********************************************************************/
+/*@{*/
 
-
+/**
+ * One-time initialization mutex lock.
+ *
+ * \sa Used by one_time_init().
+ */
 _glthread_DECLARE_STATIC_MUTEX(OneTimeLock);
 
-
-/*
- * This function just calls all the various one-time-init functions in Mesa.
+/**
+ * Calls all the various one-time-init functions in Mesa.
+ *
+ * While holding a global mutex lock, calls several initialization functions,
+ * and sets the glapi callbacks if the \c MESA_DEBUG environment variable is
+ * defined.
+ *
+ * \sa _mesa_init_lists(), _math_init().
  */
 static void
 one_time_init( GLcontext *ctx )
@@ -570,11 +771,13 @@ one_time_init( GLcontext *ctx )
 
       _mesa_init_lists();
 
+#if _HAVE_FULL_GL
       _math_init();
 
       for (i = 0; i < 256; i++) {
          _mesa_ubyte_to_float_color_tab[i] = (float) i / 255.0F;
       }
+#endif
 
 #ifdef USE_SPARC_ASM
       _mesa_init_sparc_glapi_relocs();
@@ -602,40 +805,15 @@ one_time_init( GLcontext *ctx )
    _glthread_UNLOCK_MUTEX(OneTimeLock);
 }
 
-
-static void
-init_matrix_stack( struct matrix_stack *stack,
-                   GLuint maxDepth, GLuint dirtyFlag )
-{
-   GLuint i;
-
-   stack->Depth = 0;
-   stack->MaxDepth = maxDepth;
-   stack->DirtyFlag = dirtyFlag;
-   /* The stack */
-   stack->Stack = (GLmatrix *) CALLOC(maxDepth * sizeof(GLmatrix));
-   for (i = 0; i < maxDepth; i++) {
-      _math_matrix_ctr(&stack->Stack[i]);
-      _math_matrix_alloc_inv(&stack->Stack[i]);
-   }
-   stack->Top = stack->Stack;
-}
-
-
-static void
-free_matrix_stack( struct matrix_stack *stack )
-{
-   GLuint i;
-   for (i = 0; i < stack->MaxDepth; i++) {
-      _math_matrix_dtr(&stack->Stack[i]);
-   }
-   FREE(stack->Stack);
-   stack->Stack = stack->Top = NULL;
-}
-
-
-/*
+/**
  * Allocate and initialize a shared context state structure.
+ *
+ * \return pointer to a gl_shared_state structure on success, or NULL on
+ * failure.
+ *
+ * Initializes the display list, texture objects and vertex programs hash
+ * tables, allocates the texture objects. If it runs out of memory, frees
+ * everything already allocated before returning NULL.
  */
 static GLboolean
 alloc_shared_state( GLcontext *ctx )
@@ -735,9 +913,17 @@ alloc_shared_state( GLcontext *ctx )
    return GL_FALSE;
 }
 
-
-/*
+/**
  * Deallocate a shared state context and all children structures.
+ *
+ * \param ctx GL context.
+ * \param ss shared state pointer.
+ * 
+ * Frees the display lists, the texture objects (calling the driver texture
+ * deletion callback to free its private data) and the vertex programs, as well
+ * as their hash tables.
+ *
+ * \sa alloc_shared_state().
  */
 static void
 free_shared_state( GLcontext *ctx, struct gl_shared_state *ss )
@@ -795,166 +981,30 @@ free_shared_state( GLcontext *ctx, struct gl_shared_state *ss )
 }
 
 
-
-/*
- * Initialize the nth light.  Note that the defaults for light 0 are
- * different than the other lights.
- */
-static void
-init_light( struct gl_light *l, GLuint n )
+static void _mesa_init_current( GLcontext *ctx )
 {
-   make_empty_list( l );
-
-   ASSIGN_4V( l->Ambient, 0.0, 0.0, 0.0, 1.0 );
-   if (n==0) {
-      ASSIGN_4V( l->Diffuse, 1.0, 1.0, 1.0, 1.0 );
-      ASSIGN_4V( l->Specular, 1.0, 1.0, 1.0, 1.0 );
-   }
-   else {
-      ASSIGN_4V( l->Diffuse, 0.0, 0.0, 0.0, 1.0 );
-      ASSIGN_4V( l->Specular, 0.0, 0.0, 0.0, 1.0 );
-   }
-   ASSIGN_4V( l->EyePosition, 0.0, 0.0, 1.0, 0.0 );
-   ASSIGN_3V( l->EyeDirection, 0.0, 0.0, -1.0 );
-   l->SpotExponent = 0.0;
-   _mesa_invalidate_spot_exp_table( l );
-   l->SpotCutoff = 180.0;
-   l->_CosCutoff = 0.0;		/* KW: -ve values not admitted */
-   l->ConstantAttenuation = 1.0;
-   l->LinearAttenuation = 0.0;
-   l->QuadraticAttenuation = 0.0;
-   l->Enabled = GL_FALSE;
-}
-
-
-
-static void
-init_lightmodel( struct gl_lightmodel *lm )
-{
-   ASSIGN_4V( lm->Ambient, 0.2F, 0.2F, 0.2F, 1.0F );
-   lm->LocalViewer = GL_FALSE;
-   lm->TwoSide = GL_FALSE;
-   lm->ColorControl = GL_SINGLE_COLOR;
-}
-
-
-static void
-init_material( struct gl_material *m )
-{
-   ASSIGN_4V( m->Ambient,  0.2F, 0.2F, 0.2F, 1.0F );
-   ASSIGN_4V( m->Diffuse,  0.8F, 0.8F, 0.8F, 1.0F );
-   ASSIGN_4V( m->Specular, 0.0F, 0.0F, 0.0F, 1.0F );
-   ASSIGN_4V( m->Emission, 0.0F, 0.0F, 0.0F, 1.0F );
-   m->Shininess = 0.0;
-   m->AmbientIndex = 0;
-   m->DiffuseIndex = 1;
-   m->SpecularIndex = 1;
-}
-
+   int i;
 
-
-static void
-init_texture_unit( GLcontext *ctx, GLuint unit )
-{
-   struct gl_texture_unit *texUnit = &ctx->Texture.Unit[unit];
-
-   texUnit->EnvMode = GL_MODULATE;
-   texUnit->CombineModeRGB = GL_MODULATE;
-   texUnit->CombineModeA = GL_MODULATE;
-   texUnit->CombineSourceRGB[0] = GL_TEXTURE;
-   texUnit->CombineSourceRGB[1] = GL_PREVIOUS_EXT;
-   texUnit->CombineSourceRGB[2] = GL_CONSTANT_EXT;
-   texUnit->CombineSourceA[0] = GL_TEXTURE;
-   texUnit->CombineSourceA[1] = GL_PREVIOUS_EXT;
-   texUnit->CombineSourceA[2] = GL_CONSTANT_EXT;
-   texUnit->CombineOperandRGB[0] = GL_SRC_COLOR;
-   texUnit->CombineOperandRGB[1] = GL_SRC_COLOR;
-   texUnit->CombineOperandRGB[2] = GL_SRC_ALPHA;
-   texUnit->CombineOperandA[0] = GL_SRC_ALPHA;
-   texUnit->CombineOperandA[1] = GL_SRC_ALPHA;
-   texUnit->CombineOperandA[2] = GL_SRC_ALPHA;
-   texUnit->CombineScaleShiftRGB = 0;
-   texUnit->CombineScaleShiftA = 0;
-
-   ASSIGN_4V( texUnit->EnvColor, 0.0, 0.0, 0.0, 0.0 );
-   texUnit->TexGenEnabled = 0;
-   texUnit->GenModeS = GL_EYE_LINEAR;
-   texUnit->GenModeT = GL_EYE_LINEAR;
-   texUnit->GenModeR = GL_EYE_LINEAR;
-   texUnit->GenModeQ = GL_EYE_LINEAR;
-   texUnit->_GenBitS = TEXGEN_EYE_LINEAR;
-   texUnit->_GenBitT = TEXGEN_EYE_LINEAR;
-   texUnit->_GenBitR = TEXGEN_EYE_LINEAR;
-   texUnit->_GenBitQ = TEXGEN_EYE_LINEAR;
-
-   /* Yes, these plane coefficients are correct! */
-   ASSIGN_4V( texUnit->ObjectPlaneS, 1.0, 0.0, 0.0, 0.0 );
-   ASSIGN_4V( texUnit->ObjectPlaneT, 0.0, 1.0, 0.0, 0.0 );
-   ASSIGN_4V( texUnit->ObjectPlaneR, 0.0, 0.0, 0.0, 0.0 );
-   ASSIGN_4V( texUnit->ObjectPlaneQ, 0.0, 0.0, 0.0, 0.0 );
-   ASSIGN_4V( texUnit->EyePlaneS, 1.0, 0.0, 0.0, 0.0 );
-   ASSIGN_4V( texUnit->EyePlaneT, 0.0, 1.0, 0.0, 0.0 );
-   ASSIGN_4V( texUnit->EyePlaneR, 0.0, 0.0, 0.0, 0.0 );
-   ASSIGN_4V( texUnit->EyePlaneQ, 0.0, 0.0, 0.0, 0.0 );
-
-   texUnit->Current1D = ctx->Shared->Default1D;
-   texUnit->Current2D = ctx->Shared->Default2D;
-   texUnit->Current3D = ctx->Shared->Default3D;
-   texUnit->CurrentCubeMap = ctx->Shared->DefaultCubeMap;
-   texUnit->CurrentRect = ctx->Shared->DefaultRect;
-
-   /* GL_SGI_texture_color_table */
-   texUnit->ColorTableEnabled = GL_FALSE;
-   _mesa_init_colortable(&texUnit->ColorTable);
-   _mesa_init_colortable(&texUnit->ProxyColorTable);
-}
-
-
-
-
-/* Initialize a 1-D evaluator map */
-static void
-init_1d_map( struct gl_1d_map *map, int n, const float *initial )
-{
-   map->Order = 1;
-   map->u1 = 0.0;
-   map->u2 = 1.0;
-   map->Points = (GLfloat *) MALLOC(n * sizeof(GLfloat));
-   if (map->Points) {
-      GLint i;
-      for (i=0;i<n;i++)
-         map->Points[i] = initial[i];
-   }
-}
-
-
-/* Initialize a 2-D evaluator map */
-static void
-init_2d_map( struct gl_2d_map *map, int n, const float *initial )
-{
-   map->Uorder = 1;
-   map->Vorder = 1;
-   map->u1 = 0.0;
-   map->u2 = 1.0;
-   map->v1 = 0.0;
-   map->v2 = 1.0;
-   map->Points = (GLfloat *) MALLOC(n * sizeof(GLfloat));
-   if (map->Points) {
-      GLint i;
-      for (i=0;i<n;i++)
-         map->Points[i] = initial[i];
+   /* Current group */
+   for (i = 0; i < VERT_ATTRIB_MAX; i++) {
+      ASSIGN_4V( ctx->Current.Attrib[i], 0.0, 0.0, 0.0, 1.0 );
    }
+   /* special cases: */
+   ASSIGN_4V( ctx->Current.Attrib[VERT_ATTRIB_WEIGHT], 1.0, 0.0, 0.0, 1.0 );
+   ASSIGN_4V( ctx->Current.Attrib[VERT_ATTRIB_NORMAL], 0.0, 0.0, 1.0, 1.0 );
+   ASSIGN_4V( ctx->Current.Attrib[VERT_ATTRIB_COLOR0], 1.0, 1.0, 1.0, 1.0 );
+   ASSIGN_4V( ctx->Current.Attrib[VERT_ATTRIB_COLOR1], 0.0, 0.0, 0.0, 0.0 );
+   ASSIGN_4V( ctx->Current.Attrib[VERT_ATTRIB_FOG], 0.0, 0.0, 0.0, 0.0 );
+   for (i = 0; i < MAX_TEXTURE_UNITS; i++)
+      ASSIGN_4V( ctx->Current.Attrib[VERT_ATTRIB_TEX0 + i], 0.0, 0.0, 0.0, 1.0);
+   ctx->Current.Index = 1;
+   ctx->Current.EdgeFlag = GL_TRUE;
 }
 
 
-/*
- * Initialize the attribute groups in a GLcontext.
- */
-static void
-init_attrib_groups( GLcontext *ctx )
+static void 
+_mesa_init_constants( GLcontext *ctx )
 {
-   GLuint i;
-
    assert(ctx);
 
    assert(MAX_TEXTURE_LEVELS >= MAX_3D_TEXTURE_LEVELS);
@@ -1013,678 +1063,83 @@ init_attrib_groups( GLcontext *ctx )
    ctx->Const.MaxProgramMatrixStackDepth = MAX_PROGRAM_MATRIX_STACK_DEPTH;
 
    ASSERT(ctx->Const.MaxTextureUnits == MAX2(ctx->Const.MaxTextureImageUnits, ctx->Const.MaxTextureCoordUnits));
+}
 
-   /* Initialize matrix stacks */
-   init_matrix_stack(&ctx->ModelviewMatrixStack, MAX_MODELVIEW_STACK_DEPTH,
-                     _NEW_MODELVIEW);
-   init_matrix_stack(&ctx->ProjectionMatrixStack, MAX_PROJECTION_STACK_DEPTH,
-                     _NEW_PROJECTION);
-   init_matrix_stack(&ctx->ColorMatrixStack, MAX_COLOR_STACK_DEPTH,
-                     _NEW_COLOR_MATRIX);
-   for (i = 0; i < MAX_TEXTURE_COORD_UNITS; i++)
-      init_matrix_stack(&ctx->TextureMatrixStack[i], MAX_TEXTURE_STACK_DEPTH,
-                        _NEW_TEXTURE_MATRIX);
-   for (i = 0; i < MAX_PROGRAM_MATRICES; i++)
-      init_matrix_stack(&ctx->ProgramMatrixStack[i],
-                        MAX_PROGRAM_MATRIX_STACK_DEPTH, _NEW_TRACK_MATRIX);
-   ctx->CurrentStack = &ctx->ModelviewMatrixStack;
-
-   /* Init combined Modelview*Projection matrix */
-   _math_matrix_ctr( &ctx->_ModelProjectMatrix );
-
-   /* Accumulate buffer group */
-   ASSIGN_4V( ctx->Accum.ClearColor, 0.0, 0.0, 0.0, 0.0 );
-
-   /* Color buffer group */
-   ctx->Color.IndexMask = 0xffffffff;
-   ctx->Color.ColorMask[0] = 0xff;
-   ctx->Color.ColorMask[1] = 0xff;
-   ctx->Color.ColorMask[2] = 0xff;
-   ctx->Color.ColorMask[3] = 0xff;
-   ctx->Color.ClearIndex = 0;
-   ASSIGN_4V( ctx->Color.ClearColor, 0, 0, 0, 0 );
-   ctx->Color.DrawBuffer = GL_FRONT;
-   ctx->Color.AlphaEnabled = GL_FALSE;
-   ctx->Color.AlphaFunc = GL_ALWAYS;
-   ctx->Color.AlphaRef = 0;
-   ctx->Color.BlendEnabled = GL_FALSE;
-   ctx->Color.BlendSrcRGB = GL_ONE;
-   ctx->Color.BlendDstRGB = GL_ZERO;
-   ctx->Color.BlendSrcA = GL_ONE;
-   ctx->Color.BlendDstA = GL_ZERO;
-   ctx->Color.BlendEquation = GL_FUNC_ADD_EXT;
-   ASSIGN_4V( ctx->Color.BlendColor, 0.0, 0.0, 0.0, 0.0 );
-   ctx->Color.IndexLogicOpEnabled = GL_FALSE;
-   ctx->Color.ColorLogicOpEnabled = GL_FALSE;
-   ctx->Color.LogicOp = GL_COPY;
-   ctx->Color.DitherFlag = GL_TRUE;
+/**
+ * Initialize the attribute groups in a GL context.
+ *
+ * \param ctx GL context.
+ *
+ * Initializes all the attributes, calling the respective <tt>init*</tt>
+ * functions for the more complex data structures.
+ */
+static GLboolean
+init_attrib_groups( GLcontext *ctx )
+{
+   assert(ctx);
 
-   /* Current group */
-   for (i = 0; i < VERT_ATTRIB_MAX; i++) {
-      ASSIGN_4V( ctx->Current.Attrib[i], 0.0, 0.0, 0.0, 1.0 );
-   }
-   /* special cases: */
-   ASSIGN_4V( ctx->Current.Attrib[VERT_ATTRIB_WEIGHT], 1.0, 0.0, 0.0, 1.0 );
-   ASSIGN_4V( ctx->Current.Attrib[VERT_ATTRIB_NORMAL], 0.0, 0.0, 1.0, 1.0 );
-   ASSIGN_4V( ctx->Current.Attrib[VERT_ATTRIB_COLOR0], 1.0, 1.0, 1.0, 1.0 );
-   ctx->Current.Index = 1;
-   ctx->Current.EdgeFlag = GL_TRUE;
-   
-   ASSIGN_4V( ctx->Current.RasterPos, 0.0, 0.0, 0.0, 1.0 );
-   ctx->Current.RasterDistance = 0.0;
-   ASSIGN_4V( ctx->Current.RasterColor, 1.0, 1.0, 1.0, 1.0 );
-   ASSIGN_4V( ctx->Current.RasterSecondaryColor, 0.0, 0.0, 0.0, 0.0 );
-   ctx->Current.RasterIndex = 1;
-   for (i = 0; i < MAX_TEXTURE_COORD_UNITS; i++)
-      ASSIGN_4V( ctx->Current.RasterTexCoords[i], 0.0, 0.0, 0.0, 1.0 );
-   ctx->Current.RasterPosValid = GL_TRUE;
-
-
-   /* Depth buffer group */
-   ctx->Depth.Test = GL_FALSE;
-   ctx->Depth.Clear = 1.0;
-   ctx->Depth.Func = GL_LESS;
-   ctx->Depth.Mask = GL_TRUE;
-   ctx->Depth.OcclusionTest = GL_FALSE;
-   ctx->Depth.BoundsTest = GL_FALSE;
-   ctx->Depth.BoundsMin = 0.0F;
-   ctx->Depth.BoundsMax = 1.0F;
-
-   /* Evaluators group */
-   ctx->Eval.Map1Color4 = GL_FALSE;
-   ctx->Eval.Map1Index = GL_FALSE;
-   ctx->Eval.Map1Normal = GL_FALSE;
-   ctx->Eval.Map1TextureCoord1 = GL_FALSE;
-   ctx->Eval.Map1TextureCoord2 = GL_FALSE;
-   ctx->Eval.Map1TextureCoord3 = GL_FALSE;
-   ctx->Eval.Map1TextureCoord4 = GL_FALSE;
-   ctx->Eval.Map1Vertex3 = GL_FALSE;
-   ctx->Eval.Map1Vertex4 = GL_FALSE;
-   MEMSET(ctx->Eval.Map1Attrib, 0, sizeof(ctx->Eval.Map1Attrib));
-   ctx->Eval.Map2Color4 = GL_FALSE;
-   ctx->Eval.Map2Index = GL_FALSE;
-   ctx->Eval.Map2Normal = GL_FALSE;
-   ctx->Eval.Map2TextureCoord1 = GL_FALSE;
-   ctx->Eval.Map2TextureCoord2 = GL_FALSE;
-   ctx->Eval.Map2TextureCoord3 = GL_FALSE;
-   ctx->Eval.Map2TextureCoord4 = GL_FALSE;
-   ctx->Eval.Map2Vertex3 = GL_FALSE;
-   ctx->Eval.Map2Vertex4 = GL_FALSE;
-   MEMSET(ctx->Eval.Map2Attrib, 0, sizeof(ctx->Eval.Map2Attrib));
-   ctx->Eval.AutoNormal = GL_FALSE;
-   ctx->Eval.MapGrid1un = 1;
-   ctx->Eval.MapGrid1u1 = 0.0;
-   ctx->Eval.MapGrid1u2 = 1.0;
-   ctx->Eval.MapGrid2un = 1;
-   ctx->Eval.MapGrid2vn = 1;
-   ctx->Eval.MapGrid2u1 = 0.0;
-   ctx->Eval.MapGrid2u2 = 1.0;
-   ctx->Eval.MapGrid2v1 = 0.0;
-   ctx->Eval.MapGrid2v2 = 1.0;
-
-   /* Evaluator data */
-   {
-      static GLfloat vertex[4] = { 0.0, 0.0, 0.0, 1.0 };
-      static GLfloat normal[3] = { 0.0, 0.0, 1.0 };
-      static GLfloat index[1] = { 1.0 };
-      static GLfloat color[4] = { 1.0, 1.0, 1.0, 1.0 };
-      static GLfloat texcoord[4] = { 0.0, 0.0, 0.0, 1.0 };
-      static GLfloat attrib[4] = { 0.0, 0.0, 0.0, 1.0 };
-
-      init_1d_map( &ctx->EvalMap.Map1Vertex3, 3, vertex );
-      init_1d_map( &ctx->EvalMap.Map1Vertex4, 4, vertex );
-      init_1d_map( &ctx->EvalMap.Map1Index, 1, index );
-      init_1d_map( &ctx->EvalMap.Map1Color4, 4, color );
-      init_1d_map( &ctx->EvalMap.Map1Normal, 3, normal );
-      init_1d_map( &ctx->EvalMap.Map1Texture1, 1, texcoord );
-      init_1d_map( &ctx->EvalMap.Map1Texture2, 2, texcoord );
-      init_1d_map( &ctx->EvalMap.Map1Texture3, 3, texcoord );
-      init_1d_map( &ctx->EvalMap.Map1Texture4, 4, texcoord );
-      for (i = 0; i < 16; i++)
-         init_1d_map( ctx->EvalMap.Map1Attrib + i, 4, attrib );
-
-      init_2d_map( &ctx->EvalMap.Map2Vertex3, 3, vertex );
-      init_2d_map( &ctx->EvalMap.Map2Vertex4, 4, vertex );
-      init_2d_map( &ctx->EvalMap.Map2Index, 1, index );
-      init_2d_map( &ctx->EvalMap.Map2Color4, 4, color );
-      init_2d_map( &ctx->EvalMap.Map2Normal, 3, normal );
-      init_2d_map( &ctx->EvalMap.Map2Texture1, 1, texcoord );
-      init_2d_map( &ctx->EvalMap.Map2Texture2, 2, texcoord );
-      init_2d_map( &ctx->EvalMap.Map2Texture3, 3, texcoord );
-      init_2d_map( &ctx->EvalMap.Map2Texture4, 4, texcoord );
-      for (i = 0; i < 16; i++)
-         init_2d_map( ctx->EvalMap.Map2Attrib + i, 4, attrib );
-   }
-
-   /* Fog group */
-   ctx->Fog.Enabled = GL_FALSE;
-   ctx->Fog.Mode = GL_EXP;
-   ASSIGN_4V( ctx->Fog.Color, 0.0, 0.0, 0.0, 0.0 );
-   ctx->Fog.Index = 0.0;
-   ctx->Fog.Density = 1.0;
-   ctx->Fog.Start = 0.0;
-   ctx->Fog.End = 1.0;
-   ctx->Fog.ColorSumEnabled = GL_FALSE;
-   ctx->Fog.FogCoordinateSource = GL_FRAGMENT_DEPTH_EXT;
-
-   /* Hint group */
-   ctx->Hint.PerspectiveCorrection = GL_DONT_CARE;
-   ctx->Hint.PointSmooth = GL_DONT_CARE;
-   ctx->Hint.LineSmooth = GL_DONT_CARE;
-   ctx->Hint.PolygonSmooth = GL_DONT_CARE;
-   ctx->Hint.Fog = GL_DONT_CARE;
-   ctx->Hint.ClipVolumeClipping = GL_DONT_CARE;
-   ctx->Hint.TextureCompression = GL_DONT_CARE;
-   ctx->Hint.GenerateMipmap = GL_DONT_CARE;
-
-   /* Histogram group */
-   ctx->Histogram.Width = 0;
-   ctx->Histogram.Format = GL_RGBA;
-   ctx->Histogram.Sink = GL_FALSE;
-   ctx->Histogram.RedSize       = 0;
-   ctx->Histogram.GreenSize     = 0;
-   ctx->Histogram.BlueSize      = 0;
-   ctx->Histogram.AlphaSize     = 0;
-   ctx->Histogram.LuminanceSize = 0;
-   for (i = 0; i < HISTOGRAM_TABLE_SIZE; i++) {
-      ctx->Histogram.Count[i][0] = 0;
-      ctx->Histogram.Count[i][1] = 0;
-      ctx->Histogram.Count[i][2] = 0;
-      ctx->Histogram.Count[i][3] = 0;
-   }
-
-   /* Min/Max group */
-   ctx->MinMax.Format = GL_RGBA;
-   ctx->MinMax.Sink = GL_FALSE;
-   ctx->MinMax.Min[RCOMP] = 1000;    ctx->MinMax.Max[RCOMP] = -1000;
-   ctx->MinMax.Min[GCOMP] = 1000;    ctx->MinMax.Max[GCOMP] = -1000;
-   ctx->MinMax.Min[BCOMP] = 1000;    ctx->MinMax.Max[BCOMP] = -1000;
-   ctx->MinMax.Min[ACOMP] = 1000;    ctx->MinMax.Max[ACOMP] = -1000;
+   /* Constants */
+   _mesa_init_constants( ctx );
 
    /* Extensions */
    _mesa_init_extensions( ctx );
 
-   /* Lighting group */
-   for (i=0;i<MAX_LIGHTS;i++) {
-      init_light( &ctx->Light.Light[i], i );
-   }
-   make_empty_list( &ctx->Light.EnabledList );
-
-   init_lightmodel( &ctx->Light.Model );
-   init_material( &ctx->Light.Material[0] );
-   init_material( &ctx->Light.Material[1] );
-   ctx->Light.ShadeModel = GL_SMOOTH;
-   ctx->Light.Enabled = GL_FALSE;
-   ctx->Light.ColorMaterialFace = GL_FRONT_AND_BACK;
-   ctx->Light.ColorMaterialMode = GL_AMBIENT_AND_DIFFUSE;
-   ctx->Light.ColorMaterialBitmask = _mesa_material_bitmask( ctx,
-                                               GL_FRONT_AND_BACK,
-                                               GL_AMBIENT_AND_DIFFUSE, ~0, 0 );
-
-   ctx->Light.ColorMaterialEnabled = GL_FALSE;
-
-   /* Lighting miscellaneous */
-   ctx->_ShineTabList = MALLOC_STRUCT( gl_shine_tab );
-   make_empty_list( ctx->_ShineTabList );
-   for (i = 0 ; i < 10 ; i++) {
-      struct gl_shine_tab *s = MALLOC_STRUCT( gl_shine_tab );
-      s->shininess = -1;
-      s->refcount = 0;
-      insert_at_tail( ctx->_ShineTabList, s );
-   }
-
-
-   /* Line group */
-   ctx->Line.SmoothFlag = GL_FALSE;
-   ctx->Line.StippleFlag = GL_FALSE;
-   ctx->Line.Width = 1.0;
-   ctx->Line._Width = 1.0;
-   ctx->Line.StipplePattern = 0xffff;
-   ctx->Line.StippleFactor = 1;
-
-   /* Display List group */
-   ctx->List.ListBase = 0;
-
-   /* Multisample */
-   ctx->Multisample.Enabled = GL_FALSE;
-   ctx->Multisample.SampleAlphaToCoverage = GL_FALSE;
-   ctx->Multisample.SampleAlphaToOne = GL_FALSE;
-   ctx->Multisample.SampleCoverage = GL_FALSE;
-   ctx->Multisample.SampleCoverageValue = 1.0;
-   ctx->Multisample.SampleCoverageInvert = GL_FALSE;
-
-   /* Pixel group */
-   ctx->Pixel.RedBias = 0.0;
-   ctx->Pixel.RedScale = 1.0;
-   ctx->Pixel.GreenBias = 0.0;
-   ctx->Pixel.GreenScale = 1.0;
-   ctx->Pixel.BlueBias = 0.0;
-   ctx->Pixel.BlueScale = 1.0;
-   ctx->Pixel.AlphaBias = 0.0;
-   ctx->Pixel.AlphaScale = 1.0;
-   ctx->Pixel.DepthBias = 0.0;
-   ctx->Pixel.DepthScale = 1.0;
-   ctx->Pixel.IndexOffset = 0;
-   ctx->Pixel.IndexShift = 0;
-   ctx->Pixel.ZoomX = 1.0;
-   ctx->Pixel.ZoomY = 1.0;
-   ctx->Pixel.MapColorFlag = GL_FALSE;
-   ctx->Pixel.MapStencilFlag = GL_FALSE;
-   ctx->Pixel.MapStoSsize = 1;
-   ctx->Pixel.MapItoIsize = 1;
-   ctx->Pixel.MapItoRsize = 1;
-   ctx->Pixel.MapItoGsize = 1;
-   ctx->Pixel.MapItoBsize = 1;
-   ctx->Pixel.MapItoAsize = 1;
-   ctx->Pixel.MapRtoRsize = 1;
-   ctx->Pixel.MapGtoGsize = 1;
-   ctx->Pixel.MapBtoBsize = 1;
-   ctx->Pixel.MapAtoAsize = 1;
-   ctx->Pixel.MapStoS[0] = 0;
-   ctx->Pixel.MapItoI[0] = 0;
-   ctx->Pixel.MapItoR[0] = 0.0;
-   ctx->Pixel.MapItoG[0] = 0.0;
-   ctx->Pixel.MapItoB[0] = 0.0;
-   ctx->Pixel.MapItoA[0] = 0.0;
-   ctx->Pixel.MapItoR8[0] = 0;
-   ctx->Pixel.MapItoG8[0] = 0;
-   ctx->Pixel.MapItoB8[0] = 0;
-   ctx->Pixel.MapItoA8[0] = 0;
-   ctx->Pixel.MapRtoR[0] = 0.0;
-   ctx->Pixel.MapGtoG[0] = 0.0;
-   ctx->Pixel.MapBtoB[0] = 0.0;
-   ctx->Pixel.MapAtoA[0] = 0.0;
-   ctx->Pixel.HistogramEnabled = GL_FALSE;
-   ctx->Pixel.MinMaxEnabled = GL_FALSE;
-   ctx->Pixel.PixelTextureEnabled = GL_FALSE;
-   ctx->Pixel.FragmentRgbSource = GL_PIXEL_GROUP_COLOR_SGIS;
-   ctx->Pixel.FragmentAlphaSource = GL_PIXEL_GROUP_COLOR_SGIS;
-   ASSIGN_4V(ctx->Pixel.PostColorMatrixScale, 1.0, 1.0, 1.0, 1.0);
-   ASSIGN_4V(ctx->Pixel.PostColorMatrixBias, 0.0, 0.0, 0.0, 0.0);
-   ASSIGN_4V(ctx->Pixel.ColorTableScale, 1.0, 1.0, 1.0, 1.0);
-   ASSIGN_4V(ctx->Pixel.ColorTableBias, 0.0, 0.0, 0.0, 0.0);
-   ASSIGN_4V(ctx->Pixel.PCCTscale, 1.0, 1.0, 1.0, 1.0);
-   ASSIGN_4V(ctx->Pixel.PCCTbias, 0.0, 0.0, 0.0, 0.0);
-   ASSIGN_4V(ctx->Pixel.PCMCTscale, 1.0, 1.0, 1.0, 1.0);
-   ASSIGN_4V(ctx->Pixel.PCMCTbias, 0.0, 0.0, 0.0, 0.0);
-   ctx->Pixel.ColorTableEnabled = GL_FALSE;
-   ctx->Pixel.PostConvolutionColorTableEnabled = GL_FALSE;
-   ctx->Pixel.PostColorMatrixColorTableEnabled = GL_FALSE;
-   ctx->Pixel.Convolution1DEnabled = GL_FALSE;
-   ctx->Pixel.Convolution2DEnabled = GL_FALSE;
-   ctx->Pixel.Separable2DEnabled = GL_FALSE;
-   for (i = 0; i < 3; i++) {
-      ASSIGN_4V(ctx->Pixel.ConvolutionBorderColor[i], 0.0, 0.0, 0.0, 0.0);
-      ctx->Pixel.ConvolutionBorderMode[i] = GL_REDUCE;
-      ASSIGN_4V(ctx->Pixel.ConvolutionFilterScale[i], 1.0, 1.0, 1.0, 1.0);
-      ASSIGN_4V(ctx->Pixel.ConvolutionFilterBias[i], 0.0, 0.0, 0.0, 0.0);
-   }
-   for (i = 0; i < MAX_CONVOLUTION_WIDTH * MAX_CONVOLUTION_WIDTH * 4; i++) {
-      ctx->Convolution1D.Filter[i] = 0.0;
-      ctx->Convolution2D.Filter[i] = 0.0;
-      ctx->Separable2D.Filter[i] = 0.0;
-   }
-   ASSIGN_4V(ctx->Pixel.PostConvolutionScale, 1.0, 1.0, 1.0, 1.0);
-   ASSIGN_4V(ctx->Pixel.PostConvolutionBias, 0.0, 0.0, 0.0, 0.0);
-   /* GL_SGI_texture_color_table */
-   ASSIGN_4V(ctx->Pixel.TextureColorTableScale, 1.0, 1.0, 1.0, 1.0);
-   ASSIGN_4V(ctx->Pixel.TextureColorTableBias, 0.0, 0.0, 0.0, 0.0);
-
-   /* Point group */
-   ctx->Point.SmoothFlag = GL_FALSE;
-   ctx->Point.Size = 1.0;
-   ctx->Point._Size = 1.0;
-   ctx->Point.Params[0] = 1.0;
-   ctx->Point.Params[1] = 0.0;
-   ctx->Point.Params[2] = 0.0;
-   ctx->Point._Attenuated = GL_FALSE;
-   ctx->Point.MinSize = 0.0;
-   ctx->Point.MaxSize = ctx->Const.MaxPointSize;
-   ctx->Point.Threshold = 1.0;
-   ctx->Point.PointSprite = GL_FALSE; /* GL_NV_point_sprite */
-   ctx->Point.SpriteRMode = GL_ZERO; /* GL_NV_point_sprite */
-   for (i = 0; i < MAX_TEXTURE_COORD_UNITS; i++) {
-      ctx->Point.CoordReplace[i] = GL_FALSE; /* GL_NV_point_sprite */
-   }
-
-   /* Polygon group */
-   ctx->Polygon.CullFlag = GL_FALSE;
-   ctx->Polygon.CullFaceMode = GL_BACK;
-   ctx->Polygon.FrontFace = GL_CCW;
-   ctx->Polygon._FrontBit = 0;
-   ctx->Polygon.FrontMode = GL_FILL;
-   ctx->Polygon.BackMode = GL_FILL;
-   ctx->Polygon.SmoothFlag = GL_FALSE;
-   ctx->Polygon.StippleFlag = GL_FALSE;
-   ctx->Polygon.OffsetFactor = 0.0F;
-   ctx->Polygon.OffsetUnits = 0.0F;
-   ctx->Polygon.OffsetPoint = GL_FALSE;
-   ctx->Polygon.OffsetLine = GL_FALSE;
-   ctx->Polygon.OffsetFill = GL_FALSE;
-
-   /* Polygon Stipple group */
-   MEMSET( ctx->PolygonStipple, 0xff, 32*sizeof(GLuint) );
-
-   /* Scissor group */
-   ctx->Scissor.Enabled = GL_FALSE;
-   ctx->Scissor.X = 0;
-   ctx->Scissor.Y = 0;
-   ctx->Scissor.Width = 0;
-   ctx->Scissor.Height = 0;
-
-   /* Stencil group */
-   ctx->Stencil.Enabled = GL_FALSE;
-   ctx->Stencil.TestTwoSide = GL_FALSE;
-   ctx->Stencil.ActiveFace = 0;  /* 0 = GL_FRONT, 1 = GL_BACK */
-   ctx->Stencil.Function[0] = GL_ALWAYS;
-   ctx->Stencil.Function[1] = GL_ALWAYS;
-   ctx->Stencil.FailFunc[0] = GL_KEEP;
-   ctx->Stencil.FailFunc[1] = GL_KEEP;
-   ctx->Stencil.ZPassFunc[0] = GL_KEEP;
-   ctx->Stencil.ZPassFunc[1] = GL_KEEP;
-   ctx->Stencil.ZFailFunc[0] = GL_KEEP;
-   ctx->Stencil.ZFailFunc[1] = GL_KEEP;
-   ctx->Stencil.Ref[0] = 0;
-   ctx->Stencil.Ref[1] = 0;
-   ctx->Stencil.ValueMask[0] = STENCIL_MAX;
-   ctx->Stencil.ValueMask[1] = STENCIL_MAX;
-   ctx->Stencil.WriteMask[0] = STENCIL_MAX;
-   ctx->Stencil.WriteMask[1] = STENCIL_MAX;
-   ctx->Stencil.Clear = 0;
-
-   /* Texture group */
-   ctx->Texture.CurrentUnit = 0;      /* multitexture */
-   ctx->Texture._EnabledUnits = 0;
-   for (i=0; i<MAX_TEXTURE_UNITS; i++)
-      init_texture_unit( ctx, i );
-   ctx->Texture.SharedPalette = GL_FALSE;
-   _mesa_init_colortable(&ctx->Texture.Palette);
-
-   /* Transformation group */
-   ctx->Transform.MatrixMode = GL_MODELVIEW;
-   ctx->Transform.Normalize = GL_FALSE;
-   ctx->Transform.RescaleNormals = GL_FALSE;
-   ctx->Transform.RasterPositionUnclipped = GL_FALSE;
-   for (i=0;i<MAX_CLIP_PLANES;i++) {
-      ASSIGN_4V( ctx->Transform.EyeUserPlane[i], 0.0, 0.0, 0.0, 0.0 );
-   }
-   ctx->Transform.ClipPlanesEnabled = 0;
-
-   /* Viewport group */
-   ctx->Viewport.X = 0;
-   ctx->Viewport.Y = 0;
-   ctx->Viewport.Width = 0;
-   ctx->Viewport.Height = 0;
-   ctx->Viewport.Near = 0.0;
-   ctx->Viewport.Far = 1.0;
-   _math_matrix_ctr(&ctx->Viewport._WindowMap);
-
-#define Sz 10
-#define Tz 14
-   ctx->Viewport._WindowMap.m[Sz] = 0.5F * ctx->DepthMaxF;
-   ctx->Viewport._WindowMap.m[Tz] = 0.5F * ctx->DepthMaxF;
-#undef Sz
-#undef Tz
-
-   ctx->Viewport._WindowMap.flags = MAT_FLAG_GENERAL_SCALE|MAT_FLAG_TRANSLATION;
-   ctx->Viewport._WindowMap.type = MATRIX_3D_NO_ROT;
-
-   /* Vertex arrays */
-   ctx->Array.Vertex.Size = 4;
-   ctx->Array.Vertex.Type = GL_FLOAT;
-   ctx->Array.Vertex.Stride = 0;
-   ctx->Array.Vertex.StrideB = 0;
-   ctx->Array.Vertex.Ptr = NULL;
-   ctx->Array.Vertex.Enabled = GL_FALSE;
-   ctx->Array.Vertex.Flags = CA_CLIENT_DATA;
-   ctx->Array.Normal.Type = GL_FLOAT;
-   ctx->Array.Normal.Stride = 0;
-   ctx->Array.Normal.StrideB = 0;
-   ctx->Array.Normal.Ptr = NULL;
-   ctx->Array.Normal.Enabled = GL_FALSE;
-   ctx->Array.Normal.Flags = CA_CLIENT_DATA;
-   ctx->Array.Color.Size = 4;
-   ctx->Array.Color.Type = GL_FLOAT;
-   ctx->Array.Color.Stride = 0;
-   ctx->Array.Color.StrideB = 0;
-   ctx->Array.Color.Ptr = NULL;
-   ctx->Array.Color.Enabled = GL_FALSE;
-   ctx->Array.Color.Flags = CA_CLIENT_DATA;
-   ctx->Array.SecondaryColor.Size = 3;
-   ctx->Array.SecondaryColor.Type = GL_FLOAT;
-   ctx->Array.SecondaryColor.Stride = 0;
-   ctx->Array.SecondaryColor.StrideB = 0;
-   ctx->Array.SecondaryColor.Ptr = NULL;
-   ctx->Array.SecondaryColor.Enabled = GL_FALSE;
-   ctx->Array.SecondaryColor.Flags = CA_CLIENT_DATA;
-   ctx->Array.FogCoord.Size = 1;
-   ctx->Array.FogCoord.Type = GL_FLOAT;
-   ctx->Array.FogCoord.Stride = 0;
-   ctx->Array.FogCoord.StrideB = 0;
-   ctx->Array.FogCoord.Ptr = NULL;
-   ctx->Array.FogCoord.Enabled = GL_FALSE;
-   ctx->Array.FogCoord.Flags = CA_CLIENT_DATA;
-   ctx->Array.Index.Type = GL_FLOAT;
-   ctx->Array.Index.Stride = 0;
-   ctx->Array.Index.StrideB = 0;
-   ctx->Array.Index.Ptr = NULL;
-   ctx->Array.Index.Enabled = GL_FALSE;
-   ctx->Array.Index.Flags = CA_CLIENT_DATA;
-   for (i = 0; i < MAX_TEXTURE_COORD_UNITS; i++) {
-      ctx->Array.TexCoord[i].Size = 4;
-      ctx->Array.TexCoord[i].Type = GL_FLOAT;
-      ctx->Array.TexCoord[i].Stride = 0;
-      ctx->Array.TexCoord[i].StrideB = 0;
-      ctx->Array.TexCoord[i].Ptr = NULL;
-      ctx->Array.TexCoord[i].Enabled = GL_FALSE;
-      ctx->Array.TexCoord[i].Flags = CA_CLIENT_DATA;
-   }
-   ctx->Array.TexCoordInterleaveFactor = 1;
-   ctx->Array.EdgeFlag.Stride = 0;
-   ctx->Array.EdgeFlag.StrideB = 0;
-   ctx->Array.EdgeFlag.Ptr = NULL;
-   ctx->Array.EdgeFlag.Enabled = GL_FALSE;
-   ctx->Array.EdgeFlag.Flags = CA_CLIENT_DATA;
-   ctx->Array.ActiveTexture = 0;   /* GL_ARB_multitexture */
-
-   /* Pixel transfer */
-   ctx->Pack.Alignment = 4;
-   ctx->Pack.RowLength = 0;
-   ctx->Pack.ImageHeight = 0;
-   ctx->Pack.SkipPixels = 0;
-   ctx->Pack.SkipRows = 0;
-   ctx->Pack.SkipImages = 0;
-   ctx->Pack.SwapBytes = GL_FALSE;
-   ctx->Pack.LsbFirst = GL_FALSE;
-   ctx->Unpack.Alignment = 4;
-   ctx->Unpack.RowLength = 0;
-   ctx->Unpack.ImageHeight = 0;
-   ctx->Unpack.SkipPixels = 0;
-   ctx->Unpack.SkipRows = 0;
-   ctx->Unpack.SkipImages = 0;
-   ctx->Unpack.SwapBytes = GL_FALSE;
-   ctx->Unpack.LsbFirst = GL_FALSE;
-
-   /* Feedback */
-   ctx->Feedback.Type = GL_2D;   /* TODO: verify */
-   ctx->Feedback.Buffer = NULL;
-   ctx->Feedback.BufferSize = 0;
-   ctx->Feedback.Count = 0;
-
-   /* Selection/picking */
-   ctx->Select.Buffer = NULL;
-   ctx->Select.BufferSize = 0;
-   ctx->Select.BufferCount = 0;
-   ctx->Select.Hits = 0;
-   ctx->Select.NameStackDepth = 0;
-
-   /* Renderer and client attribute stacks */
-   ctx->AttribStackDepth = 0;
-   ctx->ClientAttribStackDepth = 0;
-
-   /* Display list */
-   ctx->CallDepth = 0;
-   ctx->ExecuteFlag = GL_TRUE;
-   ctx->CompileFlag = GL_FALSE;
-   ctx->CurrentListPtr = NULL;
-   ctx->CurrentBlock = NULL;
-   ctx->CurrentListNum = 0;
-   ctx->CurrentPos = 0;
-
-   /* Color tables */
-   _mesa_init_colortable(&ctx->ColorTable);
-   _mesa_init_colortable(&ctx->ProxyColorTable);
-   _mesa_init_colortable(&ctx->PostConvolutionColorTable);
-   _mesa_init_colortable(&ctx->ProxyPostConvolutionColorTable);
-   _mesa_init_colortable(&ctx->PostColorMatrixColorTable);
-   _mesa_init_colortable(&ctx->ProxyPostColorMatrixColorTable);
-
-   /* Vertex/fragment programs */
-   ctx->Program.ErrorPos = -1;
-   ctx->Program.ErrorString = _mesa_strdup("");
-#if FEATURE_NV_vertex_program || FEATURE_ARB_vertex_program
-   ctx->VertexProgram.Enabled = GL_FALSE;
-   ctx->VertexProgram.PointSizeEnabled = GL_FALSE;
-   ctx->VertexProgram.TwoSideEnabled = GL_FALSE;
-   ctx->VertexProgram.Current = NULL;
-   ctx->VertexProgram.Current = (struct vertex_program *) ctx->Shared->DefaultVertexProgram;
-   assert(ctx->VertexProgram.Current);
-   ctx->VertexProgram.Current->Base.RefCount++;
-   for (i = 0; i < VP_NUM_PROG_REGS / 4; i++) {
-      ctx->VertexProgram.TrackMatrix[i] = GL_NONE;
-      ctx->VertexProgram.TrackMatrixTransform[i] = GL_IDENTITY_NV;
-   }
-#endif
-#if FEATURE_NV_fragment_program || FEATURE_ARB_fragment_program
-   ctx->FragmentProgram.Enabled = GL_FALSE;
-   ctx->FragmentProgram.Current = (struct fragment_program *) ctx->Shared->DefaultFragmentProgram;
-   assert(ctx->FragmentProgram.Current);
-   ctx->FragmentProgram.Current->Base.RefCount++;
-#endif
-
-#if FEATURE_ARB_occlusion_query
-   ctx->Occlusion.QueryObjects = _mesa_NewHashTable();
-#endif
+   /* Attribute Groups */
+   _mesa_init_accum( ctx );
+   _mesa_init_attrib( ctx );
+   _mesa_init_buffers( ctx );
+   _mesa_init_color( ctx );
+   _mesa_init_colortable( ctx );
+   _mesa_init_current( ctx );
+   _mesa_init_depth( ctx );
+   _mesa_init_debug( ctx );
+   _mesa_init_display_list( ctx );
+   _mesa_init_eval( ctx );
+   _mesa_init_feedback( ctx );
+   _mesa_init_fog( ctx );
+   _mesa_init_histogram( ctx );
+   _mesa_init_hint( ctx );
+   _mesa_init_line( ctx );
+   _mesa_init_lighting( ctx );
+   _mesa_init_matrix( ctx );
+   _mesa_init_pixel( ctx );
+   _mesa_init_point( ctx );
+   _mesa_init_polygon( ctx );
+   _mesa_init_rastpos( ctx );
+   _mesa_init_stencil( ctx );
+   _mesa_init_transform( ctx );
+   _mesa_init_varray( ctx );
+   _mesa_init_viewport( ctx );
+
+   if (!_mesa_init_texture( ctx ))
+      return GL_FALSE;
 
    /* Miscellaneous */
    ctx->NewState = _NEW_ALL;
-   ctx->RenderMode = GL_RENDER;
-   ctx->_ImageTransferState = 0;
-
-   ctx->_NeedNormals = 0;
-   ctx->_NeedEyeCoords = 0;
-   ctx->_ModelViewInvScale = 1.0;
-
    ctx->ErrorValue = (GLenum) GL_NO_ERROR;
-
    ctx->CatchSignals = GL_TRUE;
-   ctx->OcclusionResult = GL_FALSE;
-   ctx->OcclusionResultSaved = GL_FALSE;
    ctx->_Facing = 0;
 
-   /* For debug/development only */
-   ctx->NoRaster = _mesa_getenv("MESA_NO_RASTER") ? GL_TRUE : GL_FALSE;
-   ctx->FirstTimeCurrent = GL_TRUE;
-
-   /* Dither disable */
-   ctx->NoDither = _mesa_getenv("MESA_NO_DITHER") ? GL_TRUE : GL_FALSE;
-   if (ctx->NoDither) {
-      if (_mesa_getenv("MESA_DEBUG")) {
-         _mesa_debug(ctx, "MESA_NO_DITHER set - dithering disabled\n");
-      }
-      ctx->Color.DitherFlag = GL_FALSE;
-   }
-}
-
-
-
-
-/**
- * Allocate the proxy textures for the given context.
- * \param  ctx  the context to allocate proxies for.
- * \return  GL_TRUE if success, GL_FALSE if failure.
- */
-static GLboolean
-alloc_proxy_textures( GLcontext *ctx )
-{
-   ctx->Texture.Proxy1D = (*ctx->Driver.NewTextureObject)(ctx, 0, GL_TEXTURE_1D);
-   if (!ctx->Texture.Proxy1D)
-      goto cleanup;
-
-   ctx->Texture.Proxy2D = (*ctx->Driver.NewTextureObject)(ctx, 0, GL_TEXTURE_2D);
-   if (!ctx->Texture.Proxy2D)
-      goto cleanup;
-
-   ctx->Texture.Proxy3D = (*ctx->Driver.NewTextureObject)(ctx, 0, GL_TEXTURE_3D);
-   if (!ctx->Texture.Proxy3D)
-      goto cleanup;
-
-   ctx->Texture.ProxyCubeMap = (*ctx->Driver.NewTextureObject)(ctx, 0, GL_TEXTURE_CUBE_MAP_ARB);
-   if (!ctx->Texture.ProxyCubeMap)
-      goto cleanup;
-
-   ctx->Texture.ProxyRect = (*ctx->Driver.NewTextureObject)(ctx, 0, GL_TEXTURE_RECTANGLE_NV);
-   if (!ctx->Texture.ProxyRect)
-      goto cleanup;
-
    return GL_TRUE;
-
- cleanup:
-   if (ctx->Texture.Proxy1D)
-      (ctx->Driver.DeleteTexture)(ctx, ctx->Texture.Proxy1D);
-   if (ctx->Texture.Proxy2D)
-      (ctx->Driver.DeleteTexture)(ctx, ctx->Texture.Proxy2D);
-   if (ctx->Texture.Proxy3D)
-      (ctx->Driver.DeleteTexture)(ctx, ctx->Texture.Proxy3D);
-   if (ctx->Texture.ProxyCubeMap)
-      (ctx->Driver.DeleteTexture)(ctx, ctx->Texture.ProxyCubeMap);
-   if (ctx->Texture.ProxyRect)
-      (ctx->Driver.DeleteTexture)(ctx, ctx->Texture.ProxyRect);
-   return GL_FALSE;
 }
 
 
-static void add_debug_flags( const char *debug )
-{
-#ifdef MESA_DEBUG
-   if (_mesa_strstr(debug, "varray")) 
-      MESA_VERBOSE |= VERBOSE_VARRAY;
-
-   if (_mesa_strstr(debug, "tex")) 
-      MESA_VERBOSE |= VERBOSE_TEXTURE;
-
-   if (_mesa_strstr(debug, "imm")) 
-      MESA_VERBOSE |= VERBOSE_IMMEDIATE;
-
-   if (_mesa_strstr(debug, "pipe")) 
-      MESA_VERBOSE |= VERBOSE_PIPELINE;
-
-   if (_mesa_strstr(debug, "driver")) 
-      MESA_VERBOSE |= VERBOSE_DRIVER;
-
-   if (_mesa_strstr(debug, "state")) 
-      MESA_VERBOSE |= VERBOSE_STATE;
-
-   if (_mesa_strstr(debug, "api")) 
-      MESA_VERBOSE |= VERBOSE_API;
-
-   if (_mesa_strstr(debug, "list")) 
-      MESA_VERBOSE |= VERBOSE_DISPLAY_LIST;
-
-   if (_mesa_strstr(debug, "lighting")) 
-      MESA_VERBOSE |= VERBOSE_LIGHTING;
-   
-   /* Debug flag:
-    */
-   if (_mesa_strstr(debug, "flush")) 
-      MESA_DEBUG_FLAGS |= DEBUG_ALWAYS_FLUSH;
-#endif
-}
-
 
 /**
- * Initialize a GLcontext struct.  This includes allocating all the
- * other structs and arrays which hang off of the context by pointers.
+ * Initialize a GLcontext struct. 
+ *
+ * This includes allocating all the other structs and arrays which hang off of
+ * the context by pointers.
+ * 
+ * \sa _mesa_create_context() for the parameter description.
+ *
+ * Performs the imports and exports callback tables initialization, and
+ * miscellaneous one-time initializations. If no shared context is supplied one
+ * is allocated, and increase its reference count.  Setups the GL API dispatch
+ * tables.  Initialize the TNL module. Sets the maximum Z buffer depth.
+ * Finally queries the \c MESA_DEBUG and \c MESA_VERBOSE environment variables
+ * for debug flags.
+ *
  * \note the direct parameter is ignored (obsolete).
  */
 GLboolean
@@ -1695,7 +1150,6 @@ _mesa_initialize_context( GLcontext *ctx,
                           GLboolean direct )
 {
    GLuint dispatchSize;
-   const char *c;
 
    ASSERT(driver_ctx);
 
@@ -1739,50 +1193,15 @@ _mesa_initialize_context( GLcontext *ctx,
    ctx->Shared->RefCount++;
    _glthread_UNLOCK_MUTEX(ctx->Shared->Mutex);
 
-   init_attrib_groups( ctx );
-
-   if (visual->doubleBufferMode) {
-      ctx->Color.DrawBuffer = GL_BACK;
-      ctx->Color._DrawDestMask = BACK_LEFT_BIT;
-      ctx->Pixel.ReadBuffer = GL_BACK;
-      ctx->Pixel._ReadSrcMask = BACK_LEFT_BIT;
-   }
-   else {
-      ctx->Color.DrawBuffer = GL_FRONT;
-      ctx->Color._DrawDestMask = FRONT_LEFT_BIT;
-      ctx->Pixel.ReadBuffer = GL_FRONT;
-      ctx->Pixel._ReadSrcMask = FRONT_LEFT_BIT;
-   }
-
-   if (!alloc_proxy_textures(ctx)) {
+   if (!init_attrib_groups( ctx )) {
       free_shared_state(ctx, ctx->Shared);
+      fprintf(stderr, "%s: failed to init attrib groups\n", __FUNCTION__);
       return GL_FALSE;
    }
 
-   /*
-    * For XFree86/DRI: tell libGL to add these functions to the dispatcher.
-    * Basically, we should add all extension functions above offset 577.
-    * This enables older libGL libraries to work with newer drivers that
-    * have newer extensions.
+
+   /* TODO: move this to somewhere program-specific.
     */
-   /* GL_ARB_window_pos aliases with GL_MESA_window_pos */
-   _glapi_add_entrypoint("glWindowPos2dARB", 513);
-   _glapi_add_entrypoint("glWindowPos2dvARB", 514);
-   _glapi_add_entrypoint("glWindowPos2fARB", 515);
-   _glapi_add_entrypoint("glWindowPos2fvARB", 516);
-   _glapi_add_entrypoint("glWindowPos2iARB", 517);
-   _glapi_add_entrypoint("glWindowPos2ivARB", 518);
-   _glapi_add_entrypoint("glWindowPos2sARB", 519);
-   _glapi_add_entrypoint("glWindowPos2svARB", 520);
-   _glapi_add_entrypoint("glWindowPos3dARB", 521);
-   _glapi_add_entrypoint("glWindowPos3dvARB", 522);
-   _glapi_add_entrypoint("glWindowPos3fARB", 523);
-   _glapi_add_entrypoint("glWindowPos3fvARB", 524);
-   _glapi_add_entrypoint("glWindowPos3iARB", 525);
-   _glapi_add_entrypoint("glWindowPos3ivARB", 526);
-   _glapi_add_entrypoint("glWindowPos3sARB", 527);
-   _glapi_add_entrypoint("glWindowPos3svARB", 528);
-   /* new extension functions */
    _glapi_add_entrypoint("glAreProgramsResidentNV", 578);
    _glapi_add_entrypoint("glBindProgramNV", 579);
    _glapi_add_entrypoint("glDeleteProgramsNV", 580);
@@ -1861,6 +1280,7 @@ _mesa_initialize_context( GLcontext *ctx,
    _glapi_add_entrypoint("glSetFenceNV", 653);
    /* XXX add NV_fragment_program and ARB_vertex_program functions */
 
+
    /* Find the larger of Mesa's dispatch table and libGL's dispatch table.
     * In practice, this'll be the same for stand-alone Mesa.  But for DRI
     * Mesa we do this to accomodate different versions of libGL and various
@@ -1878,59 +1298,34 @@ _mesa_initialize_context( GLcontext *ctx,
          FREE( ctx->Exec );
    }
    _mesa_init_exec_table(ctx->Exec, dispatchSize);
-   _mesa_init_dlist_table(ctx->Save, dispatchSize);
    ctx->CurrentDispatch = ctx->Exec;
 
+#if _HAVE_FULL_GL
+   _mesa_init_dlist_table(ctx->Save, dispatchSize);
+
    ctx->ExecPrefersFloat = GL_FALSE;
    ctx->SavePrefersFloat = GL_FALSE;
 
    /* Neutral tnl module stuff */
-   _mesa_init_exec_vtxfmt( ctx );
+   _mesa_init_exec_vtxfmt( ctx ); 
    ctx->TnlModule.Current = NULL;
    ctx->TnlModule.SwapCount = 0;
 
-   /* Z buffer stuff */
-   if (ctx->Visual.depthBits == 0) {
-      /* Special case.  Even if we don't have a depth buffer we need
-       * good values for DepthMax for Z vertex transformation purposes
-       * and for per-fragment fog computation.
-       */
-      ctx->DepthMax = 1 << 16;
-      ctx->DepthMaxF = (GLfloat) ctx->DepthMax;
-   }
-   else if (ctx->Visual.depthBits < 32) {
-      ctx->DepthMax = (1 << ctx->Visual.depthBits) - 1;
-      ctx->DepthMaxF = (GLfloat) ctx->DepthMax;
-   }
-   else {
-      /* Special case since shift values greater than or equal to the
-       * number of bits in the left hand expression's type are undefined.
-       */
-      ctx->DepthMax = 0xffffffff;
-      ctx->DepthMaxF = (GLfloat) ctx->DepthMax;
-   }
-   ctx->MRD = 1.0;  /* Minimum resolvable depth value, for polygon offset */
-
-   c = _mesa_getenv("MESA_DEBUG");
-   if (c)
-      add_debug_flags(c);
-
-   c = _mesa_getenv("MESA_VERBOSE");
-   if (c)
-      add_debug_flags(c);
+#endif
 
+   fprintf(stderr, "%s: succeded\n", __FUNCTION__);
    return GL_TRUE;
 }
 
-
-
 /**
  * Allocate and initialize a GLcontext structure.
- * Input:  visual - a GLvisual pointer (we copy the struct contents)
- *         sharelist - another context to share display lists with or NULL
- *         driver_ctx - pointer to device driver's context state struct
- *         direct - obsolete, ignored
- * Return:  pointer to a new __GLcontextRec or NULL if error.
+ *
+ * \param visual a GLvisual pointer (we copy the struct contents)
+ * \param share_list another context to share display lists with or NULL
+ * \param driver_ctx pointer to device driver's context state struct
+ * \param direct obsolete, ignored
+ * 
+ * \return pointer to a new __GLcontextRec or NULL if error.
  */
 GLcontext *
 _mesa_create_context( const GLvisual *visual,
@@ -1957,37 +1352,27 @@ _mesa_create_context( const GLvisual *visual,
    }
 }
 
-
-
-/*
+/**
  * Free the data associated with the given context.
- * But don't free() the GLcontext struct itself!
+ * 
+ * But doesn't free the GLcontext struct itself.
+ *
+ * \sa _mesa_initialize_context() and init_attrib_groups().
  */
 void
 _mesa_free_context_data( GLcontext *ctx )
 {
-   struct gl_shine_tab *s, *tmps;
-   GLuint i;
-
    /* if we're destroying the current context, unbind it first */
    if (ctx == _mesa_get_current_context()) {
       _mesa_make_current(NULL, NULL);
    }
 
-   /*
-    * Free transformation matrix stacks
-    */
-   free_matrix_stack(&ctx->ModelviewMatrixStack);
-   free_matrix_stack(&ctx->ProjectionMatrixStack);
-   free_matrix_stack(&ctx->ColorMatrixStack);
-   for (i = 0; i < MAX_TEXTURE_COORD_UNITS; i++)
-      free_matrix_stack(&ctx->TextureMatrixStack[i]);
-   for (i = 0; i < MAX_PROGRAM_MATRICES; i++)
-      free_matrix_stack(&ctx->ProgramMatrixStack[i]);
-   /* combined Modelview*Projection matrix */
-   _math_matrix_dtr( &ctx->_ModelProjectMatrix );
-
-
+   _mesa_free_lighting_data( ctx );
+   _mesa_free_eval_data( ctx );
+   _mesa_free_texture_data( ctx );
+   _mesa_free_matrix_data( ctx );
+   _mesa_free_viewport_data( ctx );
+   _mesa_free_colortable_data( ctx );
 #if FEATURE_NV_vertex_program
    if (ctx->VertexProgram.Current) {
       ctx->VertexProgram.Current->Base.RefCount--;
@@ -2013,83 +1398,18 @@ _mesa_free_context_data( GLcontext *ctx )
       free_shared_state( ctx, ctx->Shared );
    }
 
-   /* Free lighting shininess exponentiation table */
-   foreach_s( s, tmps, ctx->_ShineTabList ) {
-      FREE( s );
-   }
-   FREE( ctx->_ShineTabList );
-
-   /* Free proxy texture objects */
-   (ctx->Driver.DeleteTexture)(ctx,  ctx->Texture.Proxy1D );
-   (ctx->Driver.DeleteTexture)(ctx,  ctx->Texture.Proxy2D );
-   (ctx->Driver.DeleteTexture)(ctx,  ctx->Texture.Proxy3D );
-   (ctx->Driver.DeleteTexture)(ctx,  ctx->Texture.ProxyCubeMap );
-   (ctx->Driver.DeleteTexture)(ctx,  ctx->Texture.ProxyRect );
-
-   for (i = 0; i < MAX_TEXTURE_IMAGE_UNITS; i++)
-      _mesa_free_colortable_data( &ctx->Texture.Unit[i].ColorTable );
-
-   /* Free evaluator data */
-   if (ctx->EvalMap.Map1Vertex3.Points)
-      FREE( ctx->EvalMap.Map1Vertex3.Points );
-   if (ctx->EvalMap.Map1Vertex4.Points)
-      FREE( ctx->EvalMap.Map1Vertex4.Points );
-   if (ctx->EvalMap.Map1Index.Points)
-      FREE( ctx->EvalMap.Map1Index.Points );
-   if (ctx->EvalMap.Map1Color4.Points)
-      FREE( ctx->EvalMap.Map1Color4.Points );
-   if (ctx->EvalMap.Map1Normal.Points)
-      FREE( ctx->EvalMap.Map1Normal.Points );
-   if (ctx->EvalMap.Map1Texture1.Points)
-      FREE( ctx->EvalMap.Map1Texture1.Points );
-   if (ctx->EvalMap.Map1Texture2.Points)
-      FREE( ctx->EvalMap.Map1Texture2.Points );
-   if (ctx->EvalMap.Map1Texture3.Points)
-      FREE( ctx->EvalMap.Map1Texture3.Points );
-   if (ctx->EvalMap.Map1Texture4.Points)
-      FREE( ctx->EvalMap.Map1Texture4.Points );
-   for (i = 0; i < 16; i++)
-      FREE((ctx->EvalMap.Map1Attrib[i].Points));
-
-   if (ctx->EvalMap.Map2Vertex3.Points)
-      FREE( ctx->EvalMap.Map2Vertex3.Points );
-   if (ctx->EvalMap.Map2Vertex4.Points)
-      FREE( ctx->EvalMap.Map2Vertex4.Points );
-   if (ctx->EvalMap.Map2Index.Points)
-      FREE( ctx->EvalMap.Map2Index.Points );
-   if (ctx->EvalMap.Map2Color4.Points)
-      FREE( ctx->EvalMap.Map2Color4.Points );
-   if (ctx->EvalMap.Map2Normal.Points)
-      FREE( ctx->EvalMap.Map2Normal.Points );
-   if (ctx->EvalMap.Map2Texture1.Points)
-      FREE( ctx->EvalMap.Map2Texture1.Points );
-   if (ctx->EvalMap.Map2Texture2.Points)
-      FREE( ctx->EvalMap.Map2Texture2.Points );
-   if (ctx->EvalMap.Map2Texture3.Points)
-      FREE( ctx->EvalMap.Map2Texture3.Points );
-   if (ctx->EvalMap.Map2Texture4.Points)
-      FREE( ctx->EvalMap.Map2Texture4.Points );
-   for (i = 0; i < 16; i++)
-      FREE((ctx->EvalMap.Map2Attrib[i].Points));
-
-   _mesa_free_colortable_data( &ctx->ColorTable );
-   _mesa_free_colortable_data( &ctx->PostConvolutionColorTable );
-   _mesa_free_colortable_data( &ctx->PostColorMatrixColorTable );
-   _mesa_free_colortable_data( &ctx->Texture.Palette );
-
-   _math_matrix_dtr(&ctx->Viewport._WindowMap);
-
-   if (ctx->Extensions.String)
-      FREE((void *) ctx->Extensions.String);
+   _mesa_extensions_dtr(ctx);
 
    FREE(ctx->Exec);
    FREE(ctx->Save);
 }
 
-
-
-/*
+/**
  * Destroy a GLcontext structure.
+ *
+ * \param ctx GL context.
+ * 
+ * Calls _mesa_free_context_data() and free the structure.
  */
 void
 _mesa_destroy_context( GLcontext *ctx )
@@ -2100,13 +1420,18 @@ _mesa_destroy_context( GLcontext *ctx )
    }
 }
 
-
-
-/*
+#if _HAVE_FULL_GL
+/**
  * Copy attribute groups from one context to another.
- * Input:  src - source context
- *         dst - destination context
- *         mask - bitwise OR of GL_*_BIT flags
+ * 
+ * \param src source context
+ * \param dst destination context
+ * \param mask bitwise OR of GL_*_BIT flags
+ *
+ * According to the bits specified in \p mask, copies the corresponding
+ * attributes from \p src into \dst.  For many of the attributes a simple \c
+ * memcpy is not enough due to the existence of internal pointers in their data
+ * structures.
  */
 void
 _mesa_copy_context( const GLcontext *src, GLcontext *dst, GLuint mask )
@@ -2214,35 +1539,7 @@ _mesa_copy_context( const GLcontext *src, GLcontext *dst, GLuint mask )
     */
    dst->NewState = _NEW_ALL;
 }
-
-
-
-static void print_info( void )
-{
-   _mesa_debug(NULL, "Mesa GL_VERSION = %s\n",
-	   (char *) _mesa_GetString(GL_VERSION));
-   _mesa_debug(NULL, "Mesa GL_RENDERER = %s\n",
-	   (char *) _mesa_GetString(GL_RENDERER));
-   _mesa_debug(NULL, "Mesa GL_VENDOR = %s\n",
-	   (char *) _mesa_GetString(GL_VENDOR));
-   _mesa_debug(NULL, "Mesa GL_EXTENSIONS = %s\n",
-	   (char *) _mesa_GetString(GL_EXTENSIONS));
-#if defined(THREADS)
-   _mesa_debug(NULL, "Mesa thread-safe: YES\n");
-#else
-   _mesa_debug(NULL, "Mesa thread-safe: NO\n");
-#endif
-#if defined(USE_X86_ASM)
-   _mesa_debug(NULL, "Mesa x86-optimized: YES\n");
-#else
-   _mesa_debug(NULL, "Mesa x86-optimized: NO\n");
 #endif
-#if defined(USE_SPARC_ASM)
-   _mesa_debug(NULL, "Mesa sparc-optimized: YES\n");
-#else
-   _mesa_debug(NULL, "Mesa sparc-optimized: NO\n");
-#endif
-}
 
 
 /**
@@ -2286,8 +1583,13 @@ check_compatible(const GLcontext *ctx, const GLframebuffer *buffer)
 }
 
 
-/*
+/**
  * Set the current context, binding the given frame buffer to the context.
+ *
+ * \param newCtx new GL context.
+ * \param buffer framebuffer.
+ * 
+ * Calls _mesa_make_current2() with \p buffer as read and write framebuffer.
  */
 void
 _mesa_make_current( GLcontext *newCtx, GLframebuffer *buffer )
@@ -2295,10 +1597,24 @@ _mesa_make_current( GLcontext *newCtx, GLframebuffer *buffer )
    _mesa_make_current2( newCtx, buffer, buffer );
 }
 
-
-/*
- * Bind the given context to the given draw-buffer and read-buffer
- * and make it the current context for this thread.
+/**
+ * Bind the given context to the given draw-buffer and read-buffer and
+ * make it the current context for this thread.
+ *
+ * \param newCtx new GL context. If NULL then there will be no current GL
+ * context.
+ * \param drawBuffer draw framebuffer.
+ * \param readBuffer read framebuffer.
+ * 
+ * Check that the context's and framebuffer's visuals are compatible, returning
+ * immediately otherwise. Sets the glapi current context via
+ * _glapi_set_context(). If \p newCtx is not NULL, associates \p drawBuffer and
+ * \p readBuffer with it and calls dd_function_table::ResizeBuffers if the buffers size has changed. 
+ * Calls dd_function_table::MakeCurrent callback if defined.
+ *
+ * When a context is bound by the first time and the \c MESA_INFO environment
+ * variable is set it calls print_info() as an aid for remote user
+ * troubleshooting.
  */
 void
 _mesa_make_current2( GLcontext *newCtx, GLframebuffer *drawBuffer,
@@ -2339,6 +1655,7 @@ _mesa_make_current2( GLcontext *newCtx, GLframebuffer *drawBuffer,
 	 newCtx->ReadBuffer = readBuffer;
 	 newCtx->NewState |= _NEW_BUFFERS;
 
+#if _HAVE_FULL_GL
          if (drawBuffer->Width == 0 && drawBuffer->Height == 0) {
             /* get initial window size */
             GLuint bufWidth, bufHeight;
@@ -2346,13 +1663,14 @@ _mesa_make_current2( GLcontext *newCtx, GLframebuffer *drawBuffer,
             /* ask device driver for size of output buffer */
             (*newCtx->Driver.GetBufferSize)( drawBuffer, &bufWidth, &bufHeight );
 
-            if (drawBuffer->Width == bufWidth && drawBuffer->Height == bufHeight)
-               return; /* size is as expected */
+            if (drawBuffer->Width != bufWidth || 
+		drawBuffer->Height != bufHeight) {
 
-            drawBuffer->Width = bufWidth;
-            drawBuffer->Height = bufHeight;
+	       drawBuffer->Width = bufWidth;
+	       drawBuffer->Height = bufHeight;
 
-            newCtx->Driver.ResizeBuffers( drawBuffer );
+ 	       newCtx->Driver.ResizeBuffers( drawBuffer );
+	    }
          }
 
          if (readBuffer != drawBuffer &&
@@ -2363,17 +1681,22 @@ _mesa_make_current2( GLcontext *newCtx, GLframebuffer *drawBuffer,
             /* ask device driver for size of output buffer */
             (*newCtx->Driver.GetBufferSize)( readBuffer, &bufWidth, &bufHeight );
 
-            if (readBuffer->Width == bufWidth && readBuffer->Height == bufHeight)
-               return; /* size is as expected */
+            if (readBuffer->Width != bufWidth ||
+		readBuffer->Height != bufHeight) {
 
-            readBuffer->Width = bufWidth;
-            readBuffer->Height = bufHeight;
+	       readBuffer->Width = bufWidth;
+	       readBuffer->Height = bufHeight;
 
-            newCtx->Driver.ResizeBuffers( readBuffer );
+	       newCtx->Driver.ResizeBuffers( readBuffer );
+	    }
          }
+#endif
       }
 
-      /* This is only for T&L - a bit out of place, or misnamed (BP) */
+      /* Alert the driver - usually passed on to the sw t&l module,
+       * but also used to detect threaded cases in the radeon codegen
+       * hw t&l module.
+       */
       if (newCtx->Driver.MakeCurrent)
 	 newCtx->Driver.MakeCurrent( newCtx, drawBuffer, readBuffer );
 
@@ -2384,19 +1707,20 @@ _mesa_make_current2( GLcontext *newCtx, GLframebuffer *drawBuffer,
        */
       if (newCtx->FirstTimeCurrent) {
 	 if (_mesa_getenv("MESA_INFO")) {
-	    print_info();
+	    _mesa_print_info();
 	 }
 	 newCtx->FirstTimeCurrent = GL_FALSE;
       }
    }
 }
 
-
-
-/*
- * Return current context handle for the calling thread.
- * This isn't the fastest way to get the current context.
- * If you need speed, see the GET_CURRENT_CONTEXT() macro in context.h
+/**
+ * Get current context for the calling thread.
+ * 
+ * \return pointer to the current GL context.
+ * 
+ * Calls _glapi_get_context(). This isn't the fastest way to get the current
+ * context.  If you need speed, see the #GET_CURRENT_CONTEXT macro in context.h.
  */
 GLcontext *
 _mesa_get_current_context( void )
@@ -2404,11 +1728,17 @@ _mesa_get_current_context( void )
    return (GLcontext *) _glapi_get_context();
 }
 
-
-/*
- * Return pointer to this context's current API dispatch table.
- * It'll either be the immediate-mode execute dispatcher or the
- * display list compile dispatcher.
+/**
+ * Get context's current API dispatch table.
+ *
+ * It'll either be the immediate-mode execute dispatcher or the display list
+ * compile dispatcher.
+ * 
+ * \param ctx GL context.
+ *
+ * \return pointer to dispatch_table.
+ *
+ * Simply returns __GLcontextRec::CurrentDispatch.
  */
 struct _glapi_table *
 _mesa_get_dispatch(GLcontext *ctx)
@@ -2416,15 +1746,24 @@ _mesa_get_dispatch(GLcontext *ctx)
    return ctx->CurrentDispatch;
 }
 
+/*@}*/
 
 
 /**********************************************************************/
-/*****                Miscellaneous functions                     *****/
+/** \name Miscellaneous functions                                     */
 /**********************************************************************/
+/*@{*/
 
-
-/*
- * Record the given error code and call the driver's Error function if defined.
+/**
+ * Record an error.
+ *
+ * \param ctx GL context.
+ * \param error error code.
+ * 
+ * Records the given error code and call the driver's dd_function_table::Error
+ * function if defined.
+ *
+ * \sa
  * This is called via _mesa_error().
  */
 void
@@ -2443,7 +1782,12 @@ _mesa_record_error( GLcontext *ctx, GLenum error )
    }
 }
 
-
+/**
+ * Execute glFinish().
+ *
+ * Calls the #ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH macro and the
+ * dd_function_table::Finish driver callback, if not NULL.
+ */
 void
 _mesa_Finish( void )
 {
@@ -2454,8 +1798,12 @@ _mesa_Finish( void )
    }
 }
 
-
-
+/**
+ * Execute glFlush().
+ *
+ * Calls the #ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH macro and the
+ * dd_function_table::Flush driver callback, if not NULL.
+ */
 void
 _mesa_Flush( void )
 {
@@ -2467,19 +1815,4 @@ _mesa_Flush( void )
 }
 
 
-
-const char *_mesa_prim_name[GL_POLYGON+4] = {
-   "GL_POINTS",
-   "GL_LINES",
-   "GL_LINE_LOOP",
-   "GL_LINE_STRIP",
-   "GL_TRIANGLES",
-   "GL_TRIANGLE_STRIP",
-   "GL_TRIANGLE_FAN",
-   "GL_QUADS",
-   "GL_QUAD_STRIP",
-   "GL_POLYGON",
-   "outside begin/end",
-   "inside unkown primitive",
-   "unknown state"
-};
+/*@}*/
diff --git a/src/mesa/main/context.h b/src/mesa/main/context.h
index a123b317bc..edd78e302d 100644
--- a/src/mesa/main/context.h
+++ b/src/mesa/main/context.h
@@ -1,3 +1,23 @@
+/**
+ * \file context.h
+ * Mesa context/visual/framebuffer management functions.
+ *
+ * There are three Mesa data types which are meant to be used by device
+ * drivers:
+ * - GLcontext: this contains the Mesa rendering state
+ * - GLvisual:  this describes the color buffer (RGB vs. ci), whether or not
+ *   there's a depth buffer, stencil buffer, etc.
+ * - GLframebuffer:  contains pointers to the depth buffer, stencil buffer,
+ *   accum buffer and alpha buffers.
+ *
+ * These types should be encapsulated by corresponding device driver
+ * data types.  See xmesa.h and xmesaP.h for an example.
+ *
+ * In OOP terms, GLcontext, GLvisual, and GLframebuffer are base classes
+ * which the device driver must derive from.
+ *
+ * The following functions create and destroy these data types.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -32,28 +52,10 @@
 #include "mtypes.h"
 
 
-/*
- * There are three Mesa datatypes which are meant to be used by device
- * drivers:
- *   GLcontext:  this contains the Mesa rendering state
- *   GLvisual:  this describes the color buffer (rgb vs. ci), whether
- *              or not there's a depth buffer, stencil buffer, etc.
- *   GLframebuffer:  contains pointers to the depth buffer, stencil
- *                   buffer, accum buffer and alpha buffers.
- *
- * These types should be encapsulated by corresponding device driver
- * datatypes.  See xmesa.h and xmesaP.h for an example.
- *
- * In OOP terms, GLcontext, GLvisual, and GLframebuffer are base classes
- * which the device driver must derive from.
- *
- * The following functions create and destroy these datatypes.
- */
-
-
-/*
- * Create/destroy a GLvisual.
- */
+/**********************************************************************/
+/** \name Create/destroy a GLvisual. */
+/*@{*/
+ 
 extern GLvisual *
 _mesa_create_visual( GLboolean rgbFlag,
                      GLboolean dbFlag,
@@ -92,11 +94,13 @@ _mesa_initialize_visual( GLvisual *v,
 extern void
 _mesa_destroy_visual( GLvisual *vis );
 
+/*@}*/
 
 
-/*
- * Create/destroy a GLframebuffer.
- */
+/**********************************************************************/
+/** \name Create/destroy a GLframebuffer. */
+/*@{*/
+ 
 extern GLframebuffer *
 _mesa_create_framebuffer( const GLvisual *visual,
                           GLboolean softwareDepth,
@@ -118,11 +122,13 @@ _mesa_free_framebuffer_data( GLframebuffer *buffer );
 extern void
 _mesa_destroy_framebuffer( GLframebuffer *buffer );
 
+/*@}*/
 
 
-/*
- * Create/destroy a GLcontext.
- */
+/**********************************************************************/
+/** \name Create/destroy a GLcontext. */
+/*@{*/
+
 extern GLcontext *
 _mesa_create_context( const GLvisual *visual,
                       GLcontext *share_list,
@@ -159,10 +165,21 @@ _mesa_make_current2( GLcontext *ctx, GLframebuffer *drawBuffer,
 extern GLcontext *
 _mesa_get_current_context(void);
 
+/*@}*/
 
 
-/*
- * Macros for fetching current context.
+/**
+ * Macro for declaration and fetching the current context.
+ *
+ * \param C local variable which will hold the current context.
+ *
+ * It should be used in the variable declaration area of a function:
+ * \code
+ * ...
+ * {
+ *   GET_CURRENT_CONTEXT(ctx);
+ *   ...
+ * \endcode
  */
 #ifdef THREADS
 
@@ -176,7 +193,9 @@ _mesa_get_current_context(void);
 
 
 
-/* OpenGL SI-style export functions. */
+/**********************************************************************/
+/** \name OpenGL SI-style export functions. */
+/*@{*/
 
 extern GLboolean
 _mesa_destroyContext(__GLcontext *gc);
@@ -214,6 +233,7 @@ _mesa_beginDispatchOverride(__GLcontext *gc);
 extern void
 _mesa_endDispatchOverride(__GLcontext *gc);
 
+/*@}*/
 
 
 extern struct _glapi_table *
@@ -221,9 +241,9 @@ _mesa_get_dispatch(GLcontext *ctx);
 
 
 
-/*
- * Miscellaneous
- */
+/**********************************************************************/
+/** \name Miscellaneous */
+/*@{*/
 
 extern void
 _mesa_record_error( GLcontext *ctx, GLenum error );
@@ -235,5 +255,6 @@ _mesa_Finish( void );
 extern void
 _mesa_Flush( void );
 
+/*@}*/
 
 #endif
diff --git a/src/mesa/main/convolve.h b/src/mesa/main/convolve.h
index f97c9f35bd..deac1e2c0b 100644
--- a/src/mesa/main/convolve.h
+++ b/src/mesa/main/convolve.h
@@ -31,6 +31,7 @@
 #include "mtypes.h"
 
 
+#if _HAVE_FULL_GL
 extern void
 _mesa_ConvolutionFilter1D(GLenum target, GLenum internalformat, GLsizei width,
                           GLenum format, GLenum type, const GLvoid *image);
@@ -103,5 +104,11 @@ extern void
 _mesa_adjust_image_for_convolution(const GLcontext *ctx, GLuint dimensions,
                                    GLsizei *width, GLsizei *height);
 
+#else
+#define _mesa_adjust_image_for_convolution(c, d, w, h) ((void)0)
+#define _mesa_convolve_1d_image(c,w,s,d) ((void)0)
+#define _mesa_convolve_2d_image(c,w,h,s,d) ((void)0)
+#define _mesa_convolve_sep_image(c,w,h,s,d) ((void)0)
+#endif
 
 #endif
diff --git a/src/mesa/main/dd.h b/src/mesa/main/dd.h
index 88ffb8fb47..1829bbc652 100644
--- a/src/mesa/main/dd.h
+++ b/src/mesa/main/dd.h
@@ -1,3 +1,7 @@
+/**
+ * \file dd.h
+ * Device driver interfaces.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,7 +28,6 @@
  */
 
 
-
 #ifndef DD_INCLUDED
 #define DD_INCLUDED
 
@@ -46,135 +49,183 @@ struct gl_pixelstore_attrib;
 #define DD_STENCIL_BIT     GL_STENCIL_BUFFER_BIT  /* 0x00000400 */
 
 
-/*
- * Device Driver function table.
+/**
+ * Device driver function table.
  */
 struct dd_function_table {
-   const GLubyte * (*GetString)( GLcontext *ctx, GLenum name );
-   /* Return a string as needed by glGetString().
-    * Only the GL_RENDERER token must be implemented.  Otherwise,
-    * NULL can be returned.
+   /**
+    * Return a string as needed by glGetString().
+    *
+    * Only the GL_RENDERER token must be implemented.  Otherwise, NULL can be
+    * returned.
     */
+   const GLubyte * (*GetString)( GLcontext *ctx, GLenum name );
 
-   void (*UpdateState)( GLcontext *ctx, GLuint new_state );
-   /*
-    * UpdateState() is called to notify the driver after Mesa has made
-    * some internal state changes.  This is in addition to any
-    * statechange callbacks Mesa may already have made.
+   /**
+    * Notify the driver after Mesa has made some internal state changes.  
+    *
+    * This is in addition to any state change callbacks Mesa may already have
+    * made.
     */
+   void (*UpdateState)( GLcontext *ctx, GLuint new_state );
 
-   void (*Clear)( GLcontext *ctx, GLbitfield mask, GLboolean all,
-		  GLint x, GLint y, GLint width, GLint height );
-   /* Clear the color/depth/stencil/accum buffer(s).
-    * 'mask' is a bitmask of the DD_*_BIT values defined above that indicates
+   /**
+    * Clear the color/depth/stencil/accum buffer(s).
+    *
+    * \param mask a bitmask of the DD_*_BIT values defined above that indicates
     * which buffers need to be cleared.
-    * If 'all' is true then the clear the whole buffer, else clear only the
-    * region defined by (x,y,width,height).
-    * This function must obey the glColorMask, glIndexMask and glStencilMask
+    * \param all if true then clear the whole buffer, else clear only the
+    * region defined by <tt>(x, y, width, height)</tt>.
+    * 
+    * This function must obey the glColorMask(), glIndexMask() and glStencilMask()
     * settings!
     * Software Mesa can do masked clears if the device driver can't.
     */
+   void (*Clear)( GLcontext *ctx, GLbitfield mask, GLboolean all,
+		  GLint x, GLint y, GLint width, GLint height );
 
-   void (*DrawBuffer)( GLcontext *ctx, GLenum buffer );
-   /*
-    * Specifies the current buffer for writing.  Called via glDrawBuffer().
-    * Note the driver must organize fallbacks (eg with swrast) if it
-    * cannot implement the requested mode.
+   /**
+    * Specify the current buffer for writing.  
+    *
+    * Called via glDrawBuffer().  Note the driver must organize fallbacks (e.g.
+    * with swrast) if it cannot implement the requested mode.
     */
+   void (*DrawBuffer)( GLcontext *ctx, GLenum buffer );
 
-
-   void (*ReadBuffer)( GLcontext *ctx, GLenum buffer );
-   /*
-    * Specifies the current buffer for reading.  Called via glReadBuffer().
+   /**
+    * Specifies the current buffer for reading.  
+    *
+    * Called via glReadBuffer().
     */
+   void (*ReadBuffer)( GLcontext *ctx, GLenum buffer );
 
-   void (*GetBufferSize)( GLframebuffer *buffer,
-                          GLuint *width, GLuint *height );
-   /*
-    * Returns the width and height of the named buffer/window.
+   /**
+    * Get the width and height of the named buffer/window.
+    *
     * Mesa uses this to determine when the driver's window size has changed.
     */
+   void (*GetBufferSize)( GLframebuffer *buffer,
+                          GLuint *width, GLuint *height );
 
-   void (*ResizeBuffers)( GLframebuffer *buffer );
-   /*
+   /**
     * Resize the driver's depth/stencil/accum/back buffers to match the
-    * size given in the GLframebuffer struct.  This is typically called
-    * when Mesa detects that a window size has changed.
+    * size given in the GLframebuffer struct.  
+    *
+    * This is typically called when Mesa detects that a window size has changed.
     */
+   void (*ResizeBuffers)( GLframebuffer *buffer );
 
-   void (*Finish)( GLcontext *ctx );
-   /*
+   /**
     * This is called whenever glFinish() is called.
     */
+   void (*Finish)( GLcontext *ctx );
 
-   void (*Flush)( GLcontext *ctx );
-   /*
+   /**
     * This is called whenever glFlush() is called.
     */
+   void (*Flush)( GLcontext *ctx );
 
-   void (*Error)( GLcontext *ctx );
-   /*
-    * Called whenever an error is generated.  ctx->ErrorValue contains
-    * the error value.
+   /**
+    * Called whenever an error is generated.  
+    *
+    * __GLcontextRec::ErrorValue contains the error value.
     */
+   void (*Error)( GLcontext *ctx );
 
 
-   /***
-    *** For hardware accumulation buffer:
-    ***/
+   /**
+    * \name For hardware accumulation buffer
+    */
+   /*@{*/
+   /**
+    * Execute glAccum command within the given scissor region.
+    */
    void (*Accum)( GLcontext *ctx, GLenum op, GLfloat value,
 		  GLint xpos, GLint ypos, GLint width, GLint height );
-   /* Execute glAccum command within the given scissor region.
-    */
+   /*@}*/
 
 
-   /***
-    *** glDraw/Read/CopyPixels and glBitmap functions:
-    ***/
+   /**
+    * \name glDraw(), glRead(), glCopyPixels() and glBitmap() functions
+    */
+   /*@{*/
 
+   /**
+    * This is called by glDrawPixels().
+    *
+    * \p unpack describes how to unpack the source image data.
+    */
    void (*DrawPixels)( GLcontext *ctx,
 		       GLint x, GLint y, GLsizei width, GLsizei height,
 		       GLenum format, GLenum type,
 		       const struct gl_pixelstore_attrib *unpack,
 		       const GLvoid *pixels );
-   /* This is called by glDrawPixels.
-    * 'unpack' describes how to unpack the source image data.
-    */
 
+   /**
+    * Called by glReadPixels().
+    */
    void (*ReadPixels)( GLcontext *ctx,
 		       GLint x, GLint y, GLsizei width, GLsizei height,
 		       GLenum format, GLenum type,
 		       const struct gl_pixelstore_attrib *unpack,
 		       GLvoid *dest );
-   /* Called by glReadPixels.
-    */
 
+   /**
+    * Do a glCopyPixels().  
+    *
+    * This function must respect all rasterization state, glPixelTransfer(),
+    * glPixelZoom(), etc.
+    */
    void (*CopyPixels)( GLcontext *ctx,
                             GLint srcx, GLint srcy,
                             GLsizei width, GLsizei height,
                             GLint dstx, GLint dsty, GLenum type );
-   /* Do a glCopyPixels.  This function must respect all rasterization
-    * state, glPixelTransfer, glPixelZoom, etc.
-    */
 
+   /**
+    * This is called by glBitmap().  
+    *
+    * Works the same as dd_function_table::DrawPixels, above.
+    */
    void (*Bitmap)( GLcontext *ctx,
 		   GLint x, GLint y, GLsizei width, GLsizei height,
 		   const struct gl_pixelstore_attrib *unpack,
 		   const GLubyte *bitmap );
-   /* This is called by glBitmap.  Works the same as DrawPixels, above.
+   /*@}*/
+
+   
+   /**
+    * \name Texture image functions
     */
+   /*@{*/
 
-   /***
-    *** Texture image functions:
-    ***/
+   /**
+    * Choose texture format.
+    * 
+    * This is called by the \c _mesa_store_tex[sub]image[123]d() fallback
+    * functions.  The driver should examine \p internalFormat and return a
+    * pointer to an appropriate gl_texture_format.
+    */
    const struct gl_texture_format *
    (*ChooseTextureFormat)( GLcontext *ctx, GLint internalFormat,
                            GLenum srcFormat, GLenum srcType );
-   /* This is called by the _mesa_store_tex[sub]image[123]d() fallback
-    * functions.  The driver should examine <internalFormat> and return a
-    * pointer to an appropriate gl_texture_format.
-    */
 
+   /**
+    * Called by glTexImage1D().
+    * 
+    * \param target user specified.
+    * \param format user specified.
+    * \param type user specified.
+    * \param pixels user specified.
+    * \param packing indicates the image packing of pixels.
+    * \param texObj is the target texture object.
+    * \param texImage is the target texture image.  It will have the texture \p
+    * width, \p height, \p depth, \p border and \p internalFormat information.
+    * 
+    * \p retainInternalCopy is returned by this function and indicates whether
+    * core Mesa should keep an internal copy of the texture image.
+    *
+    * Drivers should call a fallback routine from texstore.c if needed.
+    */
    void (*TexImage1D)( GLcontext *ctx, GLenum target, GLint level,
                        GLint internalFormat,
                        GLint width, GLint border,
@@ -182,6 +233,12 @@ struct dd_function_table {
                        const struct gl_pixelstore_attrib *packing,
                        struct gl_texture_object *texObj,
                        struct gl_texture_image *texImage );
+
+   /**
+    * Called by glTexImage2D().
+    * 
+    * \sa dd_function_table::TexImage1D.
+    */
    void (*TexImage2D)( GLcontext *ctx, GLenum target, GLint level,
                        GLint internalFormat,
                        GLint width, GLint height, GLint border,
@@ -189,6 +246,12 @@ struct dd_function_table {
                        const struct gl_pixelstore_attrib *packing,
                        struct gl_texture_object *texObj,
                        struct gl_texture_image *texImage );
+   
+   /**
+    * Called by glTexImage3D().
+    * 
+    * \sa dd_function_table::TexImage1D.
+    */
    void (*TexImage3D)( GLcontext *ctx, GLenum target, GLint level,
                        GLint internalFormat,
                        GLint width, GLint height, GLint depth, GLint border,
@@ -196,18 +259,28 @@ struct dd_function_table {
                        const struct gl_pixelstore_attrib *packing,
                        struct gl_texture_object *texObj,
                        struct gl_texture_image *texImage );
-   /* Called by glTexImage1/2/3D.
-    * Arguments:
-    *   <target>, <level>, <format>, <type> and <pixels> are user specified.
-    *   <packing> indicates the image packing of pixels.
-    *   <texObj> is the target texture object.
-    *   <texImage> is the target texture image.  It will have the texture
-    *      width, height, depth, border and internalFormat information.
-    *   <retainInternalCopy> is returned by this function and indicates whether
-    *      core Mesa should keep an internal copy of the texture image.
-    * Drivers should call a fallback routine from texstore.c if needed.
-    */
 
+   /**
+    * Called by glTexSubImage1D().
+    *
+    * \param target user specified.
+    * \param level user specified.
+    * \param xoffset user specified.
+    * \param yoffset user specified.
+    * \param zoffset user specified.
+    * \param width user specified.
+    * \param height user specified.
+    * \param depth user specified.
+    * \param format user specified.
+    * \param type user specified.
+    * \param pixels user specified.
+    * \param packing indicates the image packing of pixels.
+    * \param texObj is the target texture object.
+    * \param texImage is the target texture image.  It will have the texture \p
+    * width, \p height, \p border and \p internalFormat information.
+    *
+    * The driver should use a fallback routine from texstore.c if needed.
+    */
    void (*TexSubImage1D)( GLcontext *ctx, GLenum target, GLint level,
                           GLint xoffset, GLsizei width,
                           GLenum format, GLenum type,
@@ -215,6 +288,12 @@ struct dd_function_table {
                           const struct gl_pixelstore_attrib *packing,
                           struct gl_texture_object *texObj,
                           struct gl_texture_image *texImage );
+   
+   /**
+    * Called by glTexSubImage2D().
+    *
+    * \sa dd_function_table::TexSubImage1D.
+    */
    void (*TexSubImage2D)( GLcontext *ctx, GLenum target, GLint level,
                           GLint xoffset, GLint yoffset,
                           GLsizei width, GLsizei height,
@@ -223,6 +302,12 @@ struct dd_function_table {
                           const struct gl_pixelstore_attrib *packing,
                           struct gl_texture_object *texObj,
                           struct gl_texture_image *texImage );
+   
+   /**
+    * Called by glTexSubImage3D().
+    *
+    * \sa dd_function_table::TexSubImage1D.
+    */
    void (*TexSubImage3D)( GLcontext *ctx, GLenum target, GLint level,
                           GLint xoffset, GLint yoffset, GLint zoffset,
                           GLsizei width, GLsizei height, GLint depth,
@@ -231,68 +316,108 @@ struct dd_function_table {
                           const struct gl_pixelstore_attrib *packing,
                           struct gl_texture_object *texObj,
                           struct gl_texture_image *texImage );
-   /* Called by glTexSubImage1/2/3D.
-    * Arguments:
-    *   <target>, <level>, <xoffset>, <yoffset>, <zoffset>, <width>, <height>,
-    *      <depth>, <format>, <type> and <pixels> are user specified.
-    *   <packing> indicates the image packing of pixels.
-    *   <texObj> is the target texture object.
-    *   <texImage> is the target texture image.  It will have the texture
-    *      width, height, border and internalFormat information.
-    * The driver should use a fallback routine from texstore.c if needed.
-    */
 
+   /**
+    * Called by glCopyTexImage1D().
+    * 
+    * Drivers should use a fallback routine from texstore.c if needed.
+    */
    void (*CopyTexImage1D)( GLcontext *ctx, GLenum target, GLint level,
                            GLenum internalFormat, GLint x, GLint y,
                            GLsizei width, GLint border );
+
+   /**
+    * Called by glCopyTexImage2D().
+    * 
+    * Drivers should use a fallback routine from texstore.c if needed.
+    */
    void (*CopyTexImage2D)( GLcontext *ctx, GLenum target, GLint level,
                            GLenum internalFormat, GLint x, GLint y,
                            GLsizei width, GLsizei height, GLint border );
-   /* Called by glCopyTexImage1D and glCopyTexImage2D.
+
+   /**
+    * Called by glCopyTexSubImage1D().
+    * 
     * Drivers should use a fallback routine from texstore.c if needed.
     */
-
    void (*CopyTexSubImage1D)( GLcontext *ctx, GLenum target, GLint level,
                               GLint xoffset,
                               GLint x, GLint y, GLsizei width );
+   /**
+    * Called by glCopyTexSubImage2D().
+    * 
+    * Drivers should use a fallback routine from texstore.c if needed.
+    */
    void (*CopyTexSubImage2D)( GLcontext *ctx, GLenum target, GLint level,
                               GLint xoffset, GLint yoffset,
                               GLint x, GLint y,
                               GLsizei width, GLsizei height );
+   /**
+    * Called by glCopyTexSubImage3D().
+    * 
+    * Drivers should use a fallback routine from texstore.c if needed.
+    */
    void (*CopyTexSubImage3D)( GLcontext *ctx, GLenum target, GLint level,
                               GLint xoffset, GLint yoffset, GLint zoffset,
                               GLint x, GLint y,
                               GLsizei width, GLsizei height );
-   /* Called by glCopyTexSubImage1/2/3D.
-    * Drivers should use a fallback routine from texstore.c if needed.
-    */
 
+   /**
+    * Called by glTexImage[123]D when user specifies a proxy texture
+    * target.  
+    *
+    * \return GL_TRUE if the proxy test passes, or GL_FALSE if the test fails.
+    */
    GLboolean (*TestProxyTexImage)(GLcontext *ctx, GLenum target,
                                   GLint level, GLint internalFormat,
                                   GLenum format, GLenum type,
                                   GLint width, GLint height,
                                   GLint depth, GLint border);
-   /* Called by glTexImage[123]D when user specifies a proxy texture
-    * target.  Return GL_TRUE if the proxy test passes, return GL_FALSE
-    * if the test fails.
-    */
+   /*@}*/
 
-   /***
-    *** Compressed texture functions:
-    ***/
+   
+   /**
+    * \name Compressed texture functions
+    */
+   /*@{*/
 
+   /**
+    * Called by glCompressedTexImage1D().
+    *
+    * \param target user specified.
+    * \param format user specified.
+    * \param type user specified.
+    * \param pixels user specified.
+    * \param packing indicates the image packing of pixels.
+    * \param texObj is the target texture object.
+    * \param texImage is the target texture image.  It will have the texture \p
+    * width, \p height, \p depth, \p border and \p internalFormat information.
+    *      
+    * \a retainInternalCopy is returned by this function and indicates whether
+    * core Mesa should keep an internal copy of the texture image.
+    */
    void (*CompressedTexImage1D)( GLcontext *ctx, GLenum target,
                                  GLint level, GLint internalFormat,
                                  GLsizei width, GLint border,
                                  GLsizei imageSize, const GLvoid *data,
                                  struct gl_texture_object *texObj,
                                  struct gl_texture_image *texImage );
+   /**
+    * Called by glCompressedTexImage2D().
+    *
+    * \sa dd_function_table::CompressedTexImage1D.
+    */
    void (*CompressedTexImage2D)( GLcontext *ctx, GLenum target,
                                  GLint level, GLint internalFormat,
                                  GLsizei width, GLsizei height, GLint border,
                                  GLsizei imageSize, const GLvoid *data,
                                  struct gl_texture_object *texObj,
                                  struct gl_texture_image *texImage );
+   /**
+    * Called by glCompressedTexImage3D().
+    *
+    * \sa dd_function_table::CompressedTexImage3D.
+    */
    void (*CompressedTexImage3D)( GLcontext *ctx, GLenum target,
                                  GLint level, GLint internalFormat,
                                  GLsizei width, GLsizei height, GLsizei depth,
@@ -300,24 +425,35 @@ struct dd_function_table {
                                  GLsizei imageSize, const GLvoid *data,
                                  struct gl_texture_object *texObj,
                                  struct gl_texture_image *texImage );
-   /* Called by glCompressedTexImage1/2/3D.
-    * Arguments:
-    *   <target>, <level>, <internalFormat>, <data> are user specified.
-    *   <texObj> is the target texture object.
-    *   <texImage> is the target texture image.  It will have the texture
-    *      width, height, depth, border and internalFormat information.
-    *   <retainInternalCopy> is returned by this function and indicates whether
-    *      core Mesa should keep an internal copy of the texture image.
-    * Return GL_TRUE if operation completed, return GL_FALSE if core Mesa
-    * should do the job.
-    */
 
+   /**
+    * Called by glCompressedTexSubImage1D().
+    * 
+    * \param target user specified.
+    * \param level user specified.
+    * \param xoffset user specified.
+    * \param yoffset user specified.
+    * \param zoffset user specified.
+    * \param width user specified.
+    * \param height user specified.
+    * \param depth user specified.
+    * \param imageSize user specified.
+    * \param data user specified.
+    * \param texObj is the target texture object.
+    * \param texImage is the target texture image.  It will have the texture \p
+    * width, \p height, \p depth, \p border and \p internalFormat information.
+    */
    void (*CompressedTexSubImage1D)(GLcontext *ctx, GLenum target, GLint level,
                                    GLint xoffset, GLsizei width,
                                    GLenum format,
                                    GLsizei imageSize, const GLvoid *data,
                                    struct gl_texture_object *texObj,
                                    struct gl_texture_image *texImage);
+   /**
+    * Called by glCompressedTexSubImage2D().
+    *
+    * \sa dd_function_table::CompressedTexImage3D.
+    */
    void (*CompressedTexSubImage2D)(GLcontext *ctx, GLenum target, GLint level,
                                    GLint xoffset, GLint yoffset,
                                    GLsizei width, GLint height,
@@ -325,6 +461,11 @@ struct dd_function_table {
                                    GLsizei imageSize, const GLvoid *data,
                                    struct gl_texture_object *texObj,
                                    struct gl_texture_image *texImage);
+   /**
+    * Called by glCompressedTexSubImage3D().
+    *
+    * \sa dd_function_table::CompressedTexImage3D.
+    */
    void (*CompressedTexSubImage3D)(GLcontext *ctx, GLenum target, GLint level,
                                    GLint xoffset, GLint yoffset, GLint zoffset,
                                    GLsizei width, GLint height, GLint depth,
@@ -332,67 +473,77 @@ struct dd_function_table {
                                    GLsizei imageSize, const GLvoid *data,
                                    struct gl_texture_object *texObj,
                                    struct gl_texture_image *texImage);
-   /* Called by glCompressedTexSubImage1/2/3D.
-    * Arguments:
-    *   <target>, <level>, <x/z/zoffset>, <width>, <height>, <depth>,
-    *      <imageSize>, and <data> are user specified.
-    *   <texObj> is the target texture object.
-    *   <texImage> is the target texture image.  It will have the texture
-    *      width, height, depth, border and internalFormat information.
-    * Return GL_TRUE if operation completed, return GL_FALSE if core Mesa
-    * should do the job.
-    */
+   /*@}*/
 
-   /***
-    *** Texture object functions:
-    ***/
+   /**
+    * \name Texture object functions
+    */
+   /*@{*/
 
+   /**
+    * Called by glBindTexture().
+    */
    void (*BindTexture)( GLcontext *ctx, GLenum target,
                         struct gl_texture_object *tObj );
-   /* Called by glBindTexture().
+
+   /**
+    * Called when a texture object is created.
     */
+   void (*CreateTexture)( GLcontext *ctx, struct gl_texture_object *tObj );
 
-   struct gl_texture_object * (*NewTextureObject)( GLcontext *ctx, GLuint name,
-                                                   GLenum target );
-   /* Called to allocate a new texture object.
-    * NOTE: this function pointer should be initialized by drivers _BEFORE_
+   /**
+    * Called to allocate a new texture object.
+    * 
+    * \note This function pointer should be initialized by drivers \e before
     * calling _mesa_initialize_context() since context initialization involves
     * allocating some texture objects!
     */
-
-   void (*DeleteTexture)( GLcontext *ctx, struct gl_texture_object *tObj );
-   /* Called when a texture object is about to be deallocated.  Driver
-    * should free anything attached to the DriverData pointers.
+   struct gl_texture_object * (*NewTextureObject)( GLcontext *ctx, GLuint name,
+                                                   GLenum target );
+   /**
+    * Called when a texture object is about to be deallocated.  
+    *
+    * Driver should free anything attached to the DriverData pointers.
     */
+   void (*DeleteTexture)( GLcontext *ctx, struct gl_texture_object *tObj );
 
-   struct gl_texture_image * (*NewTextureImage)( GLcontext *ctx );
-   /* Called to allocate a new texture image object.
+   /**
+    * Called to allocate a new texture image object.
     */
+   struct gl_texture_image * (*NewTextureImage)( GLcontext *ctx );
 
+   /**
+    * Called by glAreTextureResident().
+    */
    GLboolean (*IsTextureResident)( GLcontext *ctx,
                                    struct gl_texture_object *t );
-   /* Called by glAreTextureResident().
-    */
 
+   /**
+    * Called by glPrioritizeTextures().
+    */
    void (*PrioritizeTexture)( GLcontext *ctx,  struct gl_texture_object *t,
                               GLclampf priority );
-   /* Called by glPrioritizeTextures().
-    */
 
-   void (*ActiveTexture)( GLcontext *ctx, GLuint texUnitNumber );
-   /* Called by glActiveTextureARB to set current texture unit.
+   /**
+    * Called by glActiveTextureARB() to set current texture unit.
     */
+   void (*ActiveTexture)( GLcontext *ctx, GLuint texUnitNumber );
 
+   /**
+    * Called when the texture's color lookup table is changed.
+    * 
+    * If \p tObj is NULL then the shared texture palette
+    * gl_texture_object::Palette is to be updated.
+    */
    void (*UpdateTexturePalette)( GLcontext *ctx,
                                  struct gl_texture_object *tObj );
-   /* Called when the texture's color lookup table is changed.
-    * If tObj is NULL then the shared texture palette ctx->Texture.Palette
-    * is to be updated.
-    */
+   /*@}*/
 
-   /***
-    *** Imaging functionality:
-    ***/
+   
+   /**
+    * \name Imaging functionality
+    */
+   /*@{*/
    void (*CopyColorTable)( GLcontext *ctx,
 			   GLenum target, GLenum internalformat,
 			   GLint x, GLint y, GLsizei width );
@@ -409,74 +560,119 @@ struct dd_function_table {
 				    GLenum internalFormat,
 				    GLint x, GLint y,
 				    GLsizei width, GLsizei height );
+   /*@}*/
 
 
-
-   /***
-    *** State-changing functions (drawing functions are above)
-    ***
-    *** These functions are called by their corresponding OpenGL API functions.
-    *** They're ALSO called by the gl_PopAttrib() function!!!
-    *** May add more functions like these to the device driver in the future.
-    ***/
+   /**
+    * \name State-changing functions.
+    *
+    * \note drawing functions are above.
+    *
+    * These functions are called by their corresponding OpenGL API functions.
+    * They are \e also called by the gl_PopAttrib() function!!!
+    * May add more functions like these to the device driver in the future.
+    */
+   /*@{*/
+   /** Specify the alpha test function */
    void (*AlphaFunc)(GLcontext *ctx, GLenum func, GLfloat ref);
+   /** Set the blend color */
    void (*BlendColor)(GLcontext *ctx, const GLfloat color[4]);
+   /** Set the blend equation */
    void (*BlendEquation)(GLcontext *ctx, GLenum mode);
+   /** Specify pixel arithmetic */
    void (*BlendFunc)(GLcontext *ctx, GLenum sfactor, GLenum dfactor);
    void (*BlendFuncSeparate)(GLcontext *ctx,
                              GLenum sfactorRGB, GLenum dfactorRGB,
                              GLenum sfactorA, GLenum dfactorA);
+   /** Specify clear values for the color buffers */
    void (*ClearColor)(GLcontext *ctx, const GLfloat color[4]);
+   /** Specify the clear value for the depth buffer */
    void (*ClearDepth)(GLcontext *ctx, GLclampd d);
+   /** Specify the clear value for the color index buffers */
    void (*ClearIndex)(GLcontext *ctx, GLuint index);
+   /** Specify the clear value for the stencil buffer */
    void (*ClearStencil)(GLcontext *ctx, GLint s);
+   /** Specify a plane against which all geometry is clipped */
    void (*ClipPlane)(GLcontext *ctx, GLenum plane, const GLfloat *equation );
+   /** Enable and disable writing of frame buffer color components */
    void (*ColorMask)(GLcontext *ctx, GLboolean rmask, GLboolean gmask,
                      GLboolean bmask, GLboolean amask );
+   /** Cause a material color to track the current color */
    void (*ColorMaterial)(GLcontext *ctx, GLenum face, GLenum mode);
+   /** Specify whether front- or back-facing facets can be culled */
    void (*CullFace)(GLcontext *ctx, GLenum mode);
+   /** Define front- and back-facing polygons */
    void (*FrontFace)(GLcontext *ctx, GLenum mode);
+   /** Specify the value used for depth buffer comparisons */
    void (*DepthFunc)(GLcontext *ctx, GLenum func);
+   /** Enable or disable writing into the depth buffer */
    void (*DepthMask)(GLcontext *ctx, GLboolean flag);
+   /** Specify mapping of depth values from normalized device coordinates to window coordinates */
    void (*DepthRange)(GLcontext *ctx, GLclampd nearval, GLclampd farval);
-   void (*Enable)(GLcontext* ctx, GLenum cap, GLboolean state);
+   /** Enable or disable server-side gl capabilities */
+   void (*Enable)(GLcontext *ctx, GLenum cap, GLboolean state);
+   /** Specify fog parameters */
    void (*Fogfv)(GLcontext *ctx, GLenum pname, const GLfloat *params);
+   /** Specify implementation-specific hints */
    void (*Hint)(GLcontext *ctx, GLenum target, GLenum mode);
+   /** Control the writing of individual bits in the color index buffers */
    void (*IndexMask)(GLcontext *ctx, GLuint mask);
+   /** Set light source parameters */
    void (*Lightfv)(GLcontext *ctx, GLenum light,
 		   GLenum pname, const GLfloat *params );
+   /** Set the lighting model parameters */
    void (*LightModelfv)(GLcontext *ctx, GLenum pname, const GLfloat *params);
+   /** Specify the line stipple pattern */
    void (*LineStipple)(GLcontext *ctx, GLint factor, GLushort pattern );
+   /** Specify the width of rasterized lines */
    void (*LineWidth)(GLcontext *ctx, GLfloat width);
+   /** Specify a logical pixel operation for color index rendering */
    void (*LogicOpcode)(GLcontext *ctx, GLenum opcode);
    void (*PointParameterfv)(GLcontext *ctx, GLenum pname,
                             const GLfloat *params);
+   /** Specify the diameter of rasterized points */
    void (*PointSize)(GLcontext *ctx, GLfloat size);
+   /** Select a polygon rasterization mode */
    void (*PolygonMode)(GLcontext *ctx, GLenum face, GLenum mode);
+   /** Set the scale and units used to calculate depth values */
    void (*PolygonOffset)(GLcontext *ctx, GLfloat factor, GLfloat units);
+   /** Set the polygon stippling pattern */
    void (*PolygonStipple)(GLcontext *ctx, const GLubyte *mask );
+   /** Set rasterization mode */
    void (*RenderMode)(GLcontext *ctx, GLenum mode );
+   /** Define the scissor box */
    void (*Scissor)(GLcontext *ctx, GLint x, GLint y, GLsizei w, GLsizei h);
+   /** Select flat or smooth shading */
    void (*ShadeModel)(GLcontext *ctx, GLenum mode);
+   /** Set function and reference value for stencil testing */
    void (*StencilFunc)(GLcontext *ctx, GLenum func, GLint ref, GLuint mask);
+   /** Control the writing of individual bits in the stencil planes */
    void (*StencilMask)(GLcontext *ctx, GLuint mask);
+   /** Set stencil test actions */
    void (*StencilOp)(GLcontext *ctx, GLenum fail, GLenum zfail, GLenum zpass);
    void (*ActiveStencilFace)(GLcontext *ctx, GLuint face);
+   /** Control the generation of texture coordinates */
    void (*TexGen)(GLcontext *ctx, GLenum coord, GLenum pname,
 		  const GLfloat *params);
+   /** Set texture environment parameters */
    void (*TexEnv)(GLcontext *ctx, GLenum target, GLenum pname,
                   const GLfloat *param);
+   /** Set texture parameters */
    void (*TexParameter)(GLcontext *ctx, GLenum target,
                         struct gl_texture_object *texObj,
                         GLenum pname, const GLfloat *params);
    void (*TextureMatrix)(GLcontext *ctx, GLuint unit, const GLmatrix *mat);
+   /** Set the viewport */
    void (*Viewport)(GLcontext *ctx, GLint x, GLint y, GLsizei w, GLsizei h);
+   /*@}*/
+
 
-   /***
-    *** Vertex array functions
-    ***
-    *** Called by the corresponding OpenGL functions.
-    ***/
+   /**
+    * \name Vertex array functions
+    *
+    * Called by the corresponding OpenGL functions.
+    */
+   /*@{*/
    void (*VertexPointer)(GLcontext *ctx, GLint size, GLenum type,
 			 GLsizei stride, const GLvoid *ptr);
    void (*NormalPointer)(GLcontext *ctx, GLenum type,
@@ -494,111 +690,171 @@ struct dd_function_table {
    void (*EdgeFlagPointer)(GLcontext *ctx, GLsizei stride, const GLvoid *ptr);
    void (*VertexAttribPointer)(GLcontext *ctx, GLuint index, GLint size,
                                GLenum type, GLsizei stride, const GLvoid *ptr);
+   /*@}*/
 
 
-   /*** State-query functions
-    ***
-    *** Return GL_TRUE if query was completed, GL_FALSE otherwise.
-    ***/
+   /** 
+    * \name State-query functions
+    *
+    * Return GL_TRUE if query was completed, GL_FALSE otherwise.
+    */
+   /*@{*/
+   /** Return the value or values of a selected parameter */
    GLboolean (*GetBooleanv)(GLcontext *ctx, GLenum pname, GLboolean *result);
+   /** Return the value or values of a selected parameter */
    GLboolean (*GetDoublev)(GLcontext *ctx, GLenum pname, GLdouble *result);
+   /** Return the value or values of a selected parameter */
    GLboolean (*GetFloatv)(GLcontext *ctx, GLenum pname, GLfloat *result);
+   /** Return the value or values of a selected parameter */
    GLboolean (*GetIntegerv)(GLcontext *ctx, GLenum pname, GLint *result);
+   /** Return the value or values of a selected parameter */
    GLboolean (*GetPointerv)(GLcontext *ctx, GLenum pname, GLvoid **result);
+   /*@}*/
+   
 
-   /***
-    *** Support for multiple t&l engines
-    ***/
+   /**
+    * \name Support for multiple T&L engines
+    */
+   /*@{*/
 
-   GLuint NeedValidate;
-   /* Bitmask of state changes that require the current tnl module to be
+   /**
+    * Bitmask of state changes that require the current T&L module to be
     * validated, using ValidateTnlModule() below.
     */
+   GLuint NeedValidate;
 
-   void (*ValidateTnlModule)( GLcontext *ctx, GLuint new_state );
-   /* Validate the current tnl module.  This is called directly after
-    * UpdateState() when a state change that has occured matches the
-    * NeedValidate bitmask above.  This ensures all computed values are
-    * up to date, thus allowing the driver to decide if the current tnl
-    * module needs to be swapped out.
+   /**
+    * Validate the current T&L module. 
+    *
+    * This is called directly after UpdateState() when a state change that has
+    * occurred matches the dd_function_table::NeedValidate bitmask above.  This
+    * ensures all computed values are up to date, thus allowing the driver to
+    * decide if the current T&L module needs to be swapped out.
     *
-    * This must be non-NULL if a driver installs a custom tnl module and
-    * sets the NeedValidate bitmask, but may be NULL otherwise.
+    * This must be non-NULL if a driver installs a custom T&L module and sets
+    * the dd_function_table::NeedValidate bitmask, but may be NULL otherwise.
     */
+   void (*ValidateTnlModule)( GLcontext *ctx, GLuint new_state );
 
 
 #define PRIM_OUTSIDE_BEGIN_END   GL_POLYGON+1
 #define PRIM_INSIDE_UNKNOWN_PRIM GL_POLYGON+2
 #define PRIM_UNKNOWN             GL_POLYGON+3
 
-   GLuint CurrentExecPrimitive;
-   /* Set by the driver-supplied t&l engine.  Set to
-    * PRIM_OUTSIDE_BEGIN_END when outside begin/end.
+   /**
+    * Set by the driver-supplied T&L engine.  
+    *
+    * Set to PRIM_OUTSIDE_BEGIN_END when outside glBegin()/glEnd().
     */
+   GLuint CurrentExecPrimitive;
 
-   GLuint CurrentSavePrimitive;
-   /* Current state of an in-progress compilation.  May take on any of
-    * the additional values defined above.
+   /**
+    * Current state of an in-progress compilation.  
+    *
+    * May take on any of the additional values PRIM_OUTSIDE_BEGIN_END,
+    * PRIM_INSIDE_UNKNOWN_PRIM or PRIM_UNKNOWN defined above.
     */
+   GLuint CurrentSavePrimitive;
 
 
 #define FLUSH_STORED_VERTICES 0x1
 #define FLUSH_UPDATE_CURRENT  0x2
-   GLuint NeedFlush;
-   /* Set by the driver-supplied t&l engine whenever vertices are
-    * buffered between begin/end objects or ctx->Current is not uptodate.
+   /**
+    * Set by the driver-supplied T&L engine whenever vertices are buffered
+    * between glBegin()/glEnd() objects or __GLcontextRec::Current is not
+    * updated.
     *
-    * The FlushVertices() call below may be used to resolve
+    * The dd_function_table::FlushVertices call below may be used to resolve
     * these conditions.
     */
+   GLuint NeedFlush;
 
-   void (*FlushVertices)( GLcontext *ctx, GLuint flags );
-   /* If inside begin/end, ASSERT(0).
-    * Otherwise,
-    *   if (flags & FLUSH_STORED_VERTICES) flushes any buffered vertices,
-    *   if (flags & FLUSH_UPDATE_CURRENT) updates ctx->Current
-    *                                     and ctx->Light.Material
+   /**
+    * If inside glBegin()/glEnd(), it should ASSERT(0).  Otherwise, if
+    * FLUSH_STORED_VERTICES bit in \p flags is set flushes any buffered
+    * vertices, if FLUSH_UPDATE_CURRENT bit is set updates
+    * __GLcontextRec::Current and gl_light_attrib::Material
     *
-    * Note that the default t&l engine never clears the
+    * Note that the default T&L engine never clears the
     * FLUSH_UPDATE_CURRENT bit, even after performing the update.
     */
+   void (*FlushVertices)( GLcontext *ctx, GLuint flags );
 
-   void (*LightingSpaceChange)( GLcontext *ctx );
-   /* Notify driver that the special derived value _NeedEyeCoords has
+   /**
+    * Notify driver that the special derived value _NeedEyeCoords has
     * changed.
     */
+   void (*LightingSpaceChange)( GLcontext *ctx );
 
-   void (*NewList)( GLcontext *ctx, GLuint list, GLenum mode );
-   void (*EndList)( GLcontext *ctx );
-   /* Let the t&l component know what is going on with display lists
+   /**
+    * Called by glNewList().
+    *
+    * Let the T&L component know what is going on with display lists
     * in time to make changes to dispatch tables, etc.
-    * Called by glNewList() and glEndList(), respectively.
     */
+   void (*NewList)( GLcontext *ctx, GLuint list, GLenum mode );
+   /**
+    * Called by glEndList().
+    *
+    * \sa dd_function_table::NewList.
+    */
+   void (*EndList)( GLcontext *ctx );
 
-   void (*BeginCallList)( GLcontext *ctx, GLuint list );
-   void (*EndCallList)( GLcontext *ctx );
-   /* Notify the t&l component before and after calling a display list.
+   /**
+    * Called by glCallList(s), but not recursively.
+    *
+    * Notify the T&L component before and after calling a display list.
     * Called by glCallList(s), but not recursively.
     */
+   void (*BeginCallList)( GLcontext *ctx, GLuint list );
+   /**
+    * Called by glEndCallList().
+    *
+    * \sa dd_function_table::BeginCallList.
+    */
+   void (*EndCallList)( GLcontext *ctx );
 
+   /**
+    * Let the T&L component know when the context becomes current.
+    */
    void (*MakeCurrent)( GLcontext *ctx, GLframebuffer *drawBuffer,
 			GLframebuffer *readBuffer );
-   /* Let the t&l component know when the context becomes current.
-    */
-
 
+   /**
+    * Called by glLockArraysEXT().
+    */
    void (*LockArraysEXT)( GLcontext *ctx, GLint first, GLsizei count );
-   void (*UnlockArraysEXT)( GLcontext *ctx );
-   /* Called by glLockArraysEXT() and glUnlockArraysEXT(), respectively.
+   /**
+    * Called by UnlockArraysEXT().
     */
+   void (*UnlockArraysEXT)( GLcontext *ctx );
+   /*@}*/
 };
 
 
-
-/*
+/**
  * Transform/Clip/Lighting interface
+ *
+ * Drivers present a reduced set of the functions possible in
+ * glBegin()/glEnd() objects.  Core mesa provides translation stubs for the
+ * remaining functions to map down to these entry points.
+ *
+ * These are the initial values to be installed into dispatch by
+ * mesa.  If the T&L driver wants to modify the dispatch table
+ * while installed, it must do so itself.  It would be possible for
+ * the vertexformat to install it's own initial values for these
+ * functions, but this way there is an obvious list of what is
+ * expected of the driver.
+ *
+ * If the driver wants to hook in entry points other than those
+ * listed, it must restore them to their original values in
+ * the disable() callback, below.
  */
 typedef struct {
+   /**
+    * \name Vertex
+    */
+   /*@{*/
    void (*ArrayElement)( GLint ); /* NOTE */
    void (*Color3f)( GLfloat, GLfloat, GLfloat );
    void (*Color3fv)( const GLfloat * );
@@ -654,52 +910,48 @@ typedef struct {
    void (*End)( void );
    void (*VertexAttrib4fNV)( GLuint index, GLfloat x, GLfloat y, GLfloat z, GLfloat w );
    void (*VertexAttrib4fvNV)( GLuint index, const GLfloat *v );
+   /*@}*/
 
-   /* Drivers present a reduced set of the functions possible in
-    * begin/end objects.  Core mesa provides translation stubs for the
-    * remaining functions to map down to these entrypoints.
-    *
-    * These are the initial values to be installed into dispatch by
-    * mesa.  If the t&l driver wants to modify the dispatch table
-    * while installed, it must do so itself.  It would be possible for
-    * the vertexformat to install it's own initial values for these
-    * functions, but this way there is an obvious list of what is
-    * expected of the driver.
-    *
-    * If the driver wants to hook in entrypoints other than those
-    * listed above, it must restore them to their original values in
-    * the disable() callback, below.
-    */
-
-   void (*Rectf)( GLfloat, GLfloat, GLfloat, GLfloat );
    /*
     */
+   void (*Rectf)( GLfloat, GLfloat, GLfloat, GLfloat );
 
+   /**
+    * \name Array
+    *
+    * These may or may not belong here.  Heuristic: if an array is
+    * enabled, the installed vertex format should support that array and
+    * its current size natively.
+    */
+   /*@{*/
    void (*DrawArrays)( GLenum mode, GLint start, GLsizei count );
    void (*DrawElements)( GLenum mode, GLsizei count, GLenum type,
 			 const GLvoid *indices );
    void (*DrawRangeElements)( GLenum mode, GLuint start,
 			      GLuint end, GLsizei count,
 			      GLenum type, const GLvoid *indices );
-   /* These may or may not belong here.  Heuristic: If an array is
-    * enabled, the installed vertex format should support that array and
-    * it's current size natively.
-    */
+   /*@}*/
 
-   void (*EvalMesh1)( GLenum mode, GLint i1, GLint i2 );
-   void (*EvalMesh2)( GLenum mode, GLint i1, GLint i2, GLint j1, GLint j2 );
-   /* If you don't support eval, fallback to the default vertex format
+   /**
+    * \name Eval
+    *
+    * If you don't support eval, fallback to the default vertex format
     * on receiving an eval call and use the pipeline mechanism to
-    * provide partial t&l acceleration.
+    * provide partial T&L acceleration.
     *
     * Mesa will provide a set of helper functions to do eval within
     * accelerated vertex formats, eventually...
     */
+   /*@{*/
+   void (*EvalMesh1)( GLenum mode, GLint i1, GLint i2 );
+   void (*EvalMesh2)( GLenum mode, GLint i1, GLint i2, GLint j1, GLint j2 );
+   /*@}*/
 
-   GLboolean prefer_float_colors;
-   /* Should core try to send colors to glColor4f or glColor4chan,
+   /**
+    * Should core try to send colors to glColor4f or glColor4chan,
     * where it has a choice?
     */
+   GLboolean prefer_float_colors;
 } GLvertexformat;
 
 
diff --git a/src/mesa/main/debug.c b/src/mesa/main/debug.c
index 7cd30f30bb..c9bf7ce068 100644
--- a/src/mesa/main/debug.c
+++ b/src/mesa/main/debug.c
@@ -27,7 +27,26 @@
 #include "context.h"
 #include "imports.h"
 #include "debug.h"
+#include "get.h"
 
+/**
+ * Primitive names
+ */
+const char *_mesa_prim_name[GL_POLYGON+4] = {
+   "GL_POINTS",
+   "GL_LINES",
+   "GL_LINE_LOOP",
+   "GL_LINE_STRIP",
+   "GL_TRIANGLES",
+   "GL_TRIANGLE_STRIP",
+   "GL_TRIANGLE_FAN",
+   "GL_QUADS",
+   "GL_QUAD_STRIP",
+   "GL_POLYGON",
+   "outside begin/end",
+   "inside unkown primitive",
+   "unknown state"
+};
 
 void
 _mesa_print_state( const char *msg, GLuint state )
@@ -87,3 +106,147 @@ _mesa_print_tri_caps( const char *name, GLuint flags )
 	   (flags & DD_TRI_CULL_FRONT_BACK) ? "cull-all, " : ""
       );
 }
+
+
+void
+_mesa_check_driver_hooks( GLcontext *ctx )
+{
+   ASSERT(ctx->Driver.GetString);
+   ASSERT(ctx->Driver.UpdateState);
+   ASSERT(ctx->Driver.Clear);
+   ASSERT(ctx->Driver.GetBufferSize);
+   if (ctx->Visual.accumRedBits > 0) {
+      ASSERT(ctx->Driver.Accum);
+   }
+   ASSERT(ctx->Driver.DrawPixels);
+   ASSERT(ctx->Driver.ReadPixels);
+   ASSERT(ctx->Driver.CopyPixels);
+   ASSERT(ctx->Driver.Bitmap);
+   ASSERT(ctx->Driver.ResizeBuffers);
+   ASSERT(ctx->Driver.TexImage1D);
+   ASSERT(ctx->Driver.TexImage2D);
+   ASSERT(ctx->Driver.TexImage3D);
+   ASSERT(ctx->Driver.TexSubImage1D);
+   ASSERT(ctx->Driver.TexSubImage2D);
+   ASSERT(ctx->Driver.TexSubImage3D);
+   ASSERT(ctx->Driver.CopyTexImage1D);
+   ASSERT(ctx->Driver.CopyTexImage2D);
+   ASSERT(ctx->Driver.CopyTexSubImage1D);
+   ASSERT(ctx->Driver.CopyTexSubImage2D);
+   ASSERT(ctx->Driver.CopyTexSubImage3D);
+   if (ctx->Extensions.ARB_texture_compression) {
+#if 0  /* HW drivers need these, but not SW rasterizers */
+      ASSERT(ctx->Driver.CompressedTexImage1D);
+      ASSERT(ctx->Driver.CompressedTexImage2D);
+      ASSERT(ctx->Driver.CompressedTexImage3D);
+      ASSERT(ctx->Driver.CompressedTexSubImage1D);
+      ASSERT(ctx->Driver.CompressedTexSubImage2D);
+      ASSERT(ctx->Driver.CompressedTexSubImage3D);
+#endif
+   }
+}
+
+/**
+ * Print information about this Mesa version and build options.
+ */
+void _mesa_print_info( void )
+{
+   _mesa_debug(NULL, "Mesa GL_VERSION = %s\n",
+	   (char *) _mesa_GetString(GL_VERSION));
+   _mesa_debug(NULL, "Mesa GL_RENDERER = %s\n",
+	   (char *) _mesa_GetString(GL_RENDERER));
+   _mesa_debug(NULL, "Mesa GL_VENDOR = %s\n",
+	   (char *) _mesa_GetString(GL_VENDOR));
+   _mesa_debug(NULL, "Mesa GL_EXTENSIONS = %s\n",
+	   (char *) _mesa_GetString(GL_EXTENSIONS));
+#if defined(THREADS)
+   _mesa_debug(NULL, "Mesa thread-safe: YES\n");
+#else
+   _mesa_debug(NULL, "Mesa thread-safe: NO\n");
+#endif
+#if defined(USE_X86_ASM)
+   _mesa_debug(NULL, "Mesa x86-optimized: YES\n");
+#else
+   _mesa_debug(NULL, "Mesa x86-optimized: NO\n");
+#endif
+#if defined(USE_SPARC_ASM)
+   _mesa_debug(NULL, "Mesa sparc-optimized: YES\n");
+#else
+   _mesa_debug(NULL, "Mesa sparc-optimized: NO\n");
+#endif
+}
+
+
+/**
+ * Set the debugging flags.
+ *
+ * \param debug debug string
+ *
+ * If compiled with debugging support then search for keywords in \p debug and
+ * enables the verbose debug output of the respective feature.
+ */
+static void add_debug_flags( const char *debug )
+{
+#ifdef MESA_DEBUG
+   if (_mesa_strstr(debug, "varray")) 
+      MESA_VERBOSE |= VERBOSE_VARRAY;
+
+   if (_mesa_strstr(debug, "tex")) 
+      MESA_VERBOSE |= VERBOSE_TEXTURE;
+
+   if (_mesa_strstr(debug, "imm")) 
+      MESA_VERBOSE |= VERBOSE_IMMEDIATE;
+
+   if (_mesa_strstr(debug, "pipe")) 
+      MESA_VERBOSE |= VERBOSE_PIPELINE;
+
+   if (_mesa_strstr(debug, "driver")) 
+      MESA_VERBOSE |= VERBOSE_DRIVER;
+
+   if (_mesa_strstr(debug, "state")) 
+      MESA_VERBOSE |= VERBOSE_STATE;
+
+   if (_mesa_strstr(debug, "api")) 
+      MESA_VERBOSE |= VERBOSE_API;
+
+   if (_mesa_strstr(debug, "list")) 
+      MESA_VERBOSE |= VERBOSE_DISPLAY_LIST;
+
+   if (_mesa_strstr(debug, "lighting")) 
+      MESA_VERBOSE |= VERBOSE_LIGHTING;
+   
+   /* Debug flag:
+    */
+   if (_mesa_strstr(debug, "flush")) 
+      MESA_DEBUG_FLAGS |= DEBUG_ALWAYS_FLUSH;
+#endif
+}
+
+
+void 
+_mesa_init_debug( GLcontext *ctx )
+{
+   char *c;
+
+   /* For debug/development only */
+   ctx->NoRaster = _mesa_getenv("MESA_NO_RASTER") ? GL_TRUE : GL_FALSE;
+   ctx->FirstTimeCurrent = GL_TRUE;
+
+   /* Dither disable */
+   ctx->NoDither = _mesa_getenv("MESA_NO_DITHER") ? GL_TRUE : GL_FALSE;
+   if (ctx->NoDither) {
+      if (_mesa_getenv("MESA_DEBUG")) {
+         _mesa_debug(ctx, "MESA_NO_DITHER set - dithering disabled\n");
+      }
+      ctx->Color.DitherFlag = GL_FALSE;
+   }
+
+   c = _mesa_getenv("MESA_DEBUG");
+   if (c)
+      add_debug_flags(c);
+
+   c = _mesa_getenv("MESA_VERBOSE");
+   if (c)
+      add_debug_flags(c);
+}
+
diff --git a/src/mesa/main/debug.h b/src/mesa/main/debug.h
index 6b45c03368..4d17771ce5 100644
--- a/src/mesa/main/debug.h
+++ b/src/mesa/main/debug.h
@@ -1,3 +1,12 @@
+/**
+ * \file debug.h
+ * Debugging functions.
+ * 
+ * \if subset
+ * (No-op)
+ *
+ * \endif
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -23,11 +32,33 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
 #ifndef _DEBUG_H
 #define _DEBUG_H
 
-void _mesa_print_tri_caps( const char *name, GLuint flags );
-void _mesa_print_enable_flags( const char *msg, GLuint flags );
-void _mesa_print_state( const char *msg, GLuint state );
+#if _HAVE_FULL_GL
+
+extern void _mesa_print_tri_caps( const char *name, GLuint flags );
+extern void _mesa_print_enable_flags( const char *msg, GLuint flags );
+extern void _mesa_print_state( const char *msg, GLuint state );
+extern void _mesa_print_info( void );
+extern void _mesa_init_debug( GLcontext *ctx );
+extern void _mesa_check_driver_hooks( GLcontext *ctx );
+
+#else
+
+/** No-op */
+#define _mesa_print_state( m, s ) ((void)0)
+
+/** No-op */
+#define _mesa_print_info() ((void)0)
+
+/** No-op */
+#define _mesa_init_debug( c ) ((void)0)
+
+/** No-op */
+#define _mesa_check_driver_hooks( c ) ((void)0)
+
+#endif
 
 #endif
diff --git a/src/mesa/main/depth.c b/src/mesa/main/depth.c
index 9d95500fca..fa7eb63b06 100644
--- a/src/mesa/main/depth.c
+++ b/src/mesa/main/depth.c
@@ -140,3 +140,45 @@ _mesa_DepthBoundsEXT( GLclampd zmin, GLclampd zmax )
    ctx->Depth.BoundsMax = zmax;
 }
 
+
+/**********************************************************************/
+/*****                      Initialization                        *****/
+/**********************************************************************/
+
+void _mesa_init_depth( GLcontext * ctx )
+{
+   /* Depth buffer group */
+   ctx->Depth.Test = GL_FALSE;
+   ctx->Depth.Clear = 1.0;
+   ctx->Depth.Func = GL_LESS;
+   ctx->Depth.Mask = GL_TRUE;
+   ctx->Depth.OcclusionTest = GL_FALSE;
+
+   /* Z buffer stuff */
+   if (ctx->Visual.depthBits == 0) {
+      /* Special case.  Even if we don't have a depth buffer we need
+       * good values for DepthMax for Z vertex transformation purposes
+       * and for per-fragment fog computation.
+       */
+      ctx->DepthMax = 1 << 16;
+      ctx->DepthMaxF = (GLfloat) ctx->DepthMax;
+   }
+   else if (ctx->Visual.depthBits < 32) {
+      ctx->DepthMax = (1 << ctx->Visual.depthBits) - 1;
+      ctx->DepthMaxF = (GLfloat) ctx->DepthMax;
+   }
+   else {
+      /* Special case since shift values greater than or equal to the
+       * number of bits in the left hand expression's type are undefined.
+       */
+      ctx->DepthMax = 0xffffffff;
+      ctx->DepthMaxF = (GLfloat) ctx->DepthMax;
+   }
+   ctx->MRD = 1.0;  /* Minimum resolvable depth value, for polygon offset */
+
+#if FEATURE_ARB_occlusion_query
+   ctx->Occlusion.QueryObjects = _mesa_NewHashTable();
+#endif
+   ctx->OcclusionResult = GL_FALSE;
+   ctx->OcclusionResultSaved = GL_FALSE;
+}
diff --git a/src/mesa/main/depth.h b/src/mesa/main/depth.h
index b90d723b38..ce5f28e84d 100644
--- a/src/mesa/main/depth.h
+++ b/src/mesa/main/depth.h
@@ -1,3 +1,8 @@
+/**
+ * \file depth.h
+ * Depth buffer operations.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -30,24 +35,28 @@
 #include "mtypes.h"
 
 
-/*
- * Immediate-mode API entrpoints
- */
+#if _HAVE_FULL_GL
 
 extern void
 _mesa_ClearDepth( GLclampd depth );
 
-
 extern void
 _mesa_DepthFunc( GLenum func );
 
-
 extern void
 _mesa_DepthMask( GLboolean flag );
 
+extern void 
+_mesa_init_depth( GLcontext * ctx );
 
 extern void
 _mesa_DepthBoundsEXT( GLclampd zmin, GLclampd zmax );
 
+#else
+
+/** No-op */
+#define _mesa_init_depth( c ) ((void)0)
+
+#endif
 
 #endif
diff --git a/src/mesa/main/dlist.c b/src/mesa/main/dlist.c
index 8513b45801..928b74cb54 100644
--- a/src/mesa/main/dlist.c
+++ b/src/mesa/main/dlist.c
@@ -1,3 +1,8 @@
+/**
+ * \file dlist.c
+ * Display lists management functions.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -22,6 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
 #include "glheader.h"
 #include "imports.h"
 #include "api_loopback.h"
@@ -72,47 +78,48 @@
 
 
 
-/*
-Functions which aren't compiled but executed immediately:
-	glIsList
-	glGenLists
-	glDeleteLists
-	glEndList  --- BUT:  call ctx->Driver.EndList at end of list execution?
-	glFeedbackBuffer
-	glSelectBuffer
-	glRenderMode
-	glReadPixels
-	glPixelStore
-	glFlush
-	glFinish
-	glIsEnabled
-	glGet*
-
-Functions which cause errors if called while compiling a display list:
-	glNewList
-*/
+/**
+ * Functions which aren't compiled but executed immediately:
+ * - glIsList
+ * - glGenLists
+ * - glDeleteLists
+ * - glEndList  --- BUT:  call ctx->Driver.EndList at end of list execution?
+ * - glFeedbackBuffer
+ * - glSelectBuffer
+ * - glRenderMode
+ * - glReadPixels
+ * - glPixelStore
+ * - glFlush
+ * - glFinish
+ * - glIsEnabled
+ * - glGet*
+ * 
+ * Functions which cause errors if called while compiling a display list:
+ *  - glNewList
+ */
 
 
 
-/*
+/**
  * Display list instructions are stored as sequences of "nodes".  Nodes
  * are allocated in blocks.  Each block has BLOCK_SIZE nodes.  Blocks
  * are linked together with a pointer.
  */
 
 
-/* How many nodes to allocate at a time:
- * - reduced now that we hold vertices etc. elsewhere.
+/**
+ * How many nodes to allocate at a time.
+ * 
+ * \note Reduced now that we hold vertices etc. elsewhere.
  */
 #define BLOCK_SIZE 256
 
 
-/*
+/**
  * Display list opcodes.
  *
  * The fact that these identifiers are assigned consecutive
  * integer values starting at 0 is very important, see InstSize array usage)
- *
  */
 typedef enum {
 	OPCODE_ACCUM,
@@ -265,10 +272,12 @@ typedef enum {
 } OpCode;
 
 
-/*
+/**
+ * Display list node.
+ *
  * Each instruction in the display list is stored as a sequence of
  * contiguous nodes in memory.
- * Each node is the union of a variety of datatypes.
+ * Each node is the union of a variety of data types.
  */
 union node {
 	OpCode		opcode;
@@ -286,9 +295,9 @@ union node {
 };
 
 
-
-/* Number of nodes of storage needed for each instruction.  Sizes for
- * dynamically allocated opcodes are stored in the context struct.
+/**
+ * Number of nodes of storage needed for each instruction.  
+ * Sizes for dynamically allocated opcodes are stored in the context struct.
  */
 static GLuint InstSize[ OPCODE_END_OF_LIST+1 ];
 
@@ -299,10 +308,6 @@ void mesa_print_display_list( GLuint list );
 /*****                           Private                          *****/
 /**********************************************************************/
 
-
-
-
-
 /*
  * Make an empty display list.  This is used by glGenLists() to
  * reserver display list IDs.
@@ -318,7 +323,7 @@ static Node *make_empty_list( void )
 
 /*
  * Destroy all nodes in a display list.
- * Input:  list - display list number
+ * \param list - display list number
  */
 void _mesa_destroy_list( GLcontext *ctx, GLuint list )
 {
@@ -682,9 +687,9 @@ void _mesa_init_lists( void )
 
 /*
  * Allocate space for a display list instruction.
- * Input:  opcode - type of instruction
+ * \param opcode - type of instruction
  *         argcount - size in bytes of data required.
- * Return: pointer to the usable data area (not including the internal
+ * \return pointer to the usable data area (not including the internal
  *         opcode).
  */
 void *
@@ -4444,7 +4449,7 @@ islist(GLcontext *ctx, GLuint list)
  * Execute a display list.  Note that the ListBase offset must have already
  * been added before calling this function.  I.e. the list argument is
  * the absolute list number, not relative to ListBase.
- * Input:  list - display list number
+ * \param list - display list number
  */
 static void
 execute_list( GLcontext *ctx, GLuint list )
@@ -4515,7 +4520,7 @@ execute_list( GLcontext *ctx, GLuint list )
          case OPCODE_CALL_LIST_OFFSET:
 	    /* Generated by glCallLists() so we must add ListBase */
             if (n[2].b) {
-               /* user specified a bad datatype at compile time */
+               /* user specified a bad data type at compile time */
                _mesa_error(ctx, GL_INVALID_ENUM, "glCallLists(type)");
             }
             else if (ctx->CallDepth < MAX_LIST_NESTING) {
@@ -6785,3 +6790,24 @@ void mesa_print_display_list( GLuint list )
    GET_CURRENT_CONTEXT(ctx);
    print_list( ctx, list );
 }
+
+
+/**********************************************************************/
+/*****                      Initialization                        *****/
+/**********************************************************************/
+
+void _mesa_init_display_list( GLcontext * ctx )
+{
+   /* Display list */
+   ctx->CallDepth = 0;
+   ctx->ExecuteFlag = GL_TRUE;
+   ctx->CompileFlag = GL_FALSE;
+   ctx->CurrentListPtr = NULL;
+   ctx->CurrentBlock = NULL;
+   ctx->CurrentListNum = 0;
+   ctx->CurrentPos = 0;
+
+   /* Display List group */
+   ctx->List.ListBase = 0;
+
+}
diff --git a/src/mesa/main/dlist.h b/src/mesa/main/dlist.h
index 9880aa0793..b8d115cd82 100644
--- a/src/mesa/main/dlist.h
+++ b/src/mesa/main/dlist.h
@@ -1,3 +1,7 @@
+/**
+ * \file dlist.h
+ * Display lists management.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,6 +28,7 @@
  */
 
 
+
 #ifndef DLIST_H
 #define DLIST_H
 
@@ -31,6 +36,13 @@
 #include "mtypes.h"
 
 
+/**
+ * Macro to assert that the API call was made outside the
+ * glBegin()/glEnd() pair, with return value.
+ * 
+ * \param ctx GL context.
+ * \param retval value to return value in case the assertion fails.
+ */
 #define ASSERT_OUTSIDE_SAVE_BEGIN_END_WITH_RETVAL(ctx, retval)		\
 do {									\
    if (ctx->Driver.CurrentSavePrimitive <= GL_POLYGON ||		\
@@ -40,6 +52,12 @@ do {									\
    }									\
 } while (0)
 
+/**
+ * Macro to assert that the API call was made outside the
+ * glBegin()/glEnd() pair.
+ * 
+ * \param ctx GL context.
+ */
 #define ASSERT_OUTSIDE_SAVE_BEGIN_END(ctx)				\
 do {									\
    if (ctx->Driver.CurrentSavePrimitive <= GL_POLYGON ||		\
@@ -49,12 +67,25 @@ do {									\
    }									\
 } while (0)
 
+/**
+ * Macro to assert that the API call was made outside the
+ * glBegin()/glEnd() pair and flush the vertices.
+ * 
+ * \param ctx GL context.
+ */
 #define ASSERT_OUTSIDE_SAVE_BEGIN_END_AND_FLUSH(ctx)			\
 do {									\
    ASSERT_OUTSIDE_SAVE_BEGIN_END(ctx);					\
    FLUSH_VERTICES(ctx, 0);						\
 } while (0)
 
+/**
+ * Macro to assert that the API call was made outside the
+ * glBegin()/glEnd() pair and flush the vertices, with return value.
+ * 
+ * \param ctx GL context.
+ * \param retval value to return value in case the assertion fails.
+ */
 #define ASSERT_OUTSIDE_SAVE_BEGIN_END_AND_FLUSH_WITH_RETVAL(ctx, retval)\
 do {									\
    ASSERT_OUTSIDE_SAVE_BEGIN_END_WITH_RETVAL(ctx, retval);		\
@@ -62,6 +93,8 @@ do {									\
 } while (0)
 
 
+#if _HAVE_FULL_GL
+
 extern void _mesa_init_lists( void );
 
 extern void _mesa_destroy_list( GLcontext *ctx, GLuint list );
@@ -102,7 +135,22 @@ extern void _mesa_save_EvalMesh2(GLenum mode, GLint i1, GLint i2,
 extern void _mesa_save_EvalMesh1( GLenum mode, GLint i1, GLint i2 );
 extern void _mesa_save_CallLists( GLsizei n, GLenum type, const GLvoid *lists );
 extern void _mesa_save_CallList( GLuint list );
+extern void _mesa_init_display_list( GLcontext * ctx );
+
+#else
+
+/** No-op */
+#define _mesa_init_lists() ((void)0)
 
+/** No-op */
+#define _mesa_destroy_list(c,l) ((void)0)
 
+/** No-op */
+#define _mesa_init_dlist_table(t,ts) ((void)0)
+
+/** No-op */
+#define _mesa_init_display_list(c) ((void)0)
+
+#endif
 
 #endif
diff --git a/src/mesa/main/drawpix.c b/src/mesa/main/drawpix.c
index 4597cd0916..83196d3de0 100644
--- a/src/mesa/main/drawpix.c
+++ b/src/mesa/main/drawpix.c
@@ -33,6 +33,7 @@
 #include "state.h"
 #include "mtypes.h"
 
+#if _HAVE_FULL_GL
 
 /*
  * Execute glDrawPixels
@@ -86,35 +87,6 @@ _mesa_DrawPixels( GLsizei width, GLsizei height,
    }
 }
 
-
-
-void
-_mesa_ReadPixels( GLint x, GLint y, GLsizei width, GLsizei height,
-		  GLenum format, GLenum type, GLvoid *pixels )
-{
-   GET_CURRENT_CONTEXT(ctx);
-   ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH(ctx);
-
-   if (width < 0 || height < 0) {
-      _mesa_error( ctx, GL_INVALID_VALUE,
-                   "glReadPixels(width=%d height=%d)", width, height );
-      return;
-   }
-
-   if (!pixels) {
-      _mesa_error( ctx, GL_INVALID_VALUE, "glReadPixels(pixels)" );
-      return;
-   }
-
-   if (ctx->NewState)
-      _mesa_update_state(ctx);
-
-   ctx->Driver.ReadPixels(ctx, x, y, width, height,
-			  format, type, &ctx->Pack, pixels);
-}
-
-
-
 void
 _mesa_CopyPixels( GLint srcx, GLint srcy, GLsizei width, GLsizei height,
                   GLenum type )
@@ -163,6 +135,37 @@ _mesa_CopyPixels( GLint srcx, GLint srcy, GLsizei width, GLsizei height,
    }
 }
 
+#endif
+
+
+
+void
+_mesa_ReadPixels( GLint x, GLint y, GLsizei width, GLsizei height,
+		  GLenum format, GLenum type, GLvoid *pixels )
+{
+   GET_CURRENT_CONTEXT(ctx);
+   ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH(ctx);
+
+   if (width < 0 || height < 0) {
+      _mesa_error( ctx, GL_INVALID_VALUE,
+                   "glReadPixels(width=%d height=%d)", width, height );
+      return;
+   }
+
+   if (!pixels) {
+      _mesa_error( ctx, GL_INVALID_VALUE, "glReadPixels(pixels)" );
+      return;
+   }
+
+   if (ctx->NewState)
+      _mesa_update_state(ctx);
+
+   ctx->Driver.ReadPixels(ctx, x, y, width, height,
+			  format, type, &ctx->Pack, pixels);
+}
+
+
+
 
 
 void
@@ -196,6 +199,7 @@ _mesa_Bitmap( GLsizei width, GLsizei height,
 	 ctx->Driver.Bitmap( ctx, x, y, width, height, &ctx->Unpack, bitmap );
       }
    }
+#if _HAVE_FULL_GL
    else if (ctx->RenderMode==GL_FEEDBACK) {
       if (ctx->Current.RasterPosValid) {
 	 FLUSH_CURRENT(ctx, 0);
@@ -210,6 +214,7 @@ _mesa_Bitmap( GLsizei width, GLsizei height,
    else if (ctx->RenderMode==GL_SELECT) {
       /* Bitmaps don't generate selection hits.  See appendix B of 1.1 spec. */
    }
+#endif
 
    /* update raster position */
    ctx->Current.RasterPos[0] += xmove;
diff --git a/src/mesa/main/enable.c b/src/mesa/main/enable.c
index 747c3f63c1..de08fa3513 100644
--- a/src/mesa/main/enable.c
+++ b/src/mesa/main/enable.c
@@ -1,3 +1,8 @@
+/**
+ * \file enable.c
+ * Enable/disable/query GL capabilities.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -135,7 +140,16 @@ client_state( GLcontext *ctx, GLenum cap, GLboolean state )
 }
 
 
-
+/**
+ * Enable GL capability.
+ *
+ * \param cap capability.
+ *
+ * \sa glEnable().
+ *
+ * Get's the current context, assures that we're outside glBegin()/glEnd() and
+ * calls client_state().
+ */
 void
 _mesa_EnableClientState( GLenum cap )
 {
@@ -145,7 +159,16 @@ _mesa_EnableClientState( GLenum cap )
 }
 
 
-
+/**
+ * Disable GL capability.
+ *
+ * \param cap capability.
+ *
+ * \sa glDisable().
+ *
+ * Get's the current context, assures that we're outside glBegin()/glEnd() and
+ * calls client_state().
+ */
 void
 _mesa_DisableClientState( GLenum cap )
 {
@@ -164,8 +187,17 @@ _mesa_DisableClientState( GLenum cap )
    }
 
 
-/*
- * Perform glEnable and glDisable calls.
+/**
+ * Perform glEnable() and glDisable() calls.
+ *
+ * \param ctx GL context.
+ * \param cap capability.
+ * \param state whether to enable or disable the specified capability.
+ *
+ * Updates the current context and flushes the vertices as needed. For
+ * capabilities associated with extensions it verifies that those extensions
+ * are effectivly present before updating. Notifies the driver via
+ * dd_function_table::Enable.
  */
 void _mesa_set_enable( GLcontext *ctx, GLenum cap, GLboolean state )
 {
@@ -197,6 +229,7 @@ void _mesa_set_enable( GLcontext *ctx, GLenum cap, GLboolean state )
          ctx->Color.ColorLogicOpEnabled =
             (ctx->Color.BlendEquation == GL_LOGIC_OP && state);
          break;
+#if FEATURE_userclip
       case GL_CLIP_PLANE0:
       case GL_CLIP_PLANE1:
       case GL_CLIP_PLANE2:
@@ -230,6 +263,7 @@ void _mesa_set_enable( GLcontext *ctx, GLenum cap, GLboolean state )
             }               
          }
          break;
+#endif
       case GL_COLOR_MATERIAL:
          if (ctx->Light.ColorMaterialEnabled == state)
             return;
@@ -949,6 +983,16 @@ void _mesa_set_enable( GLcontext *ctx, GLenum cap, GLboolean state )
 }
 
 
+/**
+ * Enable GL capability.
+ *
+ * \param cap capability.
+ *
+ * \sa glEnable().
+ *
+ * Get's the current context, assures that we're outside glBegin()/glEnd() and
+ * calls _mesa_set_enable().
+ */
 void
 _mesa_Enable( GLenum cap )
 {
@@ -959,6 +1003,16 @@ _mesa_Enable( GLenum cap )
 }
 
 
+/**
+ * Disable GL capability.
+ *
+ * \param cap capability.
+ *
+ * \sa glDisable().
+ *
+ * Get's the current context, assures that we're outside glBegin()/glEnd() and
+ * calls _mesa_set_enable().
+ */
 void
 _mesa_Disable( GLenum cap )
 {
@@ -977,6 +1031,15 @@ _mesa_Disable( GLenum cap )
    }
 
 
+/**
+ * Test whether a capability is enabled.
+ *
+ * \param cap capability.
+ *
+ * Returns the state of the specified capability from the current GL context.
+ * For the capabilities associated with extensions verifies that those
+ * extensions are effectively present before reporting.
+ */
 GLboolean
 _mesa_IsEnabled( GLenum cap )
 {
diff --git a/src/mesa/main/enable.h b/src/mesa/main/enable.h
index bf71f1773f..eeafb2dddd 100644
--- a/src/mesa/main/enable.h
+++ b/src/mesa/main/enable.h
@@ -1,3 +1,7 @@
+/**
+ * \file enable.h
+ * Enable/disable/query GL capabilities.
+ */
 
 /*
  * Mesa 3-D graphics library
diff --git a/src/mesa/main/enums.h b/src/mesa/main/enums.h
index ff59233296..1e7b86e3a0 100644
--- a/src/mesa/main/enums.h
+++ b/src/mesa/main/enums.h
@@ -1,3 +1,12 @@
+/**
+ * \file enums.h
+ * Enumeration name/number lookup functions.
+ * 
+ * \if subset
+ * (No-op)
+ *
+ * \endif
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -27,7 +36,20 @@
 #ifndef _ENUMS_H_
 #define _ENUMS_H_
 
+
+#if _HAVE_FULL_GL
+
 extern const char *_mesa_lookup_enum_by_nr( int nr );
 extern int _mesa_lookup_enum_by_name( const char *symbol );
 
+#else
+
+/** No-op */
+#define _mesa_lookup_enum_by_name( s ) 0
+
+/** No-op */
+#define _mesa_lookup_enum_by_nr( n ) "unknown"
+
+#endif
+
 #endif
diff --git a/src/mesa/main/eval.c b/src/mesa/main/eval.c
index 03d779e894..314ecf0491 100644
--- a/src/mesa/main/eval.c
+++ b/src/mesa/main/eval.c
@@ -200,8 +200,8 @@ get_2d_map( GLcontext *ctx, GLenum target )
 /*
  * Copy 1-parametric evaluator control points from user-specified
  * memory space to a buffer of contiguous control points.
- * Input:  see glMap1f for details
- * Return:  pointer to buffer of contiguous control points or NULL if out
+ * \param see glMap1f for details
+ * \return pointer to buffer of contiguous control points or NULL if out
  *          of memory.
  */
 GLfloat *_mesa_copy_map_points1f( GLenum target, GLint ustride, GLint uorder,
@@ -255,8 +255,8 @@ GLfloat *_mesa_copy_map_points1d( GLenum target, GLint ustride, GLint uorder,
  * Additional memory is allocated to be used by the horner and
  * de Casteljau evaluation schemes.
  *
- * Input:  see glMap2f for details
- * Return:  pointer to buffer of contiguous control points or NULL if out
+ * \param see glMap2f for details
+ * \return pointer to buffer of contiguous control points or NULL if out
  *          of memory.
  */
 GLfloat *_mesa_copy_map_points2f( GLenum target,
@@ -795,3 +795,168 @@ _mesa_MapGrid2d( GLint un, GLdouble u1, GLdouble u2,
    _mesa_MapGrid2f( un, (GLfloat) u1, (GLfloat) u2, 
 		    vn, (GLfloat) v1, (GLfloat) v2 );
 }
+
+
+
+/**********************************************************************/
+/*****                      Initialization                        *****/
+/**********************************************************************/
+
+/**
+ * Initialize a 1-D evaluator map.
+ */
+static void
+init_1d_map( struct gl_1d_map *map, int n, const float *initial )
+{
+   map->Order = 1;
+   map->u1 = 0.0;
+   map->u2 = 1.0;
+   map->Points = (GLfloat *) MALLOC(n * sizeof(GLfloat));
+   if (map->Points) {
+      GLint i;
+      for (i=0;i<n;i++)
+         map->Points[i] = initial[i];
+   }
+}
+
+
+/**
+ * Initialize a 2-D evaluator map 
+ */
+static void
+init_2d_map( struct gl_2d_map *map, int n, const float *initial )
+{
+   map->Uorder = 1;
+   map->Vorder = 1;
+   map->u1 = 0.0;
+   map->u2 = 1.0;
+   map->v1 = 0.0;
+   map->v2 = 1.0;
+   map->Points = (GLfloat *) MALLOC(n * sizeof(GLfloat));
+   if (map->Points) {
+      GLint i;
+      for (i=0;i<n;i++)
+         map->Points[i] = initial[i];
+   }
+}
+
+
+void _mesa_init_eval( GLcontext *ctx )
+{
+   int i;
+
+   /* Evaluators group */
+   ctx->Eval.Map1Color4 = GL_FALSE;
+   ctx->Eval.Map1Index = GL_FALSE;
+   ctx->Eval.Map1Normal = GL_FALSE;
+   ctx->Eval.Map1TextureCoord1 = GL_FALSE;
+   ctx->Eval.Map1TextureCoord2 = GL_FALSE;
+   ctx->Eval.Map1TextureCoord3 = GL_FALSE;
+   ctx->Eval.Map1TextureCoord4 = GL_FALSE;
+   ctx->Eval.Map1Vertex3 = GL_FALSE;
+   ctx->Eval.Map1Vertex4 = GL_FALSE;
+   MEMSET(ctx->Eval.Map1Attrib, 0, sizeof(ctx->Eval.Map1Attrib));
+   ctx->Eval.Map2Color4 = GL_FALSE;
+   ctx->Eval.Map2Index = GL_FALSE;
+   ctx->Eval.Map2Normal = GL_FALSE;
+   ctx->Eval.Map2TextureCoord1 = GL_FALSE;
+   ctx->Eval.Map2TextureCoord2 = GL_FALSE;
+   ctx->Eval.Map2TextureCoord3 = GL_FALSE;
+   ctx->Eval.Map2TextureCoord4 = GL_FALSE;
+   ctx->Eval.Map2Vertex3 = GL_FALSE;
+   ctx->Eval.Map2Vertex4 = GL_FALSE;
+   MEMSET(ctx->Eval.Map2Attrib, 0, sizeof(ctx->Eval.Map2Attrib));
+   ctx->Eval.AutoNormal = GL_FALSE;
+   ctx->Eval.MapGrid1un = 1;
+   ctx->Eval.MapGrid1u1 = 0.0;
+   ctx->Eval.MapGrid1u2 = 1.0;
+   ctx->Eval.MapGrid2un = 1;
+   ctx->Eval.MapGrid2vn = 1;
+   ctx->Eval.MapGrid2u1 = 0.0;
+   ctx->Eval.MapGrid2u2 = 1.0;
+   ctx->Eval.MapGrid2v1 = 0.0;
+   ctx->Eval.MapGrid2v2 = 1.0;
+
+   /* Evaluator data */
+   {
+      static GLfloat vertex[4] = { 0.0, 0.0, 0.0, 1.0 };
+      static GLfloat normal[3] = { 0.0, 0.0, 1.0 };
+      static GLfloat index[1] = { 1.0 };
+      static GLfloat color[4] = { 1.0, 1.0, 1.0, 1.0 };
+      static GLfloat texcoord[4] = { 0.0, 0.0, 0.0, 1.0 };
+      static GLfloat attrib[4] = { 0.0, 0.0, 0.0, 1.0 };
+
+      init_1d_map( &ctx->EvalMap.Map1Vertex3, 3, vertex );
+      init_1d_map( &ctx->EvalMap.Map1Vertex4, 4, vertex );
+      init_1d_map( &ctx->EvalMap.Map1Index, 1, index );
+      init_1d_map( &ctx->EvalMap.Map1Color4, 4, color );
+      init_1d_map( &ctx->EvalMap.Map1Normal, 3, normal );
+      init_1d_map( &ctx->EvalMap.Map1Texture1, 1, texcoord );
+      init_1d_map( &ctx->EvalMap.Map1Texture2, 2, texcoord );
+      init_1d_map( &ctx->EvalMap.Map1Texture3, 3, texcoord );
+      init_1d_map( &ctx->EvalMap.Map1Texture4, 4, texcoord );
+      for (i = 0; i < 16; i++)
+         init_1d_map( ctx->EvalMap.Map1Attrib + i, 4, attrib );
+
+      init_2d_map( &ctx->EvalMap.Map2Vertex3, 3, vertex );
+      init_2d_map( &ctx->EvalMap.Map2Vertex4, 4, vertex );
+      init_2d_map( &ctx->EvalMap.Map2Index, 1, index );
+      init_2d_map( &ctx->EvalMap.Map2Color4, 4, color );
+      init_2d_map( &ctx->EvalMap.Map2Normal, 3, normal );
+      init_2d_map( &ctx->EvalMap.Map2Texture1, 1, texcoord );
+      init_2d_map( &ctx->EvalMap.Map2Texture2, 2, texcoord );
+      init_2d_map( &ctx->EvalMap.Map2Texture3, 3, texcoord );
+      init_2d_map( &ctx->EvalMap.Map2Texture4, 4, texcoord );
+      for (i = 0; i < 16; i++)
+         init_2d_map( ctx->EvalMap.Map2Attrib + i, 4, attrib );
+   }
+}
+
+
+void _mesa_free_eval_data( GLcontext *ctx )
+{
+   int i;
+
+   /* Free evaluator data */
+   if (ctx->EvalMap.Map1Vertex3.Points)
+      FREE( ctx->EvalMap.Map1Vertex3.Points );
+   if (ctx->EvalMap.Map1Vertex4.Points)
+      FREE( ctx->EvalMap.Map1Vertex4.Points );
+   if (ctx->EvalMap.Map1Index.Points)
+      FREE( ctx->EvalMap.Map1Index.Points );
+   if (ctx->EvalMap.Map1Color4.Points)
+      FREE( ctx->EvalMap.Map1Color4.Points );
+   if (ctx->EvalMap.Map1Normal.Points)
+      FREE( ctx->EvalMap.Map1Normal.Points );
+   if (ctx->EvalMap.Map1Texture1.Points)
+      FREE( ctx->EvalMap.Map1Texture1.Points );
+   if (ctx->EvalMap.Map1Texture2.Points)
+      FREE( ctx->EvalMap.Map1Texture2.Points );
+   if (ctx->EvalMap.Map1Texture3.Points)
+      FREE( ctx->EvalMap.Map1Texture3.Points );
+   if (ctx->EvalMap.Map1Texture4.Points)
+      FREE( ctx->EvalMap.Map1Texture4.Points );
+   for (i = 0; i < 16; i++)
+      FREE((ctx->EvalMap.Map1Attrib[i].Points));
+
+   if (ctx->EvalMap.Map2Vertex3.Points)
+      FREE( ctx->EvalMap.Map2Vertex3.Points );
+   if (ctx->EvalMap.Map2Vertex4.Points)
+      FREE( ctx->EvalMap.Map2Vertex4.Points );
+   if (ctx->EvalMap.Map2Index.Points)
+      FREE( ctx->EvalMap.Map2Index.Points );
+   if (ctx->EvalMap.Map2Color4.Points)
+      FREE( ctx->EvalMap.Map2Color4.Points );
+   if (ctx->EvalMap.Map2Normal.Points)
+      FREE( ctx->EvalMap.Map2Normal.Points );
+   if (ctx->EvalMap.Map2Texture1.Points)
+      FREE( ctx->EvalMap.Map2Texture1.Points );
+   if (ctx->EvalMap.Map2Texture2.Points)
+      FREE( ctx->EvalMap.Map2Texture2.Points );
+   if (ctx->EvalMap.Map2Texture3.Points)
+      FREE( ctx->EvalMap.Map2Texture3.Points );
+   if (ctx->EvalMap.Map2Texture4.Points)
+      FREE( ctx->EvalMap.Map2Texture4.Points );
+   for (i = 0; i < 16; i++)
+      FREE((ctx->EvalMap.Map2Attrib[i].Points));
+}
diff --git a/src/mesa/main/eval.h b/src/mesa/main/eval.h
index 2e4f5227e4..525835c7d5 100644
--- a/src/mesa/main/eval.h
+++ b/src/mesa/main/eval.h
@@ -1,3 +1,12 @@
+/**
+ * \file eval.h
+ * Eval operations.
+ * 
+ * \if subset
+ * (No-op)
+ *
+ * \endif
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -30,8 +39,10 @@
 
 #include "mtypes.h"
 
+#if _HAVE_FULL_GL
 
-extern void _mesa_init_eval( void );
+extern void _mesa_init_eval( GLcontext *ctx );
+extern void _mesa_free_eval_data( GLcontext *ctx );
 
 
 extern GLuint _mesa_evaluator_components( GLenum target );
@@ -104,5 +115,14 @@ _mesa_GetMapfv( GLenum target, GLenum query, GLfloat *v );
 extern void
 _mesa_GetMapiv( GLenum target, GLenum query, GLint *v );
 
+#else
+
+/** No-op */
+#define _mesa_init_eval( c ) ((void)0)
+
+/** No-op */
+#define _mesa_free_eval_data( c ) ((void)0)
+
+#endif
 
 #endif
diff --git a/src/mesa/main/extensions.c b/src/mesa/main/extensions.c
index 75972c7559..db5c43e42d 100644
--- a/src/mesa/main/extensions.c
+++ b/src/mesa/main/extensions.c
@@ -22,6 +22,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
 #include "glheader.h"
 #include "imports.h"
 #include "context.h"
@@ -426,3 +427,10 @@ _mesa_make_extension_string( GLcontext *ctx )
 
    return s;
 }
+
+void 
+_mesa_extensions_dtr( GLcontext *ctx ) 
+{
+   if (ctx->Extensions.String)
+      FREE((void *) ctx->Extensions.String);
+}
diff --git a/src/mesa/main/extensions.h b/src/mesa/main/extensions.h
index 8be8689799..54aa25511b 100644
--- a/src/mesa/main/extensions.h
+++ b/src/mesa/main/extensions.h
@@ -1,3 +1,13 @@
+/**
+ * \file extensions.h
+ * Extension handling.
+ * 
+ * \if subset
+ * (No-op)
+ *
+ * \endif
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -28,6 +38,7 @@
 
 #include "mtypes.h"
 
+#if _HAVE_FULL_GL
 
 extern void _mesa_enable_sw_extensions(GLcontext *ctx);
 
@@ -49,4 +60,23 @@ extern void _mesa_init_extensions(GLcontext *ctx);
 
 extern GLubyte *_mesa_make_extension_string(GLcontext *ctx);
 
+#else
+
+/** No-op */
+#define _mesa_extensions_dtr( ctx ) ((void)0)
+
+/** No-op */
+#define _mesa_extensions_ctr( ctx ) ((void)0)
+
+/** No-op */
+#define _mesa_extensions_get_string( ctx ) "GL_EXT_texture_object"
+
+/** No-op */
+#define _mesa_enable_imaging_extensions( c ) ((void)0)
+
+/** No-op */
+#define _mesa_enable_extension( c, n ) ((void)0)
+
+#endif
+
 #endif
diff --git a/src/mesa/main/feedback.c b/src/mesa/main/feedback.c
index 53c43cf317..731fdf86bb 100644
--- a/src/mesa/main/feedback.c
+++ b/src/mesa/main/feedback.c
@@ -1,3 +1,7 @@
+/**
+ * \file feedback.c
+ * Selection and feedback modes functions.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -33,6 +37,8 @@
 #include "mtypes.h"
 
 
+#if _HAVE_FULL_GL
+
 
 #define FB_3D		0x01
 #define FB_4D		0x02
@@ -145,14 +151,25 @@ void _mesa_feedback_vertex( GLcontext *ctx,
    }
 }
 
-
-/**********************************************************************/
-/*                              Selection                             */
-/**********************************************************************/
+#endif
 
 
-/*
- * NOTE: this function can't be put in a display list.
+/**********************************************************************/
+/** \name Selection */
+/*@{*/
+
+/**
+ * Establish a buffer for selection mode values.
+ * 
+ * \param size buffer size.
+ * \param buffer buffer.
+ *
+ * \sa glSelectBuffer().
+ * 
+ * \note this function can't be put in a display list.
+ * 
+ * Verifies we're not in selection mode, flushes the vertices and initialize
+ * the fields in __GLcontextRec::Select with the given buffer.
  */
 void
 _mesa_SelectBuffer( GLsizei size, GLuint *buffer )
@@ -165,7 +182,7 @@ _mesa_SelectBuffer( GLsizei size, GLuint *buffer )
       return;			/* KW: added return */
    }
 
-   FLUSH_VERTICES(ctx, _NEW_RENDERMODE); /* why bother? */
+   FLUSH_VERTICES(ctx, _NEW_RENDERMODE); 
    ctx->Select.Buffer = buffer;
    ctx->Select.BufferSize = size;
    ctx->Select.BufferCount = 0;
@@ -175,6 +192,15 @@ _mesa_SelectBuffer( GLsizei size, GLuint *buffer )
 }
 
 
+/**
+ * Write a value of a record into the selection buffer.
+ * 
+ * \param CTX GL context.
+ * \param V value.
+ *
+ * Verifies there is free space in the buffer to write the value and
+ * increments the pointer.
+ */
 #define WRITE_RECORD( CTX, V )					\
 	if (CTX->Select.BufferCount < CTX->Select.BufferSize) {	\
 	   CTX->Select.Buffer[CTX->Select.BufferCount] = (V);	\
@@ -182,7 +208,15 @@ _mesa_SelectBuffer( GLsizei size, GLuint *buffer )
 	CTX->Select.BufferCount++;
 
 
-
+/**
+ * Update the hit flag and the maximum and minimum depth values.
+ *
+ * \param ctx GL context.
+ * \param z depth.
+ *
+ * Sets gl_selection::HitFlag and updates gl_selection::HitMinZ and
+ * gl_selection::HitMaxZ.
+ */
 void _mesa_update_hitflag( GLcontext *ctx, GLfloat z )
 {
    ctx->Select.HitFlag = GL_TRUE;
@@ -195,6 +229,17 @@ void _mesa_update_hitflag( GLcontext *ctx, GLfloat z )
 }
 
 
+/**
+ * Write the hit record.
+ *
+ * \param ctx GL context.
+ *
+ * Write the hit record, i.e., the number of names in the stack, the minimum and
+ * maximum depth values and the number of names in the name stack at the time
+ * of the event. Resets the hit flag. 
+ *
+ * \sa gl_selection.
+ */
 static void write_hit_record( GLcontext *ctx )
 {
    GLuint i;
@@ -221,7 +266,13 @@ static void write_hit_record( GLcontext *ctx )
 }
 
 
-
+/**
+ * Initialize the name stack.
+ *
+ * Verifies we are in select mode and resets the name stack depth and resets
+ * the hit record data in gl_selection. Marks new render mode in
+ * __GLcontextRec::NewState.
+ */
 void
 _mesa_InitNames( void )
 {
@@ -242,7 +293,17 @@ _mesa_InitNames( void )
 }
 
 
-
+/**
+ * Load the top-most name of the name stack.
+ *
+ * \param name name.
+ *
+ * Verifies we are in selection mode and that the name stack is not empty.
+ * Flushes vertices. If there is a hit flag writes it (via write_hit_record()),
+ * and replace the top-most name in the stack.
+ *
+ * sa __GLcontextRec::Select.
+ */
 void
 _mesa_LoadName( GLuint name )
 {
@@ -271,6 +332,17 @@ _mesa_LoadName( GLuint name )
 }
 
 
+/**
+ * Push a name into the name stack.
+ *
+ * \param name name.
+ *
+ * Verifies we are in selection mode and that the name stack is not full.
+ * Flushes vertices. If there is a hit flag writes it (via write_hit_record()),
+ * and adds the name to the top of the name stack.
+ *
+ * sa __GLcontextRec::Select.
+ */
 void
 _mesa_PushName( GLuint name )
 {
@@ -293,7 +365,15 @@ _mesa_PushName( GLuint name )
 }
 
 
-
+/**
+ * Pop a name into the name stack.
+ *
+ * Verifies we are in selection mode and that the name stack is not empty.
+ * Flushes vertices. If there is a hit flag writes it (via write_hit_record()),
+ * and removes top-most name in the name stack.
+ *
+ * sa __GLcontextRec::Select.
+ */
 void
 _mesa_PopName( void )
 {
@@ -315,16 +395,27 @@ _mesa_PopName( void )
       ctx->Select.NameStackDepth--;
 }
 
+/*@}*/
 
 
 /**********************************************************************/
-/*                           Render Mode                              */
-/**********************************************************************/
-
+/** \name Render Mode */
+/*@{*/
 
-
-/*
- * NOTE: this function can't be put in a display list.
+/**
+ * Set rasterization mode.
+ *
+ * \param mode rasterization mode.
+ *
+ * \note this function can't be put in a display list.
+ *
+ * \sa glRenderMode().
+ * 
+ * Flushes the vertices and do the necessary cleanup according to the previous
+ * rasterization mode, such as writing the hit record or resent the select
+ * buffer index when exiting the select mode. Updates
+ * __GLcontextRec::RenderMode and notifies the driver via the
+ * dd_function_table::RenderMode callback.
  */
 GLint
 _mesa_RenderMode( GLenum mode )
@@ -360,6 +451,7 @@ _mesa_RenderMode( GLenum mode )
 	 ctx->Select.Hits = 0;
 	 ctx->Select.NameStackDepth = 0;
 	 break;
+#if _HAVE_FULL_GL
       case GL_FEEDBACK:
 	 if (ctx->Feedback.Count > ctx->Feedback.BufferSize) {
 	    /* overflow */
@@ -370,6 +462,7 @@ _mesa_RenderMode( GLenum mode )
 	 }
 	 ctx->Feedback.Count = 0;
 	 break;
+#endif
       default:
 	 _mesa_error( ctx, GL_INVALID_ENUM, "glRenderMode" );
 	 return 0;
@@ -384,12 +477,14 @@ _mesa_RenderMode( GLenum mode )
 	    _mesa_error( ctx, GL_INVALID_OPERATION, "glRenderMode" );
 	 }
 	 break;
+#if _HAVE_FULL_GL
       case GL_FEEDBACK:
 	 if (ctx->Feedback.BufferSize==0) {
 	    /* haven't called glFeedbackBuffer yet */
 	    _mesa_error( ctx, GL_INVALID_OPERATION, "glRenderMode" );
 	 }
 	 break;
+#endif
       default:
 	 _mesa_error( ctx, GL_INVALID_ENUM, "glRenderMode" );
 	 return 0;
@@ -401,3 +496,34 @@ _mesa_RenderMode( GLenum mode )
 
    return result;
 }
+
+/*@}*/
+
+
+/**********************************************************************/
+/** \name Initialization */
+/*@{*/
+
+/**
+ * Initialize context feedback data.
+ */
+void _mesa_init_feedback( GLcontext * ctx )
+{
+   /* Feedback */
+   ctx->Feedback.Type = GL_2D;   /* TODO: verify */
+   ctx->Feedback.Buffer = NULL;
+   ctx->Feedback.BufferSize = 0;
+   ctx->Feedback.Count = 0;
+
+   /* Selection/picking */
+   ctx->Select.Buffer = NULL;
+   ctx->Select.BufferSize = 0;
+   ctx->Select.BufferCount = 0;
+   ctx->Select.Hits = 0;
+   ctx->Select.NameStackDepth = 0;
+
+   /* Miscellaneous */
+   ctx->RenderMode = GL_RENDER;
+}
+
+/*@}*/
diff --git a/src/mesa/main/feedback.h b/src/mesa/main/feedback.h
index e91546248a..e1f47030c9 100644
--- a/src/mesa/main/feedback.h
+++ b/src/mesa/main/feedback.h
@@ -1,3 +1,7 @@
+/**
+ * \file feedback.h
+ * Selection and feedback modes functions.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -38,6 +42,8 @@
 	CTX->Feedback.Count++;
 
 
+extern void _mesa_init_feedback( GLcontext * ctx );
+
 extern void _mesa_feedback_vertex( GLcontext *ctx,
                                 const GLfloat win[4],
                                 const GLfloat color[4],
diff --git a/src/mesa/main/fog.c b/src/mesa/main/fog.c
index 79f480db37..b7f967ed67 100644
--- a/src/mesa/main/fog.c
+++ b/src/mesa/main/fog.c
@@ -156,3 +156,22 @@ _mesa_Fogfv( GLenum pname, const GLfloat *params )
       (*ctx->Driver.Fogfv)( ctx, pname, params );
    }
 }
+
+
+/**********************************************************************/
+/*****                      Initialization                        *****/
+/**********************************************************************/
+
+void _mesa_init_fog( GLcontext * ctx )
+{
+   /* Fog group */
+   ctx->Fog.Enabled = GL_FALSE;
+   ctx->Fog.Mode = GL_EXP;
+   ASSIGN_4V( ctx->Fog.Color, 0.0, 0.0, 0.0, 0.0 );
+   ctx->Fog.Index = 0.0;
+   ctx->Fog.Density = 1.0;
+   ctx->Fog.Start = 0.0;
+   ctx->Fog.End = 1.0;
+   ctx->Fog.ColorSumEnabled = GL_FALSE;
+   ctx->Fog.FogCoordinateSource = GL_FRAGMENT_DEPTH_EXT;
+}
diff --git a/src/mesa/main/fog.h b/src/mesa/main/fog.h
index cd7f59cc6d..4a0417545b 100644
--- a/src/mesa/main/fog.h
+++ b/src/mesa/main/fog.h
@@ -1,3 +1,12 @@
+/**
+ * \file fog.h
+ * Fog operations.
+ * 
+ * \if subset
+ * (No-op)
+ *
+ * \endif
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -31,21 +40,27 @@
 #include "mtypes.h"
 
 
+#if _HAVE_FULL_GL
 
 extern void
 _mesa_Fogf(GLenum pname, GLfloat param);
 
-
 extern void
 _mesa_Fogi(GLenum pname, GLint param );
 
-
 extern void
 _mesa_Fogfv(GLenum pname, const GLfloat *params );
 
-
 extern void
 _mesa_Fogiv(GLenum pname, const GLint *params );
 
+extern void _mesa_init_fog( GLcontext * ctx );
+
+#else
+
+/** No-op */
+#define _mesa_init_fog( c ) ((void)0)
+
+#endif
 
 #endif
diff --git a/src/mesa/main/get.c b/src/mesa/main/get.c
index b0de5e7ec0..a237775385 100644
--- a/src/mesa/main/get.c
+++ b/src/mesa/main/get.c
@@ -1,3 +1,8 @@
+/**
+ * \file get.c
+ * State query functions.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -107,6 +112,18 @@ pixel_texgen_mode(const GLcontext *ctx)
 }
 
 
+/**
+ * Get the value(s) of a selected parameter.
+ *
+ * \param pname parameter to be returned.
+ * \param params will hold the value(s) of the speficifed parameter.
+ *
+ * \sa glGetBooleanv().
+ *
+ * Tries to get the specified parameter via dd_function_table::GetBooleanv,
+ * otherwise gets the specified parameter from the current context, converting
+ * it value into GLboolean.
+ */
 void
 _mesa_GetBooleanv( GLenum pname, GLboolean *params )
 {
@@ -1619,6 +1636,18 @@ _mesa_GetBooleanv( GLenum pname, GLboolean *params )
 }
 
 
+/**
+ * Get the value(s) of a selected parameter.
+ *
+ * \param pname parameter to be returned.
+ * \param params will hold the value(s) of the speficifed parameter.
+ *
+ * \sa glGetDoublev().
+ *
+ * Tries to get the specified parameter via dd_function_table::GetDoublev,
+ * otherwise gets the specified parameter from the current context, converting
+ * it value into GLdouble.
+ */
 void
 _mesa_GetDoublev( GLenum pname, GLdouble *params )
 {
@@ -3125,6 +3154,18 @@ _mesa_GetDoublev( GLenum pname, GLdouble *params )
 }
 
 
+/**
+ * Get the value(s) of a selected parameter.
+ *
+ * \param pname parameter to be returned.
+ * \param params will hold the value(s) of the speficifed parameter.
+ *
+ * \sa glGetFloatv().
+ *
+ * Tries to get the specified parameter via dd_function_table::GetFloatv,
+ * otherwise gets the specified parameter from the current context, converting
+ * it value into GLfloat.
+ */
 void
 _mesa_GetFloatv( GLenum pname, GLfloat *params )
 {
@@ -4607,6 +4648,18 @@ _mesa_GetFloatv( GLenum pname, GLfloat *params )
 }
 
 
+/**
+ * Get the value(s) of a selected parameter.
+ *
+ * \param pname parameter to be returned.
+ * \param params will hold the value(s) of the speficifed parameter.
+ *
+ * \sa glGetIntegerv().
+ *
+ * Tries to get the specified parameter via dd_function_table::GetIntegerv,
+ * otherwise gets the specified parameter from the current context, converting
+ * it value into GLinteger.
+ */
 void
 _mesa_GetIntegerv( GLenum pname, GLint *params )
 {
@@ -6127,7 +6180,17 @@ _mesa_GetIntegerv( GLenum pname, GLint *params )
 }
 
 
-
+/**
+ * Get the address of a selected pointer.
+ *
+ * \param pname array or buffer to be returned.
+ * \param params will hold the pointer speficifed by \p pname.
+ *
+ * \sa glGetPointerv().
+ *
+ * Tries to get the specified pointer via dd_function_table::GetPointerv,
+ * otherwise gets the specified pointer from the current context.
+ */
 void
 _mesa_GetPointerv( GLenum pname, GLvoid **params )
 {
@@ -6183,7 +6246,16 @@ _mesa_GetPointerv( GLenum pname, GLvoid **params )
 }
 
 
-
+/**
+ * Get a string describing the current GL connection.
+ *
+ * \param name name symbolic constant.
+ *
+ * \sa glGetString().
+ *
+ * Tries to get the string from dd_function_table::GetString, otherwise returns
+ * the hardcoded strings.
+ */
 const GLubyte *
 _mesa_GetString( GLenum name )
 {
@@ -6261,8 +6333,12 @@ _mesa_GetString( GLenum name )
 }
 
 
-/*
- * Execute a glGetError command
+/**
+ * Execute a glGetError() command.
+ *
+ * \return error number.
+ *
+ * Returns __GLcontextRec::ErrorValue.
  */
 GLenum
 _mesa_GetError( void )
diff --git a/src/mesa/main/get.h b/src/mesa/main/get.h
index eaddb746f9..5c7a81e151 100644
--- a/src/mesa/main/get.h
+++ b/src/mesa/main/get.h
@@ -1,3 +1,7 @@
+/**
+ * \file get.h
+ * State query functions.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -52,6 +56,4 @@ _mesa_GetString( GLenum name );
 extern GLenum
 _mesa_GetError( void );
 
-
-
 #endif
diff --git a/src/mesa/main/glheader.h b/src/mesa/main/glheader.h
index 52950b3556..ef4c9f0a12 100644
--- a/src/mesa/main/glheader.h
+++ b/src/mesa/main/glheader.h
@@ -1,3 +1,22 @@
+/**
+ * \file glheader.h
+ * Top-most include file.
+ * 
+ * This is the top-most include file of the Mesa sources.
+ * It includes gl.h and all system headers which are needed.
+ * Other Mesa source files should \e not directly include any system
+ * headers.  This allows Mesa to be integrated into XFree86 and
+ * allows system-dependent hacks/workarounds to be collected in one place.
+ *
+ * \note Actually, a lot of system-dependent stuff is now in imports.[ch].
+ * 
+ * If you touch this file, everything gets recompiled!
+ *
+ * This file should be included before any other header in the .c files.
+ *
+ * Put compiler/OS/assembly pragmas and macros here to avoid
+ * cluttering other source files.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -28,22 +47,6 @@
 #define GLHEADER_H
 
 
-/*
- * This is the top-most include file of the Mesa sources.
- * It includes gl.h and all system headers which are needed.
- * Other Mesa source files should _not_ directly include any system
- * headers.  This allows Mesa to be integrated into XFree86 and
- * allows system-dependent hacks/work-arounds to be collected in one place.
- * XXX actually, a lot of system-dependent stuff is now in imports.[ch].
- *
- * If you touch this file, everything gets recompiled!
- *
- * Put compiler/OS/assembly pragmas and macros here to avoid
- * cluttering other source files.
- */
-
-
-
 #if defined(XFree86LOADER) && defined(IN_MODULE)
 #include "xf86_ansic.h"
 #else
@@ -122,7 +125,7 @@
 #  define GLWINAPIV
 #endif /* WIN32 / CYGWIN bracket */
 
-/* compatability guard so we don't need to change client code */
+/* compatibility guard so we don't need to change client code */
 
 #if defined(_WIN32) && !defined(_WINDEF_) && !defined(_GNU_H_WINDOWS32_BASE) && !defined(OPENSTEP) && !defined(__CYGWIN__)
 #if 0
@@ -280,9 +283,9 @@ typedef struct tagPIXELFORMATDESCRIPTOR PIXELFORMATDESCRIPTOR, *PPIXELFORMATDESC
 #endif
 
 
-/*
+/**
  * Sometimes we treat GLfloats as GLints.  On x86 systems, moving a float
- * as a int (thereby using integer registers instead of fp registers) is
+ * as a int (thereby using integer registers instead of FP registers) is
  * a performance win.  Typically, this can be done with ordinary casts.
  * But with gcc's -fstrict-aliasing flag (which defaults to on in gcc 3.0)
  * these casts generate warnings.
@@ -291,4 +294,6 @@ typedef struct tagPIXELFORMATDESCRIPTOR PIXELFORMATDESCRIPTOR, *PPIXELFORMATDESC
 typedef union { GLfloat f; GLint i; } fi_type;
 
 
+#include "config.h"
+
 #endif /* GLHEADER_H */
diff --git a/src/mesa/main/hash.c b/src/mesa/main/hash.c
index 32e37a268d..78be122aab 100644
--- a/src/mesa/main/hash.c
+++ b/src/mesa/main/hash.c
@@ -1,3 +1,14 @@
+/**
+ * \file hash.c
+ * Generic hash table. 
+ *
+ * Used for display lists and texture objects.  The hash functions are
+ * thread-safe.
+ * 
+ * \note key=0 is illegal.
+ *
+ * \author Brian Paul
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -23,6 +34,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
 #include "glheader.h"
 #include "imports.h"
 #include "glthread.h"
@@ -30,19 +42,12 @@
 #include "context.h"
 
 
-/**
- * \file hash.c
- * \brief Generic hash table.  Used for display lists and texture objects.
- * The hash functions are thread-safe.
- * \author Brian Paul
- * \note key=0 is illegal
- */
-
-
 #define TABLE_SIZE 1023  /**< Size of lookup table/array */
 
 /**
- * An entry in the hash table.  This struct is private to this file.
+ * An entry in the hash table.  
+ *
+ * This struct is private to this file.
  */
 struct HashEntry {
    GLuint Key;             /**< the entry's key */
@@ -51,8 +56,9 @@ struct HashEntry {
 };
 
 /**
- * The hashtable data structure.  This is an opaque types (it's not
- * defined in the .h file).
+ * The hash table data structure.  
+ *
+ * This is an opaque types (it's not defined in hash.h file).
  */
 struct _mesa_HashTable {
    struct HashEntry *Table[TABLE_SIZE];  /**< the lookup table */
@@ -64,6 +70,7 @@ struct _mesa_HashTable {
 
 /**
  * Create a new hash table.
+ * 
  * \return pointer to a new, empty hash table.
  */
 struct _mesa_HashTable *_mesa_NewHashTable(void)
@@ -79,7 +86,10 @@ struct _mesa_HashTable *_mesa_NewHashTable(void)
 
 /**
  * Delete a hash table.
- * \param table - the hash table to delete
+ * 
+ * \param table the hash table to delete.
+ *
+ * Frees each entry on the hash table and then the hash table structure itself.
  */
 void _mesa_DeleteHashTable(struct _mesa_HashTable *table)
 {
@@ -101,9 +111,13 @@ void _mesa_DeleteHashTable(struct _mesa_HashTable *table)
 
 /**
  * Lookup an entry in the hash table.
- * \param table - the hash table
- * \param key - the key
+ * 
+ * \param table the hash table.
+ * \param key the key.
+ * 
  * \return pointer to user's data or NULL if key not in table
+ *
+ * Walks through the hash entry until finding the matching key.
  */
 void *_mesa_HashLookup(const struct _mesa_HashTable *table, GLuint key)
 {
@@ -127,11 +141,16 @@ void *_mesa_HashLookup(const struct _mesa_HashTable *table, GLuint key)
 
 
 /**
- * Insert into the hash table.  If an entry with this key already exists
- * we'll replace the existing entry.
- * \param table - the hash table
- * \param key - the key (not zero)
- * \param data - pointer to user data
+ * Insert into the hash table.  
+ *
+ * If an entry with this key already exists we'll replace the existing entry.
+ * 
+ * \param table the hash table.
+ * \param key the key (not zero).
+ * \param data pointer to user data.
+ *
+ * While holding the hash table's lock, walk through the hash entry list replacing the data if a
+ * matching key is found, or inserts a new table entry otherwise.
  */
 void _mesa_HashInsert(struct _mesa_HashTable *table, GLuint key, void *data)
 {
@@ -173,8 +192,12 @@ void _mesa_HashInsert(struct _mesa_HashTable *table, GLuint key, void *data)
 
 /**
  * Remove an entry from the hash table.
- * \param table - the hash table
- * \param key - key of entry to remove
+ * 
+ * \param table the hash table.
+ * \param key key of entry to remove.
+ *
+ * While holding the hash table's lock, searches the entry with the matching
+ * key and unlinks it.
  */
 void _mesa_HashRemove(struct _mesa_HashTable *table, GLuint key)
 {
@@ -213,10 +236,16 @@ void _mesa_HashRemove(struct _mesa_HashTable *table, GLuint key)
 
 /**
  * Get the key of the "first" entry in the hash table.
+ * 
  * This is used in the course of deleting all display lists when
  * a context is destroyed.
- * \param table - the hash table
+ * 
+ * \param table the hash table
+ * 
  * \return key for the "first" entry in the hash table.
+ *
+ * While holding the lock, walks through all table positions until finding
+ * the first entry of the first non-empty one.
  */
 GLuint _mesa_HashFirstEntry(struct _mesa_HashTable *table)
 {
@@ -237,7 +266,8 @@ GLuint _mesa_HashFirstEntry(struct _mesa_HashTable *table)
 
 /**
  * Dump contents of hash table for debugging.
- * \param table - the hash table
+ * 
+ * \param table the hash table.
  */
 void _mesa_HashPrint(const struct _mesa_HashTable *table)
 {
@@ -255,10 +285,17 @@ void _mesa_HashPrint(const struct _mesa_HashTable *table)
 
 
 /**
- * Find a block of 'numKeys' adjacent unused hash keys.
- * \param table - the hash table
- * \param numKeys - number of keys needed
- * \return Starting key of free block or 0 if failure
+ * Find a block of adjacent unused hash keys.
+ * 
+ * \param table the hash table.
+ * \param numKeys number of keys needed.
+ * 
+ * \return Starting key of free block or 0 if failure.
+ *
+ * If there are enough free keys between the maximum key existing in the table
+ * (_mesa_HashTable::MaxKey) and the maximum key possible, then simply return
+ * the adjacent key. Otherwise do a full search for a free key block in the
+ * allowable key range.
  */
 GLuint _mesa_HashFindFreeKeyBlock(struct _mesa_HashTable *table, GLuint numKeys)
 {
diff --git a/src/mesa/main/hash.h b/src/mesa/main/hash.h
index 07bdef46c1..359ba51274 100644
--- a/src/mesa/main/hash.h
+++ b/src/mesa/main/hash.h
@@ -1,3 +1,7 @@
+/**
+ * \file hash.h
+ * Generic hash table. 
+ */
 
 /*
  * Mesa 3-D graphics library
diff --git a/src/mesa/main/hint.c b/src/mesa/main/hint.c
index 90ccc8bf6f..5af819194a 100644
--- a/src/mesa/main/hint.c
+++ b/src/mesa/main/hint.c
@@ -120,3 +120,21 @@ _mesa_Hint( GLenum target, GLenum mode )
       (*ctx->Driver.Hint)( ctx, target, mode );
    }
 }
+
+
+/**********************************************************************/
+/*****                      Initialization                        *****/
+/**********************************************************************/
+
+void _mesa_init_hint( GLcontext * ctx )
+{
+   /* Hint group */
+   ctx->Hint.PerspectiveCorrection = GL_DONT_CARE;
+   ctx->Hint.PointSmooth = GL_DONT_CARE;
+   ctx->Hint.LineSmooth = GL_DONT_CARE;
+   ctx->Hint.PolygonSmooth = GL_DONT_CARE;
+   ctx->Hint.Fog = GL_DONT_CARE;
+   ctx->Hint.ClipVolumeClipping = GL_DONT_CARE;
+   ctx->Hint.TextureCompression = GL_DONT_CARE;
+   ctx->Hint.GenerateMipmap = GL_DONT_CARE;
+}
diff --git a/src/mesa/main/hint.h b/src/mesa/main/hint.h
index f33be7b54d..57f3823fcf 100644
--- a/src/mesa/main/hint.h
+++ b/src/mesa/main/hint.h
@@ -1,3 +1,12 @@
+/**
+ * \file hint.h
+ * Hints operations.
+ * 
+ * \if subset
+ * (No-op)
+ *
+ * \endif
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -30,9 +39,19 @@
 
 #include "mtypes.h"
 
+#if _HAVE_FULL_GL
 
 extern void
 _mesa_Hint( GLenum target, GLenum mode );
 
+extern void 
+_mesa_init_hint( GLcontext * ctx );
+
+#else
+
+/** No-op */
+#define _mesa_init_hint( c ) ((void) 0)
+
+#endif
 
 #endif
diff --git a/src/mesa/main/histogram.c b/src/mesa/main/histogram.c
index 63b147b005..ea2c465e43 100644
--- a/src/mesa/main/histogram.c
+++ b/src/mesa/main/histogram.c
@@ -1099,3 +1099,38 @@ _mesa_ResetMinmax(GLenum target)
    ctx->MinMax.Min[ACOMP] = 1000;    ctx->MinMax.Max[ACOMP] = -1000;
    ctx->NewState |= _NEW_PIXEL;
 }
+
+
+
+/**********************************************************************/
+/*****                      Initialization                        *****/
+/**********************************************************************/
+
+void _mesa_init_histogram( GLcontext * ctx )
+{
+   int i;
+
+   /* Histogram group */
+   ctx->Histogram.Width = 0;
+   ctx->Histogram.Format = GL_RGBA;
+   ctx->Histogram.Sink = GL_FALSE;
+   ctx->Histogram.RedSize       = 0;
+   ctx->Histogram.GreenSize     = 0;
+   ctx->Histogram.BlueSize      = 0;
+   ctx->Histogram.AlphaSize     = 0;
+   ctx->Histogram.LuminanceSize = 0;
+   for (i = 0; i < HISTOGRAM_TABLE_SIZE; i++) {
+      ctx->Histogram.Count[i][0] = 0;
+      ctx->Histogram.Count[i][1] = 0;
+      ctx->Histogram.Count[i][2] = 0;
+      ctx->Histogram.Count[i][3] = 0;
+   }
+
+   /* Min/Max group */
+   ctx->MinMax.Format = GL_RGBA;
+   ctx->MinMax.Sink = GL_FALSE;
+   ctx->MinMax.Min[RCOMP] = 1000;    ctx->MinMax.Max[RCOMP] = -1000;
+   ctx->MinMax.Min[GCOMP] = 1000;    ctx->MinMax.Max[GCOMP] = -1000;
+   ctx->MinMax.Min[BCOMP] = 1000;    ctx->MinMax.Max[BCOMP] = -1000;
+   ctx->MinMax.Min[ACOMP] = 1000;    ctx->MinMax.Max[ACOMP] = -1000;
+}
diff --git a/src/mesa/main/histogram.h b/src/mesa/main/histogram.h
index ece6f11ed2..548e0ba383 100644
--- a/src/mesa/main/histogram.h
+++ b/src/mesa/main/histogram.h
@@ -1,3 +1,12 @@
+/**
+ * \file histogram.h
+ * Histogram.
+ * 
+ * \if subset
+ * (No-op)
+ *
+ * \endif
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -30,6 +39,7 @@
 #include "glheader.h"
 #include "mtypes.h"
 
+#if _HAVE_FULL_GL
 
 extern void
 _mesa_update_minmax(GLcontext *ctx, GLuint n, const GLfloat rgba[][4]);
@@ -58,4 +68,19 @@ extern void _mesa_ResetHistogram(GLenum target);
 
 extern void _mesa_ResetMinmax(GLenum target);
 
+extern void
+_mesa_update_minmax(GLcontext *ctx, GLuint n, const GLfloat rgba[][4]);
+
+extern void
+_mesa_update_histogram(GLcontext *ctx, GLuint n, const GLfloat rgba[][4]);
+
+extern void _mesa_init_histogram( GLcontext * ctx );
+
+#else
+
+/** No-op */
+#define _mesa_init_histogram( c ) ((void) 0)
+
+#endif
+
 #endif
diff --git a/src/mesa/main/image.c b/src/mesa/main/image.c
index 34bcf37d15..171efb5b24 100644
--- a/src/mesa/main/image.c
+++ b/src/mesa/main/image.c
@@ -1,3 +1,7 @@
+/**
+ * \file image.c
+ * Image handling.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -23,6 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
 #include "glheader.h"
 #include "colormac.h"
 #include "context.h"
@@ -34,18 +39,16 @@
 #include "mtypes.h"
 
 
-
-/* Compute ceiling of integer quotient of A divided by B: */
+/** Compute ceiling of integer quotient of A divided by B. */
 #define CEILING( A, B )  ( (A) % (B) == 0 ? (A)/(B) : (A)/(B)+1 )
 
 
-
-/*
- * These are the image packing parameters for Mesa's internal images.
- * That is, _mesa_unpack_image() returns image data in this format.
- * When we execute image commands (glDrawPixels, glTexImage, etc)
- * from within display lists we have to be sure to set the current
- * unpacking params to these values!
+/**
+ * Image packing parameters for Mesa's internal images.
+ * 
+ * _mesa_unpack_image() returns image data in this format.  When we execute
+ * image commands (glDrawPixels(), glTexImage(), etc) from within display lists
+ * we have to be sure to set the current unpacking parameters to these values!
  */
 const struct gl_pixelstore_attrib _mesa_native_packing = {
    1,            /* Alignment */
@@ -61,14 +64,18 @@ const struct gl_pixelstore_attrib _mesa_native_packing = {
 };
 
 
-
-/*
+/**
  * Flip the 8 bits in each byte of the given array.
  *
- * XXX try this trick to flip bytes someday:
+ * \param p array.
+ * \param n number of bytes.
+ *
+ * \todo try this trick to flip bytes someday:
+ * \code
  *  v = ((v & 0x55555555) << 1) | ((v >> 1) & 0x55555555);
  *  v = ((v & 0x33333333) << 2) | ((v >> 2) & 0x33333333);
  *  v = ((v & 0x0f0f0f0f) << 4) | ((v >> 4) & 0x0f0f0f0f);
+ * \endcode
  */
 static void
 flip_bytes( GLubyte *p, GLuint n )
@@ -90,8 +97,11 @@ flip_bytes( GLubyte *p, GLuint n )
 }
 
 
-/*
+/**
  * Flip the order of the 2 bytes in each word in the given array.
+ *
+ * \param p array.
+ * \param n number of words.
  */
 void
 _mesa_swap2( GLushort *p, GLuint n )
@@ -124,12 +134,13 @@ _mesa_swap4( GLuint *p, GLuint n )
 }
 
 
-
-
-/*
- * Return the size, in bytes, of the given GL datatype.
- * Return 0 if GL_BITMAP.
- * Return -1 if invalid type enum.
+/**
+ * Get the size of a GL data type.
+ *
+ * \param type GL data type.
+ *
+ * \return the size, in bytes, of the given data type, 0 if a GL_BITMAP, or -1
+ * if an invalid type enum.
  */
 GLint _mesa_sizeof_type( GLenum type )
 {
@@ -156,9 +167,9 @@ GLint _mesa_sizeof_type( GLenum type )
 }
 
 
-/*
- * Same as _mesa_sizeof_packed_type() but we also accept the
- * packed pixel format datatypes.
+/**
+ * Same as _mesa_sizeof_type() but also accepting the packed pixel
+ * format data types.
  */
 GLint _mesa_sizeof_packed_type( GLenum type )
 {
@@ -212,10 +223,12 @@ GLint _mesa_sizeof_packed_type( GLenum type )
 }
 
 
-
-/*
- * Return the number of components in a GL enum pixel type.
- * Return -1 if bad format.
+/**
+ * Get the number of components in a pixel format.
+ *
+ * \param format pixel format.
+ *
+ * \return the number of components in the given format, or -1 if a bad format.
  */
 GLint _mesa_components_in_format( GLenum format )
 {
@@ -256,9 +269,13 @@ GLint _mesa_components_in_format( GLenum format )
 }
 
 
-/*
- * Return bytes per pixel for given format and type
- * Return -1 if bad format or type.
+/**
+ * Get the bytes per pixel of pixel format type pair.
+ *
+ * \param format pixel format.
+ * \param type pixel type.
+ *
+ * \return bytes per pixel, or -1 if a bad format or type was given.
  */
 GLint _mesa_bytes_per_pixel( GLenum format, GLenum type )
 {
@@ -320,9 +337,14 @@ GLint _mesa_bytes_per_pixel( GLenum format, GLenum type )
 }
 
 
-/*
- * Test if the given pixel format and type are legal.
- * Return GL_TRUE for legal, GL_FALSE for illegal.
+/**
+ * Test for a legal pixel format and type.
+ *
+ * \param format pixel format.
+ * \param type pixel type.
+ *
+ * \return GL_TRUE if the given pixel format and type are legal, or GL_FALSE
+ * otherwise.
  */
 GLboolean
 _mesa_is_legal_format_and_type( GLenum format, GLenum type )
@@ -417,18 +439,27 @@ _mesa_is_legal_format_and_type( GLenum format, GLenum type )
 }
 
 
-
-/*
- * Return the address of a pixel in an image (actually a volume).
- * Pixel unpacking/packing parameters are observed according to 'packing'.
- * Input:  image - start of image data
- *         width, height - size of image
- *         format - image format
- *         type - pixel component type
- *         packing - the pixelstore attributes
- *         img - which image in the volume (0 for 1D or 2D images)
- *         row, column - location of pixel in the image
- * Return:  address of pixel at (image,row,column) in image or NULL if error.
+/**
+ * Get the address of a pixel in an image (actually a volume).
+ *
+ * Pixel unpacking/packing parameters are observed according to \p packing.
+ *
+ * \param image start of image data.
+ * \param width image width.
+ * \param height image height.
+ * \param format pixel format.
+ * \param type pixel data type.
+ * \param packing the pixelstore attributes
+ * \param img which image in the volume (0 for 1D or 2D images)
+ * \param row of pixel in the image
+ * \param column of pixel in the image
+ * 
+ * \return address of pixel on success, or NULL on error.
+ *
+ * According to the \p packing information calculates the number of pixel/bytes
+ * per row/image and refers it.
+ *
+ * \sa gl_pixelstore_attrib.
  */
 GLvoid *
 _mesa_image_address( const struct gl_pixelstore_attrib *packing,
@@ -530,10 +561,19 @@ _mesa_image_address( const struct gl_pixelstore_attrib *packing,
 }
 
 
-
-/*
- * Compute the stride between image rows (in bytes) for the given
- * pixel packing parameters and image width, format and type.
+/**
+ * Compute the stride between image rows.
+ *
+ * \param packing the pixelstore attributes
+ * \param width image width.
+ * \param format pixel format.
+ * \param type pixel data type.
+ * 
+ * \return the stride in bytes for the given parameters.
+ *
+ * Computes the number of bytes per pixel and row and compensates for alignment.
+ *
+ * \sa gl_pixelstore_attrib.
  */
 GLint
 _mesa_image_row_stride( const struct gl_pixelstore_attrib *packing,
@@ -577,6 +617,7 @@ _mesa_image_row_stride( const struct gl_pixelstore_attrib *packing,
 }
 
 
+#if _HAVE_FULL_GL
 
 /*
  * Compute the stride between images in a 3D texture (in bytes) for the given
@@ -616,8 +657,6 @@ _mesa_image_image_stride( const struct gl_pixelstore_attrib *packing,
 }
 
 
-
-
 /*
  * Unpack a 32x32 pixel polygon stipple from user memory using the
  * current pixel unpack settings.
@@ -645,7 +684,6 @@ _mesa_unpack_polygon_stipple( const GLubyte *pattern, GLuint dest[32],
 }
 
 
-
 /*
  * Pack polygon stipple into user memory given current pixel packing
  * settings.
@@ -863,7 +901,6 @@ _mesa_pack_bitmap( GLint width, GLint height, const GLubyte *source,
 }
 
 
-
 /*
  * Used to pack an array [][4] of RGBA GLchan colors as specified
  * by the dstFormat, dstType and dstPacking.  Used by glReadPixels,
@@ -942,11 +979,11 @@ _mesa_pack_float_rgba_span( GLcontext *ctx,
       }
       /* update histogram count */
       if (transferOps & IMAGE_HISTOGRAM_BIT) {
-         _mesa_update_histogram(ctx, n, (CONST GLfloat (*)[4]) rgba);
+/*          _mesa_update_histogram(ctx, n, (CONST GLfloat (*)[4]) rgba); */
       }
       /* min/max here */
       if (transferOps & IMAGE_MIN_MAX_BIT) {
-         _mesa_update_minmax(ctx, n, (CONST GLfloat (*)[4]) rgba);
+/*          _mesa_update_minmax(ctx, n, (CONST GLfloat (*)[4]) rgba); */
          if (ctx->MinMax.Sink) {
             UNDEFARRAY(rgbaCopy);  /* mac 32k limitation */
             return;
@@ -1779,18 +1816,17 @@ _mesa_pack_float_rgba_span( GLcontext *ctx,
 }
 
 
-
 /*
  * Pack the given RGBA span into client memory at 'dest' address
  * in the given pixel format and type.
  * Optionally apply the enabled pixel transfer ops.
  * Pack into memory using the given packing params struct.
  * This is used by glReadPixels and glGetTexImage?D()
- * Input:  ctx - the context
+ * \param ctx - the context
  *         n - number of pixels in the span
  *         rgba - the pixels
  *         format - dest packing format
- *         type - dest packing datatype
+ *         type - dest packing data type
  *         destination - destination packing address
  *         packing - pixel packing parameters
  *         transferOps - bitmask of IMAGE_*_BIT operations to apply
@@ -2033,7 +2069,6 @@ extract_uint_indexes(GLuint n, GLuint indexes[],
 }
 
 
-
 /*
  * This function extracts floating point RGBA values from arbitrary
  * image data.  srcFormat and srcType are the format and type parameters
@@ -2046,7 +2081,7 @@ extract_uint_indexes(GLuint n, GLuint indexes[],
  * Args:  n - number of pixels
  *        rgba - output colors
  *        srcFormat - format of incoming data
- *        srcType - datatype of incoming data
+ *        srcType - data type of incoming data
  *        src - source data pointer
  *        swapBytes - perform byteswapping of incoming data?
  */
@@ -2537,18 +2572,17 @@ extract_float_rgba(GLuint n, GLfloat rgba[][4],
 }
 
 
-
 /*
  * Unpack a row of color image data from a client buffer according to
  * the pixel unpacking parameters.
  * Return GLubyte values in the specified dest image format.
  * This is (or will be) used by glDrawPixels and glTexImage?D().
- * Input:  ctx - the context
+ * \param ctx - the context
  *         n - number of pixels in the span
  *         dstFormat - format of destination color array
  *         dest - the destination color array
  *         srcFormat - source image format
- *         srcType - source image  datatype
+ *         srcType - source image  data type
  *         source - source image pointer
  *         srcPacking - pixel unpacking parameters
  *         transferOps - bitmask of IMAGE_*_BIT values of operations to apply
@@ -2818,11 +2852,11 @@ _mesa_unpack_chan_color_span( GLcontext *ctx,
          }
          /* update histogram count */
          if (transferOps & IMAGE_HISTOGRAM_BIT) {
-            _mesa_update_histogram(ctx, n, (CONST GLfloat (*)[4]) rgba);
+/*             _mesa_update_histogram(ctx, n, (CONST GLfloat (*)[4]) rgba); */
          }
          /* min/max here */
          if (transferOps & IMAGE_MIN_MAX_BIT) {
-            _mesa_update_minmax(ctx, n, (CONST GLfloat (*)[4]) rgba);
+/*             _mesa_update_minmax(ctx, n, (CONST GLfloat (*)[4]) rgba); */
          }
       }
 
@@ -3095,11 +3129,11 @@ _mesa_unpack_float_color_span( GLcontext *ctx,
          }
          /* update histogram count */
          if (transferOps & IMAGE_HISTOGRAM_BIT) {
-            _mesa_update_histogram(ctx, n, (CONST GLfloat (*)[4]) rgba);
+/*             _mesa_update_histogram(ctx, n, (CONST GLfloat (*)[4]) rgba); */
          }
          /* min/max here */
          if (transferOps & IMAGE_MIN_MAX_BIT) {
-            _mesa_update_minmax(ctx, n, (CONST GLfloat (*)[4]) rgba);
+/*             _mesa_update_minmax(ctx, n, (CONST GLfloat (*)[4]) rgba); */
          }
       }
 
@@ -3223,8 +3257,6 @@ _mesa_unpack_float_color_span( GLcontext *ctx,
 }
 
 
-
-
 /*
  * Unpack a row of color index data from a client buffer according to
  * the pixel unpacking parameters.
@@ -3232,7 +3264,7 @@ _mesa_unpack_float_color_span( GLcontext *ctx,
  *
  * Args:  ctx - the context
  *        n - number of pixels
- *        dstType - destination datatype
+ *        dstType - destination data type
  *        dest - destination array
  *        srcType - source pixel type
  *        source - source data pointer
@@ -3431,7 +3463,6 @@ _mesa_pack_index_span( const GLcontext *ctx, GLuint n,
 }
 
 
-
 /*
  * Unpack a row of stencil data from a client buffer according to
  * the pixel unpacking parameters.
@@ -3439,7 +3470,7 @@ _mesa_pack_index_span( const GLcontext *ctx, GLuint n,
  *
  * Args:  ctx - the context
  *        n - number of pixels
- *        dstType - destination datatype
+ *        dstType - destination data type
  *        dest - destination array
  *        srcType - source pixel type
  *        source - source data pointer
@@ -3684,7 +3715,6 @@ _mesa_pack_stencil_span( const GLcontext *ctx, GLuint n,
 }
 
 
-
 void
 _mesa_unpack_depth_span( const GLcontext *ctx, GLuint n, GLfloat *dest,
                          GLenum srcType, const GLvoid *source,
@@ -3765,7 +3795,6 @@ _mesa_unpack_depth_span( const GLcontext *ctx, GLuint n, GLfloat *dest,
 }
 
 
-
 /*
  * Pack an array of depth values.  The values are floats in [0,1].
  */
@@ -3875,8 +3904,6 @@ _mesa_pack_depth_span( const GLcontext *ctx, GLuint n, GLvoid *dest,
 }
 
 
-
-
 /*
  * Unpack image data.  Apply byteswapping, byte flipping (bitmap).
  * Return all image data in a contiguous block.
@@ -3945,3 +3972,5 @@ _mesa_unpack_image( GLsizei width, GLsizei height, GLsizei depth,
       return destBuffer;
    }
 }
+
+#endif
diff --git a/src/mesa/main/image.h b/src/mesa/main/image.h
index 39260f0b4f..6c8b342ba5 100644
--- a/src/mesa/main/image.h
+++ b/src/mesa/main/image.h
@@ -1,3 +1,7 @@
+/**
+ * \file image.h
+ * Image handling.
+ */
 
 /*
  * Mesa 3-D graphics library
diff --git a/src/mesa/main/imports.c b/src/mesa/main/imports.c
index a1c974ca75..7597979e4a 100644
--- a/src/mesa/main/imports.c
+++ b/src/mesa/main/imports.c
@@ -1,3 +1,35 @@
+/**
+ * \file imports.c
+ * Standard C library function wrappers.
+ * 
+ * Imports are services which the device driver or window system or
+ * operating system provides to the core renderer.  The core renderer (Mesa)
+ * will call these functions in order to do memory allocation, simple I/O,
+ * etc.
+ *
+ * Some drivers will want to override/replace this file with something
+ * specialized, but that'll be rare.
+ *
+ * Eventually, I want to move roll the glheader.h file into this.
+ *
+ * The OpenGL SI's __GLimports structure allows per-context specification of
+ * replacements for the standard C lib functions.  In practice that's probably
+ * never needed; compile-time replacements are far more likely.
+ *
+ * The _mesa_*() functions defined here don't in general take a context
+ * parameter.  I guess we can change that someday, if need be.
+ * So for now, the __GLimports stuff really isn't used.
+ *
+ * \todo Functions still needed:
+ * - scanf
+ * - qsort
+ * - bsearch
+ * - rand and RAND_MAX
+ *
+ * \note When compiled into a XFree86 module these functions wrap around
+ * XFree86 own wrappers.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -23,26 +55,6 @@
  */
 
 
-/*
- * Imports are services which the device driver or window system or
- * operating system provides to the core renderer.  The core renderer (Mesa)
- * will call these functions in order to do memory allocation, simple I/O,
- * etc.
- *
- * Some drivers will want to override/replace this file with something
- * specialized, but that'll be rare.
- *
- * Eventually, I want to move roll the glheader.h file into this.
- *
- * The OpenGL SI's __GLimports structure allows per-context specification of
- * replacements for the standard C lib functions.  In practice that's probably
- * never needed; compile-time replacements are far more likely.
- *
- * The _mesa_foo() functions defined here don't in general take a context
- * parameter.  I guess we can change that someday, if need be.
- * So for now, the __GLimports stuff really isn't used.
- */
-
 
 #include "imports.h"
 #include "context.h"
@@ -58,22 +70,10 @@ extern int vsnprintf(char *str, size_t count, const char *fmt, va_list arg);
 
 
 /**********************************************************************/
-/* Wrappers for standard C library functions                          */
-/**********************************************************************/
-
-/*
- * Functions still needed:
- * scanf
- * qsort
- * bsearch
- * rand and RAND_MAX
- */
-
-
-/**********************************************************************
- * Memory
- */
+/** \name Memory */
+/*@{*/
 
+/** Wrapper around either malloc() or xf86malloc() */
 void *
 _mesa_malloc(size_t bytes)
 {
@@ -84,7 +84,7 @@ _mesa_malloc(size_t bytes)
 #endif
 }
 
-
+/** Wrapper around either calloc() or xf86calloc() */
 void *
 _mesa_calloc(size_t bytes)
 {
@@ -95,7 +95,7 @@ _mesa_calloc(size_t bytes)
 #endif
 }
 
-
+/** Wrapper around either free() or xf86free() */
 void
 _mesa_free(void *ptr)
 {
@@ -106,7 +106,17 @@ _mesa_free(void *ptr)
 #endif
 }
 
-
+/**
+ * Allocate aligned memory.
+ *
+ * \param bytes number of bytes to allocate.
+ * \param alignment alignment (must be greater than zero).
+ * 
+ * Allocates extra memory to accommodate rounding up the address for
+ * alignment and to record the real malloc address.
+ *
+ * \sa _mesa_align_free().
+ */
 void *
 _mesa_align_malloc(size_t bytes, unsigned long alignment)
 {
@@ -114,9 +124,6 @@ _mesa_align_malloc(size_t bytes, unsigned long alignment)
 
    ASSERT( alignment > 0 );
 
-   /* Allocate extra memory to accomodate rounding up the address for
-    * alignment and to record the real malloc address.
-    */
    ptr = (unsigned long) _mesa_malloc(bytes + alignment + sizeof(void *));
    if (!ptr)
       return NULL;
@@ -135,7 +142,8 @@ _mesa_align_malloc(size_t bytes, unsigned long alignment)
    return (void *) buf;
 }
 
-
+/** Same as _mesa_align_malloc(), but using _mesa_calloc() instead of
+ * _mesa_malloc() */
 void *
 _mesa_align_calloc(size_t bytes, unsigned long alignment)
 {
@@ -161,23 +169,27 @@ _mesa_align_calloc(size_t bytes, unsigned long alignment)
    return (void *)buf;
 }
 
-
+/**
+ * Free memory allocated with _mesa_align_malloc() or _mesa_align_calloc().
+ *
+ * \param ptr pointer to the memory to be freed.
+ * 
+ * The actual address to free is stored in the word immediately before the
+ * address the client sees.
+ */
 void
 _mesa_align_free(void *ptr)
 {
 #if 0
    _mesa_free( (void *)(*(unsigned long *)((unsigned long)ptr - sizeof(void *))) );
 #else
-   /* The actuall address to free is stuffed in the word immediately
-    * before the address the client sees.
-    */
    void **cubbyHole = (void **) ((char *) ptr - sizeof(void *));
    void *realAddr = *cubbyHole;
    _mesa_free(realAddr);
 #endif
 }
 
-
+/** Wrapper around either memcpy() or xf86memcpy() */
 void *
 _mesa_realloc(void *oldBuffer, size_t oldSize, size_t newSize)
 {
@@ -203,7 +215,7 @@ _mesa_memcpy(void *dest, const void *src, size_t n)
 #endif
 }
 
-
+/** Wrapper around either memset() or xf86memset() */
 void
 _mesa_memset( void *dst, int val, size_t n )
 {
@@ -216,7 +228,12 @@ _mesa_memset( void *dst, int val, size_t n )
 #endif
 }
 
-
+/** Fill memory with a constant 16bit word.
+ *
+ * \param dst destination pointer.
+ * \param val value.
+ * \param n number of words.
+ */
 void
 _mesa_memset16( unsigned short *dst, unsigned short val, size_t n )
 {
@@ -224,7 +241,7 @@ _mesa_memset16( unsigned short *dst, unsigned short val, size_t n )
       *dst++ = val;
 }
 
-
+/** Wrapper around either memcpy() or xf86memcpy() or bzero() */
 void
 _mesa_bzero( void *dst, size_t n )
 {
@@ -237,11 +254,14 @@ _mesa_bzero( void *dst, size_t n )
 #endif
 }
 
+/*@}*/
 
-/**********************************************************************
- * Math
- */
 
+/**********************************************************************/
+/** \name Math */
+/*@{*/
+
+/** Wrapper around either sin() or xf86sin() */
 double
 _mesa_sin(double a)
 {
@@ -252,7 +272,7 @@ _mesa_sin(double a)
 #endif
 }
 
-
+/** Wrapper around either cos() or xf86cos() */
 double
 _mesa_cos(double a)
 {
@@ -263,7 +283,7 @@ _mesa_cos(double a)
 #endif
 }
 
-
+/** Wrapper around either sqrt() or xf86sqrt() */
 double
 _mesa_sqrtd(double x)
 {
@@ -474,6 +494,7 @@ _mesa_inv_sqrtf(float n)
 }
 
 
+/** Wrapper around either pow() or xf86pow() */
 double
 _mesa_pow(double x, double y)
 {
@@ -498,12 +519,14 @@ _mesa_bitcount(unsigned int n)
    return bits;
 }
 
+/*@}*/
 
 
-/**********************************************************************
- * Environment vars
- */
+/**********************************************************************/
+/** \name Environment vars */
+/*@{*/
 
+/** Wrapper around either () or xf86() */
 char *
 _mesa_getenv( const char *var )
 {
@@ -514,11 +537,14 @@ _mesa_getenv( const char *var )
 #endif
 }
 
+/*@}*/
 
-/**********************************************************************
- * String
- */
 
+/**********************************************************************/
+/** \name String */
+/*@{*/
+
+/** Wrapper around either strstr() or xf86strstr() */
 char *
 _mesa_strstr( const char *haystack, const char *needle )
 {
@@ -529,7 +555,7 @@ _mesa_strstr( const char *haystack, const char *needle )
 #endif
 }
 
-
+/** Wrapper around either strncat() or xf86strncat() */
 char *
 _mesa_strncat( char *dest, const char *src, size_t n )
 {
@@ -540,7 +566,7 @@ _mesa_strncat( char *dest, const char *src, size_t n )
 #endif
 }
 
-
+/** Wrapper around either strcpy() or xf86strcpy() */
 char *
 _mesa_strcpy( char *dest, const char *src )
 {
@@ -551,7 +577,7 @@ _mesa_strcpy( char *dest, const char *src )
 #endif
 }
 
-
+/** Wrapper around either strncpy() or xf86strncpy() */
 char *
 _mesa_strncpy( char *dest, const char *src, size_t n )
 {
@@ -562,7 +588,7 @@ _mesa_strncpy( char *dest, const char *src, size_t n )
 #endif
 }
 
-
+/** Wrapper around either strlen() or xf86strlen() */
 size_t
 _mesa_strlen( const char *s )
 {
@@ -573,7 +599,7 @@ _mesa_strlen( const char *s )
 #endif
 }
 
-
+/** Wrapper around either strcmp() or xf86strcmp() */
 int
 _mesa_strcmp( const char *s1, const char *s2 )
 {
@@ -584,7 +610,7 @@ _mesa_strcmp( const char *s1, const char *s2 )
 #endif
 }
 
-
+/** Wrapper around either strncmp() or xf86strncmp() */
 int
 _mesa_strncmp( const char *s1, const char *s2, size_t n )
 {
@@ -595,7 +621,7 @@ _mesa_strncmp( const char *s1, const char *s2, size_t n )
 #endif
 }
 
-
+/** Implemented using _mesa_malloc() and _mesa_strcpy */
 char *
 _mesa_strdup( const char *s )
 {
@@ -606,7 +632,7 @@ _mesa_strdup( const char *s )
    return s2;
 }
 
-
+/** Wrapper around either atoi() or xf86atoi() */
 int
 _mesa_atoi(const char *s)
 {
@@ -617,7 +643,7 @@ _mesa_atoi(const char *s)
 #endif
 }
 
-
+/** Wrapper around either strtod() or xf86strtod() */
 double
 _mesa_strtod( const char *s, char **end )
 {
@@ -628,11 +654,14 @@ _mesa_strtod( const char *s, char **end )
 #endif
 }
 
+/*@}*/
 
-/**********************************************************************
- * I/O
- */
 
+/**********************************************************************/
+/** \name I/O */
+/*@{*/
+
+/** Wrapper around either vsprintf() or xf86vsprintf() */
 int
 _mesa_sprintf( char *str, const char *fmt, ... )
 {
@@ -648,7 +677,8 @@ _mesa_sprintf( char *str, const char *fmt, ... )
    return r;
 }
 
-
+/** Wrapper around either printf() or xf86printf(), using vsprintf() for
+ * the formatting. */
 void
 _mesa_printf( const char *fmtString, ... )
 {
@@ -664,11 +694,23 @@ _mesa_printf( const char *fmtString, ... )
 #endif
 }
 
+/*@}*/
 
-/**********************************************************************
- * Diagnostics
- */
 
+/**********************************************************************/
+/** \name Diagnostics */
+/*@{*/
+
+/**
+ * Display a warning.
+ *
+ * \param ctx GL context.
+ * \param fmtString printf() alike format string.
+ * 
+ * If debugging is enabled (either at compile-time via the DEBUG macro, or
+ * run-time via the MESA_DEBUG environment variable), prints the warning to
+ * stderr, either via fprintf() or xf86printf().
+ */
 void
 _mesa_warning( GLcontext *ctx, const char *fmtString, ... )
 {
@@ -693,10 +735,14 @@ _mesa_warning( GLcontext *ctx, const char *fmtString, ... )
    }
 }
 
-
-/*
+/**
  * This function is called when the Mesa user has stumbled into a code
  * path which may not be implemented fully or correctly.
+ *
+ * \param ctx GL context.
+ * \param s problem description string.
+ *
+ * Prints the message to stderr, either via fprintf() or xf86fprintf().
  */
 void
 _mesa_problem( const GLcontext *ctx, const char *fmtString, ... )
@@ -718,13 +764,19 @@ _mesa_problem( const GLcontext *ctx, const char *fmtString, ... )
 #endif
 }
 
-
-/*
- * If in debug mode, print error message to stdout.
+/**
+ * Display an error message.
+ *
+ * If in debug mode, print error message.
  * Also, record the error code by calling _mesa_record_error().
- * Input:  ctx - the GL context
- *         error - the error value
- *         fmtString - printf-style format string, followed by optional args
+ * 
+ * \param ctx the GL context.
+ * \param error the error value.
+ * \param fmtString printf() style format string, followed by optional args
+ *         
+ * If debugging is enabled (either at compile-time via the DEBUG macro, or
+ * run-time via the MESA_DEBUG environment variable), interperts the error code and 
+ * prints the error message via _mesa_debug().
  */
 void
 _mesa_error( GLcontext *ctx, GLenum error, const char *fmtString, ... )
@@ -790,9 +842,13 @@ _mesa_error( GLcontext *ctx, GLenum error, const char *fmtString, ... )
    _mesa_record_error(ctx, error);
 }  
 
-
-/*
- * Call this to report debug information.  Uses stderr.
+/**
+ * Report debug information.
+ * 
+ * \param ctx GL context.
+ * \param fmtString printf() alike format string.
+ * 
+ * Prints the message to stderr, either via fprintf() or xf86printf().
  */
 void
 _mesa_debug( const GLcontext *ctx, const char *fmtString, ... )
@@ -809,12 +865,14 @@ _mesa_debug( const GLcontext *ctx, const char *fmtString, ... )
 #endif
 }
 
+/*@}*/
 
 
 /**********************************************************************/
-/* Default Imports Wrapper                                            */
-/**********************************************************************/
+/** \name Default Imports Wrapper */
+/*@{*/
 
+/** Wrapper around _mesa_malloc() */
 static void *
 default_malloc(__GLcontext *gc, size_t size)
 {
@@ -822,6 +880,7 @@ default_malloc(__GLcontext *gc, size_t size)
    return _mesa_malloc(size);
 }
 
+/** Wrapper around _mesa_malloc() */
 static void *
 default_calloc(__GLcontext *gc, size_t numElem, size_t elemSize)
 {
@@ -829,6 +888,7 @@ default_calloc(__GLcontext *gc, size_t numElem, size_t elemSize)
    return _mesa_calloc(numElem * elemSize);
 }
 
+/** Wrapper around either realloc() or xf86realloc() */
 static void *
 default_realloc(__GLcontext *gc, void *oldAddr, size_t newSize)
 {
@@ -840,6 +900,7 @@ default_realloc(__GLcontext *gc, void *oldAddr, size_t newSize)
 #endif
 }
 
+/** Wrapper around _mesa_free() */
 static void
 default_free(__GLcontext *gc, void *addr)
 {
@@ -847,6 +908,7 @@ default_free(__GLcontext *gc, void *addr)
    _mesa_free(addr);
 }
 
+/** Wrapper around _mesa_getenv() */
 static char * CAPI
 default_getenv( __GLcontext *gc, const char *var )
 {
@@ -854,12 +916,14 @@ default_getenv( __GLcontext *gc, const char *var )
    return _mesa_getenv(var);
 }
 
+/** Wrapper around _mesa_warning() */
 static void
 default_warning(__GLcontext *gc, char *str)
 {
    _mesa_warning(gc, str);
 }
 
+/** Wrapper around _mesa_problem() */
 static void
 default_fatal(__GLcontext *gc, char *str)
 {
@@ -867,6 +931,7 @@ default_fatal(__GLcontext *gc, char *str)
    abort();
 }
 
+/** Wrapper around atoi() */
 static int CAPI
 default_atoi(__GLcontext *gc, const char *str)
 {
@@ -874,6 +939,7 @@ default_atoi(__GLcontext *gc, const char *str)
    return atoi(str);
 }
 
+/** Wrapper around vsprintf() */
 static int CAPI
 default_sprintf(__GLcontext *gc, char *str, const char *fmt, ...)
 {
@@ -885,18 +951,21 @@ default_sprintf(__GLcontext *gc, char *str, const char *fmt, ...)
    return r;
 }
 
+/** Wrapper around fopen() */
 static void * CAPI
 default_fopen(__GLcontext *gc, const char *path, const char *mode)
 {
    return fopen(path, mode);
 }
 
+/** Wrapper around fclose() */
 static int CAPI
 default_fclose(__GLcontext *gc, void *stream)
 {
    return fclose((FILE *) stream);
 }
 
+/** Wrapper around vfprintf() */
 static int CAPI
 default_fprintf(__GLcontext *gc, void *stream, const char *fmt, ...)
 {
@@ -908,22 +977,28 @@ default_fprintf(__GLcontext *gc, void *stream, const char *fmt, ...)
    return r;
 }
 
-/* XXX this really is driver-specific and can't be here */
+/**
+ * \todo this really is driver-specific and can't be here 
+ */
 static __GLdrawablePrivate *
 default_GetDrawablePrivate(__GLcontext *gc)
 {
    return NULL;
 }
 
+/*@}*/
 
 
-
-/*
- * Initialize a __GLimports object to point to the functions in
- * this file.  This is to be called from device drivers.
+/**
+ * Initialize a __GLimports object to point to the functions in this
+ * file.  
+ *
+ * This is to be called from device drivers.
+ * 
  * Also, do some one-time initializations.
- * Input:  imports - the object to init
- *         driverCtx - pointer to device driver-specific data
+ * 
+ * \param imports the object to initialize.
+ * \param driverCtx pointer to device driver-specific data.
  */
 void
 _mesa_init_default_imports(__GLimports *imports, void *driverCtx)
diff --git a/src/mesa/main/imports.h b/src/mesa/main/imports.h
index 0a72da0f47..47cf2312df 100644
--- a/src/mesa/main/imports.h
+++ b/src/mesa/main/imports.h
@@ -1,3 +1,11 @@
+/**
+ * \file imports.h
+ * Standard C library function wrappers.
+ * 
+ * This file provides wrappers for all the standard C library functions
+ * like malloc(), free(), printf(), getenv(), etc.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -23,12 +31,6 @@
  */
 
 
-/*
- * This file provides wrappers for all the standard C library functions
- * like malloc, free, printf, getenv, etc.
- */
-
-
 #ifndef IMPORTS_H
 #define IMPORTS_H
 
@@ -43,46 +45,91 @@ extern "C" {
 #endif
 
 
-/**********************************************************************
- * General macros
- */
+/**********************************************************************/
+/** \name General macros */
+/*@{*/
 
 #ifndef NULL
 #define NULL 0
 #endif
 
+/*@}*/
 
 
-/**********************************************************************
- * Memory macros
- */
+/**********************************************************************/
+/** Memory macros */
+/*@{*/
 
+/** Allocate \p BYTES bytes */
 #define MALLOC(BYTES)      _mesa_malloc(BYTES)
+/** Allocate and zero \p BYTES bytes */
 #define CALLOC(BYTES)      _mesa_calloc(BYTES)
+/** Allocate a structure of type \p T */
 #define MALLOC_STRUCT(T)   (struct T *) _mesa_malloc(sizeof(struct T))
+/** Allocate and zero a structure of type \p T */
 #define CALLOC_STRUCT(T)   (struct T *) _mesa_calloc(sizeof(struct T))
+/** Free memory */
 #define FREE(PTR)          _mesa_free(PTR)
 
+/** Allocate \p BYTES aligned at \p N bytes */
 #define ALIGN_MALLOC(BYTES, N)     _mesa_align_malloc(BYTES, N)
+/** Allocate and zero \p BYTES bytes aligned at \p N bytes */
 #define ALIGN_CALLOC(BYTES, N)     _mesa_align_calloc(BYTES, N)
+/** Allocate a structure of type \p T aligned at \p N bytes */
 #define ALIGN_MALLOC_STRUCT(T, N)  (struct T *) _mesa_align_malloc(sizeof(struct T), N)
+/** Allocate and zero a structure of type \p T aligned at \p N bytes */
 #define ALIGN_CALLOC_STRUCT(T, N)  (struct T *) _mesa_align_calloc(sizeof(struct T), N)
+/** Free aligned memory */
 #define ALIGN_FREE(PTR)            _mesa_align_free(PTR)
 
+/** Copy \p BYTES bytes from \p SRC into \p DST */
 #define MEMCPY( DST, SRC, BYTES)   _mesa_memcpy(DST, SRC, BYTES)
+/** Set \p N bytes in \p DST to \p VAL */
 #define MEMSET( DST, VAL, N )      _mesa_memset(DST, VAL, N)
 
 #define MEMSET16( DST, VAL, N )   _mesa_memset16( (DST), (VAL), (size_t) (N) )
 
+/*@}*/
+
+
+/**********************************************************************/
+/** \name [Pseudo] static array declaration.
+ * 
+ * MACs and BeOS don't support static larger than 32kb, so ... 
+ */
+/*@{*/
+
+/** 
+ * \def DEFARRAY
+ * Define a [static] unidimensional array 
+ */
+
+/** 
+ * \def DEFMARRAY
+ * Define a [static] bi-dimensional array 
+ */
+
+/** 
+ * \def DEFMNARRAY
+ * Define a [static] tri-dimensional array 
+ */
+
+/**
+ * \def CHECKARRAY
+ * Verifies a [static] array was properly allocated.
+ */
+
+/**
+ * \def UNDEFARRAY
+ * Undefine (free) a [static] array.
+ */
 
-/* MACs and BeOS don't support static larger than 32kb, so... */
 #if defined(macintosh) && !defined(__MRC__)
 /*extern char *AGLAlloc(int size);*/
 /*extern void AGLFree(char* ptr);*/
 #  define DEFARRAY(TYPE,NAME,SIZE)  			TYPE *NAME = (TYPE*)_mesa_alloc(sizeof(TYPE)*(SIZE))
 #  define DEFMARRAY(TYPE,NAME,SIZE1,SIZE2)		TYPE (*NAME)[SIZE2] = (TYPE(*)[SIZE2])_mesa_alloc(sizeof(TYPE)*(SIZE1)*(SIZE2))
 #  define DEFMNARRAY(TYPE,NAME,SIZE1,SIZE2,SIZE3)	TYPE (*NAME)[SIZE2][SIZE3] = (TYPE(*)[SIZE2][SIZE3])_mesa_alloc(sizeof(TYPE)*(SIZE1)*(SIZE2)*(SIZE3))
-
 #  define CHECKARRAY(NAME,CMD)				do {if (!(NAME)) {CMD;}} while (0)
 #  define UNDEFARRAY(NAME)          			do {if ((NAME)) {_mesa_free((char*)NAME);}  }while (0)
 #elif defined(__BEOS__)
@@ -99,14 +146,33 @@ extern "C" {
 #  define UNDEFARRAY(NAME)
 #endif
 
+/*@}*/
 
-#ifdef MESA_EXTERNAL_BUFFERALLOC
-/*
- * If you want Mesa's depth/stencil/accum/etc buffers to be allocated
- * with a specialized allocator you can define MESA_EXTERNAL_BUFFERALLOC
- * and implement _ext_mesa_alloc/free_pixelbuffer() in your app.
+
+/**********************************************************************/
+/** \name External pixel buffer allocation.
+ *
+ * If you want Mesa's depth/stencil/accum/etc buffers to be allocated with a
+ * specialized allocator you can define MESA_EXTERNAL_BUFFERALLOC and implement
+ * _ext_mesa_alloc_pixelbuffer() _ext_mesa_free_pixelbuffer() in your
+ * application.
+ * 
+ * \author
  * Contributed by Gerk Huisma (gerk@five-d.demon.nl).
  */
+/*@{*/
+
+/** 
+ * \def MESA_PBUFFER_ALLOC
+ * Allocate a pixel buffer.
+ */
+
+/** 
+ * \def MESA_PBUFFER_FREE
+ * Free a pixel buffer.
+ */
+
+#ifdef MESA_EXTERNAL_BUFFERALLOC
 extern void *_ext_mesa_alloc_pixelbuffer( unsigned int size );
 extern void _ext_mesa_free_pixelbuffer( void *pb );
 
@@ -118,6 +184,8 @@ extern void _ext_mesa_free_pixelbuffer( void *pb );
 #define MESA_PBUFFER_FREE(PTR)     _mesa_align_free(PTR)
 #endif
 
+/*@}*/
+
 
 
 /**********************************************************************
diff --git a/src/mesa/main/light.c b/src/mesa/main/light.c
index 42180ad727..3ef2e3eac1 100644
--- a/src/mesa/main/light.c
+++ b/src/mesa/main/light.c
@@ -610,7 +610,7 @@ void _mesa_update_material( GLcontext *ctx,
    if (ctx->Light.ColorMaterialEnabled)
       bitmask &= ~ctx->Light.ColorMaterialBitmask;
 
-   if (MESA_VERBOSE&VERBOSE_IMMEDIATE)
+   if (MESA_VERBOSE&VERBOSE_IMMEDIATE) 
       _mesa_debug(ctx, "_mesa_update_material, mask 0x%x\n", bitmask);
 
    if (!bitmask)
@@ -1119,7 +1119,7 @@ _mesa_validate_all_lighting_tables( GLcontext *ctx )
 {
    GLint i;
    GLfloat shininess;
-
+   
    shininess = ctx->Light.Material[0].Shininess;
    if (!ctx->_ShineTable[0] || ctx->_ShineTable[0]->shininess != shininess)
       validate_shine_table( ctx, 0, shininess );
@@ -1146,15 +1146,12 @@ void
 _mesa_update_lighting( GLcontext *ctx )
 {
    struct gl_light *light;
-   ctx->_NeedEyeCoords &= ~NEED_EYE_LIGHT;
-   ctx->_NeedNormals &= ~NEED_NORMALS_LIGHT;
+   ctx->Light._NeedEyeCoords = 0;
    ctx->Light._Flags = 0;
 
    if (!ctx->Light.Enabled)
       return;
 
-   ctx->_NeedNormals |= NEED_NORMALS_LIGHT;
-
    foreach(light, &ctx->Light.EnabledList) {
       ctx->Light._Flags |= light->_Flags;
    }
@@ -1164,9 +1161,9 @@ _mesa_update_lighting( GLcontext *ctx )
        ctx->Light.Model.ColorControl == GL_SEPARATE_SPECULAR_COLOR ||
        ctx->Light.Model.LocalViewer);
 
-   if ((ctx->Light._Flags & LIGHT_POSITIONAL) ||
-       ctx->Light.Model.LocalViewer)
-      ctx->_NeedEyeCoords |= NEED_EYE_LIGHT;
+   ctx->Light._NeedEyeCoords = ((ctx->Light._Flags & LIGHT_POSITIONAL) ||
+				ctx->Light.Model.LocalViewer);
+
 
 
    /* XXX: This test is overkill & needs to be fixed both for software and
@@ -1174,7 +1171,7 @@ _mesa_update_lighting( GLcontext *ctx )
     * be tested to verify this.
     */
    if (ctx->Light._NeedVertices)
-      ctx->_NeedEyeCoords |= NEED_EYE_LIGHT;
+      ctx->Light._NeedEyeCoords = GL_TRUE;
 
 
    /* Precompute some shading values.  Although we reference
@@ -1221,7 +1218,7 @@ _mesa_update_lighting( GLcontext *ctx )
  * Update on (_NEW_MODELVIEW | _NEW_LIGHT) when lighting is enabled.
  * Also update on lighting space changes.
  */
-void
+static void
 _mesa_compute_light_positions( GLcontext *ctx )
 {
    struct gl_light *light;
@@ -1290,3 +1287,201 @@ _mesa_compute_light_positions( GLcontext *ctx )
       }
    }
 }
+
+
+
+
+
+static void
+update_modelview_scale( GLcontext *ctx )
+{
+   ctx->_ModelViewInvScale = 1.0F;
+   if (ctx->ModelviewMatrixStack.Top->flags & (MAT_FLAG_UNIFORM_SCALE |
+			       MAT_FLAG_GENERAL_SCALE |
+			       MAT_FLAG_GENERAL_3D |
+			       MAT_FLAG_GENERAL) ) {
+      const GLfloat *m = ctx->ModelviewMatrixStack.Top->inv;
+      GLfloat f = m[2] * m[2] + m[6] * m[6] + m[10] * m[10];
+      if (f < 1e-12) f = 1.0;
+      if (ctx->_NeedEyeCoords)
+	 ctx->_ModelViewInvScale = (GLfloat) INV_SQRTF(f);
+      else
+	 ctx->_ModelViewInvScale = (GLfloat) SQRTF(f);
+   }
+}
+
+
+/* Bring uptodate any state that relies on _NeedEyeCoords.
+ */
+void _mesa_update_tnl_spaces( GLcontext *ctx, GLuint new_state )
+{
+   const GLuint oldneedeyecoords = ctx->_NeedEyeCoords;
+
+   ctx->_NeedEyeCoords = (ctx->_ForceEyeCoords ||
+			  (ctx->Texture._GenFlags & TEXGEN_NEED_EYE_COORD) ||
+			  ctx->Point._Attenuated ||
+			  ctx->Light._NeedEyeCoords);
+      
+   /* Check if the truth-value interpretations of the bitfields have
+    * changed:
+    */
+   if ((oldneedeyecoords == 0) != (ctx->_NeedEyeCoords == 0)) {
+      /* Recalculate all state that depends on _NeedEyeCoords.
+       */
+      update_modelview_scale(ctx);
+      _mesa_compute_light_positions( ctx );
+
+      if (ctx->Driver.LightingSpaceChange)
+	 ctx->Driver.LightingSpaceChange( ctx );
+   }
+   else {
+      GLuint new_state = ctx->NewState;
+
+      /* Recalculate that same state only if it has been invalidated
+       * by other statechanges.
+       */
+      if (new_state & _NEW_MODELVIEW)
+	 update_modelview_scale(ctx);
+
+      if (new_state & (_NEW_LIGHT|_NEW_MODELVIEW))
+	 _mesa_compute_light_positions( ctx );
+   }
+}
+
+
+/* Drivers may need this if the hardware tnl unit doesn't support the
+ * light-in-modelspace optimization.  It's also useful for debugging.
+ */
+void
+_mesa_allow_light_in_model( GLcontext *ctx, GLboolean flag )
+{
+   ctx->_ForceEyeCoords = flag;
+   ctx->NewState |= _NEW_POINT;	/* one of the bits from
+				 * _MESA_NEW_NEED_EYE_COORDS.
+				 */
+}
+
+
+
+/**********************************************************************/
+/*****                      Initialization                        *****/
+/**********************************************************************/
+
+/**
+ * Initialize the n-th light data structure.
+ *
+ * \param l pointer to the gl_light structure to be initialized.
+ * \param n number of the light. 
+ * \note The defaults for light 0 are different than the other lights.
+ */
+static void
+init_light( struct gl_light *l, GLuint n )
+{
+   make_empty_list( l );
+
+   ASSIGN_4V( l->Ambient, 0.0, 0.0, 0.0, 1.0 );
+   if (n==0) {
+      ASSIGN_4V( l->Diffuse, 1.0, 1.0, 1.0, 1.0 );
+      ASSIGN_4V( l->Specular, 1.0, 1.0, 1.0, 1.0 );
+   }
+   else {
+      ASSIGN_4V( l->Diffuse, 0.0, 0.0, 0.0, 1.0 );
+      ASSIGN_4V( l->Specular, 0.0, 0.0, 0.0, 1.0 );
+   }
+   ASSIGN_4V( l->EyePosition, 0.0, 0.0, 1.0, 0.0 );
+   ASSIGN_3V( l->EyeDirection, 0.0, 0.0, -1.0 );
+   l->SpotExponent = 0.0;
+   _mesa_invalidate_spot_exp_table( l );
+   l->SpotCutoff = 180.0;
+   l->_CosCutoff = 0.0;		/* KW: -ve values not admitted */
+   l->ConstantAttenuation = 1.0;
+   l->LinearAttenuation = 0.0;
+   l->QuadraticAttenuation = 0.0;
+   l->Enabled = GL_FALSE;
+}
+
+/**
+ * Initialize the light model data structure.
+ *
+ * \param lm pointer to the gl_lightmodel structure to be initialized.
+ */
+static void
+init_lightmodel( struct gl_lightmodel *lm )
+{
+   ASSIGN_4V( lm->Ambient, 0.2F, 0.2F, 0.2F, 1.0F );
+   lm->LocalViewer = GL_FALSE;
+   lm->TwoSide = GL_FALSE;
+   lm->ColorControl = GL_SINGLE_COLOR;
+}
+
+/**
+ * Initialize the material data structure.
+ * 
+ * \param m pointer to the gl_material structure to be initialized.
+ */
+static void
+init_material( struct gl_material *m )
+{
+   ASSIGN_4V( m->Ambient,  0.2F, 0.2F, 0.2F, 1.0F );
+   ASSIGN_4V( m->Diffuse,  0.8F, 0.8F, 0.8F, 1.0F );
+   ASSIGN_4V( m->Specular, 0.0F, 0.0F, 0.0F, 1.0F );
+   ASSIGN_4V( m->Emission, 0.0F, 0.0F, 0.0F, 1.0F );
+   m->Shininess = 0.0;
+   m->AmbientIndex = 0;
+   m->DiffuseIndex = 1;
+   m->SpecularIndex = 1;
+}
+
+
+void _mesa_init_lighting( GLcontext *ctx )
+{
+   int i;
+
+   /* Lighting group */
+   for (i=0;i<MAX_LIGHTS;i++) {
+      init_light( &ctx->Light.Light[i], i );
+   }
+   make_empty_list( &ctx->Light.EnabledList );
+
+   init_lightmodel( &ctx->Light.Model );
+   init_material( &ctx->Light.Material[0] );
+   init_material( &ctx->Light.Material[1] );
+   ctx->Light.ShadeModel = GL_SMOOTH;
+   ctx->Light.Enabled = GL_FALSE;
+   ctx->Light.ColorMaterialFace = GL_FRONT_AND_BACK;
+   ctx->Light.ColorMaterialMode = GL_AMBIENT_AND_DIFFUSE;
+   ctx->Light.ColorMaterialBitmask = _mesa_material_bitmask( ctx,
+                                               GL_FRONT_AND_BACK,
+                                               GL_AMBIENT_AND_DIFFUSE, ~0, 0 );
+
+   ctx->Light.ColorMaterialEnabled = GL_FALSE;
+
+   /* Lighting miscellaneous */
+   ctx->_ShineTabList = MALLOC_STRUCT( gl_shine_tab );
+   make_empty_list( ctx->_ShineTabList );
+   for (i = 0 ; i < 10 ; i++) {
+      struct gl_shine_tab *s = MALLOC_STRUCT( gl_shine_tab );
+      s->shininess = -1;
+      s->refcount = 0;
+      insert_at_tail( ctx->_ShineTabList, s );
+   }
+
+   
+
+   /* Miscellaneous */
+   ctx->Light._NeedEyeCoords = 0;
+   ctx->_NeedEyeCoords = 0;
+   ctx->_ModelViewInvScale = 1.0;
+}
+
+
+void _mesa_free_lighting_data( GLcontext *ctx )
+{
+   struct gl_shine_tab *s, *tmps;
+
+   /* Free lighting shininess exponentiation table */
+   foreach_s( s, tmps, ctx->_ShineTabList ) {
+      FREE( s );
+   }
+   FREE( ctx->_ShineTabList );
+}
diff --git a/src/mesa/main/light.h b/src/mesa/main/light.h
index 557e488020..240a6317b7 100644
--- a/src/mesa/main/light.h
+++ b/src/mesa/main/light.h
@@ -1,3 +1,7 @@
+/**
+ * \file light.h
+ * Lighting.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -30,10 +34,10 @@
 
 #include "mtypes.h"
 
-
 extern void
 _mesa_ShadeModel( GLenum mode );
 
+#if _HAVE_FULL_GL
 extern void
 _mesa_ColorMaterial( GLenum face, GLenum mode );
 
@@ -91,7 +95,6 @@ do {									\
 } while (0)
 
 
-
 extern GLuint _mesa_material_bitmask( GLcontext *ctx,
                                       GLenum face, GLenum pname,
                                       GLuint legal,
@@ -105,7 +108,7 @@ extern void _mesa_validate_all_lighting_tables( GLcontext *ctx );
 
 extern void _mesa_update_lighting( GLcontext *ctx );
 
-extern void _mesa_compute_light_positions( GLcontext *ctx );
+extern void _mesa_update_tnl_spaces( GLcontext *ctx, GLuint new_state );
 
 extern void _mesa_update_material( GLcontext *ctx,
                                    const struct gl_material src[2],
@@ -118,5 +121,22 @@ extern void _mesa_copy_material_pairs( struct gl_material dst[2],
 extern void _mesa_update_color_material( GLcontext *ctx,
                                          const GLfloat rgba[4] );
 
+extern void _mesa_init_lighting( GLcontext *ctx );
+
+extern void _mesa_free_lighting_data( GLcontext *ctx );
+
+extern void _mesa_allow_light_in_model( GLcontext *ctx, GLboolean flag );
+
+#else
+#define _mesa_update_color_material( c, r ) ((void)0)
+#define _mesa_validate_all_lighting_tables( c ) ((void)0)
+#define _mesa_invalidate_spot_exp_table( l ) ((void)0)
+#define _mesa_material_bitmask( c, f, p, l, s ) 0
+#define _mesa_init_lighting( c ) ((void)0)
+#define _mesa_free_lighting_data( c ) ((void)0)
+#define _mesa_update_lighting( c ) ((void)0)
+#define _mesa_update_tnl_spaces( c, n ) ((void)0)
+#define GET_SHINE_TAB_ENTRY( table, dp, result )  ((result)=0)
+#endif
 
 #endif
diff --git a/src/mesa/main/lines.c b/src/mesa/main/lines.c
index 8a5f59f596..27f778a394 100644
--- a/src/mesa/main/lines.c
+++ b/src/mesa/main/lines.c
@@ -1,3 +1,7 @@
+/**
+ * \file lines.c
+ * Line operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -33,6 +37,19 @@
 #include "mtypes.h"
 
 
+/**
+ * Set the line width.
+ *
+ * \param width line width in pixels.
+ *
+ * \sa glLineWidth().
+ *
+ * Verifies the parameter and updates gl_line_attrib::Width. On a change,
+ * flushes the vertices, updates the clamped line width and marks the
+ * DD_LINE_WIDTH flag in __GLcontextRec::_TriangleCaps for the drivers if the
+ * width is different from one. Notifies the driver via the
+ * dd_function_table::LineWidth callback.
+ */
 void
 _mesa_LineWidth( GLfloat width )
 {
@@ -64,7 +81,18 @@ _mesa_LineWidth( GLfloat width )
 }
 
 
-
+/**
+ * Set the line stipple pattern.
+ *
+ * \param factor pattern scale factor.
+ * \param pattern bit pattern.
+ * 
+ * \sa glLineStipple().
+ *
+ * Updates gl_line_attrib::StippleFactor and gl_line_attrib::StipplePattern. On
+ * change flushes the vertices and notifies the driver via
+ * the dd_function_table::LineStipple callback.
+ */
 void
 _mesa_LineStipple( GLint factor, GLushort pattern )
 {
@@ -84,3 +112,23 @@ _mesa_LineStipple( GLint factor, GLushort pattern )
    if (ctx->Driver.LineStipple)
       ctx->Driver.LineStipple( ctx, factor, pattern );
 }
+
+
+/**
+ * Initialize the context line state.
+ *
+ * \param ctx GL context.
+ *
+ * Initializes __GLcontextRec::Line and line related constants in
+ * __GLcontextRec::Const.
+ */
+void _mesa_init_line( GLcontext * ctx )
+{
+   /* Line group */
+   ctx->Line.SmoothFlag = GL_FALSE;
+   ctx->Line.StippleFlag = GL_FALSE;
+   ctx->Line.Width = 1.0;
+   ctx->Line._Width = 1.0;
+   ctx->Line.StipplePattern = 0xffff;
+   ctx->Line.StippleFactor = 1;
+}
diff --git a/src/mesa/main/lines.h b/src/mesa/main/lines.h
index ac4b33f4db..7305a98647 100644
--- a/src/mesa/main/lines.h
+++ b/src/mesa/main/lines.h
@@ -1,3 +1,7 @@
+/**
+ * \file lines.h
+ * Line operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,6 +28,7 @@
  */
 
 
+
 #ifndef LINES_H
 #define LINES_H
 
@@ -37,5 +42,7 @@ _mesa_LineWidth( GLfloat width );
 extern void
 _mesa_LineStipple( GLint factor, GLushort pattern );
 
+extern void 
+_mesa_init_line( GLcontext * ctx );
 
 #endif
diff --git a/src/mesa/main/macros.h b/src/mesa/main/macros.h
index 9f326a0093..fcb63f53f2 100644
--- a/src/mesa/main/macros.h
+++ b/src/mesa/main/macros.h
@@ -1,3 +1,7 @@
+/**
+ * \file macros.h
+ * A collection of useful macros.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,60 +28,56 @@
  */
 
 
-/*
- * A collection of useful macros.
- */
-
 #ifndef MACROS_H
 #define MACROS_H
 
 #include "imports.h"
 
 
-/*
- * Integer / float conversion for colors, normals, etc.
+/**
+ * \name Integer / float conversion for colors, normals, etc.
  */
+/*@{*/
 
-/* Convert GLubyte in [0,255] to GLfloat in [0.0,1.0] */
+/** Convert GLubyte in [0,255] to GLfloat in [0.0,1.0] */
 extern GLfloat _mesa_ubyte_to_float_color_tab[256];
 #define UBYTE_TO_FLOAT(u) _mesa_ubyte_to_float_color_tab[(unsigned int)(u)]
 
-/* Convert GLfloat in [0.0,1.0] to GLubyte in [0,255] */
+/** Convert GLfloat in [0.0,1.0] to GLubyte in [0,255] */
 #define FLOAT_TO_UBYTE(X)	((GLubyte) (GLint) ((X) * 255.0F))
 
 
-/* Convert GLbyte in [-128,127] to GLfloat in [-1.0,1.0] */
+/** Convert GLbyte in [-128,127] to GLfloat in [-1.0,1.0] */
 #define BYTE_TO_FLOAT(B)	((2.0F * (B) + 1.0F) * (1.0F/255.0F))
 
-/* Convert GLfloat in [-1.0,1.0] to GLbyte in [-128,127] */
+/** Convert GLfloat in [-1.0,1.0] to GLbyte in [-128,127] */
 #define FLOAT_TO_BYTE(X)	( (((GLint) (255.0F * (X))) - 1) / 2 )
 
 
-/* Convert GLushort in [0,65536] to GLfloat in [0.0,1.0] */
+/** Convert GLushort in [0,65536] to GLfloat in [0.0,1.0] */
 #define USHORT_TO_FLOAT(S)	((GLfloat) (S) * (1.0F / 65535.0F))
 
-/* Convert GLfloat in [0.0,1.0] to GLushort in [0,65536] */
+/** Convert GLfloat in [0.0,1.0] to GLushort in [0,65536] */
 #define FLOAT_TO_USHORT(X)	((GLushort) (GLint) ((X) * 65535.0F))
 
-
-/* Convert GLshort in [-32768,32767] to GLfloat in [-1.0,1.0] */
+/** Convert GLshort in [-32768,32767] to GLfloat in [-1.0,1.0] */
 #define SHORT_TO_FLOAT(S)	((2.0F * (S) + 1.0F) * (1.0F/65535.0F))
 
-/* Convert GLfloat in [0.0,1.0] to GLshort in [-32768,32767] */
+/** Convert GLfloat in [0.0,1.0] to GLshort in [-32768,32767] */
 #define FLOAT_TO_SHORT(X)	( (((GLint) (65535.0F * (X))) - 1) / 2 )
 
 
-/* Convert GLuint in [0,4294967295] to GLfloat in [0.0,1.0] */
+/** Convert GLuint in [0,4294967295] to GLfloat in [0.0,1.0] */
 #define UINT_TO_FLOAT(U)	((GLfloat) (U) * (1.0F / 4294967295.0F))
 
-/* Convert GLfloat in [0.0,1.0] to GLuint in [0,4294967295] */
+/** Convert GLfloat in [0.0,1.0] to GLuint in [0,4294967295] */
 #define FLOAT_TO_UINT(X)	((GLuint) ((X) * 4294967295.0))
 
 
-/* Convert GLint in [-2147483648,2147483647] to GLfloat in [-1.0,1.0] */
+/** Convert GLint in [-2147483648,2147483647] to GLfloat in [-1.0,1.0] */
 #define INT_TO_FLOAT(I)		((2.0F * (I) + 1.0F) * (1.0F/4294967294.0F))
 
-/* Convert GLfloat in [-1.0,1.0] to GLint in [-2147483648,2147483647] */
+/** Convert GLfloat in [-1.0,1.0] to GLint in [-2147483648,2147483647] */
 /* causes overflow:
 #define FLOAT_TO_INT(X)		( (((GLint) (4294967294.0F * (X))) - 1) / 2 )
 */
@@ -103,52 +103,41 @@ extern GLfloat _mesa_ubyte_to_float_color_tab[256];
         us = ( (GLushort) IROUND( (f) * 65535.0F) )
 
 
-/* Stepping a GLfloat pointer by a byte stride
- */
+/** Stepping a GLfloat pointer by a byte stride */
 #define STRIDE_F(p, i)  (p = (GLfloat *)((GLubyte *)p + i))
+/** Stepping a GLuint pointer by a byte stride */
 #define STRIDE_UI(p, i)  (p = (GLuint *)((GLubyte *)p + i))
+/** Stepping a GLubyte[4] pointer by a byte stride */
 #define STRIDE_4UB(p, i)  (p = (GLubyte (*)[4])((GLubyte *)p + i))
+/** Stepping a GLchan[4] pointer by a byte stride */
 #define STRIDE_4CHAN(p, i)  (p = (GLchan (*)[4])((GLubyte *)p + i))
+/** Stepping a GLchan pointer by a byte stride */
 #define STRIDE_CHAN(p, i)  (p = (GLchan *)((GLubyte *)p + i))
+/** Stepping a \p t pointer by a byte stride */
 #define STRIDE_T(p, t, i)  (p = (t)((GLubyte *)p + i))
 
 
-#define ZERO_2V( DST )	(DST)[0] = (DST)[1] = 0
-#define ZERO_3V( DST )	(DST)[0] = (DST)[1] = (DST)[2] = 0
-#define ZERO_4V( DST )	(DST)[0] = (DST)[1] = (DST)[2] = (DST)[3] = 0
+/**********************************************************************/
+/** \name 4-element vector operations */
+/*@{*/
 
+/** Zero */
+#define ZERO_4V( DST )	(DST)[0] = (DST)[1] = (DST)[2] = (DST)[3] = 0
 
+/** Test for equality */
 #define TEST_EQ_4V(a,b)  ((a)[0] == (b)[0] && 	\
 			  (a)[1] == (b)[1] &&	\
 			  (a)[2] == (b)[2] &&	\
 			  (a)[3] == (b)[3])
 
-#define TEST_EQ_3V(a,b)  ((a)[0] == (b)[0] && 	\
-			  (a)[1] == (b)[1] &&	\
-			  (a)[2] == (b)[2])
-
+/** Test for equality (unsigned bytes) */
 #if defined(__i386__)
 #define TEST_EQ_4UBV(DST, SRC) *((GLuint*)(DST)) == *((GLuint*)(SRC))
 #else
 #define TEST_EQ_4UBV(DST, SRC) TEST_EQ_4V(DST, SRC)
 #endif
 
-
-
-/* Copy short vectors: */
-#define COPY_2V( DST, SRC )			\
-do {						\
-   (DST)[0] = (SRC)[0];				\
-   (DST)[1] = (SRC)[1];				\
-} while (0)
-
-#define COPY_3V( DST, SRC )			\
-do {						\
-   (DST)[0] = (SRC)[0];				\
-   (DST)[1] = (SRC)[1];				\
-   (DST)[2] = (SRC)[2];				\
-} while (0)
-
+/** Copy a 4-element vector */
 #define COPY_4V( DST, SRC )			\
 do {						\
    (DST)[0] = (SRC)[0];				\
@@ -157,19 +146,7 @@ do {						\
    (DST)[3] = (SRC)[3];				\
 } while (0)
 
-#define COPY_2V_CAST( DST, SRC, CAST )		\
-do {						\
-   (DST)[0] = (CAST)(SRC)[0];			\
-   (DST)[1] = (CAST)(SRC)[1];			\
-} while (0)
-
-#define COPY_3V_CAST( DST, SRC, CAST )		\
-do {						\
-   (DST)[0] = (CAST)(SRC)[0];			\
-   (DST)[1] = (CAST)(SRC)[1];			\
-   (DST)[2] = (CAST)(SRC)[2];			\
-} while (0)
-
+/** Copy a 4-element vector with cast */
 #define COPY_4V_CAST( DST, SRC, CAST )		\
 do {						\
    (DST)[0] = (CAST)(SRC)[0];			\
@@ -178,6 +155,7 @@ do {						\
    (DST)[3] = (CAST)(SRC)[3];			\
 } while (0)
 
+/** Copy a 4-element unsigned byte vector */
 #if defined(__i386__)
 #define COPY_4UBV(DST, SRC)			\
 do {						\
@@ -194,21 +172,7 @@ do {						\
 } while (0)
 #endif
 
-#define COPY_2FV( DST, SRC )			\
-do {						\
-   const GLfloat *_tmp = (SRC);			\
-   (DST)[0] = _tmp[0];				\
-   (DST)[1] = _tmp[1];				\
-} while (0)
-
-#define COPY_3FV( DST, SRC )			\
-do {						\
-   const GLfloat *_tmp = (SRC);			\
-   (DST)[0] = _tmp[0];				\
-   (DST)[1] = _tmp[1];				\
-   (DST)[2] = _tmp[2];				\
-} while (0)
-
+/** Copy a 4-element float vector */
 #define COPY_4FV( DST, SRC )			\
 do {						\
    const GLfloat *_tmp = (SRC);			\
@@ -219,7 +183,7 @@ do {						\
 } while (0)
 
 
-
+/** Copy \p SZ elements into a 4-element vector */
 #define COPY_SZ_4V(DST, SZ, SRC) 		\
 do {						\
    switch (SZ) {				\
@@ -230,12 +194,15 @@ do {						\
    }  						\
 } while(0)
 
+/** Copy \p SZ elements into a homegeneous (4-element) vector, giving
+ * default values to the remaining */
 #define COPY_CLEAN_4V(DST, SZ, SRC) 		\
 do {						\
       ASSIGN_4V( DST, 0, 0, 0, 1 );		\
       COPY_SZ_4V( DST, SZ, SRC );		\
 } while (0)
 
+/** Subtraction */
 #define SUB_4V( DST, SRCA, SRCB )		\
 do {						\
       (DST)[0] = (SRCA)[0] - (SRCB)[0];		\
@@ -244,6 +211,7 @@ do {						\
       (DST)[3] = (SRCA)[3] - (SRCB)[3];		\
 } while (0)
 
+/** Addition */
 #define ADD_4V( DST, SRCA, SRCB )		\
 do {						\
       (DST)[0] = (SRCA)[0] + (SRCB)[0];		\
@@ -252,6 +220,7 @@ do {						\
       (DST)[3] = (SRCA)[3] + (SRCB)[3];		\
 } while (0)
 
+/** Element-wise multiplication */
 #define SCALE_4V( DST, SRCA, SRCB )		\
 do {						\
       (DST)[0] = (SRCA)[0] * (SRCB)[0];		\
@@ -260,6 +229,7 @@ do {						\
       (DST)[3] = (SRCA)[3] * (SRCB)[3];		\
 } while (0)
 
+/** In-place addition */
 #define ACC_4V( DST, SRC )			\
 do {						\
       (DST)[0] += (SRC)[0];			\
@@ -268,6 +238,7 @@ do {						\
       (DST)[3] += (SRC)[3];			\
 } while (0)
 
+/** Element-wise multiplication and addition */
 #define ACC_SCALE_4V( DST, SRCA, SRCB )		\
 do {						\
       (DST)[0] += (SRCA)[0] * (SRCB)[0];	\
@@ -276,6 +247,7 @@ do {						\
       (DST)[3] += (SRCA)[3] * (SRCB)[3];	\
 } while (0)
 
+/** In-place scalar multiplication and addition */
 #define ACC_SCALE_SCALAR_4V( DST, S, SRCB )	\
 do {						\
       (DST)[0] += S * (SRCB)[0];		\
@@ -284,6 +256,7 @@ do {						\
       (DST)[3] += S * (SRCB)[3];		\
 } while (0)
 
+/** Scalar multiplication */
 #define SCALE_SCALAR_4V( DST, S, SRCB )		\
 do {						\
       (DST)[0] = S * (SRCB)[0];			\
@@ -292,7 +265,7 @@ do {						\
       (DST)[3] = S * (SRCB)[3];			\
 } while (0)
 
-
+/** In-place scalar multiplication */
 #define SELF_SCALE_SCALAR_4V( DST, S )		\
 do {						\
       (DST)[0] *= S;				\
@@ -301,10 +274,56 @@ do {						\
       (DST)[3] *= S;				\
 } while (0)
 
+/** Assignment */
+#define ASSIGN_4V( V, V0, V1, V2, V3 ) 		\
+do { 						\
+    V[0] = V0;					\
+    V[1] = V1;					\
+    V[2] = V2;					\
+    V[3] = V3; 					\
+} while(0)
 
-/*
- * Similarly for 3-vectors.
- */
+/*@}*/
+
+
+/**********************************************************************/
+/** \name 3-element vector operations*/
+/*@{*/
+
+/** Zero */
+#define ZERO_3V( DST )	(DST)[0] = (DST)[1] = (DST)[2] = 0
+
+/** Test for equality */
+#define TEST_EQ_3V(a,b)  ((a)[0] == (b)[0] && 	\
+			  (a)[1] == (b)[1] &&	\
+			  (a)[2] == (b)[2])
+
+/** Copy a 3-element vector */
+#define COPY_3V( DST, SRC )			\
+do {						\
+   (DST)[0] = (SRC)[0];				\
+   (DST)[1] = (SRC)[1];				\
+   (DST)[2] = (SRC)[2];				\
+} while (0)
+
+/** Copy a 3-element vector with cast */
+#define COPY_3V_CAST( DST, SRC, CAST )		\
+do {						\
+   (DST)[0] = (CAST)(SRC)[0];			\
+   (DST)[1] = (CAST)(SRC)[1];			\
+   (DST)[2] = (CAST)(SRC)[2];			\
+} while (0)
+
+/** Copy a 3-element float vector */
+#define COPY_3FV( DST, SRC )			\
+do {						\
+   const GLfloat *_tmp = (SRC);			\
+   (DST)[0] = _tmp[0];				\
+   (DST)[1] = _tmp[1];				\
+   (DST)[2] = _tmp[2];				\
+} while (0)
+
+/** Subtraction */
 #define SUB_3V( DST, SRCA, SRCB )		\
 do {						\
       (DST)[0] = (SRCA)[0] - (SRCB)[0];		\
@@ -312,6 +331,7 @@ do {						\
       (DST)[2] = (SRCA)[2] - (SRCB)[2];		\
 } while (0)
 
+/** Addition */
 #define ADD_3V( DST, SRCA, SRCB )		\
 do {						\
       (DST)[0] = (SRCA)[0] + (SRCB)[0];		\
@@ -319,6 +339,7 @@ do {						\
       (DST)[2] = (SRCA)[2] + (SRCB)[2];		\
 } while (0)
 
+/** In-place scalar multiplication */
 #define SCALE_3V( DST, SRCA, SRCB )		\
 do {						\
       (DST)[0] = (SRCA)[0] * (SRCB)[0];		\
@@ -326,6 +347,7 @@ do {						\
       (DST)[2] = (SRCA)[2] * (SRCB)[2];		\
 } while (0)
 
+/** In-place element-wise multiplication */
 #define SELF_SCALE_3V( DST, SRC )		\
 do {						\
       (DST)[0] *= (SRC)[0];			\
@@ -333,6 +355,7 @@ do {						\
       (DST)[2] *= (SRC)[2];			\
 } while (0)
 
+/** In-place addition */
 #define ACC_3V( DST, SRC )			\
 do {						\
       (DST)[0] += (SRC)[0];			\
@@ -340,6 +363,7 @@ do {						\
       (DST)[2] += (SRC)[2];			\
 } while (0)
 
+/** Element-wise multiplication and addition */
 #define ACC_SCALE_3V( DST, SRCA, SRCB )		\
 do {						\
       (DST)[0] += (SRCA)[0] * (SRCB)[0];	\
@@ -347,6 +371,7 @@ do {						\
       (DST)[2] += (SRCA)[2] * (SRCB)[2];	\
 } while (0)
 
+/** Scalar multiplication */
 #define SCALE_SCALAR_3V( DST, S, SRCB ) 	\
 do {						\
       (DST)[0] = S * (SRCB)[0];			\
@@ -354,6 +379,7 @@ do {						\
       (DST)[2] = S * (SRCB)[2];			\
 } while (0)
 
+/** In-place scalar multiplication and addition */
 #define ACC_SCALE_SCALAR_3V( DST, S, SRCB )	\
 do {						\
       (DST)[0] += S * (SRCB)[0];		\
@@ -361,6 +387,7 @@ do {						\
       (DST)[2] += S * (SRCB)[2];		\
 } while (0)
 
+/** In-place scalar multiplication */
 #define SELF_SCALE_SCALAR_3V( DST, S )		\
 do {						\
       (DST)[0] *= S;				\
@@ -368,6 +395,7 @@ do {						\
       (DST)[2] *= S;				\
 } while (0)
 
+/** In-place scalar addition */
 #define ACC_SCALAR_3V( DST, S ) 		\
 do {						\
       (DST)[0] += S;				\
@@ -375,56 +403,103 @@ do {						\
       (DST)[2] += S;				\
 } while (0)
 
-/* And also for 2-vectors
- */
+/** Assignment */
+#define ASSIGN_3V( V, V0, V1, V2 )	\
+do { 				 	\
+    V[0] = V0; 				\
+    V[1] = V1; 				\
+    V[2] = V2; 				\
+} while(0)
+
+/*@}*/
+
+
+/**********************************************************************/
+/** \name 2-element vector operations*/
+/*@{*/
+
+/** Zero */
+#define ZERO_2V( DST )	(DST)[0] = (DST)[1] = 0
+
+/** Copy a 2-element vector */
+#define COPY_2V( DST, SRC )			\
+do {						\
+   (DST)[0] = (SRC)[0];				\
+   (DST)[1] = (SRC)[1];				\
+} while (0)
+
+/** Copy a 2-element vector with cast */
+#define COPY_2V_CAST( DST, SRC, CAST )		\
+do {						\
+   (DST)[0] = (CAST)(SRC)[0];			\
+   (DST)[1] = (CAST)(SRC)[1];			\
+} while (0)
+
+/** Copy a 2-element float vector */
+#define COPY_2FV( DST, SRC )			\
+do {						\
+   const GLfloat *_tmp = (SRC);			\
+   (DST)[0] = _tmp[0];				\
+   (DST)[1] = _tmp[1];				\
+} while (0)
+
+/** Subtraction */
 #define SUB_2V( DST, SRCA, SRCB )		\
 do {						\
       (DST)[0] = (SRCA)[0] - (SRCB)[0];		\
       (DST)[1] = (SRCA)[1] - (SRCB)[1];		\
 } while (0)
 
+/** Addition */
 #define ADD_2V( DST, SRCA, SRCB )		\
 do {						\
       (DST)[0] = (SRCA)[0] + (SRCB)[0];		\
       (DST)[1] = (SRCA)[1] + (SRCB)[1];		\
 } while (0)
 
+/** In-place scalar multiplication */
 #define SCALE_2V( DST, SRCA, SRCB )		\
 do {						\
       (DST)[0] = (SRCA)[0] * (SRCB)[0];		\
       (DST)[1] = (SRCA)[1] * (SRCB)[1];		\
 } while (0)
 
+/** In-place addition */
 #define ACC_2V( DST, SRC )			\
 do {						\
       (DST)[0] += (SRC)[0];			\
       (DST)[1] += (SRC)[1];			\
 } while (0)
 
+/** Element-wise multiplication and addition */
 #define ACC_SCALE_2V( DST, SRCA, SRCB )		\
 do {						\
       (DST)[0] += (SRCA)[0] * (SRCB)[0];	\
       (DST)[1] += (SRCA)[1] * (SRCB)[1];	\
 } while (0)
 
+/** Scalar multiplication */
 #define SCALE_SCALAR_2V( DST, S, SRCB ) 	\
 do {						\
       (DST)[0] = S * (SRCB)[0];			\
       (DST)[1] = S * (SRCB)[1];			\
 } while (0)
 
+/** In-place scalar multiplication and addition */
 #define ACC_SCALE_SCALAR_2V( DST, S, SRCB )	\
 do {						\
       (DST)[0] += S * (SRCB)[0];		\
       (DST)[1] += S * (SRCB)[1];		\
 } while (0)
 
+/** In-place scalar multiplication */
 #define SELF_SCALE_SCALAR_2V( DST, S )		\
 do {						\
       (DST)[0] *= S;				\
       (DST)[1] *= S;				\
 } while (0)
 
+/** In-place scalar addition */
 #define ACC_SCALAR_2V( DST, S ) 		\
 do {						\
       (DST)[0] += S;				\
@@ -433,14 +508,15 @@ do {						\
 
 
 
-/*
+/**
  * Linear interpolation
- * NOTE:  OUT argument is evaluated twice!
- * NOTE:  Be wary of using *coord++ as an argument to any of these macros!
+ *
+ * \note \p OUT argument is evaluated twice!
+ * \note Be wary of using *coord++ as an argument to any of these macros!
  */
 #define LINTERP(T, OUT, IN)	((OUT) + (T) * ((IN) - (OUT)))
 
-/* Can do better with integer math:
+/* Can do better with integer math
  */
 #define INTERP_UB( t, dstub, outub, inub )	\
 do {						\
@@ -506,58 +582,47 @@ do {									\
 
 
 
-/* Assign scalers to short vectors: */
+/** Assign scalers to short vectors */
 #define ASSIGN_2V( V, V0, V1 )	\
 do { 				\
     V[0] = V0; 			\
     V[1] = V1; 			\
 } while(0)
 
-#define ASSIGN_3V( V, V0, V1, V2 )	\
-do { 				 	\
-    V[0] = V0; 				\
-    V[1] = V1; 				\
-    V[2] = V2; 				\
-} while(0)
-
-#define ASSIGN_4V( V, V0, V1, V2, V3 ) 		\
-do { 						\
-    V[0] = V0;					\
-    V[1] = V1;					\
-    V[2] = V2;					\
-    V[3] = V3; 					\
-} while(0)
+/*@}*/
 
 
 
-/* Clamp X to [MIN,MAX]: */
+/** Clamp X to [MIN,MAX] */
 #define CLAMP( X, MIN, MAX )  ( (X)<(MIN) ? (MIN) : ((X)>(MAX) ? (MAX) : (X)) )
 
-/* Assign X to CLAMP(X, MIN, MAX) */
+/** Assign X to CLAMP(X, MIN, MAX) */
 #define CLAMP_SELF(x, mn, mx)  \
    ( (x)<(mn) ? ((x) = (mn)) : ((x)>(mx) ? ((x)=(mx)) : (x)) )
 
 
 
-/* Min of two values: */
+/** Minimum of two values: */
 #define MIN2( A, B )   ( (A)<(B) ? (A) : (B) )
 
-/* MAX of two values: */
+/** Maximum of two values: */
 #define MAX2( A, B )   ( (A)>(B) ? (A) : (B) )
 
-/* Dot product of two 2-element vectors */
+/** Dot product of two 2-element vectors */
 #define DOT2( a, b )  ( (a)[0]*(b)[0] + (a)[1]*(b)[1] )
 
-/* Dot product of two 3-element vectors */
+/** Dot product of two 3-element vectors */
 #define DOT3( a, b )  ( (a)[0]*(b)[0] + (a)[1]*(b)[1] + (a)[2]*(b)[2] )
 
-/* Dot product of two 4-element vectors */
+/** Dot product of two 4-element vectors */
 #define DOT4( a, b )  ( (a)[0]*(b)[0] + (a)[1]*(b)[1] + \
 			(a)[2]*(b)[2] + (a)[3]*(b)[3] )
 
+/** Dot product of two 4-element vectors */
 #define DOT4V(v,a,b,c,d) (v[0]*(a) + v[1]*(b) + v[2]*(c) + v[3]*(d))
 
 
+/** Cross product of two 3-element vectors */
 #define CROSS3(n, u, v) 			\
 do {						\
    (n)[0] = (u)[1]*(v)[2] - (u)[2]*(v)[1]; 	\
@@ -585,5 +650,7 @@ do {						\
 #define LEN_SQUARED_2FV( V ) ((V)[0]*(V)[0]+(V)[1]*(V)[1])
 
 
+/*@}*/
+
 
 #endif
diff --git a/src/mesa/main/matrix.c b/src/mesa/main/matrix.c
index 244b04ca40..7e2d91e631 100644
--- a/src/mesa/main/matrix.c
+++ b/src/mesa/main/matrix.c
@@ -1,3 +1,13 @@
+/**
+ * \file matrix.c
+ * Matrix operations.
+ *
+ * \note
+ * -# 4x4 transformation matrices are stored in memory in column major order.
+ * -# Points/vertices are to be thought of as column vectors.
+ * -# Transformation of a point p by a matrix M is: p' = M * p
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -23,16 +33,6 @@
  */
 
 
-/*
- * Matrix operations
- *
- * NOTES:
- * 1. 4x4 transformation matrices are stored in memory in column major order.
- * 2. Points/vertices are to be thought of as column vectors.
- * 3. Transformation of a point p by a matrix M is: p' = M * p
- */
-
-
 #include "glheader.h"
 #include "imports.h"
 #include "buffers.h"
@@ -44,7 +44,22 @@
 #include "math/m_matrix.h"
 
 
-
+/**
+ * Apply a perspective projection matrix.
+ *
+ * \param left left clipping plane coordinate.
+ * \param right right clipping plane coordinate.
+ * \param bottom bottom clipping plane coordinate.
+ * \param top top clipping plane coordinate.
+ * \param nearval distance to the near clipping plane.
+ * \param farval distance to the far clipping plane.
+ *
+ * \sa glFrustum().
+ *
+ * Flushes vertices and validates parameters. Calls _math_matrix_frustum() with
+ * the top matrix of the current matrix stack and sets
+ * __GLcontextRec::NewState.
+ */
 void
 _mesa_Frustum( GLdouble left, GLdouble right,
                GLdouble bottom, GLdouble top,
@@ -71,6 +86,22 @@ _mesa_Frustum( GLdouble left, GLdouble right,
 }
 
 
+/**
+ * Apply an orthographic projection matrix.
+ *
+ * \param left left clipping plane coordinate.
+ * \param right right clipping plane coordinate.
+ * \param bottom bottom clipping plane coordinate.
+ * \param top top clipping plane coordinate.
+ * \param nearval distance to the near clipping plane.
+ * \param farval distance to the far clipping plane.
+ *
+ * \sa glOrtho().
+ *
+ * Flushes vertices and validates parameters. Calls _math_matrix_ortho() with
+ * the top matrix of the current matrix stack and sets
+ * __GLcontextRec::NewState.
+ */
 void
 _mesa_Ortho( GLdouble left, GLdouble right,
              GLdouble bottom, GLdouble top,
@@ -99,6 +130,17 @@ _mesa_Ortho( GLdouble left, GLdouble right,
 }
 
 
+/**
+ * Set the current matrix stack.
+ *
+ * \param mode matrix stack.
+ *
+ * \sa glMatrixMode().
+ *
+ * Flushes the vertices, validates the parameter and updates
+ * __GLcontextRec::CurrentStack and gl_transform_attrib::MatrixMode with the
+ * specified matrix stack.
+ */
 void
 _mesa_MatrixMode( GLenum mode )
 {
@@ -170,7 +212,15 @@ _mesa_MatrixMode( GLenum mode )
 }
 
 
-
+/**
+ * Push the current matrix stack.
+ *
+ * \sa glPushMatrix().
+ * 
+ * Verifies the current matrix stack is not full, and duplicates the top-most
+ * matrix in the stack. Marks __GLcontextRec::NewState with the stack dirty
+ * flag.
+ */
 void
 _mesa_PushMatrix( void )
 {
@@ -194,7 +244,15 @@ _mesa_PushMatrix( void )
 }
 
 
-
+/**
+ * Pop the current matrix stack.
+ *
+ * \sa glPopMatrix().
+ * 
+ * Flushes the vertices, verifies the current matrix stack is not empty, and
+ * moves the stack head down. Marks __GLcontextRec::NewState with the dirty
+ * stack flag.
+ */
 void
 _mesa_PopMatrix( void )
 {
@@ -216,7 +274,15 @@ _mesa_PopMatrix( void )
 }
 
 
-
+/**
+ * Replace the current matrix with the identity matrix.
+ *
+ * \sa glLoadIdentity().
+ *
+ * Flushes the vertices and calls _math_matrix_set_identity() with the top-most
+ * matrix in the current stack. Marks __GLcontextRec::NewState with the stack
+ * dirty flag.
+ */
 void
 _mesa_LoadIdentity( void )
 {
@@ -231,6 +297,17 @@ _mesa_LoadIdentity( void )
 }
 
 
+/**
+ * Replace the current matrix with a given matrix.
+ *
+ * \param m matrix.
+ *
+ * \sa glLoadMatrixf().
+ *
+ * Flushes the vertices and calls _math_matrix_loadf() with the top-most matrix
+ * in the current stack and the given matrix. Marks __GLcontextRec::NewState
+ * with the dirty stack flag.
+ */
 void
 _mesa_LoadMatrixf( const GLfloat *m )
 {
@@ -250,21 +327,16 @@ _mesa_LoadMatrixf( const GLfloat *m )
 }
 
 
-void
-_mesa_LoadMatrixd( const GLdouble *m )
-{
-   GLint i;
-   GLfloat f[16];
-   if (!m) return;
-   for (i = 0; i < 16; i++)
-      f[i] = (GLfloat) m[i];
-   _mesa_LoadMatrixf(f);
-}
-
-
-
-/*
- * Multiply the active matrix by an arbitary matrix.
+/**
+ * Multiply the current matrix with a given matrix.
+ *
+ * \param m matrix.
+ *
+ * \sa glMultMatrixf().
+ *
+ * Flushes the vertices and calls _math_matrix_mul_floats() with the top-most
+ * matrix in the current stack and the given matrix. Marks
+ * __GLcontextRec::NewState with the dirty stack flag.
  */
 void
 _mesa_MultMatrixf( const GLfloat *m )
@@ -284,25 +356,19 @@ _mesa_MultMatrixf( const GLfloat *m )
 }
 
 
-/*
- * Multiply the active matrix by an arbitary matrix.
- */
-void
-_mesa_MultMatrixd( const GLdouble *m )
-{
-   GLint i;
-   GLfloat f[16];
-   if (!m) return;
-   for (i = 0; i < 16; i++)
-      f[i] = (GLfloat) m[i];
-   _mesa_MultMatrixf( f );
-}
-
-
-
-
-/*
- * Execute a glRotate call
+/**
+ * Multiply the current matrix with a rotation matrix.
+ *
+ * \param angle angle of rotation, in degrees.
+ * \param x rotation vector x coordinate.
+ * \param y rotation vector y coordinate.
+ * \param z rotation vector z coordinate.
+ *
+ * \sa glRotatef().
+ *
+ * Flushes the vertices and calls _math_matrix_rotate() with the top-most
+ * matrix in the current stack and the given parameters. Marks
+ * __GLcontextRec::NewState with the dirty stack flag.
  */
 void
 _mesa_Rotatef( GLfloat angle, GLfloat x, GLfloat y, GLfloat z )
@@ -315,43 +381,88 @@ _mesa_Rotatef( GLfloat angle, GLfloat x, GLfloat y, GLfloat z )
    }
 }
 
+
+/**
+ * Multiply the current matrix with a general scaling matrix.
+ *
+ * \param x x axis scale factor.
+ * \param y y axis scale factor.
+ * \param z z axis scale factor.
+ *
+ * \sa glScalef().
+ *
+ * Flushes the vertices and calls _math_matrix_scale() with the top-most
+ * matrix in the current stack and the given parameters. Marks
+ * __GLcontextRec::NewState with the dirty stack flag.
+ */
 void
-_mesa_Rotated( GLdouble angle, GLdouble x, GLdouble y, GLdouble z )
+_mesa_Scalef( GLfloat x, GLfloat y, GLfloat z )
 {
-   _mesa_Rotatef((GLfloat) angle, (GLfloat) x, (GLfloat) y, (GLfloat) z);
+   GET_CURRENT_CONTEXT(ctx);
+   ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH(ctx);
+   _math_matrix_scale( ctx->CurrentStack->Top, x, y, z);
+   ctx->NewState |= ctx->CurrentStack->DirtyFlag;
 }
 
 
-/*
- * Execute a glScale call
+/**
+ * Multiply the current matrix with a general scaling matrix.
+ *
+ * \param x translation vector x coordinate.
+ * \param y translation vector y coordinate.
+ * \param z translation vector z coordinate.
+ *
+ * \sa glTranslatef().
+ *
+ * Flushes the vertices and calls _math_matrix_translate() with the top-most
+ * matrix in the current stack and the given parameters. Marks
+ * __GLcontextRec::NewState with the dirty stack flag.
  */
 void
-_mesa_Scalef( GLfloat x, GLfloat y, GLfloat z )
+_mesa_Translatef( GLfloat x, GLfloat y, GLfloat z )
 {
    GET_CURRENT_CONTEXT(ctx);
    ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH(ctx);
-   _math_matrix_scale( ctx->CurrentStack->Top, x, y, z);
+   _math_matrix_translate( ctx->CurrentStack->Top, x, y, z);
    ctx->NewState |= ctx->CurrentStack->DirtyFlag;
 }
 
+ 
+#if _HAVE_FULL_GL
+void
+_mesa_LoadMatrixd( const GLdouble *m )
+{
+   GLint i;
+   GLfloat f[16];
+   if (!m) return;
+   for (i = 0; i < 16; i++)
+      f[i] = (GLfloat) m[i];
+   _mesa_LoadMatrixf(f);
+}
 
 void
-_mesa_Scaled( GLdouble x, GLdouble y, GLdouble z )
+_mesa_MultMatrixd( const GLdouble *m )
 {
-   _mesa_Scalef((GLfloat) x, (GLfloat) y, (GLfloat) z);
+   GLint i;
+   GLfloat f[16];
+   if (!m) return;
+   for (i = 0; i < 16; i++)
+      f[i] = (GLfloat) m[i];
+   _mesa_MultMatrixf( f );
 }
 
 
-/*
- * Execute a glTranslate call
- */
 void
-_mesa_Translatef( GLfloat x, GLfloat y, GLfloat z )
+_mesa_Rotated( GLdouble angle, GLdouble x, GLdouble y, GLdouble z )
 {
-   GET_CURRENT_CONTEXT(ctx);
-   ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH(ctx);
-   _math_matrix_translate( ctx->CurrentStack->Top, x, y, z);
-   ctx->NewState |= ctx->CurrentStack->DirtyFlag;
+   _mesa_Rotatef((GLfloat) angle, (GLfloat) x, (GLfloat) y, (GLfloat) z);
+}
+
+
+void
+_mesa_Scaled( GLdouble x, GLdouble y, GLdouble z )
+{
+   _mesa_Scalef((GLfloat) x, (GLfloat) y, (GLfloat) z);
 }
 
 
@@ -360,8 +471,10 @@ _mesa_Translated( GLdouble x, GLdouble y, GLdouble z )
 {
    _mesa_Translatef((GLfloat) x, (GLfloat) y, (GLfloat) z);
 }
+#endif
 
 
+#if _HAVE_FULL_GL
 void
 _mesa_LoadTransposeMatrixfARB( const GLfloat *m )
 {
@@ -400,10 +513,19 @@ _mesa_MultTransposeMatrixdARB( const GLdouble *m )
    _math_transposefd(tm, m);
    _mesa_MultMatrixf(tm);
 }
+#endif
 
-
-/*
- * Called via glViewport or display list execution.
+/**
+ * Set the viewport.
+ * 
+ * \param x, y coordinates of the lower-left corner of the viewport rectangle.
+ * \param width width of the viewport rectangle.
+ * \param height height of the viewport rectangle.
+ *
+ * \sa Called via glViewport() or display list execution.
+ *
+ * Flushes the vertices and calls _mesa_set_viewport() with the given
+ * parameters.
  */
 void
 _mesa_Viewport( GLint x, GLint y, GLsizei width, GLsizei height )
@@ -413,14 +535,24 @@ _mesa_Viewport( GLint x, GLint y, GLsizei width, GLsizei height )
    _mesa_set_viewport(ctx, x, y, width, height);
 }
 
-
 /**
  * Set new viewport parameters and update derived state (the _WindowMap
  * matrix).  Usually called from _mesa_Viewport().
+ * 
  * \note  We also call _mesa_ResizeBuffersMESA() because this is a good
  * time to check if the window has been resized.  Many device drivers
  * can't get direct notification from the window system of size changes
  * so this is an ad-hoc solution to that problem.
+ * 
+ * \param ctx GL context.
+ * \param x, y coordinates of the lower left corner of the viewport rectangle.
+ * \param width width of the viewport rectangle.
+ * \param height height of the viewport rectangle.
+ *
+ * Verifies the parameters, clamps them to the implementation dependent range
+ * and updates __GLcontextRec::Viewport. Computes the scale and bias values for
+ * the drivers and notifies the driver via the dd_function_table::Viewport
+ * callback.
  */
 void
 _mesa_set_viewport( GLcontext *ctx, GLint x, GLint y,
@@ -448,8 +580,24 @@ _mesa_set_viewport( GLcontext *ctx, GLint x, GLint y,
    ctx->Viewport.Y = y;
    ctx->Viewport.Height = height;
 
+   /* Check if window/buffer has been resized and if so, reallocate the
+    * ancillary buffers.
+    */
+/*    _mesa_ResizeBuffersMESA(); */
+
+   if (ctx->Driver.Viewport) {
+      (*ctx->Driver.Viewport)( ctx, x, y, width, height );
+   }
+
+   if (ctx->_RotateMode) {
+      GLint tmp, tmps;
+      tmp = x; x = y; y = tmp;
+      tmps = width; width = height; height = tmps;
+   }
+
    /* compute scale and bias values :: This is really driver-specific
-    * and should be maintained elsewhere if at all.
+    * and should be maintained elsewhere if at all.  NOTE: RasterPos
+    * uses this.
     */
    ctx->Viewport._WindowMap.m[MAT_SX] = (GLfloat) width / 2.0F;
    ctx->Viewport._WindowMap.m[MAT_TX] = ctx->Viewport._WindowMap.m[MAT_SX] + x;
@@ -475,7 +623,7 @@ _mesa_set_viewport( GLcontext *ctx, GLint x, GLint y,
 }
 
 
-
+#if _HAVE_FULL_GL
 void
 _mesa_DepthRange( GLclampd nearval, GLclampd farval )
 {
@@ -510,3 +658,280 @@ _mesa_DepthRange( GLclampd nearval, GLclampd farval )
       (*ctx->Driver.DepthRange)( ctx, nearval, farval );
    }
 }
+#endif
+
+
+
+/**********************************************************************/
+/** \name State management */
+/*@{*/
+
+
+/**
+ * Update the projection matrix stack.
+ *
+ * \param ctx GL context.
+ *
+ * Calls _math_matrix_analyse() with the top-matrix of the projection matrix
+ * stack, and recomputes user clip positions if necessary.
+ * 
+ * \note This routine references __GLcontextRec::Tranform attribute values to
+ * compute userclip positions in clip space, but is only called on
+ * _NEW_PROJECTION.  The _mesa_ClipPlane() function keeps these values up to
+ * date across changes to the __GLcontextRec::Transform attributes.
+ */
+static void
+update_projection( GLcontext *ctx )
+{
+   _math_matrix_analyse( ctx->ProjectionMatrixStack.Top );
+
+#if FEATURE_userclip
+   /* Recompute clip plane positions in clipspace.  This is also done
+    * in _mesa_ClipPlane().
+    */
+   if (ctx->Transform.ClipPlanesEnabled) {
+      GLuint p;
+      for (p = 0; p < ctx->Const.MaxClipPlanes; p++) {
+	 if (ctx->Transform.ClipPlanesEnabled & (1 << p)) {
+	    _mesa_transform_vector( ctx->Transform._ClipUserPlane[p],
+				 ctx->Transform.EyeUserPlane[p],
+				 ctx->ProjectionMatrixStack.Top->inv );
+	 }
+      }
+   }
+#endif
+}
+
+
+/**
+ * Calculate the combined modelview-projection matrix.
+ *
+ * \param ctx GL context.
+ *
+ * Multiplies the top matrices of the projection and model view stacks into
+ * __GLcontextRec::_ModelProjectMatrix via _math_matrix_mul_matrix() and
+ * analyzes the resulting matrix via _math_matrix_analyse().
+ */
+static void
+calculate_model_project_matrix( GLcontext *ctx )
+{
+   _math_matrix_mul_matrix( &ctx->_ModelProjectMatrix,
+                            ctx->ProjectionMatrixStack.Top,
+                            ctx->ModelviewMatrixStack.Top );
+
+   _math_matrix_analyse( &ctx->_ModelProjectMatrix );
+}
+
+
+/**
+ * Updates the combined modelview-projection matrix.
+ *
+ * \param ctx GL context.
+ * \param new_state new state bit mask.
+ *
+ * If there is a new model view matrix then analyzes it. If there is a new
+ * projection matrix, updates it. Finally calls
+ * calculate_model_project_matrix() to recalculate the modelview-projection
+ * matrix.
+ */
+void _mesa_update_modelview_project( GLcontext *ctx, GLuint new_state )
+{
+   if (new_state & _NEW_MODELVIEW)
+      _math_matrix_analyse( ctx->ModelviewMatrixStack.Top );
+
+   if (new_state & _NEW_PROJECTION)
+      update_projection( ctx );
+
+   /* Keep ModelviewProject uptodate always to allow tnl
+    * implementations that go model->clip even when eye is required.
+    */
+   calculate_model_project_matrix(ctx);
+}
+
+/*@}*/
+
+
+/**********************************************************************/
+/** Matrix stack initialization */
+/*@{*/
+
+
+/**
+ * Initialize a matrix stack.
+ *
+ * \param stack matrix stack.
+ * \param maxDepth maximum stack depth.
+ * \param dirtyFlag dirty flag.
+ * 
+ * Allocates an array of \p maxDepth elements for the matrix stack and calls
+ * _math_matrix_ctr() and _math_matrix_alloc_inv() for each element to
+ * initialize it.
+ */
+static void
+init_matrix_stack( struct matrix_stack *stack,
+                   GLuint maxDepth, GLuint dirtyFlag )
+{
+   GLuint i;
+
+   stack->Depth = 0;
+   stack->MaxDepth = maxDepth;
+   stack->DirtyFlag = dirtyFlag;
+   /* The stack */
+   stack->Stack = (GLmatrix *) CALLOC(maxDepth * sizeof(GLmatrix));
+   for (i = 0; i < maxDepth; i++) {
+      _math_matrix_ctr(&stack->Stack[i]);
+      _math_matrix_alloc_inv(&stack->Stack[i]);
+   }
+   stack->Top = stack->Stack;
+}
+
+/**
+ * Free matrix stack.
+ * 
+ * \param stack matrix stack.
+ * 
+ * Calls _math_matrix_dtr() for each element of the matrix stack and
+ * frees the array.
+ */
+static void
+free_matrix_stack( struct matrix_stack *stack )
+{
+   GLuint i;
+   for (i = 0; i < stack->MaxDepth; i++) {
+      _math_matrix_dtr(&stack->Stack[i]);
+   }
+   FREE(stack->Stack);
+   stack->Stack = stack->Top = NULL;
+}
+
+/*@}*/
+
+
+/**********************************************************************/
+/** \name Initialization */
+/*@{*/
+
+
+/**
+ * Initialize the context matrix data.
+ *
+ * \param ctx GL context.
+ *
+ * Initializes each of the matrix stacks and the combined modelview-projection
+ * matrix.
+ */
+void _mesa_init_matrix( GLcontext * ctx )
+{
+   GLint i;
+
+   /* Initialize matrix stacks */
+   init_matrix_stack(&ctx->ModelviewMatrixStack, MAX_MODELVIEW_STACK_DEPTH,
+                     _NEW_MODELVIEW);
+   init_matrix_stack(&ctx->ProjectionMatrixStack, MAX_PROJECTION_STACK_DEPTH,
+                     _NEW_PROJECTION);
+   init_matrix_stack(&ctx->ColorMatrixStack, MAX_COLOR_STACK_DEPTH,
+                     _NEW_COLOR_MATRIX);
+   for (i = 0; i < MAX_TEXTURE_UNITS; i++)
+      init_matrix_stack(&ctx->TextureMatrixStack[i], MAX_TEXTURE_STACK_DEPTH,
+                        _NEW_TEXTURE_MATRIX);
+   for (i = 0; i < MAX_PROGRAM_MATRICES; i++)
+      init_matrix_stack(&ctx->ProgramMatrixStack[i], 
+		        MAX_PROGRAM_MATRIX_STACK_DEPTH, _NEW_TRACK_MATRIX);
+   ctx->CurrentStack = &ctx->ModelviewMatrixStack;
+
+   /* Init combined Modelview*Projection matrix */
+   _math_matrix_ctr( &ctx->_ModelProjectMatrix );
+}
+
+
+/**
+ * Free the context matrix data.
+ * 
+ * \param ctx GL context.
+ *
+ * Frees each of the matrix stacks and the combined modelview-projection
+ * matrix.
+ */
+void _mesa_free_matrix_data( GLcontext *ctx )
+{
+   GLint i;
+
+   free_matrix_stack(&ctx->ModelviewMatrixStack);
+   free_matrix_stack(&ctx->ProjectionMatrixStack);
+   free_matrix_stack(&ctx->ColorMatrixStack);
+   for (i = 0; i < MAX_TEXTURE_UNITS; i++)
+      free_matrix_stack(&ctx->TextureMatrixStack[i]);
+   for (i = 0; i < MAX_PROGRAM_MATRICES; i++)
+      free_matrix_stack(&ctx->ProgramMatrixStack[i]);
+   /* combined Modelview*Projection matrix */
+   _math_matrix_dtr( &ctx->_ModelProjectMatrix );
+
+}
+
+
+/** 
+ * Initialize the context transform attribute group.
+ *
+ * \param ctx GL context.
+ *
+ * \todo Move this to a new file with other 'transform' routines.
+ */
+void _mesa_init_transform( GLcontext *ctx )
+{
+   GLint i;
+
+   /* Transformation group */
+   ctx->Transform.MatrixMode = GL_MODELVIEW;
+   ctx->Transform.Normalize = GL_FALSE;
+   ctx->Transform.RescaleNormals = GL_FALSE;
+   ctx->Transform.RasterPositionUnclipped = GL_FALSE;
+   for (i=0;i<MAX_CLIP_PLANES;i++) {
+      ASSIGN_4V( ctx->Transform.EyeUserPlane[i], 0.0, 0.0, 0.0, 0.0 );
+   }
+   ctx->Transform.ClipPlanesEnabled = 0;
+}
+
+
+/** 
+ * Initialize the context viewport attribute group.
+ *
+ * \param ctx GL context.
+ * 
+ * \todo Move this to a new file with other 'viewport' routines.
+ */
+void _mesa_init_viewport( GLcontext *ctx )
+{
+   /* Viewport group */
+   ctx->Viewport.X = 0;
+   ctx->Viewport.Y = 0;
+   ctx->Viewport.Width = 0;
+   ctx->Viewport.Height = 0;
+   ctx->Viewport.Near = 0.0;
+   ctx->Viewport.Far = 1.0;
+   _math_matrix_ctr(&ctx->Viewport._WindowMap);
+
+#define Sz 10
+#define Tz 14
+   ctx->Viewport._WindowMap.m[Sz] = 0.5F * ctx->DepthMaxF;
+   ctx->Viewport._WindowMap.m[Tz] = 0.5F * ctx->DepthMaxF;
+#undef Sz
+#undef Tz
+
+   ctx->Viewport._WindowMap.flags = MAT_FLAG_GENERAL_SCALE|MAT_FLAG_TRANSLATION;
+   ctx->Viewport._WindowMap.type = MATRIX_3D_NO_ROT;
+}
+
+
+/** 
+ * Free the context viewport attribute group data.
+ *
+ * \param ctx GL context.
+ * 
+ * \todo Move this to a new file with other 'viewport' routines.
+ */
+void _mesa_free_viewport_data( GLcontext *ctx )
+{
+   _math_matrix_dtr(&ctx->Viewport._WindowMap);
+}
+
+/*@}*/
diff --git a/src/mesa/main/matrix.h b/src/mesa/main/matrix.h
index 13dc31eac4..b81ab84844 100644
--- a/src/mesa/main/matrix.h
+++ b/src/mesa/main/matrix.h
@@ -1,3 +1,7 @@
+/**
+ * \file matrix.h
+ * Matrix operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -105,4 +109,23 @@ extern void
 _mesa_DepthRange( GLclampd nearval, GLclampd farval );
 
 
+extern void 
+_mesa_init_matrix( GLcontext * ctx );
+
+extern void 
+_mesa_init_transform( GLcontext *ctx );
+
+extern void 
+_mesa_init_viewport( GLcontext *ctx );
+
+extern void
+_mesa_free_matrix_data( GLcontext *ctx );
+
+extern void 
+_mesa_free_viewport_data( GLcontext *ctx );
+
+extern void 
+_mesa_update_modelview_project( GLcontext *ctx, GLuint newstate );
+
+
 #endif
diff --git a/src/mesa/main/mtypes.h b/src/mesa/main/mtypes.h
index c116228bf8..bac711de1c 100644
--- a/src/mesa/main/mtypes.h
+++ b/src/mesa/main/mtypes.h
@@ -1,3 +1,10 @@
+/**
+ * \file mtypes.h
+ * Main Mesa data structures.
+ *
+ * Please try to mark derived values with a leading underscore ('_').
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -22,10 +29,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/**
- * \file mtypes.h
- * \brief Main Mesa data structures.
- */
+
 
 #ifndef TYPES_H
 #define TYPES_H
@@ -43,11 +47,8 @@
 #endif
 
 
-/* Please try to mark derived values with a leading underscore ('_').
- */
-
-/*
- * Color channel data type:
+/**
+ * Color channel data type.
  */
 #if CHAN_BITS == 8
    typedef GLubyte GLchan;
@@ -70,7 +71,7 @@
 
 
 /**
- * Accumulation buffer data type:
+ * Accumulation buffer data type.
  */
 #if ACCUM_BITS==8
    typedef GLbyte GLaccum;
@@ -84,7 +85,7 @@
 
 
 /**
- * Stencil buffer data type:
+ * Stencil buffer data type.
  */
 #if STENCIL_BITS==8
    typedef GLubyte GLstencil;
@@ -98,13 +99,15 @@
 
 
 /**
- * Depth buffer data type:
+ * Depth buffer data type.
+ *
+ * \note Must be 32-bits!
  */
-typedef GLuint GLdepth;  /* Must be 32-bits! */
+typedef GLuint GLdepth;  
 
 
 /**
- * Fixed point data type:
+ * Fixed point data type.
  */
 typedef int GLfixed;
 /*
@@ -138,38 +141,45 @@ typedef int GLfixed;
 
 
 /**
- * Some forward type declarations
+ * \name Some forward type declarations
  */
+/*@{*/
 struct _mesa_HashTable;
 struct gl_texture_image;
 struct gl_texture_object;
 typedef struct __GLcontextRec GLcontext;
 typedef struct __GLcontextModesRec GLvisual;
 typedef struct gl_frame_buffer GLframebuffer;
+/*@}*/
 
 
 
-/* These define the aliases between numbered vertex attributes and
+/**
+ * These define the aliases between numbered vertex attributes and
  * conventional OpenGL vertex attributes.  We use these values in
- * quite a few places.  New in Mesa 4.1.
- */
-#define VERT_ATTRIB_POS      0
-#define VERT_ATTRIB_WEIGHT   1
-#define VERT_ATTRIB_NORMAL   2
-#define VERT_ATTRIB_COLOR0   3
-#define VERT_ATTRIB_COLOR1   4
-#define VERT_ATTRIB_FOG      5
-#define VERT_ATTRIB_SIX      6
-#define VERT_ATTRIB_SEVEN    7
-#define VERT_ATTRIB_TEX0     8
-#define VERT_ATTRIB_TEX1     9
-#define VERT_ATTRIB_TEX2     10
-#define VERT_ATTRIB_TEX3     11
-#define VERT_ATTRIB_TEX4     12
-#define VERT_ATTRIB_TEX5     13
-#define VERT_ATTRIB_TEX6     14
-#define VERT_ATTRIB_TEX7     15
-#define VERT_ATTRIB_MAX      16
+ * quite a few places.  
+ *
+ * New in Mesa 4.1.
+ */
+enum {
+	VERT_ATTRIB_POS = 0,
+	VERT_ATTRIB_WEIGHT = 1,
+	VERT_ATTRIB_NORMAL = 2,
+	VERT_ATTRIB_COLOR0 = 3,
+	VERT_ATTRIB_COLOR1 = 4,
+	VERT_ATTRIB_FOG = 5,
+	VERT_ATTRIB_SIX = 6,
+	VERT_ATTRIB_SEVEN = 7,
+	VERT_ATTRIB_TEX0 = 8,
+	VERT_ATTRIB_TEX1 = 9,
+	VERT_ATTRIB_TEX2 = 10,
+	VERT_ATTRIB_TEX3 = 11,
+	VERT_ATTRIB_TEX4 = 12,
+	VERT_ATTRIB_TEX5 = 13,
+	VERT_ATTRIB_TEX6 = 14,
+	VERT_ATTRIB_TEX7 = 15,
+	VERT_ATTRIB_MAX = 16
+} ;
 
 /* These are used in bitfields in many places */
 #define VERT_BIT_POS     (1 << VERT_ATTRIB_POS)
@@ -194,19 +204,22 @@ typedef struct gl_frame_buffer GLframebuffer;
 
 
 /**
- * Maximum number of temporary vertices required for clipping.  (Used
- * in array_cache and tnl modules).
+ * Maximum number of temporary vertices required for clipping.  
+ *
+ * Used in array_cache and tnl modules.
  */
 #define MAX_CLIPPED_VERTICES ((2 * (6 + MAX_CLIP_PLANES))+1)
 
 
-/* Data structure for color tables */
+/**
+ * Data structure for color tables
+ */
 struct gl_color_table {
-   GLenum Format;         /* GL_ALPHA, GL_RGB, GL_RGB, etc */
+   GLenum Format;         /**< GL_ALPHA, GL_RGB, GL_RGB, etc */
    GLenum IntFormat;
-   GLuint Size;           /* number of entries (rows) in table */
-   GLvoid *Table;         /* either GLfloat * or GLchan * */
-   GLboolean FloatTable;  /* are entries stored as floats? */
+   GLuint Size;           /**< number of entries (rows) in table */
+   GLvoid *Table;         /**< either GLfloat * or GLchan * */
+   GLboolean FloatTable;  /**< are entries stored as floats? */
    GLubyte RedSize;
    GLubyte GreenSize;
    GLubyte BlueSize;
@@ -216,9 +229,10 @@ struct gl_color_table {
 };
 
 
-/*
- * Bit flags used for updating material values.
+/**
+ * \name Bit flags used for updating material values.
  */
+/*@{*/
 #define FRONT_AMBIENT_BIT     0x1
 #define BACK_AMBIENT_BIT      0x2
 #define FRONT_DIFFUSE_BIT     0x4
@@ -241,15 +255,15 @@ struct gl_color_table {
 				 BACK_SHININESS_BIT | BACK_INDEXES_BIT)
 
 #define ALL_MATERIAL_BITS	(FRONT_MATERIAL_BITS | BACK_MATERIAL_BITS)
+/*@}*/
 
 
+#define EXP_TABLE_SIZE 512	/**< Specular exponent lookup table sizes */
+#define SHINE_TABLE_SIZE 256	/**< Material shininess lookup table sizes */
 
-/*
- * Specular exponent and material shininess lookup table sizes:
+/**
+ * Material shininess lookup table.
  */
-#define EXP_TABLE_SIZE 512
-#define SHINE_TABLE_SIZE 256
-
 struct gl_shine_tab {
    struct gl_shine_tab *next, *prev;
    GLfloat tab[SHINE_TABLE_SIZE+1];
@@ -258,50 +272,63 @@ struct gl_shine_tab {
 };
 
 
+/**
+ * Light.
+ */
 struct gl_light {
-   struct gl_light *next;	/* double linked list with sentinel */
+   struct gl_light *next;	/**< double linked list with sentinel */
    struct gl_light *prev;
 
-   GLfloat Ambient[4];		/* ambient color */
-   GLfloat Diffuse[4];		/* diffuse color */
-   GLfloat Specular[4];		/* specular color */
-   GLfloat EyePosition[4];	/* position in eye coordinates */
-   GLfloat EyeDirection[4];	/* spotlight dir in eye coordinates */
+   GLfloat Ambient[4];		/**< ambient color */
+   GLfloat Diffuse[4];		/**< diffuse color */
+   GLfloat Specular[4];		/**< specular color */
+   GLfloat EyePosition[4];	/**< position in eye coordinates */
+   GLfloat EyeDirection[4];	/**< spotlight dir in eye coordinates */
    GLfloat SpotExponent;
-   GLfloat SpotCutoff;		/* in degress */
-   GLfloat _CosCutoff;		/* = MAX(0, cos(SpotCutoff)) */
+   GLfloat SpotCutoff;		/**< in degrees */
+   GLfloat _CosCutoff;		/**< = MAX(0, cos(SpotCutoff)) */
    GLfloat ConstantAttenuation;
    GLfloat LinearAttenuation;
    GLfloat QuadraticAttenuation;
-   GLboolean Enabled;		/* On/off flag */
+   GLboolean Enabled;		/**< On/off flag */
 
-   /* Derived fields */
-   GLuint _Flags;		/* State */
+   /** 
+    * \name Derived fields
+    */
+   /*@{*/
+   GLuint _Flags;		/**< State */
 
-   GLfloat _Position[4];	/* position in eye/obj coordinates */
-   GLfloat _VP_inf_norm[3];	/* Norm direction to infinite light */
-   GLfloat _h_inf_norm[3];	/* Norm( _VP_inf_norm + <0,0,1> ) */
-   GLfloat _NormDirection[4];	/* normalized spotlight direction */
+   GLfloat _Position[4];	/**< position in eye/obj coordinates */
+   GLfloat _VP_inf_norm[3];	/**< Norm direction to infinite light */
+   GLfloat _h_inf_norm[3];	/**< Norm( _VP_inf_norm + <0,0,1> ) */
+   GLfloat _NormDirection[4];	/**< normalized spotlight direction */
    GLfloat _VP_inf_spot_attenuation;
 
-   GLfloat _SpotExpTable[EXP_TABLE_SIZE][2];  /* to replace a pow() call */
-   GLfloat _MatAmbient[2][3];	/* material ambient * light ambient */
-   GLfloat _MatDiffuse[2][3];	/* material diffuse * light diffuse */
-   GLfloat _MatSpecular[2][3];	/* material spec * light specular */
-   GLfloat _dli;		/* CI diffuse light intensity */
-   GLfloat _sli;		/* CI specular light intensity */
+   GLfloat _SpotExpTable[EXP_TABLE_SIZE][2];  /**< to replace a pow() call */
+   GLfloat _MatAmbient[2][3];	/**< material ambient * light ambient */
+   GLfloat _MatDiffuse[2][3];	/**< material diffuse * light diffuse */
+   GLfloat _MatSpecular[2][3];	/**< material spec * light specular */
+   GLfloat _dli;		/**< CI diffuse light intensity */
+   GLfloat _sli;		/**< CI specular light intensity */
+   /*@}*/
 };
 
 
+/**
+ * Light model.
+ */
 struct gl_lightmodel {
-   GLfloat Ambient[4];		/* ambient color */
-   GLboolean LocalViewer;	/* Local (or infinite) view point? */
-   GLboolean TwoSide;		/* Two (or one) sided lighting? */
-   GLenum ColorControl;		/* either GL_SINGLE_COLOR */
-				/* or GL_SEPARATE_SPECULAR_COLOR */
+   GLfloat Ambient[4];		/**< ambient color */
+   GLboolean LocalViewer;	/**< Local (or infinite) view point? */
+   GLboolean TwoSide;		/**< Two (or one) sided lighting? */
+   GLenum ColorControl;		/**< either GL_SINGLE_COLOR
+				 *    or GL_SEPARATE_SPECULAR_COLOR */
 };
 
 
+/**
+ * Material.
+ */
 struct gl_material
 {
    GLfloat Ambient[4];
@@ -309,25 +336,27 @@ struct gl_material
    GLfloat Specular[4];
    GLfloat Emission[4];
    GLfloat Shininess;
-   GLfloat AmbientIndex;	/* for color index lighting */
-   GLfloat DiffuseIndex;	/* for color index lighting */
-   GLfloat SpecularIndex;	/* for color index lighting */
+   GLfloat AmbientIndex;	/**< for color index lighting */
+   GLfloat DiffuseIndex;	/**< for color index lighting */
+   GLfloat SpecularIndex;	/**< for color index lighting */
 };
 
 
-/*
- * Attribute structures:
- *    We define a struct for each attribute group to make pushing and
- *    popping attributes easy.  Also it's a good organization.
+/**
+ * Accumulation buffer attributes.
  */
 struct gl_accum_attrib {
-   GLfloat ClearColor[4];	/* Accumulation buffer clear color */
+   GLfloat ClearColor[4];	/**< Accumulation buffer clear color */
 };
 
 
-/*
- * Used in _DrawDestMask and _ReadSrcMask below to identify color buffers.
+/**
+ * \name Clipping planes bits
+ * 
+ * Used in gl_colorbuffer_attrib::_DrawDestMask and
+ * gl_colorbuffer_attrib::_ReadSrcMask below to identify color buffers.
  */
+/*@{*/
 #define FRONT_LEFT_BIT  0x1
 #define FRONT_RIGHT_BIT 0x2
 #define BACK_LEFT_BIT   0x4
@@ -336,72 +365,106 @@ struct gl_accum_attrib {
 #define AUX1_BIT        0x20
 #define AUX2_BIT        0x40
 #define AUX3_BIT        0x80
+/*@}*/
 
+
+/**
+ * Color buffers attributes.
+ */
 struct gl_colorbuffer_attrib {
-   GLuint ClearIndex;			/* Index to use for glClear */
-   GLclampf ClearColor[4];		/* Color to use for glClear */
-
-   GLuint IndexMask;			/* Color index write mask */
-   GLubyte ColorMask[4];		/* Each flag is 0xff or 0x0 */
-
-   GLenum DrawBuffer;		/* Which buffer to draw into */
-   GLubyte _DrawDestMask;	/* bitwise-OR of FRONT/BACK_LEFT/RIGHT_BITs */
-
-   /* alpha testing */
-   GLboolean AlphaEnabled;		/* Alpha test enabled flag */
-   GLenum AlphaFunc;			/* Alpha test function */
-   GLclampf AlphaRef;
-
-   /* blending */
-   GLboolean BlendEnabled;		/* Blending enabled flag */
-   GLenum BlendSrcRGB;			/* Blending source operator */
-   GLenum BlendDstRGB;			/* Blending destination operator */
-   GLenum BlendSrcA;			/* GL_INGR_blend_func_separate */
-   GLenum BlendDstA;			/* GL_INGR_blend_func_separate */
-   GLenum BlendEquation;
-   GLfloat BlendColor[4];
-
-   /* logic op */
-   GLenum LogicOp;			/* Logic operator */
-   GLboolean IndexLogicOpEnabled;	/* Color index logic op enabled flag */
-   GLboolean ColorLogicOpEnabled;	/* RGBA logic op enabled flag */
-
-   GLboolean DitherFlag;		/* Dither enable flag */
+   GLuint ClearIndex;			/**< Index to use for glClear */
+   GLclampf ClearColor[4];		/**< Color to use for glClear */
+
+   GLuint IndexMask;			/**< Color index write mask */
+   GLubyte ColorMask[4];		/**< Each flag is 0xff or 0x0 */
+
+   GLenum DrawBuffer;			/**< Which buffer to draw into */
+   GLubyte _DrawDestMask;		/**< bitwise-OR of FRONT/BACK_LEFT/RIGHT_BITs */
+
+   /** 
+    * \name alpha testing
+    */
+   /*@{*/
+   GLboolean AlphaEnabled;		/**< Alpha test enabled flag */
+   GLenum AlphaFunc;			/**< Alpha test function */
+   GLclampf AlphaRef;			/**< Alpha reference value */
+   /*@}*/
+
+   /** 
+    * \name Blending
+    */
+   /*@{*/
+   GLboolean BlendEnabled;		/**< Blending enabled flag */
+   GLenum BlendSrcRGB;			/**< Blending source operator */
+   GLenum BlendDstRGB;			/**< Blending destination operator */
+   GLenum BlendSrcA;			/**< GL_INGR_blend_func_separate */
+   GLenum BlendDstA;			/**< GL_INGR_blend_func_separate */
+   GLenum BlendEquation;		/**< Blending equation */
+   GLfloat BlendColor[4];		/**< Blending color */
+   /*@}*/
+
+   /** 
+    * \name Logic op
+    */
+   /*@{*/
+   GLenum LogicOp;			/**< Logic operator */
+   GLboolean IndexLogicOpEnabled;	/**< Color index logic op enabled flag */
+   GLboolean ColorLogicOpEnabled;	/**< RGBA logic op enabled flag */
+   /*@}*/
+
+   GLboolean DitherFlag;		/**< Dither enable flag */
 };
 
 
+/**
+ * Current attributes.
+ */
 struct gl_current_attrib {
-   /* These values valid only when FLUSH_VERTICES has been called.
+   /**
+    * \name Values valid only when FLUSH_VERTICES has been called.
     */
-   GLfloat Attrib[VERT_ATTRIB_MAX][4];		/* Current vertex attributes */
-						/* indexed by VERT_ATTRIB_* */
-   GLuint Index;				/* Current color index */
-   GLboolean EdgeFlag;				/* Current edge flag */
+   /*@{*/
+   GLfloat Attrib[VERT_ATTRIB_MAX][4];		/**< Current vertex attributes
+						  *  indexed by VERT_ATTRIB_* */
+   GLuint Index;				/**< Current color index */
+   GLboolean EdgeFlag;				/**< Current edge flag */
+   /*@}*/
 
-   /* These values are always valid.  BTW, note how similar this set of
-    * attributes is to the SWvertex datatype in the software rasterizer...
+   /**
+    * \name Values are always valid.  
+    * 
+    * \note BTW, note how similar this set of attributes is to the SWvertex data type
+    * in the software rasterizer...
     */
-   GLfloat RasterPos[4];			/* Current raster position */
-   GLfloat RasterDistance;			/* Current raster distance */
-   GLfloat RasterColor[4];			/* Current raster color */
-   GLfloat RasterSecondaryColor[4];             /* Current rast 2ndary color */
-   GLuint RasterIndex;				/* Current raster index */
-   GLfloat RasterTexCoords[MAX_TEXTURE_COORD_UNITS][4];
-   GLboolean RasterPosValid;			/* Raster pos valid flag */
+   /*@{*/
+   GLfloat RasterPos[4];			/**< Current raster position */
+   GLfloat RasterDistance;			/**< Current raster distance */
+   GLfloat RasterColor[4];			/**< Current raster color */
+   GLfloat RasterSecondaryColor[4];             /**< Current raster secondary color */
+   GLuint RasterIndex;				/**< Current raster index */
+   GLfloat RasterTexCoords[MAX_TEXTURE_UNITS][4];/**< Current raster texcoords */
+   GLboolean RasterPosValid;			/**< Raster pos valid flag */
+   /*@}*/
 };
 
 
+/**
+ * Depth buffer attributes.
+ */
 struct gl_depthbuffer_attrib {
-   GLenum Func;			/* Function for depth buffer compare */
-   GLfloat Clear;		/* Value to clear depth buffer to */
-   GLboolean Test;		/* Depth buffering enabled flag */
-   GLboolean Mask;		/* Depth buffer writable? */
-   GLboolean OcclusionTest;	/* GL_HP_occlusion_test */
-   GLboolean BoundsTest;        /* GL_EXT_depth_bounds_test */
-   GLfloat BoundsMin, BoundsMax;/* GL_EXT_depth_bounds_test */
+   GLenum Func;			/**< Function for depth buffer compare */
+   GLfloat Clear;		/**< Value to clear depth buffer to */
+   GLboolean Test;		/**< Depth buffering enabled flag */
+   GLboolean Mask;		/**< Depth buffer writable? */
+   GLboolean OcclusionTest;	/**< GL_HP_occlusion_test */
+   GLboolean BoundsTest;        /**< GL_EXT_depth_bounds_test */
+   GLfloat BoundsMin, BoundsMax;/**< GL_EXT_depth_bounds_test */
 };
 
 
+/**
+ * glEnable()/glDisable() attributes.
+ */
 struct gl_enable_attrib {
    GLboolean AlphaTest;
    GLboolean AutoNormal;
@@ -476,8 +539,14 @@ struct gl_enable_attrib {
 };
 
 
+/**
+ * Eval attributes.
+ */
 struct gl_eval_attrib {
-   /* Enable bits */
+   /**
+    * \name Enable bits 
+    */
+   /*@{*/
    GLboolean Map1Color4;
    GLboolean Map1Index;
    GLboolean Map1Normal;
@@ -499,47 +568,63 @@ struct gl_eval_attrib {
    GLboolean Map2Vertex4;
    GLboolean Map2Attrib[16];  /* GL_NV_vertex_program */
    GLboolean AutoNormal;
-   /* Map Grid endpoints and divisions and calculated du values */
+   /*@}*/
+   
+   /**
+    * \name Map Grid endpoints and divisions and calculated du values
+    */
+   /*@{*/
    GLint MapGrid1un;
    GLfloat MapGrid1u1, MapGrid1u2, MapGrid1du;
    GLint MapGrid2un, MapGrid2vn;
    GLfloat MapGrid2u1, MapGrid2u2, MapGrid2du;
    GLfloat MapGrid2v1, MapGrid2v2, MapGrid2dv;
+   /*@}*/
 };
 
 
+/**
+ * Fog attributes.
+ */
 struct gl_fog_attrib {
-   GLboolean Enabled;		/* Fog enabled flag */
-   GLfloat Color[4];		/* Fog color */
-   GLfloat Density;		/* Density >= 0.0 */
-   GLfloat Start;		/* Start distance in eye coords */
-   GLfloat End;			/* End distance in eye coords */
-   GLfloat Index;		/* Fog index */
-   GLenum Mode;			/* Fog mode */
+   GLboolean Enabled;		/**< Fog enabled flag */
+   GLfloat Color[4];		/**< Fog color */
+   GLfloat Density;		/**< Density >= 0.0 */
+   GLfloat Start;		/**< Start distance in eye coords */
+   GLfloat End;			/**< End distance in eye coords */
+   GLfloat Index;		/**< Fog index */
+   GLenum Mode;			/**< Fog mode */
    GLboolean ColorSumEnabled;
-   GLenum FogCoordinateSource;  /* GL_EXT_fog_coord */
+   GLenum FogCoordinateSource;  /**< GL_EXT_fog_coord */
 };
 
 
+/** 
+ * Hint attributes.
+ * 
+ * Values are always one of GL_FASTEST, GL_NICEST, or GL_DONT_CARE.
+ */
 struct gl_hint_attrib {
-   /* always one of GL_FASTEST, GL_NICEST, or GL_DONT_CARE */
    GLenum PerspectiveCorrection;
    GLenum PointSmooth;
    GLenum LineSmooth;
    GLenum PolygonSmooth;
    GLenum Fog;
-   GLenum ClipVolumeClipping;   /* GL_EXT_clip_volume_hint */
-   GLenum TextureCompression;   /* GL_ARB_texture_compression */
-   GLenum GenerateMipmap;       /* GL_SGIS_generate_mipmap */
+   GLenum ClipVolumeClipping;   /**< GL_EXT_clip_volume_hint */
+   GLenum TextureCompression;   /**< GL_ARB_texture_compression */
+   GLenum GenerateMipmap;       /**< GL_SGIS_generate_mipmap */
 };
 
 
+/**
+ * Histogram attributes.
+ */
 struct gl_histogram_attrib {
-   GLuint Width;				/* number of table entries */
-   GLint Format;				/* GL_ALPHA, GL_RGB, etc */
-   GLuint Count[HISTOGRAM_TABLE_SIZE][4];	/* the histogram */
-   GLboolean Sink;				/* terminate image transfer? */
-   GLubyte RedSize;				/* Bits per counter */
+   GLuint Width;				/**< number of table entries */
+   GLint Format;				/**< GL_ALPHA, GL_RGB, etc */
+   GLuint Count[HISTOGRAM_TABLE_SIZE][4];	/**< the histogram */
+   GLboolean Sink;				/**< terminate image transfer? */
+   GLubyte RedSize;				/**< Bits per counter */
    GLubyte GreenSize;
    GLubyte BlueSize;
    GLubyte AlphaSize;
@@ -550,7 +635,7 @@ struct gl_histogram_attrib {
 struct gl_minmax_attrib {
    GLenum Format;
    GLboolean Sink;
-   GLfloat Min[4], Max[4];   /* RGBA */
+   GLfloat Min[4], Max[4];   /**< RGBA */
 };
 
 
@@ -568,37 +653,51 @@ struct gl_convolution_attrib {
 #define LIGHT_POSITIONAL   0x4
 #define LIGHT_NEED_VERTICES (LIGHT_POSITIONAL|LIGHT_LOCAL_VIEWER)
 
+/**
+ * Lighting attributes.
+ */
 struct gl_light_attrib {
-   struct gl_light Light[MAX_LIGHTS];	/* Array of lights */
-   struct gl_lightmodel Model;		/* Lighting model */
+   struct gl_light Light[MAX_LIGHTS];	/**< Array of lights */
+   struct gl_lightmodel Model;		/**< Lighting model */
 
-   /* Must flush FLUSH_VERTICES before referencing:
+   /**
+    * Must flush FLUSH_VERTICES before referencing:
     */
-   struct gl_material Material[2];	/* Material 0=front, 1=back */
-
-   GLboolean Enabled;			/* Lighting enabled flag */
-   GLenum ShadeModel;			/* GL_FLAT or GL_SMOOTH */
-   GLenum ColorMaterialFace;		/* GL_FRONT, BACK or FRONT_AND_BACK */
-   GLenum ColorMaterialMode;		/* GL_AMBIENT, GL_DIFFUSE, etc */
-   GLuint ColorMaterialBitmask;		/* bitmask formed from Face and Mode */
+   /*@{*/
+   struct gl_material Material[2];	/**< Material 0=front, 1=back */
+   /*@}*/
+
+   GLboolean Enabled;			/**< Lighting enabled flag */
+   GLenum ShadeModel;			/**< GL_FLAT or GL_SMOOTH */
+   GLenum ColorMaterialFace;		/**< GL_FRONT, BACK or FRONT_AND_BACK */
+   GLenum ColorMaterialMode;		/**< GL_AMBIENT, GL_DIFFUSE, etc */
+   GLuint ColorMaterialBitmask;		/**< bitmask formed from Face and Mode */
    GLboolean ColorMaterialEnabled;
 
-   struct gl_light EnabledList;         /* List sentinel */
+   struct gl_light EnabledList;         /**< List sentinel */
 
-   /* Derived for optimizations: */
-   GLboolean _NeedVertices;		/* Use fast shader? */
-   GLuint  _Flags;		        /* LIGHT_* flags, see above */
+   /** 
+    * Derived for optimizations: 
+    */
+   /*@{*/
+   GLboolean _NeedEyeCoords;		
+   GLboolean _NeedVertices;		/**< Use fast shader? */
+   GLuint  _Flags;		        /**< LIGHT_* flags, see above */
    GLfloat _BaseColor[2][3];
+   /*@}*/
 };
 
 
+/**
+ * Line attributes.
+ */
 struct gl_line_attrib {
-   GLboolean SmoothFlag;	/* GL_LINE_SMOOTH enabled? */
-   GLboolean StippleFlag;	/* GL_LINE_STIPPLE enabled? */
-   GLushort StipplePattern;	/* Stipple pattern */
-   GLint StippleFactor;		/* Stipple repeat factor */
-   GLfloat Width;		/* Line width */
-   GLfloat _Width;		/* Clamped Line width */
+   GLboolean SmoothFlag;	/**< GL_LINE_SMOOTH enabled? */
+   GLboolean StippleFlag;	/**< GL_LINE_STIPPLE enabled? */
+   GLushort StipplePattern;	/**< Stipple pattern */
+   GLint StippleFactor;		/**< Stipple repeat factor */
+   GLfloat Width;		/**< Line width */
+   GLfloat _Width;		/**< Clamped Line width */
 };
 
 
@@ -632,11 +731,15 @@ struct gl_multisample_attrib {
 };
 
 
+/**
+ * Pixel attributes.
+ */
 struct gl_pixel_attrib {
-   GLenum ReadBuffer;		/* src buffer for glRead/CopyPixels */
-   GLubyte _ReadSrcMask;	/* Not really a mask, but like _DrawDestMask */
-				/* May be: FRONT_LEFT_BIT, BACK_LEFT_BIT, */
-				/* FRONT_RIGHT_BIT or BACK_RIGHT_BIT. */
+   GLenum ReadBuffer;		/**< source buffer for glReadPixels()/glCopyPixels() */
+   GLubyte _ReadSrcMask;	/**< Not really a mask, but like _DrawDestMask
+				  *
+				  * May be: FRONT_LEFT_BIT, BACK_LEFT_BIT,
+				  * FRONT_RIGHT_BIT or BACK_RIGHT_BIT. */
    GLfloat RedBias, RedScale;
    GLfloat GreenBias, GreenScale;
    GLfloat BlueBias, BlueScale;
@@ -647,7 +750,7 @@ struct gl_pixel_attrib {
    GLboolean MapStencilFlag;
    GLfloat ZoomX, ZoomY;
    /* XXX move these out of gl_pixel_attrib */
-   GLint MapStoSsize;		/* Size of each pixel map */
+   GLint MapStoSsize;		/**< Size of each pixel map */
    GLint MapItoIsize;
    GLint MapItoRsize;
    GLint MapItoGsize;
@@ -657,13 +760,13 @@ struct gl_pixel_attrib {
    GLint MapGtoGsize;
    GLint MapBtoBsize;
    GLint MapAtoAsize;
-   GLint MapStoS[MAX_PIXEL_MAP_TABLE];	/* Pixel map tables */
+   GLint MapStoS[MAX_PIXEL_MAP_TABLE];	/**< Pixel map tables */
    GLint MapItoI[MAX_PIXEL_MAP_TABLE];
    GLfloat MapItoR[MAX_PIXEL_MAP_TABLE];
    GLfloat MapItoG[MAX_PIXEL_MAP_TABLE];
    GLfloat MapItoB[MAX_PIXEL_MAP_TABLE];
    GLfloat MapItoA[MAX_PIXEL_MAP_TABLE];
-   GLubyte MapItoR8[MAX_PIXEL_MAP_TABLE];  /* converted to 8-bit color */
+   GLubyte MapItoR8[MAX_PIXEL_MAP_TABLE];  /**< converted to 8-bit color */
    GLubyte MapItoG8[MAX_PIXEL_MAP_TABLE];
    GLubyte MapItoB8[MAX_PIXEL_MAP_TABLE];
    GLubyte MapItoA8[MAX_PIXEL_MAP_TABLE];
@@ -671,17 +774,17 @@ struct gl_pixel_attrib {
    GLfloat MapGtoG[MAX_PIXEL_MAP_TABLE];
    GLfloat MapBtoB[MAX_PIXEL_MAP_TABLE];
    GLfloat MapAtoA[MAX_PIXEL_MAP_TABLE];
-   /* GL_EXT_histogram */
+   /** GL_EXT_histogram */
    GLboolean HistogramEnabled;
    GLboolean MinMaxEnabled;
-   /* GL_SGIS_pixel_texture */
+   /** GL_SGIS_pixel_texture */
    GLboolean PixelTextureEnabled;
    GLenum FragmentRgbSource;
    GLenum FragmentAlphaSource;
-   /* GL_SGI_color_matrix */
-   GLfloat PostColorMatrixScale[4];  /* RGBA */
-   GLfloat PostColorMatrixBias[4];   /* RGBA */
-   /* GL_SGI_color_table */
+   /** GL_SGI_color_matrix */
+   GLfloat PostColorMatrixScale[4];  /**< RGBA */
+   GLfloat PostColorMatrixBias[4];   /**< RGBA */
+   /** GL_SGI_color_table */
    GLfloat ColorTableScale[4];
    GLfloat ColorTableBias[4];
    GLboolean ColorTableEnabled;
@@ -691,10 +794,10 @@ struct gl_pixel_attrib {
    GLfloat PCMCTscale[4];
    GLfloat PCMCTbias[4];
    GLboolean PostColorMatrixColorTableEnabled;
-   /* GL_SGI_texture_color_table */
+   /** GL_SGI_texture_color_table */
    GLfloat TextureColorTableScale[4];
    GLfloat TextureColorTableBias[4];
-   /* Convolution */
+   /** Convolution */
    GLboolean Convolution1DEnabled;
    GLboolean Convolution2DEnabled;
    GLboolean Separable2DEnabled;
@@ -702,61 +805,73 @@ struct gl_pixel_attrib {
    GLenum ConvolutionBorderMode[3];
    GLfloat ConvolutionFilterScale[3][4];
    GLfloat ConvolutionFilterBias[3][4];
-   GLfloat PostConvolutionScale[4];  /* RGBA */
-   GLfloat PostConvolutionBias[4];   /* RGBA */
+   GLfloat PostConvolutionScale[4];  /**< RGBA */
+   GLfloat PostConvolutionBias[4];   /**< RGBA */
 };
 
 
+/**
+ * Point attributes.
+ */
 struct gl_point_attrib {
-   GLboolean SmoothFlag;	/* True if GL_POINT_SMOOTH is enabled */
-   GLfloat Size;		/* User-specified point size */
-   GLfloat _Size;		/* Size clamped to Const.Min/MaxPointSize */
-   GLfloat Params[3];		/* GL_EXT_point_parameters */
-   GLfloat MinSize, MaxSize;	/* GL_EXT_point_parameters */
-   GLfloat Threshold;		/* GL_EXT_point_parameters */
-   GLboolean _Attenuated;	/* True if Params != [1, 0, 0] */
-   GLboolean PointSprite;	/* GL_NV_point_sprite */
-   GLboolean CoordReplace[MAX_TEXTURE_COORD_UNITS]; /* GL_NV_point_sprite */
-   GLenum SpriteRMode;		/* GL_NV_point_sprite */
+   GLboolean SmoothFlag;	/**< True if GL_POINT_SMOOTH is enabled */
+   GLfloat Size;		/**< User-specified point size */
+   GLfloat _Size;		/**< Size clamped to Const.Min/MaxPointSize */
+   GLfloat Params[3];		/**< GL_EXT_point_parameters */
+   GLfloat MinSize, MaxSize;	/**< GL_EXT_point_parameters */
+   GLfloat Threshold;		/**< GL_EXT_point_parameters */
+   GLboolean _Attenuated;	/**< True if Params != [1, 0, 0] */
+   GLboolean PointSprite;	/**< GL_NV_point_sprite */
+   GLboolean CoordReplace[MAX_TEXTURE_UNITS]; /**< GL_NV_point_sprite */
+   GLenum SpriteRMode;		/**< GL_NV_point_sprite */
 };
 
 
+/**
+ * Polygon attributes.
+ */
 struct gl_polygon_attrib {
-   GLenum FrontFace;		/* Either GL_CW or GL_CCW */
-   GLenum FrontMode;		/* Either GL_POINT, GL_LINE or GL_FILL */
-   GLenum BackMode;		/* Either GL_POINT, GL_LINE or GL_FILL */
-   GLboolean _FrontBit;		/* 0=GL_CCW, 1=GL_CW */
-   GLboolean CullFlag;		/* Culling on/off flag */
-   GLboolean SmoothFlag;	/* True if GL_POLYGON_SMOOTH is enabled */
-   GLboolean StippleFlag;	/* True if GL_POLYGON_STIPPLE is enabled */
-   GLenum CullFaceMode;		/* Culling mode GL_FRONT or GL_BACK */
-   GLfloat OffsetFactor;	/* Polygon offset factor, from user */
-   GLfloat OffsetUnits;		/* Polygon offset units, from user */
-   GLboolean OffsetPoint;	/* Offset in GL_POINT mode */
-   GLboolean OffsetLine;	/* Offset in GL_LINE mode */
-   GLboolean OffsetFill;	/* Offset in GL_FILL mode */
+   GLenum FrontFace;		/**< Either GL_CW or GL_CCW */
+   GLenum FrontMode;		/**< Either GL_POINT, GL_LINE or GL_FILL */
+   GLenum BackMode;		/**< Either GL_POINT, GL_LINE or GL_FILL */
+   GLboolean _FrontBit;		/**< 0=GL_CCW, 1=GL_CW */
+   GLboolean CullFlag;		/**< Culling on/off flag */
+   GLboolean SmoothFlag;	/**< True if GL_POLYGON_SMOOTH is enabled */
+   GLboolean StippleFlag;	/**< True if GL_POLYGON_STIPPLE is enabled */
+   GLenum CullFaceMode;		/**< Culling mode GL_FRONT or GL_BACK */
+   GLfloat OffsetFactor;	/**< Polygon offset factor, from user */
+   GLfloat OffsetUnits;		/**< Polygon offset units, from user */
+   GLboolean OffsetPoint;	/**< Offset in GL_POINT mode */
+   GLboolean OffsetLine;	/**< Offset in GL_LINE mode */
+   GLboolean OffsetFill;	/**< Offset in GL_FILL mode */
 };
 
 
+/**
+ * Scissor attributes.
+ */
 struct gl_scissor_attrib {
-   GLboolean Enabled;		/* Scissor test enabled? */
-   GLint X, Y;			/* Lower left corner of box */
-   GLsizei Width, Height;	/* Size of box */
+   GLboolean Enabled;		/**< Scissor test enabled? */
+   GLint X, Y;			/**< Lower left corner of box */
+   GLsizei Width, Height;	/**< Size of box */
 };
 
 
+/**
+ * Stencil attributes.
+ */
 struct gl_stencil_attrib {
-   GLboolean Enabled;		/* Enabled flag */
-   GLboolean TestTwoSide;	/* GL_EXT_stencil_two_side */
-   GLubyte ActiveFace;		/* GL_EXT_stencil_two_side (0 or 1) */
-   GLenum Function[2];		/* Stencil function */
-   GLenum FailFunc[2];		/* Fail function */
-   GLenum ZPassFunc[2];		/* Depth buffer pass function */
-   GLenum ZFailFunc[2];		/* Depth buffer fail function */
-   GLstencil Ref[2];		/* Reference value */
-   GLstencil ValueMask[2];	/* Value mask */
-   GLstencil WriteMask[2];	/* Write mask */
-   GLstencil Clear;		/* Clear value */
+   GLboolean Enabled;		/**< Enabled flag */
+   GLboolean TestTwoSide;	/**< GL_EXT_stencil_two_side */
+   GLubyte ActiveFace;		/**< GL_EXT_stencil_two_side (0 or 1) */
+   GLenum Function[2];		/**< Stencil function */
+   GLenum FailFunc[2];		/**< Fail function */
+   GLenum ZPassFunc[2];		/**< Depth buffer pass function */
+   GLenum ZFailFunc[2];		/**< Depth buffer fail function */
+   GLstencil Ref[2];		/**< Reference value */
+   GLstencil ValueMask[2];	/**< Value mask */
+   GLstencil WriteMask[2];	/**< Write mask */
+   GLstencil Clear;		/**< Clear value */
 };
 
 
@@ -819,147 +934,187 @@ struct gl_stencil_attrib {
 #define ENABLE_TEXGEN(i) (ENABLE_TEXGEN0 << (i))
 #define ENABLE_TEXMAT(i) (ENABLE_TEXMAT0 << (i))
 
-/*
- * If teximage is color-index, texelOut returns GLchan[1].
- * If teximage is depth, texelOut returns GLfloat[1].
- * Otherwise, texelOut returns GLchan[4].
+/**
+ * Texel fetch function prototype.
+ * 
+ * \param texImage texture image.
+ * \param col texel column.
+ * \param row texel row.
+ * \param img texel level.
+ * \param texelOut output texel. If \p texImage is color-index, \p texelOut
+ * returns <tt>GLchan[1]</tt>.  If \p texImage is depth, \p texelOut returns
+ * <tt>GLfloat[1]</tt>.  Otherwise, \p texelOut returns <tt>GLchan[4]</tt>.
  */
 typedef void (*FetchTexelFunc)( const struct gl_texture_image *texImage,
                                 GLint col, GLint row, GLint img,
                                 GLvoid *texelOut );
 
-/* Texture format record */
+/**
+ * Texture format record 
+ */
 struct gl_texture_format {
-   GLint MesaFormat;		/* One of the MESA_FORMAT_* values */
+   GLint MesaFormat;		/**< One of the MESA_FORMAT_* values */
 
-   GLenum BaseFormat;		/* Either GL_ALPHA, GL_INTENSITY, GL_LUMINANCE,
-                                 * GL_LUMINANCE_ALPHA, GL_RGB, GL_RGBA,
-                                 * GL_COLOR_INDEX or GL_DEPTH_COMPONENT.
+   GLenum BaseFormat;		/**< Either GL_ALPHA, GL_INTENSITY, GL_LUMINANCE,
+                                 *   GL_LUMINANCE_ALPHA, GL_RGB, GL_RGBA,
+                                 *   GL_COLOR_INDEX or GL_DEPTH_COMPONENT.
                                  */
-   GLubyte RedBits;		/* Bits per texel component */
-   GLubyte GreenBits;		/* These are just rough approximations for */
-   GLubyte BlueBits;		/* compressed texture formats. */
+   GLubyte RedBits;		/**< Bits per texel component */
+   GLubyte GreenBits;		/**< These are just rough approximations for */
+   GLubyte BlueBits;		/**< compressed texture formats. */
    GLubyte AlphaBits;
    GLubyte LuminanceBits;
    GLubyte IntensityBits;
    GLubyte IndexBits;
    GLubyte DepthBits;
 
-   GLint TexelBytes;		/* Bytes per texel (0 for compressed formats */
+   GLint TexelBytes;		/**< Bytes per texel (0 for compressed formats */
 
-   FetchTexelFunc FetchTexel1D;	/* Texel fetch function pointers */
+   /**
+    * \name Texel fetch function pointers
+    */
+   /*@{*/
+   FetchTexelFunc FetchTexel1D;
    FetchTexelFunc FetchTexel2D;
    FetchTexelFunc FetchTexel3D;
+   /*@}*/
 };
 
 
-/* Texture image record */
+/**
+ * Texture image record 
+ */
 struct gl_texture_image {
-   GLenum Format;		/* GL_ALPHA, GL_LUMINANCE, GL_LUMINANCE_ALPHA,
-				 * GL_INTENSITY, GL_RGB, GL_RGBA,
-                                 * GL_COLOR_INDEX or GL_DEPTH_COMPONENT only.
-                                 * Used for choosing TexEnv arithmetic.
+   GLenum Format;		/**< GL_ALPHA, GL_LUMINANCE, GL_LUMINANCE_ALPHA,
+				 *    GL_INTENSITY, GL_RGB, GL_RGBA,
+                                 *    GL_COLOR_INDEX or GL_DEPTH_COMPONENT only.
+                                 *    Used for choosing TexEnv arithmetic.
 				 */
-   GLint IntFormat;		/* Internal format as given by the user */
-   GLuint Border;		/* 0 or 1 */
-   GLuint Width;		/* = 2^WidthLog2 + 2*Border */
-   GLuint Height;		/* = 2^HeightLog2 + 2*Border */
-   GLuint Depth;		/* = 2^DepthLog2 + 2*Border */
-   GLuint RowStride;		/* == Width unless IsClientData and padded */
-   GLuint Width2;		/* = Width - 2*Border */
-   GLuint Height2;		/* = Height - 2*Border */
-   GLuint Depth2;		/* = Depth - 2*Border */
-   GLuint WidthLog2;		/* = log2(Width2) */
-   GLuint HeightLog2;		/* = log2(Height2) */
-   GLuint DepthLog2;		/* = log2(Depth2) */
-   GLuint MaxLog2;		/* = MAX(WidthLog2, HeightLog2) */
-   GLfloat WidthScale;		/* used for mipmap lod computation */
-   GLfloat HeightScale;		/* used for mipmap lod computation */
-   GLfloat DepthScale;		/* used for mipmap lod computation */
-   GLvoid *Data;		/* Image data, accessed via FetchTexel() */
-   GLboolean IsClientData;	/* Data owned by client? */
-   GLboolean _IsPowerOfTwo;	/* Are all dimensions powers of two? */
+   GLint IntFormat;		/**< Internal format as given by the user */
+   GLuint Border;		/**< 0 or 1 */
+   GLuint Width;		/**< = 2^WidthLog2 + 2*Border */
+   GLuint Height;		/**< = 2^HeightLog2 + 2*Border */
+   GLuint Depth;		/**< = 2^DepthLog2 + 2*Border */
+   GLuint RowStride;		/**< == Width unless IsClientData and padded */
+   GLuint Width2;		/**< = Width - 2*Border */
+   GLuint Height2;		/**< = Height - 2*Border */
+   GLuint Depth2;		/**< = Depth - 2*Border */
+   GLuint WidthLog2;		/**< = log2(Width2) */
+   GLuint HeightLog2;		/**< = log2(Height2) */
+   GLuint DepthLog2;		/**< = log2(Depth2) */
+   GLuint MaxLog2;		/**< = MAX(WidthLog2, HeightLog2) */
+   GLfloat WidthScale;		/**< used for mipmap LOD computation */
+   GLfloat HeightScale;		/**< used for mipmap LOD computation */
+   GLfloat DepthScale;		/**< used for mipmap LOD computation */
+   GLvoid *Data;		/**< Image data, accessed via FetchTexel() */
+   GLboolean IsClientData;	/**< Data owned by client? */
+   GLboolean _IsPowerOfTwo;	/**< Are all dimensions powers of two? */
 
    const struct gl_texture_format *TexFormat;
 
-   FetchTexelFunc FetchTexel;	/* Texel fetch function pointer */
+   FetchTexelFunc FetchTexel;	/**< Texel fetch function pointer */
 
-   GLboolean IsCompressed;	/* GL_ARB_texture_compression */
-   GLuint CompressedSize;	/* GL_ARB_texture_compression */
+   GLboolean IsCompressed;	/**< GL_ARB_texture_compression */
+   GLuint CompressedSize;	/**< GL_ARB_texture_compression */
 
-   /* For device driver: */
-   void *DriverData;		/* Arbitrary device driver data */
+   /**
+    * \name For device driver:
+    */
+   /*@{*/
+   void *DriverData;		/**< Arbitrary device driver data */
+   /*@}*/
 };
 
 
-/* Texture object record */
+/**
+ * Texture object record
+ */
 struct gl_texture_object {
-   _glthread_Mutex Mutex;	/* for thread safety */
-   GLint RefCount;		/* reference count */
-   GLuint Name;			/* an unsigned integer */
-   GLenum Target;               /* GL_TEXTURE_1D, GL_TEXTURE_2D, etc. */
-   GLfloat Priority;		/* in [0,1] */
-   GLfloat BorderColor[4];	/* unclamped */
-   GLchan _BorderChan[4];	/* clamped, as GLchan */
-   GLenum WrapS;		/* Wrap modes are: GL_CLAMP, REPEAT */
-   GLenum WrapT;		/*   GL_CLAMP_TO_EDGE, and          */
-   GLenum WrapR;		/*   GL_CLAMP_TO_BORDER_ARB         */
-   GLenum MinFilter;		/* minification filter */
-   GLenum MagFilter;		/* magnification filter */
-   GLfloat MinLod;		/* min lambda, OpenGL 1.2 */
-   GLfloat MaxLod;		/* max lambda, OpenGL 1.2 */
-   GLint BaseLevel;		/* min mipmap level, OpenGL 1.2 */
-   GLint MaxLevel;		/* max mipmap level, OpenGL 1.2 */
-   GLfloat MaxAnisotropy;	/* GL_EXT_texture_filter_anisotropic */
-   GLboolean CompareFlag;	/* GL_SGIX_shadow */
-   GLenum CompareOperator;	/* GL_SGIX_shadow */
+   _glthread_Mutex Mutex;	/**< for thread safety */
+   GLint RefCount;		/**< reference count */
+   GLuint Name;			/**< an unsigned integer */
+   GLenum Target;               /**< GL_TEXTURE_1D, GL_TEXTURE_2D, etc. */
+   GLfloat Priority;		/**< in [0,1] */
+   GLfloat BorderColor[4];	/**< unclamped */
+   GLchan _BorderChan[4];	/**< clamped, as GLchan */
+   /** \name Wrap modes
+    * Are GL_CLAMP, REPEAT, GL_CLAMP_TO_EDGE, and GL_CLAMP_TO_BORDER_ARB. */
+   /*@{*/
+   GLenum WrapS;
+   GLenum WrapT;
+   GLenum WrapR;
+   /*@}*/
+   GLenum MinFilter;		/**< minification filter */
+   GLenum MagFilter;		/**< magnification filter */
+   GLfloat MinLod;		/**< min lambda, OpenGL 1.2 */
+   GLfloat MaxLod;		/**< max lambda, OpenGL 1.2 */
+   GLint BaseLevel;		/**< min mipmap level, OpenGL 1.2 */
+   GLint MaxLevel;		/**< max mipmap level, OpenGL 1.2 */
+   GLfloat MaxAnisotropy;	/**< GL_EXT_texture_filter_anisotropic */
+   GLboolean CompareFlag;	/**< GL_SGIX_shadow */
+   GLenum CompareOperator;	/**< GL_SGIX_shadow */
    GLfloat ShadowAmbient;
-   GLenum CompareMode;		/* GL_ARB_shadow */
-   GLenum CompareFunc;		/* GL_ARB_shadow */
-   GLenum DepthMode;		/* GL_ARB_depth_texture */
-   GLint _MaxLevel;		/* actual max mipmap level (q in the spec) */
-   GLfloat _MaxLambda;		/* = _MaxLevel - BaseLevel (q - b in spec) */
-   GLboolean GenerateMipmap;    /* GL_SGIS_generate_mipmap */
-   GLboolean _IsPowerOfTwo;	/* Are all image dimensions powers of two? */
+   GLenum CompareMode;		/**< GL_ARB_shadow */
+   GLenum CompareFunc;		/**< GL_ARB_shadow */
+   GLenum DepthMode;		/**< GL_ARB_depth_texture */
+   GLint _MaxLevel;		/**< actual max mipmap level (q in the spec) */
+   GLfloat _MaxLambda;		/**< = _MaxLevel - BaseLevel (q - b in spec) */
+   GLboolean GenerateMipmap;    /**< GL_SGIS_generate_mipmap */
+   GLboolean _IsPowerOfTwo;	/**< Are all image dimensions powers of two? */
 
    struct gl_texture_image *Image[MAX_TEXTURE_LEVELS];
 
-   /* Texture cube faces */
-   /* Image[] is alias for *PosX[MAX_TEXTURE_LEVELS]; */
+   /**
+    * \name Texture cube faces 
+    * 
+    * Image[] is alias for *PosX[MAX_TEXTURE_LEVELS];
+    */
+   /*@{*/
    struct gl_texture_image *NegX[MAX_TEXTURE_LEVELS];
    struct gl_texture_image *PosY[MAX_TEXTURE_LEVELS];
    struct gl_texture_image *NegY[MAX_TEXTURE_LEVELS];
    struct gl_texture_image *PosZ[MAX_TEXTURE_LEVELS];
    struct gl_texture_image *NegZ[MAX_TEXTURE_LEVELS];
+   /*@}*/
 
-   /* GL_EXT_paletted_texture */
+   /** GL_EXT_paletted_texture */
    struct gl_color_table Palette;
 
-   GLboolean Complete;			/* Is texture object complete? */
-   struct gl_texture_object *Next;	/* Next in linked list */
+   GLboolean Complete;			/**< Is texture object complete? */
+   struct gl_texture_object *Next;	/**< Next in linked list */
 
-   /* For device driver: */
-   void *DriverData;	/* Arbitrary device driver data */
+   /**
+    * \name For device driver
+    */
+   /*@{*/
+   void *DriverData;	/**< Arbitrary device driver data */
+   /*@}*/
 };
 
 
-/* Texture unit record */
+/**
+ * Texture unit record 
+ */
 struct gl_texture_unit {
-   GLuint Enabled;              /* bitmask of TEXTURE_*_BIT flags */
-   GLuint _ReallyEnabled;       /* 0 or exactly one of TEXTURE_*_BIT flags */
+   GLuint Enabled;              /**< bitmask of TEXTURE_*_BIT flags */
+   GLuint _ReallyEnabled;       /**< 0 or exactly one of TEXTURE_*_BIT flags */
 
-   GLenum EnvMode;              /* GL_MODULATE, GL_DECAL, GL_BLEND, etc. */
+   GLenum EnvMode;              /**< GL_MODULATE, GL_DECAL, GL_BLEND, etc. */
    GLfloat EnvColor[4];
-   GLuint TexGenEnabled;	/* Bitwise-OR of [STRQ]_BIT values */
-   GLenum GenModeS;		/* Tex coord generation mode, either */
-   GLenum GenModeT;		/*	GL_OBJECT_LINEAR, or */
-   GLenum GenModeR;		/*	GL_EYE_LINEAR, or    */
-   GLenum GenModeQ;		/*      GL_SPHERE_MAP        */
+   GLuint TexGenEnabled;	/**< Bitwise-OR of [STRQ]_BIT values */
+   /** \name Tex coord generation mode
+    * Either GL_OBJECT_LINEAR, GL_EYE_LINEAR or GL_SPHERE_MAP. */
+   /*@{*/
+   GLenum GenModeS;		
+   GLenum GenModeT;
+   GLenum GenModeR;
+   GLenum GenModeQ;
+   /*@}*/
    GLuint _GenBitS;
    GLuint _GenBitT;
    GLuint _GenBitR;
    GLuint _GenBitQ;
-   GLuint _GenFlags;		/* bitwise or of GenBit[STRQ] */
+   GLuint _GenFlags;		/**< bitwise or of GenBit[STRQ] */
    GLfloat ObjectPlaneS[4];
    GLfloat ObjectPlaneT[4];
    GLfloat ObjectPlaneR[4];
@@ -968,27 +1123,31 @@ struct gl_texture_unit {
    GLfloat EyePlaneT[4];
    GLfloat EyePlaneR[4];
    GLfloat EyePlaneQ[4];
-   GLfloat LodBias;		/* for biasing mipmap levels */
-
-   /* GL_EXT_texture_env_combine */
-   GLenum CombineModeRGB;       /* GL_REPLACE, GL_DECAL, GL_ADD, etc. */
-   GLenum CombineModeA;         /* GL_REPLACE, GL_DECAL, GL_ADD, etc. */
-   GLenum CombineSourceRGB[3];  /* GL_PRIMARY_COLOR, GL_TEXTURE, etc. */
-   GLenum CombineSourceA[3];    /* GL_PRIMARY_COLOR, GL_TEXTURE, etc. */
-   GLenum CombineOperandRGB[3]; /* SRC_COLOR, ONE_MINUS_SRC_COLOR, etc */
-   GLenum CombineOperandA[3];   /* SRC_ALPHA, ONE_MINUS_SRC_ALPHA, etc */
-   GLuint CombineScaleShiftRGB; /* 0, 1 or 2 */
-   GLuint CombineScaleShiftA;   /* 0, 1 or 2 */
+   GLfloat LodBias;		/**< for biasing mipmap levels */
+
+   /** 
+    * \name GL_EXT_texture_env_combine 
+    */
+   /*@{*/
+   GLenum CombineModeRGB;       /**< GL_REPLACE, GL_DECAL, GL_ADD, etc. */
+   GLenum CombineModeA;         /**< GL_REPLACE, GL_DECAL, GL_ADD, etc. */
+   GLenum CombineSourceRGB[3];  /**< GL_PRIMARY_COLOR, GL_TEXTURE, etc. */
+   GLenum CombineSourceA[3];    /**< GL_PRIMARY_COLOR, GL_TEXTURE, etc. */
+   GLenum CombineOperandRGB[3]; /**< SRC_COLOR, ONE_MINUS_SRC_COLOR, etc */
+   GLenum CombineOperandA[3];   /**< SRC_ALPHA, ONE_MINUS_SRC_ALPHA, etc */
+   GLuint CombineScaleShiftRGB; /**< 0, 1 or 2 */
+   GLuint CombineScaleShiftA;   /**< 0, 1 or 2 */
+   /*@}*/
 
    struct gl_texture_object *Current1D;
    struct gl_texture_object *Current2D;
    struct gl_texture_object *Current3D;
-   struct gl_texture_object *CurrentCubeMap; /* GL_ARB_texture_cube_map */
-   struct gl_texture_object *CurrentRect;    /* GL_NV_texture_rectangle */
+   struct gl_texture_object *CurrentCubeMap; /**< GL_ARB_texture_cube_map */
+   struct gl_texture_object *CurrentRect;    /**< GL_NV_texture_rectangle */
 
-   struct gl_texture_object *_Current; /* Points to really enabled tex obj */
+   struct gl_texture_object *_Current; /**< Points to really enabled tex obj */
 
-   struct gl_texture_object Saved1D;  /* only used by glPush/PopAttrib */
+   struct gl_texture_object Saved1D;  /**< only used by glPush/PopAttrib */
    struct gl_texture_object Saved2D;
    struct gl_texture_object Saved3D;
    struct gl_texture_object SavedCubeMap;
@@ -1001,16 +1160,21 @@ struct gl_texture_unit {
 };
 
 
-/* The texture attribute group */
+/**
+ * Texture attributes
+ */
 struct gl_texture_attrib {
-   /* multitexture */
-   GLuint CurrentUnit;	        /* Active texture unit */
-
-   GLuint _EnabledUnits;        /* one bit set for each really-enabled unit */
-   GLuint _EnabledCoordUnits;   /* one bit per enabled coordinate unit */
-   GLuint _GenFlags;            /* for texgen */
-   GLuint _TexGenEnabled;	
+   /**
+    * name multitexture 
+    */
+   /**@{*/
+   GLuint CurrentUnit;	        /**< Active texture unit */
+   GLuint _EnabledUnits;        /**< one bit set for each really-enabled unit */
+   GLuint _EnabledCoordUnits;   /**< one bit per enabled coordinate unit */
+   GLuint _GenFlags;            /**< for texgen */
+   GLuint _TexGenEnabled;
    GLuint _TexMatEnabled;
+   /**@}*/
 
    struct gl_texture_unit Unit[MAX_TEXTURE_UNITS];
 
@@ -1020,32 +1184,40 @@ struct gl_texture_attrib {
    struct gl_texture_object *ProxyCubeMap;
    struct gl_texture_object *ProxyRect;
 
-   /* GL_EXT_shared_texture_palette */
+   /** GL_EXT_shared_texture_palette */
    GLboolean SharedPalette;
    struct gl_color_table Palette;
 };
 
 
+/**
+ * Transformation attributes.
+ */
 struct gl_transform_attrib {
-   GLenum MatrixMode;				/* Matrix mode */
-   GLfloat EyeUserPlane[MAX_CLIP_PLANES][4];
-   GLfloat _ClipUserPlane[MAX_CLIP_PLANES][4];	/* derived */
-   GLuint ClipPlanesEnabled;                    /* on/off bitmask */
-   GLboolean Normalize;				/* Normalize all normals? */
-   GLboolean RescaleNormals;			/* GL_EXT_rescale_normal */
-   GLboolean RasterPositionUnclipped;           /* GL_IBM_rasterpos_clip */
+   GLenum MatrixMode;				/**< Matrix mode */
+   GLfloat EyeUserPlane[MAX_CLIP_PLANES][4];	/**< User clip planes */
+   GLfloat _ClipUserPlane[MAX_CLIP_PLANES][4];	/**< derived */
+   GLuint ClipPlanesEnabled;                    /**< on/off bitmask */
+   GLboolean Normalize;				/**< Normalize all normals? */
+   GLboolean RescaleNormals;			/**< GL_EXT_rescale_normal */
+   GLboolean RasterPositionUnclipped;           /**< GL_IBM_rasterpos_clip */
 };
 
 
+/**
+ * Viewport attributes.
+ */
 struct gl_viewport_attrib {
-   GLint X, Y;			/* position */
-   GLsizei Width, Height;	/* size */
-   GLfloat Near, Far;		/* Depth buffer range */
-   GLmatrix _WindowMap;		/* Mapping transformation as a matrix. */
+   GLint X, Y;			/**< position */
+   GLsizei Width, Height;	/**< size */
+   GLfloat Near, Far;		/**< Depth buffer range */
+   GLmatrix _WindowMap;		/**< Mapping transformation as a matrix. */
 };
 
 
-/* For the attribute stack: */
+/**
+ * Node for the attribute stack
+ */
 struct gl_attrib_node {
    GLbitfield kind;
    void *data;
@@ -1053,7 +1225,7 @@ struct gl_attrib_node {
 };
 
 
-/*
+/**
  * Client pixel packing/unpacking attributes
  */
 struct gl_pixelstore_attrib {
@@ -1061,35 +1233,38 @@ struct gl_pixelstore_attrib {
    GLint RowLength;
    GLint SkipPixels;
    GLint SkipRows;
-   GLint ImageHeight;     /* for GL_EXT_texture3D */
-   GLint SkipImages;      /* for GL_EXT_texture3D */
+   GLint ImageHeight;     /**< for GL_EXT_texture3D */
+   GLint SkipImages;      /**< for GL_EXT_texture3D */
    GLboolean SwapBytes;
    GLboolean LsbFirst;
-   GLboolean ClientStorage; /* GL_APPLE_client_storage */
-   GLboolean Invert;        /* GL_MESA_pack_invert */
+   GLboolean ClientStorage; /**< GL_APPLE_client_storage */
+   GLboolean Invert;        /**< GL_MESA_pack_invert */
 };
 
 
-#define CA_CLIENT_DATA     0x1	/* Data not alloced by mesa */
+#define CA_CLIENT_DATA     0x1	/**< Data not allocated by mesa */
 
 
-/*
+/**
  * Client vertex array attributes
  */
 struct gl_client_array {
    GLint Size;
    GLenum Type;
-   GLsizei Stride;		/* user-specified stride */
-   GLsizei StrideB;		/* actual stride in bytes */
+   GLsizei Stride;		/**< user-specified stride */
+   GLsizei StrideB;		/**< actual stride in bytes */
    void *Ptr;
    GLuint Flags;
-   GLuint Enabled;		/* one of the _NEW_ARRAY_ bits */
-   GLboolean Normalized;        /* GL_ARB_vertex_program */
+   GLuint Enabled;		/**< one of the _NEW_ARRAY_ bits */
+   GLboolean Normalized;        /**< GL_ARB_vertex_program */
 };
 
 
+/**
+ * Array attributes.
+ */
 struct gl_array_attrib {
-   struct gl_client_array Vertex;	     /* client data descriptors */
+   struct gl_client_array Vertex;	     /**< client data descriptors */
    struct gl_client_array Normal;
    struct gl_client_array Color;
    struct gl_client_array SecondaryColor;
@@ -1097,16 +1272,16 @@ struct gl_array_attrib {
    struct gl_client_array Index;
    struct gl_client_array TexCoord[MAX_TEXTURE_COORD_UNITS];
    struct gl_client_array EdgeFlag;
-   /* GL_NV_vertex_program */
-   struct gl_client_array VertexAttrib[VERT_ATTRIB_MAX];
+
+   struct gl_client_array VertexAttrib[VERT_ATTRIB_MAX];  /**< GL_NV_vertex_program */
 
    GLint TexCoordInterleaveFactor;
-   GLint ActiveTexture;		/* Client Active Texture */
+   GLint ActiveTexture;		/**< Client Active Texture */
    GLuint LockFirst;
    GLuint LockCount;
 
-   GLuint _Enabled;		/* _NEW_ARRAY_* - bit set if array enabled */
-   GLuint NewState;		/* _NEW_ARRAY_* */
+   GLuint _Enabled;		/**< _NEW_ARRAY_* - bit set if array enabled */
+   GLuint NewState;		/**< _NEW_ARRAY_* */
 
    /* GL_ARB_vertex_buffer_object */
    GLuint ArrayBufferBinding;
@@ -1133,45 +1308,52 @@ struct gl_feedback {
 };
 
 
+/**
+ * Selection attributes.
+ */
 struct gl_selection {
-   GLuint *Buffer;
-   GLuint BufferSize;	/* size of SelectBuffer */
-   GLuint BufferCount;	/* number of values in SelectBuffer */
-   GLuint Hits;		/* number of records in SelectBuffer */
-   GLuint NameStackDepth;
-   GLuint NameStack[MAX_NAME_STACK_DEPTH];
-   GLboolean HitFlag;
-   GLfloat HitMinZ, HitMaxZ;
+   GLuint *Buffer;	/**< selection buffer */
+   GLuint BufferSize;	/**< size of the selection buffer */
+   GLuint BufferCount;	/**< number of values in the selection buffer */
+   GLuint Hits;		/**< number of records in the selection buffer */
+   GLuint NameStackDepth; /**< name stack depth */
+   GLuint NameStack[MAX_NAME_STACK_DEPTH]; /**< name stack */
+   GLboolean HitFlag;	/**< hit flag */
+   GLfloat HitMinZ;	/**< minimum hit depth */
+   GLfloat HitMaxZ;	/**< maximum hit depth */
 };
 
 
-/*
+/**
  * 1-D Evaluator control points
  */
 struct gl_1d_map {
-   GLuint Order;	/* Number of control points */
-   GLfloat u1, u2, du;	/* u1, u2, 1.0/(u2-u1) */
-   GLfloat *Points;	/* Points to contiguous control points */
+   GLuint Order;	/**< Number of control points */
+   GLfloat u1, u2, du;	/**< u1, u2, 1.0/(u2-u1) */
+   GLfloat *Points;	/**< Points to contiguous control points */
 };
 
 
-/*
+/**
  * 2-D Evaluator control points
  */
 struct gl_2d_map {
-   GLuint Uorder;		/* Number of control points in U dimension */
-   GLuint Vorder;		/* Number of control points in V dimension */
+   GLuint Uorder;		/**< Number of control points in U dimension */
+   GLuint Vorder;		/**< Number of control points in V dimension */
    GLfloat u1, u2, du;
    GLfloat v1, v2, dv;
-   GLfloat *Points;		/* Points to contiguous control points */
+   GLfloat *Points;		/**< Points to contiguous control points */
 };
 
 
-/*
- * All evalutator control points
+/**
+ * All evaluator control points
  */
 struct gl_evaluators {
-   /* 1-D maps */
+   /** 
+    * \name 1-D maps
+    */
+   /*@{*/
    struct gl_1d_map Map1Vertex3;
    struct gl_1d_map Map1Vertex4;
    struct gl_1d_map Map1Index;
@@ -1181,9 +1363,13 @@ struct gl_evaluators {
    struct gl_1d_map Map1Texture2;
    struct gl_1d_map Map1Texture3;
    struct gl_1d_map Map1Texture4;
-   struct gl_1d_map Map1Attrib[16];  /* GL_NV_vertex_program */
+   struct gl_1d_map Map1Attrib[16];  /**< GL_NV_vertex_program */
+   /*@}*/
 
-   /* 2-D maps */
+   /** 
+    * \name 2-D maps 
+    */
+   /*@{*/
    struct gl_2d_map Map2Vertex3;
    struct gl_2d_map Map2Vertex4;
    struct gl_2d_map Map2Index;
@@ -1193,12 +1379,20 @@ struct gl_evaluators {
    struct gl_2d_map Map2Texture2;
    struct gl_2d_map Map2Texture3;
    struct gl_2d_map Map2Texture4;
-   struct gl_2d_map Map2Attrib[16];  /* GL_NV_vertex_program */
+   struct gl_2d_map Map2Attrib[16];  /**< GL_NV_vertex_program */
+   /*@}*/
 };
 
 
+/**
+ * \name NV_vertex_program runtime state
+ */
+/*@{*/
+
 
-/* NV_vertex_program runtime state */
+/** 
+ * Machine state (i.e. the register file) 
+ */
 struct vp_machine
 {
    GLfloat Registers[MAX_NV_VERTEX_PROGRAM_TEMPS
@@ -1209,7 +1403,9 @@ struct vp_machine
 };
 
 
-/* NV_fragment_program runtime state */
+/**
+ * NV_fragment_program runtime state
+ */
 struct fp_machine
 {
    GLfloat Registers[MAX_NV_FRAGMENT_PROGRAM_TEMPS
@@ -1225,7 +1421,9 @@ struct fp_machine
 struct vp_instruction;
 struct fp_instruction;
 
-/* Program parameters */
+/**
+ * Program parameters 
+ */
 struct program_parameter
 {
    const char *Name;
@@ -1234,7 +1432,9 @@ struct program_parameter
 };
 
 
-/* Base class for any kind of program object */
+/**
+ * Base class for any kind of program object
+ */
 struct program
 {
    GLuint Id;
@@ -1252,7 +1452,7 @@ struct program
 };
 
 
-/* Vertex program object */
+/** Vertex program object */
 struct vertex_program
 {
    struct program Base;   /* base class */
@@ -1263,23 +1463,23 @@ struct vertex_program
 };
 
 
-/* Fragment program object */
+/** Fragment program object */
 struct fragment_program
 {
-   struct program Base;   /* base class */
-   struct fp_instruction *Instructions;  /* Compiled instructions */
-   GLuint InputsRead;     /* Bitmask of which input regs are read */
-   GLuint OutputsWritten; /* Bitmask of which output regs are written to */
-   GLuint TexturesUsed[MAX_TEXTURE_IMAGE_UNITS];  /* TEXTURE_x_INDEX bitmask */
-   GLuint NumAluInstructions; /* GL_ARB_fragment_program */
+   struct program Base;   /**< base class */
+   struct fp_instruction *Instructions;  /**< Compiled instructions */
+   GLuint InputsRead;     /**< Bitmask of which input regs are read */
+   GLuint OutputsWritten; /**< Bitmask of which output regs are written to */
+   GLuint TexturesUsed[MAX_TEXTURE_IMAGE_UNITS];  /**< TEXTURE_x_INDEX bitmask */
+   GLuint NumAluInstructions; /**< GL_ARB_fragment_program */
    GLuint NumTexInstructions;
    GLuint NumTexIndirections;
-   struct program_parameter *Parameters; /* array [NumParameters] */
+   struct program_parameter *Parameters; /**< array [NumParameters] */
    GLuint NumParameters;
 };
 
 
-/*
+/**
  * State common to vertex and fragment programs.
  */
 struct program_state {
@@ -1288,16 +1488,16 @@ struct program_state {
 };
 
 
-/*
- * State for GL_ARB/NV_vertex_program
+/**
+ * State vars for GL_NV_vertex_program
  */
 struct vertex_program_state
 {
-   GLboolean Enabled;                    /* GL_VERTEX_PROGRAM_NV */
-   GLboolean PointSizeEnabled;           /* GL_VERTEX_PROGRAM_POINT_SIZE_NV */
-   GLboolean TwoSideEnabled;             /* GL_VERTEX_PROGRAM_TWO_SIDE_NV */
-   struct vertex_program *Current;       /* ptr to currently bound program */
-   struct vp_machine Machine;            /* machine state */
+   GLboolean Enabled;                    /**< GL_VERTEX_PROGRAM_NV */
+   GLboolean PointSizeEnabled;           /**< GL_VERTEX_PROGRAM_POINT_SIZE_NV */
+   GLboolean TwoSideEnabled;             /**< GL_VERTEX_PROGRAM_TWO_SIDE_NV */
+   struct vertex_program *Current;       /**< ptr to currently bound program */
+   struct vp_machine Machine;            /**< machine state */
 
    GLenum TrackMatrix[MAX_NV_VERTEX_PROGRAM_PARAMS / 4];
    GLenum TrackMatrixTransform[MAX_NV_VERTEX_PROGRAM_PARAMS / 4];
@@ -1314,6 +1514,7 @@ struct fragment_program_state
    struct fp_machine Machine;            /* machine state */
 };
 
+/*@}*/
 
 /*
  * State for GL_ARB_occlusion_query
@@ -1327,24 +1528,31 @@ struct occlusion_state
 };
 
 
-/*
+/**
  * State which can be shared by multiple contexts:
  */
 struct gl_shared_state {
-   _glthread_Mutex Mutex;		   /* for thread safety */
-   GLint RefCount;			   /* Reference count */
-   struct _mesa_HashTable *DisplayList;	   /* Display lists hash table */
-   struct _mesa_HashTable *TexObjects;	   /* Texture objects hash table */
-   struct gl_texture_object *TexObjectList;/* Linked list of texture objects */
+   _glthread_Mutex Mutex;		   /**< for thread safety */
+   GLint RefCount;			   /**< Reference count */
+   struct _mesa_HashTable *DisplayList;	   /**< Display lists hash table */
+   struct _mesa_HashTable *TexObjects;	   /**< Texture objects hash table */
+   struct gl_texture_object *TexObjectList;/**< Linked list of texture objects */
 
-   /* Default texture objects (shared by all multi-texture units) */
+   /**
+    * \name Default texture objects (shared by all multi-texture units)
+    */
+   /*@{*/
    struct gl_texture_object *Default1D;
    struct gl_texture_object *Default2D;
    struct gl_texture_object *Default3D;
    struct gl_texture_object *DefaultCubeMap;
    struct gl_texture_object *DefaultRect;
+   /*@}*/
 
-   /* GL_NV_vertex/_program */
+   /**
+    * \name GL_NV_vertex/_program 
+    */
+   /*@{*/
    struct _mesa_HashTable *Programs;
 #if FEATURE_ARB_vertex_program
    struct program *DefaultVertexProgram;
@@ -1352,56 +1560,75 @@ struct gl_shared_state {
 #if FEATURE_ARB_fragment_program
    struct program *DefaultFragmentProgram;
 #endif
+   /*@}*/
 
-   void *DriverData;  /* Device driver shared state */
+   void *DriverData;  /**< Device driver shared state */
 };
 
 
-/*
+/**
+ * Frame buffer.
+ *
  * A "frame buffer" is a color buffer and its optional ancillary buffers:
  * depth, accum, stencil, and software-simulated alpha buffers.
  * In C++ terms, think of this as a base class from which device drivers
  * will make derived classes.
  */
 struct gl_frame_buffer {
-   GLvisual Visual;		/* The corresponding visual */
+   GLvisual Visual;		/**< The corresponding visual */
 
-   GLuint Width, Height;	/* size of frame buffer in pixels */
+   GLuint Width, Height;	/**< size of frame buffer in pixels */
 
    GLboolean UseSoftwareDepthBuffer;
    GLboolean UseSoftwareAccumBuffer;
    GLboolean UseSoftwareStencilBuffer;
    GLboolean UseSoftwareAlphaBuffers;
 
-   /* Software depth (aka Z) buffer */
-   GLvoid *DepthBuffer;		/* array [Width*Height] of GLushort or GLuint*/
-
-   /* Software stencil buffer */
-   GLstencil *Stencil;		/* array [Width*Height] of GLstencil values */
-
-   /* Software accumulation buffer */
-   GLaccum *Accum;		/* array [4*Width*Height] of GLaccum values */
-
-   /* Software alpha planes */
-   GLvoid *FrontLeftAlpha;	/* array [Width*Height] of GLubyte */
-   GLvoid *BackLeftAlpha;	/* array [Width*Height] of GLubyte */
-   GLvoid *FrontRightAlpha;	/* array [Width*Height] of GLubyte */
-   GLvoid *BackRightAlpha;	/* array [Width*Height] of GLubyte */
-
-   /* Drawing bounds: intersection of window size and scissor box */
-   GLint _Xmin, _Ymin;  /* inclusive */
-   GLint _Xmax, _Ymax;  /* exclusive */
+   /** \name Software depth (aka Z) buffer */
+   /*@{*/
+   GLvoid *DepthBuffer;		/**< array [Width*Height] of GLushort or GLuint*/
+   /*@}*/
+
+   /** \name Software stencil buffer */
+   /*@{*/
+   GLstencil *Stencil;		/**< array [Width*Height] of GLstencil values */
+   /*@}*/
+
+   /** \name Software accumulation buffer */
+   /*@{*/
+   GLaccum *Accum;		/**< array [4*Width*Height] of GLaccum values */
+   /*@}*/
+
+   /** \name Software alpha planes */
+   /*@{*/
+   GLvoid *FrontLeftAlpha;	/**< array [Width*Height] of GLubyte */
+   GLvoid *BackLeftAlpha;	/**< array [Width*Height] of GLubyte */
+   GLvoid *FrontRightAlpha;	/**< array [Width*Height] of GLubyte */
+   GLvoid *BackRightAlpha;	/**< array [Width*Height] of GLubyte */
+   /*@}*/
+
+   /** 
+    * \name Drawing bounds
+    *
+    * Intersection of window size and scissor box 
+    */
+   /*@{*/
+   GLint _Xmin;  /**< inclusive */
+   GLint _Ymin;  /**< inclusive */
+   GLint _Xmax;  /**< exclusive */
+   GLint _Ymax;  /**< exclusive */
+   /*@}*/
 };
 
 
-/*
- * Constants which may be overriden by device driver during context creation
+/**
+ * Constants which may be overridden by device driver during context creation
  * but are never changed after that.
  */
 struct gl_constants {
-   GLint MaxTextureLevels;
-   GLint Max3DTextureLevels;
-   GLint MaxCubeTextureLevels;          /* GL_ARB_texture_cube_map */
+   GLint MaxTextureLevels;		/**< Maximum number of allowed mipmap levels. */ 
+   GLint Max3DTextureLevels;		/**< Maximum number of allowed mipmap levels for 3D texture targets. */
+   GLint MaxCubeTextureLevels;          /**< Maximum number of allowed mipmap levels for GL_ARB_texture_cube_map */
    GLint MaxTextureRectSize;            /* GL_NV_texture_rectangle */
    GLuint MaxTextureCoordUnits;
    GLuint MaxTextureImageUnits;
@@ -1447,13 +1674,16 @@ struct gl_constants {
 };
 
 
-/*
+/**
  * List of extensions.
  */
 struct gl_extensions {
-   /* Flags to quickly test if certain extensions are available.
+   /**
+    * \name Flags to quickly test if certain extensions are available.
+    * 
     * Not every extension needs to have such a flag, but it's encouraged.
     */
+   /*@{*/
    GLboolean dummy;  /* don't remove this! */
    GLboolean ARB_depth_texture;
    GLboolean ARB_fragment_program;
@@ -1525,27 +1755,31 @@ struct gl_extensions {
    GLboolean SGIX_shadow_ambient; /* or GL_ARB_shadow_ambient */
    GLboolean TDFX_texture_compression_FXT1;
    GLboolean APPLE_client_storage;
+   /*@}*/
    /* The extension string */
    const GLubyte *String;
 };
 
 
-/*
+/**
  * A stack of matrices (projection, modelview, color, texture, etc).
  */
 struct matrix_stack
 {
-   GLmatrix *Top;      /* points into Stack */
-   GLmatrix *Stack;    /* array [MaxDepth] of GLmatrix */
-   GLuint Depth;       /* 0 <= Depth < MaxDepth */
-   GLuint MaxDepth;    /* size of Stack[] array */
-   GLuint DirtyFlag;   /* _NEW_MODELVIEW or _NEW_PROJECTION, for example */
+   GLmatrix *Top;      /**< points into Stack */
+   GLmatrix *Stack;    /**< array [MaxDepth] of GLmatrix */
+   GLuint Depth;       /**< 0 <= Depth < MaxDepth */
+   GLuint MaxDepth;    /**< size of Stack[] array */
+   GLuint DirtyFlag;   /**< _NEW_MODELVIEW or _NEW_PROJECTION, for example */
 };
 
 
-/*
- * Bits for image transfer operations (ctx->ImageTransferState).
+/**
+ * \name Bits for image transfer operations 
+ *
+ * \sa __GLcontextRec::ImageTransferState.
  */
+/*@{*/
 #define IMAGE_SCALE_BIAS_BIT                      0x1
 #define IMAGE_SHIFT_OFFSET_BIT                    0x2
 #define IMAGE_MAP_COLOR_BIT                       0x4
@@ -1558,58 +1792,66 @@ struct matrix_stack
 #define IMAGE_HISTOGRAM_BIT                       0x200
 #define IMAGE_MIN_MAX_BIT                         0x400
 
-/* transfer ops up to convolution: */
+/** Transfer ops up to convolution */
 #define IMAGE_PRE_CONVOLUTION_BITS (IMAGE_SCALE_BIAS_BIT |     \
                                     IMAGE_SHIFT_OFFSET_BIT |   \
                                     IMAGE_MAP_COLOR_BIT |      \
                                     IMAGE_COLOR_TABLE_BIT)
 
-/* transfer ops after convolution: */
+/** Transfer ops after convolution */
 #define IMAGE_POST_CONVOLUTION_BITS (IMAGE_POST_CONVOLUTION_SCALE_BIAS |      \
                                      IMAGE_POST_CONVOLUTION_COLOR_TABLE_BIT | \
                                      IMAGE_COLOR_MATRIX_BIT |                 \
                                      IMAGE_POST_COLOR_MATRIX_COLOR_TABLE_BIT |\
                                      IMAGE_HISTOGRAM_BIT |                    \
                                      IMAGE_MIN_MAX_BIT)
+/*@}*/
 
 
-/*
- * Bits to indicate what state has changed.  6 unused flags.
- */
-#define _NEW_MODELVIEW		0x1        /* ctx->ModelView */
-#define _NEW_PROJECTION		0x2        /* ctx->Projection */
-#define _NEW_TEXTURE_MATRIX	0x4        /* ctx->TextureMatrix */
-#define _NEW_COLOR_MATRIX	0x8        /* ctx->ColorMatrix */
-#define _NEW_ACCUM		0x10       /* ctx->Accum */
-#define _NEW_COLOR		0x20       /* ctx->Color */
-#define _NEW_DEPTH		0x40       /* ctx->Depth */
-#define _NEW_EVAL		0x80       /* ctx->Eval, ctx->EvalMap */
-#define _NEW_FOG		0x100      /* ctx->Fog */
-#define _NEW_HINT		0x200      /* ctx->Hint */
-#define _NEW_LIGHT		0x400      /* ctx->Light */
-#define _NEW_LINE		0x800      /* ctx->Line */
-#define _NEW_PIXEL		0x1000     /* ctx->Pixel */
-#define _NEW_POINT		0x2000     /* ctx->Point */
-#define _NEW_POLYGON		0x4000     /* ctx->Polygon */
-#define _NEW_POLYGONSTIPPLE	0x8000     /* ctx->PolygonStipple */
-#define _NEW_SCISSOR		0x10000    /* ctx->Scissor */
-#define _NEW_STENCIL		0x20000    /* ctx->Stencil */
-#define _NEW_TEXTURE		0x40000    /* ctx->Texture */
-#define _NEW_TRANSFORM		0x80000    /* ctx->Transform */
-#define _NEW_VIEWPORT		0x100000   /* ctx->Viewport */
-#define _NEW_PACKUNPACK		0x200000   /* ctx->Pack, ctx->Unpack */
-#define _NEW_ARRAY	        0x400000   /* ctx->Array */
-#define _NEW_RENDERMODE		0x800000   /* RenderMode, Feedback, Select */
-#define _NEW_BUFFERS            0x1000000  /* ctx->Visual, ctx->DrawBuffer, */
-#define _NEW_MULTISAMPLE        0x2000000  /* ctx->Multisample */
-#define _NEW_TRACK_MATRIX       0x4000000  /* ctx->VertexProgram */
-#define _NEW_PROGRAM            0x8000000  /* ctx->VertexProgram */
+/**
+ * \name Bits to indicate what state has changed.  
+ *
+ * 6 unused flags.
+ */
+/*@{*/
+#define _NEW_MODELVIEW		0x1        /**< __GLcontextRec::ModelView */
+#define _NEW_PROJECTION		0x2        /**< __GLcontextRec::Projection */
+#define _NEW_TEXTURE_MATRIX	0x4        /**< __GLcontextRec::TextureMatrix */
+#define _NEW_COLOR_MATRIX	0x8        /**< __GLcontextRec::ColorMatrix */
+#define _NEW_ACCUM		0x10       /**< __GLcontextRec::Accum */
+#define _NEW_COLOR		0x20       /**< __GLcontextRec::Color */
+#define _NEW_DEPTH		0x40       /**< __GLcontextRec::Depth */
+#define _NEW_EVAL		0x80       /**< __GLcontextRec::Eval, __GLcontextRec::EvalMap */
+#define _NEW_FOG		0x100      /**< __GLcontextRec::Fog */
+#define _NEW_HINT		0x200      /**< __GLcontextRec::Hint */
+#define _NEW_LIGHT		0x400      /**< __GLcontextRec::Light */
+#define _NEW_LINE		0x800      /**< __GLcontextRec::Line */
+#define _NEW_PIXEL		0x1000     /**< __GLcontextRec::Pixel */
+#define _NEW_POINT		0x2000     /**< __GLcontextRec::Point */
+#define _NEW_POLYGON		0x4000     /**< __GLcontextRec::Polygon */
+#define _NEW_POLYGONSTIPPLE	0x8000     /**< __GLcontextRec::PolygonStipple */
+#define _NEW_SCISSOR		0x10000    /**< __GLcontextRec::Scissor */
+#define _NEW_STENCIL		0x20000    /**< __GLcontextRec::Stencil */
+#define _NEW_TEXTURE		0x40000    /**< __GLcontextRec::Texture */
+#define _NEW_TRANSFORM		0x80000    /**< __GLcontextRec::Transform */
+#define _NEW_VIEWPORT		0x100000   /**< __GLcontextRec::Viewport */
+#define _NEW_PACKUNPACK		0x200000   /**< __GLcontextRec::Pack, __GLcontextRec::Unpack */
+#define _NEW_ARRAY	        0x400000   /**< __GLcontextRec::Array */
+#define _NEW_RENDERMODE		0x800000   /**< __GLcontextRec::RenderMode, __GLcontextRec::Feedback, __GLcontextRec::Select */
+#define _NEW_BUFFERS            0x1000000  /**< __GLcontextRec::Visual, __GLcontextRec::DrawBuffer, */
+#define _NEW_MULTISAMPLE        0x2000000  /**< __GLcontextRec::Multisample */
+#define _NEW_TRACK_MATRIX       0x4000000  /**< __GLcontextRec::VertexProgram */
+#define _NEW_PROGRAM            0x8000000  /**< __GLcontextRec::VertexProgram */
 #define _NEW_ALL ~0
+/*@}*/
 
 
-
-/* Bits to track array state changes (also used to summarize array enabled)
+/**
+ * \name Bits to track array state changes 
+ *
+ * Also used to summarize array enabled.
  */
+/*@{*/
 #define _NEW_ARRAY_VERTEX           VERT_BIT_POS
 #define _NEW_ARRAY_WEIGHT           VERT_BIT_WEIGHT
 #define _NEW_ARRAY_NORMAL           VERT_BIT_NORMAL
@@ -1632,11 +1874,15 @@ struct matrix_stack
 
 #define _NEW_ARRAY_TEXCOORD(i) (_NEW_ARRAY_TEXCOORD_0 << (i))
 #define _NEW_ARRAY_ATTRIB(i) (_NEW_ARRAY_ATTRIB_0 << (i))
+/*@}*/
 
 
-/* A bunch of flags that we think might be useful to drivers.
- * Set in the ctx->_TriangleCaps bitfield.
+/**
+ * \name A bunch of flags that we think might be useful to drivers.
+ * 
+ * Set in the __GLcontextRec::_TriangleCaps bitfield.
  */
+/*@{*/
 #define DD_FLATSHADE                0x1
 #define DD_SEPARATE_SPECULAR        0x2
 #define DD_TRI_CULL_FRONT_BACK      0x4 /* special case on some hw */
@@ -1651,10 +1897,13 @@ struct matrix_stack
 #define DD_POINT_SMOOTH             0x800
 #define DD_POINT_SIZE               0x1000
 #define DD_POINT_ATTEN              0x2000
+/*@}*/
 
 
-/* Define the state changes under which each of these bits might change
+/**
+ * \name Define the state changes under which each of these bits might change
  */
+/*@{*/
 #define _DD_NEW_FLATSHADE                _NEW_LIGHT
 #define _DD_NEW_SEPARATE_SPECULAR        (_NEW_LIGHT | _NEW_FOG)
 #define _DD_NEW_TRI_CULL_FRONT_BACK      _NEW_POLYGON
@@ -1669,6 +1918,8 @@ struct matrix_stack
 #define _DD_NEW_POINT_SMOOTH             _NEW_POINT
 #define _DD_NEW_POINT_SIZE               _NEW_POINT
 #define _DD_NEW_POINT_ATTEN              _NEW_POINT
+/*@}*/
+
 
 #define _MESA_NEW_NEED_EYE_COORDS         (_NEW_LIGHT |		\
                                            _NEW_TEXTURE |	\
@@ -1681,20 +1932,10 @@ struct matrix_stack
 #define _IMAGE_NEW_TRANSFER_STATE         (_NEW_PIXEL | _NEW_COLOR_MATRIX)
 
 
-/* Bits for ctx->_NeedNormals */
-#define NEED_NORMALS_TEXGEN      0x1
-#define NEED_NORMALS_LIGHT       0x2
-
-/* Bits for ctx->_NeedEyeCoords */
-#define NEED_EYE_TEXGEN          0x1
-#define NEED_EYE_LIGHT           0x2
-#define NEED_EYE_LIGHT_MODELVIEW 0x4
-#define NEED_EYE_POINT_ATTEN     0x8
-#define NEED_EYE_DRIVER          0x10
 
 
 /*
- * Forward declaration of display list datatypes:
+ * Forward declaration of display list data types:
  */
 union node;
 typedef union node Node;
@@ -1704,25 +1945,31 @@ typedef union node Node;
 #include "dd.h"
 
 
-/*
- * Core Mesa's support for tnl modules:
- */
 #define NUM_VERTEX_FORMAT_ENTRIES (sizeof(GLvertexformat) / sizeof(void *))
 
+/**
+ * Core Mesa's support for tnl modules:
+ */
 struct gl_tnl_module {
-   /* Vertex format to be lazily swapped into current dispatch.
+   /**
+    * Vertex format to be lazily swapped into current dispatch.
     */
    GLvertexformat *Current;
 
-   /* Record of functions swapped out.  On restore, only need to swap
-    * these functions back in.
+   /**
+    * \name Record of functions swapped out.  
+    * On restore, only need to swap these functions back in.
     */
+   /*@{*/
    void *Swapped[NUM_VERTEX_FORMAT_ENTRIES][2];
    GLuint SwapCount;
+   /*@}*/
 };
 
 
 /**
+ * Mesa context
+ *
  * This is the central context data structure for Mesa.  Almost all
  * OpenGL state is contained in this structure.
  * Think of this as a base class from which device drivers will derive
@@ -1730,20 +1977,25 @@ struct gl_tnl_module {
  */
 struct __GLcontextRec {
    /**
-    * OS related interfaces; these *must* be the first members of this
-    * structure, because they are exposed to the outside world (i.e. GLX
-    * extension).
+    * \name OS related interfaces. 
+    *
+    * These \b must be the first members of this structure, because they are
+    * exposed to the outside world (i.e. GLX extension).
     */
+   /*@{*/
    __GLimports imports;
    __GLexports exports;
+   /*@}*/
 
-   /* State possibly shared with other contexts in the address space */
+   /** State possibly shared with other contexts in the address space */
    struct gl_shared_state *Shared;
 
-   /* API function pointer tables */
-   struct _glapi_table *Save;	/**< Display list save funcs */
-   struct _glapi_table *Exec;	/**< Execute funcs */
+   /** \name API function pointer tables */
+   /*@{*/
+   struct _glapi_table *Save;	/**< Display list save functions */
+   struct _glapi_table *Exec;	/**< Execute functions */
    struct _glapi_table *CurrentDispatch;  /**< == Save or Exec !! */
+   /*@}*/
 
    GLboolean ExecPrefersFloat;	/**< What preference for color conversion? */
    GLboolean SavePrefersFloat;
@@ -1760,127 +2012,153 @@ struct __GLcontextRec {
    void *DriverCtx;	/**< Points to device driver context/state */
    void *DriverMgrCtx;	/**< Points to device driver manager (optional)*/
 
-   /* Core/Driver constants */
+   /** Core/Driver constants */
    struct gl_constants Const;
 
-   /* The various 4x4 matrix stacks */
+   /** \name The various 4x4 matrix stacks */
+   /*@{*/
    struct matrix_stack ModelviewMatrixStack;
    struct matrix_stack ProjectionMatrixStack;
    struct matrix_stack ColorMatrixStack;
    struct matrix_stack TextureMatrixStack[MAX_TEXTURE_COORD_UNITS];
    struct matrix_stack ProgramMatrixStack[MAX_PROGRAM_MATRICES];
-   struct matrix_stack *CurrentStack; /* Points to one of the above stacks */
+   struct matrix_stack *CurrentStack; /**< Points to one of the above stacks */
+   /*@}*/
 
-   /* Combined modelview and projection matrix */
+   /** Combined modelview and projection matrix */
    GLmatrix _ModelProjectMatrix;
 
-   /* Display lists */
-   GLuint CallDepth;		/* Current recursion calling depth */
-   GLboolean ExecuteFlag;	/* Execute GL commands? */
-   GLboolean CompileFlag;	/* Compile GL commands into display list? */
-   Node *CurrentListPtr;	/* Head of list being compiled */
-   GLuint CurrentListNum;	/* Number of the list being compiled */
-   Node *CurrentBlock;		/* Pointer to current block of nodes */
-   GLuint CurrentPos;		/* Index into current block of nodes */
-
-   /* Extensions */
+   /** \name Display lists */
+   /*@{*/
+   GLuint CallDepth;		/**< Current recursion calling depth */
+   GLboolean ExecuteFlag;	/**< Execute GL commands? */
+   GLboolean CompileFlag;	/**< Compile GL commands into display list? */
+   Node *CurrentListPtr;	/**< Head of list being compiled */
+   GLuint CurrentListNum;	/**< Number of the list being compiled */
+   Node *CurrentBlock;		/**< Pointer to current block of nodes */
+   GLuint CurrentPos;		/**< Index into current block of nodes */
+   /*@}*/
+
+   /** Extensions */
    struct gl_extensions Extensions;
 
-   /* Renderer attribute stack */
+   /** \name Renderer attribute stack */
+   /*@{*/
    GLuint AttribStackDepth;
    struct gl_attrib_node *AttribStack[MAX_ATTRIB_STACK_DEPTH];
+   /*@}*/
 
-   /* Renderer attribute groups */
-   struct gl_accum_attrib	Accum;
-   struct gl_colorbuffer_attrib	Color;
-   struct gl_current_attrib	Current;
-   struct gl_depthbuffer_attrib	Depth;
-   struct gl_eval_attrib	Eval;
-   struct gl_fog_attrib		Fog;
-   struct gl_hint_attrib	Hint;
-   struct gl_light_attrib	Light;
-   struct gl_line_attrib	Line;
-   struct gl_list_attrib	List;
+   /** \name Renderer attribute groups
+    * 
+    * We define a struct for each attribute group to make pushing and popping
+    * attributes easy.  Also it's a good organization.
+    */
+   /*@{*/
+   struct gl_accum_attrib	Accum;		/**< Accumulation buffer attributes */
+   struct gl_colorbuffer_attrib	Color;		/**< Color buffers attributes */
+   struct gl_current_attrib	Current;	/**< Current attributes */
+   struct gl_depthbuffer_attrib	Depth;		/**< Depth buffer attributes */
+   struct gl_eval_attrib	Eval;		/**< Eval attributes */
+   struct gl_fog_attrib		Fog;		/**< Fog attributes */
+   struct gl_hint_attrib	Hint;		/**< Hint attributes */
+   struct gl_light_attrib	Light;		/**< Light attributes */
+   struct gl_line_attrib	Line;		/**< Line attributes */
+   struct gl_list_attrib	List;		/**< List attributes */
    struct gl_multisample_attrib Multisample;
-   struct gl_pixel_attrib	Pixel;
-   struct gl_point_attrib	Point;
-   struct gl_polygon_attrib	Polygon;
-   GLuint PolygonStipple[32];
-   struct gl_scissor_attrib	Scissor;
-   struct gl_stencil_attrib	Stencil;
-   struct gl_texture_attrib	Texture;
-   struct gl_transform_attrib	Transform;
-   struct gl_viewport_attrib	Viewport;
-
-   /* Other attribute groups */
+   struct gl_pixel_attrib	Pixel;		/**< Pixel attributes */
+   struct gl_point_attrib	Point;		/**< Point attributes */
+   struct gl_polygon_attrib	Polygon;	/**< Polygon attributes */
+   GLuint PolygonStipple[32];			/**< Polygon stipple */
+   struct gl_scissor_attrib	Scissor;	/**< Scissor attributes */
+   struct gl_stencil_attrib	Stencil;	/**< Stencil buffer attributes */
+   struct gl_texture_attrib	Texture;	/**< Texture attributes */
+   struct gl_transform_attrib	Transform;	/**< Transformation attributes */
+   struct gl_viewport_attrib	Viewport;	/**< Viewport attributes */
+   /*@}*/
+
+   /** \name Other attribute groups */
+   /*@{*/
    struct gl_histogram_attrib	Histogram;
    struct gl_minmax_attrib	MinMax;
    struct gl_convolution_attrib Convolution1D;
    struct gl_convolution_attrib Convolution2D;
    struct gl_convolution_attrib Separable2D;
+   /*@}*/
 
-   /* Client attribute stack */
+   /** \name Client attribute stack */
+   /*@{*/
    GLuint ClientAttribStackDepth;
    struct gl_attrib_node *ClientAttribStack[MAX_CLIENT_ATTRIB_STACK_DEPTH];
+   /*@}*/
 
-   /* Client attribute groups */
-   struct gl_array_attrib	Array;	/* Vertex arrays */
-   struct gl_pixelstore_attrib	Pack;	/* Pixel packing */
-   struct gl_pixelstore_attrib	Unpack;	/* Pixel unpacking */
+   /** \name Client attribute groups */
+   /*@{*/
+   struct gl_array_attrib	Array;	/**< Vertex arrays */
+   struct gl_pixelstore_attrib	Pack;	/**< Pixel packing */
+   struct gl_pixelstore_attrib	Unpack;	/**< Pixel unpacking */
 
-   struct gl_evaluators EvalMap;   /* All evaluators */
-   struct gl_feedback   Feedback;  /* Feedback */
-   struct gl_selection  Select;    /* Selection */
+   struct gl_evaluators EvalMap;   /**< All evaluators */
+   struct gl_feedback   Feedback;  /**< Feedback */
+   struct gl_selection  Select;    /**< Selection */
 
-   struct gl_color_table ColorTable;       /* Pre-convolution */
-   struct gl_color_table ProxyColorTable;  /* Pre-convolution */
+   struct gl_color_table ColorTable;       /**< Pre-convolution */
+   struct gl_color_table ProxyColorTable;  /**< Pre-convolution */
    struct gl_color_table PostConvolutionColorTable;
    struct gl_color_table ProxyPostConvolutionColorTable;
    struct gl_color_table PostColorMatrixColorTable;
    struct gl_color_table ProxyPostColorMatrixColorTable;
 
-   struct program_state Program;             /* for vertex or fragment progs */
-   struct vertex_program_state VertexProgram;      /* GL_NV_vertex_program */
-   struct fragment_program_state FragmentProgram;  /* GL_NV_fragment_program */
+   struct program_state Program;             /**< for vertex or fragment progs */
+   struct vertex_program_state VertexProgram;      /**< GL_NV_vertex_program */
+   struct fragment_program_state FragmentProgram;  /**< GL_NV_fragment_program */
 
-   struct occlusion_state Occlusion;  /* GL_ARB_occlusion_query */
+   struct occlusion_state Occlusion;  /**< GL_ARB_occlusion_query */
 
-   GLenum ErrorValue;        /* Last error code */
-   GLenum RenderMode;        /* either GL_RENDER, GL_SELECT, GL_FEEDBACK */
-   GLuint NewState;          /* bitwise-or of _NEW_* flags */
+   GLenum ErrorValue;        /**< Last error code */
+   GLenum RenderMode;        /**< either GL_RENDER, GL_SELECT, GL_FEEDBACK */
+   GLuint NewState;          /**< bitwise-or of _NEW_* flags */
+   /*@}*/
 
-   /* Derived */
-   GLuint _TriangleCaps;      /* bitwise-or of DD_* flags */
-   GLuint _ImageTransferState;/* bitwise-or of IMAGE_*_BIT flags */
+   /** \name Derived */
+   /*@{*/
+   GLuint _TriangleCaps;      /**< bitwise-or of DD_* flags */
+   GLuint _ImageTransferState;/**< bitwise-or of IMAGE_*_BIT flags */
    GLfloat _EyeZDir[3];
    GLfloat _ModelViewInvScale;
    GLuint _NeedEyeCoords;
-   GLuint _NeedNormals;    /* Are vertex normal vectors needed? */
+   GLuint _ForceEyeCoords; 
+   GLboolean _RotateMode;
 
-   struct gl_shine_tab *_ShineTable[2]; /* Active shine tables */
-   struct gl_shine_tab *_ShineTabList;  /* Mru list of inactive shine tables */
+   struct gl_shine_tab *_ShineTable[2]; /**< Active shine tables */
+   struct gl_shine_tab *_ShineTabList;  /**< MRU list of inactive shine tables */
+   /**@}*/
 
-   struct gl_list_extensions listext; /* driver dlist extensions */
+   struct gl_list_extensions listext; /**< driver dlist extensions */
 
 
    GLboolean OcclusionResult;       /**< for GL_HP_occlusion_test */
    GLboolean OcclusionResultSaved;  /**< for GL_HP_occlusion_test */
-   GLuint _Facing; /* This is a hack for 2-sided stencil test.  We don't */
-                   /* have a better way to communicate this value from */
-                   /* swrast_setup to swrast. */
+   GLuint _Facing; /**< This is a hack for 2-sided stencil test.
+		    *
+		    * We don't have a better way to communicate this value from
+		    * swrast_setup to swrast. */
 
 
-   /* Z buffer stuff */
+   /** \name Z buffer stuff */
+   /*@{*/
    GLuint DepthMax;	/**< Max depth buffer value */
    GLfloat DepthMaxF;	/**< Float max depth buffer value */
    GLfloat MRD;		/**< minimum resolvable difference in Z values */
+   /*@}*/
 
    /** Should 3Dfx Glide driver catch signals? */
    GLboolean CatchSignals;
 
-   /** For debugging/development only */
+   /** \name For debugging/development only */
+   /*@{*/
    GLboolean NoRaster;
    GLboolean FirstTimeCurrent;
+   /*@}*/
 
    /** Dither disable via MESA_NO_DITHER env var */
    GLboolean NoDither;
@@ -1895,22 +2173,26 @@ struct __GLcontextRec {
    void *TraceCtx;
 #endif
 
-   /* Core tnl module support */
+   /** Core tnl module support */
    struct gl_tnl_module TnlModule;
 
-   /* Hooks for module contexts.  These will eventually live
-    * in the driver or elsewhere.
+   /**
+    * \name Hooks for module contexts.  
+    *
+    * These will eventually live in the driver or elsewhere.
     */
+   /*@{*/
    void *swrast_context;
    void *swsetup_context;
    void *swtnl_context;
    void *swtnl_im;
    void *acache_context;
    void *aelt_context;
+   /*@}*/
 };
 
 
-/* The string names for GL_POINT, GL_LINE_LOOP, etc */
+/** The string names for GL_POINT, GL_LINE_LOOP, etc */
 extern const char *_mesa_prim_name[GL_POLYGON+4];
 
 
@@ -1950,7 +2232,17 @@ enum _debug {
 #define Elements(x) sizeof(x)/sizeof(*(x))
 
 
-/* Eventually let the driver specify what statechanges require a flush:
+/**
+ * Flush vertices.
+ *
+ * \param ctx GL context.
+ * \param newstate new state.
+ *
+ * Checks if dd_function_table::NeedFlush is marked to flush stored vertices,
+ * and calls dd_function_table::FlushVertices if so. Marks
+ * __GLcontextRec::NewState with \p newstate.
+ * 
+ * \todo Eventually let the driver specify what state changes require a flush:
  */
 #define FLUSH_VERTICES(ctx, newstate)				\
 do {								\
@@ -1961,6 +2253,16 @@ do {								\
    ctx->NewState |= newstate;					\
 } while (0)
 
+/**
+ * Flush current state.
+ *
+ * \param ctx GL context.
+ * \param newstate new state.
+ *
+ * Checks if dd_function_table::NeedFlush is marked to flush current state,
+ * and calls dd_function_table::FlushVertices if so. Marks
+ * __GLcontextRec::NewState with \p newstate.
+ */
 #define FLUSH_CURRENT(ctx, newstate)				\
 do {								\
    if (MESA_VERBOSE & VERBOSE_STATE)				\
@@ -1970,6 +2272,13 @@ do {								\
    ctx->NewState |= newstate;					\
 } while (0)
 
+/**
+ * Macro to assert that the API call was made outside the
+ * glBegin()/glEnd() pair, with return value.
+ * 
+ * \param ctx GL context.
+ * \param retval value to return value in case the assertion fails.
+ */
 #define ASSERT_OUTSIDE_BEGIN_END_WITH_RETVAL(ctx, retval)		\
 do {									\
    if (ctx->Driver.CurrentExecPrimitive != PRIM_OUTSIDE_BEGIN_END) {	\
@@ -1978,6 +2287,12 @@ do {									\
    }									\
 } while (0)
 
+/**
+ * Macro to assert that the API call was made outside the
+ * glBegin()/glEnd() pair.
+ * 
+ * \param ctx GL context.
+ */
 #define ASSERT_OUTSIDE_BEGIN_END(ctx)					\
 do {									\
    if (ctx->Driver.CurrentExecPrimitive != PRIM_OUTSIDE_BEGIN_END) {	\
@@ -1986,12 +2301,25 @@ do {									\
    }									\
 } while (0)
 
+/**
+ * Macro to assert that the API call was made outside the
+ * glBegin()/glEnd() pair and flush the vertices.
+ * 
+ * \param ctx GL context.
+ */
 #define ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH(ctx)				\
 do {									\
    ASSERT_OUTSIDE_BEGIN_END(ctx);					\
    FLUSH_VERTICES(ctx, 0);						\
 } while (0)
 
+/**
+ * Macro to assert that the API call was made outside the
+ * glBegin()/glEnd() pair and flush the vertices, with return value.
+ * 
+ * \param ctx GL context.
+ * \param retval value to return value in case the assertion fails.
+ */
 #define ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH_WITH_RETVAL(ctx, retval)	\
 do {									\
    ASSERT_OUTSIDE_BEGIN_END_WITH_RETVAL(ctx, retval);			\
@@ -1999,6 +2327,4 @@ do {									\
 } while (0)
 
 
-
-
 #endif /* TYPES_H */
diff --git a/src/mesa/main/nvfragparse.c b/src/mesa/main/nvfragparse.c
index f9d66f4a25..38da433197 100644
--- a/src/mesa/main/nvfragparse.c
+++ b/src/mesa/main/nvfragparse.c
@@ -24,7 +24,7 @@
 
 /**
  * \file nvfragparse.c
- * \brief NVIDIA fragment program parser.
+ * NVIDIA fragment program parser.
  * \author Brian Paul
  */
 
diff --git a/src/mesa/main/nvprogram.c b/src/mesa/main/nvprogram.c
index 67f416dbc2..6c5c15a3ca 100644
--- a/src/mesa/main/nvprogram.c
+++ b/src/mesa/main/nvprogram.c
@@ -24,7 +24,7 @@
 
 /**
  * \file nvprogram.c
- * \brief NVIDIA vertex/fragment program state management functions.
+ * NVIDIA vertex/fragment program state management functions.
  * \author Brian Paul
  */
 
diff --git a/src/mesa/main/nvvertexec.c b/src/mesa/main/nvvertexec.c
index bacbea8343..b81c2278a5 100644
--- a/src/mesa/main/nvvertexec.c
+++ b/src/mesa/main/nvvertexec.c
@@ -24,7 +24,7 @@
 
 /**
  * \file nvvertexec.c
- * \brief Code to execute vertex programs.
+ * Code to execute vertex programs.
  * \author Brian Paul
  */
 
diff --git a/src/mesa/main/nvvertparse.c b/src/mesa/main/nvvertparse.c
index a06f02060e..2e18c7abe4 100644
--- a/src/mesa/main/nvvertparse.c
+++ b/src/mesa/main/nvvertparse.c
@@ -24,7 +24,7 @@
 
 /**
  * \file nvvertparse.c
- * \brief NVIDIA vertex program parser.
+ * NVIDIA vertex program parser.
  * \author Brian Paul
  */
 
diff --git a/src/mesa/main/occlude.c b/src/mesa/main/occlude.c
index 029e5d0894..4a5df2127f 100644
--- a/src/mesa/main/occlude.c
+++ b/src/mesa/main/occlude.c
@@ -24,7 +24,7 @@
 
 
 /*
- * \brief Functions to implement the GL_ARB_occlusion_query extension.
+ * Functions to implement the GL_ARB_occlusion_query extension.
  */
 
 
diff --git a/src/mesa/main/pixel.c b/src/mesa/main/pixel.c
index db378226f8..ce4be7eadc 100644
--- a/src/mesa/main/pixel.c
+++ b/src/mesa/main/pixel.c
@@ -776,8 +776,6 @@ _mesa_PixelTransferi( GLenum pname, GLint param )
    _mesa_PixelTransferf( pname, (GLfloat) param );
 }
 
-
-
 /**********************************************************************/
 /*****                  Pixel processing functions               ******/
 /**********************************************************************/
@@ -1326,3 +1324,199 @@ _mesa_chan_to_float_span(const GLcontext *ctx, GLuint n,
    }
 #endif
 }
+
+/**********************************************************************/
+/*****                    State Management                        *****/
+/**********************************************************************/
+
+/*
+ * Return a bitmask of IMAGE_*_BIT flags which to indicate which
+ * pixel transfer operations are enabled.
+ */
+static void
+update_image_transfer_state(GLcontext *ctx)
+{
+   GLuint mask = 0;
+
+   if (ctx->Pixel.RedScale   != 1.0F || ctx->Pixel.RedBias   != 0.0F ||
+       ctx->Pixel.GreenScale != 1.0F || ctx->Pixel.GreenBias != 0.0F ||
+       ctx->Pixel.BlueScale  != 1.0F || ctx->Pixel.BlueBias  != 0.0F ||
+       ctx->Pixel.AlphaScale != 1.0F || ctx->Pixel.AlphaBias != 0.0F)
+      mask |= IMAGE_SCALE_BIAS_BIT;
+
+   if (ctx->Pixel.IndexShift || ctx->Pixel.IndexOffset)
+      mask |= IMAGE_SHIFT_OFFSET_BIT;
+
+   if (ctx->Pixel.MapColorFlag)
+      mask |= IMAGE_MAP_COLOR_BIT;
+
+   if (ctx->Pixel.ColorTableEnabled)
+      mask |= IMAGE_COLOR_TABLE_BIT;
+
+   if (ctx->Pixel.Convolution1DEnabled ||
+       ctx->Pixel.Convolution2DEnabled ||
+       ctx->Pixel.Separable2DEnabled) {
+      mask |= IMAGE_CONVOLUTION_BIT;
+      if (ctx->Pixel.PostConvolutionScale[0] != 1.0F ||
+          ctx->Pixel.PostConvolutionScale[1] != 1.0F ||
+          ctx->Pixel.PostConvolutionScale[2] != 1.0F ||
+          ctx->Pixel.PostConvolutionScale[3] != 1.0F ||
+          ctx->Pixel.PostConvolutionBias[0] != 0.0F ||
+          ctx->Pixel.PostConvolutionBias[1] != 0.0F ||
+          ctx->Pixel.PostConvolutionBias[2] != 0.0F ||
+          ctx->Pixel.PostConvolutionBias[3] != 0.0F) {
+         mask |= IMAGE_POST_CONVOLUTION_SCALE_BIAS;
+      }
+   }
+
+   if (ctx->Pixel.PostConvolutionColorTableEnabled)
+      mask |= IMAGE_POST_CONVOLUTION_COLOR_TABLE_BIT;
+
+   if (ctx->ColorMatrixStack.Top->type != MATRIX_IDENTITY ||
+       ctx->Pixel.PostColorMatrixScale[0] != 1.0F ||
+       ctx->Pixel.PostColorMatrixBias[0]  != 0.0F ||
+       ctx->Pixel.PostColorMatrixScale[1] != 1.0F ||
+       ctx->Pixel.PostColorMatrixBias[1]  != 0.0F ||
+       ctx->Pixel.PostColorMatrixScale[2] != 1.0F ||
+       ctx->Pixel.PostColorMatrixBias[2]  != 0.0F ||
+       ctx->Pixel.PostColorMatrixScale[3] != 1.0F ||
+       ctx->Pixel.PostColorMatrixBias[3]  != 0.0F)
+      mask |= IMAGE_COLOR_MATRIX_BIT;
+
+   if (ctx->Pixel.PostColorMatrixColorTableEnabled)
+      mask |= IMAGE_POST_COLOR_MATRIX_COLOR_TABLE_BIT;
+
+   if (ctx->Pixel.HistogramEnabled)
+      mask |= IMAGE_HISTOGRAM_BIT;
+
+   if (ctx->Pixel.MinMaxEnabled)
+      mask |= IMAGE_MIN_MAX_BIT;
+
+   ctx->_ImageTransferState = mask;
+}
+
+
+void _mesa_update_pixel( GLcontext *ctx, GLuint new_state )
+{
+   if (new_state & _NEW_COLOR_MATRIX)
+      _math_matrix_analyse( ctx->ColorMatrixStack.Top );
+
+   /* References ColorMatrix.type (derived above).
+    */
+   if (new_state & _IMAGE_NEW_TRANSFER_STATE)
+      update_image_transfer_state(ctx);
+}
+
+
+/**********************************************************************/
+/*****                      Initialization                        *****/
+/**********************************************************************/
+
+void _mesa_init_pixel( GLcontext * ctx )
+{
+   int i;
+
+   /* Pixel group */
+   ctx->Pixel.RedBias = 0.0;
+   ctx->Pixel.RedScale = 1.0;
+   ctx->Pixel.GreenBias = 0.0;
+   ctx->Pixel.GreenScale = 1.0;
+   ctx->Pixel.BlueBias = 0.0;
+   ctx->Pixel.BlueScale = 1.0;
+   ctx->Pixel.AlphaBias = 0.0;
+   ctx->Pixel.AlphaScale = 1.0;
+   ctx->Pixel.DepthBias = 0.0;
+   ctx->Pixel.DepthScale = 1.0;
+   ctx->Pixel.IndexOffset = 0;
+   ctx->Pixel.IndexShift = 0;
+   ctx->Pixel.ZoomX = 1.0;
+   ctx->Pixel.ZoomY = 1.0;
+   ctx->Pixel.MapColorFlag = GL_FALSE;
+   ctx->Pixel.MapStencilFlag = GL_FALSE;
+   ctx->Pixel.MapStoSsize = 1;
+   ctx->Pixel.MapItoIsize = 1;
+   ctx->Pixel.MapItoRsize = 1;
+   ctx->Pixel.MapItoGsize = 1;
+   ctx->Pixel.MapItoBsize = 1;
+   ctx->Pixel.MapItoAsize = 1;
+   ctx->Pixel.MapRtoRsize = 1;
+   ctx->Pixel.MapGtoGsize = 1;
+   ctx->Pixel.MapBtoBsize = 1;
+   ctx->Pixel.MapAtoAsize = 1;
+   ctx->Pixel.MapStoS[0] = 0;
+   ctx->Pixel.MapItoI[0] = 0;
+   ctx->Pixel.MapItoR[0] = 0.0;
+   ctx->Pixel.MapItoG[0] = 0.0;
+   ctx->Pixel.MapItoB[0] = 0.0;
+   ctx->Pixel.MapItoA[0] = 0.0;
+   ctx->Pixel.MapItoR8[0] = 0;
+   ctx->Pixel.MapItoG8[0] = 0;
+   ctx->Pixel.MapItoB8[0] = 0;
+   ctx->Pixel.MapItoA8[0] = 0;
+   ctx->Pixel.MapRtoR[0] = 0.0;
+   ctx->Pixel.MapGtoG[0] = 0.0;
+   ctx->Pixel.MapBtoB[0] = 0.0;
+   ctx->Pixel.MapAtoA[0] = 0.0;
+   ctx->Pixel.HistogramEnabled = GL_FALSE;
+   ctx->Pixel.MinMaxEnabled = GL_FALSE;
+   ctx->Pixel.PixelTextureEnabled = GL_FALSE;
+   ctx->Pixel.FragmentRgbSource = GL_PIXEL_GROUP_COLOR_SGIS;
+   ctx->Pixel.FragmentAlphaSource = GL_PIXEL_GROUP_COLOR_SGIS;
+   ASSIGN_4V(ctx->Pixel.PostColorMatrixScale, 1.0, 1.0, 1.0, 1.0);
+   ASSIGN_4V(ctx->Pixel.PostColorMatrixBias, 0.0, 0.0, 0.0, 0.0);
+   ASSIGN_4V(ctx->Pixel.ColorTableScale, 1.0, 1.0, 1.0, 1.0);
+   ASSIGN_4V(ctx->Pixel.ColorTableBias, 0.0, 0.0, 0.0, 0.0);
+   ASSIGN_4V(ctx->Pixel.PCCTscale, 1.0, 1.0, 1.0, 1.0);
+   ASSIGN_4V(ctx->Pixel.PCCTbias, 0.0, 0.0, 0.0, 0.0);
+   ASSIGN_4V(ctx->Pixel.PCMCTscale, 1.0, 1.0, 1.0, 1.0);
+   ASSIGN_4V(ctx->Pixel.PCMCTbias, 0.0, 0.0, 0.0, 0.0);
+   ctx->Pixel.ColorTableEnabled = GL_FALSE;
+   ctx->Pixel.PostConvolutionColorTableEnabled = GL_FALSE;
+   ctx->Pixel.PostColorMatrixColorTableEnabled = GL_FALSE;
+   ctx->Pixel.Convolution1DEnabled = GL_FALSE;
+   ctx->Pixel.Convolution2DEnabled = GL_FALSE;
+   ctx->Pixel.Separable2DEnabled = GL_FALSE;
+   for (i = 0; i < 3; i++) {
+      ASSIGN_4V(ctx->Pixel.ConvolutionBorderColor[i], 0.0, 0.0, 0.0, 0.0);
+      ctx->Pixel.ConvolutionBorderMode[i] = GL_REDUCE;
+      ASSIGN_4V(ctx->Pixel.ConvolutionFilterScale[i], 1.0, 1.0, 1.0, 1.0);
+      ASSIGN_4V(ctx->Pixel.ConvolutionFilterBias[i], 0.0, 0.0, 0.0, 0.0);
+   }
+   for (i = 0; i < MAX_CONVOLUTION_WIDTH * MAX_CONVOLUTION_WIDTH * 4; i++) {
+      ctx->Convolution1D.Filter[i] = 0.0;
+      ctx->Convolution2D.Filter[i] = 0.0;
+      ctx->Separable2D.Filter[i] = 0.0;
+   }
+   ASSIGN_4V(ctx->Pixel.PostConvolutionScale, 1.0, 1.0, 1.0, 1.0);
+   ASSIGN_4V(ctx->Pixel.PostConvolutionBias, 0.0, 0.0, 0.0, 0.0);
+
+   /* Pixel transfer */
+   ctx->Pack.Alignment = 4;
+   ctx->Pack.RowLength = 0;
+   ctx->Pack.ImageHeight = 0;
+   ctx->Pack.SkipPixels = 0;
+   ctx->Pack.SkipRows = 0;
+   ctx->Pack.SkipImages = 0;
+   ctx->Pack.SwapBytes = GL_FALSE;
+   ctx->Pack.LsbFirst = GL_FALSE;
+   ctx->Unpack.Alignment = 4;
+   ctx->Unpack.RowLength = 0;
+   ctx->Unpack.ImageHeight = 0;
+   ctx->Unpack.SkipPixels = 0;
+   ctx->Unpack.SkipRows = 0;
+   ctx->Unpack.SkipImages = 0;
+   ctx->Unpack.SwapBytes = GL_FALSE;
+   ctx->Unpack.LsbFirst = GL_FALSE;
+
+   if (ctx->Visual.doubleBufferMode) {
+      ctx->Pixel.ReadBuffer = GL_BACK;
+      ctx->Pixel._ReadSrcMask = BACK_LEFT_BIT;
+   }
+   else {
+      ctx->Pixel.ReadBuffer = GL_FRONT;
+      ctx->Pixel._ReadSrcMask = FRONT_LEFT_BIT;
+   }
+
+   /* Miscellaneous */
+   ctx->_ImageTransferState = 0;
+}
diff --git a/src/mesa/main/pixel.h b/src/mesa/main/pixel.h
index 48138e0838..e559453769 100644
--- a/src/mesa/main/pixel.h
+++ b/src/mesa/main/pixel.h
@@ -1,3 +1,7 @@
+/**
+ * \file pixel.h
+ * Pixel operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -31,10 +35,8 @@
 #include "mtypes.h"
 
 
-/*
- * API functions
- */
-
+/** \name API functions */
+/*@*/
 
 extern void
 _mesa_GetPixelMapfv( GLenum map, GLfloat *values );
@@ -69,11 +71,11 @@ _mesa_PixelTransferi( GLenum pname, GLint param );
 extern void
 _mesa_PixelZoom( GLfloat xfactor, GLfloat yfactor );
 
+/*@}*/
 
 
-/*
- * Pixel processing functions
- */
+/** \name Pixel processing functions */
+/*@{*/
 
 extern void
 _mesa_scale_and_bias_rgba(const GLcontext *ctx, GLuint n, GLfloat rgba[][4],
@@ -135,4 +137,12 @@ _mesa_chan_to_float_span(const GLcontext *ctx, GLuint n,
                          CONST GLchan rgba[][4], GLfloat rgbaf[][4]);
 
 
+extern void 
+_mesa_update_pixel( GLcontext *ctx, GLuint newstate );
+
+extern void 
+_mesa_init_pixel( GLcontext * ctx );
+
+/*@}*/
+
 #endif
diff --git a/src/mesa/main/points.c b/src/mesa/main/points.c
index 272a47de1b..5d332a8e19 100644
--- a/src/mesa/main/points.c
+++ b/src/mesa/main/points.c
@@ -1,3 +1,7 @@
+/**
+ * \file points.c
+ * Point operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -32,7 +36,19 @@
 #include "mtypes.h"
 
 
-
+/**
+ * Set the point size.
+ *
+ * \param size pointer diameter.
+ *
+ * \sa glPointSize().
+ *
+ * Verifies the parameter and updates gl_point_attrib::Size. On a change,
+ * flushes the vertices, updates the clamped point size and marks the
+ * DD_POINT_SIZE flag in __GLcontextRec::_TriangleCaps for the drivers if the
+ * size is different from one. Notifies the driver via
+ * the dd_function_table::PointSize callback.
+ */
 void
 _mesa_PointSize( GLfloat size )
 {
@@ -63,6 +79,7 @@ _mesa_PointSize( GLfloat size )
 }
 
 
+#if _HAVE_FULL_GL
 
 /*
  * Added by GL_NV_point_sprite
@@ -127,7 +144,6 @@ _mesa_PointParameterfvEXT( GLenum pname, const GLfloat *params)
 
             if (tmp != ctx->Point._Attenuated) {
                ctx->_TriangleCaps ^= DD_POINT_ATTEN;
-	       ctx->_NeedEyeCoords ^= NEED_EYE_POINT_ATTEN;
             }
          }
          else {
@@ -218,3 +234,35 @@ _mesa_PointParameterfvEXT( GLenum pname, const GLfloat *params)
    if (ctx->Driver.PointParameterfv)
       (*ctx->Driver.PointParameterfv)(ctx, pname, params);
 }
+#endif
+
+
+/**
+ * Initialize the context point state.
+ *
+ * \param ctx GL context.
+ *
+ * Initializes __GLcontextRec::Point and point related constants in
+ * __GLcontextRec::Const.
+ */
+void _mesa_init_point( GLcontext * ctx )
+{
+   int i;
+   
+   /* Point group */
+   ctx->Point.SmoothFlag = GL_FALSE;
+   ctx->Point.Size = 1.0;
+   ctx->Point._Size = 1.0;
+   ctx->Point.Params[0] = 1.0;
+   ctx->Point.Params[1] = 0.0;
+   ctx->Point.Params[2] = 0.0;
+   ctx->Point._Attenuated = GL_FALSE;
+   ctx->Point.MinSize = 0.0;
+   ctx->Point.MaxSize = ctx->Const.MaxPointSize;
+   ctx->Point.Threshold = 1.0;
+   ctx->Point.PointSprite = GL_FALSE; /* GL_NV_point_sprite */
+   ctx->Point.SpriteRMode = GL_ZERO; /* GL_NV_point_sprite */
+   for (i = 0; i < MAX_TEXTURE_UNITS; i++) {
+      ctx->Point.CoordReplace[i] = GL_FALSE; /* GL_NV_point_sprite */
+   }
+}
diff --git a/src/mesa/main/points.h b/src/mesa/main/points.h
index da57fba7a7..7a4a77caa9 100644
--- a/src/mesa/main/points.h
+++ b/src/mesa/main/points.h
@@ -1,3 +1,7 @@
+/**
+ * \file points.h
+ * Point operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -46,5 +50,8 @@ _mesa_PointParameterfEXT( GLenum pname, GLfloat param );
 extern void
 _mesa_PointParameterfvEXT( GLenum pname, const GLfloat *params );
 
+extern void 
+_mesa_init_point( GLcontext * ctx );
+
 
 #endif
diff --git a/src/mesa/main/polygon.c b/src/mesa/main/polygon.c
index dd4f44ec36..1051c8ce17 100644
--- a/src/mesa/main/polygon.c
+++ b/src/mesa/main/polygon.c
@@ -1,3 +1,7 @@
+/**
+ * \file polygon.c
+ * Polygon operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -34,6 +38,17 @@
 #include "mtypes.h"
 
 
+/**
+ * Specify whether to cull front- or back-facing facets.
+ *
+ * \param mode culling mode.
+ *
+ * \sa glCullFace().
+ *
+ * Verifies the parameter and updates gl_polygon_attrib::CullFaceMode. On
+ * change, flushes the vertices and notifies the driver via
+ * the dd_function_table::CullFace callback.
+ */
 void
 _mesa_CullFace( GLenum mode )
 {
@@ -59,7 +74,17 @@ _mesa_CullFace( GLenum mode )
 }
 
 
-
+/**
+ * Define front- and back-facing 
+ *
+ * \param mode orientation of front-facing polygons.
+ *
+ * \sa glFrontFace().
+ *
+ * Verifies the parameter and updates gl_polygon_attrib::FrontFace. On change
+ * flushes the vertices and notifies the driver via
+ * the dd_function_table::FrontFace callback.
+ */
 void
 _mesa_FrontFace( GLenum mode )
 {
@@ -87,7 +112,18 @@ _mesa_FrontFace( GLenum mode )
 }
 
 
-
+/**
+ * Set the polygon rasterization mode.
+ *
+ * \param face the polygons which \p mode applies to.
+ * \param mode how polygons should be rasterized.
+ *
+ * \sa glPolygonMode(). 
+ * 
+ * Verifies the parameters and updates gl_polygon_attrib::FrontMode and
+ * gl_polygon_attrib::BackMode. On change flushes the vertices and notifies the
+ * driver via the dd_function_table::PolygonMode callback.
+ */
 void
 _mesa_PolygonMode( GLenum face, GLenum mode )
 {
@@ -139,7 +175,7 @@ _mesa_PolygonMode( GLenum face, GLenum mode )
    }
 }
 
-
+#if _HAVE_FULL_GL
 
 void
 _mesa_PolygonStipple( const GLubyte *pattern )
@@ -172,7 +208,6 @@ _mesa_GetPolygonStipple( GLubyte *dest )
 }
 
 
-
 void
 _mesa_PolygonOffset( GLfloat factor, GLfloat units )
 {
@@ -202,3 +237,68 @@ _mesa_PolygonOffsetEXT( GLfloat factor, GLfloat bias )
    GET_CURRENT_CONTEXT(ctx);
    _mesa_PolygonOffset(factor, bias * ctx->DepthMaxF );
 }
+
+#endif
+
+
+/**********************************************************************/
+/** \name State Management */
+/*@{*/
+
+/*
+ * Check polygon state and set DD_TRI_CULL_FRONT_BACK and/or DD_TRI_OFFSET
+ * in ctx->_TriangleCaps if needed.
+ */
+void _mesa_update_polygon( GLcontext *ctx )
+{
+   ctx->_TriangleCaps &= ~(DD_TRI_CULL_FRONT_BACK | DD_TRI_OFFSET);
+
+   if (ctx->Polygon.CullFlag && ctx->Polygon.CullFaceMode == GL_FRONT_AND_BACK)
+      ctx->_TriangleCaps |= DD_TRI_CULL_FRONT_BACK;
+
+   /* Any Polygon offsets enabled? */
+   if (ctx->Polygon.OffsetPoint ||
+       ctx->Polygon.OffsetLine ||
+       ctx->Polygon.OffsetFill) {
+      ctx->_TriangleCaps |= DD_TRI_OFFSET;
+   }
+}
+
+/*@}*/
+
+
+/**********************************************************************/
+/** \name Initialization */
+/*@{*/
+
+/**
+ * Initialize the context polygon state.
+ *
+ * \param ctx GL context.
+ *
+ * Initializes __GLcontextRec::Polygon and __GLcontextRec::PolygonStipple
+ * attribute groups.
+ */
+void _mesa_init_polygon( GLcontext * ctx )
+{
+   /* Polygon group */
+   ctx->Polygon.CullFlag = GL_FALSE;
+   ctx->Polygon.CullFaceMode = GL_BACK;
+   ctx->Polygon.FrontFace = GL_CCW;
+   ctx->Polygon._FrontBit = 0;
+   ctx->Polygon.FrontMode = GL_FILL;
+   ctx->Polygon.BackMode = GL_FILL;
+   ctx->Polygon.SmoothFlag = GL_FALSE;
+   ctx->Polygon.StippleFlag = GL_FALSE;
+   ctx->Polygon.OffsetFactor = 0.0F;
+   ctx->Polygon.OffsetUnits = 0.0F;
+   ctx->Polygon.OffsetPoint = GL_FALSE;
+   ctx->Polygon.OffsetLine = GL_FALSE;
+   ctx->Polygon.OffsetFill = GL_FALSE;
+
+
+   /* Polygon Stipple group */
+   MEMSET( ctx->PolygonStipple, 0xff, 32*sizeof(GLuint) );
+}
+
+/*@}*/
diff --git a/src/mesa/main/polygon.h b/src/mesa/main/polygon.h
index 81b67ff546..ec0735b108 100644
--- a/src/mesa/main/polygon.h
+++ b/src/mesa/main/polygon.h
@@ -1,3 +1,7 @@
+/**
+ * \file polygon.h
+ * Polygon operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -52,5 +56,10 @@ _mesa_PolygonStipple( const GLubyte *mask );
 extern void
 _mesa_GetPolygonStipple( GLubyte *mask );
 
+extern void 
+_mesa_update_polygon( GLcontext *ctx );
+
+extern void 
+_mesa_init_polygon( GLcontext * ctx );
 
 #endif
diff --git a/src/mesa/main/rastpos.c b/src/mesa/main/rastpos.c
index 3c48a3afec..77d84a50b6 100644
--- a/src/mesa/main/rastpos.c
+++ b/src/mesa/main/rastpos.c
@@ -1,3 +1,8 @@
+/**
+ * \file rastpos.c
+ * Raster position operations.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -24,7 +29,7 @@
 
 
 #include "glheader.h"
-#include "clip.h"
+/*#include "clip.h"*/
 #include "colormac.h"
 #include "context.h"
 #include "feedback.h"
@@ -36,13 +41,14 @@
 #include "mtypes.h"
 
 #include "math/m_matrix.h"
-#include "math/m_xform.h"
 
 
 /**
  * Clip a point against the view volume.
- * \param v  vertex-vector describing the point to clip
- * \return  0 = outside view volume, 1 = inside view volume
+ *
+ * \param v vertex vector describing the point to clip.
+ * 
+ * \return zero if outside view volume, or one if inside.
  */
 static GLuint
 viewclip_point( const GLfloat v[] )
@@ -58,7 +64,13 @@ viewclip_point( const GLfloat v[] )
 }
 
 
-/* As above, but only clip test against far/near Z planes */
+/**
+ * Clip a point against the far/near Z clipping planes.
+ *
+ * \param v vertex vector describing the point to clip.
+ * 
+ * \return zero if outside view volume, or one if inside.
+ */
 static GLuint
 viewclip_point_z( const GLfloat v[] )
 {
@@ -71,11 +83,13 @@ viewclip_point_z( const GLfloat v[] )
 }
 
 
-
 /**
  * Clip a point against the user clipping planes.
- * \param v  vertex-vector describing the point to clip.
- * \return  0 = point was clipped, 1 = point not clipped
+ * 
+ * \param ctx GL context.
+ * \param v vertex vector describing the point to clip.
+ * 
+ * \return zero if the point was clipped, or one otherwise.
  */
 static GLuint
 userclip_point( GLcontext *ctx, const GLfloat v[] )
@@ -102,12 +116,12 @@ userclip_point( GLcontext *ctx, const GLfloat v[] )
  * This has been split off to allow the normal shade routines to
  * get a little closer to the vertex buffer, and to use the
  * GLvector objects directly.
- * Input: ctx - the context
- *        vertex - vertex location
- *        normal - normal vector
- * Output: Rcolor - returned color
- *         Rspec  - returned specular color (if separate specular enabled)
- *         Rindex - returned color index
+ * \param ctx the context
+ * \param vertex vertex location
+ * \param normal normal vector
+ * \param Rcolor returned color
+ * \param Rspec returned specular color (if separate specular enabled)
+ * \param Rindex returned color index
  */
 static void
 shade_rastpos(GLcontext *ctx,
@@ -265,8 +279,23 @@ shade_rastpos(GLcontext *ctx,
 
 
 /**
+ * Set the raster position for pixel operations.
+ *
  * All glRasterPos command call this function to update the current
  * raster position.
+ * 
+ * \param ctx GL context.
+ * \param x x coordinate for the raster position.
+ * \param y y coordinate for the raster position.
+ * \param z z coordinate for the raster position.
+ * \param w w coordinate for the raster position.
+ * 
+ * \sa Called by _mesa_RasterPos4f().
+ *
+ * Flushes the vertices, transforms and clips the vertex coordinates, and
+ * finally sets the current raster position and associated data in
+ * __GLcontextRec::Current.  When in selection mode calls
+ * _mesa_update_hitflag() with the current raster position.
  */
 static void
 raster_pos4f(GLcontext *ctx, GLfloat x, GLfloat y, GLfloat z, GLfloat w)
@@ -305,7 +334,6 @@ raster_pos4f(GLcontext *ctx, GLfloat x, GLfloat y, GLfloat z, GLfloat w)
                         ctx->Current.RasterColor,
                         ctx->Current.RasterSecondaryColor,
                         &ctx->Current.RasterIndex );
-
       }
       else {
          /* use current color or index */
@@ -382,60 +410,70 @@ raster_pos4f(GLcontext *ctx, GLfloat x, GLfloat y, GLfloat z, GLfloat w)
 }
 
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos2d(GLdouble x, GLdouble y)
 {
    _mesa_RasterPos4f((GLfloat) x, (GLfloat) y, 0.0F, 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos2f(GLfloat x, GLfloat y)
 {
    _mesa_RasterPos4f(x, y, 0.0F, 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos2i(GLint x, GLint y)
 {
    _mesa_RasterPos4f((GLfloat) x, (GLfloat) y, 0.0F, 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos2s(GLshort x, GLshort y)
 {
    _mesa_RasterPos4f(x, y, 0.0F, 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos3d(GLdouble x, GLdouble y, GLdouble z)
 {
    _mesa_RasterPos4f((GLfloat) x, (GLfloat) y, (GLfloat) z, 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos3f(GLfloat x, GLfloat y, GLfloat z)
 {
    _mesa_RasterPos4f(x, y, z, 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos3i(GLint x, GLint y, GLint z)
 {
    _mesa_RasterPos4f((GLfloat) x, (GLfloat) y, (GLfloat) z, 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos3s(GLshort x, GLshort y, GLshort z)
 {
    _mesa_RasterPos4f(x, y, z, 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos4d(GLdouble x, GLdouble y, GLdouble z, GLdouble w)
 {
    _mesa_RasterPos4f((GLfloat) x, (GLfloat) y, (GLfloat) z, (GLfloat) w);
 }
 
+/** Calls raster_pos4f() */
 void
 _mesa_RasterPos4f(GLfloat x, GLfloat y, GLfloat z, GLfloat w)
 {
@@ -443,66 +481,77 @@ _mesa_RasterPos4f(GLfloat x, GLfloat y, GLfloat z, GLfloat w)
    raster_pos4f(ctx, x, y, z, w);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos4i(GLint x, GLint y, GLint z, GLint w)
 {
    _mesa_RasterPos4f((GLfloat) x, (GLfloat) y, (GLfloat) z, (GLfloat) w);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos4s(GLshort x, GLshort y, GLshort z, GLshort w)
 {
    _mesa_RasterPos4f(x, y, z, w);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos2dv(const GLdouble *v)
 {
    _mesa_RasterPos4f((GLfloat) v[0], (GLfloat) v[1], 0.0F, 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos2fv(const GLfloat *v)
 {
    _mesa_RasterPos4f(v[0], v[1], 0.0F, 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos2iv(const GLint *v)
 {
    _mesa_RasterPos4f((GLfloat) v[0], (GLfloat) v[1], 0.0F, 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos2sv(const GLshort *v)
 {
    _mesa_RasterPos4f(v[0], v[1], 0.0F, 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos3dv(const GLdouble *v)
 {
    _mesa_RasterPos4f((GLfloat) v[0], (GLfloat) v[1], (GLfloat) v[2], 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos3fv(const GLfloat *v)
 {
    _mesa_RasterPos4f(v[0], v[1], v[2], 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos3iv(const GLint *v)
 {
    _mesa_RasterPos4f((GLfloat) v[0], (GLfloat) v[1], (GLfloat) v[2], 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos3sv(const GLshort *v)
 {
    _mesa_RasterPos4f(v[0], v[1], v[2], 1.0F);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos4dv(const GLdouble *v)
 {
@@ -510,12 +559,14 @@ _mesa_RasterPos4dv(const GLdouble *v)
 		     (GLfloat) v[2], (GLfloat) v[3]);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos4fv(const GLfloat *v)
 {
    _mesa_RasterPos4f(v[0], v[1], v[2], v[3]);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos4iv(const GLint *v)
 {
@@ -523,6 +574,7 @@ _mesa_RasterPos4iv(const GLint *v)
 		     (GLfloat) v[2], (GLfloat) v[3]);
 }
 
+/** Calls _mesa_RasterPos4f() */
 void
 _mesa_RasterPos4sv(const GLshort *v)
 {
@@ -534,7 +586,7 @@ _mesa_RasterPos4sv(const GLshort *v)
 /***           GL_ARB_window_pos / GL_MESA_window_pos               ***/
 /**********************************************************************/
 
-
+#if FEATURE_windowpos
 /**
  * All glWindowPosMESA and glWindowPosARB commands call this function to
  * update the current raster position.
@@ -758,7 +810,7 @@ _mesa_WindowPos4svMESA(const GLshort *v)
    window_pos4f(v[0], v[1], v[2], v[3]);
 }
 
-
+#endif
 
 #if 0
 
@@ -797,3 +849,57 @@ void glWindowPos4fMESA( GLfloat x, GLfloat y, GLfloat z, GLfloat w )
 }
 
 #endif
+
+
+/**********************************************************************/
+/** \name Initialization                                              */
+/**********************************************************************/
+/*@{*/
+
+/**
+ * Initialize the context current raster position information.
+ *
+ * \param ctx GL context.
+ *
+ * Initialize the current raster position information in
+ * __GLcontextRec::Current, and adds the extension entry points to the
+ * dispatcher.
+ */
+void _mesa_init_rastpos( GLcontext * ctx )
+{
+   int i;
+
+   ASSIGN_4V( ctx->Current.RasterPos, 0.0, 0.0, 0.0, 1.0 );
+   ctx->Current.RasterDistance = 0.0;
+   ASSIGN_4V( ctx->Current.RasterColor, 1.0, 1.0, 1.0, 1.0 );
+   ctx->Current.RasterIndex = 1;
+   for (i=0; i<MAX_TEXTURE_UNITS; i++)
+      ASSIGN_4V( ctx->Current.RasterTexCoords[i], 0.0, 0.0, 0.0, 1.0 );
+   ctx->Current.RasterPosValid = GL_TRUE;
+
+  /*
+    * For XFree86/DRI: tell libGL to add these functions to the dispatcher.
+    * Basically, we should add all extension functions above offset 577.
+    * This enables older libGL libraries to work with newer drivers that
+    * have newer extensions.
+    */
+   /* GL_ARB_window_pos aliases with GL_MESA_window_pos */
+   _glapi_add_entrypoint("glWindowPos2dARB", 513);
+   _glapi_add_entrypoint("glWindowPos2dvARB", 514);
+   _glapi_add_entrypoint("glWindowPos2fARB", 515);
+   _glapi_add_entrypoint("glWindowPos2fvARB", 516);
+   _glapi_add_entrypoint("glWindowPos2iARB", 517);
+   _glapi_add_entrypoint("glWindowPos2ivARB", 518);
+   _glapi_add_entrypoint("glWindowPos2sARB", 519);
+   _glapi_add_entrypoint("glWindowPos2svARB", 520);
+   _glapi_add_entrypoint("glWindowPos3dARB", 521);
+   _glapi_add_entrypoint("glWindowPos3dvARB", 522);
+   _glapi_add_entrypoint("glWindowPos3fARB", 523);
+   _glapi_add_entrypoint("glWindowPos3fvARB", 524);
+   _glapi_add_entrypoint("glWindowPos3iARB", 525);
+   _glapi_add_entrypoint("glWindowPos3ivARB", 526);
+   _glapi_add_entrypoint("glWindowPos3sARB", 527);
+   _glapi_add_entrypoint("glWindowPos3svARB", 528);
+}
+
+/*@}*/
diff --git a/src/mesa/main/rastpos.h b/src/mesa/main/rastpos.h
index 3d18cb91c5..ae7278c470 100644
--- a/src/mesa/main/rastpos.h
+++ b/src/mesa/main/rastpos.h
@@ -1,3 +1,7 @@
+/**
+ * \file rastpos.h
+ * Raster position operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -105,8 +109,9 @@ _mesa_RasterPos4sv(const GLshort *v);
 
 
 /**********************************************************************/
-/***                     GL_MESA_window_pos                         ***/
+/** \name GL_MESA_window_pos                                          */
 /**********************************************************************/
+/*@{*/
 
 extern void
 _mesa_WindowPos2dMESA(GLdouble x, GLdouble y);
@@ -180,5 +185,9 @@ _mesa_WindowPos4ivMESA(const GLint *v);
 extern void
 _mesa_WindowPos4svMESA(const GLshort *v);
 
+extern void 
+_mesa_init_rastpos( GLcontext * ctx );
+
+/*@}*/
 
 #endif
diff --git a/src/mesa/main/simple_list.h b/src/mesa/main/simple_list.h
index 2d9d4c8453..63475f6f74 100644
--- a/src/mesa/main/simple_list.h
+++ b/src/mesa/main/simple_list.h
@@ -1,3 +1,13 @@
+/**
+ * \file simple_list.h
+ * Simple macros for type-safe, intrusive lists.
+ *
+ *  Intended to work with a list sentinal which is created as an empty
+ *  list.  Insert & delete are O(1).
+ *  
+ * \author
+ *  (C) 1997, Keith Whitwell
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -23,23 +33,27 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/*  Simple macros for typesafe, intrusive lists.
- *  (C) 1997, Keith Whitwell
- *
- *  Intended to work with a list sentinal which is created as an empty
- *  list.  Insert & delete are O(1).
- */
-
 
 #ifndef _SIMPLE_LIST_H
 #define _SIMPLE_LIST_H
 
+/**
+ * Remove an element from list.
+ *
+ * \param elem element to remove.
+ */
 #define remove_from_list(elem)			\
 do {						\
    (elem)->next->prev = (elem)->prev;		\
    (elem)->prev->next = (elem)->next;		\
 } while (0)
 
+/**
+ * Insert an element to the list head.
+ *
+ * \param list list.
+ * \param elem element to insert.
+ */
 #define insert_at_head(list, elem)		\
 do {						\
    (elem)->prev = list;				\
@@ -48,6 +62,12 @@ do {						\
    (list)->next = elem;				\
 } while(0)
 
+/**
+ * Insert an element to the list tail.
+ *
+ * \param list list.
+ * \param elem element to insert.
+ */
 #define insert_at_tail(list, elem)		\
 do {						\
    (elem)->next = list;				\
@@ -56,42 +76,122 @@ do {						\
    (list)->prev = elem;				\
 } while(0)
 
+/**
+ * Move an element to the list head.
+ *
+ * \param list list.
+ * \param elem element to move.
+ */
 #define move_to_head(list, elem)		\
 do {						\
    remove_from_list(elem);			\
    insert_at_head(list, elem);			\
 } while (0)
 
+/**
+ * Move an element to the list tail.
+ *
+ * \param list list.
+ * \param elem element to move.
+ */
 #define move_to_tail(list, elem)		\
 do {						\
    remove_from_list(elem);			\
    insert_at_tail(list, elem);			\
 } while (0)
 
-
+/**
+ * Make a empty list empty.
+ *
+ * \param sentinal list (sentinal element).
+ */
 #define make_empty_list(sentinal)		\
 do {						\
    (sentinal)->next = sentinal;			\
    (sentinal)->prev = sentinal;			\
 } while (0)
 
-
+/**
+ * Get list first element.
+ *
+ * \param list list.
+ *
+ * \return pointer to first element.
+ */
 #define first_elem(list)       ((list)->next)
+
+/**
+ * Get list last element.
+ *
+ * \param list list.
+ *
+ * \return pointer to last element.
+ */
 #define last_elem(list)        ((list)->prev)
+
+/**
+ * Get next element.
+ *
+ * \param elem element.
+ *
+ * \return pointer to next element.
+ */
 #define next_elem(elem)        ((elem)->next)
+
+/**
+ * Get previous element.
+ *
+ * \param elem element.
+ *
+ * \return pointer to previous element.
+ */
 #define prev_elem(elem)        ((elem)->prev)
+
+/**
+ * Test whether element is at end of the list.
+ * 
+ * \param list list.
+ * \param elem element.
+ * 
+ * \return non-zero if element is at end of list, or zero otherwise.
+ */
 #define at_end(list, elem)     ((elem) == (list))
+
+/**
+ * Test if a list is empty.
+ * 
+ * \param list list.
+ * 
+ * \return non-zero if list empty, or zero otherwise.
+ */
 #define is_empty_list(list)    ((list)->next == (list))
 
+/**
+ * Walk through the elements of a list.
+ *
+ * \param ptr pointer to the current element.
+ * \param list list.
+ *
+ * \note It should be followed by a { } block or a single statement, as in a \c
+ * for loop.
+ */
 #define foreach(ptr, list)     \
         for( ptr=(list)->next ;  ptr!=list ;  ptr=(ptr)->next )
 
-/* Kludgey - Lets you unlink the current value during a list
- *           traversal.  Useful for free()-ing a list, element
- *           by element.
+/**
+ * Walk through the elements of a list.
+ *
+ * Same as #foreach but lets you unlink the current value during a list
+ * traversal.  Useful for freeing a list, element by element.
+ * 
+ * \param ptr pointer to the current element.
+ * \param t temporary pointer.
+ * \param list list.
+ *
+ * \note It should be followed by a { } block or a single statement, as in a \c
+ * for loop.
  */
 #define foreach_s(ptr, t, list)   \
         for(ptr=(list)->next,t=(ptr)->next; list != ptr; ptr=t, t=(t)->next)
 
-
 #endif
diff --git a/src/mesa/main/state.c b/src/mesa/main/state.c
index 2851b8e083..2683556f02 100644
--- a/src/mesa/main/state.c
+++ b/src/mesa/main/state.c
@@ -1,3 +1,11 @@
+/**
+ * \file state.c
+ * State management.
+ * 
+ * This file manages recalculation of derived values in the __GLcontextRec.
+ * Also, this is where we initialize the API dispatch table.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -23,12 +31,6 @@
  */
 
 
-/*
- * /brief This file manages recalculation of derived values in the
- * __GLcontext.  Also, this is where we initialize the API dispatch table.
- */
-
-
 #include "glheader.h"
 #include "accum.h"
 #include "api_loopback.h"
@@ -79,24 +81,37 @@
 #if FEATURE_NV_fragment_program
 #include "nvfragprog.h"
 #endif
+#include "debug.h"
+
+/* #include "math/m_matrix.h" */
+/* #include "math/m_xform.h" */
 
-#include "math/m_matrix.h"
-#include "math/m_xform.h"
 
+/**********************************************************************/
+/** \name Dispatch table setup */
+/*@{*/
 
+/**
+ * Generic no-op dispatch function.
+ *
+ * Used in replacement of the functions which are not part of Mesa subset.
+ *
+ * Displays a message.
+ */
 static int
 generic_noop(void)
 {
-#ifdef DEBUG
-   _mesa_problem(NULL, "User called no-op dispatch function");
-#endif
+   _mesa_problem(NULL, "User called no-op dispatch function (not part of Mesa subset?)");
    return 0;
 }
 
 
-/*
+/**
  * Set all pointers in the given dispatch table to point to a
- * generic no-op function.
+ * generic no-op function - generic_noop().
+ *
+ * \param table dispatch table.
+ * \param tableSize dispatch table size.
  */
 void
 _mesa_init_no_op_table(struct _glapi_table *table, GLuint tableSize)
@@ -109,13 +124,15 @@ _mesa_init_no_op_table(struct _glapi_table *table, GLuint tableSize)
 }
 
 
-
-/*
- * Initialize the given dispatch table with pointers to Mesa's
- * immediate-mode commands.
+/**
+ * Initialize a dispatch table with pointers to Mesa's immediate-mode
+ * commands.
+ *
+ * Pointers to glBegin()/glEnd() object commands and a few others
+ * are provided via the GLvertexformat interface.
  *
- * Pointers to begin/end object commands and a few others
- * are provided via the vtxfmt interface elsewhere.
+ * \param exec dispatch table.
+ * \param tableSize dispatch table size.
  */
 void
 _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
@@ -123,51 +140,90 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
    /* first initialize all dispatch slots to no-op */
    _mesa_init_no_op_table(exec, tableSize);
 
+#if _HAVE_FULL_GL
    _mesa_loopback_init_api_table( exec, GL_TRUE );
+#endif
 
    /* load the dispatch slots we understand */
-   exec->Accum = _mesa_Accum;
    exec->AlphaFunc = _mesa_AlphaFunc;
-   exec->Bitmap = _mesa_Bitmap;
    exec->BlendFunc = _mesa_BlendFunc;
+   exec->Clear = _mesa_Clear;
+   exec->ClearColor = _mesa_ClearColor;
+   exec->ClearStencil = _mesa_ClearStencil;
+   exec->ColorMask = _mesa_ColorMask;
+   exec->CullFace = _mesa_CullFace;
+   exec->Disable = _mesa_Disable;
+   exec->DrawBuffer = _mesa_DrawBuffer;
+   exec->Enable = _mesa_Enable;
+   exec->Finish = _mesa_Finish;
+   exec->Flush = _mesa_Flush;
+   exec->FrontFace = _mesa_FrontFace;
+   exec->Frustum = _mesa_Frustum;
+   exec->GetError = _mesa_GetError;
+   exec->GetFloatv = _mesa_GetFloatv;
+   exec->GetString = _mesa_GetString;
+   exec->InitNames = _mesa_InitNames;
+   exec->LineStipple = _mesa_LineStipple;
+   exec->LineWidth = _mesa_LineWidth;
+   exec->LoadIdentity = _mesa_LoadIdentity;
+   exec->LoadMatrixf = _mesa_LoadMatrixf;
+   exec->LoadName = _mesa_LoadName;
+   exec->LogicOp = _mesa_LogicOp;
+   exec->MatrixMode = _mesa_MatrixMode;
+   exec->MultMatrixf = _mesa_MultMatrixf;
+   exec->Ortho = _mesa_Ortho;
+   exec->PixelStorei = _mesa_PixelStorei;
+   exec->PopMatrix = _mesa_PopMatrix;
+   exec->PopName = _mesa_PopName;
+   exec->PushMatrix = _mesa_PushMatrix;
+   exec->PushName = _mesa_PushName;
+   exec->RasterPos2f = _mesa_RasterPos2f;
+   exec->RasterPos2fv = _mesa_RasterPos2fv;
+   exec->RasterPos2i = _mesa_RasterPos2i;
+   exec->RasterPos2iv = _mesa_RasterPos2iv;
+   exec->ReadBuffer = _mesa_ReadBuffer;
+   exec->RenderMode = _mesa_RenderMode;
+   exec->Rotatef = _mesa_Rotatef;
+   exec->Scalef = _mesa_Scalef;
+   exec->Scissor = _mesa_Scissor;
+   exec->SelectBuffer = _mesa_SelectBuffer;
+   exec->ShadeModel = _mesa_ShadeModel;
+   exec->StencilFunc = _mesa_StencilFunc;
+   exec->StencilMask = _mesa_StencilMask;
+   exec->StencilOp = _mesa_StencilOp;
+   exec->TexEnvfv = _mesa_TexEnvfv;
+   exec->TexEnvi = _mesa_TexEnvi;
+   exec->TexImage2D = _mesa_TexImage2D;
+   exec->TexParameteri = _mesa_TexParameteri; 
+   exec->Translatef = _mesa_Translatef;
+   exec->Viewport = _mesa_Viewport;
+#if _HAVE_FULL_GL
+   exec->Accum = _mesa_Accum;
+   exec->Bitmap = _mesa_Bitmap;
    exec->CallList = _mesa_CallList;
    exec->CallLists = _mesa_CallLists;
-   exec->Clear = _mesa_Clear;
    exec->ClearAccum = _mesa_ClearAccum;
-   exec->ClearColor = _mesa_ClearColor;
    exec->ClearDepth = _mesa_ClearDepth;
    exec->ClearIndex = _mesa_ClearIndex;
-   exec->ClearStencil = _mesa_ClearStencil;
    exec->ClipPlane = _mesa_ClipPlane;
-   exec->ColorMask = _mesa_ColorMask;
    exec->ColorMaterial = _mesa_ColorMaterial;
    exec->CopyPixels = _mesa_CopyPixels;
-   exec->CullFace = _mesa_CullFace;
    exec->DeleteLists = _mesa_DeleteLists;
    exec->DepthFunc = _mesa_DepthFunc;
    exec->DepthMask = _mesa_DepthMask;
    exec->DepthRange = _mesa_DepthRange;
-   exec->Disable = _mesa_Disable;
-   exec->DrawBuffer = _mesa_DrawBuffer;
    exec->DrawPixels = _mesa_DrawPixels;
-   exec->Enable = _mesa_Enable;
    exec->EndList = _mesa_EndList;
    exec->FeedbackBuffer = _mesa_FeedbackBuffer;
-   exec->Finish = _mesa_Finish;
-   exec->Flush = _mesa_Flush;
    exec->FogCoordPointerEXT = _mesa_FogCoordPointerEXT;
    exec->Fogf = _mesa_Fogf;
    exec->Fogfv = _mesa_Fogfv;
    exec->Fogi = _mesa_Fogi;
    exec->Fogiv = _mesa_Fogiv;
-   exec->FrontFace = _mesa_FrontFace;
-   exec->Frustum = _mesa_Frustum;
    exec->GenLists = _mesa_GenLists;
-   exec->GetBooleanv = _mesa_GetBooleanv;
    exec->GetClipPlane = _mesa_GetClipPlane;
+   exec->GetBooleanv = _mesa_GetBooleanv;
    exec->GetDoublev = _mesa_GetDoublev;
-   exec->GetError = _mesa_GetError;
-   exec->GetFloatv = _mesa_GetFloatv;
    exec->GetIntegerv = _mesa_GetIntegerv;
    exec->GetLightfv = _mesa_GetLightfv;
    exec->GetLightiv = _mesa_GetLightiv;
@@ -180,20 +236,18 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
    exec->GetPixelMapuiv = _mesa_GetPixelMapuiv;
    exec->GetPixelMapusv = _mesa_GetPixelMapusv;
    exec->GetPolygonStipple = _mesa_GetPolygonStipple;
-   exec->GetString = _mesa_GetString;
    exec->GetTexEnvfv = _mesa_GetTexEnvfv;
    exec->GetTexEnviv = _mesa_GetTexEnviv;
-   exec->GetTexGendv = _mesa_GetTexGendv;
-   exec->GetTexGenfv = _mesa_GetTexGenfv;
-   exec->GetTexGeniv = _mesa_GetTexGeniv;
-   exec->GetTexImage = _mesa_GetTexImage;
    exec->GetTexLevelParameterfv = _mesa_GetTexLevelParameterfv;
    exec->GetTexLevelParameteriv = _mesa_GetTexLevelParameteriv;
    exec->GetTexParameterfv = _mesa_GetTexParameterfv;
    exec->GetTexParameteriv = _mesa_GetTexParameteriv;
+   exec->GetTexGendv = _mesa_GetTexGendv;
+   exec->GetTexGenfv = _mesa_GetTexGenfv;
+   exec->GetTexGeniv = _mesa_GetTexGeniv;
+   exec->GetTexImage = _mesa_GetTexImage;
    exec->Hint = _mesa_Hint;
    exec->IndexMask = _mesa_IndexMask;
-   exec->InitNames = _mesa_InitNames;
    exec->IsEnabled = _mesa_IsEnabled;
    exec->IsList = _mesa_IsList;
    exec->LightModelf = _mesa_LightModelf;
@@ -204,14 +258,8 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
    exec->Lightfv = _mesa_Lightfv;
    exec->Lighti = _mesa_Lighti;
    exec->Lightiv = _mesa_Lightiv;
-   exec->LineStipple = _mesa_LineStipple;
-   exec->LineWidth = _mesa_LineWidth;
    exec->ListBase = _mesa_ListBase;
-   exec->LoadIdentity = _mesa_LoadIdentity;
    exec->LoadMatrixd = _mesa_LoadMatrixd;
-   exec->LoadMatrixf = _mesa_LoadMatrixf;
-   exec->LoadName = _mesa_LoadName;
-   exec->LogicOp = _mesa_LogicOp;
    exec->Map1d = _mesa_Map1d;
    exec->Map1f = _mesa_Map1f;
    exec->Map2d = _mesa_Map2d;
@@ -220,17 +268,13 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
    exec->MapGrid1f = _mesa_MapGrid1f;
    exec->MapGrid2d = _mesa_MapGrid2d;
    exec->MapGrid2f = _mesa_MapGrid2f;
-   exec->MatrixMode = _mesa_MatrixMode;
    exec->MultMatrixd = _mesa_MultMatrixd;
-   exec->MultMatrixf = _mesa_MultMatrixf;
    exec->NewList = _mesa_NewList;
-   exec->Ortho = _mesa_Ortho;
    exec->PassThrough = _mesa_PassThrough;
    exec->PixelMapfv = _mesa_PixelMapfv;
    exec->PixelMapuiv = _mesa_PixelMapuiv;
    exec->PixelMapusv = _mesa_PixelMapusv;
    exec->PixelStoref = _mesa_PixelStoref;
-   exec->PixelStorei = _mesa_PixelStorei;
    exec->PixelTransferf = _mesa_PixelTransferf;
    exec->PixelTransferi = _mesa_PixelTransferi;
    exec->PixelZoom = _mesa_PixelZoom;
@@ -239,17 +283,9 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
    exec->PolygonOffset = _mesa_PolygonOffset;
    exec->PolygonStipple = _mesa_PolygonStipple;
    exec->PopAttrib = _mesa_PopAttrib;
-   exec->PopMatrix = _mesa_PopMatrix;
-   exec->PopName = _mesa_PopName;
    exec->PushAttrib = _mesa_PushAttrib;
-   exec->PushMatrix = _mesa_PushMatrix;
-   exec->PushName = _mesa_PushName;
    exec->RasterPos2d = _mesa_RasterPos2d;
    exec->RasterPos2dv = _mesa_RasterPos2dv;
-   exec->RasterPos2f = _mesa_RasterPos2f;
-   exec->RasterPos2fv = _mesa_RasterPos2fv;
-   exec->RasterPos2i = _mesa_RasterPos2i;
-   exec->RasterPos2iv = _mesa_RasterPos2iv;
    exec->RasterPos2s = _mesa_RasterPos2s;
    exec->RasterPos2sv = _mesa_RasterPos2sv;
    exec->RasterPos3d = _mesa_RasterPos3d;
@@ -268,23 +304,11 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
    exec->RasterPos4iv = _mesa_RasterPos4iv;
    exec->RasterPos4s = _mesa_RasterPos4s;
    exec->RasterPos4sv = _mesa_RasterPos4sv;
-   exec->ReadBuffer = _mesa_ReadBuffer;
    exec->ReadPixels = _mesa_ReadPixels;
-   exec->RenderMode = _mesa_RenderMode;
    exec->Rotated = _mesa_Rotated;
-   exec->Rotatef = _mesa_Rotatef;
    exec->Scaled = _mesa_Scaled;
-   exec->Scalef = _mesa_Scalef;
-   exec->Scissor = _mesa_Scissor;
    exec->SecondaryColorPointerEXT = _mesa_SecondaryColorPointerEXT;
-   exec->SelectBuffer = _mesa_SelectBuffer;
-   exec->ShadeModel = _mesa_ShadeModel;
-   exec->StencilFunc = _mesa_StencilFunc;
-   exec->StencilMask = _mesa_StencilMask;
-   exec->StencilOp = _mesa_StencilOp;
    exec->TexEnvf = _mesa_TexEnvf;
-   exec->TexEnvfv = _mesa_TexEnvfv;
-   exec->TexEnvi = _mesa_TexEnvi;
    exec->TexEnviv = _mesa_TexEnviv;
    exec->TexGend = _mesa_TexGend;
    exec->TexGendv = _mesa_TexGendv;
@@ -293,29 +317,27 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
    exec->TexGeni = _mesa_TexGeni;
    exec->TexGeniv = _mesa_TexGeniv;
    exec->TexImage1D = _mesa_TexImage1D;
-   exec->TexImage2D = _mesa_TexImage2D;
    exec->TexParameterf = _mesa_TexParameterf;
    exec->TexParameterfv = _mesa_TexParameterfv;
-   exec->TexParameteri = _mesa_TexParameteri;
    exec->TexParameteriv = _mesa_TexParameteriv;
    exec->Translated = _mesa_Translated;
-   exec->Translatef = _mesa_Translatef;
-   exec->Viewport = _mesa_Viewport;
+#endif
 
    /* 1.1 */
+   exec->BindTexture = _mesa_BindTexture;
+   exec->DeleteTextures = _mesa_DeleteTextures;
+   exec->GenTextures = _mesa_GenTextures;
+#if _HAVE_FULL_GL
    exec->AreTexturesResident = _mesa_AreTexturesResident;
    exec->AreTexturesResidentEXT = _mesa_AreTexturesResident;
-   exec->BindTexture = _mesa_BindTexture;
    exec->ColorPointer = _mesa_ColorPointer;
    exec->CopyTexImage1D = _mesa_CopyTexImage1D;
    exec->CopyTexImage2D = _mesa_CopyTexImage2D;
    exec->CopyTexSubImage1D = _mesa_CopyTexSubImage1D;
    exec->CopyTexSubImage2D = _mesa_CopyTexSubImage2D;
-   exec->DeleteTextures = _mesa_DeleteTextures;
    exec->DisableClientState = _mesa_DisableClientState;
    exec->EdgeFlagPointer = _mesa_EdgeFlagPointer;
    exec->EnableClientState = _mesa_EnableClientState;
-   exec->GenTextures = _mesa_GenTextures;
    exec->GenTexturesEXT = _mesa_GenTextures;
    exec->GetPointerv = _mesa_GetPointerv;
    exec->IndexPointer = _mesa_IndexPointer;
@@ -330,13 +352,17 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
    exec->TexSubImage1D = _mesa_TexSubImage1D;
    exec->TexSubImage2D = _mesa_TexSubImage2D;
    exec->VertexPointer = _mesa_VertexPointer;
+#endif
 
    /* 1.2 */
+#if _HAVE_FULL_GL
    exec->CopyTexSubImage3D = _mesa_CopyTexSubImage3D;
    exec->TexImage3D = _mesa_TexImage3D;
    exec->TexSubImage3D = _mesa_TexSubImage3D;
+#endif
 
    /* OpenGL 1.2  GL_ARB_imaging */
+#if _HAVE_FULL_GL
    exec->BlendColor = _mesa_BlendColor;
    exec->BlendEquation = _mesa_BlendEquation;
    exec->ColorSubTable = _mesa_ColorSubTable;
@@ -384,48 +410,59 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
    exec->ResetHistogram = _mesa_ResetHistogram;
    exec->ResetMinmax = _mesa_ResetMinmax;
    exec->SeparableFilter2D = _mesa_SeparableFilter2D;
+#endif
 
    /* 2. GL_EXT_blend_color */
 #if 0
-   exec->BlendColorEXT = _mesa_BlendColorEXT;
+/*    exec->BlendColorEXT = _mesa_BlendColorEXT; */
 #endif
 
    /* 3. GL_EXT_polygon_offset */
+#if _HAVE_FULL_GL
    exec->PolygonOffsetEXT = _mesa_PolygonOffsetEXT;
+#endif
 
    /* 6. GL_EXT_texture3d */
 #if 0
-   exec->CopyTexSubImage3DEXT = _mesa_CopyTexSubImage3D;
-   exec->TexImage3DEXT = _mesa_TexImage3DEXT;
-   exec->TexSubImage3DEXT = _mesa_TexSubImage3D;
+/*    exec->CopyTexSubImage3DEXT = _mesa_CopyTexSubImage3D; */
+/*    exec->TexImage3DEXT = _mesa_TexImage3DEXT; */
+/*    exec->TexSubImage3DEXT = _mesa_TexSubImage3D; */
 #endif
 
    /* 11. GL_EXT_histogram */
+#if _HAVE_FULL_GL
    exec->GetHistogramEXT = _mesa_GetHistogram;
    exec->GetHistogramParameterfvEXT = _mesa_GetHistogramParameterfv;
    exec->GetHistogramParameterivEXT = _mesa_GetHistogramParameteriv;
    exec->GetMinmaxEXT = _mesa_GetMinmax;
    exec->GetMinmaxParameterfvEXT = _mesa_GetMinmaxParameterfv;
    exec->GetMinmaxParameterivEXT = _mesa_GetMinmaxParameteriv;
+#endif
 
    /* ?. GL_SGIX_pixel_texture */
+#if _HAVE_FULL_GL
    exec->PixelTexGenSGIX = _mesa_PixelTexGenSGIX;
+#endif
 
    /* 15. GL_SGIS_pixel_texture */
+#if _HAVE_FULL_GL
    exec->PixelTexGenParameteriSGIS = _mesa_PixelTexGenParameteriSGIS;
    exec->PixelTexGenParameterivSGIS = _mesa_PixelTexGenParameterivSGIS;
    exec->PixelTexGenParameterfSGIS = _mesa_PixelTexGenParameterfSGIS;
    exec->PixelTexGenParameterfvSGIS = _mesa_PixelTexGenParameterfvSGIS;
    exec->GetPixelTexGenParameterivSGIS = _mesa_GetPixelTexGenParameterivSGIS;
    exec->GetPixelTexGenParameterfvSGIS = _mesa_GetPixelTexGenParameterfvSGIS;
+#endif
 
    /* 30. GL_EXT_vertex_array */
+#if _HAVE_FULL_GL
    exec->ColorPointerEXT = _mesa_ColorPointerEXT;
    exec->EdgeFlagPointerEXT = _mesa_EdgeFlagPointerEXT;
    exec->IndexPointerEXT = _mesa_IndexPointerEXT;
    exec->NormalPointerEXT = _mesa_NormalPointerEXT;
    exec->TexCoordPointerEXT = _mesa_TexCoordPointerEXT;
    exec->VertexPointerEXT = _mesa_VertexPointerEXT;
+#endif
 
    /* 37. GL_EXT_blend_minmax */
 #if 0
@@ -433,33 +470,46 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
 #endif
 
    /* 54. GL_EXT_point_parameters */
+#if _HAVE_FULL_GL
    exec->PointParameterfEXT = _mesa_PointParameterfEXT;
    exec->PointParameterfvEXT = _mesa_PointParameterfvEXT;
+#endif
 
    /* 78. GL_EXT_paletted_texture */
 #if 0
    exec->ColorTableEXT = _mesa_ColorTableEXT;
    exec->ColorSubTableEXT = _mesa_ColorSubTableEXT;
 #endif
+#if _HAVE_FULL_GL
    exec->GetColorTableEXT = _mesa_GetColorTable;
    exec->GetColorTableParameterfvEXT = _mesa_GetColorTableParameterfv;
    exec->GetColorTableParameterivEXT = _mesa_GetColorTableParameteriv;
+#endif
 
    /* 97. GL_EXT_compiled_vertex_array */
+#if _HAVE_FULL_GL
    exec->LockArraysEXT = _mesa_LockArraysEXT;
    exec->UnlockArraysEXT = _mesa_UnlockArraysEXT;
+#endif
 
    /* 148. GL_EXT_multi_draw_arrays */
+#if _HAVE_FULL_GL
    exec->MultiDrawArraysEXT = _mesa_MultiDrawArraysEXT;
    exec->MultiDrawElementsEXT = _mesa_MultiDrawElementsEXT;
+#endif
 
    /* 173. GL_INGR_blend_func_separate */
+#if _HAVE_FULL_GL
    exec->BlendFuncSeparateEXT = _mesa_BlendFuncSeparateEXT;
+#endif
 
    /* 196. GL_MESA_resize_buffers */
+#if _HAVE_FULL_GL
    exec->ResizeBuffersMESA = _mesa_ResizeBuffersMESA;
+#endif
 
    /* 197. GL_MESA_window_pos */
+#if _HAVE_FULL_GL
    exec->WindowPos2dMESA = _mesa_WindowPos2dMESA;
    exec->WindowPos2dvMESA = _mesa_WindowPos2dvMESA;
    exec->WindowPos2fMESA = _mesa_WindowPos2fMESA;
@@ -484,6 +534,7 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
    exec->WindowPos4ivMESA = _mesa_WindowPos4ivMESA;
    exec->WindowPos4sMESA = _mesa_WindowPos4sMESA;
    exec->WindowPos4svMESA = _mesa_WindowPos4svMESA;
+#endif
 
    /* 233. GL_NV_vertex_program */
 #if FEATURE_NV_vertex_program
@@ -532,29 +583,40 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
 #endif
 
    /* 262. GL_NV_point_sprite */
+#if _HAVE_FULL_GL
    exec->PointParameteriNV = _mesa_PointParameteriNV;
    exec->PointParameterivNV = _mesa_PointParameterivNV;
+#endif
 
    /* 268. GL_EXT_stencil_two_side */
+#if _HAVE_FULL_GL
    exec->ActiveStencilFaceEXT = _mesa_ActiveStencilFaceEXT;
+#endif
 
    /* ???. GL_EXT_depth_bounds_test */
    exec->DepthBoundsEXT = _mesa_DepthBoundsEXT;
 
    /* ARB 1. GL_ARB_multitexture */
+#if _HAVE_FULL_GL
    exec->ActiveTextureARB = _mesa_ActiveTextureARB;
    exec->ClientActiveTextureARB = _mesa_ClientActiveTextureARB;
+#endif
 
    /* ARB 3. GL_ARB_transpose_matrix */
+#if _HAVE_FULL_GL
    exec->LoadTransposeMatrixdARB = _mesa_LoadTransposeMatrixdARB;
    exec->LoadTransposeMatrixfARB = _mesa_LoadTransposeMatrixfARB;
    exec->MultTransposeMatrixdARB = _mesa_MultTransposeMatrixdARB;
    exec->MultTransposeMatrixfARB = _mesa_MultTransposeMatrixfARB;
+#endif
 
    /* ARB 5. GL_ARB_multisample */
+#if _HAVE_FULL_GL
    exec->SampleCoverageARB = _mesa_SampleCoverageARB;
+#endif
 
    /* ARB 12. GL_ARB_texture_compression */
+#if _HAVE_FULL_GL
    exec->CompressedTexImage3DARB = _mesa_CompressedTexImage3DARB;
    exec->CompressedTexImage2DARB = _mesa_CompressedTexImage2DARB;
    exec->CompressedTexImage1DARB = _mesa_CompressedTexImage1DARB;
@@ -562,6 +624,7 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
    exec->CompressedTexSubImage2DARB = _mesa_CompressedTexSubImage2DARB;
    exec->CompressedTexSubImage1DARB = _mesa_CompressedTexSubImage1DARB;
    exec->GetCompressedTexImageARB = _mesa_GetCompressedTexImageARB;
+#endif
 
    /* ARB 14. GL_ARB_point_parameters */
    /* reuse EXT_point_parameters functions */
@@ -660,392 +723,20 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize)
 #endif
 }
 
+/*@}*/
 
 
 /**********************************************************************/
-/*****                   State update logic                       *****/
-/**********************************************************************/
-
-
-/*
- * Check polygon state and set DD_TRI_CULL_FRONT_BACK and/or DD_TRI_OFFSET
- * in ctx->_TriangleCaps if needed.
- */
-static void
-update_polygon( GLcontext *ctx )
-{
-   ctx->_TriangleCaps &= ~(DD_TRI_CULL_FRONT_BACK | DD_TRI_OFFSET);
-
-   if (ctx->Polygon.CullFlag && ctx->Polygon.CullFaceMode == GL_FRONT_AND_BACK)
-      ctx->_TriangleCaps |= DD_TRI_CULL_FRONT_BACK;
-
-   /* Any Polygon offsets enabled? */
-   if (ctx->Polygon.OffsetPoint ||
-       ctx->Polygon.OffsetLine ||
-       ctx->Polygon.OffsetFill) {
-      ctx->_TriangleCaps |= DD_TRI_OFFSET;
-   }
-}
-
-static void
-calculate_model_project_matrix( GLcontext *ctx )
-{
-   _math_matrix_mul_matrix( &ctx->_ModelProjectMatrix,
-                            ctx->ProjectionMatrixStack.Top,
-                            ctx->ModelviewMatrixStack.Top );
-
-   _math_matrix_analyse( &ctx->_ModelProjectMatrix );
-}
-
-static void
-update_modelview_scale( GLcontext *ctx )
-{
-   ctx->_ModelViewInvScale = 1.0F;
-   if (ctx->ModelviewMatrixStack.Top->flags & (MAT_FLAG_UNIFORM_SCALE |
-			       MAT_FLAG_GENERAL_SCALE |
-			       MAT_FLAG_GENERAL_3D |
-			       MAT_FLAG_GENERAL) ) {
-      const GLfloat *m = ctx->ModelviewMatrixStack.Top->inv;
-      GLfloat f = m[2] * m[2] + m[6] * m[6] + m[10] * m[10];
-      if (f < 1e-12) f = 1.0;
-      if (ctx->_NeedEyeCoords)
-	 ctx->_ModelViewInvScale = 1.0F / SQRTF(f);
-      else
-	 ctx->_ModelViewInvScale = SQRTF(f);
-   }
-}
-
-
-/* Bring uptodate any state that relies on _NeedEyeCoords.
- */
-static void
-update_tnl_spaces( GLcontext *ctx, GLuint oldneedeyecoords )
-{
-   /* Check if the truth-value interpretations of the bitfields have
-    * changed:
-    */
-   if ((oldneedeyecoords == 0) != (ctx->_NeedEyeCoords == 0)) {
-      /* Recalculate all state that depends on _NeedEyeCoords.
-       */
-      update_modelview_scale(ctx);
-      _mesa_compute_light_positions( ctx );
-
-      if (ctx->Driver.LightingSpaceChange)
-	 ctx->Driver.LightingSpaceChange( ctx );
-   }
-   else {
-      GLuint new_state = ctx->NewState;
-
-      /* Recalculate that same state only if it has been invalidated
-       * by other statechanges.
-       */
-      if (new_state & _NEW_MODELVIEW)
-	 update_modelview_scale(ctx);
-
-      if (new_state & (_NEW_LIGHT|_NEW_MODELVIEW))
-	 _mesa_compute_light_positions( ctx );
-   }
-}
-
-
-static void
-update_drawbuffer( GLcontext *ctx )
-{
-   ctx->DrawBuffer->_Xmin = 0;
-   ctx->DrawBuffer->_Ymin = 0;
-   ctx->DrawBuffer->_Xmax = ctx->DrawBuffer->Width;
-   ctx->DrawBuffer->_Ymax = ctx->DrawBuffer->Height;
-   if (ctx->Scissor.Enabled) {
-      if (ctx->Scissor.X > ctx->DrawBuffer->_Xmin) {
-	 ctx->DrawBuffer->_Xmin = ctx->Scissor.X;
-      }
-      if (ctx->Scissor.Y > ctx->DrawBuffer->_Ymin) {
-	 ctx->DrawBuffer->_Ymin = ctx->Scissor.Y;
-      }
-      if (ctx->Scissor.X + ctx->Scissor.Width < ctx->DrawBuffer->_Xmax) {
-	 ctx->DrawBuffer->_Xmax = ctx->Scissor.X + ctx->Scissor.Width;
-      }
-      if (ctx->Scissor.Y + ctx->Scissor.Height < ctx->DrawBuffer->_Ymax) {
-	 ctx->DrawBuffer->_Ymax = ctx->Scissor.Y + ctx->Scissor.Height;
-      }
-   }
-}
-
-
-/* NOTE: This routine references Tranform attribute values to compute
- * userclip positions in clip space, but is only called on
- * _NEW_PROJECTION.  The _mesa_ClipPlane() function keeps these values
- * up to date across changes to the Transform attributes.
- */
-static void
-update_projection( GLcontext *ctx )
-{
-   _math_matrix_analyse( ctx->ProjectionMatrixStack.Top );
-
-   /* Recompute clip plane positions in clipspace.  This is also done
-    * in _mesa_ClipPlane().
-    */
-   if (ctx->Transform.ClipPlanesEnabled) {
-      GLuint p;
-      for (p = 0; p < ctx->Const.MaxClipPlanes; p++) {
-	 if (ctx->Transform.ClipPlanesEnabled & (1 << p)) {
-	    _mesa_transform_vector( ctx->Transform._ClipUserPlane[p],
-				 ctx->Transform.EyeUserPlane[p],
-				 ctx->ProjectionMatrixStack.Top->inv );
-	 }
-      }
-   }
-}
-
-
-/*
- * Return a bitmask of IMAGE_*_BIT flags which to indicate which
- * pixel transfer operations are enabled.
- */
-static void
-update_image_transfer_state(GLcontext *ctx)
-{
-   GLuint mask = 0;
-
-   if (ctx->Pixel.RedScale   != 1.0F || ctx->Pixel.RedBias   != 0.0F ||
-       ctx->Pixel.GreenScale != 1.0F || ctx->Pixel.GreenBias != 0.0F ||
-       ctx->Pixel.BlueScale  != 1.0F || ctx->Pixel.BlueBias  != 0.0F ||
-       ctx->Pixel.AlphaScale != 1.0F || ctx->Pixel.AlphaBias != 0.0F)
-      mask |= IMAGE_SCALE_BIAS_BIT;
-
-   if (ctx->Pixel.IndexShift || ctx->Pixel.IndexOffset)
-      mask |= IMAGE_SHIFT_OFFSET_BIT;
-
-   if (ctx->Pixel.MapColorFlag)
-      mask |= IMAGE_MAP_COLOR_BIT;
-
-   if (ctx->Pixel.ColorTableEnabled)
-      mask |= IMAGE_COLOR_TABLE_BIT;
-
-   if (ctx->Pixel.Convolution1DEnabled ||
-       ctx->Pixel.Convolution2DEnabled ||
-       ctx->Pixel.Separable2DEnabled) {
-      mask |= IMAGE_CONVOLUTION_BIT;
-      if (ctx->Pixel.PostConvolutionScale[0] != 1.0F ||
-          ctx->Pixel.PostConvolutionScale[1] != 1.0F ||
-          ctx->Pixel.PostConvolutionScale[2] != 1.0F ||
-          ctx->Pixel.PostConvolutionScale[3] != 1.0F ||
-          ctx->Pixel.PostConvolutionBias[0] != 0.0F ||
-          ctx->Pixel.PostConvolutionBias[1] != 0.0F ||
-          ctx->Pixel.PostConvolutionBias[2] != 0.0F ||
-          ctx->Pixel.PostConvolutionBias[3] != 0.0F) {
-         mask |= IMAGE_POST_CONVOLUTION_SCALE_BIAS;
-      }
-   }
-
-   if (ctx->Pixel.PostConvolutionColorTableEnabled)
-      mask |= IMAGE_POST_CONVOLUTION_COLOR_TABLE_BIT;
-
-   if (ctx->ColorMatrixStack.Top->type != MATRIX_IDENTITY ||
-       ctx->Pixel.PostColorMatrixScale[0] != 1.0F ||
-       ctx->Pixel.PostColorMatrixBias[0]  != 0.0F ||
-       ctx->Pixel.PostColorMatrixScale[1] != 1.0F ||
-       ctx->Pixel.PostColorMatrixBias[1]  != 0.0F ||
-       ctx->Pixel.PostColorMatrixScale[2] != 1.0F ||
-       ctx->Pixel.PostColorMatrixBias[2]  != 0.0F ||
-       ctx->Pixel.PostColorMatrixScale[3] != 1.0F ||
-       ctx->Pixel.PostColorMatrixBias[3]  != 0.0F)
-      mask |= IMAGE_COLOR_MATRIX_BIT;
-
-   if (ctx->Pixel.PostColorMatrixColorTableEnabled)
-      mask |= IMAGE_POST_COLOR_MATRIX_COLOR_TABLE_BIT;
-
-   if (ctx->Pixel.HistogramEnabled)
-      mask |= IMAGE_HISTOGRAM_BIT;
-
-   if (ctx->Pixel.MinMaxEnabled)
-      mask |= IMAGE_MIN_MAX_BIT;
-
-   ctx->_ImageTransferState = mask;
-}
+/** \name State update logic */
+/*@{*/
 
 
 
 
-/* Note: This routine refers to derived texture attribute values to
- * compute the ENABLE_TEXMAT flags, but is only called on
- * _NEW_TEXTURE_MATRIX.  On changes to _NEW_TEXTURE, the ENABLE_TEXMAT
- * flags are updated by _mesa_update_textures(), below.
- *
- * If both TEXTURE and TEXTURE_MATRIX change at once, these values
- * will be computed twice.
- */
-static void
-update_texture_matrices( GLcontext *ctx )
-{
-   GLuint i;
 
-   ctx->Texture._TexMatEnabled = 0;
 
-   for (i=0; i < ctx->Const.MaxTextureCoordUnits; i++) {
-      if (ctx->TextureMatrixStack[i].Top->flags & MAT_DIRTY) {
-	 _math_matrix_analyse( ctx->TextureMatrixStack[i].Top );
-
-	 if (ctx->Texture.Unit[i]._ReallyEnabled &&
-	     ctx->TextureMatrixStack[i].Top->type != MATRIX_IDENTITY)
-	    ctx->Texture._TexMatEnabled |= ENABLE_TEXMAT(i);
-
-	 if (ctx->Driver.TextureMatrix)
-	    ctx->Driver.TextureMatrix( ctx, i, ctx->TextureMatrixStack[i].Top);
-      }
-   }
-}
 
 
-/* Note: This routine refers to derived texture matrix values to
- * compute the ENABLE_TEXMAT flags, but is only called on
- * _NEW_TEXTURE.  On changes to _NEW_TEXTURE_MATRIX, the ENABLE_TEXMAT
- * flags are updated by _mesa_update_texture_matrices, above.
- *
- * If both TEXTURE and TEXTURE_MATRIX change at once, these values
- * will be computed twice.
- */
-static void
-update_texture_state( GLcontext *ctx )
-{
-   GLuint unit;
-
-   ctx->Texture._EnabledUnits = 0;
-   ctx->Texture._GenFlags = 0;
-   ctx->_NeedNormals &= ~NEED_NORMALS_TEXGEN;
-   ctx->_NeedEyeCoords &= ~NEED_EYE_TEXGEN;
-   ctx->Texture._TexMatEnabled = 0;
-   ctx->Texture._TexGenEnabled = 0;
-
-   /* Update texture unit state.
-    * XXX this loop should probably be broken into separate loops for
-    * texture coord units and texture image units.
-    */
-   for (unit = 0; unit < ctx->Const.MaxTextureUnits; unit++) {
-      struct gl_texture_unit *texUnit = &ctx->Texture.Unit[unit];
-      GLuint enableBits;
-
-      texUnit->_ReallyEnabled = 0;
-      texUnit->_GenFlags = 0;
-
-      /* Get the bitmask of texture enables */
-      if (ctx->FragmentProgram.Enabled && ctx->FragmentProgram.Current) {
-         enableBits = ctx->FragmentProgram.Current->TexturesUsed[unit];
-      }
-      else {
-         if (!texUnit->Enabled)
-            continue;
-         enableBits = texUnit->Enabled;
-      }
-
-      /* Look for the highest-priority texture target that's enabled and
-       * complete.  That's the one we'll use for texturing.  If we're using
-       * a fragment program we're guaranteed that bitcount(enabledBits) <= 1.
-       */
-      if (enableBits & TEXTURE_CUBE_BIT) {
-         struct gl_texture_object *texObj = texUnit->CurrentCubeMap;
-         if (!texObj->Complete) {
-            _mesa_test_texobj_completeness(ctx, texObj);
-         }
-         if (texObj->Complete) {
-            texUnit->_ReallyEnabled = TEXTURE_CUBE_BIT;
-            texUnit->_Current = texObj;
-         }
-      }
-
-      if (!texUnit->_ReallyEnabled && (enableBits & TEXTURE_3D_BIT)) {
-         struct gl_texture_object *texObj = texUnit->Current3D;
-         if (!texObj->Complete) {
-            _mesa_test_texobj_completeness(ctx, texObj);
-         }
-         if (texObj->Complete) {
-            texUnit->_ReallyEnabled = TEXTURE_3D_BIT;
-            texUnit->_Current = texObj;
-         }
-      }
-
-      if (!texUnit->_ReallyEnabled && (enableBits & TEXTURE_RECT_BIT)) {
-         struct gl_texture_object *texObj = texUnit->CurrentRect;
-         if (!texObj->Complete) {
-            _mesa_test_texobj_completeness(ctx, texObj);
-         }
-         if (texObj->Complete) {
-            texUnit->_ReallyEnabled = TEXTURE_RECT_BIT;
-            texUnit->_Current = texObj;
-         }
-      }
-
-      if (!texUnit->_ReallyEnabled && (enableBits & TEXTURE_2D_BIT)) {
-         struct gl_texture_object *texObj = texUnit->Current2D;
-         if (!texObj->Complete) {
-            _mesa_test_texobj_completeness(ctx, texObj);
-         }
-         if (texObj->Complete) {
-            texUnit->_ReallyEnabled = TEXTURE_2D_BIT;
-            texUnit->_Current = texObj;
-         }
-      }
-
-      if (!texUnit->_ReallyEnabled && (enableBits & TEXTURE_1D_BIT)) {
-         struct gl_texture_object *texObj = texUnit->Current1D;
-         if (!texObj->Complete) {
-            _mesa_test_texobj_completeness(ctx, texObj);
-         }
-         if (texObj->Complete) {
-            texUnit->_ReallyEnabled = TEXTURE_1D_BIT;
-            texUnit->_Current = texObj;
-         }
-      }
-
-      if (!texUnit->_ReallyEnabled) {
-	 texUnit->_Current = NULL;
-	 continue;
-      }
-
-      if (texUnit->_ReallyEnabled)
-         ctx->Texture._EnabledUnits |= (1 << unit);
-
-      if (texUnit->TexGenEnabled) {
-	 if (texUnit->TexGenEnabled & S_BIT) {
-	    texUnit->_GenFlags |= texUnit->_GenBitS;
-	 }
-	 if (texUnit->TexGenEnabled & T_BIT) {
-	    texUnit->_GenFlags |= texUnit->_GenBitT;
-	 }
-	 if (texUnit->TexGenEnabled & Q_BIT) {
-	    texUnit->_GenFlags |= texUnit->_GenBitQ;
-	 }
-	 if (texUnit->TexGenEnabled & R_BIT) {
-	    texUnit->_GenFlags |= texUnit->_GenBitR;
-	 }
-
-	 ctx->Texture._TexGenEnabled |= ENABLE_TEXGEN(unit);
-	 ctx->Texture._GenFlags |= texUnit->_GenFlags;
-      }
-
-      if (ctx->TextureMatrixStack[unit].Top->type != MATRIX_IDENTITY)
-	 ctx->Texture._TexMatEnabled |= ENABLE_TEXMAT(unit);
-   }
-
-   if (ctx->Texture._GenFlags & TEXGEN_NEED_NORMALS) {
-      ctx->_NeedNormals |= NEED_NORMALS_TEXGEN;
-      ctx->_NeedEyeCoords |= NEED_EYE_TEXGEN;
-   }
-
-   if (ctx->Texture._GenFlags & TEXGEN_NEED_EYE_COORD) {
-      ctx->_NeedEyeCoords |= NEED_EYE_TEXGEN;
-   }
-
-   ctx->Texture._EnabledCoordUnits = ctx->Texture._EnabledUnits;
-   /* Fragment programs may need texture coordinates but not the
-    * corresponding texture images.
-    */
-   if (ctx->FragmentProgram.Enabled && ctx->FragmentProgram.Current) {
-      ctx->Texture._EnabledCoordUnits |=
-         (ctx->FragmentProgram.Current->InputsRead >> FRAG_ATTRIB_TEX0);
-   }
-}
-
 
 /*
  * Update items which depend on vertex/fragment programs.
@@ -1061,93 +752,44 @@ update_program( GLcontext *ctx )
 
 
 /*
- * If ctx->NewState is non-zero then this function MUST be called before
- * rendering any primitive.  Basically, function pointers and miscellaneous
- * flags are updated to reflect the current state of the state machine.
- *
- * The above constraint is now maintained largely by the two Exec
- * dispatch tables, which trigger the appropriate flush on transition
- * between State and Geometry modes.
+ * If __GLcontextRec::NewState is non-zero then this function \b must be called
+ * before rendering any primitive.  Basically, function pointers and
+ * miscellaneous flags are updated to reflect the current state of the state
+ * machine.
  *
- * Special care is taken with the derived value _NeedEyeCoords.  This
- * is a bitflag which is updated with information from a number of
- * attribute groups (MODELVIEW, LIGHT, TEXTURE).  A lot of derived
- * state references this value, and must be treated with care to
- * ensure that updates are done correctly.  All state dependent on
- * _NeedEyeCoords is calculated from within _mesa_update_tnl_spaces(),
- * and from nowhere else.
+ * Calls dd_function_table::UpdateState to perform any internal state management
+ * necessary.
+ * 
+ * \sa _mesa_update_modelview_project(), _mesa_update_texture(),
+ * _mesa_update_buffers(), _mesa_update_polygon(), _mesa_update_lighting() and
+ * _mesa_update_tnl_spaces().
  */
 void _mesa_update_state( GLcontext *ctx )
 {
    const GLuint new_state = ctx->NewState;
-   const GLuint oldneedeyecoords = ctx->_NeedEyeCoords;
 
    if (MESA_VERBOSE & VERBOSE_STATE)
       _mesa_print_state("_mesa_update_state", new_state);
 
-   if (new_state & _NEW_MODELVIEW)
-      _math_matrix_analyse( ctx->ModelviewMatrixStack.Top );
-
-   if (new_state & _NEW_PROJECTION)
-      update_projection( ctx );
-
-   if (new_state & _NEW_TEXTURE_MATRIX)
-      update_texture_matrices( ctx );
-
-   if (new_state & _NEW_COLOR_MATRIX)
-      _math_matrix_analyse( ctx->ColorMatrixStack.Top );
-
-   /* References ColorMatrix.type (derived above).
-    */
-   if (new_state & _IMAGE_NEW_TRANSFER_STATE)
-      update_image_transfer_state(ctx);
+   if (new_state & (_NEW_MODELVIEW|_NEW_PROJECTION))
+      _mesa_update_modelview_project( ctx, new_state );
 
-   /* Contributes to NeedEyeCoords, NeedNormals.
-    */
-   if (new_state & _NEW_TEXTURE)
-      update_texture_state( ctx );
+   if (new_state & (_NEW_TEXTURE|_NEW_TEXTURE_MATRIX))
+      _mesa_update_texture( ctx, new_state );
 
-   if (new_state & (_NEW_BUFFERS|_NEW_SCISSOR))
-      update_drawbuffer( ctx );
+   if (new_state & (_NEW_SCISSOR|_NEW_BUFFERS))
+      _mesa_update_buffers( ctx );
 
    if (new_state & _NEW_POLYGON)
-      update_polygon( ctx );
+      _mesa_update_polygon( ctx );
 
-   /* Contributes to NeedEyeCoords, NeedNormals.
-    */
    if (new_state & _NEW_LIGHT)
       _mesa_update_lighting( ctx );
 
-   /* We can light in object space if the modelview matrix preserves
-    * lengths and relative angles.
-    */
-   if (new_state & (_NEW_MODELVIEW|_NEW_LIGHT)) {
-      ctx->_NeedEyeCoords &= ~NEED_EYE_LIGHT_MODELVIEW;
-      if (ctx->Light.Enabled &&
-	  !TEST_MAT_FLAGS( ctx->ModelviewMatrixStack.Top, MAT_FLAGS_LENGTH_PRESERVING))
-	    ctx->_NeedEyeCoords |= NEED_EYE_LIGHT_MODELVIEW;
-   }
 
    if (new_state & _NEW_PROGRAM)
       update_program( ctx );
 
-#if 0
-   /* XXX this is a bit of a hack.  We should be checking elsewhere if
-    * vertex program mode is enabled.  We set _NeedEyeCoords to zero to
-    * ensure that the combined modelview/projection matrix is computed
-    * in calculate_model_project_matrix().
-    */
-   if (ctx->VertexProgram.Enabled)
-      ctx->_NeedEyeCoords = 0;
-   /* KW: it's now always computed.
-    */
-#endif
-
-   /* Keep ModelviewProject uptodate always to allow tnl
-    * implementations that go model->clip even when eye is required.
-    */
-   if (new_state & (_NEW_MODELVIEW|_NEW_PROJECTION))
-      calculate_model_project_matrix(ctx);
 
    /* ctx->_NeedEyeCoords is now uptodate.
     *
@@ -1158,10 +800,8 @@ void _mesa_update_state( GLcontext *ctx )
     * If the lighting space hasn't changed, may still need to recompute
     * light positions & normal transforms for other reasons.
     */
-   if (new_state & (_NEW_MODELVIEW |
-		    _NEW_LIGHT |
-		    _MESA_NEW_NEED_EYE_COORDS))
-      update_tnl_spaces( ctx, oldneedeyecoords );
+   if (new_state & _MESA_NEW_NEED_EYE_COORDS) 
+      _mesa_update_tnl_spaces( ctx, new_state );
 
    /*
     * Here the driver sets up all the ctx->Driver function pointers
@@ -1179,52 +819,7 @@ void _mesa_update_state( GLcontext *ctx )
    /* At this point we can do some assertions to be sure the required
     * device driver function pointers are all initialized.
     */
-   ASSERT(ctx->Driver.GetString);
-   ASSERT(ctx->Driver.UpdateState);
-   ASSERT(ctx->Driver.Clear);
-   ASSERT(ctx->Driver.GetBufferSize);
-   if (ctx->Visual.accumRedBits > 0) {
-      ASSERT(ctx->Driver.Accum);
-   }
-   ASSERT(ctx->Driver.DrawPixels);
-   ASSERT(ctx->Driver.ReadPixels);
-   ASSERT(ctx->Driver.CopyPixels);
-   ASSERT(ctx->Driver.Bitmap);
-   ASSERT(ctx->Driver.ResizeBuffers);
-   ASSERT(ctx->Driver.TexImage1D);
-   ASSERT(ctx->Driver.TexImage2D);
-   ASSERT(ctx->Driver.TexImage3D);
-   ASSERT(ctx->Driver.TexSubImage1D);
-   ASSERT(ctx->Driver.TexSubImage2D);
-   ASSERT(ctx->Driver.TexSubImage3D);
-   ASSERT(ctx->Driver.CopyTexImage1D);
-   ASSERT(ctx->Driver.CopyTexImage2D);
-   ASSERT(ctx->Driver.CopyTexSubImage1D);
-   ASSERT(ctx->Driver.CopyTexSubImage2D);
-   ASSERT(ctx->Driver.CopyTexSubImage3D);
-   if (ctx->Extensions.ARB_texture_compression) {
-#if 0  /* HW drivers need these, but not SW rasterizers */
-      ASSERT(ctx->Driver.CompressedTexImage1D);
-      ASSERT(ctx->Driver.CompressedTexImage2D);
-      ASSERT(ctx->Driver.CompressedTexImage3D);
-      ASSERT(ctx->Driver.CompressedTexSubImage1D);
-      ASSERT(ctx->Driver.CompressedTexSubImage2D);
-      ASSERT(ctx->Driver.CompressedTexSubImage3D);
-#endif
-   }
+   _mesa_check_driver_hooks( ctx );
 }
 
-/* Is this helpful?
- */
-void
-_mesa_allow_light_in_model( GLcontext *ctx, GLboolean flag )
-{
-   if (flag) 
-      ctx->_NeedEyeCoords &= ~NEED_EYE_DRIVER;
-   else
-      ctx->_NeedEyeCoords |= NEED_EYE_DRIVER;
-
-   ctx->NewState |= _NEW_POINT;	/* one of the bits from
-				 * _MESA_NEW_NEED_EYE_COORDS.
-				 */
-}
+/*@}*/
diff --git a/src/mesa/main/state.h b/src/mesa/main/state.h
index 8d3ccc16d5..fe577a8563 100644
--- a/src/mesa/main/state.h
+++ b/src/mesa/main/state.h
@@ -1,3 +1,7 @@
+/**
+ * \file state.h
+ * State management.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -29,7 +33,6 @@
 
 #include "mtypes.h"
 
-
 extern void
 _mesa_init_no_op_table(struct _glapi_table *exec, GLuint tableSize);
 
@@ -39,13 +42,5 @@ _mesa_init_exec_table(struct _glapi_table *exec, GLuint tableSize);
 extern void
 _mesa_update_state( GLcontext *ctx );
 
-extern void
-_mesa_print_state( const char *msg, GLuint state );
-
-extern void
-_mesa_print_enable_flags( const char *msg, GLuint flags );
-
-extern void
-_mesa_allow_light_in_model( GLcontext *ctx, GLboolean flag );
 
 #endif
diff --git a/src/mesa/main/stencil.c b/src/mesa/main/stencil.c
index 1b7c637c4c..bcfe383790 100644
--- a/src/mesa/main/stencil.c
+++ b/src/mesa/main/stencil.c
@@ -1,3 +1,7 @@
+/**
+ * \file stencil.c
+ * Stencil operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -34,6 +38,17 @@
 #include "enable.h"
 
 
+/**
+ * Set the clear value for the stencil buffer.
+ *
+ * \param s clear value.
+ *
+ * \sa glClearStencil().
+ *
+ * Updates gl_stencil_attrib::Clear. On change
+ * flushes the vertices and notifies the driver via
+ * the dd_function_table::ClearStencil callback.
+ */
 void
 _mesa_ClearStencil( GLint s )
 {
@@ -52,7 +67,19 @@ _mesa_ClearStencil( GLint s )
 }
 
 
-
+/**
+ * Set the function and reference value for stencil testing.
+ *
+ * \param func test function.
+ * \param ref reference value.
+ * \param mask bitmask.
+ *
+ * \sa glStencilFunc().
+ *
+ * Verifies the parameters and updates the respective values in
+ * __GLcontextRec::Stencil. On change flushes the vertices and notifies the
+ * driver via the dd_function_table::StencilFunc callback.
+ */
 void
 _mesa_StencilFunc( GLenum func, GLint ref, GLuint mask )
 {
@@ -95,7 +122,17 @@ _mesa_StencilFunc( GLenum func, GLint ref, GLuint mask )
 }
 
 
-
+/**
+ * Set the stencil writing mask.
+ *
+ * \param mask bit-mask to enable/disable writing of individual bits in the
+ * stencil planes.
+ *
+ * \sa glStencilMask().
+ *
+ * Updates gl_stencil_attrib::WriteMask. On change flushes the vertices and
+ * notifies the driver via the dd_function_table::StencilMask callback.
+ */
 void
 _mesa_StencilMask( GLuint mask )
 {
@@ -115,7 +152,20 @@ _mesa_StencilMask( GLuint mask )
 }
 
 
-
+/**
+ * Set the stencil test actions.
+ *
+ * \param fail action to take when stencil test fails.
+ * \param zfail action to take when stencil test passes, but the depth test fails.
+ * \param zpass action to take when stencil test passes and the depth test
+ * passes (or depth testing is not enabled).
+ * 
+ * \sa glStencilOp().
+ * 
+ * Verifies the parameters and updates the respective fields in
+ * __GLcontextRec::Stencil. On change flushes the vertices and notifies the
+ * driver via the dd_function_table::StencilOp callback.
+ */
 void
 _mesa_StencilOp(GLenum fail, GLenum zfail, GLenum zpass)
 {
@@ -194,6 +244,7 @@ _mesa_StencilOp(GLenum fail, GLenum zfail, GLenum zpass)
 }
 
 
+#if _HAVE_FULL_GL
 /* GL_EXT_stencil_two_side */
 void
 _mesa_ActiveStencilFaceEXT(GLenum face)
@@ -210,4 +261,36 @@ _mesa_ActiveStencilFaceEXT(GLenum face)
       (*ctx->Driver.ActiveStencilFace)( ctx, (GLuint) ctx->Stencil.ActiveFace );
    }
 }
+#endif
+
 
+/**
+ * Initialize the context stipple state.
+ *
+ * \param ctx GL context.
+ *
+ * Initializes __GLcontextRec::Stencil attribute group.
+ */
+void _mesa_init_stencil( GLcontext * ctx )
+{
+
+   /* Stencil group */
+   ctx->Stencil.Enabled = GL_FALSE;
+   ctx->Stencil.TestTwoSide = GL_FALSE;
+   ctx->Stencil.ActiveFace = 0;  /* 0 = GL_FRONT, 1 = GL_BACK */
+   ctx->Stencil.Function[0] = GL_ALWAYS;
+   ctx->Stencil.Function[1] = GL_ALWAYS;
+   ctx->Stencil.FailFunc[0] = GL_KEEP;
+   ctx->Stencil.FailFunc[1] = GL_KEEP;
+   ctx->Stencil.ZPassFunc[0] = GL_KEEP;
+   ctx->Stencil.ZPassFunc[1] = GL_KEEP;
+   ctx->Stencil.ZFailFunc[0] = GL_KEEP;
+   ctx->Stencil.ZFailFunc[1] = GL_KEEP;
+   ctx->Stencil.Ref[0] = 0;
+   ctx->Stencil.Ref[1] = 0;
+   ctx->Stencil.ValueMask[0] = STENCIL_MAX;
+   ctx->Stencil.ValueMask[1] = STENCIL_MAX;
+   ctx->Stencil.WriteMask[0] = STENCIL_MAX;
+   ctx->Stencil.WriteMask[1] = STENCIL_MAX;
+   ctx->Stencil.Clear = 0;
+}
diff --git a/src/mesa/main/stencil.h b/src/mesa/main/stencil.h
index bb20884b85..cf645608f8 100644
--- a/src/mesa/main/stencil.h
+++ b/src/mesa/main/stencil.h
@@ -1,3 +1,7 @@
+/**
+ * \file stencil.h
+ * Stencil operations.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -51,4 +55,7 @@ extern void
 _mesa_ActiveStencilFaceEXT(GLenum face);
 
 
+extern void
+_mesa_init_stencil( GLcontext * ctx );
+
 #endif
diff --git a/src/mesa/main/texcompress.c b/src/mesa/main/texcompress.c
index 01425f33a5..e6a9695722 100644
--- a/src/mesa/main/texcompress.c
+++ b/src/mesa/main/texcompress.c
@@ -1,3 +1,8 @@
+/**
+ * \file texcompress.c
+ * Compressed textures functions.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -33,7 +38,10 @@
 
 /**
  * Get the list of supported internal compression formats.
- * \param formats - the results list (may be NULL)
+ * 
+ * \param ctx GL context.
+ * \param formats the resulting format list (may be NULL).
+ *
  * \return number of formats.
  */
 GLuint
@@ -70,13 +78,16 @@ _mesa_get_compressed_formats( GLcontext *ctx, GLint *formats )
 }
 
 
-
 /**
- * Return bytes of storage needed for the given texture size and compressed
- * format.
- * \param width, height, depth  the texture size in texels
- * \param texFormat   one of the specific compressed format enums
- * \return size in bytes, or zero if bad texFormat
+ * Return bytes of storage needed for the given texture size and
+ * compressed format.
+ * 
+ * \param width texture width in texels.
+ * \param height texture height in texels.
+ * \param depth texture depth in texels.
+ * \param texFormat one of the compressed format enums
+ * 
+ * \return size in bytes, or zero if bad \p texFormat.
  */
 GLuint
 _mesa_compressed_texture_size( GLcontext *ctx,
@@ -159,11 +170,15 @@ _mesa_compressed_row_stride(GLenum format, GLsizei width)
 /**
  * Return the address of the pixel at (col, row, img) in a
  * compressed texture image.
- * \param col, row, img - image position (3D)
- * \param format - compressed image format
- * \param width - image width
- * \param image - the image address
- * \return address of pixel at (row, col)
+ * 
+ * \param col image position.
+ * \param row image position.
+ * \param img image position.
+ * \param format compressed image format.
+ * \param width image width.
+ * \param image the image address.
+ * 
+ * \return address of pixel at (row, col).
  */
 GLubyte *
 _mesa_compressed_image_address(GLint col, GLint row, GLint img,
@@ -197,9 +212,8 @@ _mesa_compressed_image_address(GLint col, GLint row, GLint img,
 }
 
 
-
-/*
- * \param srcRowStride - source stride, in pixels
+/**
+ * \param srcRowStride source stride, in pixels
  */
 void
 _mesa_compress_teximage( GLcontext *ctx, GLsizei width, GLsizei height,
diff --git a/src/mesa/main/texcompress.h b/src/mesa/main/texcompress.h
index d0856142e3..457c1d7582 100644
--- a/src/mesa/main/texcompress.h
+++ b/src/mesa/main/texcompress.h
@@ -28,7 +28,7 @@
 
 #include "mtypes.h"
 
-
+#if _HAVE_FULL_GL
 extern GLuint
 _mesa_get_compressed_formats( GLcontext *ctx, GLint *formats );
 
@@ -53,5 +53,12 @@ _mesa_compress_teximage( GLcontext *ctx, GLsizei width, GLsizei height,
                          GLint srcRowStride,
                          const struct gl_texture_format *dstFormat,
                          GLubyte *dest, GLint dstRowStride );
+#else
+#define _mesa_get_compressed_formats( c, f ) 0
+#define _mesa_compressed_texture_size( c, w, h, d, f ) 0
+#define _mesa_compressed_row_stride( f, w) 0
+#define _mesa_compressed_image_address(c, r, i, f, w, i2 ) 0
+#define _mesa_compress_teximage( c, w, h, sF, s, sRS, dF, d, drs ) ((void)0)
+#endif
 
 #endif /* TEXCOMPRESS_H */
diff --git a/src/mesa/main/texformat.c b/src/mesa/main/texformat.c
index e92572242f..b5c721f211 100644
--- a/src/mesa/main/texformat.c
+++ b/src/mesa/main/texformat.c
@@ -1,3 +1,10 @@
+/**
+ * \file texformat.c
+ * Texture formats.
+ *
+ * \author Gareth Hughes
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -20,11 +27,9 @@
  * BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- *
- * Author:
- *    Gareth Hughes
  */
 
+
 #include "glheader.h"
 #include "colormac.h"
 #include "context.h"
@@ -36,7 +41,7 @@
 #include "texstate.h"
 
 
-/* Texel fetch routines for all supported formats:
+/* Texel fetch routines for all supported formats
  */
 #define DIM 1
 #include "texformat_tmp.h"
@@ -47,7 +52,10 @@
 #define DIM 3
 #include "texformat_tmp.h"
 
-/* Have to have this so the FetchTexel function pointer is never NULL.
+/**
+ * Null texel fetch function.
+ *
+ * Have to have this so the FetchTexel function pointer is never NULL.
  */
 static void fetch_null_texel( const struct gl_texture_image *texImage,
 			      GLint i, GLint j, GLint k, GLvoid *texel )
@@ -60,9 +68,9 @@ static void fetch_null_texel( const struct gl_texture_image *texImage,
 }
 
 
-/* =============================================================
- * Default GLchan-based formats:
- */
+/***************************************************************/
+/** \name Default GLchan-based formats */
+/*@{*/
 
 const struct gl_texture_format _mesa_texformat_rgba = {
    MESA_FORMAT_RGBA,			/* MesaFormat */
@@ -200,10 +208,12 @@ const struct gl_texture_format _mesa_texformat_depth_component = {
    fetch_3d_texel_depth_component,	/* FetchTexel3D */
 };
 
+/*@}*/
 
-/* =============================================================
- * Hardware formats:
- */
+
+/***************************************************************/
+/** \name Hardware formats */
+/*@{*/
 
 const struct gl_texture_format _mesa_texformat_rgba8888 = {
    MESA_FORMAT_RGBA8888,		/* MesaFormat */
@@ -659,9 +669,12 @@ const struct gl_texture_format _mesa_texformat_bgr233 = {
 };
 #endif
 
-/* =============================================================
- * Null format (useful for proxy textures):
- */
+/*@}*/
+
+
+/***************************************************************/
+/** \name Null format (useful for proxy textures) */
+/*@{*/
 
 const struct gl_texture_format _mesa_null_texformat = {
    -1,					/* MesaFormat */
@@ -680,7 +693,21 @@ const struct gl_texture_format _mesa_null_texformat = {
    fetch_null_texel,			/* FetchTexel3D */
 };
 
+/*@}*/
+
 
+/**
+ * Determine whether a given texture format is a hardware texture
+ * format.
+ *
+ * \param format texture format.
+ * 
+ * \return GL_TRUE if \p format is a hardware texture format, or GL_FALSE
+ * otherwise.
+ *
+ * \p format is a hardware texture format if gl_texture_format::MesaFormat is
+ * lower than _format::MESA_FORMAT_RGBA.
+ */
 GLboolean
 _mesa_is_hardware_tex_format( const struct gl_texture_format *format )
 {
@@ -688,11 +715,19 @@ _mesa_is_hardware_tex_format( const struct gl_texture_format *format )
 }
 
 
-/* Given an internal texture format (or 1, 2, 3, 4) return a pointer
- * to a gl_texture_format which which to store the texture.
- * This is called via ctx->Driver.ChooseTextureFormat().
- * Hardware drivers typically override this function with a specialized
- * version.
+/**
+ * Choose an appropriate texture format.
+ *
+ * \param ctx GL context.
+ * \param internalFormat internal texture format.
+ * \param format pixel format.
+ * \param type data type.
+ *
+ * \return a pointer to a gl_texture_format in which to store the texture on
+ * success, or NULL on failure.
+ * 
+ * This is called via dd_function_table::ChooseTextureFormat.  Hardware drivers
+ * typically override this function with a specialized version.
  */
 const struct gl_texture_format *
 _mesa_choose_tex_format( GLcontext *ctx, GLint internalFormat,
@@ -849,11 +884,10 @@ _mesa_choose_tex_format( GLcontext *ctx, GLint internalFormat,
 }
 
 
-
-
-/*
+/**
  * Return the base texture format for the given compressed format
- * Called via ctx->Driver.BaseCompressedTexFormat().
+ * 
+ * Called via dd_function_table::Driver.BaseCompressedTexFormat.
  * This function is used by software rasterizers.  Hardware drivers
  * which support texture compression should not use this function but
  * a specialized function instead.
diff --git a/src/mesa/main/texformat.h b/src/mesa/main/texformat.h
index 6f19aac7bc..07fa2adb75 100644
--- a/src/mesa/main/texformat.h
+++ b/src/mesa/main/texformat.h
@@ -1,3 +1,10 @@
+/**
+ * \file texformat.h
+ * Texture formats definitions.
+ *
+ * \author Gareth Hughes
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -20,34 +27,36 @@
  * BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- *
- * Author:
- *    Gareth Hughes
  */
 
+
 #ifndef TEXFORMAT_H
 #define TEXFORMAT_H
 
 #include "mtypes.h"
 
 
-/*
- * The Mesa internal texture image types.
+/**
+ * Mesa internal texture image types.
+ * 
  * All texture images must be stored in one of these formats.
  */
 enum _format {
-   /* Hardware-friendly formats.  Drivers can override the default
-    * formats and convert texture images to one of these as required.
-    * The driver's ChooseTextureFormat() function will choose one of
-    * these formats.
-    * These formats are all little endian, as shown below.  They will be
-    * most useful for x86-based PC graphics card drivers.
+   /** 
+    * \name Hardware-friendly formats.  
+    *
+    * Drivers can override the default formats and convert texture images to
+    * one of these as required.  The driver's
+    * dd_function_table::ChooseTextureFormat function will choose one of these
+    * formats.  These formats are all little endian, as shown below.  They will
+    * be most useful for x86-based PC graphics card drivers.
     *
-    * NOTE: In the default case, some of these formats will be
-    * duplicates of the generic formats listed below.  However, these
-    * formats guarantee their internal component sizes, while GLchan may
-    * vary betwen GLubyte, GLushort and GLfloat.
+    * \note In the default case, some of these formats will be duplicates of
+    * the generic formats listed below.  However, these formats guarantee their
+    * internal component sizes, while GLchan may vary between GLubyte, GLushort
+    * and GLfloat.
     */
+   /*@{*/
 				/* msb <------ TEXEL BITS -----------> lsb */
 				/* ---- ---- ---- ---- ---- ---- ---- ---- */
    MESA_FORMAT_RGBA8888,	/* RRRR RRRR GGGG GGGG BBBB BBBB AAAA AAAA */
@@ -64,6 +73,7 @@ enum _format {
    MESA_FORMAT_CI8,		/*                               CCCC CCCC */
    MESA_FORMAT_YCBCR,		/*                     YYYY YYYY UorV UorV */
    MESA_FORMAT_YCBCR_REV,	/*                     UorV UorV YYYY YYYY */
+   /*@}*/
 
    MESA_FORMAT_RGB_DXT1,
    MESA_FORMAT_RGBA_DXT1,
@@ -71,8 +81,10 @@ enum _format {
    MESA_FORMAT_RGBA_DXT5,
 
 #if 0
-   /* upcoming little-endian formats: */
-
+   /** 
+    * \name Upcoming little-endian formats 
+    */
+   /*@{*/
 				/* msb <------ TEXEL BITS -----------> lsb */
 				/* ---- ---- ---- ---- ---- ---- ---- ---- */
    MESA_FORMAT_ABGR8888,	/* AAAA AAAA BBBB BBBB GGGG GGGG RRRR RRRR */
@@ -83,18 +95,22 @@ enum _format {
    MESA_FORMAT_BGRA5551,	/*                     BBBB BGGG GGRR RRRA */
    MESA_FORMAT_LA88,		/*                     LLLL LLLL AAAA AAAA */
    MESA_FORMAT_BGR233,		/*                               BBGG GRRR */
+   /*@}*/
 #endif
 
-   /* Generic GLchan-based formats.  These are the default formats used
-    * by the software rasterizer and, unless the driver overrides the
-    * texture image functions, incoming images will be converted to one
-    * of these formats.  Components are arrays of GLchan values, so
-    * there will be no big/little endian issues.
+   /**
+    * \name Generic GLchan-based formats.
+    *
+    * These are the default formats used by the software rasterizer and, unless
+    * the driver overrides the texture image functions, incoming images will be
+    * converted to one of these formats.  Components are arrays of GLchan
+    * values, so there will be no big/little endian issues.
     *
-    * NOTE: Because these are based on the GLchan datatype, one cannot
-    * assume 8 bits per channel with these formats.  If you require
-    * GLubyte channels, use one of the hardware formats above.
+    * \note Because these are based on the GLchan data type, one cannot assume 8
+    * bits per channel with these formats.  If you require GLubyte channels,
+    * use one of the hardware formats above.
     */
+   /*@{*/
    MESA_FORMAT_RGBA,
    MESA_FORMAT_RGB,
    MESA_FORMAT_ALPHA,
@@ -103,6 +119,7 @@ enum _format {
    MESA_FORMAT_INTENSITY,
    MESA_FORMAT_COLOR_INDEX,
    MESA_FORMAT_DEPTH_COMPONENT
+   /*@}*/
 };
 
 
@@ -117,8 +134,8 @@ extern GLint
 _mesa_base_compressed_texformat(GLcontext *ctx, GLint intFormat);
 
 
-/* The default formats, GLchan per component:
- */
+/** The default formats, GLchan per component */
+/*@{*/
 extern const struct gl_texture_format _mesa_texformat_rgba;
 extern const struct gl_texture_format _mesa_texformat_rgb;
 extern const struct gl_texture_format _mesa_texformat_alpha;
@@ -127,9 +144,10 @@ extern const struct gl_texture_format _mesa_texformat_luminance_alpha;
 extern const struct gl_texture_format _mesa_texformat_intensity;
 extern const struct gl_texture_format _mesa_texformat_color_index;
 extern const struct gl_texture_format _mesa_texformat_depth_component;
+/*@}*/
 
-/* The hardware-friendly formats:
- */
+/** \name The hardware-friendly formats */
+/*@{*/
 extern const struct gl_texture_format _mesa_texformat_rgba8888;
 extern const struct gl_texture_format _mesa_texformat_argb8888;
 extern const struct gl_texture_format _mesa_texformat_rgb888;
@@ -148,9 +166,11 @@ extern const struct gl_texture_format _mesa_texformat_rgb_dxt1;
 extern const struct gl_texture_format _mesa_texformat_rgba_dxt1;
 extern const struct gl_texture_format _mesa_texformat_rgba_dxt3;
 extern const struct gl_texture_format _mesa_texformat_rgba_dxt5;
+/*@}*/
 
-/* The null format:
- */
+/** \name The null format */
+/*@{*/
 extern const struct gl_texture_format _mesa_null_texformat;
+/*@}*/
 
 #endif
diff --git a/src/mesa/main/texformat_tmp.h b/src/mesa/main/texformat_tmp.h
index 83715d3fdb..840fcd2549 100644
--- a/src/mesa/main/texformat_tmp.h
+++ b/src/mesa/main/texformat_tmp.h
@@ -1,3 +1,20 @@
+/**
+ * \file texformat_tmp.h
+ * Texel fetch functions template.
+ * 
+ * This template file is used by texformat.c to generate texel fetch functions
+ * for 1-D, 2-D and 3-D texture images. 
+ *
+ * It should be expanded by definining \p DIM as the number texture dimensions
+ * (1, 2 or 3).  According to the value of \p DIM a serie of macros is defined
+ * for the texel lookup in the gl_texture_image::Data.
+ * 
+ * \sa texformat.c and FetchTexel.
+ * 
+ * \author Gareth Hughes
+ * \author Brian Paul
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -20,16 +37,6 @@
  * BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- *
- * Authors:
- *    Gareth Hughes
- *    Brian Paul
- */
-
-
-/*
- * This template file generates texel fetch functions for 1-D, 2-D and 3-D
- * texture images.
  */
 
 
diff --git a/src/mesa/main/teximage.c b/src/mesa/main/teximage.c
index de28839463..90f0332237 100644
--- a/src/mesa/main/teximage.c
+++ b/src/mesa/main/teximage.c
@@ -1,3 +1,14 @@
+/**
+ * \file teximage.c
+ * Texture images manipulation functions.
+ *
+ * \note Mesa's native texture data type is GLchan.  Native formats are
+ * GL_ALPHA, GL_LUMINANCE, GL_LUMANCE_ALPHA, GL_INTENSITY, GL_RGB, GL_RGBA, and
+ * GL_COLOR_INDEX.
+ *
+ * \note Device drivers are free to implement any internal format they want.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -22,6 +33,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
 #include "glheader.h"
 #include "context.h"
 #include "convolve.h"
@@ -37,16 +49,6 @@
 #include "mtypes.h"
 
 
-/*
- * NOTES:
- *
- * Mesa's native texture datatype is GLchan.  Native formats are
- * GL_ALPHA, GL_LUMINANCE, GL_LUMANCE_ALPHA, GL_INTENSITY, GL_RGB, GL_RGBA,
- * and GL_COLOR_INDEX.
- * Device drivers are free to implement any internal format they want.
- */
-
-
 #if 0
 static void PrintTexture(GLcontext *ctx, const struct gl_texture_image *img)
 {
@@ -101,7 +103,6 @@ static void PrintTexture(GLcontext *ctx, const struct gl_texture_image *img)
 #endif
 
 
-
 /*
  * Compute floor(log_base_2(n)).
  * If n <= 0 return -1.
@@ -130,15 +131,17 @@ logbase2( int n )
 
 
 
-/*
- * Given an internal texture format enum or 1, 2, 3, 4 return the
- * corresponding _base_ internal format:  GL_ALPHA, GL_LUMINANCE,
- * GL_LUMANCE_ALPHA, GL_INTENSITY, GL_RGB, or GL_RGBA.
+/**
+ * Get base internal format.
+ *
+ * \param ctx GL context.
+ * \param format internal texture format enum or 1, 2, 3, 4.
+ *
+ * \return the corresponding \u base internal format (GL_ALPHA, GL_LUMINANCE,
+ * GL_LUMANCE_ALPHA, GL_INTENSITY, GL_RGB, or GL_RGBA), or -1 if invalid enum.
  *
  * This is the format which is used during texture application (i.e. the
  * texture format and env mode determine the arithmetic used.
- *
- * Return -1 if invalid enum.
  */
 GLint
 _mesa_base_tex_format( GLcontext *ctx, GLint format )
@@ -270,9 +273,9 @@ _mesa_base_tex_format( GLcontext *ctx, GLint format )
 }
 
 
-/*
- * Test if the given image format is a color/rgba format.  That is,
- * not color index, depth, stencil, etc.
+/**
+ * Test if the given image format is a color/RGBA format, i.e., not
+ * color index, depth, stencil, etc.
  */
 static GLboolean
 is_color_format(GLenum format)
@@ -328,6 +331,9 @@ is_color_format(GLenum format)
 }
 
 
+/**
+ * Test if the given image format is a color index format.
+ */
 static GLboolean
 is_index_format(GLenum format)
 {
@@ -347,9 +353,15 @@ is_index_format(GLenum format)
 
 
 /**
- * Return GL_TRUE if internalFormat is a supported compressed format,
- * return GL_FALSE otherwise.
- * \param - internalFormat - the internal format token provided by the user
+ * Test if it is a supported compressed format.
+ * 
+ * \param internalFormat the internal format token provided by the user.
+ * 
+ * \ret GL_TRUE if \p internalFormat is a supported compressed format, or
+ * GL_FALSE otherwise.
+ *
+ * Currently only GL_COMPRESSED_RGB_FXT1_3DFX and GL_COMPRESSED_RGBA_FXT1_3DFX
+ * are supported.
  */
 static GLboolean
 is_compressed_format(GLenum internalFormat)
@@ -364,9 +376,15 @@ is_compressed_format(GLenum internalFormat)
 }
 
 
-/*
+/**
  * Store a gl_texture_image pointer in a gl_texture_object structure
  * according to the target and level parameters.
+ * 
+ * \param tObj texture object.
+ * \param target texture target.
+ * \param level image level.
+ * \param texImage texture image.
+ * 
  * This was basically prompted by the introduction of cube maps.
  */
 void
@@ -411,11 +429,14 @@ _mesa_set_tex_image(struct gl_texture_object *tObj,
 }
 
 
-
 /**
- * Return new gl_texture_image struct with all fields initialized to zero.
+ * Allocate a texture image structure.
+ * 
  * Called via ctx->Driver.NewTextureImage() unless overriden by a device
  * driver.
+ *
+ * \return a pointer to gl_texture_image struct with all fields initialized to
+ * zero.
  */
 struct gl_texture_image *
 _mesa_new_texture_image( GLcontext *ctx )
@@ -425,9 +446,12 @@ _mesa_new_texture_image( GLcontext *ctx )
 }
 
 
-
 /**
- * Delete/free the given texture image and associated image data if it's not
+ * Free texture image.
+ *
+ * \param teximage texture image.
+ *
+ * Free the texture image structure and the associated image data if it's not
  * marked as client data.
  */
 void
@@ -441,8 +465,12 @@ _mesa_delete_texture_image( struct gl_texture_image *teximage )
 }
 
 
-/*
- * Return GL_TRUE if the target is a proxy target.
+/**
+ * Test if a target is a proxy target.
+ *
+ * \param target texture target.
+ *
+ * \return GL_TRUE if the target is a proxy target, GL_FALSE otherwise.
  */
 static GLboolean
 is_proxy_target(GLenum target)
@@ -455,9 +483,16 @@ is_proxy_target(GLenum target)
 }
 
 
-/*
- * Given a texture unit and a texture target, return the corresponding
- * texture object.
+/**
+ * Get the texture object that corresponds to the target of the given texture unit.
+ *
+ * \param ctx GL context.
+ * \param texUnit texture unit.
+ * \param target texture target.
+ *
+ * \return pointer to the texture object on success, or NULL on failure.
+ * 
+ * \sa gl_texture_unit.
  */
 struct gl_texture_object *
 _mesa_select_tex_object(GLcontext *ctx, const struct gl_texture_unit *texUnit,
@@ -501,9 +536,18 @@ _mesa_select_tex_object(GLcontext *ctx, const struct gl_texture_unit *texUnit,
 }
 
 
-/*
- * Return the texture image struct which corresponds to target and level
- * for the given texture unit.
+/**
+ * Get the texture image struct which corresponds to target and level
+ * of the given texture unit.
+ *
+ * \param ctx GL context.
+ * \param texUnit texture unit.
+ * \param target texture target.
+ * \param level image level.
+ *
+ * \return pointer to the texture image structure on success, or NULL on failure.
+ *
+ * \sa gl_texture_unit.
  */
 struct gl_texture_image *
 _mesa_select_tex_image(GLcontext *ctx, const struct gl_texture_unit *texUnit,
@@ -694,9 +738,16 @@ _mesa_get_proxy_tex_image(GLcontext *ctx, GLenum target, GLint level)
 }
 
 
-/*
- * Return the maximum number of allows mipmap levels for the given
- * texture target.
+/**
+ * Get the maximum number of allowed mipmap levels.
+ *
+ * \param ctx GL context.
+ * \param target texture target.
+ * 
+ * \return the maximum number of allowed mipmap levels for the given
+ * texture target, or zero if passed a bad target.
+ *
+ * \sa gl_constants.
  */
 GLint
 _mesa_max_texture_levels(GLcontext *ctx, GLenum target)
@@ -786,6 +837,9 @@ make_null_texture(GLint width, GLint height, GLint depth, GLenum format)
 
 /**
  * Reset the fields of a gl_texture_image struct to zero.
+ * 
+ * \param img texture image structure.
+ *
  * This is called when a proxy texture test fails, we set all the
  * image members (except DriverData) to zero.
  * It's also used in glTexImage[123]D as a safeguard to be sure all
@@ -817,8 +871,19 @@ clear_teximage_fields(struct gl_texture_image *img)
 }
 
 
-/*
+/**
  * Initialize basic fields of the gl_texture_image struct.
+ *
+ * \param ctx GL context.
+ * \param target texture target.
+ * \param img texture image structure to be initialized.
+ * \param width image width.
+ * \param height image height.
+ * \param depth image depth.
+ * \param border image border.
+ * \param internalFormat internal format.
+ *
+ * Fills in the fields of \p img with the given information.
  * Note: width, height and depth include the border.
  */
 void
@@ -978,11 +1043,25 @@ _mesa_test_proxy_teximage(GLcontext *ctx, GLenum target, GLint level,
 
 
 /**
- * Test glTexImage[123]D() parameters for errors.
- * This function calls the ctx->Driver.TestProxyTexImage() function to
- * check the level and size.
- * \param dimensions  must be 1 or 2 or 3
- * \return  GL_TRUE if an error was detected or GL_FALSE if no errors
+ * Test the glTexImage[123]D() parameters for errors.
+ * 
+ * \param ctx GL context.
+ * \param target texture target given by the user.
+ * \param level image level given by the user.
+ * \param internalFormat internal format given by the user.
+ * \param format pixel data format given by the user.
+ * \param type pixel data type given by the user.
+ * \param dimensions texture image dimensions (must be 1, 2 or 3).
+ * \param width image width given by the user.
+ * \param height image height given by the user.
+ * \param depth image depth given by the user.
+ * \param border image border given by the user.
+ * 
+ * \return GL_TRUE if an error was detected, or GL_FALSE if no errors.
+ *
+ * Verifies each of the parameters against the constants specified in
+ * __GLcontextRec::Const and the supported extensions, and according to the
+ * OpenGL specification.
  */
 static GLboolean
 texture_error_check( GLcontext *ctx, GLenum target,
@@ -1186,12 +1265,27 @@ texture_error_check( GLcontext *ctx, GLenum target,
 }
 
 
-
-/*
+/**
  * Test glTexSubImage[123]D() parameters for errors.
- * Input:
- *         dimensions - must be 1 or 2 or 3
- * Return:  GL_TRUE = an error was detected, GL_FALSE = no errors
+ * 
+ * \param ctx GL context.
+ * \param dimensions texture image dimensions (must be 1, 2 or 3).
+ * \param target texture target given by the user.
+ * \param level image level given by the user.
+ * \param xoffset sub-image x offset given by the user.
+ * \param yoffset sub-image y offset given by the user.
+ * \param zoffset sub-image z offset given by the user.
+ * \param format pixel data format given by the user.
+ * \param type pixel data type given by the user.
+ * \param width image width given by the user.
+ * \param height image height given by the user.
+ * \param depth image depth given by the user.
+ * 
+ * \return GL_TRUE if an error was detected, or GL_FALSE if no errors.
+ *
+ * Verifies each of the parameters against the constants specified in
+ * __GLcontextRec::Const and the supported extensions, and according to the
+ * OpenGL specification.
  */
 static GLboolean
 subtexture_error_check( GLcontext *ctx, GLuint dimensions,
@@ -1353,10 +1447,24 @@ subtexture_error_check( GLcontext *ctx, GLuint dimensions,
 }
 
 
-/*
+/**
  * Test glCopyTexImage[12]D() parameters for errors.
- * Input:  dimensions - must be 1 or 2 or 3
- * Return:  GL_TRUE = an error was detected, GL_FALSE = no errors
+ * 
+ * \param ctx GL context.
+ * \param dimensions texture image dimensions (must be 1, 2 or 3).
+ * \param target texture target given by the user.
+ * \param level image level given by the user.
+ * \param internalFormat internal format given by the user.
+ * \param width image width given by the user.
+ * \param height image height given by the user.
+ * \param depth image depth given by the user.
+ * \param border texture border.
+ * 
+ * \return GL_TRUE if an error was detected, or GL_FALSE if no errors.
+ * 
+ * Verifies each of the parameters against the constants specified in
+ * __GLcontextRec::Const and the supported extensions, and according to the
+ * OpenGL specification.
  */
 static GLboolean
 copytexture_error_check( GLcontext *ctx, GLuint dimensions,
@@ -1477,6 +1585,25 @@ copytexture_error_check( GLcontext *ctx, GLuint dimensions,
 }
 
 
+/**
+ * Test glCopyTexImage[12]D() parameters for errors.
+ * 
+ * \param ctx GL context.
+ * \param dimensions texture image dimensions (must be 1, 2 or 3).
+ * \param target texture target given by the user.
+ * \param level image level given by the user.
+ * \param xoffset sub-image x offset given by the user.
+ * \param yoffset sub-image y offset given by the user.
+ * \param zoffset sub-image z offset given by the user.
+ * \param width image width given by the user.
+ * \param height image height given by the user.
+ * 
+ * \return GL_TRUE if an error was detected, or GL_FALSE if no errors.
+ * 
+ * Verifies each of the parameters against the constants specified in
+ * __GLcontextRec::Const and the supported extensions, and according to the
+ * OpenGL specification.
+ */
 static GLboolean
 copytexsubimage_error_check( GLcontext *ctx, GLuint dimensions,
                              GLenum target, GLint level,
@@ -1618,7 +1745,15 @@ copytexsubimage_error_check( GLcontext *ctx, GLuint dimensions,
 }
 
 
-
+/**
+ * Get texture image.
+ *
+ * \param target texture target.
+ * \param level image level.
+ * \param format pixel data format.
+ * \param type pixel data type.
+ * \param pixels pixel data.
+ */
 void
 _mesa_GetTexImage( GLenum target, GLint level, GLenum format,
                    GLenum type, GLvoid *pixels )
diff --git a/src/mesa/main/teximage.h b/src/mesa/main/teximage.h
index ed0008e37f..e90cd71705 100644
--- a/src/mesa/main/teximage.h
+++ b/src/mesa/main/teximage.h
@@ -1,3 +1,8 @@
+/**
+ * \file teximage.h
+ * Texture images manipulation functions.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -30,8 +35,8 @@
 #include "mtypes.h"
 
 
-/*** Internal functions ***/
-
+/** \name Internal functions */
+/*@{*/
 
 extern GLint
 _mesa_base_tex_format( GLcontext *ctx, GLint format );
@@ -86,8 +91,11 @@ _mesa_test_proxy_teximage(GLcontext *ctx, GLenum target, GLint level,
                          GLint internalFormat, GLenum format, GLenum type,
                          GLint width, GLint height, GLint depth, GLint border);
 
-/*** API entry point functions ***/
+/*@}*/
+
 
+/** \name API entry point functions */
+/*@{*/
 
 extern void
 _mesa_TexImage1D( GLenum target, GLint level, GLint internalformat,
@@ -214,5 +222,6 @@ _mesa_CompressedTexSubImage3DARB(GLenum target, GLint level, GLint xoffset,
 extern void
 _mesa_GetCompressedTexImageARB(GLenum target, GLint lod, GLvoid *img);
 
+/*@}*/
 
 #endif
diff --git a/src/mesa/main/texobj.c b/src/mesa/main/texobj.c
index 19b2b3f8e4..e131fae50e 100644
--- a/src/mesa/main/texobj.c
+++ b/src/mesa/main/texobj.c
@@ -1,3 +1,8 @@
+/**
+ * \file texobj.c
+ * Texture object management.
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -22,6 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
 #include "glheader.h"
 #include "colortab.h"
 #include "context.h"
@@ -35,16 +41,30 @@
 #include "mtypes.h"
 
 
+/**********************************************************************/
+/** \name Internal functions */
+/*@{*/
+
 /**
- * Allocate and initialize a new texture object
+ * Allocate and initialize a new texture object and add it to the linked list of
+ * texture objects.  
+ *
  * Called via ctx->Driver.NewTextureObject, unless overridden by a device
  * driver.
- * \param ctx  the rendering context
- * \param name  the integer name for the texture object
- * \param target  either GL_TEXTURE_1D, GL_TEXTURE_2D, GL_TEXTURE_3D,
- *                GL_TEXTURE_CUBE_MAP_ARB or GL_TEXTURE_RECTANGLE_NV
- *                zero is ok for the sake of GenTextures()
- * \return  pointer to new texture object
+ * 
+ * \param shared the shared GL state structure to contain the texture object
+ * \param name integer name for the texture object
+ * \param target either GL_TEXTURE_1D, GL_TEXTURE_2D, GL_TEXTURE_3D,
+ * GL_TEXTURE_CUBE_MAP_ARB or GL_TEXTURE_RECTANGLE_NV.  zero is ok for the sake
+ * of GenTextures()
+ *
+ * \return pointer to new texture object.
+ *
+ * Allocate and initialize a gl_texture_object structure, and insert in the
+ * shared state texture list while holding its mutex.
+ * If <tt>name > 0</tt> then also insert the new texture object into the hash
+ * table.
+ * 
  */
 struct gl_texture_object *
 _mesa_new_texture_object( GLcontext *ctx, GLuint name, GLenum target )
@@ -103,14 +123,20 @@ _mesa_initialize_texture_object( struct gl_texture_object *obj,
    obj->CompareFunc = GL_LEQUAL;       /* ARB_shadow */
    obj->DepthMode = GL_LUMINANCE;      /* ARB_depth_texture */
    obj->ShadowAmbient = 0.0F;          /* ARB/SGIX_shadow_ambient */
-   _mesa_init_colortable(&obj->Palette);
+   _mesa_init_one_colortable(&obj->Palette);
 }
 
 
-/*
- * Deallocate a texture object.  It should have already been removed from
- * the texture object pool.
- * \param texObj  the texture object to deallocate
+/**
+ * Deallocate a texture object struct.  It should have already been
+ * removed from the texture object pool.
+ *
+ * \param shared the shared GL state to which the object belongs.
+ * \param texOjb the texture object to delete.
+ *
+ * Unlink the texture object from the shared state texture linked list while
+ * holding its lock. If the texture is a name number it's also removed from the
+ * hash table. Finally frees the texture images and the object itself.
  */
 void
 _mesa_delete_texture_object( GLcontext *ctx, struct gl_texture_object *texObj )
@@ -121,7 +147,7 @@ _mesa_delete_texture_object( GLcontext *ctx, struct gl_texture_object *texObj )
 
    assert(texObj);
 
-   _mesa_free_colortable_data(&texObj->Palette);
+   _mesa_free_one_colortable(&texObj->Palette);
 
    /* free the texture images */
    for (i = 0; i < MAX_TEXTURE_LEVELS; i++) {
@@ -193,9 +219,11 @@ _mesa_remove_texture_object( GLcontext *ctx, struct gl_texture_object *texObj )
    }
 }
 
-
-/*
+/**
  * Copy texture object state from one texture object to another.
+ *
+ * \param dest destination texture object.
+ * \param src source texture object.
  */
 void
 _mesa_copy_texture_object( struct gl_texture_object *dest,
@@ -232,8 +260,13 @@ _mesa_copy_texture_object( struct gl_texture_object *dest,
 }
 
 
-/*
- * Report why a texture object is incomplete.  (for debug only)
+/**
+ * Report why a texture object is incomplete.  
+ *
+ * \param t texture object.
+ * \param why string describing why it's incomplete.
+ *
+ * \note For debug purposes only.
  */
 #if 0
 static void
@@ -242,13 +275,21 @@ incomplete(const struct gl_texture_object *t, const char *why)
    _mesa_printf("Texture Obj %d incomplete because: %s\n", t->Name, why);
 }
 #else
-#define incomplete(a, b)
+#define incomplete(t, why)
 #endif
 
 
-/*
+/**
  * Examine a texture object to determine if it is complete.
- * The t->Complete flag will be set to GL_TRUE or GL_FALSE accordingly.
+ *
+ * The gl_texture_object::Complete flag will be set to GL_TRUE or GL_FALSE
+ * accordingly.
+ *
+ * \param ctx GL context.
+ * \param t texture object.
+ *
+ * According to the texture target, verifies that each of the mipmaps is
+ * present and has the expected size.
  */
 void
 _mesa_test_texobj_completeness( const GLcontext *ctx,
@@ -525,13 +566,33 @@ _mesa_test_texobj_completeness( const GLcontext *ctx,
    }
 }
 
+/*@}*/
 
-_glthread_DECLARE_STATIC_MUTEX(GenTexturesLock);
 
+/***********************************************************************/
+/** \name API functions */
+/*@{*/
 
-/*
- * Execute glGenTextures
+/**
+ * Texture name generation lock.
+ *
+ * Used by _mesa_GenTextures() to guarantee that the generation and allocation
+ * of texture IDs is atomic.
  */
+_glthread_DECLARE_STATIC_MUTEX(GenTexturesLock);
+
+/**
+ * Generate texture names.
+ *
+ * \param n number of texture names to be generated.
+ * \param texName an array in which will hold the generated texture names.
+ *
+ * \sa glGenTextures().
+ *
+ * While holding the GenTexturesLock lock, calls _mesa_HashFindFreeKeyBlock()
+ * to find a block of free texture IDs which are stored in \p texName.
+ * Corresponding empty texture objects are also generated.
+ */ 
 void
 _mesa_GenTextures( GLsizei n, GLuint *texName )
 {
@@ -576,10 +637,17 @@ _mesa_GenTextures( GLsizei n, GLuint *texName )
    _glthread_UNLOCK_MUTEX(GenTexturesLock);
 }
 
-
-
-/*
- * Execute glDeleteTextures
+/**
+ * Delete named textures.
+ *
+ * \param n number of textures to be deleted.
+ * \param texName array of textures names to be deleted.
+ *
+ * \sa glDeleteTextures().
+ *
+ * For each texture checks if its bound to any of the texture units, unbinding
+ * it and decrementing the reference count if so. If the texture reference
+ * count is zero, delete its object.
  */
 void
 _mesa_DeleteTextures( GLsizei n, const GLuint *texName)
@@ -655,10 +723,20 @@ _mesa_DeleteTextures( GLsizei n, const GLuint *texName)
    }
 }
 
-
-
-/*
- * Execute glBindTexture
+/**
+ * Bind a named texture to a texturing target.
+ * 
+ * \param target texture target.
+ * \param texName texture name.
+ * 
+ * \sa glBindTexture().
+ *
+ * Determines the old texture object bound and returns immediately if rebinding
+ * the same texture.  Get the current texture which is either a default texture
+ * if name is null, a named texture from the hash, or a new texture if the
+ * given texture name is new. Increments its reference count, binds it, and
+ * calls dd_function_table::BindTexture. Decrements the old texture reference
+ * count and deletes it if it reaches zero.
  */
 void
 _mesa_BindTexture( GLenum target, GLuint texName )
@@ -804,10 +882,17 @@ _mesa_BindTexture( GLenum target, GLuint texName )
    }
 }
 
-
-
-/*
- * Execute glPrioritizeTextures
+/**
+ * Set texture priorities.
+ * 
+ * \param n number of textures.
+ * \param texName texture names.
+ * \param priorities corresponding texture priorities.
+ * 
+ * \sa glPrioritizeTextures().
+ * 
+ * Looks up each texture in the hash, clamps the corresponding priority between
+ * 0.0 and 1.0, and calls dd_function_table::PrioritizeTexture.
  */
 void
 _mesa_PrioritizeTextures( GLsizei n, const GLuint *texName,
@@ -840,10 +925,19 @@ _mesa_PrioritizeTextures( GLsizei n, const GLuint *texName,
    ctx->NewState |= _NEW_TEXTURE;
 }
 
-
-
-/*
- * Execute glAreTexturesResident
+/**
+ * See if textures are loaded in texture memory.
+ * 
+ * \param n number of textures to query.
+ * \param texName array with the texture names.
+ * \param residences array which will hold the residence status.
+ *
+ * \return GL_TRUE if all textures are resident and \p residences is left unchanged, 
+ * 
+ * \sa glAreTexturesResident().
+ *
+ * Looks up each texture in the hash and calls
+ * dd_function_table::IsTextureResident.
  */
 GLboolean
 _mesa_AreTexturesResident(GLsizei n, const GLuint *texName,
@@ -894,10 +988,17 @@ _mesa_AreTexturesResident(GLsizei n, const GLuint *texName,
    return allResident;
 }
 
-
-
-/*
- * Execute glIsTexture
+/**
+ * See if a name corresponds to a texture.
+ *
+ * \param texture texture name.
+ *
+ * \return GL_TRUE if texture name corresponds to a texture, or GL_FALSE
+ * otherwise.
+ * 
+ * \sa glIsTexture().
+ *
+ * Calls _mesa_HashLookup().
  */
 GLboolean
 _mesa_IsTexture( GLuint texture )
@@ -906,3 +1007,5 @@ _mesa_IsTexture( GLuint texture )
    ASSERT_OUTSIDE_BEGIN_END_WITH_RETVAL(ctx, GL_FALSE);
    return texture > 0 && _mesa_HashLookup(ctx->Shared->TexObjects, texture);
 }
+
+/*@}*/
diff --git a/src/mesa/main/texobj.h b/src/mesa/main/texobj.h
index 6311a50a71..f7e8e690c4 100644
--- a/src/mesa/main/texobj.h
+++ b/src/mesa/main/texobj.h
@@ -1,3 +1,7 @@
+/**
+ * \file texobj.h
+ * Texture object management.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -31,10 +35,10 @@
 #include "mtypes.h"
 
 
-
-/*
- * Internal functions
+/**
+ * \name Internal functions
  */
+/*@{*/
 
 extern struct gl_texture_object *
 _mesa_new_texture_object( GLcontext *ctx, GLuint name, GLenum target );
@@ -60,10 +64,13 @@ extern void
 _mesa_test_texobj_completeness( const GLcontext *ctx,
                                 struct gl_texture_object *obj );
 
+/*@}*/
 
-/*
- * API functions
+
+/**
+ * \name API functions
  */
+/*@{*/
 
 extern void
 _mesa_GenTextures( GLsizei n, GLuint *textures );
@@ -86,9 +93,9 @@ extern GLboolean
 _mesa_AreTexturesResident( GLsizei n, const GLuint *textures,
                            GLboolean *residences );
 
-
 extern GLboolean
 _mesa_IsTexture( GLuint texture );
 
+/*@}*/
 
 #endif
diff --git a/src/mesa/main/texstate.c b/src/mesa/main/texstate.c
index 9359c7b1b1..59fd7a9928 100644
--- a/src/mesa/main/texstate.c
+++ b/src/mesa/main/texstate.c
@@ -25,10 +25,12 @@
 
 #include "glheader.h"
 #include "colormac.h"
+#include "colortab.h"
 #include "context.h"
 #include "enums.h"
 #include "extensions.h"
 #include "macros.h"
+#include "nvfragprog.h"
 #include "texobj.h"
 #include "teximage.h"
 #include "texstate.h"
@@ -1909,7 +1911,7 @@ _mesa_GetTexParameteriv( GLenum target, GLenum pname, GLint *params )
 /*                    Texture Coord Generation                        */
 /**********************************************************************/
 
-
+#if FEATURE_texgen
 void
 _mesa_TexGenfv( GLenum coord, GLenum pname, const GLfloat *params )
 {
@@ -2458,7 +2460,7 @@ _mesa_GetTexGeniv( GLenum coord, GLenum pname, GLint *params )
 	 return;
    }
 }
-
+#endif
 
 /* GL_ARB_multitexture */
 void
@@ -2643,3 +2645,347 @@ _mesa_GetPixelTexGenParameterivSGIS(GLenum target, GLint *value)
       _mesa_error(ctx, GL_INVALID_ENUM, "glGetPixelTexGenParameterivSGIS(target)");
    }
 }
+
+
+
+/**********************************************************************/
+/*****                    State management                        *****/
+/**********************************************************************/
+
+
+/**
+ * \note This routine refers to derived texture attribute values to
+ * compute the ENABLE_TEXMAT flags, but is only called on
+ * _NEW_TEXTURE_MATRIX.  On changes to _NEW_TEXTURE, the ENABLE_TEXMAT
+ * flags are updated by _mesa_update_textures(), below.
+ *
+ * \param ctx GL context.
+ */
+static void
+update_texture_matrices( GLcontext *ctx )
+{
+   GLuint i;
+
+   ctx->Texture._TexMatEnabled = 0;
+
+   for (i=0; i < ctx->Const.MaxTextureUnits; i++) {
+      if (ctx->TextureMatrixStack[i].Top->flags & MAT_DIRTY) {
+	 _math_matrix_analyse( ctx->TextureMatrixStack[i].Top );
+
+	 if (ctx->Texture.Unit[i]._ReallyEnabled &&
+	     ctx->TextureMatrixStack[i].Top->type != MATRIX_IDENTITY)
+	    ctx->Texture._TexMatEnabled |= ENABLE_TEXMAT(i);
+
+	 if (ctx->Driver.TextureMatrix)
+	    ctx->Driver.TextureMatrix( ctx, i, ctx->TextureMatrixStack[i].Top);
+      }
+   }
+}
+
+
+
+
+/**
+ * \note This routine refers to derived texture matrix values to
+ * compute the ENABLE_TEXMAT flags, but is only called on
+ * _NEW_TEXTURE.  On changes to _NEW_TEXTURE_MATRIX, the ENABLE_TEXMAT
+ * flags are updated by _mesa_update_texture_matrices, above.
+ *
+ * \param ctx GL context.
+ */
+static void
+update_texture_state( GLcontext *ctx )
+{
+   GLuint unit;
+
+   ctx->Texture._EnabledUnits = 0;
+   ctx->Texture._GenFlags = 0;
+   ctx->Texture._TexMatEnabled = 0;
+   ctx->Texture._TexGenEnabled = 0;
+
+   /* Update texture unit state.
+    * XXX this loop should probably be broken into separate loops for
+    * texture coord units and texture image units.
+    */
+   for (unit = 0; unit < ctx->Const.MaxTextureUnits; unit++) {
+      struct gl_texture_unit *texUnit = &ctx->Texture.Unit[unit];
+      GLuint enableBits;
+
+      texUnit->_ReallyEnabled = 0;
+      texUnit->_GenFlags = 0;
+
+      /* Get the bitmask of texture enables */
+      if (ctx->FragmentProgram.Enabled && ctx->FragmentProgram.Current) {
+         enableBits = ctx->FragmentProgram.Current->TexturesUsed[unit];
+      }
+      else {
+         if (!texUnit->Enabled)
+            continue;
+         enableBits = texUnit->Enabled;
+      }
+
+      /* Look for the highest-priority texture target that's enabled and
+       * complete.  That's the one we'll use for texturing.  If we're using
+       * a fragment program we're guaranteed that bitcount(enabledBits) <= 1.
+       */
+      if (texUnit->Enabled & TEXTURE_CUBE_BIT) {
+         struct gl_texture_object *texObj = texUnit->CurrentCubeMap;
+         if (!texObj->Complete) {
+            _mesa_test_texobj_completeness(ctx, texObj);
+         }
+         if (texObj->Complete) {
+            texUnit->_ReallyEnabled = TEXTURE_CUBE_BIT;
+            texUnit->_Current = texObj;
+         }
+      }
+
+      if (!texUnit->_ReallyEnabled && (texUnit->Enabled & TEXTURE_3D_BIT)) {
+         struct gl_texture_object *texObj = texUnit->Current3D;
+         if (!texObj->Complete) {
+            _mesa_test_texobj_completeness(ctx, texObj);
+         }
+         if (texObj->Complete) {
+            texUnit->_ReallyEnabled = TEXTURE_3D_BIT;
+            texUnit->_Current = texObj;
+         }
+      }
+
+      if (!texUnit->_ReallyEnabled && (texUnit->Enabled & TEXTURE_RECT_BIT)) {
+         struct gl_texture_object *texObj = texUnit->CurrentRect;
+         if (!texObj->Complete) {
+            _mesa_test_texobj_completeness(ctx, texObj);
+         }
+         if (texObj->Complete) {
+            texUnit->_ReallyEnabled = TEXTURE_RECT_BIT;
+            texUnit->_Current = texObj;
+         }
+      }
+
+      if (!texUnit->_ReallyEnabled && (texUnit->Enabled & TEXTURE_2D_BIT)) {
+         struct gl_texture_object *texObj = texUnit->Current2D;
+         if (!texObj->Complete) {
+            _mesa_test_texobj_completeness(ctx, texObj);
+         }
+         if (texObj->Complete) {
+            texUnit->_ReallyEnabled = TEXTURE_2D_BIT;
+            texUnit->_Current = texObj;
+         }
+      }
+
+      if (!texUnit->_ReallyEnabled && (texUnit->Enabled & TEXTURE_1D_BIT)) {
+         struct gl_texture_object *texObj = texUnit->Current1D;
+         if (!texObj->Complete) {
+            _mesa_test_texobj_completeness(ctx, texObj);
+         }
+         if (texObj->Complete) {
+            texUnit->_ReallyEnabled = TEXTURE_1D_BIT;
+            texUnit->_Current = texObj;
+         }
+      }
+
+      if (!texUnit->_ReallyEnabled) {
+	 texUnit->_Current = NULL;
+	 continue;
+      }
+
+      if (texUnit->_ReallyEnabled)
+         ctx->Texture._EnabledUnits |= (1 << unit);
+
+      if (texUnit->TexGenEnabled) {
+	 if (texUnit->TexGenEnabled & S_BIT) {
+	    texUnit->_GenFlags |= texUnit->_GenBitS;
+	 }
+	 if (texUnit->TexGenEnabled & T_BIT) {
+	    texUnit->_GenFlags |= texUnit->_GenBitT;
+	 }
+	 if (texUnit->TexGenEnabled & Q_BIT) {
+	    texUnit->_GenFlags |= texUnit->_GenBitQ;
+	 }
+	 if (texUnit->TexGenEnabled & R_BIT) {
+	    texUnit->_GenFlags |= texUnit->_GenBitR;
+	 }
+
+	 ctx->Texture._TexGenEnabled |= ENABLE_TEXGEN(unit);
+	 ctx->Texture._GenFlags |= texUnit->_GenFlags;
+      }
+
+      if (ctx->TextureMatrixStack[unit].Top->type != MATRIX_IDENTITY)
+	 ctx->Texture._TexMatEnabled |= ENABLE_TEXMAT(unit);
+   }
+
+   ctx->Texture._EnabledCoordUnits = ctx->Texture._EnabledUnits;
+   /* Fragment programs may need texture coordinates but not the
+    * corresponding texture images.
+    */
+   if (ctx->FragmentProgram.Enabled && ctx->FragmentProgram.Current) {
+      ctx->Texture._EnabledCoordUnits |=
+         (ctx->FragmentProgram.Current->InputsRead >> FRAG_ATTRIB_TEX0);
+   }
+}
+
+
+void _mesa_update_texture( GLcontext *ctx, GLuint new_state )
+{
+   if (new_state & _NEW_TEXTURE_MATRIX)
+      update_texture_matrices( ctx );
+
+   if (new_state & _NEW_TEXTURE)
+      update_texture_state( ctx );
+}
+
+/**********************************************************************/
+/*****                      Initialization                        *****/
+/**********************************************************************/
+
+/**
+ * Allocate the proxy textures for the given context.
+ * 
+ * \param ctx the context to allocate proxies for.
+ * 
+ * \return GL_TRUE on success, or GL_FALSE on failure
+ * 
+ * If run out of memory part way through the allocations, clean up and return
+ * GL_FALSE.
+ */
+static GLboolean
+alloc_proxy_textures( GLcontext *ctx )
+{
+   ctx->Texture.Proxy1D = (*ctx->Driver.NewTextureObject)(ctx, 0, GL_TEXTURE_1D);
+   if (!ctx->Texture.Proxy1D)
+      goto cleanup;
+
+   ctx->Texture.Proxy2D = (*ctx->Driver.NewTextureObject)(ctx, 0, GL_TEXTURE_2D);
+   if (!ctx->Texture.Proxy2D)
+      goto cleanup;
+
+   ctx->Texture.Proxy3D = (*ctx->Driver.NewTextureObject)(ctx, 0, GL_TEXTURE_3D);
+   if (!ctx->Texture.Proxy3D)
+      goto cleanup;
+
+   ctx->Texture.ProxyCubeMap = (*ctx->Driver.NewTextureObject)(ctx, 0, GL_TEXTURE_CUBE_MAP_ARB);
+   if (!ctx->Texture.ProxyCubeMap)
+      goto cleanup;
+
+   ctx->Texture.ProxyRect = (*ctx->Driver.NewTextureObject)(ctx, 0, GL_TEXTURE_RECTANGLE_NV);
+   if (!ctx->Texture.ProxyRect)
+      goto cleanup;
+
+   return GL_TRUE;
+
+ cleanup:
+   if (ctx->Texture.Proxy1D)
+      (ctx->Driver.DeleteTexture)(ctx, ctx->Texture.Proxy1D);
+   if (ctx->Texture.Proxy2D)
+      (ctx->Driver.DeleteTexture)(ctx, ctx->Texture.Proxy2D);
+   if (ctx->Texture.Proxy3D)
+      (ctx->Driver.DeleteTexture)(ctx, ctx->Texture.Proxy3D);
+   if (ctx->Texture.ProxyCubeMap)
+      (ctx->Driver.DeleteTexture)(ctx, ctx->Texture.ProxyCubeMap);
+   if (ctx->Texture.ProxyRect)
+      (ctx->Driver.DeleteTexture)(ctx, ctx->Texture.ProxyRect);
+   return GL_FALSE;
+}
+
+
+/**
+ * Initialize a texture unit.
+ *
+ * \param ctx GL context.
+ * \param unit texture unit number to be initialized.
+ */
+static void
+init_texture_unit( GLcontext *ctx, GLuint unit )
+{
+   struct gl_texture_unit *texUnit = &ctx->Texture.Unit[unit];
+
+   texUnit->EnvMode = GL_MODULATE;
+   ASSIGN_4V( texUnit->EnvColor, 0.0, 0.0, 0.0, 0.0 );
+
+   texUnit->CombineModeRGB = GL_MODULATE;
+   texUnit->CombineModeA = GL_MODULATE;
+   texUnit->CombineSourceRGB[0] = GL_TEXTURE;
+   texUnit->CombineSourceRGB[1] = GL_PREVIOUS_EXT;
+   texUnit->CombineSourceRGB[2] = GL_CONSTANT_EXT;
+   texUnit->CombineSourceA[0] = GL_TEXTURE;
+   texUnit->CombineSourceA[1] = GL_PREVIOUS_EXT;
+   texUnit->CombineSourceA[2] = GL_CONSTANT_EXT;
+   texUnit->CombineOperandRGB[0] = GL_SRC_COLOR;
+   texUnit->CombineOperandRGB[1] = GL_SRC_COLOR;
+   texUnit->CombineOperandRGB[2] = GL_SRC_ALPHA;
+   texUnit->CombineOperandA[0] = GL_SRC_ALPHA;
+   texUnit->CombineOperandA[1] = GL_SRC_ALPHA;
+   texUnit->CombineOperandA[2] = GL_SRC_ALPHA;
+   texUnit->CombineScaleShiftRGB = 0;
+   texUnit->CombineScaleShiftA = 0;
+
+   texUnit->TexGenEnabled = 0;
+   texUnit->GenModeS = GL_EYE_LINEAR;
+   texUnit->GenModeT = GL_EYE_LINEAR;
+   texUnit->GenModeR = GL_EYE_LINEAR;
+   texUnit->GenModeQ = GL_EYE_LINEAR;
+   texUnit->_GenBitS = TEXGEN_EYE_LINEAR;
+   texUnit->_GenBitT = TEXGEN_EYE_LINEAR;
+   texUnit->_GenBitR = TEXGEN_EYE_LINEAR;
+   texUnit->_GenBitQ = TEXGEN_EYE_LINEAR;
+
+   /* Yes, these plane coefficients are correct! */
+   ASSIGN_4V( texUnit->ObjectPlaneS, 1.0, 0.0, 0.0, 0.0 );
+   ASSIGN_4V( texUnit->ObjectPlaneT, 0.0, 1.0, 0.0, 0.0 );
+   ASSIGN_4V( texUnit->ObjectPlaneR, 0.0, 0.0, 0.0, 0.0 );
+   ASSIGN_4V( texUnit->ObjectPlaneQ, 0.0, 0.0, 0.0, 0.0 );
+   ASSIGN_4V( texUnit->EyePlaneS, 1.0, 0.0, 0.0, 0.0 );
+   ASSIGN_4V( texUnit->EyePlaneT, 0.0, 1.0, 0.0, 0.0 );
+   ASSIGN_4V( texUnit->EyePlaneR, 0.0, 0.0, 0.0, 0.0 );
+   ASSIGN_4V( texUnit->EyePlaneQ, 0.0, 0.0, 0.0, 0.0 );
+
+   texUnit->Current1D = ctx->Shared->Default1D;
+   texUnit->Current2D = ctx->Shared->Default2D;
+   texUnit->Current3D = ctx->Shared->Default3D;
+   texUnit->CurrentCubeMap = ctx->Shared->DefaultCubeMap;
+   texUnit->CurrentRect = ctx->Shared->DefaultRect;
+}
+
+
+GLboolean _mesa_init_texture( GLcontext * ctx )
+{
+   int i;
+
+   assert(MAX_TEXTURE_LEVELS >= MAX_3D_TEXTURE_LEVELS);
+   assert(MAX_TEXTURE_LEVELS >= MAX_CUBE_TEXTURE_LEVELS);
+
+   /* Effectively bind the default textures to all texture units */
+   ctx->Shared->Default1D->RefCount += MAX_TEXTURE_UNITS;
+   ctx->Shared->Default2D->RefCount += MAX_TEXTURE_UNITS;
+   ctx->Shared->Default3D->RefCount += MAX_TEXTURE_UNITS;
+   ctx->Shared->DefaultCubeMap->RefCount += MAX_TEXTURE_UNITS;
+   ctx->Shared->DefaultRect->RefCount += MAX_TEXTURE_UNITS;
+
+   /* Texture group */
+   ctx->Texture.CurrentUnit = 0;      /* multitexture */
+   ctx->Texture._EnabledUnits = 0;
+   for (i=0; i<MAX_TEXTURE_UNITS; i++)
+      init_texture_unit( ctx, i );
+   ctx->Texture.SharedPalette = GL_FALSE;
+   _mesa_init_one_colortable(&ctx->Texture.Palette);
+
+   /* Allocate proxy textures */
+   if (!alloc_proxy_textures( ctx ))
+      return GL_FALSE;
+
+   return GL_TRUE;
+}
+
+void _mesa_free_texture_data( GLcontext *ctx )
+{
+   int i;
+
+   /* Free proxy texture objects */
+   (ctx->Driver.DeleteTexture)(ctx,  ctx->Texture.Proxy1D );
+   (ctx->Driver.DeleteTexture)(ctx,  ctx->Texture.Proxy2D );
+   (ctx->Driver.DeleteTexture)(ctx,  ctx->Texture.Proxy3D );
+   (ctx->Driver.DeleteTexture)(ctx,  ctx->Texture.ProxyCubeMap );
+   (ctx->Driver.DeleteTexture)(ctx,  ctx->Texture.ProxyRect );
+
+   for (i = 0; i < MAX_TEXTURE_IMAGE_UNITS; i++)
+      _mesa_free_colortable_data( &ctx->Texture.Unit[i].ColorTable );
+}
diff --git a/src/mesa/main/texstate.h b/src/mesa/main/texstate.h
index de4678665d..d2cde7b326 100644
--- a/src/mesa/main/texstate.h
+++ b/src/mesa/main/texstate.h
@@ -1,3 +1,7 @@
+/**
+ * \file texstate.h
+ * Texture state management.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -38,7 +42,10 @@ extern void
 _mesa_print_texunit_state( GLcontext *ctx, GLuint unit );
 
 
-/*** Called from API ***/
+/**
+ * \name Called from API
+ */
+/*@{*/
 
 extern void
 _mesa_GetTexEnvfv( GLenum target, GLenum pname, GLfloat *params );
@@ -116,8 +123,6 @@ extern void
 _mesa_TexGeniv( GLenum coord, GLenum pname, const GLint *params );
 
 
-
-
 /*
  * GL_ARB_multitexture
  */
@@ -165,5 +170,23 @@ _mesa_GetPixelTexGenParameterfvSGIS(GLenum target, GLfloat *value);
 extern void
 _mesa_GetPixelTexGenParameterivSGIS(GLenum target, GLint *value);
 
+/*@}*/
+
+
+/**
+ * \name Initialization, state maintenance
+ */
+/*@{*/
+
+extern void 
+_mesa_update_texture( GLcontext *ctx, GLuint new_state );
+
+extern GLboolean
+_mesa_init_texture( GLcontext *ctx );
+
+extern void 
+_mesa_free_texture_data( GLcontext *ctx );
+
+/*@}*/
 
 #endif
diff --git a/src/mesa/main/texstore.c b/src/mesa/main/texstore.c
index f9afbb6b87..16dd320e82 100644
--- a/src/mesa/main/texstore.c
+++ b/src/mesa/main/texstore.c
@@ -157,7 +157,7 @@ components_in_intformat( GLint format )
  * apply pixel transfer ops into a temporary image buffer.  Then,
  * convert the temporary image into the special hardware format.
  *
- * Input:
+ * \param
  *   dimensions - 1, 2, or 3
  *   texDestFormat - GL_LUMINANCE, GL_INTENSITY, GL_LUMINANCE_ALPHA, GL_ALPHA,
  *                   GL_RGB or GL_RGBA (the destination format)
@@ -435,7 +435,7 @@ transfer_teximage(GLcontext *ctx, GLuint dimensions,
  * Transfer a texture image from user space to <destAddr> applying all
  * needed image transfer operations and storing the result in the format
  * specified by <dstFormat>.  <dstFormat> may be any format from texformat.h.
- * Input:
+ * \param
  *   dimensions - 1, 2 or 3
  *   baseInternalFormat - base format of the internal texture format
  *       specified by the user.  This is very important, see below.
@@ -445,7 +445,7 @@ transfer_teximage(GLcontext *ctx, GLuint dimensions,
  *   dstX/Y/Zoffset - as specified by glTexSubImage
  *   dstRowStride - stride between dest rows in bytes
  *   dstImageStride - stride between dest images in bytes
- *   srcFormat, srcType - incoming image format and datatype
+ *   srcFormat, srcType - incoming image format and data type
  *   srcAddr - source image address
  *   srcPacking - packing params of source image
  *
diff --git a/src/mesa/main/texstore.h b/src/mesa/main/texstore.h
index 6d3a4397b2..f6931dc5e7 100644
--- a/src/mesa/main/texstore.h
+++ b/src/mesa/main/texstore.h
@@ -1,3 +1,10 @@
+/**
+ * \file texstore.h
+ * Texture image storage.
+ *
+ * \author Brian Paul
+ */
+
 /*
  * Mesa 3-D graphics library
  * Version:  5.1
@@ -22,11 +29,6 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/*
- * Authors:
- *   Brian Paul
- */
-
 
 #ifndef TEXSTORE_H
 #define TEXSTORE_H
diff --git a/src/mesa/main/texutil.c b/src/mesa/main/texutil.c
index 19d3df1109..cf50da813a 100644
--- a/src/mesa/main/texutil.c
+++ b/src/mesa/main/texutil.c
@@ -868,7 +868,7 @@ _mesa_convert_texsubimage1d( GLint mesaFormat,
  * with the _mesa_transfer_teximage() function.  That function will also
  * do image transfer operations such as scale/bias and convolution.
  *
- * Input:
+ * \param
  *   mesaFormat - one of the MESA_FORMAT_* values from texformat.h
  *   xoffset, yoffset - position in dest image to put data
  *   width, height - incoming image size, also size of dest region.
diff --git a/src/mesa/main/texutil_tmp.h b/src/mesa/main/texutil_tmp.h
index 2dd3ccee5e..7b2ccaa1c9 100644
--- a/src/mesa/main/texutil_tmp.h
+++ b/src/mesa/main/texutil_tmp.h
@@ -1,3 +1,28 @@
+/**
+ * \file texutil_tmp.h
+ * Texture conversion templates.
+ *
+ * \author Gareth Hughes
+ *
+ * For 2D and 3D texture images, we generate functions for
+ *  - conversion without pixel unpacking and standard stride
+ *  - conversion without pixel unpacking and non-standard stride
+ *  - conversion with pixel unpacking and standard stride
+ *  - conversion with pixel unpacking and non-standard stride
+ *
+ * Macros which need to be defined before including this file:
+ *  - \c TAG(x) - the function name wrapper
+ *  - \c DST_TYPE - the destination texel data type (GLuint, GLushort, etc)
+ *  - \c DST_TEXELS_PER_DWORD - number of destination texels that'll fit in 4 bytes
+ *  - \c CONVERT_TEXEL - code to convert from source to destination texel
+ *  - \c CONVER_TEXEL_DWORD - if multiple texels fit in 4 bytes, this macros
+ *  will convert/store multiple texels at once
+ *  - \c CONVERT_DIRECT - if defined, just memcpy texels from source to destination
+ *  - \c SRC_TEXEL_BYTES - bytes per source texel
+ *  - \c PRESERVE_DST_TYPE - if defined, don't undefined these macros at end
+ *  
+ * \sa convert_func.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -21,30 +46,6 @@
  * BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- *
- * Author:
- *    Gareth Hughes
- */
-
-
-/*
- * For 2D and 3D texture images, we generate functions for
- *  - conversion without pixel unpacking and standard stride
- *  - conversion without pixel unpacking and non-standard stride
- *  - conversion with pixel unpacking and standard stride
- *  - conversion with pixel unpacking and non-standard stride
- *
- *
- * Macros which need to be defined before including this file:
- *  TAG(x)  - the function name wrapper
- *  DST_TYPE - the destination texel datatype (GLuint, GLushort, etc)
- *  DST_TEXELS_PER_DWORD - number of dest texels that'll fit in 4 bytes
- *  CONVERT_TEXEL - code to convert from source to dest texel
- *  CONVER_TEXEL_DWORD - if multiple texels fit in 4 bytes, this macros
- *                       will convert/store multiple texels at once
- *  CONVERT_DIRECT - if defined, just memcpy texels from src to dest
- *  SRC_TEXEL_BYTES - bytes per source texel
- *  PRESERVE_DST_TYPE - if defined, don't undefined these macros at end
  */
 
 
@@ -55,9 +56,17 @@
 				 convert->dstImageHeight * DST_TEXEL_BYTES)
 
 
-/* =============================================================
- * PRE: No pixelstore attribs, width == dstImageWidth.
+/***************************************************************/
+/** \name Doesn't require pixelstore attributes or stride
+ *
+ * \code width == dstImageWidth \endcode 
+ * and
+ * \code height == dstImageHeight \endcode
+ * if applicable.
  */
+/*@{*/
+
+/** \sa convert_func */
 static GLboolean
 TAG(texsubimage2d)( const struct convert_info *convert )
 {
@@ -92,8 +101,7 @@ TAG(texsubimage2d)( const struct convert_info *convert )
    return GL_TRUE;
 }
 
-/* PRE: As above, height == dstImageHeight also.
- */
+/** \sa convert_func */
 static GLboolean
 TAG(texsubimage3d)( const struct convert_info *convert )
 {
@@ -128,11 +136,20 @@ TAG(texsubimage3d)( const struct convert_info *convert )
    return GL_TRUE;
 }
 
+/*@}*/
 
 
-/* =============================================================
- * PRE: No pixelstore attribs, width != dstImageWidth.
+/***************************************************************/
+/** \name Requires stride but no pixelstore attributes
+ *
+ * \code width != dstImageWidth \endcode 
+ * or
+ * \code height != dstImageHeight \endcode
+ * if applicable.
  */
+/*@{*/
+
+/** \sa convert_func */
 static GLboolean
 TAG(texsubimage2d_stride)( const struct convert_info *convert )
 {
@@ -164,8 +181,7 @@ TAG(texsubimage2d_stride)( const struct convert_info *convert )
    return GL_TRUE;
 }
 
-/* PRE: As above, or height != dstImageHeight also.
- */
+/** \sa convert_func */
 static GLboolean
 TAG(texsubimage3d_stride)( const struct convert_info *convert )
 {
@@ -201,11 +217,20 @@ TAG(texsubimage3d_stride)( const struct convert_info *convert )
    return GL_TRUE;
 }
 
+/*@}*/
 
 
-/* =============================================================
- * PRE: Require pixelstore attribs, width == dstImageWidth.
+/***************************************************************/
+/** \name Requires pixelstore attributes but no stride.
+ *
+ * \code width == dstImageWidth \endcode 
+ * and
+ * \code height == dstImageHeight \endcode
+ * if applicable.
  */
+/*@{*/
+
+/** \sa convert_func */
 static GLboolean
 TAG(texsubimage2d_unpack)( const struct convert_info *convert )
 {
@@ -262,8 +287,7 @@ TAG(texsubimage2d_unpack)( const struct convert_info *convert )
    return GL_TRUE;
 }
 
-/* PRE: as above, height == dstImageHeight also.
- */
+/** \sa convert_func */
 static GLboolean
 TAG(texsubimage3d_unpack)( const struct convert_info *convert )
 {
@@ -334,11 +358,20 @@ TAG(texsubimage3d_unpack)( const struct convert_info *convert )
    return GL_TRUE;
 }
 
+/*@}*/
 
 
-/* =============================================================
- * PRE: Require pixelstore attribs, width != dstImageWidth.
+/***************************************************************/
+/** \name Requires pixelstore attributes and stride.
+ *
+ * \code width != dstImageWidth \endcode 
+ * or
+ * \code height != dstImageHeight \endcode
+ * if applicable.
  */
+/*@{*/
+
+/** \sa convert_func */
 static GLboolean
 TAG(texsubimage2d_stride_unpack)( const struct convert_info *convert )
 {
@@ -385,8 +418,7 @@ TAG(texsubimage2d_stride_unpack)( const struct convert_info *convert )
    return GL_TRUE;
 }
 
-/* PRE: As above, or height != dstImageHeight also.
- */
+/** \sa convert_func */
 static GLboolean
 TAG(texsubimage3d_stride_unpack)( const struct convert_info *convert )
 {
@@ -442,8 +474,19 @@ TAG(texsubimage3d_stride_unpack)( const struct convert_info *convert )
    return GL_TRUE;
 }
 
+/*@}*/
+
 
+/***********************************************************************/
+/** \name Conversion function tables
+ */
+/*@{*/
 
+/**
+ * 2D texture conversion functions table.
+ * 
+ * \sa convert_func.
+ */
 static convert_func TAG(texsubimage2d_tab)[] = {
    TAG(texsubimage2d),
    TAG(texsubimage2d_stride),
@@ -451,6 +494,11 @@ static convert_func TAG(texsubimage2d_tab)[] = {
    TAG(texsubimage2d_stride_unpack),
 };
 
+/**
+ * 3D texture conversion functions table.
+ *
+ * \sa convert_func.
+ */
 static convert_func TAG(texsubimage3d_tab)[] = {
    TAG(texsubimage3d),
    TAG(texsubimage3d_stride),
@@ -458,6 +506,8 @@ static convert_func TAG(texsubimage3d_tab)[] = {
    TAG(texsubimage3d_stride_unpack),
 };
 
+/*@}*/
+
 
 #ifndef PRESERVE_DST_TYPE
 #undef DST_TYPE
diff --git a/src/mesa/main/varray.c b/src/mesa/main/varray.c
index 0251e89ae8..07b341e68a 100644
--- a/src/mesa/main/varray.c
+++ b/src/mesa/main/varray.c
@@ -22,6 +22,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
 #include "glheader.h"
 #include "context.h"
 #include "enable.h"
@@ -36,7 +37,6 @@
 #include "math/m_translate.h"
 
 
-
 void
 _mesa_VertexPointer(GLint size, GLenum type, GLsizei stride, const GLvoid *ptr)
 {
@@ -911,3 +911,71 @@ _mesa_MultiDrawElementsEXT( GLenum mode, const GLsizei *count, GLenum type,
       }
    }
 }
+
+
+/**********************************************************************/
+/*****                      Initialization                        *****/
+/**********************************************************************/
+
+void _mesa_init_varray( GLcontext * ctx )
+{
+   int i;
+
+   /* Vertex arrays */
+   ctx->Array.Vertex.Size = 4;
+   ctx->Array.Vertex.Type = GL_FLOAT;
+   ctx->Array.Vertex.Stride = 0;
+   ctx->Array.Vertex.StrideB = 0;
+   ctx->Array.Vertex.Ptr = NULL;
+   ctx->Array.Vertex.Enabled = GL_FALSE;
+   ctx->Array.Vertex.Flags = CA_CLIENT_DATA;
+   ctx->Array.Normal.Type = GL_FLOAT;
+   ctx->Array.Normal.Stride = 0;
+   ctx->Array.Normal.StrideB = 0;
+   ctx->Array.Normal.Ptr = NULL;
+   ctx->Array.Normal.Enabled = GL_FALSE;
+   ctx->Array.Normal.Flags = CA_CLIENT_DATA;
+   ctx->Array.Color.Size = 4;
+   ctx->Array.Color.Type = GL_FLOAT;
+   ctx->Array.Color.Stride = 0;
+   ctx->Array.Color.StrideB = 0;
+   ctx->Array.Color.Ptr = NULL;
+   ctx->Array.Color.Enabled = GL_FALSE;
+   ctx->Array.Color.Flags = CA_CLIENT_DATA;
+   ctx->Array.SecondaryColor.Size = 4;
+   ctx->Array.SecondaryColor.Type = GL_FLOAT;
+   ctx->Array.SecondaryColor.Stride = 0;
+   ctx->Array.SecondaryColor.StrideB = 0;
+   ctx->Array.SecondaryColor.Ptr = NULL;
+   ctx->Array.SecondaryColor.Enabled = GL_FALSE;
+   ctx->Array.SecondaryColor.Flags = CA_CLIENT_DATA;
+   ctx->Array.FogCoord.Size = 1;
+   ctx->Array.FogCoord.Type = GL_FLOAT;
+   ctx->Array.FogCoord.Stride = 0;
+   ctx->Array.FogCoord.StrideB = 0;
+   ctx->Array.FogCoord.Ptr = NULL;
+   ctx->Array.FogCoord.Enabled = GL_FALSE;
+   ctx->Array.FogCoord.Flags = CA_CLIENT_DATA;
+   ctx->Array.Index.Type = GL_FLOAT;
+   ctx->Array.Index.Stride = 0;
+   ctx->Array.Index.StrideB = 0;
+   ctx->Array.Index.Ptr = NULL;
+   ctx->Array.Index.Enabled = GL_FALSE;
+   ctx->Array.Index.Flags = CA_CLIENT_DATA;
+   for (i = 0; i < MAX_TEXTURE_UNITS; i++) {
+      ctx->Array.TexCoord[i].Size = 4;
+      ctx->Array.TexCoord[i].Type = GL_FLOAT;
+      ctx->Array.TexCoord[i].Stride = 0;
+      ctx->Array.TexCoord[i].StrideB = 0;
+      ctx->Array.TexCoord[i].Ptr = NULL;
+      ctx->Array.TexCoord[i].Enabled = GL_FALSE;
+      ctx->Array.TexCoord[i].Flags = CA_CLIENT_DATA;
+   }
+   ctx->Array.TexCoordInterleaveFactor = 1;
+   ctx->Array.EdgeFlag.Stride = 0;
+   ctx->Array.EdgeFlag.StrideB = 0;
+   ctx->Array.EdgeFlag.Ptr = NULL;
+   ctx->Array.EdgeFlag.Enabled = GL_FALSE;
+   ctx->Array.EdgeFlag.Flags = CA_CLIENT_DATA;
+   ctx->Array.ActiveTexture = 0;   /* GL_ARB_multitexture */
+}
diff --git a/src/mesa/main/varray.h b/src/mesa/main/varray.h
index 168c17243a..58d115c287 100644
--- a/src/mesa/main/varray.h
+++ b/src/mesa/main/varray.h
@@ -1,3 +1,12 @@
+/**
+ * \file varray.h
+ * Vertex arrays.
+ *
+ * \if subset
+ * (No-op)
+ *
+ * \endif
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -30,6 +39,7 @@
 
 #include "mtypes.h"
 
+#if _HAVE_FULL_GL
 
 extern void
 _mesa_VertexPointer(GLint size, GLenum type, GLsizei stride,
@@ -124,5 +134,14 @@ extern void
 _mesa_MultiDrawElementsEXT( GLenum mode, const GLsizei *count, GLenum type,
                             const GLvoid **indices, GLsizei primcount );
 
+extern void
+_mesa_init_varray( GLcontext * ctx );
+
+#else
+
+/** No-op */
+#define _mesa_init_varray( c )  ((void)0)
+
+#endif
 
 #endif
diff --git a/src/mesa/main/vtxfmt.h b/src/mesa/main/vtxfmt.h
index 6f6006bd22..310f157b5e 100644
--- a/src/mesa/main/vtxfmt.h
+++ b/src/mesa/main/vtxfmt.h
@@ -1,3 +1,9 @@
+/**
+ * \file vtxfmt.h
+ * 
+ * \author Keith Whitwell <keith@tungstengraphics.com>
+ * \author Gareth Hughes
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -21,12 +27,9 @@
  * BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- *
- * Authors:
- *    Keith Whitwell <keith@tungstengraphics.com>
- *    Gareth Hughes
  */
 
+
 #ifndef _VTXFMT_H_
 #define _VTXFMT_H_
 
diff --git a/src/mesa/math/m_debug_xform.c b/src/mesa/math/m_debug_xform.c
index ba2701e179..e173d14bd5 100644
--- a/src/mesa/math/m_debug_xform.c
+++ b/src/mesa/math/m_debug_xform.c
@@ -105,7 +105,7 @@ static int *templates[7] = {
    m_2d_no_rot,
    m_3d
 };
-static enum matrix_type mtypes[7] = {
+static enum GLmatrixtype mtypes[7] = {
    MATRIX_GENERAL,
    MATRIX_IDENTITY,
    MATRIX_3D_NO_ROT,
diff --git a/src/mesa/math/m_matrix.c b/src/mesa/math/m_matrix.c
index e204cc7bbc..e81be8a7e0 100644
--- a/src/mesa/math/m_matrix.c
+++ b/src/mesa/math/m_matrix.c
@@ -1,3 +1,12 @@
+/**
+ * \file m_matrix.c
+ * Matrix operations.
+ *
+ * \note
+ * -# 4x4 transformation matrices are stored in memory in column major order.
+ * -# Points/vertices are to be thought of as column vectors.
+ * -# Transformation of a point p by a matrix M is: p' = M * p
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,15 +33,6 @@
  */
 
 
-/*
- * Matrix operations
- *
- * NOTES:
- * 1. 4x4 transformation matrices are stored in memory in column major order.
- * 2. Points/vertices are to be thought of as column vectors.
- * 3. Transformation of a point p by a matrix M is: p' = M * p
- */
-
 #include "glheader.h"
 #include "imports.h"
 #include "macros.h"
@@ -41,6 +41,9 @@
 #include "m_matrix.h"
 
 
+/**
+ * Names of the corresponding GLmatrixtype values.
+ */
 static const char *types[] = {
    "MATRIX_GENERAL",
    "MATRIX_IDENTITY",
@@ -52,6 +55,9 @@ static const char *types[] = {
 };
 
 
+/**
+ * Identity matrix.
+ */
 static GLfloat Identity[16] = {
    1.0, 0.0, 0.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
@@ -61,22 +67,27 @@ static GLfloat Identity[16] = {
 
 
 
+/**********************************************************************/
+/** \name Matrix multiplication */
+/*@{*/
 
-/*
- * This matmul was contributed by Thomas Malik
- *
- * Perform a 4x4 matrix multiplication  (product = a x b).
- * Input:  a, b - matrices to multiply
- * Output:  product - product of a and b
- * WARNING: (product != b) assumed
- * NOTE:    (product == a) allowed
- *
- * KW: 4*16 = 64 muls
- */
 #define A(row,col)  a[(col<<2)+row]
 #define B(row,col)  b[(col<<2)+row]
 #define P(row,col)  product[(col<<2)+row]
 
+/**
+ * Perform a full 4x4 matrix multiplication.
+ *
+ * \param a matrix.
+ * \param b matrix.
+ * \param product will receive the product of \p a and \p b.
+ *
+ * \warning Is assumed that \p product != \p b. \p product == \p a is allowed.
+ *
+ * \note KW: 4*16 = 64 multiplications
+ * 
+ * \author This \c matmul was contributed by Thomas Malik
+ */
 static void matmul4( GLfloat *product, const GLfloat *a, const GLfloat *b )
 {
    GLint i;
@@ -89,9 +100,13 @@ static void matmul4( GLfloat *product, const GLfloat *a, const GLfloat *b )
    }
 }
 
-
-/* Multiply two matrices known to occupy only the top three rows, such
- * as typical model matrices, and ortho matrices.
+/**
+ * Multiply two matrices known to occupy only the top three rows, such
+ * as typical model matrices, and orthogonal matrices.
+ *
+ * \param a matrix.
+ * \param b matrix.
+ * \param product will receive the product of \p a and \p b.
  */
 static void matmul34( GLfloat *product, const GLfloat *a, const GLfloat *b )
 {
@@ -109,14 +124,20 @@ static void matmul34( GLfloat *product, const GLfloat *a, const GLfloat *b )
    P(3,3) = 1;
 }
 
-
 #undef A
 #undef B
 #undef P
 
-
-/*
+/**
  * Multiply a matrix by an array of floats with known properties.
+ *
+ * \param mat pointer to a GLmatrix structure containing the left multiplication
+ * matrix, and that will receive the product result.
+ * \param m right multiplication matrix array.
+ * \param flags flags of the matrix \p m.
+ * 
+ * Joins both flags and marks the type and inverse as dirty.  Calls matmul34()
+ * if both matrices are 3D, or matmul4() otherwise.
  */
 static void matrix_multf( GLmatrix *mat, const GLfloat *m, GLuint flags )
 {
@@ -128,7 +149,63 @@ static void matrix_multf( GLmatrix *mat, const GLfloat *m, GLuint flags )
       matmul4( mat->m, mat->m, m );
 }
 
+/**
+ * Matrix multiplication.
+ *
+ * \param dest destination matrix.
+ * \param a left matrix.
+ * \param b right matrix.
+ * 
+ * Joins both flags and marks the type and inverse as dirty.  Calls matmul34()
+ * if both matrices are 3D, or matmul4() otherwise.
+ */
+void
+_math_matrix_mul_matrix( GLmatrix *dest, const GLmatrix *a, const GLmatrix *b )
+{
+   dest->flags = (a->flags |
+		  b->flags |
+		  MAT_DIRTY_TYPE |
+		  MAT_DIRTY_INVERSE);
 
+   if (TEST_MAT_FLAGS(dest, MAT_FLAGS_3D))
+      matmul34( dest->m, a->m, b->m );
+   else
+      matmul4( dest->m, a->m, b->m );
+}
+
+/**
+ * Matrix multiplication.
+ *
+ * \param dest left and destination matrix.
+ * \param m right matrix array.
+ * 
+ * Marks the matrix flags with general flag, and type and inverse dirty flags.
+ * Calls matmul4() for the multiplication.
+ */
+void
+_math_matrix_mul_floats( GLmatrix *dest, const GLfloat *m )
+{
+   dest->flags |= (MAT_FLAG_GENERAL |
+		   MAT_DIRTY_TYPE |
+		   MAT_DIRTY_INVERSE);
+
+   matmul4( dest->m, dest->m, m );
+}
+
+/*@}*/
+
+
+/**********************************************************************/
+/** \name Matrix output */
+/*@{*/
+
+/**
+ * Print a matrix array.
+ *
+ * \param m matrix array.
+ *
+ * Called by _math_matrix_print() to print a matrix or its inverse.
+ */
 static void print_matrix_floats( const GLfloat m[16] )
 {
    int i;
@@ -137,6 +214,11 @@ static void print_matrix_floats( const GLfloat m[16] )
    }
 }
 
+/**
+ * Dumps the contents of a GLmatrix structure.
+ * 
+ * \param m pointer to the GLmatrix structure.
+ */
 void
 _math_matrix_print( const GLmatrix *m )
 {
@@ -155,16 +237,48 @@ _math_matrix_print( const GLmatrix *m )
    }
 }
 
+/*@}*/
+
+
+/**
+ * References an element of 4x4 matrix.
+ *
+ * \param m matrix array.
+ * \param c column of the desired element.
+ * \param r row of the desired element.
+ * 
+ * \return value of the desired element.
+ *
+ * Calculate the linear storage index of the element and references it. 
+ */
+#define MAT(m,r,c) (m)[(c)*4+(r)]
 
 
+/**********************************************************************/
+/** \name Matrix inversion */
+/*@{*/
 
+/**
+ * Swaps the values of two floating pointer variables.
+ *
+ * Used by invert_matrix_general() to swap the row pointers.
+ */
 #define SWAP_ROWS(a, b) { GLfloat *_tmp = a; (a)=(b); (b)=_tmp; }
-#define MAT(m,r,c) (m)[(c)*4+(r)]
 
-/*
+/**
  * Compute inverse of 4x4 transformation matrix.
+ * 
+ * \param mat pointer to a GLmatrix structure. The matrix inverse will be
+ * stored in the GLmatrix::inv attribute.
+ * 
+ * \return GL_TRUE for success, GL_FALSE for failure (\p singular matrix).
+ * 
+ * \author
  * Code contributed by Jacques Leroy jle@star.be
- * Return GL_TRUE for success, GL_FALSE for failure (singular matrix)
+ *
+ * Calculates the inverse matrix by performing the gaussian matrix reduction
+ * with partial pivoting followed by back/substitution with the loops manually
+ * unrolled.
  */
 static GLboolean invert_matrix_general( GLmatrix *mat )
 {
@@ -279,8 +393,20 @@ static GLboolean invert_matrix_general( GLmatrix *mat )
 }
 #undef SWAP_ROWS
 
-
-/* Adapted from graphics gems II.
+/**
+ * Compute inverse of a general 3d transformation matrix.
+ * 
+ * \param mat pointer to a GLmatrix structure. The matrix inverse will be
+ * stored in the GLmatrix::inv attribute.
+ * 
+ * \return GL_TRUE for success, GL_FALSE for failure (\p singular matrix).
+ *
+ * \author Adapted from graphics gems II.
+ *
+ * Calculates the inverse of the upper left by first calculating its
+ * determinant and multiplying it to the symmetric adjust matrix of each
+ * element. Finally deals with the translation part by transforming the
+ * original translation vector using by the calculated submatrix inverse.
  */
 static GLboolean invert_matrix_3d_general( GLmatrix *mat )
 {
@@ -341,7 +467,19 @@ static GLboolean invert_matrix_3d_general( GLmatrix *mat )
    return GL_TRUE;
 }
 
-
+/**
+ * Compute inverse of a 3d transformation matrix.
+ * 
+ * \param mat pointer to a GLmatrix structure. The matrix inverse will be
+ * stored in the GLmatrix::inv attribute.
+ * 
+ * \return GL_TRUE for success, GL_FALSE for failure (\p singular matrix).
+ *
+ * If the matrix is not an angle preserving matrix then calls
+ * invert_matrix_3d_general for the actual calculation. Otherwise calculates
+ * the inverse matrix analyzing and inverting each of the scaling, rotation and
+ * translation parts.
+ */
 static GLboolean invert_matrix_3d( GLmatrix *mat )
 {
    const GLfloat *in = mat->m;
@@ -412,15 +550,32 @@ static GLboolean invert_matrix_3d( GLmatrix *mat )
    return GL_TRUE;
 }
 
-
-
+/**
+ * Compute inverse of an identity transformation matrix.
+ * 
+ * \param mat pointer to a GLmatrix structure. The matrix inverse will be
+ * stored in the GLmatrix::inv attribute.
+ * 
+ * \return always GL_TRUE.
+ *
+ * Simply copies Identity into GLmatrix::inv.
+ */
 static GLboolean invert_matrix_identity( GLmatrix *mat )
 {
    MEMCPY( mat->inv, Identity, sizeof(Identity) );
    return GL_TRUE;
 }
 
-
+/**
+ * Compute inverse of a no-rotation 3d transformation matrix.
+ * 
+ * \param mat pointer to a GLmatrix structure. The matrix inverse will be
+ * stored in the GLmatrix::inv attribute.
+ * 
+ * \return GL_TRUE for success, GL_FALSE for failure (\p singular matrix).
+ *
+ * Calculates the 
+ */
 static GLboolean invert_matrix_3d_no_rot( GLmatrix *mat )
 {
    const GLfloat *in = mat->m;
@@ -443,7 +598,17 @@ static GLboolean invert_matrix_3d_no_rot( GLmatrix *mat )
    return GL_TRUE;
 }
 
-
+/**
+ * Compute inverse of a no-rotation 2d transformation matrix.
+ * 
+ * \param mat pointer to a GLmatrix structure. The matrix inverse will be
+ * stored in the GLmatrix::inv attribute.
+ * 
+ * \return GL_TRUE for success, GL_FALSE for failure (\p singular matrix).
+ *
+ * Calculates the inverse matrix by applying the inverse scaling and
+ * translation to the identity matrix.
+ */
 static GLboolean invert_matrix_2d_no_rot( GLmatrix *mat )
 {
    const GLfloat *in = mat->m;
@@ -464,7 +629,6 @@ static GLboolean invert_matrix_2d_no_rot( GLmatrix *mat )
    return GL_TRUE;
 }
 
-
 #if 0
 /* broken */
 static GLboolean invert_matrix_perspective( GLmatrix *mat )
@@ -493,10 +657,14 @@ static GLboolean invert_matrix_perspective( GLmatrix *mat )
 }
 #endif
 
-
+/**
+ * Matrix inversion function pointer type.
+ */
 typedef GLboolean (*inv_mat_func)( GLmatrix *mat );
 
-
+/**
+ * Table of the matrix inversion functions according to the matrix type.
+ */
 static inv_mat_func inv_mat_tab[7] = {
    invert_matrix_general,
    invert_matrix_identity,
@@ -514,7 +682,18 @@ static inv_mat_func inv_mat_tab[7] = {
    invert_matrix_3d
 };
 
-
+/**
+ * Compute inverse of a transformation matrix.
+ * 
+ * \param mat pointer to a GLmatrix structure. The matrix inverse will be
+ * stored in the GLmatrix::inv attribute.
+ * 
+ * \return GL_TRUE for success, GL_FALSE for failure (\p singular matrix).
+ *
+ * Calls the matrix inversion function in inv_mat_tab corresponding to the
+ * given matrix type.  In case of failure, updates the MAT_FLAG_SINGULAR flag,
+ * and copies the identity matrix into GLmatrix::inv.
+ */
 static GLboolean matrix_invert( GLmatrix *mat )
 {
    if (inv_mat_tab[mat->type](mat)) {
@@ -527,16 +706,20 @@ static GLboolean matrix_invert( GLmatrix *mat )
    }
 }
 
+/*@}*/
 
 
+/**********************************************************************/
+/** \name Matrix generation */
+/*@{*/
 
-
-
-/*
+/**
  * Generate a 4x4 transformation matrix from glRotate parameters, and
- * postmultiply the input matrix by it.
- * This function contributed by Erich Boleyn (erich@uruk.org).
- * Optimizatios contributed by Rudolf Opalla (rudi@khm.de).
+ * post-multiply the input matrix by it.
+ *
+ * \author
+ * This function was contributed by Erich Boleyn (erich@uruk.org).
+ * Optimizations contributed by Rudolf Opalla (rudi@khm.de).
  */
 void
 _math_matrix_rotate( GLmatrix *mat,
@@ -708,8 +891,20 @@ _math_matrix_rotate( GLmatrix *mat,
    matrix_multf( mat, m, MAT_FLAG_ROTATION );
 }
 
-
-
+/**
+ * Apply a perspective projection matrix.
+ *
+ * \param mat matrix to apply the projection.
+ * \param left left clipping plane coordinate.
+ * \param right right clipping plane coordinate.
+ * \param bottom bottom clipping plane coordinate.
+ * \param top top clipping plane coordinate.
+ * \param nearval distance to the near clipping plane.
+ * \param farval distance to the far clipping plane.
+ *
+ * Creates the projection matrix and multiplies it with \p mat, marking the
+ * MAT_FLAG_PERSPECTIVE flag.
+ */
 void
 _math_matrix_frustum( GLmatrix *mat,
 		      GLfloat left, GLfloat right,
@@ -736,6 +931,20 @@ _math_matrix_frustum( GLmatrix *mat,
    matrix_multf( mat, m, MAT_FLAG_PERSPECTIVE );
 }
 
+/**
+ * Apply an orthographic projection matrix.
+ *
+ * \param mat matrix to apply the projection.
+ * \param left left clipping plane coordinate.
+ * \param right right clipping plane coordinate.
+ * \param bottom bottom clipping plane coordinate.
+ * \param top top clipping plane coordinate.
+ * \param nearval distance to the near clipping plane.
+ * \param farval distance to the far clipping plane.
+ *
+ * Creates the projection matrix and multiplies it with \p mat, marking the
+ * MAT_FLAG_GENERAL_SCALE and MAT_FLAG_TRANSLATION flags.
+ */
 void
 _math_matrix_ortho( GLmatrix *mat,
 		    GLfloat left, GLfloat right,
@@ -763,6 +972,91 @@ _math_matrix_ortho( GLmatrix *mat,
    matrix_multf( mat, m, (MAT_FLAG_GENERAL_SCALE|MAT_FLAG_TRANSLATION));
 }
 
+/**
+ * Multiply a matrix with a general scaling matrix.
+ *
+ * \param mat matrix.
+ * \param x x axis scale factor.
+ * \param y y axis scale factor.
+ * \param z z axis scale factor.
+ *
+ * Multiplies in-place the elements of \p mat by the scale factors. Checks if
+ * the scales factors are roughly the same, marking the MAT_FLAG_UNIFORM_SCALE
+ * flag, or MAT_FLAG_GENERAL_SCALE. Marks the MAT_DIRTY_TYPE and
+ * MAT_DIRTY_INVERSE dirty flags.
+ */
+void
+_math_matrix_scale( GLmatrix *mat, GLfloat x, GLfloat y, GLfloat z )
+{
+   GLfloat *m = mat->m;
+   m[0] *= x;   m[4] *= y;   m[8]  *= z;
+   m[1] *= x;   m[5] *= y;   m[9]  *= z;
+   m[2] *= x;   m[6] *= y;   m[10] *= z;
+   m[3] *= x;   m[7] *= y;   m[11] *= z;
+
+   if (fabs(x - y) < 1e-8 && fabs(x - z) < 1e-8)
+      mat->flags |= MAT_FLAG_UNIFORM_SCALE;
+   else
+      mat->flags |= MAT_FLAG_GENERAL_SCALE;
+
+   mat->flags |= (MAT_DIRTY_TYPE |
+		  MAT_DIRTY_INVERSE);
+}
+
+/**
+ * Multiply a matrix with a translation matrix.
+ *
+ * \param mat matrix.
+ * \param x translation vector x coordinate.
+ * \param y translation vector y coordinate.
+ * \param z translation vector z coordinate.
+ *
+ * Adds the translation coordinates to the elements of \p mat in-place.  Marks
+ * the MAT_FLAG_TRANSLATION flag, and the MAT_DIRTY_TYPE and MAT_DIRTY_INVERSE
+ * dirty flags.
+ */
+void
+_math_matrix_translate( GLmatrix *mat, GLfloat x, GLfloat y, GLfloat z )
+{
+   GLfloat *m = mat->m;
+   m[12] = m[0] * x + m[4] * y + m[8]  * z + m[12];
+   m[13] = m[1] * x + m[5] * y + m[9]  * z + m[13];
+   m[14] = m[2] * x + m[6] * y + m[10] * z + m[14];
+   m[15] = m[3] * x + m[7] * y + m[11] * z + m[15];
+
+   mat->flags |= (MAT_FLAG_TRANSLATION |
+		  MAT_DIRTY_TYPE |
+		  MAT_DIRTY_INVERSE);
+}
+
+/**
+ * Set a matrix to the identity matrix.
+ *
+ * \param mat matrix.
+ *
+ * Copies ::Identity into \p GLmatrix::m, and into GLmatrix::inv if not NULL.
+ * Sets the matrix type to identity, and clear the dirty flags.
+ */
+void
+_math_matrix_set_identity( GLmatrix *mat )
+{
+   MEMCPY( mat->m, Identity, 16*sizeof(GLfloat) );
+
+   if (mat->inv)
+      MEMCPY( mat->inv, Identity, 16*sizeof(GLfloat) );
+
+   mat->type = MATRIX_IDENTITY;
+   mat->flags &= ~(MAT_DIRTY_FLAGS|
+		   MAT_DIRTY_TYPE|
+		   MAT_DIRTY_INVERSE);
+}
+
+/*@}*/
+
+
+/**********************************************************************/
+/** \name Matrix analysis */
+/*@{*/
 
 #define ZERO(x) (1<<x)
 #define ONE(x)  (1<<(x+16))
@@ -804,8 +1098,12 @@ _math_matrix_ortho( GLmatrix *mat,
 
 #define SQ(x) ((x)*(x))
 
-/* Determine type and flags from scratch.  This is expensive enough to
- * only want to do it once.
+/**
+ * Determine type and flags from scratch.  
+ *
+ * \param mat matrix.
+ * 
+ * This is expensive enough to only want to do it once.
  */
 static void analyse_from_scratch( GLmatrix *mat )
 {
@@ -915,9 +1213,10 @@ static void analyse_from_scratch( GLmatrix *mat )
    }
 }
 
-
-/* Analyse a matrix given that its flags are accurate - this is the
- * more common operation, hopefully.
+/**
+ * Analyze a matrix given that its flags are accurate.
+ * 
+ * This is the more common operation, hopefully.
  */
 static void analyse_from_flags( GLmatrix *mat )
 {
@@ -957,7 +1256,16 @@ static void analyse_from_flags( GLmatrix *mat )
    }
 }
 
-
+/**
+ * Analyze and update a matrix.
+ *
+ * \param mat matrix.
+ *
+ * If the matrix type is dirty then calls either analyse_from_scratch() or
+ * analyse_from_flags() to determine its type, according to whether the flags
+ * are dirty or not, respectively. If the matrix has an inverse and it's dirty
+ * then calls matrix_invert(). Finally clears the dirty flags.
+ */
 void
 _math_matrix_analyse( GLmatrix *mat )
 {
@@ -977,7 +1285,21 @@ _math_matrix_analyse( GLmatrix *mat )
 		   MAT_DIRTY_INVERSE);
 }
 
+/*@}*/
+
 
+/**********************************************************************/
+/** \name Matrix setup */
+/*@{*/
+
+/**
+ * Copy a matrix.
+ *
+ * \param to destination matrix.
+ * \param from source matrix.
+ *
+ * Copies all fields in GLmatrix, creating an inverse array if necessary.
+ */
 void
 _math_matrix_copy( GLmatrix *to, const GLmatrix *from )
 {
@@ -995,41 +1317,15 @@ _math_matrix_copy( GLmatrix *to, const GLmatrix *from )
    }
 }
 
-
-void
-_math_matrix_scale( GLmatrix *mat, GLfloat x, GLfloat y, GLfloat z )
-{
-   GLfloat *m = mat->m;
-   m[0] *= x;   m[4] *= y;   m[8]  *= z;
-   m[1] *= x;   m[5] *= y;   m[9]  *= z;
-   m[2] *= x;   m[6] *= y;   m[10] *= z;
-   m[3] *= x;   m[7] *= y;   m[11] *= z;
-
-   if (fabs(x - y) < 1e-8 && fabs(x - z) < 1e-8)
-      mat->flags |= MAT_FLAG_UNIFORM_SCALE;
-   else
-      mat->flags |= MAT_FLAG_GENERAL_SCALE;
-
-   mat->flags |= (MAT_DIRTY_TYPE |
-		  MAT_DIRTY_INVERSE);
-}
-
-
-void
-_math_matrix_translate( GLmatrix *mat, GLfloat x, GLfloat y, GLfloat z )
-{
-   GLfloat *m = mat->m;
-   m[12] = m[0] * x + m[4] * y + m[8]  * z + m[12];
-   m[13] = m[1] * x + m[5] * y + m[9]  * z + m[13];
-   m[14] = m[2] * x + m[6] * y + m[10] * z + m[14];
-   m[15] = m[3] * x + m[7] * y + m[11] * z + m[15];
-
-   mat->flags |= (MAT_FLAG_TRANSLATION |
-		  MAT_DIRTY_TYPE |
-		  MAT_DIRTY_INVERSE);
-}
-
-
+/**
+ * Loads a matrix array into GLmatrix.
+ * 
+ * \param m matrix array.
+ * \param mat matrix.
+ *
+ * Copies \p m into GLmatrix::m and marks the MAT_FLAG_GENERAL and MAT_DIRTY
+ * flags.
+ */
 void
 _math_matrix_loadf( GLmatrix *mat, const GLfloat *m )
 {
@@ -1037,6 +1333,13 @@ _math_matrix_loadf( GLmatrix *mat, const GLfloat *m )
    mat->flags = (MAT_FLAG_GENERAL | MAT_DIRTY);
 }
 
+/**
+ * Matrix constructor.
+ *
+ * \param m matrix.
+ *
+ * Initialize the GLmatrix fields.
+ */
 void
 _math_matrix_ctr( GLmatrix *m )
 {
@@ -1048,6 +1351,13 @@ _math_matrix_ctr( GLmatrix *m )
    m->flags = 0;
 }
 
+/**
+ * Matrix destructor.
+ *
+ * \param m matrix.
+ *
+ * Frees the data in a GLmatrix.
+ */
 void
 _math_matrix_dtr( GLmatrix *m )
 {
@@ -1061,7 +1371,13 @@ _math_matrix_dtr( GLmatrix *m )
    }
 }
 
-
+/**
+ * Allocate a matrix inverse.
+ *
+ * \param m matrix.
+ *
+ * Allocates the matrix inverse, GLmatrix::inv, and sets it to Identity.
+ */
 void
 _math_matrix_alloc_inv( GLmatrix *m )
 {
@@ -1072,48 +1388,19 @@ _math_matrix_alloc_inv( GLmatrix *m )
    }
 }
 
-
-void
-_math_matrix_mul_matrix( GLmatrix *dest, const GLmatrix *a, const GLmatrix *b )
-{
-   dest->flags = (a->flags |
-		  b->flags |
-		  MAT_DIRTY_TYPE |
-		  MAT_DIRTY_INVERSE);
-
-   if (TEST_MAT_FLAGS(dest, MAT_FLAGS_3D))
-      matmul34( dest->m, a->m, b->m );
-   else
-      matmul4( dest->m, a->m, b->m );
-}
-
-
-void
-_math_matrix_mul_floats( GLmatrix *dest, const GLfloat *m )
-{
-   dest->flags |= (MAT_FLAG_GENERAL |
-		   MAT_DIRTY_TYPE |
-		   MAT_DIRTY_INVERSE);
-
-   matmul4( dest->m, dest->m, m );
-}
-
-void
-_math_matrix_set_identity( GLmatrix *mat )
-{
-   MEMCPY( mat->m, Identity, 16*sizeof(GLfloat) );
-
-   if (mat->inv)
-      MEMCPY( mat->inv, Identity, 16*sizeof(GLfloat) );
-
-   mat->type = MATRIX_IDENTITY;
-   mat->flags &= ~(MAT_DIRTY_FLAGS|
-		   MAT_DIRTY_TYPE|
-		   MAT_DIRTY_INVERSE);
-}
+/*@}*/
 
 
+/**********************************************************************/
+/** \name Matrix transpose */
+/*@{*/
 
+/**
+ * Transpose a GLfloat matrix.
+ *
+ * \param to destination array.
+ * \param from source array.
+ */
 void
 _math_transposef( GLfloat to[16], const GLfloat from[16] )
 {
@@ -1135,7 +1422,12 @@ _math_transposef( GLfloat to[16], const GLfloat from[16] )
    to[15] = from[15];
 }
 
-
+/**
+ * Transpose a GLdouble matrix.
+ *
+ * \param to destination array.
+ * \param from source array.
+ */
 void
 _math_transposed( GLdouble to[16], const GLdouble from[16] )
 {
@@ -1157,6 +1449,12 @@ _math_transposed( GLdouble to[16], const GLdouble from[16] )
    to[15] = from[15];
 }
 
+/**
+ * Transpose a GLdouble matrix and convert to GLfloat.
+ *
+ * \param to destination array.
+ * \param from source array.
+ */
 void
 _math_transposefd( GLfloat to[16], const GLdouble from[16] )
 {
@@ -1177,3 +1475,6 @@ _math_transposefd( GLfloat to[16], const GLdouble from[16] )
    to[14] = (GLfloat) from[11];
    to[15] = (GLfloat) from[15];
 }
+
+/*@}*/
+
diff --git a/src/mesa/math/m_matrix.h b/src/mesa/math/m_matrix.h
index 00bfcf8d16..96f5649ee8 100644
--- a/src/mesa/math/m_matrix.h
+++ b/src/mesa/math/m_matrix.h
@@ -1,3 +1,7 @@
+/**
+ * \file math/m_matrix.h
+ * Defines basic structures for matrix-handling.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -23,27 +27,25 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/**
- * \file math/m_matrix.h
- * \brief Defines basic structures for matrix-handling.
- */
-
 
 #ifndef _M_MATRIX_H
 #define _M_MATRIX_H
 
 
 
-/* Give symbolic names to some of the entries in the matrix to help
- * out with the rework of the viewport_map as a matrix transform.
+/**
+ * \name Symbolic names to some of the entries in the matrix
+ *
+ * To help out with the rework of the viewport_map as a matrix transform.
  */
+/*@{*/
 #define MAT_SX 0
 #define MAT_SY 5
 #define MAT_SZ 10
 #define MAT_TX 12
 #define MAT_TY 13
 #define MAT_TZ 14
-
+/*@}*/
 
 /**
  * \defgroup MatFlags MAT_FLAG_XXX-flags
@@ -52,34 +54,40 @@
  * GLmatrix::flags
  */
 /*@{*/
-#define MAT_FLAG_IDENTITY       0
-#define MAT_FLAG_GENERAL        0x1
-#define MAT_FLAG_ROTATION       0x2
-#define MAT_FLAG_TRANSLATION    0x4
-#define MAT_FLAG_UNIFORM_SCALE  0x8
-#define MAT_FLAG_GENERAL_SCALE  0x10
-#define MAT_FLAG_GENERAL_3D     0x20
-#define MAT_FLAG_PERSPECTIVE    0x40
-#define MAT_FLAG_SINGULAR       0x80
-#define MAT_DIRTY_TYPE          0x100
-#define MAT_DIRTY_FLAGS         0x200
-#define MAT_DIRTY_INVERSE       0x400
-/*@}*/
-
 
+#define MAT_FLAG_IDENTITY       0	/**< is an identity matrix flag.
+					 *   (Not actually used - the identity
+					 *   matrix is identified by the absense
+					 /   of all other flags.) */
+#define MAT_FLAG_GENERAL        0x1	/**< is a general matrix flag */
+#define MAT_FLAG_ROTATION       0x2	/**< is a rotation matrix flag */
+#define MAT_FLAG_TRANSLATION    0x4	/**< is a translation matrix flag */
+#define MAT_FLAG_UNIFORM_SCALE  0x8	/**< is an uniform scaling matrix flag */
+#define MAT_FLAG_GENERAL_SCALE  0x10	/**< is a general scaling matrix flag */
+#define MAT_FLAG_GENERAL_3D     0x20	/**< general 3D matrix flag */
+#define MAT_FLAG_PERSPECTIVE    0x40	/**< is a perspective projection matrix flag */
+#define MAT_FLAG_SINGULAR       0x80	/**< is a singular matrix flag */
+#define MAT_DIRTY_TYPE          0x100	/**< matrix type is dirty */
+#define MAT_DIRTY_FLAGS         0x200	/**< matrix flags are dirty */
+#define MAT_DIRTY_INVERSE       0x400	/**< matrix inverse is dirty */
+
+/** angle preserving matrix flags mask */
 #define MAT_FLAGS_ANGLE_PRESERVING (MAT_FLAG_ROTATION | \
 				    MAT_FLAG_TRANSLATION | \
 				    MAT_FLAG_UNIFORM_SCALE)
 
+/** length preserving matrix flags mask */
 #define MAT_FLAGS_LENGTH_PRESERVING (MAT_FLAG_ROTATION | \
 				     MAT_FLAG_TRANSLATION)
 
+/** 3D (non-perspective) matrix flags mask */
 #define MAT_FLAGS_3D (MAT_FLAG_ROTATION | \
 		      MAT_FLAG_TRANSLATION | \
 		      MAT_FLAG_UNIFORM_SCALE | \
 		      MAT_FLAG_GENERAL_SCALE | \
 		      MAT_FLAG_GENERAL_3D)
 
+/** geometry related matrix flags mask */
 #define MAT_FLAGS_GEOMETRY (MAT_FLAG_GENERAL | \
 			    MAT_FLAG_ROTATION | \
 			    MAT_FLAG_TRANSLATION | \
@@ -89,31 +97,49 @@
 			    MAT_FLAG_PERSPECTIVE | \
 	                    MAT_FLAG_SINGULAR)
 
+/** dirty matrix flags mask */
 #define MAT_DIRTY          (MAT_DIRTY_TYPE | \
 			    MAT_DIRTY_FLAGS | \
 			    MAT_DIRTY_INVERSE)
 
+/*@}*/
+
+
+/** 
+ * Test geometry related matrix flags.
+ * 
+ * \param mat a pointer to a GLmatrix structure.
+ * \param a flags mask.
+ *
+ * \returns non-zero if all geometry related matrix flags are contained within
+ * the mask, or zero otherwise.
+ */ 
 #define TEST_MAT_FLAGS(mat, a)  \
     ((MAT_FLAGS_GEOMETRY & (~(a)) & ((mat)->flags) ) == 0)
 
 
-enum matrix_type {
-   MATRIX_GENERAL,	/**< general 4x4 matrix */
-   MATRIX_IDENTITY,   /**< identity matrix */
-   MATRIX_3D_NO_ROT,	/**< ortho projection and others... */
-   MATRIX_PERSPECTIVE,/**< perspective projection matrix */
-   MATRIX_2D, 	/**< 2-D transformation */
-   MATRIX_2D_NO_ROT,	/**< 2-D scale & translate only */
-   MATRIX_3D  	/**< 3-D transformation */
-};
+/**
+ * Different kinds of 4x4 transformation matrices.
+ */
+enum GLmatrixtype {
+	MATRIX_GENERAL,		/**< general 4x4 matrix */
+	MATRIX_IDENTITY,	/**< identity matrix */
+	MATRIX_3D_NO_ROT,	/**< orthogonal projection and others... */
+	MATRIX_PERSPECTIVE,	/**< perspective projection matrix */
+	MATRIX_2D,		/**< 2-D transformation */
+	MATRIX_2D_NO_ROT,	/**< 2-D scale & translate only */
+	MATRIX_3D		/**< 3-D transformation */
+} ;
 
+/**
+ * Matrix.
+ */
 typedef struct {
-   GLfloat *m;		/* 16-byte aligned */
-   GLfloat *inv;	/* optional, 16-byte aligned */
+   GLfloat *m;		/**< matrix, 16-byte aligned */
+   GLfloat *inv;	/**< optional inverse, 16-byte aligned */
    GLuint flags;        /**< possible values determined by (of \link
 			   MatFlags MAT_FLAG_* flags\endlink) */
-
-   enum matrix_type type;
+   enum GLmatrixtype type;
 } GLmatrix;
 
 
@@ -173,9 +199,11 @@ _math_matrix_print( const GLmatrix *m );
 
 
 
-
-/* Related functions that don't actually operate on GLmatrix structs:
+/**
+ * \name Related functions that don't actually operate on GLmatrix structs
  */
+/*@{*/
+
 extern void
 _math_transposef( GLfloat to[16], const GLfloat from[16] );
 
@@ -186,6 +214,35 @@ extern void
 _math_transposefd( GLfloat to[16], const GLdouble from[16] );
 
 
+/*
+ * Transform a point (column vector) by a matrix:   Q = M * P
+ */
+#define TRANSFORM_POINT( Q, M, P )					\
+   Q[0] = M[0] * P[0] + M[4] * P[1] + M[8] *  P[2] + M[12] * P[3];	\
+   Q[1] = M[1] * P[0] + M[5] * P[1] + M[9] *  P[2] + M[13] * P[3];	\
+   Q[2] = M[2] * P[0] + M[6] * P[1] + M[10] * P[2] + M[14] * P[3];	\
+   Q[3] = M[3] * P[0] + M[7] * P[1] + M[11] * P[2] + M[15] * P[3];
+
+
+#define TRANSFORM_POINT3( Q, M, P )				\
+   Q[0] = M[0] * P[0] + M[4] * P[1] + M[8] *  P[2] + M[12];	\
+   Q[1] = M[1] * P[0] + M[5] * P[1] + M[9] *  P[2] + M[13];	\
+   Q[2] = M[2] * P[0] + M[6] * P[1] + M[10] * P[2] + M[14];	\
+   Q[3] = M[3] * P[0] + M[7] * P[1] + M[11] * P[2] + M[15];
+
+
+/*
+ * Transform a normal (row vector) by a matrix:  [NX NY NZ] = N * MAT
+ */
+#define TRANSFORM_NORMAL( TO, N, MAT )				\
+do {								\
+   TO[0] = N[0] * MAT[0] + N[1] * MAT[1] + N[2] * MAT[2];	\
+   TO[1] = N[0] * MAT[4] + N[1] * MAT[5] + N[2] * MAT[6];	\
+   TO[2] = N[0] * MAT[8] + N[1] * MAT[9] + N[2] * MAT[10];	\
+} while (0)
+
+
+/*@}*/
 
 
 #endif
diff --git a/src/mesa/math/mathmod.h b/src/mesa/math/mathmod.h
index 35f6671f2d..6fbaaea94b 100644
--- a/src/mesa/math/mathmod.h
+++ b/src/mesa/math/mathmod.h
@@ -23,6 +23,16 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
+/**
+ * \mainpage Mesa Math Module
+ *
+ * This module contains math-related utility functions for transforming
+ * vertices, translating arrays of numbers from one data type to another,
+ * evaluating curved surfaces, etc.
+ */
+
+
 #ifndef _MESA_MATH_H_
 #define _MESA_MATH_H_
 
diff --git a/src/mesa/tnl/t_imm_exec.c b/src/mesa/tnl/t_imm_exec.c
index 0fec5d4cd4..c71c2da1a0 100644
--- a/src/mesa/tnl/t_imm_exec.c
+++ b/src/mesa/tnl/t_imm_exec.c
@@ -254,7 +254,7 @@ static void _tnl_vb_bind_immediate( GLcontext *ctx, struct immediate *IM )
 
 /*     _tnl_print_vert_flags("copy-orflag", IM->CopyOrFlag); */
 /*     _tnl_print_vert_flags("orflag", IM->OrFlag); */
-/*     _tnl_print_vert_flags("inputs", inputs); */
+/*      _tnl_print_vert_flags("inputs", inputs);  */
 
    /* Setup the initial values of array pointers in the vb.
     */
diff --git a/src/mesa/tnl/t_vb_lighttmp.h b/src/mesa/tnl/t_vb_lighttmp.h
index c0ef45ccef..5ddac76862 100644
--- a/src/mesa/tnl/t_vb_lighttmp.h
+++ b/src/mesa/tnl/t_vb_lighttmp.h
@@ -80,7 +80,7 @@
 
 
 /* define TRACE if to trace lighting code */
-
+/* #define TRACE 1 */
 
 /*
  * ctx is the current context
diff --git a/src/mesa/tnl/t_vb_normals.c b/src/mesa/tnl/t_vb_normals.c
index 4cf4bb65c7..22c9729143 100644
--- a/src/mesa/tnl/t_vb_normals.c
+++ b/src/mesa/tnl/t_vb_normals.c
@@ -87,7 +87,6 @@ static GLboolean run_validate_normal_stage( GLcontext *ctx,
 {
    struct normal_stage_data *store = NORMAL_STAGE_DATA(stage);
 
-   ASSERT(ctx->_NeedNormals);
 
    if (ctx->_NeedEyeCoords) {
       GLuint transform = NORM_TRANSFORM_NO_ROT;
@@ -136,7 +135,9 @@ static GLboolean run_validate_normal_stage( GLcontext *ctx,
 static void check_normal_transform( GLcontext *ctx,
 				    struct gl_pipeline_stage *stage )
 {
-   stage->active = ctx->_NeedNormals && !ctx->VertexProgram.Enabled;
+   stage->active = !ctx->VertexProgram.Enabled &&
+      (ctx->Light.Enabled || (ctx->Texture._GenFlags & TEXGEN_NEED_NORMALS));
+
    /* Don't clobber the initialize function:
     */
    if (stage->privatePtr)