From bafbdcb7034cedbb9e517224c754d2d7d2f595c4 Mon Sep 17 00:00:00 2001
From: Jose Fonseca <j_r_fonseca@yahoo.co.uk>
Date: Sun, 9 Mar 2003 10:52:20 +0000
Subject: [PATCH] Doxygen documentation additions and fixes

---
 src/mesa/main/context.c  | 283 ++++++++++++++++++++++++++++++++++-----
 src/mesa/main/dd.h       |  11 +-
 src/mesa/main/dlist.c    |  10 +-
 src/mesa/main/eval.c     |  10 +-
 src/mesa/main/image.c    |  10 +-
 src/mesa/main/imports.c  |   6 +-
 src/mesa/main/rastpos.c  |  12 +-
 src/mesa/main/teximage.c |  14 +-
 src/mesa/main/texobj.c   | 186 ++++++++++++++++++-------
 src/mesa/main/texstore.c |   6 +-
 src/mesa/main/texutil.c  |   4 +-
 11 files changed, 432 insertions(+), 120 deletions(-)

diff --git a/src/mesa/main/context.c b/src/mesa/main/context.c
index 4ae19f99567..b49235bbaf7 100644
--- a/src/mesa/main/context.c
+++ b/src/mesa/main/context.c
@@ -28,7 +28,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: context.c,v 1.188.2.1.2.6 2003/03/05 14:22:21 keithw Exp $ */
+/* $Id: context.c,v 1.188.2.1.2.7 2003/03/09 10:52:20 jrfonseca Exp $ */
 
 /**
  * \mainpage Mesa Core Module
@@ -134,8 +134,15 @@ free_shared_state( GLcontext *ctx, struct gl_shared_state *ss );
 /*@{*/
 
 /**
- * Called by window system/device driver (via gc->exports.destroyCurrent())
- * when the rendering context is to be destroyed.
+ * \brief Destroy context callback.
+ * 
+ * \param gc context.
+ * \return GL_TRUE on success, or GL_FALSE on failure.
+ * 
+ * Called by window system/device driver (via __GLexports::destroyCurrent) when
+ * the rendering context is to be destroyed.
+ *
+ * Frees the context data and the context structure.
  */
 GLboolean
 _mesa_destroyContext(__GLcontext *gc)
@@ -148,8 +155,15 @@ _mesa_destroyContext(__GLcontext *gc)
 }
 
 /**
- * Called by window system/device driver (via gc->exports.loseCurrent())
+ * \brief Unbind context callback.
+ * 
+ * \param gc context.
+ * \return GL_TRUE on success, or GL_FALSE on failure.
+ *
+ * Called by window system/device driver (via __GLexports::loseCurrent)
  * when the rendering context is made non-current.
+ *
+ * No-op.
  */
 GLboolean
 _mesa_loseCurrent(__GLcontext *gc)
@@ -159,8 +173,15 @@ _mesa_loseCurrent(__GLcontext *gc)
 }
 
 /**
- * Called by window system/device driver (via gc->exports.makeCurrent())
+ * \brief Bind context callback.
+ * 
+ * \param gc context.
+ * \return GL_TRUE on success, or GL_FALSE on failure.
+ *
+ * Called by window system/device driver (via __GLexports::makeCurrent)
  * when the rendering context is made current.
+ *
+ * No-op.
  */
 GLboolean
 _mesa_makeCurrent(__GLcontext *gc)
@@ -170,8 +191,12 @@ _mesa_makeCurrent(__GLcontext *gc)
 }
 
 /**
- * Called by window system/device driver - yadda, yadda, yadda.
- * See above comments.
+ * \brief Share context callback.
+ * 
+ * \param gc context.
+ * \return GL_TRUE on success, or GL_FALSE on failure.
+ *
+ * Called by window system/device driver (via __GLexports::shareContext)
  */
 GLboolean
 _mesa_shareContext(__GLcontext *gc, __GLcontext *gcShare)
@@ -190,6 +215,9 @@ _mesa_shareContext(__GLcontext *gc, __GLcontext *gcShare)
    }
 }
 
