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

1 files changed, 492 insertions, 240 deletions

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;