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

1 files changed, 172 insertions, 97 deletions

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)