+/**
+ * \brief Copy context callback.
+ */
 GLboolean
 _mesa_copyContext(__GLcontext *dst, const __GLcontext *src, GLuint mask)
 {
@@ -202,12 +230,19 @@ _mesa_copyContext(__GLcontext *dst, const __GLcontext *src, GLuint mask)
    }
 }
 
+/** No-op. */
 GLboolean
 _mesa_forceCurrent(__GLcontext *gc)
 {
    return GL_TRUE;
 }
 
+/**
+ * \brief Windows/buffer resizing notification callback.
+ *
+ * \param gc GL context.
+ * \return GL_TRUE on success, or GL_FALSE on failure.
+ */
 GLboolean
 _mesa_notifyResize(__GLcontext *gc)
 {
@@ -222,7 +257,13 @@ _mesa_notifyResize(__GLcontext *gc)
 }
 
 /**
+ * \brief 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)
@@ -231,6 +272,10 @@ _mesa_notifyDestroy(__GLcontext *gc)
 }
 
 /**
+ * \brief Swap buffers notification callback.
+ * 
+ * \param gc GL context.
+ *
  * Called by window system just before swapping buffers.
  * We have to finish any pending rendering.
  */
@@ -240,17 +285,20 @@ _mesa_notifySwapBuffers(__GLcontext *gc)
    FLUSH_VERTICES( gc, 0 );
 }
 
+/** \brief No-op. */
 struct __GLdispatchStateRec *
 _mesa_dispatchExec(__GLcontext *gc)
 {
    return NULL;
 }
 
+/** \brief No-op. */
 void
 _mesa_beginDispatchOverride(__GLcontext *gc)
 {
 }
 
+/** \brief No-op. */
 void
 _mesa_endDispatchOverride(__GLcontext *gc)
 {
@@ -330,15 +378,15 @@ __glCoreNopDispatch(void)
 /**
  * \brief Allocate a new GLvisual object.
  * 
- * \param rgbFlag GL_TRUE=RGB(A) mode, GL_FALSE=Color Index mode
- * \param dbFlag double buffering?
- * \param stereoFlag stereo buffer?
+ * \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 accumBits requested minimum bits per accum buffer component
- * \param indexBits number of bits per pixel if rgbFlag==GL_FALSE
+ * \param indexBits number of bits per pixel if \p rgbFlag is GL_FALSE
  * \param red number of bits per color component in frame buffer for RGB(A)
  * mode.  We always use 8 in core Mesa though.
  * \param green same as above.
@@ -347,6 +395,9 @@ __glCoreNopDispatch(void)
  * 
  * \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,
@@ -385,7 +436,10 @@ _mesa_create_visual( GLboolean rgbFlag,
  * 
  * \return GL_TRUE on success, or GL_FALSE on failure.
  *
- * \sa see _mesa_create_visual() above.
+ * \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,
@@ -462,6 +516,13 @@ _mesa_initialize_visual( GLvisual *vis,
    return GL_TRUE;
 }
 
+/**
+ * \brief Destroy a visual.
+ *
+ * \param vis visual.
+ * 
+ * Frees the visual structure.
+ */
 void
 _mesa_destroy_visual( GLvisual *vis )
 {
@@ -489,6 +550,9 @@ _mesa_destroy_visual( GLvisual *vis )
  * \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,
@@ -510,7 +574,10 @@ _mesa_create_framebuffer( const GLvisual *visual,
 /**
  * \brief Initialize a GLframebuffer object.
  * 
- * \sa _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,
@@ -550,9 +617,10 @@ _mesa_initialize_framebuffer( GLframebuffer *buffer,
    buffer->UseSoftwareAlphaBuffers = softwareAlpha;
 }
 
-
 /**
  * \brief Free a framebuffer struct and its buffers.
+ *
+ * Calls _mesa_free_framebuffer_data() and frees the structure.
  */
 void
 _mesa_destroy_framebuffer( GLframebuffer *buffer )
@@ -563,9 +631,12 @@ _mesa_destroy_framebuffer( GLframebuffer *buffer )
    }
 }
 
-
 /**
  * \brief 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 )
@@ -607,14 +678,29 @@ _mesa_free_framebuffer_data( GLframebuffer *buffer )
 
 
 /**********************************************************************/
-/** \name Context allocation, initialization, destroying       *****/
+/** \name Context allocation, initialization, destroying              */
 /**********************************************************************/
+/**
+ * The purpose of the most initalization functions here is to provide the
+ * default state values according to the OpenGL specification.
+ */
 /*@{*/
 
+/**
+ * \brief One-time initalization mutex lock.
+ *
+ * \sa Used by one_time_init().
+ */
 _glthread_DECLARE_STATIC_MUTEX(OneTimeLock);
 
 /**
- * \brief This function just calls all the various one-time-init functions in Mesa.
+ * \brief Calls all the various one-time-init functions in Mesa.
+ *
+ * While holding the OneTimeLock 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() and _mesa_init_math().
  */
 static void
 one_time_init( GLcontext *ctx )
@@ -663,6 +749,17 @@ one_time_init( GLcontext *ctx )
    _glthread_UNLOCK_MUTEX(OneTimeLock);
 }
 
