From 6dc85575000127630489b407c50a4b3ea87c9acb Mon Sep 17 00:00:00 2001 From: Keith Whitwell Date: Thu, 17 Jul 2003 13:43:59 +0000 Subject: Merge Jose's documentation and core Mesa changes from embedded branch --- src/mesa/main/imports.c | 269 +++++++++++++++++++++++++++++++----------------- 1 file changed, 172 insertions(+), 97 deletions(-) (limited to 'src/mesa/main/imports.c') 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) -- cgit v1.2.3