diff --git a/src/mesa/glapi/glapi.h b/src/mesa/glapi/glapi.h index be62118b57f..7a3a7fa4b0d 100644 --- a/src/mesa/glapi/glapi.h +++ b/src/mesa/glapi/glapi.h @@ -1,4 +1,6 @@ -/* $Id: glapi.h,v 1.20 2002/06/29 19:48:16 brianp Exp $ */ +/** + * \file glapi.h + */ /* * Mesa 3-D graphics library @@ -24,6 +26,7 @@ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/* $Id: glapi.h,v 1.20.6.1 2003/03/02 00:27:35 jrfonseca Exp $ */ #ifndef _GLAPI_H #define _GLAPI_H diff --git a/src/mesa/main/context.c b/src/mesa/main/context.c index 5f7d40195f1..981dfe54b96 100644 --- a/src/mesa/main/context.c +++ b/src/mesa/main/context.c @@ -1,4 +1,8 @@ -/* $Id: context.c,v 1.188.2.1.2.3 2003/02/21 21:14:08 keithw Exp $ */ +/** + * \file context.c + * \brief Mesa context/visual/framebuffer management functions. + * \author Brian Paul + */ /* * Mesa 3-D graphics library @@ -24,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.4 2003/03/02 00:27:31 jrfonseca Exp $ */ /** * \mainpage Mesa Core Module @@ -68,13 +72,6 @@ */ -/** - * \file context.c - * \brief Mesa context/visual/framebuffer management functions. - * \author Brian Paul - */ - - #include "glheader.h" #include "imports.h" #include "buffers.h" @@ -132,10 +129,12 @@ free_shared_state( GLcontext *ctx, struct gl_shared_state *ss ); /**********************************************************************/ -/***** OpenGL SI-style interface (new in Mesa 3.5) *****/ +/** \name OpenGL SI-style interface (new in Mesa 3.5) */ /**********************************************************************/ +/*@{*/ -/* Called by window system/device driver (via gc->exports.destroyCurrent()) +/** + * Called by window system/device driver (via gc->exports.destroyCurrent()) * when the rendering context is to be destroyed. */ GLboolean @@ -148,7 +147,8 @@ _mesa_destroyContext(__GLcontext *gc) return GL_TRUE; } -/* Called by window system/device driver (via gc->exports.loseCurrent()) +/** + * Called by window system/device driver (via gc->exports.loseCurrent()) * when the rendering context is made non-current. */ GLboolean @@ -158,7 +158,8 @@ _mesa_loseCurrent(__GLcontext *gc) return GL_TRUE; } -/* Called by window system/device driver (via gc->exports.makeCurrent()) +/** + * Called by window system/device driver (via gc->exports.makeCurrent()) * when the rendering context is made current. */ GLboolean @@ -168,7 +169,8 @@ _mesa_makeCurrent(__GLcontext *gc) return GL_TRUE; } -/* Called by window system/device driver - yadda, yadda, yadda. +/** + * Called by window system/device driver - yadda, yadda, yadda. * See above comments. */ GLboolean @@ -219,14 +221,17 @@ _mesa_notifyResize(__GLcontext *gc) return GL_TRUE; } +/** + * Called when the context's window/buffer is going to be destroyed. + */ void _mesa_notifyDestroy(__GLcontext *gc) { - /* Called when the context's window/buffer is going to be destroyed. */ /* Unbind from it. */ } -/* Called by window system just before swapping buffers. +/** + * Called by window system just before swapping buffers. * We have to finish any pending rendering. */ void @@ -251,9 +256,13 @@ _mesa_endDispatchOverride(__GLcontext *gc) { } -/* Setup the exports. The window system will call these functions - * when it needs Mesa to do something. - * NOTE: Device drivers should override these functions! For example, +/** + * \brief Setup the exports. + * + * The window system will call these functions when it needs Mesa to do + * something. + * + * \note Device drivers should override these functions! For example, * the Xlib driver should plug in the XMesa*-style functions into this * structure. The XMesa-style functions should then call the _mesa_* * version of these functions. This is an approximation to OO design @@ -276,9 +285,9 @@ _mesa_init_default_exports(__GLexports *exports) exports->endDispatchOverride = _mesa_endDispatchOverride; } - - -/* exported OpenGL SI interface */ +/** + * \brief Exported OpenGL SI interface. + */ __GLcontext * __glCoreCreateContext(__GLimports *imports, __GLcontextModes *modes) { @@ -295,8 +304,9 @@ __glCoreCreateContext(__GLimports *imports, __GLcontextModes *modes) return ctx; } - -/* exported OpenGL SI interface */ +/** + * \brief Exported OpenGL SI interface. + */ void __glCoreNopDispatch(void) { @@ -309,28 +319,34 @@ __glCoreNopDispatch(void) #endif } +/*@}*/ + /**********************************************************************/ -/***** GL Visual allocation/destruction *****/ +/** \name GL Visual allocation/destruction */ /**********************************************************************/ +/*@{*/ - -/* - * Allocate a new GLvisual object. - * Input: rgbFlag - GL_TRUE=RGB(A) mode, GL_FALSE=Color Index mode - * dbFlag - double buffering? - * stereoFlag - stereo buffer? - * depthBits - requested bits per depth buffer value - * Any value in [0, 32] is acceptable but the actual - * depth type will be GLushort or GLuint as needed. - * stencilBits - requested minimum bits per stencil buffer value - * accumBits - requested minimum bits per accum buffer component - * indexBits - number of bits per pixel if rgbFlag==GL_FALSE - * red/green/blue/alphaBits - number of bits per color component - * in frame buffer for RGB(A) mode. - * We always use 8 in core Mesa though. - * Return: pointer to new GLvisual or NULL if requested parameters can't - * be met. +/** + * \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 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 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. + * \param blue same as above. + * \param alphaBits same as above. + * + * \return pointer to new GLvisual or NULL if requested parameters can't be + * met. */ GLvisual * _mesa_create_visual( GLboolean rgbFlag, @@ -364,12 +380,12 @@ _mesa_create_visual( GLboolean rgbFlag, return vis; } - -/* - * Initialize the fields of the given GLvisual. - * Input: see _mesa_create_visual() above. - * Return: GL_TRUE = success - * GL_FALSE = failure. +/** + * \brief Initialize the fields of the given GLvisual. + * + * \return GL_TRUE on success, or GL_FALSE on failure. + * + * \sa see _mesa_create_visual() above. */ GLboolean _mesa_initialize_visual( GLvisual *vis, @@ -446,29 +462,33 @@ _mesa_initialize_visual( GLvisual *vis, return GL_TRUE; } - void _mesa_destroy_visual( GLvisual *vis ) { FREE(vis); } +/*@}*/ + /**********************************************************************/ -/***** GL Framebuffer allocation/destruction *****/ +/** \name GL Framebuffer allocation/destruction */ /**********************************************************************/ +/*@{*/ - -/* - * Create a new framebuffer. A GLframebuffer is a struct which - * encapsulates the depth, stencil and accum buffers and related - * parameters. - * Input: visual - a GLvisual pointer (we copy the struct contents) - * softwareDepth - create/use a software depth buffer? - * softwareStencil - create/use a software stencil buffer? - * softwareAccum - create/use a software accum buffer? - * softwareAlpha - create/use a software alpha buffer? - * Return: pointer to new GLframebuffer struct or NULL if error. +/** + * \brief Create a new framebuffer. + * + * A GLframebuffer is a struct which encapsulates the depth, stencil and accum + * buffers and related parameters. + * + * \param visual a GLvisual pointer (we copy the struct contents) + * \param softwareDepth create/use a software depth buffer? + * \param softwareStencil create/use a software stencil buffer? + * \param softwareAccum create/use a software accum buffer? + * \param softwareAlpha create/use a software alpha buffer? + * + * \return pointer to new GLframebuffer struct or NULL if error. */ GLframebuffer * _mesa_create_framebuffer( const GLvisual *visual, @@ -487,10 +507,10 @@ _mesa_create_framebuffer( const GLvisual *visual, return buffer; } - -/* - * Initialize a GLframebuffer object. - * Input: See _mesa_create_framebuffer() above. +/** + * \brief Initialize a GLframebuffer object. + * + * \sa _mesa_create_framebuffer() above. */ void _mesa_initialize_framebuffer( GLframebuffer *buffer, @@ -531,8 +551,8 @@ _mesa_initialize_framebuffer( GLframebuffer *buffer, } -/* - * Free a framebuffer struct and its buffers. +/** + * \brief Free a framebuffer struct and its buffers. */ void _mesa_destroy_framebuffer( GLframebuffer *buffer ) @@ -544,8 +564,8 @@ _mesa_destroy_framebuffer( GLframebuffer *buffer ) } -/* - * Free the data hanging off of , but not itself. +/** + * \brief Free the data hanging off of \p buffer, but not \p buffer itself. */ void _mesa_free_framebuffer_data( GLframebuffer *buffer ) @@ -583,18 +603,18 @@ _mesa_free_framebuffer_data( GLframebuffer *buffer ) } } +/*@}*/ /**********************************************************************/ -/***** Context allocation, initialization, destroying *****/ +/** \name Context allocation, initialization, destroying *****/ /**********************************************************************/ - +/*@{*/ _glthread_DECLARE_STATIC_MUTEX(OneTimeLock); - -/* - * This function just calls all the various one-time-init functions in Mesa. +/** + * \brief This function just calls all the various one-time-init functions in Mesa. */ static void one_time_init( GLcontext *ctx ) @@ -641,7 +661,6 @@ one_time_init( GLcontext *ctx ) _glthread_UNLOCK_MUTEX(OneTimeLock); } - static void init_matrix_stack( struct matrix_stack *stack, GLuint maxDepth, GLuint dirtyFlag ) @@ -660,7 +679,6 @@ init_matrix_stack( struct matrix_stack *stack, stack->Top = stack->Stack; } - static void free_matrix_stack( struct matrix_stack *stack ) { @@ -672,9 +690,8 @@ free_matrix_stack( struct matrix_stack *stack ) stack->Stack = stack->Top = NULL; } - -/* - * Allocate and initialize a shared context state structure. +/** + * \brief Allocate and initialize a shared context state structure. */ static struct gl_shared_state * alloc_shared_state( void ) @@ -754,9 +771,8 @@ alloc_shared_state( void ) } } - -/* - * Deallocate a shared state context and all children structures. +/** + * \brief Deallocate a shared state context and all children structures. */ static void free_shared_state( GLcontext *ctx, struct gl_shared_state *ss ) @@ -799,11 +815,10 @@ free_shared_state( GLcontext *ctx, struct gl_shared_state *ss ) FREE(ss); } - - -/* - * Initialize the nth light. Note that the defaults for light 0 are - * different than the other lights. +/** + * \brief Initialize the n-th light. + * + * Note that the defaults for light 0 are different than the other lights. */ static void init_light( struct gl_light *l, GLuint n ) @@ -831,8 +846,6 @@ init_light( struct gl_light *l, GLuint n ) l->Enabled = GL_FALSE; } - - static void init_lightmodel( struct gl_lightmodel *lm ) { @@ -842,7 +855,6 @@ init_lightmodel( struct gl_lightmodel *lm ) lm->ColorControl = GL_SINGLE_COLOR; } - static void init_material( struct gl_material *m ) { @@ -856,8 +868,6 @@ init_material( struct gl_material *m ) m->SpecularIndex = 1; } - - static void init_texture_unit( GLcontext *ctx, GLuint unit ) { @@ -910,9 +920,9 @@ init_texture_unit( GLcontext *ctx, GLuint unit ) } - - -/* Initialize a 1-D evaluator map */ +/** + * \brief Initialize a 1-D evaluator map. + */ static void init_1d_map( struct gl_1d_map *map, int n, const float *initial ) { @@ -928,7 +938,9 @@ init_1d_map( struct gl_1d_map *map, int n, const float *initial ) } -/* Initialize a 2-D evaluator map */ +/** + * \brief Initialize a 2-D evaluator map + */ static void init_2d_map( struct gl_2d_map *map, int n, const float *initial ) { @@ -946,9 +958,8 @@ init_2d_map( struct gl_2d_map *map, int n, const float *initial ) } } - -/* - * Initialize the attribute groups in a GLcontext. +/** + * \brief Initialize the attribute groups in a GLcontext. */ static void init_attrib_groups( GLcontext *ctx ) @@ -1547,13 +1558,13 @@ init_attrib_groups( GLcontext *ctx ) } } - - - -/* - * Allocate the proxy textures. If we run out of memory part way through - * the allocations clean up and return GL_FALSE. - * Return: GL_TRUE=success, GL_FALSE=failure +/** + * \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 */ static GLboolean alloc_proxy_textures( GLcontext *ctx ) @@ -1645,7 +1656,6 @@ alloc_proxy_textures( GLcontext *ctx ) } } - static void add_debug_flags( const char *debug ) { #ifdef MESA_DEBUG @@ -1683,10 +1693,11 @@ static void add_debug_flags( const char *debug ) #endif } - -/* - * Initialize a GLcontext struct. This includes allocating all the - * other structs and arrays which hang off of the context by pointers. +/** + * \brief Initialize a GLcontext struct. + * + * This includes allocating all the other structs and arrays which hang off of + * the context by pointers. */ GLboolean _mesa_initialize_context( GLcontext *ctx, @@ -1920,15 +1931,15 @@ _mesa_initialize_context( GLcontext *ctx, return GL_TRUE; } - - /** - * Allocate and initialize a GLcontext structure. - * Input: visual - a GLvisual pointer (we copy the struct contents) - * sharelist - another context to share display lists with or NULL - * driver_ctx - pointer to device driver's context state struct - * direct - direct rendering? - * Return: pointer to a new __GLcontextRec or NULL if error. + * \brief Allocate and initialize a GLcontext structure. + * + * \param visual a GLvisual pointer (we copy the struct contents) + * \param sharelist another context to share display lists with or NULL + * \param driver_ctx pointer to device driver's context state struct + * \param direct direct rendering? + * + * \return pointer to a new __GLcontextRec or NULL if error. */ GLcontext * _mesa_create_context( const GLvisual *visual, @@ -1955,10 +1966,9 @@ _mesa_create_context( const GLvisual *visual, } } - - /** - * Free the data associated with the given context. + * \brief Free the data associated with the given context. + * * But don't free() the GLcontext struct itself! */ void @@ -2073,10 +2083,8 @@ _mesa_free_context_data( GLcontext *ctx ) FREE(ctx->Save); } - - /** - * Destroy a GLcontext structure. + * \brief Destroy a GLcontext structure. */ void _mesa_destroy_context( GLcontext *ctx ) @@ -2087,13 +2095,12 @@ _mesa_destroy_context( GLcontext *ctx ) } } - - -/* - * Copy attribute groups from one context to another. - * Input: src - source context - * dst - destination context - * mask - bitwise OR of GL_*_BIT flags +/** + * \brief Copy attribute groups from one context to another. + * + * \param src source context + * \param dst destination context + * \param mask bitwise OR of GL_*_BIT flags */ void _mesa_copy_context( const GLcontext *src, GLcontext *dst, GLuint mask ) @@ -2202,8 +2209,6 @@ _mesa_copy_context( const GLcontext *src, GLcontext *dst, GLuint mask ) dst->NewState = _NEW_ALL; } - - static void print_info( void ) { _mesa_debug(NULL, "Mesa GL_VERSION = %s\n", @@ -2231,9 +2236,8 @@ static void print_info( void ) #endif } - -/* - * Set the current context, binding the given frame buffer to the context. +/** + * \brief Set the current context, binding the given frame buffer to the context. */ void _mesa_make_current( GLcontext *newCtx, GLframebuffer *buffer ) @@ -2242,9 +2246,9 @@ _mesa_make_current( GLcontext *newCtx, GLframebuffer *buffer ) } -/* - * Bind the given context to the given draw-buffer and read-buffer - * and make it the current context for this thread. +/** + * \brief Bind the given context to the given draw-buffer and read-buffer and + * make it the current context for this thread. */ void _mesa_make_current2( GLcontext *newCtx, GLframebuffer *drawBuffer, @@ -2345,10 +2349,9 @@ _mesa_make_current2( GLcontext *newCtx, GLframebuffer *drawBuffer, } } - - -/* - * Return current context handle for the calling thread. +/** + * \brief Return current context handle for the calling thread. + * * This isn't the fastest way to get the current context. * If you need speed, see the GET_CURRENT_CONTEXT() macro in context.h */ @@ -2358,11 +2361,11 @@ _mesa_get_current_context( void ) return (GLcontext *) _glapi_get_context(); } - -/* - * Return pointer to this context's current API dispatch table. - * It'll either be the immediate-mode execute dispatcher or the - * display list compile dispatcher. +/** + * \brief Return pointer to this context's current API dispatch table. + * + * It'll either be the immediate-mode execute dispatcher or the display list + * compile dispatcher. */ struct _glapi_table * _mesa_get_dispatch(GLcontext *ctx) @@ -2370,15 +2373,17 @@ _mesa_get_dispatch(GLcontext *ctx) return ctx->CurrentDispatch; } +/*@}*/ /**********************************************************************/ -/***** Miscellaneous functions *****/ +/** \name Miscellaneous functions *****/ /**********************************************************************/ +/*@{*/ - -/* +/** * Record the given error code and call the driver's Error function if defined. + * * This is called via _mesa_error(). */ void @@ -2397,7 +2402,6 @@ _mesa_record_error( GLcontext *ctx, GLenum error ) } } - void _mesa_Finish( void ) { @@ -2408,8 +2412,6 @@ _mesa_Finish( void ) } } - - void _mesa_Flush( void ) { @@ -2420,8 +2422,9 @@ _mesa_Flush( void ) } } - - +/** + * \brief Primitive names + */ const char *_mesa_prim_name[GL_POLYGON+4] = { "GL_POINTS", "GL_LINES", @@ -2437,3 +2440,5 @@ const char *_mesa_prim_name[GL_POLYGON+4] = { "inside unkown primitive", "unknown state" }; + +/*@{*/ diff --git a/src/mesa/main/context.h b/src/mesa/main/context.h index 8b1de0a53aa..fe4b9842cca 100644 --- a/src/mesa/main/context.h +++ b/src/mesa/main/context.h @@ -1,4 +1,23 @@ -/* $Id: context.h,v 1.35 2002/10/24 23:57:20 brianp Exp $ */ +/** + * \file context.h + * \brief Context. + * + * There are three Mesa datatypes which are meant to be used by device + * drivers: + * - GLcontext: this contains the Mesa rendering state + * - GLvisual: this describes the color buffer (RGB vs. ci), whether or not + * there's a depth buffer, stencil buffer, etc. + * - GLframebuffer: contains pointers to the depth buffer, stencil buffer, + * accum buffer and alpha buffers. + * + * These types should be encapsulated by corresponding device driver + * datatypes. See xmesa.h and xmesaP.h for an example. + * + * In OOP terms, GLcontext, GLvisual, and GLframebuffer are base classes + * which the device driver must derive from. + * + * The following functions create and destroy these datatypes. + */ /* * Mesa 3-D graphics library @@ -24,6 +43,7 @@ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/* $Id: context.h,v 1.35.4.1 2003/03/02 00:27:32 jrfonseca Exp $ */ #ifndef CONTEXT_H #define CONTEXT_H @@ -33,28 +53,10 @@ #include "mtypes.h" -/* - * There are three Mesa datatypes which are meant to be used by device - * drivers: - * GLcontext: this contains the Mesa rendering state - * GLvisual: this describes the color buffer (rgb vs. ci), whether - * or not there's a depth buffer, stencil buffer, etc. - * GLframebuffer: contains pointers to the depth buffer, stencil - * buffer, accum buffer and alpha buffers. - * - * These types should be encapsulated by corresponding device driver - * datatypes. See xmesa.h and xmesaP.h for an example. - * - * In OOP terms, GLcontext, GLvisual, and GLframebuffer are base classes - * which the device driver must derive from. - * - * The following functions create and destroy these datatypes. - */ - - -/* - * Create/destroy a GLvisual. - */ +/**********************************************************************/ +/** \name Create/destroy a GLvisual. */ +/*@{*/ + extern GLvisual * _mesa_create_visual( GLboolean rgbFlag, GLboolean dbFlag, @@ -93,11 +95,13 @@ _mesa_initialize_visual( GLvisual *v, extern void _mesa_destroy_visual( GLvisual *vis ); +/*@}*/ -/* - * Create/destroy a GLframebuffer. - */ +/**********************************************************************/ +/** \name Create/destroy a GLframebuffer. */ +/*@{*/ + extern GLframebuffer * _mesa_create_framebuffer( const GLvisual *visual, GLboolean softwareDepth, @@ -119,11 +123,13 @@ _mesa_free_framebuffer_data( GLframebuffer *buffer ); extern void _mesa_destroy_framebuffer( GLframebuffer *buffer ); +/*@}*/ -/* - * Create/destroy a GLcontext. - */ +/**********************************************************************/ +/** \name Create/destroy a GLcontext. */ +/*@{*/ + extern GLcontext * _mesa_create_context( const GLvisual *visual, GLcontext *share_list, @@ -160,10 +166,13 @@ _mesa_make_current2( GLcontext *ctx, GLframebuffer *drawBuffer, extern GLcontext * _mesa_get_current_context(void); +/*@}*/ -/* - * Macros for fetching current context. +/** + * \brief Macro for fetching the current context. + * + * It should be used in the variable declaration area of a function. */ #ifdef THREADS @@ -177,7 +186,9 @@ _mesa_get_current_context(void); -/* OpenGL SI-style export functions. */ +/**********************************************************************/ +/** \name OpenGL SI-style export functions. */ +/*@{*/ extern GLboolean _mesa_destroyContext(__GLcontext *gc); @@ -215,6 +226,7 @@ _mesa_beginDispatchOverride(__GLcontext *gc); extern void _mesa_endDispatchOverride(__GLcontext *gc); +/*@}*/ extern struct _glapi_table * @@ -222,9 +234,9 @@ _mesa_get_dispatch(GLcontext *ctx); -/* - * Miscellaneous - */ +/**********************************************************************/ +/** \name Miscellaneous */ +/*@{*/ extern void _mesa_record_error( GLcontext *ctx, GLenum error ); @@ -236,5 +248,6 @@ _mesa_Finish( void ); extern void _mesa_Flush( void ); +/*@}*/ #endif diff --git a/src/mesa/main/dd.h b/src/mesa/main/dd.h index d6f0da1c69e..b6391234281 100644 --- a/src/mesa/main/dd.h +++ b/src/mesa/main/dd.h @@ -1,4 +1,7 @@ -/* $Id: dd.h,v 1.74 2002/10/11 17:41:04 brianp Exp $ */ +/** + * \file dd.h + * \brief Device driver interfaces. + */ /* * Mesa 3-D graphics library @@ -24,6 +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 $ */ #ifndef DD_INCLUDED @@ -47,136 +51,181 @@ struct gl_pixelstore_attrib; #define DD_STENCIL_BIT GL_STENCIL_BUFFER_BIT /* 0x00000400 */ -/* - * Device Driver function table. +/** + * \brief Device driver function table. */ struct dd_function_table { - + /** + * \brief 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 ); - /* Return a string as needed by glGetString(). - * Only the GL_RENDERER token must be implemented. Otherwise, - * NULL can be returned. - */ + /** + * \brief Notify the driver after Mesa has made some internal state changes. + * + * This is in addition to any statechange callbacks Mesa may already have + * made. + */ 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. - */ - 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 + /** + * \brief Clear the color/depth/stencil/accum buffer(s). + * + * \p mask is 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 + * If \p all is true then clear the whole buffer, else clear only the + * region defined by \c (x, y, width, height). + * 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 ); + /** + * \brief 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 ); - /* - * 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. + + /** + * \brief Specifies the current buffer for reading. + * + * Called via glReadBuffer(). */ - - void (*ReadBuffer)( GLcontext *ctx, GLenum buffer ); - /* - * Specifies the current buffer for reading. Called via glReadBuffer(). - */ - void (*GetBufferSize)( GLframebuffer *buffer, - GLuint *width, GLuint *height ); - /* - * Returns the width and height of the named buffer/window. + /** + * \brief 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 ); + /** + * \brief 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. + */ 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. - */ + /** + * \brief This is called whenever glFinish() is called. + */ void (*Finish)( GLcontext *ctx ); - /* - * This is called whenever glFinish() is called. - */ + /** + * \brief This is called whenever glFlush() is called. + */ void (*Flush)( GLcontext *ctx ); - /* - * This is called whenever glFlush() is called. - */ - void (*Error)( GLcontext *ctx ); - /* - * Called whenever an error is generated. ctx->ErrorValue contains + /** + * \brief Called whenever an error is generated. ctx->ErrorValue contains * the error value. */ + void (*Error)( GLcontext *ctx ); - /*** - *** For hardware accumulation buffer: - ***/ + /** + * \name For hardware accumulation buffer + */ + /*@{*/ + /** + * \brief 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. + /*@}*/ + + + /** + * \name glDraw(), glRead(), glCopyPixels() and glBitmap() functions */ + /*@{*/ - - /*** - *** glDraw/Read/CopyPixels and glBitmap functions: - ***/ - + /** + * \brief 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. - */ + /** + * \brief 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. - */ + /** + * \brief 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. - */ + /** + * \brief 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. - */ + /*@}*/ - /*** - *** Texture image functions: - ***/ + + /** + * \name Texture image functions + */ + /*@{*/ + + /** + * \brief 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 and return a - * pointer to an appropriate gl_texture_format. - */ + /** + * \brief 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, @@ -184,6 +233,12 @@ struct dd_function_table { const struct gl_pixelstore_attrib *packing, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); + + /** + * \brief Called by glTexImage2D(). + * + * \sa dd_function_table::TexImage1D. + */ void (*TexImage2D)( GLcontext *ctx, GLenum target, GLint level, GLint internalFormat, GLint width, GLint height, GLint border, @@ -191,6 +246,12 @@ struct dd_function_table { const struct gl_pixelstore_attrib *packing, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); + + /** + * \brief 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, @@ -198,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: - * , , , and are user specified. - * indicates the image packing of pixels. - * is the target texture object. - * is the target texture image. It will have the texture - * width, height, depth, border and internalFormat information. - * 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. - */ + /** + * \brief 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, @@ -217,6 +288,12 @@ struct dd_function_table { const struct gl_pixelstore_attrib *packing, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); + + /** + * \brief Called by glTexSubImage2D(). + * + * \sa dd_function_table::TexSubImage1D. + */ void (*TexSubImage2D)( GLcontext *ctx, GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLsizei height, @@ -225,6 +302,12 @@ struct dd_function_table { const struct gl_pixelstore_attrib *packing, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); + + /** + * \brief 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, @@ -233,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: - * , , , , , , , - * , , and are user specified. - * indicates the image packing of pixels. - * is the target texture object. - * 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. - */ + /** + * \brief 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 ); + + /** + * \brief 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. + + /** + * \brief 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 ); + /** + * \brief 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 ); + /** + * \brief 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. - */ + /** + * \brief 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. + /*@}*/ + + + /** + * \name Compressed texture functions */ + /*@{*/ - /*** - *** Compressed texture functions: - ***/ - + /** + * \brief 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 ); + /** + * \brief Called by glCompressedTexImage2D(). + * + * \sa dd_function_table::glCompressedTexImage1D. + */ 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 ); + /** + * \brief Called by glCompressedTexImage3D(). + * + * \sa dd_function_table::glCompressedTexImage3D. + */ void (*CompressedTexImage3D)( GLcontext *ctx, GLenum target, GLint level, GLint internalFormat, GLsizei width, GLsizei height, GLsizei depth, @@ -302,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: - * , , , are user specified. - * is the target texture object. - * is the target texture image. It will have the texture - * width, height, depth, border and internalFormat information. - * 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. - */ + /** + * \brief 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); + /** + * \brief Called by glCompressedTexSubImage2D(). + * + * \sa dd_function_table::glCompressedTexImage3D. + */ void (*CompressedTexSubImage2D)(GLcontext *ctx, GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLint height, @@ -327,6 +461,11 @@ struct dd_function_table { GLsizei imageSize, const GLvoid *data, struct gl_texture_object *texObj, struct gl_texture_image *texImage); + /** + * \brief Called by glCompressedTexSubImage3D(). + * + * \sa dd_function_table::glCompressedTexImage3D. + */ void (*CompressedTexSubImage3D)(GLcontext *ctx, GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLint height, GLint depth, @@ -334,59 +473,64 @@ 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: - * , , , , , , - * , and are user specified. - * is the target texture object. - * 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. + /*@}*/ + + /** + * \name Texture object functions */ + /*@{*/ - /*** - *** Texture object functions: - ***/ - + /** + * \brief Called by glBindTexture(). + */ void (*BindTexture)( GLcontext *ctx, GLenum target, struct gl_texture_object *tObj ); - /* Called by glBindTexture(). - */ + /** + * \brief Called when a texture object is created. + */ void (*CreateTexture)( GLcontext *ctx, struct gl_texture_object *tObj ); - /* Called when a texture object is created. - */ + /** + * \brief 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 ); - /* Called when a texture object is about to be deallocated. Driver - * should free anything attached to the DriverData pointers. - */ + /** + * \brief Called by glAreTextureResident(). + */ GLboolean (*IsTextureResident)( GLcontext *ctx, struct gl_texture_object *t ); - /* Called by glAreTextureResident(). - */ + /** + * \brief Called by glPrioritizeTextures(). + */ void (*PrioritizeTexture)( GLcontext *ctx, struct gl_texture_object *t, GLclampf priority ); - /* Called by glPrioritizeTextures(). - */ + /** + * \brief Called by glActiveTextureARB() to set current texture unit. + */ void (*ActiveTexture)( GLcontext *ctx, GLuint texUnitNumber ); - /* Called by glActiveTextureARB to set current texture unit. - */ - 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 + /** + * \brief Called when the texture's color lookup table is changed. + * + * If \p tObj is NULL then the shared texture palette ctx->Texture.Palette * is to be updated. */ + void (*UpdateTexturePalette)( GLcontext *ctx, + struct gl_texture_object *tObj ); + /*@}*/ - /*** - *** Imaging functionality: - ***/ + + /** + * \name Imaging functionality + * . + */ + /*@{*/ void (*CopyColorTable)( GLcontext *ctx, GLenum target, GLenum internalformat, GLint x, GLint y, GLsizei width ); @@ -403,16 +547,19 @@ 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're \e also called by the gl_PopAttrib() function!!! + * May add more functions like these to the device driver in the future. + */ + /*@{*/ void (*AlphaFunc)(GLcontext *ctx, GLenum func, GLfloat ref); void (*BlendColor)(GLcontext *ctx, const GLfloat color[4]); void (*BlendEquation)(GLcontext *ctx, GLenum mode); @@ -465,12 +612,15 @@ struct dd_function_table { GLenum pname, const GLfloat *params); void (*TextureMatrix)(GLcontext *ctx, GLuint unit, const GLmatrix *mat); 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, @@ -488,111 +638,164 @@ 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. + */ + /*@{*/ GLboolean (*GetBooleanv)(GLcontext *ctx, GLenum pname, GLboolean *result); GLboolean (*GetDoublev)(GLcontext *ctx, GLenum pname, GLdouble *result); GLboolean (*GetFloatv)(GLcontext *ctx, GLenum pname, GLfloat *result); GLboolean (*GetIntegerv)(GLcontext *ctx, GLenum pname, GLint *result); 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 + /** + * \brief 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. + /** + * \brief Validate the current T&L module. * - * This must be non-NULL if a driver installs a custom tnl module and - * sets the NeedValidate bitmask, but may be NULL otherwise. + * This is called directly after UpdateState() when a state change that has + * occured 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 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 + /** + * \brief Set by the driver-supplied T&L engine. + * + * Set to PRIM_OUTSIDE_BEGIN_END when outside glBegin()/glEnd(). + */ GLuint CurrentExecPrimitive; - /* Set by the driver-supplied t&l engine. Set to - * PRIM_OUTSIDE_BEGIN_END when outside begin/end. - */ - 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 ctx->Current is not uptodate. * - * 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 ctx->Current and + * ctx->Light.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 + /** + * \brief 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 + /** + * \brief 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 ); + /** + * \brief 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. + /** + * \brief 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 ); + /** + * \brief Called by glEndCallList(). + * + * \sa dd_function_table::BeginCallList. + */ + void (*EndCallList)( GLcontext *ctx ); + /** + * \brief 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. + + /** + * \brief Called by glLockArraysEXT(). */ - - void (*LockArraysEXT)( GLcontext *ctx, GLint first, GLsizei count ); - void (*UnlockArraysEXT)( GLcontext *ctx ); - /* Called by glLockArraysEXT() and glUnlockArraysEXT(), respectively. + /** + * \brief Called by UnlockArraysEXT(). */ + void (*UnlockArraysEXT)( GLcontext *ctx ); + /*@}*/ }; -/* - * Transform/Clip/Lighting interface +/** + * \brief Transform/Clip/Lighting interface */ typedef struct { + /** + * 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 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, it must restore them to their original values in + * the disable() callback, below. + */ + /*@{*/ void (*ArrayElement)( GLint ); /* NOTE */ void (*Color3f)( GLfloat, GLfloat, GLfloat ); void (*Color3fv)( const GLfloat * ); @@ -648,52 +851,44 @@ 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 ); + /** + * 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 (*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 + /** + * If you don't support eval, fallback to the default vertex format * on receiving an eval call and use the pipeline mechanism to - * provide partial t&l acceleration. + * provide partial T&L acceleration. * * Mesa will provide a set of helper functions to do eval within * accelerated vertex formats, eventually... */ + /*@{*/ + void (*EvalMesh1)( GLenum mode, GLint i1, GLint i2 ); + void (*EvalMesh2)( GLenum mode, GLint i1, GLint i2, GLint j1, GLint j2 ); + /*@}*/ - GLboolean prefer_float_colors; - /* Should core try to send colors to glColor4f or glColor4chan, + /** + * Should core try to send colors to glColor4f or glColor4chan, * where it has a choice? */ + GLboolean prefer_float_colors; } GLvertexformat; diff --git a/src/mesa/main/dlist.c b/src/mesa/main/dlist.c index 2391d8dcdbd..c9e36e47f24 100644 --- a/src/mesa/main/dlist.c +++ b/src/mesa/main/dlist.c @@ -1,4 +1,7 @@ -/* $Id: dlist.c,v 1.100 2002/11/06 15:16:23 brianp Exp $ */ +/** + * \file dlist.c + * \brief Display lists management functions. + */ /* * Mesa 3-D graphics library @@ -24,6 +27,8 @@ * 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 $ */ + #include "glheader.h" #include "imports.h" #include "api_loopback.h" @@ -70,47 +75,48 @@ -/* -Functions which aren't compiled but executed immediately: - glIsList - glGenLists - glDeleteLists - glEndList --- BUT: call ctx->Driver.EndList at end of list execution? - glFeedbackBuffer - glSelectBuffer - glRenderMode - glReadPixels - glPixelStore - glFlush - glFinish - glIsEnabled - glGet* - -Functions which cause errors if called while compiling a display list: - glNewList -*/ +/** + * Functions which aren't compiled but executed immediately: + * - glIsList + * - glGenLists + * - glDeleteLists + * - glEndList --- BUT: call ctx->Driver.EndList at end of list execution? + * - glFeedbackBuffer + * - glSelectBuffer + * - glRenderMode + * - glReadPixels + * - glPixelStore + * - glFlush + * - glFinish + * - glIsEnabled + * - glGet* + * + * Functions which cause errors if called while compiling a display list: + * - glNewList + */ -/* +/** * Display list instructions are stored as sequences of "nodes". Nodes * are allocated in blocks. Each block has BLOCK_SIZE nodes. Blocks * are linked together with a pointer. */ -/* How many nodes to allocate at a time: - * - reduced now that we hold vertices etc. elsewhere. +/** + * \brief How many nodes to allocate at a time. + * + * \note Reduced now that we hold vertices etc. elsewhere. */ #define BLOCK_SIZE 256 -/* - * Display list opcodes. +/** + * \brief Display list opcodes. * * The fact that these identifiers are assigned consecutive * integer values starting at 0 is very important, see InstSize array usage) - * */ typedef enum { OPCODE_ACCUM, @@ -258,7 +264,9 @@ typedef enum { } OpCode; -/* +/** + * \brief Display list node. + * * Each instruction in the display list is stored as a sequence of * contiguous nodes in memory. * Each node is the union of a variety of datatypes. @@ -279,9 +287,9 @@ union node { }; - -/* Number of nodes of storage needed for each instruction. Sizes for - * dynamically allocated opcodes are stored in the context struct. +/** + * \brief Number of nodes of storage needed for each instruction. + * Sizes for dynamically allocated opcodes are stored in the context struct. */ static GLuint InstSize[ OPCODE_END_OF_LIST+1 ]; @@ -292,10 +300,6 @@ void mesa_print_display_list( GLuint list ); /***** Private *****/ /**********************************************************************/ - - - - /* * Make an empty display list. This is used by glGenLists() to * reserver display list IDs. diff --git a/src/mesa/main/glheader.h b/src/mesa/main/glheader.h index b27f8d2f78e..7fcf3073526 100644 --- a/src/mesa/main/glheader.h +++ b/src/mesa/main/glheader.h @@ -1,4 +1,20 @@ -/* $Id: glheader.h,v 1.29 2002/10/30 19:44:41 brianp Exp $ */ +/** + * \file glheader.h + * \brief Top-most include file. + * + * This is the top-most include file of the Mesa sources. + * It includes gl.h and all system headers which are needed. + * Other Mesa source files should _not_ directly include any system + * headers. This allows Mesa to be integrated into XFree86 and + * allows system-dependent hacks/work-arounds to be collected in one place. + * + * If you touch this file, everything gets recompiled! + * + * This file should be included before any other header in the .c files. + * + * Put compiler/OS/assembly pragmas and macros here to avoid + * cluttering other source files. + */ /* * Mesa 3-D graphics library @@ -24,26 +40,13 @@ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/* $Id: glheader.h,v 1.29.4.1 2003/03/02 00:27:35 jrfonseca Exp $ */ + #ifndef GLHEADER_H #define GLHEADER_H -/* - * This is the top-most include file of the Mesa sources. - * It includes gl.h and all system headers which are needed. - * Other Mesa source files should _not_ directly include any system - * headers. This allows Mesa to be integrated into XFree86 and - * allows system-dependent hacks/work-arounds to be collected in one place. - * - * If you touch this file, everything gets recompiled! - * - * This file should be included before any other header in the .c files. - * - * Put compiler/OS/assembly pragmas and macros here to avoid - * cluttering other source files. - */ - #if defined(XFree86LOADER) && defined(IN_MODULE) @@ -282,7 +285,7 @@ typedef struct tagPIXELFORMATDESCRIPTOR PIXELFORMATDESCRIPTOR, *PPIXELFORMATDESC #endif -/* +/** * Sometimes we treat GLfloats as GLints. On x86 systems, moving a float * as a int (thereby using integer registers instead of fp registers) is * a performance win. Typically, this can be done with ordinary casts. diff --git a/src/mesa/main/mtypes.h b/src/mesa/main/mtypes.h index fde7e3fab2c..94390486321 100644 --- a/src/mesa/main/mtypes.h +++ b/src/mesa/main/mtypes.h @@ -1,4 +1,9 @@ -/* $Id: mtypes.h,v 1.97 2002/10/21 15:52:34 brianp Exp $ */ +/** + * \file mtypes.h + * \brief Main Mesa data structures. + * + * Please try to mark derived values with a leading underscore ('_'). + */ /* * Mesa 3-D graphics library @@ -24,10 +29,8 @@ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ -/** - * \file mtypes.h - * \brief Main Mesa data structures. - */ +/* $Id: mtypes.h,v 1.97.4.1 2003/03/02 00:27:35 jrfonseca Exp $ */ + #ifndef TYPES_H #define TYPES_H @@ -45,11 +48,8 @@ #endif -/* Please try to mark derived values with a leading underscore ('_'). - */ - -/* - * Color channel data type: +/** + * \brief Color channel data type. */ #if CHAN_BITS == 8 typedef GLubyte GLchan; @@ -72,7 +72,7 @@ /** - * Accumulation buffer data type: + * \brief Accumulation buffer data type. */ #if ACCUM_BITS==8 typedef GLbyte GLaccum; @@ -86,7 +86,7 @@ /** - * Stencil buffer data type: + * \brief Stencil buffer data type. */ #if STENCIL_BITS==8 typedef GLubyte GLstencil; @@ -100,51 +100,60 @@ /** - * Depth buffer data type: + * \brief Depth buffer data type. + * + * \note Must be 32-bits! */ -typedef GLuint GLdepth; /* Must be 32-bits! */ +typedef GLuint GLdepth; /** - * Fixed point data type: + * \brief Fixed point data type. */ typedef int GLfixed; /** - * Some forward type declarations + * \name Some forward type declarations */ +/*@{*/ struct _mesa_HashTable; struct gl_texture_image; struct gl_texture_object; typedef struct __GLcontextRec GLcontext; typedef struct __GLcontextModesRec GLvisual; typedef struct gl_frame_buffer GLframebuffer; +/*@}*/ -/* These define the aliases between numbered vertex attributes and +/** + * These define the aliases between numbered vertex attributes and * conventional OpenGL vertex attributes. We use these values in - * quite a few places. New in Mesa 4.1. + * quite a few places. + * + * New in Mesa 4.1. */ -#define VERT_ATTRIB_POS 0 -#define VERT_ATTRIB_WEIGHT 1 -#define VERT_ATTRIB_NORMAL 2 -#define VERT_ATTRIB_COLOR0 3 -#define VERT_ATTRIB_COLOR1 4 -#define VERT_ATTRIB_FOG 5 -#define VERT_ATTRIB_SIX 6 -#define VERT_ATTRIB_SEVEN 7 -#define VERT_ATTRIB_TEX0 8 -#define VERT_ATTRIB_TEX1 9 -#define VERT_ATTRIB_TEX2 10 -#define VERT_ATTRIB_TEX3 11 -#define VERT_ATTRIB_TEX4 12 -#define VERT_ATTRIB_TEX5 13 -#define VERT_ATTRIB_TEX6 14 -#define VERT_ATTRIB_TEX7 15 -#define VERT_ATTRIB_MAX 16 +enum { + VERT_ATTRIB_POS = 0, + VERT_ATTRIB_WEIGHT = 1, + VERT_ATTRIB_NORMAL = 2, + VERT_ATTRIB_COLOR0 = 3, + VERT_ATTRIB_COLOR1 = 4, + VERT_ATTRIB_FOG = 5, + VERT_ATTRIB_SIX = 6, + VERT_ATTRIB_SEVEN = 7, + VERT_ATTRIB_TEX0 = 8, + VERT_ATTRIB_TEX1 = 9, + VERT_ATTRIB_TEX2 = 10, + VERT_ATTRIB_TEX3 = 11, + VERT_ATTRIB_TEX4 = 12, + VERT_ATTRIB_TEX5 = 13, + VERT_ATTRIB_TEX6 = 14, + VERT_ATTRIB_TEX7 = 15, + VERT_ATTRIB_MAX = 16, +} ; /* These are used in bitfields in many places */ #define VERT_BIT_POS (1 << VERT_ATTRIB_POS) @@ -169,19 +178,22 @@ typedef struct gl_frame_buffer GLframebuffer; /** - * Maximum number of temporary vertices required for clipping. (Used - * in array_cache and tnl modules). + * Maximum number of temporary vertices required for clipping. + * + * Used in array_cache and tnl modules. */ #define MAX_CLIPPED_VERTICES ((2 * (6 + MAX_CLIP_PLANES))+1) -/* Data structure for color tables */ +/** + * \brief Data structure for color tables + */ struct gl_color_table { - GLenum Format; /* GL_ALPHA, GL_RGB, GL_RGB, etc */ + GLenum Format; /**< \brief GL_ALPHA, GL_RGB, GL_RGB, etc */ GLenum IntFormat; - GLuint Size; /* number of entries (rows) in table */ - GLvoid *Table; /* either GLfloat * or GLchan * */ - GLboolean FloatTable; /* are entries stored as floats? */ + GLuint Size; /**< \brief number of entries (rows) in table */ + GLvoid *Table; /**< \brief either GLfloat * or GLchan * */ + GLboolean FloatTable; /**< \brief are entries stored as floats? */ GLubyte RedSize; GLubyte GreenSize; GLubyte BlueSize; @@ -219,12 +231,13 @@ struct gl_color_table { -/* - * Specular exponent and material shininess lookup table sizes: - */ -#define EXP_TABLE_SIZE 512 -#define SHINE_TABLE_SIZE 256 +#define EXP_TABLE_SIZE 512 /**< \brief Specular exponent lookup table sizes */ +#define SHINE_TABLE_SIZE 256 /**< \brief Material shininess lookup table sizes */ + +/** + * \brief Material shininess lookup table. + */ struct gl_shine_tab { struct gl_shine_tab *next, *prev; GLfloat tab[SHINE_TABLE_SIZE+1]; @@ -233,50 +246,63 @@ struct gl_shine_tab { }; +/** + * \brief Light. + */ struct gl_light { - struct gl_light *next; /* double linked list with sentinel */ + struct gl_light *next; /**< \brief double linked list with sentinel */ struct gl_light *prev; - GLfloat Ambient[4]; /* ambient color */ - GLfloat Diffuse[4]; /* diffuse color */ - GLfloat Specular[4]; /* specular color */ - GLfloat EyePosition[4]; /* position in eye coordinates */ - GLfloat EyeDirection[4]; /* spotlight dir in eye coordinates */ + GLfloat Ambient[4]; /**< \brief ambient color */ + GLfloat Diffuse[4]; /**< \brief diffuse color */ + GLfloat Specular[4]; /**< \brief specular color */ + GLfloat EyePosition[4]; /**< \brief position in eye coordinates */ + GLfloat EyeDirection[4]; /**< \brief spotlight dir in eye coordinates */ GLfloat SpotExponent; - GLfloat SpotCutoff; /* in degress */ - GLfloat _CosCutoff; /* = MAX(0, cos(SpotCutoff)) */ + GLfloat SpotCutoff; /**< \brief in degress */ + GLfloat _CosCutoff; /**< \brief = MAX(0, cos(SpotCutoff)) */ GLfloat ConstantAttenuation; GLfloat LinearAttenuation; GLfloat QuadraticAttenuation; - GLboolean Enabled; /* On/off flag */ + GLboolean Enabled; /**< \brief On/off flag */ - /* Derived fields */ - GLuint _Flags; /* State */ + /** + * \name Derived fields + */ + /*@{*/ + GLuint _Flags; /**< \brief State */ - GLfloat _Position[4]; /* position in eye/obj coordinates */ - GLfloat _VP_inf_norm[3]; /* Norm direction to infinite light */ - GLfloat _h_inf_norm[3]; /* Norm( _VP_inf_norm + <0,0,1> ) */ - GLfloat _NormDirection[4]; /* normalized spotlight direction */ + GLfloat _Position[4]; /**< \brief position in eye/obj coordinates */ + GLfloat _VP_inf_norm[3]; /**< \brief Norm direction to infinite light */ + GLfloat _h_inf_norm[3]; /**< \brief Norm( _VP_inf_norm + <0,0,1> ) */ + GLfloat _NormDirection[4]; /**< \brief normalized spotlight direction */ GLfloat _VP_inf_spot_attenuation; - GLfloat _SpotExpTable[EXP_TABLE_SIZE][2]; /* to replace a pow() call */ - GLfloat _MatAmbient[2][3]; /* material ambient * light ambient */ - GLfloat _MatDiffuse[2][3]; /* material diffuse * light diffuse */ - GLfloat _MatSpecular[2][3]; /* material spec * light specular */ - GLfloat _dli; /* CI diffuse light intensity */ - GLfloat _sli; /* CI specular light intensity */ + GLfloat _SpotExpTable[EXP_TABLE_SIZE][2]; /**< \brief to replace a pow() call */ + GLfloat _MatAmbient[2][3]; /**< \brief material ambient * light ambient */ + GLfloat _MatDiffuse[2][3]; /**< \brief material diffuse * light diffuse */ + GLfloat _MatSpecular[2][3]; /**< \brief material spec * light specular */ + GLfloat _dli; /**< \brief CI diffuse light intensity */ + GLfloat _sli; /**< \brief CI specular light intensity */ + /*@}*/ }; +/** + * \brief Light model. + */ struct gl_lightmodel { - GLfloat Ambient[4]; /* ambient color */ - GLboolean LocalViewer; /* Local (or infinite) view point? */ - GLboolean TwoSide; /* Two (or one) sided lighting? */ - GLenum ColorControl; /* either GL_SINGLE_COLOR */ - /* or GL_SEPARATE_SPECULAR_COLOR */ + GLfloat Ambient[4]; /**< \brief ambient color */ + GLboolean LocalViewer; /**< \brief Local (or infinite) view point? */ + GLboolean TwoSide; /**< \brief Two (or one) sided lighting? */ + GLenum ColorControl; /**< \brief either GL_SINGLE_COLOR + * or GL_SEPARATE_SPECULAR_COLOR */ }; +/** + * \brief Material. + */ struct gl_material { GLfloat Ambient[4]; @@ -284,19 +310,20 @@ struct gl_material GLfloat Specular[4]; GLfloat Emission[4]; GLfloat Shininess; - GLfloat AmbientIndex; /* for color index lighting */ - GLfloat DiffuseIndex; /* for color index lighting */ - GLfloat SpecularIndex; /* for color index lighting */ + GLfloat AmbientIndex; /**< \brief for color index lighting */ + GLfloat DiffuseIndex; /**< \brief for color index lighting */ + GLfloat SpecularIndex; /**< \brief for color index lighting */ }; -/* - * Attribute structures: - * We define a struct for each attribute group to make pushing and - * popping attributes easy. Also it's a good organization. +/** + * \brief Attribute structures. + * + * We define a struct for each attribute group to make pushing and popping + * attributes easy. Also it's a good organization. */ struct gl_accum_attrib { - GLfloat ClearColor[4]; /* Accumulation buffer clear color */ + GLfloat ClearColor[4]; /**< \brief Accumulation buffer clear color */ }; @@ -312,69 +339,102 @@ struct gl_accum_attrib { #define AUX2_BIT 0x40 #define AUX3_BIT 0x80 + +/** + * \brief Color buffers attributes. + */ struct gl_colorbuffer_attrib { - GLuint ClearIndex; /* Index to use for glClear */ - GLclampf ClearColor[4]; /* Color to use for glClear */ + GLuint ClearIndex; /**< \brief Index to use for glClear */ + GLclampf ClearColor[4]; /**< \brief Color to use for glClear */ - GLuint IndexMask; /* Color index write mask */ - GLubyte ColorMask[4]; /* Each flag is 0xff or 0x0 */ + GLuint IndexMask; /**< \brief Color index write mask */ + GLubyte ColorMask[4]; /**< \brief Each flag is 0xff or 0x0 */ - GLenum DrawBuffer; /* Which buffer to draw into */ - GLubyte _DrawDestMask; /* bitwise-OR of FRONT/BACK_LEFT/RIGHT_BITs */ + GLenum DrawBuffer; /**< \brief Which buffer to draw into */ + GLubyte _DrawDestMask; /**< \brief bitwise-OR of FRONT/BACK_LEFT/RIGHT_BITs */ - /* alpha testing */ - GLboolean AlphaEnabled; /* Alpha test enabled flag */ - GLenum AlphaFunc; /* Alpha test function */ + /** + * \name alpha testing + */ + /*@{*/ + GLboolean AlphaEnabled; /**< \brief Alpha test enabled flag */ + GLenum AlphaFunc; /**< \brief Alpha test function */ GLclampf AlphaRef; + /*@}*/ - /* blending */ - GLboolean BlendEnabled; /* Blending enabled flag */ - GLenum BlendSrcRGB; /* Blending source operator */ - GLenum BlendDstRGB; /* Blending destination operator */ - GLenum BlendSrcA; /* GL_INGR_blend_func_separate */ - GLenum BlendDstA; /* GL_INGR_blend_func_separate */ + /** + * \name blending + */ + /*@{*/ + GLboolean BlendEnabled; /**< \brief Blending enabled flag */ + GLenum BlendSrcRGB; /**< \brief Blending source operator */ + GLenum BlendDstRGB; /**< \brief Blending destination operator */ + GLenum BlendSrcA; /**< \brief GL_INGR_blend_func_separate */ + GLenum BlendDstA; /**< \brief GL_INGR_blend_func_separate */ GLenum BlendEquation; GLfloat BlendColor[4]; + /*@}*/ - /* logic op */ - GLenum LogicOp; /* Logic operator */ - GLboolean IndexLogicOpEnabled; /* Color index logic op enabled flag */ - GLboolean ColorLogicOpEnabled; /* RGBA logic op enabled flag */ + /** + * \name logic op + */ + /*@{*/ + GLenum LogicOp; /**< \brief Logic operator */ + GLboolean IndexLogicOpEnabled; /**< \brief Color index logic op enabled flag */ + GLboolean ColorLogicOpEnabled; /**< \brief RGBA logic op enabled flag */ + /*@}*/ - GLboolean DitherFlag; /* Dither enable flag */ + GLboolean DitherFlag; /**< \brief Dither enable flag */ }; +/** + * \brief Current attributes. + */ struct gl_current_attrib { - /* These values valid only when FLUSH_VERTICES has been called. + /** + * \name Values valid only when FLUSH_VERTICES has been called. */ - GLfloat Attrib[VERT_ATTRIB_MAX][4]; /* Current vertex attributes */ - /* indexed by VERT_ATTRIB_* */ - GLuint Index; /* Current color index */ - GLboolean EdgeFlag; /* Current edge flag */ + /*@{*/ + GLfloat Attrib[VERT_ATTRIB_MAX][4]; /**< \brief Current vertex attributes + * indexed by VERT_ATTRIB_* */ + GLuint Index; /**< \brief Current color index */ + GLboolean EdgeFlag; /**< \brief Current edge flag */ + /*@}*/ - /* These values are always valid. BTW, note how similar this set of - * attributes is to the SWvertex datatype in the software rasterizer... + /** + * \name Values are always valid. + * + * \note BTW, note how similar this set of attributes is to the SWvertex datatype + * in the software rasterizer... */ - GLfloat RasterPos[4]; /* Current raster position */ - GLfloat RasterDistance; /* Current raster distance */ - GLfloat RasterColor[4]; /* Current raster color */ - GLfloat RasterSecondaryColor[4]; /* Current rast 2ndary color */ - GLuint RasterIndex; /* Current raster index */ - GLfloat RasterTexCoords[MAX_TEXTURE_UNITS][4];/* Current raster texcoords */ - GLboolean RasterPosValid; /* Raster pos valid flag */ + /*@{*/ + GLfloat RasterPos[4]; /**< \brief Current raster position */ + GLfloat RasterDistance; /**< \brief Current raster distance */ + GLfloat RasterColor[4]; /**< \brief Current raster color */ + GLfloat RasterSecondaryColor[4]; /**< \brief Current raster secondary color */ + GLuint RasterIndex; /**< \brief Current raster index */ + GLfloat RasterTexCoords[MAX_TEXTURE_UNITS][4];/**< \brief Current raster texcoords */ + GLboolean RasterPosValid; /**< \brief Raster pos valid flag */ + /*@}*/ }; +/** + * \brief Depth buffer attributes. + */ struct gl_depthbuffer_attrib { - GLenum Func; /* Function for depth buffer compare */ - GLfloat Clear; /* Value to clear depth buffer to */ - GLboolean Test; /* Depth buffering enabled flag */ - GLboolean Mask; /* Depth buffer writable? */ - GLboolean OcclusionTest; /* GL_HP_occlusion_test */ + GLenum Func; /**< \brief Function for depth buffer compare */ + GLfloat Clear; /**< \brief Value to clear depth buffer to */ + GLboolean Test; /**< \brief Depth buffering enabled flag */ + GLboolean Mask; /**< \brief Depth buffer writable? */ + GLboolean OcclusionTest; /**< \brief GL_HP_occlusion_test */ }; +/** + * \brief glEnable()/glDisable() attributes. + */ struct gl_enable_attrib { GLboolean AlphaTest; GLboolean AutoNormal; @@ -442,8 +502,14 @@ struct gl_enable_attrib { }; +/** + * \brief Eval attributes. + */ struct gl_eval_attrib { - /* Enable bits */ + /** + * \name Enable bits + */ + /*@{*/ GLboolean Map1Color4; GLboolean Map1Index; GLboolean Map1Normal; @@ -465,47 +531,63 @@ struct gl_eval_attrib { GLboolean Map2Vertex4; GLboolean Map2Attrib[16]; /* GL_NV_vertex_program */ GLboolean AutoNormal; - /* Map Grid endpoints and divisions and calculated du values */ + /*@}*/ + + /** + * \name Map Grid endpoints and divisions and calculated du values + */ + /*@{*/ GLint MapGrid1un; GLfloat MapGrid1u1, MapGrid1u2, MapGrid1du; GLint MapGrid2un, MapGrid2vn; GLfloat MapGrid2u1, MapGrid2u2, MapGrid2du; GLfloat MapGrid2v1, MapGrid2v2, MapGrid2dv; + /*@}*/ }; +/** + * \brief Fog attributes. + */ struct gl_fog_attrib { - GLboolean Enabled; /* Fog enabled flag */ - GLfloat Color[4]; /* Fog color */ - GLfloat Density; /* Density >= 0.0 */ - GLfloat Start; /* Start distance in eye coords */ - GLfloat End; /* End distance in eye coords */ - GLfloat Index; /* Fog index */ - GLenum Mode; /* Fog mode */ + GLboolean Enabled; /**< \brief Fog enabled flag */ + GLfloat Color[4]; /**< \brief Fog color */ + GLfloat Density; /**< \brief Density >= 0.0 */ + GLfloat Start; /**< \brief Start distance in eye coords */ + GLfloat End; /**< \brief End distance in eye coords */ + GLfloat Index; /**< \brief Fog index */ + GLenum Mode; /**< \brief Fog mode */ GLboolean ColorSumEnabled; - GLenum FogCoordinateSource; /* GL_EXT_fog_coord */ + GLenum FogCoordinateSource; /**< \brief GL_EXT_fog_coord */ }; +/** + * \brief Hint attributes. + * + * Values are always one of GL_FASTEST, GL_NICEST, or GL_DONT_CARE. + */ struct gl_hint_attrib { - /* always one of GL_FASTEST, GL_NICEST, or GL_DONT_CARE */ GLenum PerspectiveCorrection; GLenum PointSmooth; GLenum LineSmooth; GLenum PolygonSmooth; GLenum Fog; - GLenum ClipVolumeClipping; /* GL_EXT_clip_volume_hint */ - GLenum TextureCompression; /* GL_ARB_texture_compression */ - GLenum GenerateMipmap; /* GL_SGIS_generate_mipmap */ + GLenum ClipVolumeClipping; /**< \brief GL_EXT_clip_volume_hint */ + GLenum TextureCompression; /**< \brief GL_ARB_texture_compression */ + GLenum GenerateMipmap; /**< \brief GL_SGIS_generate_mipmap */ }; +/** + * \brief Histogram attributes. + */ struct gl_histogram_attrib { - GLuint Width; /* number of table entries */ - GLint Format; /* GL_ALPHA, GL_RGB, etc */ - GLuint Count[HISTOGRAM_TABLE_SIZE][4]; /* the histogram */ - GLboolean Sink; /* terminate image transfer? */ - GLubyte RedSize; /* Bits per counter */ + GLuint Width; /**< \brief number of table entries */ + GLint Format; /**< \brief GL_ALPHA, GL_RGB, etc */ + GLuint Count[HISTOGRAM_TABLE_SIZE][4]; /**< \brief the histogram */ + GLboolean Sink; /**< \brief terminate image transfer? */ + GLubyte RedSize; /**< \brief Bits per counter */ GLubyte GreenSize; GLubyte BlueSize; GLubyte AlphaSize; @@ -516,7 +598,7 @@ struct gl_histogram_attrib { struct gl_minmax_attrib { GLenum Format; GLboolean Sink; - GLfloat Min[4], Max[4]; /* RGBA */ + GLfloat Min[4], Max[4]; /**< \brief RGBA */ }; @@ -535,29 +617,39 @@ struct gl_convolution_attrib { #define LIGHT_NEED_VERTICES (LIGHT_POSITIONAL|LIGHT_LOCAL_VIEWER) struct gl_light_attrib { - struct gl_light Light[MAX_LIGHTS]; /* Array of lights */ - struct gl_lightmodel Model; /* Lighting model */ + struct gl_light Light[MAX_LIGHTS]; /**< \brief Array of lights */ + struct gl_lightmodel Model; /**< \brief Lighting model */ - /* Must flush FLUSH_VERTICES before referencing: + /** + * Must flush FLUSH_VERTICES before referencing: */ - struct gl_material Material[2]; /* Material 0=front, 1=back */ + /*@{*/ + struct gl_material Material[2]; /**< \brief Material 0=front, 1=back */ + /*@}*/ - GLboolean Enabled; /* Lighting enabled flag */ - GLenum ShadeModel; /* GL_FLAT or GL_SMOOTH */ - GLenum ColorMaterialFace; /* GL_FRONT, BACK or FRONT_AND_BACK */ - GLenum ColorMaterialMode; /* GL_AMBIENT, GL_DIFFUSE, etc */ - GLuint ColorMaterialBitmask; /* bitmask formed from Face and Mode */ + GLboolean Enabled; /**< \brief Lighting enabled flag */ + GLenum ShadeModel; /**< \brief GL_FLAT or GL_SMOOTH */ + GLenum ColorMaterialFace; /**< \brief GL_FRONT, BACK or FRONT_AND_BACK */ + GLenum ColorMaterialMode; /**< \brief GL_AMBIENT, GL_DIFFUSE, etc */ + GLuint ColorMaterialBitmask; /**< \brief bitmask formed from Face and Mode */ GLboolean ColorMaterialEnabled; - struct gl_light EnabledList; /* List sentinel */ + struct gl_light EnabledList; /**< \brief List sentinel */ - /* Derived for optimizations: */ - GLboolean _NeedVertices; /* Use fast shader? */ - GLuint _Flags; /* LIGHT_* flags, see above */ + /** + * Derived for optimizations: + */ + /*@{*/ + GLboolean _NeedVertices; /**< \brief Use fast shader? */ + GLuint _Flags; /**< \brief LIGHT_* flags, see above */ GLfloat _BaseColor[2][3]; + /*@}*/ }; +/** + * \brief Line attributes. + */ struct gl_line_attrib { GLboolean SmoothFlag; /* GL_LINE_SMOOTH enabled? */ GLboolean StippleFlag; /* GL_LINE_STIPPLE enabled? */ @@ -598,11 +690,14 @@ struct gl_multisample_attrib { }; +/** + * \brief Pixel attributes. + */ struct gl_pixel_attrib { - GLenum ReadBuffer; /* src buffer for glRead/CopyPixels */ - GLubyte _ReadSrcMask; /* Not really a mask, but like _DrawDestMask */ - /* May be: FRONT_LEFT_BIT, BACK_LEFT_BIT, */ - /* FRONT_RIGHT_BIT or BACK_RIGHT_BIT. */ + GLenum ReadBuffer; /**< \brief src buffer for glRead/CopyPixels */ + GLubyte _ReadSrcMask; /**< \brief Not really a mask, but like _DrawDestMask + * May be: FRONT_LEFT_BIT, BACK_LEFT_BIT, + * FRONT_RIGHT_BIT or BACK_RIGHT_BIT. */ GLfloat RedBias, RedScale; GLfloat GreenBias, GreenScale; GLfloat BlueBias, BlueScale; @@ -613,7 +708,7 @@ struct gl_pixel_attrib { GLboolean MapStencilFlag; GLfloat ZoomX, ZoomY; /* XXX move these out of gl_pixel_attrib */ - GLint MapStoSsize; /* Size of each pixel map */ + GLint MapStoSsize; /**< \brief Size of each pixel map */ GLint MapItoIsize; GLint MapItoRsize; GLint MapItoGsize; @@ -623,13 +718,13 @@ struct gl_pixel_attrib { GLint MapGtoGsize; GLint MapBtoBsize; GLint MapAtoAsize; - GLint MapStoS[MAX_PIXEL_MAP_TABLE]; /* Pixel map tables */ + GLint MapStoS[MAX_PIXEL_MAP_TABLE]; /**< \brief Pixel map tables */ GLint MapItoI[MAX_PIXEL_MAP_TABLE]; GLfloat MapItoR[MAX_PIXEL_MAP_TABLE]; GLfloat MapItoG[MAX_PIXEL_MAP_TABLE]; GLfloat MapItoB[MAX_PIXEL_MAP_TABLE]; GLfloat MapItoA[MAX_PIXEL_MAP_TABLE]; - GLubyte MapItoR8[MAX_PIXEL_MAP_TABLE]; /* converted to 8-bit color */ + GLubyte MapItoR8[MAX_PIXEL_MAP_TABLE]; /**< \brief converted to 8-bit color */ GLubyte MapItoG8[MAX_PIXEL_MAP_TABLE]; GLubyte MapItoB8[MAX_PIXEL_MAP_TABLE]; GLubyte MapItoA8[MAX_PIXEL_MAP_TABLE]; @@ -637,17 +732,17 @@ struct gl_pixel_attrib { GLfloat MapGtoG[MAX_PIXEL_MAP_TABLE]; GLfloat MapBtoB[MAX_PIXEL_MAP_TABLE]; GLfloat MapAtoA[MAX_PIXEL_MAP_TABLE]; - /* GL_EXT_histogram */ + /** GL_EXT_histogram */ GLboolean HistogramEnabled; GLboolean MinMaxEnabled; - /* GL_SGIS_pixel_texture */ + /** GL_SGIS_pixel_texture */ GLboolean PixelTextureEnabled; GLenum FragmentRgbSource; GLenum FragmentAlphaSource; - /* GL_SGI_color_matrix */ - GLfloat PostColorMatrixScale[4]; /* RGBA */ - GLfloat PostColorMatrixBias[4]; /* RGBA */ - /* GL_SGI_color_table */ + /** GL_SGI_color_matrix */ + GLfloat PostColorMatrixScale[4]; /**< \brief RGBA */ + GLfloat PostColorMatrixBias[4]; /**< \brief RGBA */ + /** GL_SGI_color_table */ GLfloat ColorTableScale[4]; GLfloat ColorTableBias[4]; GLboolean ColorTableEnabled; @@ -657,7 +752,7 @@ struct gl_pixel_attrib { GLfloat PCMCTscale[4]; GLfloat PCMCTbias[4]; GLboolean PostColorMatrixColorTableEnabled; - /* Convolution */ + /** Convolution */ GLboolean Convolution1DEnabled; GLboolean Convolution2DEnabled; GLboolean Separable2DEnabled; @@ -665,61 +760,73 @@ struct gl_pixel_attrib { GLenum ConvolutionBorderMode[3]; GLfloat ConvolutionFilterScale[3][4]; GLfloat ConvolutionFilterBias[3][4]; - GLfloat PostConvolutionScale[4]; /* RGBA */ - GLfloat PostConvolutionBias[4]; /* RGBA */ + GLfloat PostConvolutionScale[4]; /**< \brief RGBA */ + GLfloat PostConvolutionBias[4]; /**< \brief RGBA */ }; +/** + * \brief Point attributes. + */ struct gl_point_attrib { - GLboolean SmoothFlag; /* True if GL_POINT_SMOOTH is enabled */ - GLfloat Size; /* User-specified point size */ - GLfloat _Size; /* Size clamped to Const.Min/MaxPointSize */ - GLfloat Params[3]; /* GL_EXT_point_parameters */ - GLfloat MinSize, MaxSize; /* GL_EXT_point_parameters */ - GLfloat Threshold; /* GL_EXT_point_parameters */ - GLboolean _Attenuated; /* True if Params != [1, 0, 0] */ - GLboolean PointSprite; /* GL_NV_point_sprite */ - GLboolean CoordReplace[MAX_TEXTURE_UNITS]; /* GL_NV_point_sprite */ - GLenum SpriteRMode; /* GL_NV_point_sprite */ + GLboolean SmoothFlag; /**< \brief True if GL_POINT_SMOOTH is enabled */ + GLfloat Size; /**< \brief User-specified point size */ + GLfloat _Size; /**< \brief Size clamped to Const.Min/MaxPointSize */ + GLfloat Params[3]; /**< \brief GL_EXT_point_parameters */ + GLfloat MinSize, MaxSize; /**< \brief GL_EXT_point_parameters */ + GLfloat Threshold; /**< \brief GL_EXT_point_parameters */ + GLboolean _Attenuated; /**< \brief True if Params != [1, 0, 0] */ + GLboolean PointSprite; /**< \brief GL_NV_point_sprite */ + GLboolean CoordReplace[MAX_TEXTURE_UNITS]; /**< \brief GL_NV_point_sprite */ + GLenum SpriteRMode; /**< \brief GL_NV_point_sprite */ }; +/** + * \brief Polygon attributes. + */ struct gl_polygon_attrib { - GLenum FrontFace; /* Either GL_CW or GL_CCW */ - GLenum FrontMode; /* Either GL_POINT, GL_LINE or GL_FILL */ - GLenum BackMode; /* Either GL_POINT, GL_LINE or GL_FILL */ - GLboolean _FrontBit; /* 0=GL_CCW, 1=GL_CW */ - GLboolean CullFlag; /* Culling on/off flag */ - GLboolean SmoothFlag; /* True if GL_POLYGON_SMOOTH is enabled */ - GLboolean StippleFlag; /* True if GL_POLYGON_STIPPLE is enabled */ - GLenum CullFaceMode; /* Culling mode GL_FRONT or GL_BACK */ - GLfloat OffsetFactor; /* Polygon offset factor, from user */ - GLfloat OffsetUnits; /* Polygon offset units, from user */ - GLboolean OffsetPoint; /* Offset in GL_POINT mode */ - GLboolean OffsetLine; /* Offset in GL_LINE mode */ - GLboolean OffsetFill; /* Offset in GL_FILL mode */ + GLenum FrontFace; /**< \brief Either GL_CW or GL_CCW */ + GLenum FrontMode; /**< \brief Either GL_POINT, GL_LINE or GL_FILL */ + GLenum BackMode; /**< \brief Either GL_POINT, GL_LINE or GL_FILL */ + GLboolean _FrontBit; /**< \brief 0=GL_CCW, 1=GL_CW */ + GLboolean CullFlag; /**< \brief Culling on/off flag */ + GLboolean SmoothFlag; /**< \brief True if GL_POLYGON_SMOOTH is enabled */ + GLboolean StippleFlag; /**< \brief True if GL_POLYGON_STIPPLE is enabled */ + GLenum CullFaceMode; /**< \brief Culling mode GL_FRONT or GL_BACK */ + GLfloat OffsetFactor; /**< \brief Polygon offset factor, from user */ + GLfloat OffsetUnits; /**< \brief Polygon offset units, from user */ + GLboolean OffsetPoint; /**< \brief Offset in GL_POINT mode */ + GLboolean OffsetLine; /**< \brief Offset in GL_LINE mode */ + GLboolean OffsetFill; /**< \brief Offset in GL_FILL mode */ }; +/** + * \brief Scissor attributes. + */ struct gl_scissor_attrib { - GLboolean Enabled; /* Scissor test enabled? */ - GLint X, Y; /* Lower left corner of box */ - GLsizei Width, Height; /* Size of box */ + GLboolean Enabled; /**< \brief Scissor test enabled? */ + GLint X, Y; /**< \brief Lower left corner of box */ + GLsizei Width, Height; /**< \brief Size of box */ }; +/** + * \brief Stencil attributes. + */ struct gl_stencil_attrib { - GLboolean Enabled; /* Enabled flag */ - GLboolean TestTwoSide; /* GL_EXT_stencil_two_side */ - GLubyte ActiveFace; /* GL_EXT_stencil_two_side (0 or 1) */ - GLenum Function[2]; /* Stencil function */ - GLenum FailFunc[2]; /* Fail function */ - GLenum ZPassFunc[2]; /* Depth buffer pass function */ - GLenum ZFailFunc[2]; /* Depth buffer fail function */ - GLstencil Ref[2]; /* Reference value */ - GLstencil ValueMask[2]; /* Value mask */ - GLstencil WriteMask[2]; /* Write mask */ - GLstencil Clear; /* Clear value */ + GLboolean Enabled; /**< \brief Enabled flag */ + GLboolean TestTwoSide; /**< \brief GL_EXT_stencil_two_side */ + GLubyte ActiveFace; /**< \brief GL_EXT_stencil_two_side (0 or 1) */ + GLenum Function[2]; /**< \brief Stencil function */ + GLenum FailFunc[2]; /**< \brief Fail function */ + GLenum ZPassFunc[2]; /**< \brief Depth buffer pass function */ + GLenum ZFailFunc[2]; /**< \brief Depth buffer fail function */ + GLstencil Ref[2]; /**< \brief Reference value */ + GLstencil ValueMask[2]; /**< \brief Value mask */ + GLstencil WriteMask[2]; /**< \brief Write mask */ + GLstencil Clear; /**< \brief Clear value */ }; @@ -736,7 +843,7 @@ struct gl_stencil_attrib { #define TEXTURE_CUBE_BIT 0x08 #define TEXTURE_RECT_BIT 0x10 -#define NUM_TEXTURE_TARGETS 5 /* 1D, 2D, 3D, CUBE and RECT */ +#define NUM_TEXTURE_TARGETS 5 /**< \brief 1D, 2D, 3D, CUBE and RECT */ /* Bitmap versions of the GL_ constants. */ @@ -778,7 +885,7 @@ struct gl_stencil_attrib { #define ENABLE_TEXGEN(i) (ENABLE_TEXGEN0 << (i)) #define ENABLE_TEXMAT(i) (ENABLE_TEXMAT0 << (i)) -/* +/** * If teximage is color-index, texelOut returns GLchan[1]. * If teximage is depth, texelOut returns GLfloat[1]. * Otherwise, texelOut returns GLchan[4]. @@ -787,137 +894,164 @@ typedef void (*FetchTexelFunc)( const struct gl_texture_image *texImage, GLint col, GLint row, GLint img, GLvoid *texelOut ); -/* Texture format record */ +/** + * \brief Texture format record + */ struct gl_texture_format { - GLint MesaFormat; /* One of the MESA_FORMAT_* values */ + GLint MesaFormat; /**< \brief One of the MESA_FORMAT_* values */ - GLenum BaseFormat; /* Either GL_ALPHA, GL_INTENSITY, GL_LUMINANCE, - * GL_LUMINANCE_ALPHA, GL_RGB, GL_RGBA, - * GL_COLOR_INDEX or GL_DEPTH_COMPONENT. + GLenum BaseFormat; /**< \brief Either GL_ALPHA, GL_INTENSITY, GL_LUMINANCE, + * GL_LUMINANCE_ALPHA, GL_RGB, GL_RGBA, + * GL_COLOR_INDEX or GL_DEPTH_COMPONENT. */ - GLubyte RedBits; /* Bits per texel component */ - GLubyte GreenBits; /* These are just rough approximations for */ - GLubyte BlueBits; /* compressed texture formats. */ + GLubyte RedBits; /**< \brief Bits per texel component */ + GLubyte GreenBits; /**< \brief These are just rough approximations for */ + GLubyte BlueBits; /**< \brief compressed texture formats. */ GLubyte AlphaBits; GLubyte LuminanceBits; GLubyte IntensityBits; GLubyte IndexBits; GLubyte DepthBits; - GLint TexelBytes; /* Bytes per texel (0 for compressed formats */ + GLint TexelBytes; /**< \brief Bytes per texel (0 for compressed formats */ - FetchTexelFunc FetchTexel1D; /* Texel fetch function pointers */ + FetchTexelFunc FetchTexel1D; /**< \brief Texel fetch function pointers */ FetchTexelFunc FetchTexel2D; FetchTexelFunc FetchTexel3D; }; -/* Texture image record */ +/** + * \brief Texture image record + */ struct gl_texture_image { - GLenum Format; /* GL_ALPHA, GL_LUMINANCE, GL_LUMINANCE_ALPHA, - * GL_INTENSITY, GL_RGB, GL_RGBA, - * GL_COLOR_INDEX or GL_DEPTH_COMPONENT only. - * Used for choosing TexEnv arithmetic. + GLenum Format; /**< \brief GL_ALPHA, GL_LUMINANCE, GL_LUMINANCE_ALPHA, + * GL_INTENSITY, GL_RGB, GL_RGBA, + * GL_COLOR_INDEX or GL_DEPTH_COMPONENT only. + * Used for choosing TexEnv arithmetic. */ - GLint IntFormat; /* Internal format as given by the user */ - GLuint Border; /* 0 or 1 */ - GLuint Width; /* = 2^WidthLog2 + 2*Border */ - GLuint Height; /* = 2^HeightLog2 + 2*Border */ - GLuint Depth; /* = 2^DepthLog2 + 2*Border */ - GLuint RowStride; /* == Width unless IsClientData and padded */ - GLuint Width2; /* = Width - 2*Border */ - GLuint Height2; /* = Height - 2*Border */ - GLuint Depth2; /* = Depth - 2*Border */ - GLuint WidthLog2; /* = log2(Width2) */ - GLuint HeightLog2; /* = log2(Height2) */ - GLuint DepthLog2; /* = log2(Depth2) */ - GLuint MaxLog2; /* = MAX(WidthLog2, HeightLog2) */ - GLfloat WidthScale; /* used for mipmap lod computation */ - GLfloat HeightScale; /* used for mipmap lod computation */ - GLfloat DepthScale; /* used for mipmap lod computation */ - GLvoid *Data; /* Image data, accessed via FetchTexel() */ - GLboolean IsClientData; /* Data owned by client? */ + GLint IntFormat; /**< \brief Internal format as given by the user */ + GLuint Border; /**< \brief 0 or 1 */ + GLuint Width; /**< \brief = 2^WidthLog2 + 2*Border */ + GLuint Height; /**< \brief = 2^HeightLog2 + 2*Border */ + GLuint Depth; /**< \brief = 2^DepthLog2 + 2*Border */ + GLuint RowStride; /**< \brief == Width unless IsClientData and padded */ + GLuint Width2; /**< \brief = Width - 2*Border */ + GLuint Height2; /**< \brief = Height - 2*Border */ + GLuint Depth2; /**< \brief = Depth - 2*Border */ + GLuint WidthLog2; /**< \brief = log2(Width2) */ + GLuint HeightLog2; /**< \brief = log2(Height2) */ + GLuint DepthLog2; /**< \brief = log2(Depth2) */ + GLuint MaxLog2; /**< \brief = MAX(WidthLog2, HeightLog2) */ + GLfloat WidthScale; /**< \brief used for mipmap lod computation */ + GLfloat HeightScale; /**< \brief used for mipmap lod computation */ + GLfloat DepthScale; /**< \brief used for mipmap lod computation */ + GLvoid *Data; /**< \brief Image data, accessed via FetchTexel() */ + GLboolean IsClientData; /**< \brief Data owned by client? */ const struct gl_texture_format *TexFormat; - FetchTexelFunc FetchTexel; /* Texel fetch function pointer */ + FetchTexelFunc FetchTexel; /**< \brief Texel fetch function pointer */ - GLboolean IsCompressed; /* GL_ARB_texture_compression */ - GLuint CompressedSize; /* GL_ARB_texture_compression */ + GLboolean IsCompressed; /**< \brief GL_ARB_texture_compression */ + GLuint CompressedSize; /**< \brief GL_ARB_texture_compression */ - /* For device driver: */ - void *DriverData; /* Arbitrary device driver data */ + /** + * \name For device driver: + */ + /*@{*/ + void *DriverData; /**< \brief Arbitrary device driver data */ + /*@}*/ }; -/* Texture object record */ +/** + * \brief Texture object record + */ struct gl_texture_object { - _glthread_Mutex Mutex; /* for thread safety */ - GLint RefCount; /* reference count */ - GLuint Name; /* an unsigned integer */ - GLenum Target; /* GL_TEXTURE_1D, GL_TEXTURE_2D, etc. */ - GLfloat Priority; /* in [0,1] */ - GLfloat BorderColor[4]; /* unclamped */ - GLchan _BorderChan[4]; /* clamped, as GLchan */ - GLenum WrapS; /* Wrap modes are: GL_CLAMP, REPEAT */ - GLenum WrapT; /* GL_CLAMP_TO_EDGE, and */ - GLenum WrapR; /* GL_CLAMP_TO_BORDER_ARB */ - GLenum MinFilter; /* minification filter */ - GLenum MagFilter; /* magnification filter */ - GLfloat MinLod; /* min lambda, OpenGL 1.2 */ - GLfloat MaxLod; /* max lambda, OpenGL 1.2 */ - GLint BaseLevel; /* min mipmap level, OpenGL 1.2 */ - GLint MaxLevel; /* max mipmap level, OpenGL 1.2 */ - GLfloat MaxAnisotropy; /* GL_EXT_texture_filter_anisotropic */ - GLboolean CompareFlag; /* GL_SGIX_shadow */ - GLenum CompareOperator; /* GL_SGIX_shadow */ + _glthread_Mutex Mutex; /**< \brief for thread safety */ + GLint RefCount; /**< \brief reference count */ + GLuint Name; /**< \brief an unsigned integer */ + GLenum Target; /**< \brief GL_TEXTURE_1D, GL_TEXTURE_2D, etc. */ + GLfloat Priority; /**< \brief in [0,1] */ + GLfloat BorderColor[4]; /**< \brief unclamped */ + GLchan _BorderChan[4]; /**< \brief clamped, as GLchan */ + /** \name Wrap modes + * Are GL_CLAMP, REPEAT, GL_CLAMP_TO_EDGE, and GL_CLAMP_TO_BORDER_ARB. */ + /*@{*/ + GLenum WrapS; + GLenum WrapT; + GLenum WrapR; + /*@{*/ + GLenum MinFilter; /**< \brief minification filter */ + GLenum MagFilter; /**< \brief magnification filter */ + GLfloat MinLod; /**< \brief min lambda, OpenGL 1.2 */ + GLfloat MaxLod; /**< \brief max lambda, OpenGL 1.2 */ + GLint BaseLevel; /**< \brief min mipmap level, OpenGL 1.2 */ + GLint MaxLevel; /**< \brief max mipmap level, OpenGL 1.2 */ + GLfloat MaxAnisotropy; /**< \brief GL_EXT_texture_filter_anisotropic */ + GLboolean CompareFlag; /**< \brief GL_SGIX_shadow */ + GLenum CompareOperator; /**< \brief GL_SGIX_shadow */ GLfloat ShadowAmbient; - GLenum CompareMode; /* GL_ARB_shadow */ - GLenum CompareFunc; /* GL_ARB_shadow */ - GLenum DepthMode; /* GL_ARB_depth_texture */ - GLint _MaxLevel; /* actual max mipmap level (q in the spec) */ - GLfloat _MaxLambda; /* = _MaxLevel - BaseLevel (q - b in spec) */ - GLboolean GenerateMipmap; /* GL_SGIS_generate_mipmap */ + GLenum CompareMode; /**< \brief GL_ARB_shadow */ + GLenum CompareFunc; /**< \brief GL_ARB_shadow */ + GLenum DepthMode; /**< \brief GL_ARB_depth_texture */ + GLint _MaxLevel; /**< \brief actual max mipmap level (q in the spec) */ + GLfloat _MaxLambda; /**< \brief = _MaxLevel - BaseLevel (q - b in spec) */ + GLboolean GenerateMipmap; /**< \brief GL_SGIS_generate_mipmap */ struct gl_texture_image *Image[MAX_TEXTURE_LEVELS]; - /* Texture cube faces */ - /* Image[] is alias for *PosX[MAX_TEXTURE_LEVELS]; */ + /** + * \name Texture cube faces + * + * Image[] is alias for *PosX[MAX_TEXTURE_LEVELS]; + */ + /*@{*/ struct gl_texture_image *NegX[MAX_TEXTURE_LEVELS]; struct gl_texture_image *PosY[MAX_TEXTURE_LEVELS]; struct gl_texture_image *NegY[MAX_TEXTURE_LEVELS]; struct gl_texture_image *PosZ[MAX_TEXTURE_LEVELS]; struct gl_texture_image *NegZ[MAX_TEXTURE_LEVELS]; + /*@}*/ - /* GL_EXT_paletted_texture */ + /** \brief GL_EXT_paletted_texture */ struct gl_color_table Palette; - GLboolean Complete; /* Is texture object complete? */ - struct gl_texture_object *Next; /* Next in linked list */ + GLboolean Complete; /**< \brief Is texture object complete? */ + struct gl_texture_object *Next; /**< \brief Next in linked list */ - /* For device driver: */ - void *DriverData; /* Arbitrary device driver data */ + /** + * \name For device driver + */ + /*@{*/ + void *DriverData; /**< \brief Arbitrary device driver data */ + /*@}*/ }; /* Texture unit record */ struct gl_texture_unit { - GLuint Enabled; /* bitmask of TEXTURE_*_BIT flags */ - GLuint _ReallyEnabled; /* 0 or exactly one of TEXTURE_*_BIT flags */ + GLuint Enabled; /**< \brief bitmask of TEXTURE_*_BIT flags */ + GLuint _ReallyEnabled; /**< \brief 0 or exactly one of TEXTURE_*_BIT flags */ - GLenum EnvMode; /* GL_MODULATE, GL_DECAL, GL_BLEND, etc. */ + GLenum EnvMode; /**< \brief GL_MODULATE, GL_DECAL, GL_BLEND, etc. */ GLfloat EnvColor[4]; - GLuint TexGenEnabled; /* Bitwise-OR of [STRQ]_BIT values */ - GLenum GenModeS; /* Tex coord generation mode, either */ - GLenum GenModeT; /* GL_OBJECT_LINEAR, or */ - GLenum GenModeR; /* GL_EYE_LINEAR, or */ - GLenum GenModeQ; /* GL_SPHERE_MAP */ + GLuint TexGenEnabled; /**< \brief Bitwise-OR of [STRQ]_BIT values */ + /** \name Tex coord generation mode + * Either GL_OBJECT_LINEAR, GL_EYE_LINEAR or GL_SPHERE_MAP. */ + /*@{*/ + GLenum GenModeS; + GLenum GenModeT; + GLenum GenModeR; + GLenum GenModeQ; + /*@}*/ GLuint _GenBitS; GLuint _GenBitT; GLuint _GenBitR; GLuint _GenBitQ; - GLuint _GenFlags; /* bitwise or of GenBit[STRQ] */ + GLuint _GenFlags; /**< \brief bitwise or of GenBit[STRQ] */ GLfloat ObjectPlaneS[4]; GLfloat ObjectPlaneT[4]; GLfloat ObjectPlaneR[4]; @@ -926,27 +1060,31 @@ struct gl_texture_unit { GLfloat EyePlaneT[4]; GLfloat EyePlaneR[4]; GLfloat EyePlaneQ[4]; - GLfloat LodBias; /* for biasing mipmap levels */ + GLfloat LodBias; /**< \brief for biasing mipmap levels */ - /* GL_EXT_texture_env_combine */ - GLenum CombineModeRGB; /* GL_REPLACE, GL_DECAL, GL_ADD, etc. */ - GLenum CombineModeA; /* GL_REPLACE, GL_DECAL, GL_ADD, etc. */ - GLenum CombineSourceRGB[3]; /* GL_PRIMARY_COLOR, GL_TEXTURE, etc. */ - GLenum CombineSourceA[3]; /* GL_PRIMARY_COLOR, GL_TEXTURE, etc. */ - GLenum CombineOperandRGB[3]; /* SRC_COLOR, ONE_MINUS_SRC_COLOR, etc */ - GLenum CombineOperandA[3]; /* SRC_ALPHA, ONE_MINUS_SRC_ALPHA, etc */ - GLuint CombineScaleShiftRGB; /* 0, 1 or 2 */ - GLuint CombineScaleShiftA; /* 0, 1 or 2 */ + /** + * \name GL_EXT_texture_env_combine + */ + /*@{*/ + GLenum CombineModeRGB; /**< \brief GL_REPLACE, GL_DECAL, GL_ADD, etc. */ + GLenum CombineModeA; /**< \brief GL_REPLACE, GL_DECAL, GL_ADD, etc. */ + GLenum CombineSourceRGB[3]; /**< \brief GL_PRIMARY_COLOR, GL_TEXTURE, etc. */ + GLenum CombineSourceA[3]; /**< \brief GL_PRIMARY_COLOR, GL_TEXTURE, etc. */ + GLenum CombineOperandRGB[3]; /**< \brief SRC_COLOR, ONE_MINUS_SRC_COLOR, etc */ + GLenum CombineOperandA[3]; /**< \brief SRC_ALPHA, ONE_MINUS_SRC_ALPHA, etc */ + GLuint CombineScaleShiftRGB; /**< \brief 0, 1 or 2 */ + GLuint CombineScaleShiftA; /**< \brief 0, 1 or 2 */ + /*@}*/ struct gl_texture_object *Current1D; struct gl_texture_object *Current2D; struct gl_texture_object *Current3D; - struct gl_texture_object *CurrentCubeMap; /* GL_ARB_texture_cube_map */ - struct gl_texture_object *CurrentRect; /* GL_NV_texture_rectangle */ + struct gl_texture_object *CurrentCubeMap; /**< \brief GL_ARB_texture_cube_map */ + struct gl_texture_object *CurrentRect; /**< \brief GL_NV_texture_rectangle */ - struct gl_texture_object *_Current; /* Points to really enabled tex obj */ + struct gl_texture_object *_Current; /**< \brief Points to really enabled tex obj */ - struct gl_texture_object Saved1D; /* only used by glPush/PopAttrib */ + struct gl_texture_object Saved1D; /**< \brief only used by glPush/PopAttrib */ struct gl_texture_object Saved2D; struct gl_texture_object Saved3D; struct gl_texture_object SavedCubeMap; @@ -954,15 +1092,21 @@ struct gl_texture_unit { }; -/* The texture attribute group */ +/** + * \brief The texture attribute group + */ struct gl_texture_attrib { - /* multitexture */ - GLuint CurrentUnit; /* Active texture unit */ + /** + * name multitexture + */ + /**@{*/ + GLuint CurrentUnit; /**< \brief Active texture unit */ - GLuint _EnabledUnits; /* one bit set for each really-enabled unit */ - GLuint _GenFlags; /* for texgen */ - GLuint _TexGenEnabled; + GLuint _EnabledUnits; /**< \brief one bit set for each really-enabled unit */ + GLuint _GenFlags; /**< \brief for texgen */ + GLuint _TexGenEnabled; GLuint _TexMatEnabled; + /**@}*/ struct gl_texture_unit Unit[MAX_TEXTURE_UNITS]; @@ -972,32 +1116,40 @@ struct gl_texture_attrib { struct gl_texture_object *ProxyCubeMap; struct gl_texture_object *ProxyRect; - /* GL_EXT_shared_texture_palette */ + /** \brief GL_EXT_shared_texture_palette */ GLboolean SharedPalette; struct gl_color_table Palette; }; +/** + * \brief Transformation attributes. + */ struct gl_transform_attrib { - GLenum MatrixMode; /* Matrix mode */ + GLenum MatrixMode; /**< \brief Matrix mode */ GLfloat EyeUserPlane[MAX_CLIP_PLANES][4]; - GLfloat _ClipUserPlane[MAX_CLIP_PLANES][4]; /* derived */ - GLuint ClipPlanesEnabled; /* on/off bitmask */ - GLboolean Normalize; /* Normalize all normals? */ - GLboolean RescaleNormals; /* GL_EXT_rescale_normal */ - GLboolean RasterPositionUnclipped; /* GL_IBM_rasterpos_clip */ + GLfloat _ClipUserPlane[MAX_CLIP_PLANES][4]; /**< \brief derived */ + GLuint ClipPlanesEnabled; /**< \brief on/off bitmask */ + GLboolean Normalize; /**< \brief Normalize all normals? */ + GLboolean RescaleNormals; /**< \brief GL_EXT_rescale_normal */ + GLboolean RasterPositionUnclipped; /**< \brief GL_IBM_rasterpos_clip */ }; +/** + * \brief Viewport attributes. + */ struct gl_viewport_attrib { - GLint X, Y; /* position */ - GLsizei Width, Height; /* size */ - GLfloat Near, Far; /* Depth buffer range */ - GLmatrix _WindowMap; /* Mapping transformation as a matrix. */ + GLint X, Y; /**< \brief position */ + GLsizei Width, Height; /**< \brief size */ + GLfloat Near, Far; /**< \brief Depth buffer range */ + GLmatrix _WindowMap; /**< \brief Mapping transformation as a matrix. */ }; -/* For the attribute stack: */ +/** + * \brief Node for the attribute stack + */ struct gl_attrib_node { GLbitfield kind; void *data; @@ -1005,42 +1157,45 @@ struct gl_attrib_node { }; -/* - * Client pixel packing/unpacking attributes +/** + * \brief Client pixel packing/unpacking attributes */ struct gl_pixelstore_attrib { GLint Alignment; GLint RowLength; GLint SkipPixels; GLint SkipRows; - GLint ImageHeight; /* for GL_EXT_texture3D */ - GLint SkipImages; /* for GL_EXT_texture3D */ + GLint ImageHeight; /**< \brief for GL_EXT_texture3D */ + GLint SkipImages; /**< \brief for GL_EXT_texture3D */ GLboolean SwapBytes; GLboolean LsbFirst; - GLboolean ClientStorage; /* GL_APPLE_client_storage */ - GLboolean Invert; /* GL_MESA_pack_invert */ + GLboolean ClientStorage; /**< \brief GL_APPLE_client_storage */ + GLboolean Invert; /**< \brief GL_MESA_pack_invert */ }; -#define CA_CLIENT_DATA 0x1 /* Data not alloced by mesa */ +#define CA_CLIENT_DATA 0x1 /**< \brief Data not alloced by mesa */ -/* - * Client vertex array attributes +/** + * \brief Client vertex array attributes */ struct gl_client_array { GLint Size; GLenum Type; - GLsizei Stride; /* user-specified stride */ - GLsizei StrideB; /* actual stride in bytes */ + GLsizei Stride; /**< \brief user-specified stride */ + GLsizei StrideB; /**< \brief actual stride in bytes */ void *Ptr; GLuint Flags; - GLuint Enabled; /* one of the _NEW_ARRAY_ bits */ + GLuint Enabled; /**< \brief one of the _NEW_ARRAY_ bits */ }; +/** + * \brief Array attributes. + */ struct gl_array_attrib { - struct gl_client_array Vertex; /* client data descriptors */ + struct gl_client_array Vertex; /**< \brief client data descriptors */ struct gl_client_array Normal; struct gl_client_array Color; struct gl_client_array SecondaryColor; @@ -1049,15 +1204,15 @@ struct gl_array_attrib { struct gl_client_array TexCoord[MAX_TEXTURE_UNITS]; struct gl_client_array EdgeFlag; - struct gl_client_array VertexAttrib[16]; /* GL_NV_vertex_program */ + struct gl_client_array VertexAttrib[16]; /**< \brief GL_NV_vertex_program */ GLint TexCoordInterleaveFactor; - GLint ActiveTexture; /* Client Active Texture */ + GLint ActiveTexture; /**< \brief Client Active Texture */ GLuint LockFirst; GLuint LockCount; - GLuint _Enabled; /* _NEW_ARRAY_* - bit set if array enabled */ - GLuint NewState; /* _NEW_ARRAY_* */ + GLuint _Enabled; /**< \brief _NEW_ARRAY_* - bit set if array enabled */ + GLuint NewState; /**< \brief _NEW_ARRAY_* */ }; @@ -1070,11 +1225,14 @@ struct gl_feedback { }; +/** + * \brief Selection attributes. + */ struct gl_selection { GLuint *Buffer; - GLuint BufferSize; /* size of SelectBuffer */ - GLuint BufferCount; /* number of values in SelectBuffer */ - GLuint Hits; /* number of records in SelectBuffer */ + GLuint BufferSize; /**< \brief size of SelectBuffer */ + GLuint BufferCount; /**< \brief number of values in SelectBuffer */ + GLuint Hits; /**< \brief number of records in SelectBuffer */ GLuint NameStackDepth; GLuint NameStack[MAX_NAME_STACK_DEPTH]; GLboolean HitFlag; @@ -1082,33 +1240,36 @@ struct gl_selection { }; -/* - * 1-D Evaluator control points +/** + * \brief 1-D Evaluator control points */ struct gl_1d_map { - GLuint Order; /* Number of control points */ - GLfloat u1, u2, du; /* u1, u2, 1.0/(u2-u1) */ - GLfloat *Points; /* Points to contiguous control points */ + GLuint Order; /**< \brief Number of control points */ + GLfloat u1, u2, du; /**< \brief u1, u2, 1.0/(u2-u1) */ + GLfloat *Points; /**< \brief Points to contiguous control points */ }; -/* - * 2-D Evaluator control points +/** + * \brief 2-D Evaluator control points */ struct gl_2d_map { - GLuint Uorder; /* Number of control points in U dimension */ - GLuint Vorder; /* Number of control points in V dimension */ + GLuint Uorder; /**< \brief Number of control points in U dimension */ + GLuint Vorder; /**< \brief Number of control points in V dimension */ GLfloat u1, u2, du; GLfloat v1, v2, dv; - GLfloat *Points; /* Points to contiguous control points */ + GLfloat *Points; /**< \brief Points to contiguous control points */ }; -/* - * All evalutator control points +/** + * \brief All evalutator control points */ struct gl_evaluators { - /* 1-D maps */ + /** + * \name 1-D maps + */ + /*@{*/ struct gl_1d_map Map1Vertex3; struct gl_1d_map Map1Vertex4; struct gl_1d_map Map1Index; @@ -1118,9 +1279,13 @@ struct gl_evaluators { struct gl_1d_map Map1Texture2; struct gl_1d_map Map1Texture3; struct gl_1d_map Map1Texture4; - struct gl_1d_map Map1Attrib[16]; /* GL_NV_vertex_program */ + struct gl_1d_map Map1Attrib[16]; /**< \brief GL_NV_vertex_program */ + /*@}*/ - /* 2-D maps */ + /** + * \name 2-D maps + */ + /*@{*/ struct gl_2d_map Map2Vertex3; struct gl_2d_map Map2Vertex4; struct gl_2d_map Map2Index; @@ -1130,13 +1295,15 @@ struct gl_evaluators { struct gl_2d_map Map2Texture2; struct gl_2d_map Map2Texture3; struct gl_2d_map Map2Texture4; - struct gl_2d_map Map2Attrib[16]; /* GL_NV_vertex_program */ + struct gl_2d_map Map2Attrib[16]; /**< \brief GL_NV_vertex_program */ + /*@}*/ }; -/* - * Vertex program tokens and datatypes +/** + * \name Vertex program tokens and datatypes */ +/*@{*/ #define VP_MAX_INSTRUCTIONS 128 @@ -1158,7 +1325,9 @@ struct gl_evaluators { #define VP_PROG_REG_END (VP_PROG_REG_START + VP_NUM_PROG_REGS - 1) -/* Machine state (i.e. the register file) */ +/** + * \brief Machine state (i.e. the register file) + */ struct vp_machine { GLfloat Registers[VP_NUM_TOTAL_REGISTERS][4]; @@ -1166,7 +1335,9 @@ struct vp_machine }; -/* Vertex program opcodes */ +/** + * \brief Vertex program opcodes + */ enum vp_opcode { MOV, @@ -1194,7 +1365,9 @@ enum vp_opcode }; -/* Instruction source register */ +/** + * \brief Instruction source register + */ struct vp_src_register { GLint Register; /* or the offset from the address register */ @@ -1204,7 +1377,9 @@ struct vp_src_register }; -/* Instruction destination register */ +/** + * \brief Instruction destination register + */ struct vp_dst_register { GLint Register; @@ -1212,7 +1387,9 @@ struct vp_dst_register }; -/* Vertex program instruction */ +/** + * \brief Vertex program instruction + */ struct vp_instruction { enum vp_opcode Opcode; @@ -1221,102 +1398,127 @@ struct vp_instruction }; -/* The actual vertex program, stored in the hash table */ +/** + * \brief The actual vertex program, stored in the hash table + */ struct vp_program { - GLubyte *String; /* Original user code */ - struct vp_instruction *Instructions; /* Compiled instructions */ - GLenum Target; /* GL_VERTEX_PROGRAM_NV or GL_VERTEX_STATE_PROGRAM_NV */ - GLint RefCount; /* Since programs can be shared among contexts */ - GLboolean IsPositionInvariant; /* GL_NV_vertex_program1_1 */ + GLubyte *String; /**< \brief Original user code */ + struct vp_instruction *Instructions; /**< \brief Compiled instructions */ + GLenum Target; /**< \brief GL_VERTEX_PROGRAM_NV or GL_VERTEX_STATE_PROGRAM_NV */ + GLint RefCount; /**< \brief Since programs can be shared among contexts */ + GLboolean IsPositionInvariant; /**< \brief GL_NV_vertex_program1_1 */ GLboolean Resident; - GLuint InputsRead; /* Bitmask of which input regs are read */ - GLuint OutputsWritten; /* Bitmask of which output regs are written to */ + GLuint InputsRead; /**< \brief Bitmask of which input regs are read */ + GLuint OutputsWritten; /**< \brief Bitmask of which output regs are written to */ }; -/* - * State vars for GL_NV_vertex_program +/** + * \brief State vars for GL_NV_vertex_program */ struct vertex_program_state { - GLboolean Enabled; /* GL_VERTEX_PROGRAM_NV */ - GLboolean PointSizeEnabled; /* GL_VERTEX_PROGRAM_POINT_SIZE_NV */ - GLboolean TwoSideEnabled; /* GL_VERTEX_PROGRAM_TWO_SIDE_NV */ - GLuint CurrentID; /* currently bound program's ID */ - GLint ErrorPos; /* GL_PROGRAM_ERROR_POSITION_NV */ - struct vp_program *Current; /* ptr to currently bound program */ - struct vp_machine Machine; /* machine state */ + GLboolean Enabled; /**< \brief GL_VERTEX_PROGRAM_NV */ + GLboolean PointSizeEnabled; /**< \brief GL_VERTEX_PROGRAM_POINT_SIZE_NV */ + GLboolean TwoSideEnabled; /**< \brief GL_VERTEX_PROGRAM_TWO_SIDE_NV */ + GLuint CurrentID; /**< \brief currently bound program's ID */ + GLint ErrorPos; /**< \brief GL_PROGRAM_ERROR_POSITION_NV */ + struct vp_program *Current; /**< \brief ptr to currently bound program */ + struct vp_machine Machine; /**< \brief machine state */ GLenum TrackMatrix[VP_NUM_PROG_REGS / 4]; GLenum TrackMatrixTransform[VP_NUM_PROG_REGS / 4]; }; +/*@}*/ -/* - * State which can be shared by multiple contexts: +/** + * \brief State which can be shared by multiple contexts: */ struct gl_shared_state { - _glthread_Mutex Mutex; /* for thread safety */ - GLint RefCount; /* Reference count */ - struct _mesa_HashTable *DisplayList; /* Display lists hash table */ - struct _mesa_HashTable *TexObjects; /* Texture objects hash table */ - struct gl_texture_object *TexObjectList;/* Linked list of texture objects */ + _glthread_Mutex Mutex; /**< \brief for thread safety */ + GLint RefCount; /**< \brief Reference count */ + struct _mesa_HashTable *DisplayList; /**< \brief Display lists hash table */ + struct _mesa_HashTable *TexObjects; /**< \brief Texture objects hash table */ + struct gl_texture_object *TexObjectList;/**< \brief Linked list of texture objects */ - /* Default texture objects (shared by all multi-texture units) */ + /** + * \name Default texture objects (shared by all multi-texture units) + */ + /*@{*/ struct gl_texture_object *Default1D; struct gl_texture_object *Default2D; struct gl_texture_object *Default3D; struct gl_texture_object *DefaultCubeMap; struct gl_texture_object *DefaultRect; + /*@}*/ - /* GL_NV_vertex_program */ + /** \brief GL_NV_vertex_program */ struct _mesa_HashTable *VertexPrograms; - void *DriverData; /* Device driver shared state */ + void *DriverData; /**< \brief Device driver shared state */ }; -/* +/** + * \brief Frame buffer. + * * A "frame buffer" is a color buffer and its optional ancillary buffers: * depth, accum, stencil, and software-simulated alpha buffers. * In C++ terms, think of this as a base class from which device drivers * will make derived classes. */ struct gl_frame_buffer { - GLvisual Visual; /* The corresponding visual */ + GLvisual Visual; /**< \brief The corresponding visual */ - GLuint Width, Height; /* size of frame buffer in pixels */ + GLuint Width, Height; /**< \brief size of frame buffer in pixels */ GLboolean UseSoftwareDepthBuffer; GLboolean UseSoftwareAccumBuffer; GLboolean UseSoftwareStencilBuffer; GLboolean UseSoftwareAlphaBuffers; - /* Software depth (aka Z) buffer */ - GLvoid *DepthBuffer; /* array [Width*Height] of GLushort or GLuint*/ + /** \name Software depth (aka Z) buffer */ + /*@{*/ + GLvoid *DepthBuffer; /**< \brief array [Width*Height] of GLushort or GLuint*/ + /*@}*/ - /* Software stencil buffer */ - GLstencil *Stencil; /* array [Width*Height] of GLstencil values */ + /** \name Software stencil buffer */ + /*@{*/ + GLstencil *Stencil; /**< \brief array [Width*Height] of GLstencil values */ + /*@}*/ - /* Software accumulation buffer */ - GLaccum *Accum; /* array [4*Width*Height] of GLaccum values */ + /** \name Software accumulation buffer */ + /*@{*/ + GLaccum *Accum; /**< \brief array [4*Width*Height] of GLaccum values */ + /*@}*/ - /* Software alpha planes */ - GLvoid *FrontLeftAlpha; /* array [Width*Height] of GLubyte */ - GLvoid *BackLeftAlpha; /* array [Width*Height] of GLubyte */ - GLvoid *FrontRightAlpha; /* array [Width*Height] of GLubyte */ - GLvoid *BackRightAlpha; /* array [Width*Height] of GLubyte */ + /** \name Software alpha planes */ + /*@{*/ + GLvoid *FrontLeftAlpha; /**< \brief array [Width*Height] of GLubyte */ + GLvoid *BackLeftAlpha; /**< \brief array [Width*Height] of GLubyte */ + GLvoid *FrontRightAlpha; /**< \brief array [Width*Height] of GLubyte */ + GLvoid *BackRightAlpha; /**< \brief array [Width*Height] of GLubyte */ + /*@}*/ - /* Drawing bounds: intersection of window size and scissor box */ - GLint _Xmin, _Ymin; /* inclusive */ - GLint _Xmax, _Ymax; /* exclusive */ + /** + * \name Drawing bounds + * + * Intersection of window size and scissor box + */ + /*@{*/ + GLint _Xmin; /**< \brief inclusive */ + GLint _Ymin; /**< \brief inclusive */ + GLint _Xmax; /**< \brief exclusive */ + GLint _Ymax; /**< \brief exclusive */ + /*@}*/ }; -/* - * Constants which may be overriden by device driver during context creation +/** + * \brief Constants which may be overriden by device driver during context creation * but are never changed after that. */ struct gl_constants { @@ -1344,16 +1546,19 @@ struct gl_constants { }; -/* - * List of extensions. +/** + * \brief List of extensions. */ struct extension; struct gl_extensions { char *ext_string; struct extension *ext_list; - /* Flags to quickly test if certain extensions are available. + /** + * \name Flags to quickly test if certain extensions are available. + * * Not every extension needs to have such a flag, but it's encouraged. */ + /*@{*/ GLboolean ARB_depth_texture; GLboolean ARB_imaging; GLboolean ARB_multisample; @@ -1422,19 +1627,20 @@ struct gl_extensions { GLboolean SGIX_shadow_ambient; /* or GL_ARB_shadow_ambient */ GLboolean TDFX_texture_compression_FXT1; GLboolean APPLE_client_storage; + /*@}*/ }; -/* - * A stack of matrices (projection, modelview, color, texture, etc). +/** + * \brief A stack of matrices (projection, modelview, color, texture, etc). */ struct matrix_stack { - GLmatrix *Top; /* points into Stack */ - GLmatrix *Stack; /* array [MaxDepth] of GLmatrix */ - GLuint Depth; /* 0 <= Depth < MaxDepth */ - GLuint MaxDepth; /* size of Stack[] array */ - GLuint DirtyFlag; /* _NEW_MODELVIEW or _NEW_PROJECTION, for example */ + GLmatrix *Top; /**< \brief points into Stack */ + GLmatrix *Stack; /**< \brief array [MaxDepth] of GLmatrix */ + GLuint Depth; /**< \brief 0 <= Depth < MaxDepth */ + GLuint MaxDepth; /**< \brief size of Stack[] array */ + GLuint DirtyFlag; /**< \brief _NEW_MODELVIEW or _NEW_PROJECTION, for example */ }; @@ -1453,13 +1659,13 @@ struct matrix_stack #define IMAGE_HISTOGRAM_BIT 0x200 #define IMAGE_MIN_MAX_BIT 0x400 -/* transfer ops up to convolution: */ +/** transfer ops up to convolution: */ #define IMAGE_PRE_CONVOLUTION_BITS (IMAGE_SCALE_BIAS_BIT | \ IMAGE_SHIFT_OFFSET_BIT | \ IMAGE_MAP_COLOR_BIT | \ IMAGE_COLOR_TABLE_BIT) -/* transfer ops after convolution: */ +/** transfer ops after convolution: */ #define IMAGE_POST_CONVOLUTION_BITS (IMAGE_POST_CONVOLUTION_SCALE_BIAS | \ IMAGE_POST_CONVOLUTION_COLOR_TABLE_BIT | \ IMAGE_COLOR_MATRIX_BIT | \ @@ -1471,34 +1677,34 @@ struct matrix_stack /* * Bits to indicate what state has changed. 6 unused flags. */ -#define _NEW_MODELVIEW 0x1 /* ctx->ModelView */ -#define _NEW_PROJECTION 0x2 /* ctx->Projection */ -#define _NEW_TEXTURE_MATRIX 0x4 /* ctx->TextureMatrix */ -#define _NEW_COLOR_MATRIX 0x8 /* ctx->ColorMatrix */ -#define _NEW_ACCUM 0x10 /* ctx->Accum */ -#define _NEW_COLOR 0x20 /* ctx->Color */ -#define _NEW_DEPTH 0x40 /* ctx->Depth */ -#define _NEW_EVAL 0x80 /* ctx->Eval, ctx->EvalMap */ -#define _NEW_FOG 0x100 /* ctx->Fog */ -#define _NEW_HINT 0x200 /* ctx->Hint */ -#define _NEW_LIGHT 0x400 /* ctx->Light */ -#define _NEW_LINE 0x800 /* ctx->Line */ -#define _NEW_PIXEL 0x1000 /* ctx->Pixel */ -#define _NEW_POINT 0x2000 /* ctx->Point */ -#define _NEW_POLYGON 0x4000 /* ctx->Polygon */ -#define _NEW_POLYGONSTIPPLE 0x8000 /* ctx->PolygonStipple */ -#define _NEW_SCISSOR 0x10000 /* ctx->Scissor */ -#define _NEW_STENCIL 0x20000 /* ctx->Stencil */ -#define _NEW_TEXTURE 0x40000 /* ctx->Texture */ -#define _NEW_TRANSFORM 0x80000 /* ctx->Transform */ -#define _NEW_VIEWPORT 0x100000 /* ctx->Viewport */ -#define _NEW_PACKUNPACK 0x200000 /* ctx->Pack, ctx->Unpack */ -#define _NEW_ARRAY 0x400000 /* ctx->Array */ -#define _NEW_RENDERMODE 0x800000 /* RenderMode, Feedback, Select */ -#define _NEW_BUFFERS 0x1000000 /* ctx->Visual, ctx->DrawBuffer, */ -#define _NEW_MULTISAMPLE 0x2000000 /* ctx->Multisample */ -#define _NEW_TRACK_MATRIX 0x4000000 /* ctx->VertexProgram */ -#define _NEW_PROGRAM 0x8000000 /* ctx->VertexProgram */ +#define _NEW_MODELVIEW 0x1 /**< \brief ctx->ModelView */ +#define _NEW_PROJECTION 0x2 /**< \brief ctx->Projection */ +#define _NEW_TEXTURE_MATRIX 0x4 /**< \brief ctx->TextureMatrix */ +#define _NEW_COLOR_MATRIX 0x8 /**< \brief ctx->ColorMatrix */ +#define _NEW_ACCUM 0x10 /**< \brief ctx->Accum */ +#define _NEW_COLOR 0x20 /**< \brief ctx->Color */ +#define _NEW_DEPTH 0x40 /**< \brief ctx->Depth */ +#define _NEW_EVAL 0x80 /**< \brief ctx->Eval, ctx->EvalMap */ +#define _NEW_FOG 0x100 /**< \brief ctx->Fog */ +#define _NEW_HINT 0x200 /**< \brief ctx->Hint */ +#define _NEW_LIGHT 0x400 /**< \brief ctx->Light */ +#define _NEW_LINE 0x800 /**< \brief ctx->Line */ +#define _NEW_PIXEL 0x1000 /**< \brief ctx->Pixel */ +#define _NEW_POINT 0x2000 /**< \brief ctx->Point */ +#define _NEW_POLYGON 0x4000 /**< \brief ctx->Polygon */ +#define _NEW_POLYGONSTIPPLE 0x8000 /**< \brief ctx->PolygonStipple */ +#define _NEW_SCISSOR 0x10000 /**< \brief ctx->Scissor */ +#define _NEW_STENCIL 0x20000 /**< \brief ctx->Stencil */ +#define _NEW_TEXTURE 0x40000 /**< \brief ctx->Texture */ +#define _NEW_TRANSFORM 0x80000 /**< \brief ctx->Transform */ +#define _NEW_VIEWPORT 0x100000 /**< \brief ctx->Viewport */ +#define _NEW_PACKUNPACK 0x200000 /**< \brief ctx->Pack, ctx->Unpack */ +#define _NEW_ARRAY 0x400000 /**< \brief ctx->Array */ +#define _NEW_RENDERMODE 0x800000 /**< \brief RenderMode, Feedback, Select */ +#define _NEW_BUFFERS 0x1000000 /**< \brief ctx->Visual, ctx->DrawBuffer, */ +#define _NEW_MULTISAMPLE 0x2000000 /**< \brief ctx->Multisample */ +#define _NEW_TRACK_MATRIX 0x4000000 /**< \brief ctx->VertexProgram */ +#define _NEW_PROGRAM 0x8000000 /**< \brief ctx->VertexProgram */ #define _NEW_ALL ~0 @@ -1599,25 +1805,31 @@ typedef union node Node; #include "dd.h" -/* - * Core Mesa's support for tnl modules: - */ #define NUM_VERTEX_FORMAT_ENTRIES (sizeof(GLvertexformat) / sizeof(void *)) +/** + * \brief Core Mesa's support for tnl modules: + */ struct gl_tnl_module { - /* Vertex format to be lazily swapped into current dispatch. + /** + * \brief Vertex format to be lazily swapped into current dispatch. */ GLvertexformat *Current; - /* Record of functions swapped out. On restore, only need to swap - * these functions back in. + /** + * \name Record of functions swapped out. + * On restore, only need to swap these functions back in. */ + /*@{*/ void *Swapped[NUM_VERTEX_FORMAT_ENTRIES][2]; GLuint SwapCount; + /*@}*/ }; /** + * \brief Mesa context + * * This is the central context data structure for Mesa. Almost all * OpenGL state is contained in this structure. * Think of this as a base class from which device drivers will derive @@ -1625,67 +1837,79 @@ struct gl_tnl_module { */ struct __GLcontextRec { /** - * OS related interfaces; these *must* be the first members of this - * structure, because they are exposed to the outside world (i.e. GLX - * extension). + * \name OS related interfaces. + * + * These \b must be the first members of this structure, because they are + * exposed to the outside world (i.e. GLX extension). */ + /*@{*/ __GLimports imports; __GLexports exports; + /*@}*/ - /* State possibly shared with other contexts in the address space */ + /** \brief State possibly shared with other contexts in the address space */ struct gl_shared_state *Shared; - /* API function pointer tables */ - struct _glapi_table *Save; /**< Display list save funcs */ - struct _glapi_table *Exec; /**< Execute funcs */ + /** \name API function pointer tables */ + /*@{*/ + struct _glapi_table *Save; /**< \brief Display list save funcs */ + struct _glapi_table *Exec; /**< \brief Execute funcs */ struct _glapi_table *CurrentDispatch; /**< == Save or Exec !! */ + /*@}*/ - GLboolean ExecPrefersFloat; /**< What preference for color conversion? */ + GLboolean ExecPrefersFloat; /**< \brief What preference for color conversion? */ GLboolean SavePrefersFloat; GLvisual Visual; - GLframebuffer *DrawBuffer; /**< buffer for writing */ - GLframebuffer *ReadBuffer; /**< buffer for reading */ + GLframebuffer *DrawBuffer; /**< \brief buffer for writing */ + GLframebuffer *ReadBuffer; /**< \brief buffer for reading */ /** - * Device driver function pointer table + * \brief Device driver function pointer table */ struct dd_function_table Driver; - void *DriverCtx; /**< Points to device driver context/state */ - void *DriverMgrCtx; /**< Points to device driver manager (optional)*/ + void *DriverCtx; /**< \brief Points to device driver context/state */ + void *DriverMgrCtx; /**< \brief Points to device driver manager (optional)*/ - /* Core/Driver constants */ + /** \brief Core/Driver constants */ struct gl_constants Const; - /* The various 4x4 matrix stacks */ + /** \name The various 4x4 matrix stacks */ + /*@{*/ struct matrix_stack ModelviewMatrixStack; struct matrix_stack ProjectionMatrixStack; struct matrix_stack ColorMatrixStack; struct matrix_stack TextureMatrixStack[MAX_TEXTURE_UNITS]; struct matrix_stack ProgramMatrixStack[MAX_PROGRAM_MATRICES]; - struct matrix_stack *CurrentStack; /* Points to one of the above stacks */ + struct matrix_stack *CurrentStack; /**< \brief Points to one of the above stacks */ + /*@}*/ - /* Combined modelview and projection matrix */ + /** \brief Combined modelview and projection matrix */ GLmatrix _ModelProjectMatrix; - /* Display lists */ - GLuint CallDepth; /* Current recursion calling depth */ - GLboolean ExecuteFlag; /* Execute GL commands? */ - GLboolean CompileFlag; /* Compile GL commands into display list? */ - Node *CurrentListPtr; /* Head of list being compiled */ - GLuint CurrentListNum; /* Number of the list being compiled */ - Node *CurrentBlock; /* Pointer to current block of nodes */ - GLuint CurrentPos; /* Index into current block of nodes */ + /** \name Display lists */ + /*@{*/ + GLuint CallDepth; /**< \brief Current recursion calling depth */ + GLboolean ExecuteFlag; /**< \brief Execute GL commands? */ + GLboolean CompileFlag; /**< \brief Compile GL commands into display list? */ + Node *CurrentListPtr; /**< \brief Head of list being compiled */ + GLuint CurrentListNum; /**< \brief Number of the list being compiled */ + Node *CurrentBlock; /**< \brief Pointer to current block of nodes */ + GLuint CurrentPos; /**< \brief Index into current block of nodes */ + /*@}*/ - /* Extensions */ + /** \brief Extensions */ struct gl_extensions Extensions; - /* Renderer attribute stack */ + /** \name Renderer attribute stack */ + /*@{*/ GLuint AttribStackDepth; struct gl_attrib_node *AttribStack[MAX_ATTRIB_STACK_DEPTH]; + /*@}*/ - /* Renderer attribute groups */ + /** \name Renderer attribute groups */ + /*@{*/ struct gl_accum_attrib Accum; struct gl_colorbuffer_attrib Color; struct gl_current_attrib Current; @@ -1706,74 +1930,88 @@ struct __GLcontextRec { struct gl_texture_attrib Texture; struct gl_transform_attrib Transform; struct gl_viewport_attrib Viewport; + /*@}*/ - /* Other attribute groups */ + /** \name Other attribute groups */ + /*@{*/ struct gl_histogram_attrib Histogram; struct gl_minmax_attrib MinMax; struct gl_convolution_attrib Convolution1D; struct gl_convolution_attrib Convolution2D; struct gl_convolution_attrib Separable2D; + /*@}*/ - /* Client attribute stack */ + /** \name Client attribute stack */ + /*@{*/ GLuint ClientAttribStackDepth; struct gl_attrib_node *ClientAttribStack[MAX_CLIENT_ATTRIB_STACK_DEPTH]; + /*@}*/ - /* Client attribute groups */ - struct gl_array_attrib Array; /* Vertex arrays */ - struct gl_pixelstore_attrib Pack; /* Pixel packing */ - struct gl_pixelstore_attrib Unpack; /* Pixel unpacking */ + /** \name Client attribute groups */ + /*@{*/ + struct gl_array_attrib Array; /**< \brief Vertex arrays */ + struct gl_pixelstore_attrib Pack; /**< \brief Pixel packing */ + struct gl_pixelstore_attrib Unpack; /**< \brief Pixel unpacking */ - struct gl_evaluators EvalMap; /* All evaluators */ - struct gl_feedback Feedback; /* Feedback */ - struct gl_selection Select; /* Selection */ + struct gl_evaluators EvalMap; /**< \brief All evaluators */ + struct gl_feedback Feedback; /**< \brief Feedback */ + struct gl_selection Select; /**< \brief Selection */ - struct gl_color_table ColorTable; /* Pre-convolution */ - struct gl_color_table ProxyColorTable; /* Pre-convolution */ + struct gl_color_table ColorTable; /**< \brief Pre-convolution */ + struct gl_color_table ProxyColorTable; /**< \brief Pre-convolution */ struct gl_color_table PostConvolutionColorTable; struct gl_color_table ProxyPostConvolutionColorTable; struct gl_color_table PostColorMatrixColorTable; struct gl_color_table ProxyPostColorMatrixColorTable; - struct vertex_program_state VertexProgram; /* GL_NV_vertex_program */ + struct vertex_program_state VertexProgram; /**< \brief GL_NV_vertex_program */ - GLenum ErrorValue; /* Last error code */ - GLenum RenderMode; /* either GL_RENDER, GL_SELECT, GL_FEEDBACK */ - GLuint NewState; /* bitwise-or of _NEW_* flags */ + GLenum ErrorValue; /**< \brief Last error code */ + GLenum RenderMode; /**< \brief either GL_RENDER, GL_SELECT, GL_FEEDBACK */ + GLuint NewState; /**< \brief bitwise-or of _NEW_* flags */ + /*@}*/ - /* Derived */ - GLuint _TriangleCaps; /* bitwise-or of DD_* flags */ - GLuint _ImageTransferState;/* bitwise-or of IMAGE_*_BIT flags */ + /** \name Derived */ + /*@{*/ + GLuint _TriangleCaps; /**< \brief bitwise-or of DD_* flags */ + GLuint _ImageTransferState;/**< \brief bitwise-or of IMAGE_*_BIT flags */ GLfloat _EyeZDir[3]; GLfloat _ModelViewInvScale; GLuint _NeedEyeCoords; - GLuint _NeedNormals; /* Are vertex normal vectors needed? */ + GLuint _NeedNormals; /**< \brief Are vertex normal vectors needed? */ - struct gl_shine_tab *_ShineTable[2]; /* Active shine tables */ - struct gl_shine_tab *_ShineTabList; /* Mru list of inactive shine tables */ + struct gl_shine_tab *_ShineTable[2]; /**< \brief Active shine tables */ + struct gl_shine_tab *_ShineTabList; /**< \brief Mru list of inactive shine tables */ + /**@}*/ - struct gl_list_extensions listext; /* driver dlist extensions */ + struct gl_list_extensions listext; /**< \brief driver dlist extensions */ - GLboolean OcclusionResult; /**< for GL_HP_occlusion_test */ - GLboolean OcclusionResultSaved; /**< for GL_HP_occlusion_test */ - GLuint _Facing; /* This is a hack for 2-sided stencil test. We don't */ - /* have a better way to communicate this value from */ - /* swrast_setup to swrast. */ + GLboolean OcclusionResult; /**< \brief*< for GL_HP_occlusion_test */ + GLboolean OcclusionResultSaved; /**< \brief*< for GL_HP_occlusion_test */ + GLuint _Facing; /**< \brief This is a hack for 2-sided stencil test. + * + * We don't have a better way to communicate this value from + * swrast_setup to swrast. */ - /* Z buffer stuff */ - GLuint DepthMax; /**< Max depth buffer value */ - GLfloat DepthMaxF; /**< Float max depth buffer value */ - GLfloat MRD; /**< minimum resolvable difference in Z values */ + /** \name Z buffer stuff */ + /*@{*/ + GLuint DepthMax; /**< \brief Max depth buffer value */ + GLfloat DepthMaxF; /**< \brief Float max depth buffer value */ + GLfloat MRD; /**< \brief minimum resolvable difference in Z values */ + /*@}*/ - /** Should 3Dfx Glide driver catch signals? */ + /** \brief Should 3Dfx Glide driver catch signals? */ GLboolean CatchSignals; - /** For debugging/development only */ + /** \name For debugging/development only */ + /*@{*/ GLboolean NoRaster; GLboolean FirstTimeCurrent; + /*@}*/ - /** Dither disable via MESA_NO_DITHER env var */ + /** \brief Dither disable via MESA_NO_DITHER env var */ GLboolean NoDither; GLboolean Rendering; @@ -1786,22 +2024,26 @@ struct __GLcontextRec { void *TraceCtx; #endif - /* Core tnl module support */ + /** \brief Core tnl module support */ struct gl_tnl_module TnlModule; - /* Hooks for module contexts. These will eventually live - * in the driver or elsewhere. + /** + * \name Hooks for module contexts. + * + * These will eventually live in the driver or elsewhere. */ + /*@{*/ void *swrast_context; void *swsetup_context; void *swtnl_context; void *swtnl_im; void *acache_context; void *aelt_context; + /*@}*/ }; -/* The string names for GL_POINT, GL_LINE_LOOP, etc */ +/** \brief The string names for GL_POINT, GL_LINE_LOOP, etc */ extern const char *_mesa_prim_name[GL_POLYGON+4]; #ifndef MESA_DEBUG diff --git a/src/mesa/math/m_matrix.c b/src/mesa/math/m_matrix.c index 4b346860d61..83d19a41ceb 100644 --- a/src/mesa/math/m_matrix.c +++ b/src/mesa/math/m_matrix.c @@ -1,4 +1,12 @@ -/* $Id: m_matrix.c,v 1.14 2002/10/24 23:57:24 brianp Exp $ */ +/** + * \file m_matrix.c + * \brief Matrix operations. + * + * \note + * -# 4x4 transformation matrices are stored in memory in column major order. + * -# Points/vertices are to be thought of as column vectors. + * -# Transformation of a point p by a matrix M is: p' = M * p + */ /* * Mesa 3-D graphics library @@ -24,15 +32,8 @@ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/* $Id: m_matrix.c,v 1.14.4.1 2003/03/02 00:27:36 jrfonseca Exp $ */ -/* - * Matrix operations - * - * NOTES: - * 1. 4x4 transformation matrices are stored in memory in column major order. - * 2. Points/vertices are to be thought of as column vectors. - * 3. Transformation of a point p by a matrix M is: p' = M * p - */ #include "glheader.h" #include "imports.h" @@ -43,6 +44,9 @@ #include "m_matrix.h" +/** + * \brief Names of the corresponding GLmatrixtype values. + */ static const char *types[] = { "MATRIX_GENERAL", "MATRIX_IDENTITY", @@ -54,6 +58,9 @@ static const char *types[] = { }; +/** + * \brief Identity matrix. + */ static GLfloat Identity[16] = { 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, @@ -63,22 +70,27 @@ static GLfloat Identity[16] = { +/**********************************************************************/ +/** \name Matrix multiplication */ +/*@{*/ -/* - * This matmul was contributed by Thomas Malik - * - * Perform a 4x4 matrix multiplication (product = a x b). - * Input: a, b - matrices to multiply - * Output: product - product of a and b - * WARNING: (product != b) assumed - * NOTE: (product == a) allowed - * - * KW: 4*16 = 64 muls - */ #define A(row,col) a[(col<<2)+row] #define B(row,col) b[(col<<2)+row] #define P(row,col) product[(col<<2)+row] +/** + * \brief Perform a full 4x4 matrix multiplication. + * + * \param a matrix. + * \param b matrix. + * \param product will receive the product of \p a and \p b. + * + * \warning Is assumed that \p product != \p b. \p product == \p a is allowed. + * + * \note KW: 4*16 = 64 multiplications + * + * \author This \c matmul was contributed by Thomas Malik + */ static void matmul4( GLfloat *product, const GLfloat *a, const GLfloat *b ) { GLint i; @@ -91,9 +103,13 @@ static void matmul4( GLfloat *product, const GLfloat *a, const GLfloat *b ) } } - -/* Multiply two matrices known to occupy only the top three rows, such +/** + * \brief Multiply two matrices known to occupy only the top three rows, such * as typical model matrices, and ortho matrices. + * + * \param a matrix. + * \param b matrix. + * \param product will receive the product of \p a and \p b. */ static void matmul34( GLfloat *product, const GLfloat *a, const GLfloat *b ) { @@ -111,14 +127,20 @@ static void matmul34( GLfloat *product, const GLfloat *a, const GLfloat *b ) P(3,3) = 1; } - #undef A #undef B #undef P - -/* - * Multiply a matrix by an array of floats with known properties. +/** + * \brief Multiply a matrix by an array of floats with known properties. + * + * \param mat pointer to a GLmatrix structure containing the left mutiplication + * matrix, and that will receive the product result. + * \param m right multiplication matrix array. + * \param flags flags of the matrix \p m. + * + * Joins both flags and marks the type and inverse as drity. Calls matmul34() + * if both matrices are 3D, or matmul4() otherwise. */ static void matrix_multf( GLmatrix *mat, const GLfloat *m, GLuint flags ) { @@ -130,7 +152,49 @@ static void matrix_multf( GLmatrix *mat, const GLfloat *m, GLuint flags ) matmul4( mat->m, mat->m, m ); } +/** + * \brief Matrix multiplication. + * + */ +void +_math_matrix_mul_matrix( GLmatrix *dest, const GLmatrix *a, const GLmatrix *b ) +{ + dest->flags = (a->flags | + b->flags | + MAT_DIRTY_TYPE | + MAT_DIRTY_INVERSE); + if (TEST_MAT_FLAGS(dest, MAT_FLAGS_3D)) + matmul34( dest->m, a->m, b->m ); + else + matmul4( dest->m, a->m, b->m ); +} + + +void +_math_matrix_mul_floats( GLmatrix *dest, const GLfloat *m ) +{ + dest->flags |= (MAT_FLAG_GENERAL | + MAT_DIRTY_TYPE | + MAT_DIRTY_INVERSE); + + matmul4( dest->m, dest->m, m ); +} + +/*@{*/ + + +/**********************************************************************/ +/** \name Matrix output */ +/*@{*/ + +/** + * \brief Print a matrix array. + * + * \param m matrix array. + * + * Called by _math_matrix_print() to print a matrix or its inverse. + */ static void print_matrix_floats( const GLfloat m[16] ) { int i; @@ -139,6 +203,11 @@ static void print_matrix_floats( const GLfloat m[16] ) } } +/** + * \brief Dumps the contents of a GLmatrix structure. + * + * \param m pointer to the GLmatrix strucure. + */ void _math_matrix_print( const GLmatrix *m ) { @@ -157,16 +226,48 @@ _math_matrix_print( const GLmatrix *m ) } } +/*@}*/ - -#define SWAP_ROWS(a, b) { GLfloat *_tmp = a; (a)=(b); (b)=_tmp; } +/** + * \brief References an element of 4x4 matrix. + * + * \param m matrix array. + * \param c column of the desired element. + * \param r row of the desired element. + * + * \return value of the desired element. + * + * Calculate the linear storage index of the element and references it. + */ #define MAT(m,r,c) (m)[(c)*4+(r)] -/* - * Compute inverse of 4x4 transformation matrix. + +/**********************************************************************/ +/** \name Matrix inversion */ +/*@{*/ + +/** + * \brief Swaps the values of two floating pointer variables. + * + * Used by invert_matrix_general() to swap the row pointers. + */ +#define SWAP_ROWS(a, b) { GLfloat *_tmp = a; (a)=(b); (b)=_tmp; } + +/** + * \brief Compute inverse of 4x4 transformation matrix. + * + * \param mat pointer to a GLmatrix structure. The matrix inverse will be + * stored in the GLmatrix::inv attribute. + * + * \return GL_TRUE for success, GL_FALSE for failure (\p singular matrix). + * + * \author * Code contributed by Jacques Leroy jle@star.be - * Return GL_TRUE for success, GL_FALSE for failure (singular matrix) + * + * Calculates the inverse matrix by performing the gaussian matrix reduction + * with partial pivoting folloed by back/substitution with the loops manually + * unrolled. */ static GLboolean invert_matrix_general( GLmatrix *mat ) { @@ -281,8 +382,20 @@ static GLboolean invert_matrix_general( GLmatrix *mat ) } #undef SWAP_ROWS - -/* Adapted from graphics gems II. +/** + * \brief Compute inverse of a general 3d transformation matrix. + * + * \param mat pointer to a GLmatrix structure. The matrix inverse will be + * stored in the GLmatrix::inv attribute. + * + * \return GL_TRUE for success, GL_FALSE for failure (\p singular matrix). + * + * \author Adapted from graphics gems II. + * + * Calculates the inverse of the upper left by first calculating its + * determinant and multiplying it to the simetric adjust matrix of each + * element. Finally deals with the translation part by transforming the + * original translation vector using by the calculated submatrix inverse. */ static GLboolean invert_matrix_3d_general( GLmatrix *mat ) { @@ -343,7 +456,19 @@ static GLboolean invert_matrix_3d_general( GLmatrix *mat ) return GL_TRUE; } - +/** + * \brief Compute inverse of a 3d transformation matrix. + * + * \param mat pointer to a GLmatrix structure. The matrix inverse will be + * stored in the GLmatrix::inv attribute. + * + * \return GL_TRUE for success, GL_FALSE for failure (\p singular matrix). + * + * If the matrix is not an angle preserving matrix then calls + * invert_matrix_3d_general for the actual calculation. Otherwise calculates + * the inverse matrix analyzing and inverting each of the scaling, rotation and + * translation parts. + */ static GLboolean invert_matrix_3d( GLmatrix *mat ) { const GLfloat *in = mat->m; @@ -414,15 +539,32 @@ static GLboolean invert_matrix_3d( GLmatrix *mat ) return GL_TRUE; } - - +/** + * \brief Compute inverse of an identity transformation matrix. + * + * \param mat pointer to a GLmatrix structure. The matrix inverse will be + * stored in the GLmatrix::inv attribute. + * + * \return always GL_TRUE. + * + * Simply copies Identity into GLmatrix::inv. + */ static GLboolean invert_matrix_identity( GLmatrix *mat ) { MEMCPY( mat->inv, Identity, sizeof(Identity) ); return GL_TRUE; } - +/** + * \brief Compute inverse of a no-rotation 3d transformation matrix. + * + * \param mat pointer to a GLmatrix structure. The matrix inverse will be + * stored in the GLmatrix::inv attribute. + * + * \return GL_TRUE for success, GL_FALSE for failure (\p singular matrix). + * + * Calculates the + */ static GLboolean invert_matrix_3d_no_rot( GLmatrix *mat ) { const GLfloat *in = mat->m; @@ -445,7 +587,17 @@ static GLboolean invert_matrix_3d_no_rot( GLmatrix *mat ) return GL_TRUE; } - +/** + * \brief Compute inverse of a no-rotation 2d transformation matrix. + * + * \param mat pointer to a GLmatrix structure. The matrix inverse will be + * stored in the GLmatrix::inv attribute. + * + * \return GL_TRUE for success, GL_FALSE for failure (\p singular matrix). + * + * Calculates the inverse matrix by applying the inverse scaling and + * translation to the identity matrix. + */ static GLboolean invert_matrix_2d_no_rot( GLmatrix *mat ) { const GLfloat *in = mat->m; @@ -466,7 +618,6 @@ static GLboolean invert_matrix_2d_no_rot( GLmatrix *mat ) return GL_TRUE; } - #if 0 /* broken */ static GLboolean invert_matrix_perspective( GLmatrix *mat ) @@ -495,10 +646,14 @@ static GLboolean invert_matrix_perspective( GLmatrix *mat ) } #endif - +/** + * \brief Matrix inversion function pointer type. + */ typedef GLboolean (*inv_mat_func)( GLmatrix *mat ); - +/** + * \brief Table of the matrix inversion functions according to the matrix type. + */ static inv_mat_func inv_mat_tab[7] = { invert_matrix_general, invert_matrix_identity, @@ -516,7 +671,18 @@ static inv_mat_func inv_mat_tab[7] = { invert_matrix_3d }; - +/** + * \brief Compute inverse of a transformation matrix. + * + * \param mat pointer to a GLmatrix structure. The matrix inverse will be + * stored in the GLmatrix::inv attribute. + * + * \return GL_TRUE for success, GL_FALSE for failure (\p singular matrix). + * + * Calls the matrix inversion function in inv_mat_tab corresponding to the + * given matrix type. In case of failure, updates the MAT_FLAG_SINGULAR flag, + * and copies the identity matrix into GLmatrix::inv. + */ static GLboolean matrix_invert( GLmatrix *mat ) { if (inv_mat_tab[mat->type](mat)) { @@ -529,16 +695,20 @@ static GLboolean matrix_invert( GLmatrix *mat ) } } +/*@}*/ +/**********************************************************************/ +/** \name Matrix generation */ +/*@{*/ - - -/* - * Generate a 4x4 transformation matrix from glRotate parameters, and - * postmultiply the input matrix by it. - * This function contributed by Erich Boleyn (erich@uruk.org). - * Optimizatios contributed by Rudolf Opalla (rudi@khm.de). +/** + * \brief Generate a 4x4 transformation matrix from glRotate parameters, and + * post-multiply the input matrix by it. + * + * \author + * This function was contributed by Erich Boleyn (erich@uruk.org). + * Optimizations contributed by Rudolf Opalla (rudi@khm.de). */ void _math_matrix_rotate( GLmatrix *mat, @@ -710,8 +880,6 @@ _math_matrix_rotate( GLmatrix *mat, matrix_multf( mat, m, MAT_FLAG_ROTATION ); } - - void _math_matrix_frustum( GLmatrix *mat, GLfloat left, GLfloat right, @@ -765,6 +933,58 @@ _math_matrix_ortho( GLmatrix *mat, matrix_multf( mat, m, (MAT_FLAG_GENERAL_SCALE|MAT_FLAG_TRANSLATION)); } +void +_math_matrix_scale( GLmatrix *mat, GLfloat x, GLfloat y, GLfloat z ) +{ + GLfloat *m = mat->m; + m[0] *= x; m[4] *= y; m[8] *= z; + m[1] *= x; m[5] *= y; m[9] *= z; + m[2] *= x; m[6] *= y; m[10] *= z; + m[3] *= x; m[7] *= y; m[11] *= z; + + if (fabs(x - y) < 1e-8 && fabs(x - z) < 1e-8) + mat->flags |= MAT_FLAG_UNIFORM_SCALE; + else + mat->flags |= MAT_FLAG_GENERAL_SCALE; + + mat->flags |= (MAT_DIRTY_TYPE | + MAT_DIRTY_INVERSE); +} + +void +_math_matrix_translate( GLmatrix *mat, GLfloat x, GLfloat y, GLfloat z ) +{ + GLfloat *m = mat->m; + m[12] = m[0] * x + m[4] * y + m[8] * z + m[12]; + m[13] = m[1] * x + m[5] * y + m[9] * z + m[13]; + m[14] = m[2] * x + m[6] * y + m[10] * z + m[14]; + m[15] = m[3] * x + m[7] * y + m[11] * z + m[15]; + + mat->flags |= (MAT_FLAG_TRANSLATION | + MAT_DIRTY_TYPE | + MAT_DIRTY_INVERSE); +} + +void +_math_matrix_set_identity( GLmatrix *mat ) +{ + MEMCPY( mat->m, Identity, 16*sizeof(GLfloat) ); + + if (mat->inv) + MEMCPY( mat->inv, Identity, 16*sizeof(GLfloat) ); + + mat->type = MATRIX_IDENTITY; + mat->flags &= ~(MAT_DIRTY_FLAGS| + MAT_DIRTY_TYPE| + MAT_DIRTY_INVERSE); +} + +/*@}*/ + + +/**********************************************************************/ +/** \name Matrix analysis */ +/*@{*/ #define ZERO(x) (1<m; - m[0] *= x; m[4] *= y; m[8] *= z; - m[1] *= x; m[5] *= y; m[9] *= z; - m[2] *= x; m[6] *= y; m[10] *= z; - m[3] *= x; m[7] *= y; m[11] *= z; - - if (fabs(x - y) < 1e-8 && fabs(x - z) < 1e-8) - mat->flags |= MAT_FLAG_UNIFORM_SCALE; - else - mat->flags |= MAT_FLAG_GENERAL_SCALE; - - mat->flags |= (MAT_DIRTY_TYPE | - MAT_DIRTY_INVERSE); -} - - -void -_math_matrix_translate( GLmatrix *mat, GLfloat x, GLfloat y, GLfloat z ) -{ - GLfloat *m = mat->m; - m[12] = m[0] * x + m[4] * y + m[8] * z + m[12]; - m[13] = m[1] * x + m[5] * y + m[9] * z + m[13]; - m[14] = m[2] * x + m[6] * y + m[10] * z + m[14]; - m[15] = m[3] * x + m[7] * y + m[11] * z + m[15]; - - mat->flags |= (MAT_FLAG_TRANSLATION | - MAT_DIRTY_TYPE | - MAT_DIRTY_INVERSE); -} - - void _math_matrix_loadf( GLmatrix *mat, const GLfloat *m ) { @@ -1063,7 +1253,6 @@ _math_matrix_dtr( GLmatrix *m ) } } - void _math_matrix_alloc_inv( GLmatrix *m ) { @@ -1074,47 +1263,12 @@ _math_matrix_alloc_inv( GLmatrix *m ) } } - -void -_math_matrix_mul_matrix( GLmatrix *dest, const GLmatrix *a, const GLmatrix *b ) -{ - dest->flags = (a->flags | - b->flags | - MAT_DIRTY_TYPE | - MAT_DIRTY_INVERSE); - - if (TEST_MAT_FLAGS(dest, MAT_FLAGS_3D)) - matmul34( dest->m, a->m, b->m ); - else - matmul4( dest->m, a->m, b->m ); -} - - -void -_math_matrix_mul_floats( GLmatrix *dest, const GLfloat *m ) -{ - dest->flags |= (MAT_FLAG_GENERAL | - MAT_DIRTY_TYPE | - MAT_DIRTY_INVERSE); - - matmul4( dest->m, dest->m, m ); -} - -void -_math_matrix_set_identity( GLmatrix *mat ) -{ - MEMCPY( mat->m, Identity, 16*sizeof(GLfloat) ); - - if (mat->inv) - MEMCPY( mat->inv, Identity, 16*sizeof(GLfloat) ); - - mat->type = MATRIX_IDENTITY; - mat->flags &= ~(MAT_DIRTY_FLAGS| - MAT_DIRTY_TYPE| - MAT_DIRTY_INVERSE); -} +/*@}*/ +/**********************************************************************/ +/** \name Matrix transpose */ +/*@{*/ void _math_transposef( GLfloat to[16], const GLfloat from[16] ) @@ -1137,7 +1291,6 @@ _math_transposef( GLfloat to[16], const GLfloat from[16] ) to[15] = from[15]; } - void _math_transposed( GLdouble to[16], const GLdouble from[16] ) { @@ -1179,3 +1332,6 @@ _math_transposefd( GLfloat to[16], const GLdouble from[16] ) to[14] = (GLfloat) from[11]; to[15] = (GLfloat) from[15]; } + +/*@}*/ + diff --git a/src/mesa/math/m_matrix.h b/src/mesa/math/m_matrix.h index d042b746282..2bc080b2896 100644 --- a/src/mesa/math/m_matrix.h +++ b/src/mesa/math/m_matrix.h @@ -1,4 +1,7 @@ -/* $Id: m_matrix.h,v 1.4 2001/03/12 00:48:41 gareth Exp $ */ +/** + * \file m_matrix.h + * \brief Matrix operations. + */ /* * Mesa 3-D graphics library @@ -24,13 +27,15 @@ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/* $Id: m_matrix.h,v 1.4.8.1 2003/03/02 00:27:36 jrfonseca Exp $ */ #ifndef _M_MATRIX_H #define _M_MATRIX_H -/* Give symbolic names to some of the entries in the matrix to help +/** + * Give symbolic names to some of the entries in the matrix to help * out with the rework of the viewport_map as a matrix transform. */ #define MAT_SX 0 @@ -40,43 +45,52 @@ #define MAT_TY 13 #define MAT_TZ 14 -/* - * Different kinds of 4x4 transformation matrices: +/** + * \brief Different kinds of 4x4 transformation matrices. */ -#define MATRIX_GENERAL 0 /* general 4x4 matrix */ -#define MATRIX_IDENTITY 1 /* identity matrix */ -#define MATRIX_3D_NO_ROT 2 /* ortho projection and others... */ -#define MATRIX_PERSPECTIVE 3 /* perspective projection matrix */ -#define MATRIX_2D 4 /* 2-D transformation */ -#define MATRIX_2D_NO_ROT 5 /* 2-D scale & translate only */ -#define MATRIX_3D 6 /* 3-D transformation */ +enum GLmatrixtype { + MATRIX_GENERAL = 0, /**< \brief general 4x4 matrix */ + MATRIX_IDENTITY = 1, /**< \brief identity matrix */ + MATRIX_3D_NO_ROT = 2, /**< \brief ortho projection and others... */ + MATRIX_PERSPECTIVE = 3, /**< \brief perspective projection matrix */ + MATRIX_2D = 4, /**< \brief 2-D transformation */ + MATRIX_2D_NO_ROT = 5, /**< \brief 2-D scale & translate only */ + MATRIX_3D = 6, /**< \brief 3-D transformation */ +} ; -#define MAT_FLAG_IDENTITY 0 -#define MAT_FLAG_GENERAL 0x1 -#define MAT_FLAG_ROTATION 0x2 -#define MAT_FLAG_TRANSLATION 0x4 -#define MAT_FLAG_UNIFORM_SCALE 0x8 -#define MAT_FLAG_GENERAL_SCALE 0x10 -#define MAT_FLAG_GENERAL_3D 0x20 -#define MAT_FLAG_PERSPECTIVE 0x40 -#define MAT_FLAG_SINGULAR 0x80 -#define MAT_DIRTY_TYPE 0x100 -#define MAT_DIRTY_FLAGS 0x200 -#define MAT_DIRTY_INVERSE 0x400 +#define MAT_FLAG_IDENTITY 0 /**< \brief is an identity matrix flag. + * (Not actualy used - the identity + * matrix is identified by the abcense + / of all other flags.) */ +#define MAT_FLAG_GENERAL 0x1 /**< \brief is a general matrix flag */ +#define MAT_FLAG_ROTATION 0x2 /**< \brief is a rotation matrix flag */ +#define MAT_FLAG_TRANSLATION 0x4 /**< \brief is a translation matrix flag */ +#define MAT_FLAG_UNIFORM_SCALE 0x8 /**< \brief is an uniform scaling matrix flag */ +#define MAT_FLAG_GENERAL_SCALE 0x10 /**< \brief is a general scaling matrix flag */ +#define MAT_FLAG_GENERAL_3D 0x20 /**< \brief general 3D matrix flag */ +#define MAT_FLAG_PERSPECTIVE 0x40 /**< \brief is a perspective projection matrix flag */ +#define MAT_FLAG_SINGULAR 0x80 /**< \brief is a singular matrix flag */ +#define MAT_DIRTY_TYPE 0x100 /**< \brief matrix type is dirty */ +#define MAT_DIRTY_FLAGS 0x200 /**< \brief matrix flags are dirty */ +#define MAT_DIRTY_INVERSE 0x400 /**< \brief matrix inverse is dirty */ +/** \brief angle preserving matrix flags mask */ #define MAT_FLAGS_ANGLE_PRESERVING (MAT_FLAG_ROTATION | \ MAT_FLAG_TRANSLATION | \ MAT_FLAG_UNIFORM_SCALE) +/** \brief length preserving matrix flags mask */ #define MAT_FLAGS_LENGTH_PRESERVING (MAT_FLAG_ROTATION | \ MAT_FLAG_TRANSLATION) +/** \brief 3D (non-perspective) matrix flags mask */ #define MAT_FLAGS_3D (MAT_FLAG_ROTATION | \ MAT_FLAG_TRANSLATION | \ MAT_FLAG_UNIFORM_SCALE | \ MAT_FLAG_GENERAL_SCALE | \ MAT_FLAG_GENERAL_3D) +/** \brief geometry related matrix flags mask */ #define MAT_FLAGS_GEOMETRY (MAT_FLAG_GENERAL | \ MAT_FLAG_ROTATION | \ MAT_FLAG_TRANSLATION | \ @@ -86,19 +100,32 @@ MAT_FLAG_PERSPECTIVE | \ MAT_FLAG_SINGULAR) +/** \brief dirty matrix flags mask */ #define MAT_DIRTY (MAT_DIRTY_TYPE | \ MAT_DIRTY_FLAGS | \ MAT_DIRTY_INVERSE) +/** + * \brief Test geometry related matrix flags. + * + * \param mat a pointer to a GLmatrix structure. + * \param a flags mask. + * + * \returns non-zero if all geometry related matrix flags are contained within + * the mask, or zero otherwise. + */ #define TEST_MAT_FLAGS(mat, a) \ ((MAT_FLAGS_GEOMETRY & (~(a)) & ((mat)->flags) ) == 0) +/** + * \brief Matrix. + */ typedef struct { - GLfloat *m; /* 16-byte aligned */ - GLfloat *inv; /* optional, 16-byte aligned */ - GLuint flags; - GLuint type; /* one of the MATRIX_* values */ + GLfloat *m; /**< \brief matrix, 16-byte aligned */ + GLfloat *inv; /**< \brief optional inverse, 16-byte aligned */ + GLuint flags; /**< \brief property flags */ + GLuint type; /**< \brief one of the GLmatrixtype values */ } GLmatrix; @@ -158,9 +185,11 @@ _math_matrix_print( const GLmatrix *m ); - -/* Related functions that don't actually operate on GLmatrix structs: +/** + * \name Related functions that don't actually operate on GLmatrix structs */ +/*@{*/ + extern void _math_transposef( GLfloat to[16], const GLfloat from[16] ); @@ -170,7 +199,7 @@ _math_transposed( GLdouble to[16], const GLdouble from[16] ); extern void _math_transposefd( GLfloat to[16], const GLdouble from[16] ); - +/*@}*/ #endif