+/**
+ * \brief 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 )
@@ -681,6 +778,14 @@ init_matrix_stack( struct matrix_stack *stack,
    stack->Top = stack->Stack;
 }
 
+/**
+ * \brief 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 )
 {
@@ -694,6 +799,13 @@ free_matrix_stack( struct matrix_stack *stack )
 
 /**
  * \brief 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 returing NULL.
  */
 static struct gl_shared_state *
 alloc_shared_state( void )
@@ -775,6 +887,15 @@ alloc_shared_state( void )
 
 /**
  * \brief 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 )
@@ -818,9 +939,11 @@ free_shared_state( GLcontext *ctx, struct gl_shared_state *ss )
 }
 
 /**
- * \brief Initialize the n-th light.  
+ * \brief Initialize the n-th light data structure.
  *
- * Note that the defaults for light 0 are different than the other lights.
+ * \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 )
@@ -848,6 +971,11 @@ init_light( struct gl_light *l, GLuint n )
    l->Enabled = GL_FALSE;
 }
 
+/**
+ * \brief 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 )
 {
@@ -857,6 +985,11 @@ init_lightmodel( struct gl_lightmodel *lm )
    lm->ColorControl = GL_SINGLE_COLOR;
 }
 
+/**
+ * \brief Initalize the material data structure.
+ * 
+ * \param m pointer to the gl_material structure to be initialized.
+ */
 static void
 init_material( struct gl_material *m )
 {
@@ -870,6 +1003,12 @@ init_material( struct gl_material *m )
    m->SpecularIndex = 1;
 }
 
+/**
+ * \brief Initalize a texture unit.
+ *
+ * \param ctx GL context.
+ * \param unit texture unit number to be initialized.
+ */
 static void
 init_texture_unit( GLcontext *ctx, GLuint unit )
 {
@@ -961,7 +1100,12 @@ init_2d_map( struct gl_2d_map *map, int n, const float *initial )
 }
 
 /**
- * \brief Initialize the attribute groups in a GLcontext.
+ * \brief Initialize the attribute groups in a GL context.
+ *
+ * \param ctx GL context.
+ *
+ * Initializes all the attributes, calling the respective <c>init*</c>
+ * functions for the more complex data structures.
  */
 static void
 init_attrib_groups( GLcontext *ctx )
@@ -1563,10 +1707,10 @@ init_attrib_groups( GLcontext *ctx )
 /**
  * \brief Allocate the proxy textures.  
  *
- * If we run out of memory part way through the allocations clean up and return
- * GL_FALSE.
- *
  * \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 )
@@ -1658,6 +1802,14 @@ alloc_proxy_textures( GLcontext *ctx )
    }
 }
 
+/**
+ * \brief 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
@@ -1700,6 +1852,17 @@ static void add_debug_flags( const char *debug )
  *
  * This includes allocating all the other structs and arrays which hang off of
  * the context by pointers.
+ * 
+ * \param ctx GL context.
+ * 
+ * \sa _mesa_create_context() for the remaining parameter description.
+ *
+ * Performs the imports and exports callback tables initialzation, and
+ * miscellaenuos 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.
  */
 GLboolean
 _mesa_initialize_context( GLcontext *ctx,
@@ -1973,7 +2136,9 @@ _mesa_create_context( const GLvisual *visual,
 /**
  * \brief 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 )
@@ -2089,6 +2254,10 @@ _mesa_free_context_data( GLcontext *ctx )
 
 /**
  * \brief Destroy a GLcontext structure.
+ *
+ * \param ctx GL context.
+ * 
+ * Calls _mesa_free_context_data() and free the structure.
  */
 void
 _mesa_destroy_context( GLcontext *ctx )
@@ -2105,6 +2274,11 @@ _mesa_destroy_context( GLcontext *ctx )
  * \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 )
@@ -2213,6 +2387,9 @@ _mesa_copy_context( const GLcontext *src, GLcontext *dst, GLuint mask )
    dst->NewState = _NEW_ALL;
 }
 
