From 71f8b2b2e6f53f1437413c6adc3d30df037bcbe5 Mon Sep 17 00:00:00 2001 From: Jose Fonseca Date: Sat, 5 Apr 2003 16:42:15 +0000 Subject: Some Doxygenization of the comments --- src/mesa/tnl/NOTES | 102 ------------- src/mesa/tnl/t_array_api.c | 12 +- src/mesa/tnl/t_context.c | 129 +++++++++++++++- src/mesa/tnl/t_context.h | 357 +++++++++++++++++++++++++++++---------------- src/mesa/tnl/t_imm_api.c | 54 +++++-- src/mesa/tnl/t_imm_api.h | 12 +- src/mesa/tnl/t_imm_exec.c | 12 +- src/mesa/tnl/tnl.h | 38 +++-- 8 files changed, 447 insertions(+), 269 deletions(-) delete mode 100644 src/mesa/tnl/NOTES diff --git a/src/mesa/tnl/NOTES b/src/mesa/tnl/NOTES deleted file mode 100644 index c39b43485e..0000000000 --- a/src/mesa/tnl/NOTES +++ /dev/null @@ -1,102 +0,0 @@ -INTRODUCTION - -A generic, configurable software implementation of GL transformation & -lighting. - -This module provides an implementation of the routines required by the -'vtxfmt' mechanism of core mesa for tnl functionality in all -combinations of compile and execute modes. - -Most current drivers use the tnl module exclusively to provide this -functionality, though there is an experimental alternate -implementation provided by the tnl_dd/t_dd_imm_* files which can -handle a small subset of GL states in execute mode only. - - -STATE - -To create and destroy the module: - - GLboolean _tnl_CreateContext( GLcontext *ctx ); - void _tnl_DestroyContext( GLcontext *ctx ); - -The module is not active by default, and must be installed by calling -_tnl_Wakeup(). This function installs internal tnl functions into all -the vtxfmt dispatch hooks, thus taking over the task of transformation -and lighting entirely: - - void _tnl_wakeup_exec( GLcontext *ctx ); - void _tnl_wakeup_save_exec( GLcontext *ctx ); - - -This module tracks state changes internally and maintains derived -values based on the current state. For this to work, the driver -ensure the following funciton is called whenever the state changes and -the swsetup module is 'awake': - - void _tnl_InvalidateState( GLcontext *ctx, GLuint new_state ); - -There is no explicit call to put the tnl module to sleep. Simply -install other function pointers into all the vtxfmt dispatch slots, -and (optionally) cease calling _tnl_InvalidateState(). - -CUSTOMIZATION - -The module provides customizability through several mechanisms. The -most important is by allowing drivers to specify the pipeline through -which vertex data is passed, including its eventual transfer to -rasterization hardware (or software). - -The default pipeline is specified in t_pipeline.c, and is usually a -starting point for driver pipelines. Some drivers will remove a stage -where hardware provides support for the implemented operation (for -instance fog where per-pixel hardware fog is available, as in the dri -tdfx driver), or add stages to shortcircuit latter operations (for -example taking advantage of hardware support for strips and other -higher-level primitives (for example the radeon driver). - -In addition, the following functions provide further tweaks: - -extern void -_tnl_need_projected_coords( GLcontext *ctx, GLboolean flag ); - - - Direct the default vertex transformation stage to - produce/not produce projected clip coordinates. - -extern void -_tnl_need_dlist_loopback( GLcontext *ctx, GLboolean flag ); - - - Direct the display list component of the tnl module to - replay display lists as 'glVertex' type calls, rather than - passing the display list data directly into the tnl pipeline - mechanism. - - This allows display lists to be replayed by the tnl module - even when the module is not strictly active. - - -extern void -_tnl_need_dlist_norm_lengths( GLcontext *ctx, GLboolean flag ); - - - Direct the display list component to enable/disable caching - 1/length values for display list normals. Doing so is - ususally helpful when lighting is performed in software, but - wasteful otherwise. - - -DRIVER INTERFACE - -The module itself offers a minimal driver interface: - - void (*RunPipeline)( GLcontext *ctx ); - -Normally this is set to _tnl_RunPipeline(), however the driver can use -this hook to wrap checks or other code around this call. - -In addition, the driver interface for the default render pipeline -stage is housed in the tnl context struct (this could be cleaner). - - -RENDER DRIVER INTERFACE - -See t_context.h for the definition and explanation of this. \ No newline at end of file diff --git a/src/mesa/tnl/t_array_api.c b/src/mesa/tnl/t_array_api.c index 19cb19b716..edb2a8db92 100644 --- a/src/mesa/tnl/t_array_api.c +++ b/src/mesa/tnl/t_array_api.c @@ -1,4 +1,8 @@ -/* $Id: t_array_api.c,v 1.31 2003/03/01 01:50:26 brianp Exp $ */ +/** + * \file t_array_api.c + * \brief Vertex array API functions (glDrawArrays, etc) + * \author Keith Whitwell + */ /* * Mesa 3-D graphics library @@ -24,11 +28,7 @@ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ -/** - * \file t_array_api.c - * \brief Vertex array API functions (glDrawArrays, etc) - * \author Keith Whitwell - */ +/* $Id: t_array_api.c,v 1.31.2.1 2003/04/05 16:42:15 jrfonseca Exp $ */ #include "glheader.h" #include "api_validate.h" diff --git a/src/mesa/tnl/t_context.c b/src/mesa/tnl/t_context.c index 6e8f48aaec..6693a27b0e 100644 --- a/src/mesa/tnl/t_context.c +++ b/src/mesa/tnl/t_context.c @@ -1,4 +1,8 @@ -/* $Id: t_context.c,v 1.31 2003/02/04 14:40:56 brianp Exp $ */ +/** + * \file t_context.c + * + * \author Keith Whitwell + */ /* * Mesa 3-D graphics library @@ -23,10 +27,129 @@ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * - * Authors: - * Keith Whitwell */ +/* $Id: t_context.c,v 1.31.2.1 2003/04/05 16:42:15 jrfonseca Exp $ */ + +/** + * \mainpage + * + * \section TnlIntroduction Introduction + * + * A generic, configurable software implementation of GL transformation & + * lighting. + * + * This module provides an implementation of the routines required by the + * 'vtxfmt' mechanism of core mesa for tnl functionality in all + * combinations of compile and execute modes. + * + * Most current drivers use the tnl module exclusively to provide this + * functionality, though there is an experimental alternate + * implementation provided by the tnl_dd/t_dd_imm_* files which can + * handle a small subset of GL states in execute mode only. + * + * + * \section TnlState State + * + * To create and destroy the module: + * + * \code + * GLboolean _tnl_CreateContext( GLcontext *ctx ); + * void _tnl_DestroyContext( GLcontext *ctx ); + * \endcode + * + * The module is not active by default, and must be installed by calling + * _tnl_Wakeup(). This function installs internal tnl functions into all + * the vtxfmt dispatch hooks, thus taking over the task of transformation + * and lighting entirely: + * + * \code + * void _tnl_wakeup_exec( GLcontext *ctx ); + * void _tnl_wakeup_save_exec( GLcontext *ctx ); + * \endcode + * + * This module tracks state changes internally and maintains derived + * values based on the current state. For this to work, the driver + * ensure the following funciton is called whenever the state changes and + * the swsetup module is 'awake': + * + * \code + * void _tnl_InvalidateState( GLcontext *ctx, GLuint new_state ); + * \endcode + * + * There is no explicit call to put the tnl module to sleep. Simply + * install other function pointers into all the vtxfmt dispatch slots, + * and (optionally) cease calling _tnl_InvalidateState(). + * + * \section TnlCustomization Customization + * + * The module provides customizability through several mechanisms. The + * most important is by allowing drivers to specify the pipeline through + * which vertex data is passed, including its eventual transfer to + * rasterization hardware (or software). + * + * The default pipeline is specified in t_pipeline.c, and is usually a + * starting point for driver pipelines. Some drivers will remove a stage + * where hardware provides support for the implemented operation (for + * instance fog where per-pixel hardware fog is available, as in the dri + * tdfx driver), or add stages to shortcircuit latter operations (for + * example taking advantage of hardware support for strips and other + * higher-level primitives (for example the radeon driver). + * + * In addition, the following functions provide further tweaks: + * + * \code + * extern void + * _tnl_need_projected_coords( GLcontext *ctx, GLboolean flag ); + * \endcode + * + * - Direct the default vertex transformation stage to + * produce/not produce projected clip coordinates. + * + * \code + * extern void + * _tnl_need_dlist_loopback( GLcontext *ctx, GLboolean flag ); + * \endcode + * + * - Direct the display list component of the tnl module to + * replay display lists as 'glVertex' type calls, rather than + * passing the display list data directly into the tnl pipeline + * mechanism. + * + * This allows display lists to be replayed by the tnl module + * even when the module is not strictly active. + * + * + * \code + * extern void + * _tnl_need_dlist_norm_lengths( GLcontext *ctx, GLboolean flag ); + * \endcode + * + * - Direct the display list component to enable/disable caching + * 1/length values for display list normals. Doing so is + * ususally helpful when lighting is performed in software, but + * wasteful otherwise. + * + * + * \section TnlDriverInterface Driver Interface + * + * The module itself offers a minimal driver interface: + * + * \code + * void (*RunPipeline)( GLcontext *ctx ); + * \endcode + * + * Normally this is set to _tnl_RunPipeline(), however the driver can use + * this hook to wrap checks or other code around this call. + * + * In addition, the driver interface for the default render pipeline + * stage is housed in the tnl context struct (this could be cleaner). + * + * + * \section TnlRenderDriverInterface Render Driver Interface + * + * See t_context.h for the definition and explanation of this. + */ #include "glheader.h" #include "imports.h" diff --git a/src/mesa/tnl/t_context.h b/src/mesa/tnl/t_context.h index b7153c545f..96a4d2be69 100644 --- a/src/mesa/tnl/t_context.h +++ b/src/mesa/tnl/t_context.h @@ -1,4 +1,8 @@ -/* $Id: t_context.h,v 1.46 2003/03/31 18:19:56 brianp Exp $ */ +/** + * \file t_context.h + * \brief TnL module datatypes and definitions. + * \author Keith Whitwell + */ /* * Mesa 3-D graphics library @@ -24,11 +28,7 @@ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ -/** - * \file t_context.h - * \brief TnL module datatypes and definitions. - * \author Keith Whitwell - */ +/* $Id: t_context.h,v 1.46.2.1 2003/04/05 16:42:15 jrfonseca Exp $ */ #ifndef _T_CONTEXT_H #define _T_CONTEXT_H @@ -44,38 +44,50 @@ #define MAX_PIPELINE_STAGES 30 -/* Numbers for sizing immediate structs. +/** + * \name Numbers for sizing immediate structs. */ +/*@{*/ #define IMM_MAX_COPIED_VERTS 3 #define IMM_MAXDATA (216 + IMM_MAX_COPIED_VERTS) #define IMM_SIZE (IMM_MAXDATA + MAX_CLIPPED_VERTICES) +/*@}*/ -/* Values for IM->BeginState +/** + * \name Values for immediate::BeginState */ -#define VERT_BEGIN_0 0x1 /* glBegin (if initially inside beg/end) */ -#define VERT_BEGIN_1 0x2 /* glBegin (if initially outside beg/end) */ -#define VERT_ERROR_0 0x4 /* invalid_operation in initial state 0 */ -#define VERT_ERROR_1 0x8 /* invalid_operation in initial state 1 */ +/*@{*/ +#define VERT_BEGIN_0 0x1 /**< glBegin (if initially inside beg/end) */ +#define VERT_BEGIN_1 0x2 /**< glBegin (if initially outside beg/end) */ +#define VERT_ERROR_0 0x4 /**< invalid_operation in initial state 0 */ +#define VERT_ERROR_1 0x8 /**< invalid_operation in initial state 1 */ +/*@}*/ -/* Flags to be added to the primitive enum in VB->Primitive. +/** + * \name Flags to be added to the primitive enum in vertex_buffer::Primitive. */ -#define PRIM_MODE_MASK 0xff /* Extract the actual primitive */ -#define PRIM_BEGIN 0x100 /* The prim starts here (not wrapped) */ -#define PRIM_END 0x200 /* The prim ends in this VB (does not wrap) */ -#define PRIM_PARITY 0x400 /* The prim wrapped on an odd number of verts */ -#define PRIM_LAST 0x800 /* No more prims in the VB */ +/*@{*/ +#define PRIM_MODE_MASK 0xff /**< Extract the actual primitive */ +#define PRIM_BEGIN 0x100 /**< The prim starts here (not wrapped) */ +#define PRIM_END 0x200 /**< The prim ends in this VB (does not wrap) */ +#define PRIM_PARITY 0x400 /**< The prim wrapped on an odd number of verts */ +#define PRIM_LAST 0x800 /**< No more prims in the VB */ +/*@}*/ /** - * Flags that describe the inputs and outputs of pipeline stages, and - * the contents of a vertex-cassette. We reuse the VERT_BIT_* flags - * defined in mtypes.h and add a bunch of new ones. + * \name Flags that describe the inputs and outputs of pipeline stages, and + * the contents of a vertex-cassette. + * + * We reuse the VERT_BIT_* flags defined in mtypes.h and add a bunch of new + * ones. */ +/*@{*/ /* bits 0..5 defined in mtypes.h */ -#define VERT_BIT_INDEX VERT_BIT_SIX /* a free vertex attrib bit */ -#define VERT_BIT_EDGEFLAG VERT_BIT_SEVEN /* a free vertex attrib bit */ +#define VERT_BIT_INDEX VERT_BIT_SIX /**< a free vertex attrib bit */ +#define VERT_BIT_EDGEFLAG VERT_BIT_SEVEN /**< a free vertex attrib bit */ /* bits 8..15 defined in mtypes.h */ #define VERT_BIT_EVAL_C1 (1 << 16) /* imm only */ #define VERT_BIT_EVAL_C2 (1 << 17) /* imm only */ @@ -91,14 +103,20 @@ #define VERT_BIT_POINT_SIZE (1 << 27) /* vb only, could reuse a bit */ #define VERT_BIT_EYE VERT_BIT_BEGIN /* vb only, reuse imm bit */ #define VERT_BIT_CLIP VERT_BIT_END /* vb only, reuse imm bit*/ +/*@}*/ -/* Flags for IM->TexCoordSize. Enough flags for 16 units. +/** + * \name Flags for immediate::TexCoordSize. + * + * Enough flags for 16 units. */ +/*@{*/ #define TEX_0_SIZE_3 (unsigned)0x1 #define TEX_0_SIZE_4 (unsigned)0x10001 #define TEX_SIZE_3(unit) (TEX_0_SIZE_3 << (unit)) #define TEX_SIZE_4(unit) (TEX_0_SIZE_4 << (unit)) +/*@}*/ /* Shorthands. @@ -144,22 +162,27 @@ /** * Stores everything that can take place between a glBegin and glEnd. - * Adjacent glBegin/glEnd pairs are stored back-to-back when there's no + * + * Adjacent glBegin()/glEnd() pairs are stored back-to-back when there's no * state changes between them. + * * Used for immediate mode rendering and display lists. */ struct immediate { GLuint id, ref_count; - /* This must be saved when immediates are shared in display lists. + /** + * \name This must be saved when immediates are shared in display lists. */ + /*@{*/ GLuint CopyStart, Start, Count; GLuint LastData; /* count or count+1 */ GLuint AndFlag, OrFlag; GLuint TexSize; /* keep track of texcoord sizes */ GLuint BeginState, SavedBeginState; GLuint LastPrimitive; + /*@}*/ GLuint ArrayEltFlags; /* precalc'ed for glArrayElt */ GLuint ArrayEltIncr; @@ -174,10 +197,12 @@ struct immediate /* Temporary values created when vertices are copied into the * first 3 slots of the struct: */ + /*@{*/ GLuint CopyOrFlag; GLuint CopyAndFlag; GLuint CopyTexSize; GLuint Evaluated; + /*@}*/ /* allocate storage for these on demand: @@ -192,14 +217,16 @@ struct immediate GLuint PrimitiveLength[IMM_SIZE]; /* BEGIN/END */ GLuint Flag[IMM_SIZE]; /* VERT_BIT_* flags */ - /* Attrib is an array [MAX_VERT_ATTRIBS] of pointer to array [][4] + /** + * Attrib is an array [MAX_VERT_ATTRIBS] of pointer to array [][4] * of GLfloat. + * * We only pre-allocate the vertex position array. The other vertex * attribute arrays are only allocated when needed to save memory. */ GLfloat (*Attrib[VERT_ATTRIB_MAX])[4]; - GLfloat *NormalLengthPtr; /* length of normal vectors (display list only) */ + GLfloat *NormalLengthPtr; /**< length of normal vectors (display list only) */ GLuint Elt[IMM_SIZE]; GLubyte EdgeFlag[IMM_SIZE]; @@ -209,7 +236,9 @@ struct immediate struct vertex_arrays { - /* Conventional vertex attribute arrays */ + /** + * \name Conventional vertex attribute arrays + */ GLvector4f Obj; GLvector4f Normal; struct gl_client_array Color; @@ -220,7 +249,8 @@ struct vertex_arrays GLvector1ui Index; GLvector1ui Elt; - /* These attributes don't alias with the conventional attributes. + /** + * These attributes don't alias with the conventional attributes. * The GL_NV_vertex_program extension defines 16 extra sets of vertex * arrays which have precedent over the conventional arrays when enabled. */ @@ -233,47 +263,57 @@ struct vertex_arrays */ typedef struct vertex_buffer { - /* Constant over life of the vertex_buffer. + /** + * \name Constant over life of the vertex_buffer. */ + /*@{*/ GLuint Size; + /*@}*/ - /* Constant over the pipeline. + /** + * \name Constant over the pipeline. */ + /*@{*/ GLuint Count; /* for everything except Elts */ GLuint FirstClipped; /* temp verts for clipping */ GLuint FirstPrimitive; /* usually zero */ + /*@}*/ - /* Pointers to current data. - */ - GLuint *Elts; /* VERT_BIT_ELT */ - GLvector4f *ObjPtr; /* VERT_BIT_POS */ - GLvector4f *EyePtr; /* VERT_BIT_EYE */ - GLvector4f *ClipPtr; /* VERT_BIT_CLIP */ - GLvector4f *NdcPtr; /* VERT_BIT_CLIP (2) */ - GLubyte ClipOrMask; /* VERT_BIT_CLIP (3) */ - GLubyte *ClipMask; /* VERT_BIT_CLIP (4) */ - GLvector4f *NormalPtr; /* VERT_BIT_NORMAL */ - GLfloat *NormalLengthPtr; /* VERT_BIT_NORMAL */ - GLboolean *EdgeFlag; /* VERT_BIT_EDGEFLAG */ - GLvector4f *TexCoordPtr[MAX_TEXTURE_COORD_UNITS]; /* VERT_TEX_0..n */ - GLvector1ui *IndexPtr[2]; /* VERT_BIT_INDEX */ - struct gl_client_array *ColorPtr[2]; /* VERT_BIT_COLOR0 */ - struct gl_client_array *SecondaryColorPtr[2];/* VERT_BIT_COLOR1 */ - GLvector4f *PointSizePtr; /* VERT_BIT_POINT_SIZE */ - GLvector4f *FogCoordPtr; /* VERT_BIT_FOG */ - struct gl_material (*Material)[2]; /* VERT_BIT_MATERIAL, optional */ - GLuint *MaterialMask; /* VERT_BIT_MATERIAL, optional */ - GLuint *Flag; /* VERT_BIT_* flags, optional */ - GLuint *Primitive; /* GL_(mode)|PRIM_* flags */ - GLuint *PrimitiveLength; /* integers */ - - /* Inputs to the vertex program stage */ + /** + * \name Pointers to current data. + */ + /*@{*/ + GLuint *Elts; /**< VERT_BIT_ELT */ + GLvector4f *ObjPtr; /**< VERT_BIT_POS */ + GLvector4f *EyePtr; /**< VERT_BIT_EYE */ + GLvector4f *ClipPtr; /**< VERT_BIT_CLIP */ + GLvector4f *NdcPtr; /**< VERT_BIT_CLIP (2) */ + GLubyte ClipOrMask; /**< VERT_BIT_CLIP (3) */ + GLubyte *ClipMask; /**< VERT_BIT_CLIP (4) */ + GLvector4f *NormalPtr; /**< VERT_BIT_NORMAL */ + GLfloat *NormalLengthPtr; /**< VERT_BIT_NORMAL */ + GLboolean *EdgeFlag; /**< VERT_BIT_EDGEFLAG */ + GLvector4f *TexCoordPtr[MAX_TEXTURE_COORD_UNITS]; /**< VERT_TEX_0..n */ + GLvector1ui *IndexPtr[2]; /**< VERT_BIT_INDEX */ + struct gl_client_array *ColorPtr[2]; /**< VERT_BIT_COLOR0 */ + struct gl_client_array *SecondaryColorPtr[2];/**< VERT_BIT_COLOR1 */ + GLvector4f *PointSizePtr; /**< VERT_BIT_POINT_SIZE */ + GLvector4f *FogCoordPtr; /**< VERT_BIT_FOG */ + struct gl_material (*Material)[2]; /**< VERT_BIT_MATERIAL, optional */ + GLuint *MaterialMask; /**< VERT_BIT_MATERIAL, optional */ + GLuint *Flag; /**< VERT_BIT_* flags, optional */ + GLuint *Primitive; /**< GL_(mode)|PRIM_* flags */ + GLuint *PrimitiveLength; /**< integers */ + /*@}*/ + + /** Inputs to the vertex program stage */ GLvector4f *AttribPtr[VERT_ATTRIB_MAX]; /* GL_NV_vertex_program */ GLuint importable_data; void *import_source; void (*import_data)( GLcontext *ctx, GLuint flags, GLuint vecflags ); - /* Callback to the provider of the untransformed input for the + /**< + * Callback to the provider of the untransformed input for the * render stage (or other stages) to call if they need to write into * write-protected arrays, or fixup the stride on input arrays. * @@ -282,7 +322,8 @@ typedef struct vertex_buffer */ GLuint LastClipped; - /* Private data from _tnl_render_stage that has no business being + /**< + * Private data from _tnl_render_stage that has no business being * in this struct. */ @@ -290,43 +331,56 @@ typedef struct vertex_buffer -/* Describes an individual operation on the pipeline. +/** + * Describes an individual operation on the pipeline. */ struct gl_pipeline_stage { const char *name; - GLuint check_state; /* All state referenced in check() -- + GLuint check_state; /**< + * All state referenced in check() -- * When is the pipeline_stage struct * itself invalidated? Must be * constant. */ - /* Usually constant or set by the 'check' callback: + /** + * \name Usually constant or set by the 'check' callback: */ - GLuint run_state; /* All state referenced in run() -- + /*@{*/ + GLuint run_state; /**< + * All state referenced in run() -- * When is the cached output of the * stage invalidated? */ - GLboolean active; /* True if runnable in current state */ - GLuint inputs; /* VERT_* inputs to the stage */ - GLuint outputs; /* VERT_* outputs of the stage */ + GLboolean active; /**< True if runnable in current state */ + GLuint inputs; /**< VERT_* inputs to the stage */ + GLuint outputs; /**< VERT_* outputs of the stage */ + /*@}*/ - /* Set in _tnl_run_pipeline(): + /** + * \name Set in _tnl_run_pipeline(): */ - GLuint changed_inputs; /* Generated value -- inputs to the + /*@{*/ + GLuint changed_inputs; /**< + * Generated value -- inputs to the * stage that have changed since last * call to 'run'. */ + /*@}*/ - /* Private data for the pipeline stage: + /** + * Private data for the pipeline stage: */ void *privatePtr; - /* Free private data. May not be null. + /** + * Free private data. May not be null. */ void (*destroy)( struct gl_pipeline_stage * ); - /* Called from _tnl_validate_pipeline(). Must update all fields in + /** + * Called from _tnl_validate_pipeline(). Must update all fields in * the pipeline_stage struct for the current state. */ void (*check)( GLcontext *ctx, struct gl_pipeline_stage * ); @@ -343,12 +397,15 @@ struct gl_pipeline_stage { }; +/** + * The pipeline. + */ struct gl_pipeline { - GLuint build_state_trigger; /* state changes which require build */ - GLuint build_state_changes; /* state changes since last build */ - GLuint run_state_changes; /* state changes since last run */ - GLuint run_input_changes; /* VERT_* changes since last run */ - GLuint inputs; /* VERT_* inputs to pipeline */ + GLuint build_state_trigger; /**< state changes which require build */ + GLuint build_state_changes; /**< state changes since last build */ + GLuint run_state_changes; /**< state changes since last run */ + GLuint run_input_changes; /**< VERT_* changes since last run */ + GLuint inputs; /**< VERT_* inputs to pipeline */ struct gl_pipeline_stage stages[MAX_PIPELINE_STAGES+1]; GLuint nr_stages; }; @@ -381,87 +438,116 @@ typedef void (*setup_func)( GLcontext *ctx, GLuint new_inputs); +/** + * TNL device driver callbacks + */ struct tnl_device_driver { - /*** - *** TNL Pipeline - ***/ + /** + * \name TNL Pipeline + */ + /*@{*/ void (*RunPipeline)(GLcontext *ctx); - /* Replaces PipelineStart/PipelineFinish -- intended to allow + /**< + * Replaces PipelineStart/PipelineFinish -- intended to allow * drivers to wrap _tnl_run_pipeline() with code to validate state * and grab/release hardware locks. */ void (*NotifyMaterialChange)(GLcontext *ctx); - /* Alert tnl-aware drivers of changes to material. + /**< + * Alert tnl-aware drivers of changes to material. */ GLboolean (*NotifyBegin)(GLcontext *ctx, GLenum p); - /* Allow drivers to hook in optimized begin/end engines. - * Return value: GL_TRUE - driver handled the begin - * GL_FALSE - driver didn't handle the begin + /**< + * Allow drivers to hook in optimized begin/end engines. + * + * \return GL_TRUE if driver handled the begin, or GL_FALSE otherwise. */ + /*@}*/ - /*** - *** Rendering -- These functions called only from t_vb_render.c - ***/ + /** + * Rendering. + * + * These functions called only from t_vb_render.c + */ struct { - void (*Start)(GLcontext *ctx); - void (*Finish)(GLcontext *ctx); - /* Called before and after all rendering operations, including DrawPixels, + /** + * Called before and after all rendering operations, including DrawPixels, * ReadPixels, Bitmap, span functions, and CopyTexImage, etc commands. * These are a suitable place for grabbing/releasing hardware locks. */ + /*@{*/ + void (*Start)(GLcontext *ctx); + void (*Finish)(GLcontext *ctx); + /*@}*/ - void (*PrimitiveNotify)(GLcontext *ctx, GLenum mode); - /* Called between RenderStart() and RenderFinish() to indicate the + /** + * Called between RenderStart() and RenderFinish() to indicate the * type of primitive we're about to draw. Mode will be one of the * modes accepted by glBegin(). */ + void (*PrimitiveNotify)(GLcontext *ctx, GLenum mode); - interp_func Interp; - /* The interp function is called by the clipping routines when we need + /** + * The interp function is called by the clipping routines when we need * to generate an interpolated vertex. All pertinant vertex ancilliary * data should be computed by interpolating between the 'in' and 'out' * vertices. */ + interp_func Interp; - copy_pv_func CopyPV; - /* The copy function is used to make a copy of a vertex. All pertinant + /** + * The copy function is used to make a copy of a vertex. All pertinant * vertex attributes should be copied. */ + copy_pv_func CopyPV; - void (*ClippedPolygon)( GLcontext *ctx, const GLuint *elts, GLuint n ); - /* Render a polygon with vertices whose indexes are in the + /** + * Render a polygon with vertices whose indexes are in the * array. */ + void (*ClippedPolygon)( GLcontext *ctx, const GLuint *elts, GLuint n ); + /** + * Render a line between the two vertices given by indexes v0 and v1. + */ void (*ClippedLine)( GLcontext *ctx, GLuint v0, GLuint v1 ); - /* Render a line between the two vertices given by indexes v0 and v1. */ + /** + * \name Render points, lines, triangles, and quads. + * + * These are only called via the T&L module. + */ + /*@{*/ points_func Points; /* must now respect vb->elts */ line_func Line; triangle_func Triangle; quad_func Quad; - /* These functions are called in order to render points, lines, - * triangles and quads. These are only called via the T&L module. - */ + /*@}*/ + /** + * \name Render whole unclipped primitives (points, lines, linestrips, + * lineloops, etc). + * + * The tables are indexed by the GL enum of the primitive to be rendered. + * RenderTabVerts is used for non-indexed arrays of vertices. + * RenderTabElts is used for indexed arrays of vertices. + */ + /*@{*/ render_func *PrimTabVerts; render_func *PrimTabElts; - /* Render whole unclipped primitives (points, lines, linestrips, - * lineloops, etc). The tables are indexed by the GL enum of the - * primitive to be rendered. RenderTabVerts is used for non-indexed - * arrays of vertices. RenderTabElts is used for indexed arrays of - * vertices. - */ + /*@}*/ - void (*ResetLineStipple)( GLcontext *ctx ); - /* Reset the hardware's line stipple counter. + /** + * Reset the hardware's line stipple counter. */ + void (*ResetLineStipple)( GLcontext *ctx ); setup_func BuildVertices; - /* This function is called whenever new vertices are required for + /**< + * This function is called whenever new vertices are required for * rendering. The vertices in question are those n such that start * <= n < end. The new_inputs parameter indicates those fields of * the vertex which need to be updated, if only a partial repair of @@ -472,7 +558,8 @@ struct tnl_device_driver { GLboolean (*Multipass)( GLcontext *ctx, GLuint passno ); - /* Driver may request additional render passes by returning GL_TRUE + /**< + * Driver may request additional render passes by returning GL_TRUE * when this function is called. This function will be called * after the first pass, and passes will be made until the function * returns GL_FALSE. If no function is registered, only one pass @@ -484,65 +571,82 @@ struct tnl_device_driver { }; +/** + * TNL context. + */ typedef struct { - /* Driver interface. + /** + * Driver interface. */ struct tnl_device_driver Driver; - /* Track whether the module is active. + /** + * Track whether the module is active. */ GLboolean bound_exec; - /* Display list extensions + /** + * Display list extensions */ GLuint opcode_vertex_cassette; - /* Pipeline + /** + * Pipeline */ struct gl_pipeline pipeline; struct vertex_buffer vb; - /* GLvectors for binding to vb: + /** + * \name GLvectors for binding to vb: */ + /*@{*/ struct vertex_arrays imm_inputs; struct vertex_arrays array_inputs; GLuint *tmp_primitive; GLuint *tmp_primitive_length; + /*@}*/ - /* Set when executing an internally generated begin/end object. If + /** + * Set when executing an internally generated begin/end object. If * such an object is encountered in a display list, it will be * replayed only if the list is outside any existing begin/end * objects. */ GLboolean ReplayHardBeginEnd; - /* Note which vertices need copying over succesive immediates. + /** + * \name Note which vertices need copying over succesive immediates. + * * Will add save versions to precompute vertex copying where * possible. */ + /*@{*/ struct immediate *ExecCopySource; GLuint ExecCopyCount; GLuint ExecCopyElts[IMM_MAX_COPIED_VERTS]; GLuint ExecCopyTexSize; GLuint ExecParity; + /*@}*/ GLuint DlistPrimitive; GLuint DlistPrimitiveLength; GLuint DlistLastPrimitive; - /* Cache a single free immediate (refcount == 0) + /** + * Cache a single free immediate (refcount == 0) */ struct immediate *freed_immediate; - /* Probably need a better configuration mechanism: + /** + * Probably need a better configuration mechanism: */ GLboolean NeedNdcCoords; GLboolean LoopbackDListCassettes; GLboolean CalcDListNormalLengths; GLboolean IsolateMaterials; - /* Derived state and storage for _tnl_eval_vb: + /** Derived state and storage for _tnl_eval_vb: */ struct tnl_eval_store eval; @@ -554,8 +658,9 @@ typedef struct { } TNLcontext; - +/** Get the TNL context pointer from the GL context pointer */ #define TNL_CONTEXT(ctx) ((TNLcontext *)(ctx->swtnl_context)) +/** Get the current immediate pointer from the GL context pointer */ #define TNL_CURRENT_IM(ctx) ((struct immediate *)(ctx->swtnl_im)) @@ -567,9 +672,10 @@ extern void _tnl_MakeCurrent( GLcontext *ctx, GLframebuffer *readBuffer ); -/* - * Macros for fetching current input buffer. +/** + * \name Macros for fetching current input buffer. */ +/*@{*/ #ifdef THREADS #define GET_IMMEDIATE struct immediate *IM = TNL_CURRENT_IM(((GLcontext *) (_glapi_Context ? _glapi_Context : _glapi_get_context()))) #define SET_IMMEDIATE(ctx, im) ctx->swtnl_im = (void *)im @@ -582,6 +688,7 @@ do { \ _tnl_CurrentInput = im; \ } while (0) #endif +/*@}*/ #endif diff --git a/src/mesa/tnl/t_imm_api.c b/src/mesa/tnl/t_imm_api.c index 0eef3b735c..81093c16b7 100644 --- a/src/mesa/tnl/t_imm_api.c +++ b/src/mesa/tnl/t_imm_api.c @@ -1,4 +1,7 @@ -/* $Id: t_imm_api.c,v 1.40 2003/03/31 18:19:56 brianp Exp $ */ +/** + * \file t_imm_api.c + * \brief TNL immediate API. + */ /* * Mesa 3-D graphics library @@ -27,6 +30,7 @@ * Keith Whitwell */ +/* $Id: t_imm_api.c,v 1.40.2.1 2003/04/05 16:42:15 jrfonseca Exp $ */ #include "glheader.h" @@ -47,7 +51,9 @@ #include "t_imm_dlist.h" -/* A cassette is full or flushed on a statechange. +/** + * + * A cassette is full or flushed on a statechange. */ void _tnl_flush_immediate( GLcontext *ctx, struct immediate *IM ) { @@ -79,7 +85,8 @@ void _tnl_flush_immediate( GLcontext *ctx, struct immediate *IM ) } -/* Hook for ctx->Driver.FlushVertices: +/** + * Hook for dd_function_table::FlushVertices */ void _tnl_flush_vertices( GLcontext *ctx, GLuint flags ) { @@ -400,7 +407,8 @@ _tnl_End(void) } -/* If the given vertex attribute array hasn't been allocated yet, +/** + * If the given vertex attribute array hasn't been allocated yet, * allocate it now. */ #define CHECK_ATTRIB_ARRAY(IM, ATTR) \ @@ -414,6 +422,9 @@ _tnl_End(void) } +/** + * Update the color attribute in the immediate structure. + */ #define COLOR( r, g, b, a ) \ { \ GET_IMMEDIATE; \ @@ -489,7 +500,9 @@ _tnl_Color4ubv( const GLubyte *v) } - +/** + * Update the secondary color attribute in the immediate structure. + */ #define SECONDARY_COLOR( r, g, b ) \ { \ GET_IMMEDIATE; \ @@ -597,6 +610,9 @@ _tnl_Indexiv( const GLint *c ) } +/** + * Update the normal attribute in the immediate structure. + */ #define NORMAL( x, y, z ) \ { \ GET_IMMEDIATE; \ @@ -639,6 +655,10 @@ _tnl_Normal3fv( const GLfloat *v ) } +/** + * \name Texture coordinates + */ +/*@{*/ #define TEXCOORD1(s) \ { \ @@ -754,8 +774,14 @@ _tnl_TexCoord4fv( const GLfloat *v ) TEXCOORD4(v[0], v[1], v[2], v[3]); } +/*@}*/ +/** + * \name Vertex coordinates + */ +/*@{*/ + /* KW: Run into bad problems in vertex copying if we don't fully pad * the incoming vertices. */ @@ -887,16 +913,18 @@ _tnl_Vertex4fv( const GLfloat *v ) VERTEX4F( IM, v[0], v[1], v[2], v[3] ); } +/*@}*/ -/* +/** * GL_ARB_multitexture * * Note: the multitexture spec says that specifying an invalid target * has undefined results and does not have to generate an error. Just * don't crash. We no-op on invalid targets. */ +/*@{*/ #define MAX_TARGET (GL_TEXTURE0_ARB + MAX_TEXTURE_COORD_UNITS) @@ -1027,6 +1055,7 @@ _tnl_MultiTexCoord4fvARB(GLenum target, const GLfloat *v) MULTI_TEXCOORD4( target, v[0], v[1], v[2], v[3] ); } +/*@}*/ /* KW: Because the eval values don't become 'current', fixup will flow @@ -1229,10 +1258,12 @@ _tnl_VertexAttrib4fvNV( GLuint index, const GLfloat *v ) } -/* Execute a glRectf() function. _tnl_hard_begin() ensures the check - * on outside_begin_end is executed even in compiled lists. These - * vertices can now participate in the same immediate as regular ones, - * even in most display lists. +/** + * Execute a glRectf() function. + * + * _tnl_hard_begin() ensures the check on outside_begin_end is executed even in + * compiled lists. These vertices can now participate in the same immediate as + * regular ones, even in most display lists. */ static void _tnl_Rectf( GLfloat x1, GLfloat y1, GLfloat x2, GLfloat y2 ) @@ -1345,6 +1376,9 @@ _tnl_Materialfv( GLenum face, GLenum pname, const GLfloat *params ) } } +/** + * Initialize our part of the GLvertexformat structure. + */ void _tnl_imm_vtxfmt_init( GLcontext *ctx ) { GLvertexformat *vfmt = &(TNL_CONTEXT(ctx)->vtxfmt); diff --git a/src/mesa/tnl/t_imm_api.h b/src/mesa/tnl/t_imm_api.h index 6615a9ce93..5d9dcaa905 100644 --- a/src/mesa/tnl/t_imm_api.h +++ b/src/mesa/tnl/t_imm_api.h @@ -1,5 +1,3 @@ -/* $Id: t_imm_api.h,v 1.5 2002/04/09 16:56:52 keithw Exp $ */ - /* * Mesa 3-D graphics library * Version: 4.1 @@ -24,6 +22,8 @@ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/* $Id: t_imm_api.h,v 1.5.8.1 2003/04/05 16:42:15 jrfonseca Exp $ */ + #ifndef _T_VTXFMT_H #define _T_VTXFMT_H @@ -40,17 +40,19 @@ extern void _tnl_Begin( GLenum mode ); extern void _tnl_End(void); -/* TNL-private internal functions for building higher-level operations: +/** + * \name TNL-private internal functions for building higher-level operations */ +/*@{*/ extern GLboolean _tnl_hard_begin( GLcontext *ctx, GLenum p ); extern void _tnl_end( GLcontext *ctx ); extern void _tnl_vertex2f( GLcontext *ctx, GLfloat x, GLfloat y ); extern void _tnl_eval_coord1f( GLcontext *CC, GLfloat u ); extern void _tnl_eval_coord2f( GLcontext *CC, GLfloat u, GLfloat v ); extern void _tnl_array_element( GLcontext *CC, GLint i ); +/*@}*/ + -/* Initialize our part of the vtxfmt struct: - */ extern void _tnl_imm_vtxfmt_init( GLcontext *ctx ); diff --git a/src/mesa/tnl/t_imm_exec.c b/src/mesa/tnl/t_imm_exec.c index 97f49762ad..1d0ec0a9bd 100644 --- a/src/mesa/tnl/t_imm_exec.c +++ b/src/mesa/tnl/t_imm_exec.c @@ -1,4 +1,8 @@ -/* $Id: t_imm_exec.c,v 1.44 2003/03/01 01:50:27 brianp Exp $ */ +/** + * \file tnl/t_imm_exec.c + * \brief Setup to execute immediate-mode vertex data. + * \author Keith Whitwell + */ /* * Mesa 3-D graphics library @@ -24,11 +28,7 @@ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ -/** - * \file tnl/t_imm_exec.c - * \brief Setup to execute immediate-mode vertex data. - * \author Keith Whitwell - */ +/* $Id: t_imm_exec.c,v 1.44.2.1 2003/04/05 16:42:15 jrfonseca Exp $ */ #include "glheader.h" #include "colormac.h" diff --git a/src/mesa/tnl/tnl.h b/src/mesa/tnl/tnl.h index 1fe7b451cc..d651aa51cb 100644 --- a/src/mesa/tnl/tnl.h +++ b/src/mesa/tnl/tnl.h @@ -1,4 +1,12 @@ -/* $Id: tnl.h,v 1.10 2002/10/29 20:29:04 brianp Exp $ */ +/** + * \file tnl.h + * \author Keith Whitwell + * \file TnL public interface. + * + * These are the public-access functions exported from tnl. (A few + * more are currently hooked into dispatch directly by the module + * itself.) + */ /* * Mesa 3-D graphics library @@ -22,11 +30,10 @@ * BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - * - * Authors: - * Keith Whitwell */ +/* $Id: tnl.h,v 1.10.6.1 2003/04/05 16:42:15 jrfonseca Exp $ */ + #ifndef _TNL_H #define _TNL_H @@ -34,10 +41,6 @@ -/* These are the public-access functions exported from tnl. (A few - * more are currently hooked into dispatch directly by the module - * itself.) - */ extern GLboolean _tnl_CreateContext( GLcontext *ctx ); @@ -47,22 +50,31 @@ _tnl_DestroyContext( GLcontext *ctx ); extern void _tnl_InvalidateState( GLcontext *ctx, GLuint new_state ); -/* Functions to revive the tnl module after being unhooked from + +/** + * \name Functions to revive the tnl module after being unhooked from * dispatch and/or driver callbacks. */ +/*@{*/ -/* Restore just the ctx->Exec table: +/** + * Restore just the ctx->Exec table */ extern void _tnl_wakeup_exec( GLcontext *ctx ); -/* Restore both ctx->Exec and ctx->Save: +/** + * Restore both ctx->Exec and ctx->Save: */ extern void _tnl_wakeup_save_exec( GLcontext *ctx ); +/*@}*/ -/* Driver configuration options: + +/** + * Driver configuration options */ +/*@{*/ extern void _tnl_need_projected_coords( GLcontext *ctx, GLboolean flag ); @@ -74,5 +86,7 @@ _tnl_need_dlist_norm_lengths( GLcontext *ctx, GLboolean flag ); extern void _tnl_isolate_materials( GLcontext *ctx, GLboolean flag ); +/*@}*/ + #endif -- cgit v1.2.3