+/**
+ * \brief Print information about this Mesa version and build options.
+ */
 static void print_info( void )
 {
    _mesa_debug(NULL, "Mesa GL_VERSION = %s\n",
@@ -2242,6 +2419,11 @@ static void print_info( void )
 
 /**
  * \brief 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 )
@@ -2249,10 +2431,24 @@ _mesa_make_current( GLcontext *newCtx, GLframebuffer *buffer )
    _mesa_make_current2( newCtx, buffer, buffer );
 }
 
-
 /**
  * \brief 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
+ * imediatly 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,
@@ -2354,10 +2550,12 @@ _mesa_make_current2( GLcontext *newCtx, GLframebuffer *drawBuffer,
 }
 
 /**
- * \brief Return current context handle for the calling thread.
+ * \brief Get current context 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
+ * \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 )
@@ -2366,10 +2564,16 @@ _mesa_get_current_context( void )
 }
 
 /**
- * \brief Return pointer to this context's current API dispatch table.
+ * \brief 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)
@@ -2386,8 +2590,15 @@ _mesa_get_dispatch(GLcontext *ctx)
 /*@{*/
 
 /**
- * Record the given error code and call the driver's Error function if defined.
+ * \brief 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
@@ -2406,6 +2617,12 @@ _mesa_record_error( GLcontext *ctx, GLenum error )
    }
 }
 
+/**
+ * \brief 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 )
 {
@@ -2416,6 +2633,12 @@ _mesa_Finish( void )
    }
 }
 
+/**
+ * \brief 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 )
 {
diff --git a/src/mesa/main/dd.h b/src/mesa/main/dd.h
index b6391234281..a5f879473d9 100644
--- a/src/mesa/main/dd.h
+++ b/src/mesa/main/dd.h
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: dd.h,v 1.74.6.1 2003/03/02 00:27:33 jrfonseca Exp $ */
+/* $Id: dd.h,v 1.74.6.2 2003/03/09 10:52:20 jrfonseca Exp $ */
 
 
 #ifndef DD_INCLUDED
@@ -74,10 +74,11 @@ struct dd_function_table {
    /**
     * \brief Clear the color/depth/stencil/accum buffer(s).
     *
-    * \p mask is a bitmask of the DD_*_BIT values defined above that indicates
+    * \param mask a bitmask of the DD_*_BIT values defined above that indicates
     * which buffers need to be cleared.
-    * If \p all is true then clear the whole buffer, else clear only the
-    * region defined by \c (x, y, width, height).
+    * \param all if true then clear the whole buffer, else clear only the
+    * region defined by <c>(x, y, width, height)</c>.
+    * 
     * This function must obey the glColorMask(), glIndexMask() and glStencilMask()
     * settings!
     * Software Mesa can do masked clears if the device driver can't.
@@ -580,7 +581,7 @@ struct dd_function_table {
    void (*DepthFunc)(GLcontext *ctx, GLenum func);
    void (*DepthMask)(GLcontext *ctx, GLboolean flag);
    void (*DepthRange)(GLcontext *ctx, GLclampd nearval, GLclampd farval);
-   void (*Enable)(GLcontext* ctx, GLenum cap, GLboolean state);
+   void (*Enable)(GLcontext *ctx, GLenum cap, GLboolean state);
    void (*Fogfv)(GLcontext *ctx, GLenum pname, const GLfloat *params);
    void (*Hint)(GLcontext *ctx, GLenum target, GLenum mode);
    void (*IndexMask)(GLcontext *ctx, GLuint mask);
diff --git a/src/mesa/main/dlist.c b/src/mesa/main/dlist.c
index c9e36e47f24..9cf0de897da 100644
--- a/src/mesa/main/dlist.c
+++ b/src/mesa/main/dlist.c
@@ -27,7 +27,7 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/* $Id: dlist.c,v 1.100.4.1 2003/03/02 00:27:34 jrfonseca Exp $ */
+/* $Id: dlist.c,v 1.100.4.2 2003/03/09 10:52:20 jrfonseca Exp $ */
 
 #include "glheader.h"
 #include "imports.h"
@@ -315,7 +315,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 )
 {
@@ -657,9 +657,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 *
@@ -4193,7 +4193,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 )
diff --git a/src/mesa/main/eval.c b/src/mesa/main/eval.c
index 30767a6277e..eef12d02fca 100644
--- a/src/mesa/main/eval.c
+++ b/src/mesa/main/eval.c
@@ -1,4 +1,4 @@
-/* $Id: eval.c,v 1.24 2002/10/24 23:57:20 brianp Exp $ */
+/* $Id: eval.c,v 1.24.4.1 2003/03/09 10:52:20 jrfonseca Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -202,8 +202,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,
@@ -257,8 +257,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,
diff --git a/src/mesa/main/image.c b/src/mesa/main/image.c
index 7f46b7dbc86..c88a8a73717 100644
--- a/src/mesa/main/image.c
+++ b/src/mesa/main/image.c
@@ -1,4 +1,4 @@
-/* $Id: image.c,v 1.69.4.1 2002/12/30 15:20:35 keithw Exp $ */
+/* $Id: image.c,v 1.69.4.2 2003/03/09 10:52:20 jrfonseca Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -417,14 +417,14 @@ _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
+ * \param 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.
+ * \return address of pixel at (image,row,column) in image or NULL if error.
  */
 GLvoid *
 _mesa_image_address( const struct gl_pixelstore_attrib *packing,
@@ -1782,7 +1782,7 @@ _mesa_pack_float_rgba_span( GLcontext *ctx,
  * 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
@@ -2539,7 +2539,7 @@ extract_float_rgba(GLuint n, GLfloat rgba[][4],
  * 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
diff --git a/src/mesa/main/imports.c b/src/mesa/main/imports.c
index 75ca33a6937..05d04a62f95 100644
--- a/src/mesa/main/imports.c
+++ b/src/mesa/main/imports.c
@@ -1,4 +1,4 @@
-/* $Id: imports.c,v 1.25 2002/10/30 20:40:46 brianp Exp $ */
+/* $Id: imports.c,v 1.25.4.1 2003/03/09 10:52:21 jrfonseca Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -443,7 +443,7 @@ _mesa_problem( const GLcontext *ctx, const char *s )
 /*
  * If in debug mode, print error message to stdout.
  * Also, record the error code by calling _mesa_record_error().
- * Input:  ctx - the GL context
+ * \param ctx - the GL context
  *         error - the error value
  *         fmtString - printf-style format string, followed by optional args
  */
@@ -642,7 +642,7 @@ default_GetDrawablePrivate(__GLcontext *gc)
 /*
  * Initialize a __GLimports object to point to the functions in
  * this file.  This is to be called from device drivers.
- * Input:  imports - the object to init
+ * \param imports - the object to init
  *         driverCtx - pointer to device driver-specific data
  */
 void
diff --git a/src/mesa/main/rastpos.c b/src/mesa/main/rastpos.c
index bb03c456973..ac4fd4b125c 100644
--- a/src/mesa/main/rastpos.c
+++ b/src/mesa/main/rastpos.c
@@ -1,4 +1,4 @@
-/* $Id: rastpos.c,v 1.39 2002/10/24 23:57:21 brianp Exp $ */
+/* $Id: rastpos.c,v 1.39.4.1 2003/03/09 10:52:21 jrfonseca Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -44,8 +44,8 @@
 
 /*
  * Clip a point against the view volume.
- * Input:  v - vertex-vector describing the point to clip
- * Return:  0 = outside view volume
+ * \param v - vertex-vector describing the point to clip
+ * \return 0 = outside view volume
  *          1 = inside view volume
  */
 static GLuint
@@ -78,8 +78,8 @@ viewclip_point_z( const GLfloat v[] )
 
 /*
  * Clip a point against the user clipping planes.
- * Input:  v - vertex-vector describing the point to clip.
- * Return:  0 = point was clipped
+ * \param v - vertex-vector describing the point to clip.
+ * \return 0 = point was clipped
  *          1 = point not clipped
  */
 static GLuint
@@ -106,7 +106,7 @@ 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
+ * \param ctx - the context
  *        vertex - vertex location
  *        normal - normal vector
  * Output: Rcolor - returned color
diff --git a/src/mesa/main/teximage.c b/src/mesa/main/teximage.c
index a3e7fe8cea0..440f8e78f58 100644
--- a/src/mesa/main/teximage.c
+++ b/src/mesa/main/teximage.c
@@ -1,4 +1,4 @@
-/* $Id: teximage.c,v 1.124 2002/10/30 19:58:58 brianp Exp $ */
+/* $Id: teximage.c,v 1.124.4.1 2003/03/09 10:52:21 jrfonseca Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -757,9 +757,9 @@ _mesa_init_teximage_fields(GLcontext *ctx, GLenum target,
 
 /*
  * Test glTexImage[123]D() parameters for errors.
- * Input:
+ * \param
  *         dimensions - must be 1 or 2 or 3
- * Return:  GL_TRUE = an error was detected, GL_FALSE = no errors
+ * \return GL_TRUE = an error was detected, GL_FALSE = no errors
  */
 static GLboolean
 texture_error_check( GLcontext *ctx, GLenum target,
@@ -1046,9 +1046,9 @@ texture_error_check( GLcontext *ctx, GLenum target,
 
 /*
  * Test glTexSubImage[123]D() parameters for errors.
- * Input:
+ * \param
  *         dimensions - must be 1 or 2 or 3
- * Return:  GL_TRUE = an error was detected, GL_FALSE = no errors
+ * \return GL_TRUE = an error was detected, GL_FALSE = no errors
  */
 static GLboolean
 subtexture_error_check( GLcontext *ctx, GLuint dimensions,
@@ -1213,8 +1213,8 @@ 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 dimensions - must be 1 or 2 or 3
+ * \return GL_TRUE = an error was detected, GL_FALSE = no errors
  */
 static GLboolean
 copytexture_error_check( GLcontext *ctx, GLuint dimensions,
diff --git a/src/mesa/main/texobj.c b/src/mesa/main/texobj.c
index 93ae40ac745..23de0744773 100644
--- a/src/mesa/main/texobj.c
+++ b/src/mesa/main/texobj.c
@@ -1,4 +1,7 @@
-/* $Id: texobj.c,v 1.62 2002/10/24 23:57:21 brianp Exp $ */
+/**
+ * \file texobj.c
+ * \brief Texture object functions.
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -24,6 +27,8 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/* $Id: texobj.c,v 1.62.4.1 2003/03/09 10:52:21 jrfonseca Exp $ */
+
 #include "glheader.h"
 #include "colortab.h"
 #include "context.h"
@@ -37,16 +42,23 @@
 #include "mtypes.h"
 
 
-/*
- * Allocate a new texture object and add it to the linked list of texture
- * objects.  If name>0 then also insert the new texture object into the hash
+/**
+ * \brief Allocate a new texture object and add it to the linked list of
+ * texture objects.  
+ *
+ * \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 initalize a gl_texture_object structure, and insert in the
+ * shared state texture list while holding its mutex.
+ * If <c>name > 0</c> then also insert the new texture object into the hash
  * table.
- * Input:  shared - the shared GL state structure to contain the texture object
- *         name - integer name for the texture object
- *         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
+ * 
  */
 struct gl_texture_object *
 _mesa_alloc_texture_object( struct gl_shared_state *shared,
@@ -112,12 +124,16 @@ _mesa_alloc_texture_object( struct gl_shared_state *shared,
    return obj;
 }
 
-
-/*
- * Deallocate a texture object struct and remove it from the given
+/**
+ * \brief Deallocate a texture object struct and remove it from the given
  * shared GL state.
- * Input:  shared - the shared GL state to which the object belongs
- *         t - the texture object to delete
+ *
+ * \param shared the shared GL state to which the object belongs.
+ * \param t 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 rees the texture images and the object itself.
  */
 void _mesa_free_texture_object( struct gl_shared_state *shared,
                                 struct gl_texture_object *t )
@@ -168,9 +184,11 @@ void _mesa_free_texture_object( struct gl_shared_state *shared,
    FREE( t );
 }
 
-
-/*
- * Copy texture object state from one texture object to another.
+/**
+ * \brief 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,
@@ -206,8 +224,13 @@ _mesa_copy_texture_object( struct gl_texture_object *dest,
 }
 
 
-/*
- * Report why a texture object is incomplete.  (for debug only)
+/**
+ * \brief 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
@@ -216,13 +239,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.
+/**
+ * \brief Examine a texture object to determine if it is complete.
+ *
+ * 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,
@@ -492,13 +523,26 @@ _mesa_test_texobj_completeness( const GLcontext *ctx,
    }
 }
 
-
+/**
+ * \brief 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);
 
-
-/*
- * Execute glGenTextures
- */
+/**
+ * \brief 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 holdind 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 )
 {
@@ -537,10 +581,17 @@ _mesa_GenTextures( GLsizei n, GLuint *texName )
    _glthread_UNLOCK_MUTEX(GenTexturesLock);
 }
 
-
-
-/*
- * Execute glDeleteTextures
+/**
+ * \brief 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, unbind 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)
@@ -616,10 +667,20 @@ _mesa_DeleteTextures( GLsizei n, const GLuint *texName)
    }
 }
 
-
-
-/*
- * Execute glBindTexture
+/**
+ * \brief 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 immediatly 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_driver_table::BindTexture. Decrements the old texture reference
+ * count and deletes it if it reaches zero.
  */
 void
 _mesa_BindTexture( GLenum target, GLuint texName )
@@ -766,10 +827,17 @@ _mesa_BindTexture( GLenum target, GLuint texName )
    }
 }
 
-
-
-/*
- * Execute glPrioritizeTextures
+/**
+ * \brief Set texture priorities.
+ * 
+ * \param n number of textures.
+ * \param texName texture names.
+ * \param priorities corresponding texture priorities.
+ * 
+ * \sa glPrioritizeTextures().
+ * 
+ * Looksup each texture in the hash, clamps the corresponding priority between
+ * 0.0 and 1.0, and calls dd_driver_table::PrioritizeTexture.
  */
 void
 _mesa_PrioritizeTextures( GLsizei n, const GLuint *texName,
@@ -802,10 +870,23 @@ _mesa_PrioritizeTextures( GLsizei n, const GLuint *texName,
    ctx->NewState |= _NEW_TEXTURE;
 }
 
-
-
-/*
- * Execute glAreTexturesResident
+/**
+ * \brief 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().
+ *
+ * Looksup each texture in the hash and calls
+ * dd_driver_table::IsTextureResident.
+ * 
+ * \todo According to the OpenGL specification the \p residences contents
+ * should be left unchanged when all textures are resident, which is not done in
+ * this implementation.
  */
 GLboolean
 _mesa_AreTexturesResident(GLsizei n, const GLuint *texName,
@@ -850,10 +931,17 @@ _mesa_AreTexturesResident(GLsizei n, const GLuint *texName,
    return allResident;
 }
 
-
-
-/*
- * Execute glIsTexture
+/**
+ * \brief 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 )
diff --git a/src/mesa/main/texstore.c b/src/mesa/main/texstore.c
index 2e9fd717842..700c916b645 100644
--- a/src/mesa/main/texstore.c
+++ b/src/mesa/main/texstore.c
@@ -1,4 +1,4 @@
-/* $Id: texstore.c,v 1.47.4.1 2002/11/20 21:40:02 brianp Exp $ */
+/* $Id: texstore.c,v 1.47.4.2 2003/03/09 10:52:21 jrfonseca Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -159,7 +159,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.
diff --git a/src/mesa/main/texutil.c b/src/mesa/main/texutil.c
index 660f7ec63f5..2bf2edf633e 100644
--- a/src/mesa/main/texutil.c
+++ b/src/mesa/main/texutil.c
@@ -1,4 +1,4 @@
-/* $Id: texutil.c,v 1.34 2002/10/29 20:28:53 brianp Exp $ */
+/* $Id: texutil.c,v 1.34.4.1 2003/03/09 10:52:21 jrfonseca Exp $ */
 
 /*
  * Mesa 3-D graphics library
@@ -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.