diff options
Diffstat (limited to 'src/mesa/main/mtypes.h')
-rw-r--r-- | src/mesa/main/mtypes.h | 1510 |
1 files changed, 918 insertions, 592 deletions
diff --git a/src/mesa/main/mtypes.h b/src/mesa/main/mtypes.h index c116228..bac711d 100644 --- a/src/mesa/main/mtypes.h +++ b/src/mesa/main/mtypes.h @@ -1,3 +1,10 @@ +/** + * \file mtypes.h + * Main Mesa data structures. + * + * Please try to mark derived values with a leading underscore ('_'). + */ + /* * Mesa 3-D graphics library * Version: 5.1 @@ -22,10 +29,7 @@ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ -/** - * \file mtypes.h - * \brief Main Mesa data structures. - */ + #ifndef TYPES_H #define TYPES_H @@ -43,11 +47,8 @@ #endif -/* Please try to mark derived values with a leading underscore ('_'). - */ - -/* - * Color channel data type: +/** + * Color channel data type. */ #if CHAN_BITS == 8 typedef GLubyte GLchan; @@ -70,7 +71,7 @@ /** - * Accumulation buffer data type: + * Accumulation buffer data type. */ #if ACCUM_BITS==8 typedef GLbyte GLaccum; @@ -84,7 +85,7 @@ /** - * Stencil buffer data type: + * Stencil buffer data type. */ #if STENCIL_BITS==8 typedef GLubyte GLstencil; @@ -98,13 +99,15 @@ /** - * Depth buffer data type: + * Depth buffer data type. + * + * \note Must be 32-bits! */ -typedef GLuint GLdepth; /* Must be 32-bits! */ +typedef GLuint GLdepth; /** - * Fixed point data type: + * Fixed point data type. */ typedef int GLfixed; /* @@ -138,38 +141,45 @@ 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. - */ -#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 + * quite a few places. + * + * New in Mesa 4.1. + */ +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) @@ -194,19 +204,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 */ +/** + * Data structure for color tables + */ struct gl_color_table { - GLenum Format; /* GL_ALPHA, GL_RGB, GL_RGB, etc */ + GLenum Format; /**< 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; /**< number of entries (rows) in table */ + GLvoid *Table; /**< either GLfloat * or GLchan * */ + GLboolean FloatTable; /**< are entries stored as floats? */ GLubyte RedSize; GLubyte GreenSize; GLubyte BlueSize; @@ -216,9 +229,10 @@ struct gl_color_table { }; -/* - * Bit flags used for updating material values. +/** + * \name Bit flags used for updating material values. */ +/*@{*/ #define FRONT_AMBIENT_BIT 0x1 #define BACK_AMBIENT_BIT 0x2 #define FRONT_DIFFUSE_BIT 0x4 @@ -241,15 +255,15 @@ struct gl_color_table { BACK_SHININESS_BIT | BACK_INDEXES_BIT) #define ALL_MATERIAL_BITS (FRONT_MATERIAL_BITS | BACK_MATERIAL_BITS) +/*@}*/ +#define EXP_TABLE_SIZE 512 /**< Specular exponent lookup table sizes */ +#define SHINE_TABLE_SIZE 256 /**< Material shininess lookup table sizes */ -/* - * Specular exponent and material shininess lookup table sizes: +/** + * Material shininess lookup table. */ -#define EXP_TABLE_SIZE 512 -#define SHINE_TABLE_SIZE 256 - struct gl_shine_tab { struct gl_shine_tab *next, *prev; GLfloat tab[SHINE_TABLE_SIZE+1]; @@ -258,50 +272,63 @@ struct gl_shine_tab { }; +/** + * Light. + */ struct gl_light { - struct gl_light *next; /* double linked list with sentinel */ + struct gl_light *next; /**< 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]; /**< 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 SpotExponent; - GLfloat SpotCutoff; /* in degress */ - GLfloat _CosCutoff; /* = MAX(0, cos(SpotCutoff)) */ + GLfloat SpotCutoff; /**< in degrees */ + GLfloat _CosCutoff; /**< = MAX(0, cos(SpotCutoff)) */ GLfloat ConstantAttenuation; GLfloat LinearAttenuation; GLfloat QuadraticAttenuation; - GLboolean Enabled; /* On/off flag */ + GLboolean Enabled; /**< On/off flag */ - /* Derived fields */ - GLuint _Flags; /* State */ + /** + * \name Derived fields + */ + /*@{*/ + GLuint _Flags; /**< 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]; /**< 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 _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]; /**< 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 */ + /*@}*/ }; +/** + * 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]; /**< 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 */ }; +/** + * Material. + */ struct gl_material { GLfloat Ambient[4]; @@ -309,25 +336,27 @@ 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; /**< for color index lighting */ + GLfloat DiffuseIndex; /**< for color index lighting */ + GLfloat SpecularIndex; /**< 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. +/** + * Accumulation buffer attributes. */ struct gl_accum_attrib { - GLfloat ClearColor[4]; /* Accumulation buffer clear color */ + GLfloat ClearColor[4]; /**< Accumulation buffer clear color */ }; -/* - * Used in _DrawDestMask and _ReadSrcMask below to identify color buffers. +/** + * \name Clipping planes bits + * + * Used in gl_colorbuffer_attrib::_DrawDestMask and + * gl_colorbuffer_attrib::_ReadSrcMask below to identify color buffers. */ +/*@{*/ #define FRONT_LEFT_BIT 0x1 #define FRONT_RIGHT_BIT 0x2 #define BACK_LEFT_BIT 0x4 @@ -336,72 +365,106 @@ struct gl_accum_attrib { #define AUX1_BIT 0x20 #define AUX2_BIT 0x40 #define AUX3_BIT 0x80 +/*@}*/ + +/** + * Color buffers attributes. + */ struct gl_colorbuffer_attrib { - GLuint ClearIndex; /* Index to use for glClear */ - GLclampf ClearColor[4]; /* Color to use for glClear */ - - GLuint IndexMask; /* Color index write mask */ - GLubyte ColorMask[4]; /* Each flag is 0xff or 0x0 */ - - GLenum DrawBuffer; /* Which buffer to draw into */ - GLubyte _DrawDestMask; /* bitwise-OR of FRONT/BACK_LEFT/RIGHT_BITs */ - - /* alpha testing */ - GLboolean AlphaEnabled; /* Alpha test enabled flag */ - GLenum AlphaFunc; /* 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 */ - 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 */ - - GLboolean DitherFlag; /* Dither enable flag */ + GLuint ClearIndex; /**< Index to use for glClear */ + GLclampf ClearColor[4]; /**< Color to use for glClear */ + + GLuint IndexMask; /**< Color index write mask */ + GLubyte ColorMask[4]; /**< Each flag is 0xff or 0x0 */ + + GLenum DrawBuffer; /**< Which buffer to draw into */ + GLubyte _DrawDestMask; /**< bitwise-OR of FRONT/BACK_LEFT/RIGHT_BITs */ + + /** + * \name alpha testing + */ + /*@{*/ + GLboolean AlphaEnabled; /**< Alpha test enabled flag */ + GLenum AlphaFunc; /**< Alpha test function */ + GLclampf AlphaRef; /**< Alpha reference value */ + /*@}*/ + + /** + * \name 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 */ + GLenum BlendEquation; /**< Blending equation */ + GLfloat BlendColor[4]; /**< Blending color */ + /*@}*/ + + /** + * \name Logic op + */ + /*@{*/ + GLenum LogicOp; /**< Logic operator */ + GLboolean IndexLogicOpEnabled; /**< Color index logic op enabled flag */ + GLboolean ColorLogicOpEnabled; /**< RGBA logic op enabled flag */ + /*@}*/ + + GLboolean DitherFlag; /**< Dither enable flag */ }; +/** + * 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]; /**< Current vertex attributes + * indexed by VERT_ATTRIB_* */ + GLuint Index; /**< Current color index */ + GLboolean EdgeFlag; /**< 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 data type + * 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_COORD_UNITS][4]; - GLboolean RasterPosValid; /* Raster pos valid flag */ + /*@{*/ + GLfloat RasterPos[4]; /**< Current raster position */ + GLfloat RasterDistance; /**< Current raster distance */ + GLfloat RasterColor[4]; /**< Current raster color */ + GLfloat RasterSecondaryColor[4]; /**< Current raster secondary color */ + GLuint RasterIndex; /**< Current raster index */ + GLfloat RasterTexCoords[MAX_TEXTURE_UNITS][4];/**< Current raster texcoords */ + GLboolean RasterPosValid; /**< Raster pos valid flag */ + /*@}*/ }; +/** + * 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 */ - GLboolean BoundsTest; /* GL_EXT_depth_bounds_test */ - GLfloat BoundsMin, BoundsMax;/* GL_EXT_depth_bounds_test */ + 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 */ + GLboolean BoundsTest; /**< GL_EXT_depth_bounds_test */ + GLfloat BoundsMin, BoundsMax;/**< GL_EXT_depth_bounds_test */ }; +/** + * glEnable()/glDisable() attributes. + */ struct gl_enable_attrib { GLboolean AlphaTest; GLboolean AutoNormal; @@ -476,8 +539,14 @@ struct gl_enable_attrib { }; +/** + * Eval attributes. + */ struct gl_eval_attrib { - /* Enable bits */ + /** + * \name Enable bits + */ + /*@{*/ GLboolean Map1Color4; GLboolean Map1Index; GLboolean Map1Normal; @@ -499,47 +568,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; + /*@}*/ }; +/** + * 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; /**< 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 ColorSumEnabled; - GLenum FogCoordinateSource; /* GL_EXT_fog_coord */ + GLenum FogCoordinateSource; /**< GL_EXT_fog_coord */ }; +/** + * 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; /**< GL_EXT_clip_volume_hint */ + GLenum TextureCompression; /**< GL_ARB_texture_compression */ + GLenum GenerateMipmap; /**< GL_SGIS_generate_mipmap */ }; +/** + * 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; /**< 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 */ GLubyte GreenSize; GLubyte BlueSize; GLubyte AlphaSize; @@ -550,7 +635,7 @@ struct gl_histogram_attrib { struct gl_minmax_attrib { GLenum Format; GLboolean Sink; - GLfloat Min[4], Max[4]; /* RGBA */ + GLfloat Min[4], Max[4]; /**< RGBA */ }; @@ -568,37 +653,51 @@ struct gl_convolution_attrib { #define LIGHT_POSITIONAL 0x4 #define LIGHT_NEED_VERTICES (LIGHT_POSITIONAL|LIGHT_LOCAL_VIEWER) +/** + * Lighting attributes. + */ 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]; /**< Array of lights */ + struct gl_lightmodel Model; /**< Lighting model */ - /* Must flush FLUSH_VERTICES before referencing: + /** + * Must flush FLUSH_VERTICES before referencing: */ - struct gl_material Material[2]; /* 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 */ + /*@{*/ + struct gl_material Material[2]; /**< 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 ColorMaterialEnabled; - struct gl_light EnabledList; /* List sentinel */ + struct gl_light EnabledList; /**< List sentinel */ - /* Derived for optimizations: */ - GLboolean _NeedVertices; /* Use fast shader? */ - GLuint _Flags; /* LIGHT_* flags, see above */ + /** + * Derived for optimizations: + */ + /*@{*/ + GLboolean _NeedEyeCoords; + GLboolean _NeedVertices; /**< Use fast shader? */ + GLuint _Flags; /**< LIGHT_* flags, see above */ GLfloat _BaseColor[2][3]; + /*@}*/ }; +/** + * Line attributes. + */ struct gl_line_attrib { - GLboolean SmoothFlag; /* GL_LINE_SMOOTH enabled? */ - GLboolean StippleFlag; /* GL_LINE_STIPPLE enabled? */ - GLushort StipplePattern; /* Stipple pattern */ - GLint StippleFactor; /* Stipple repeat factor */ - GLfloat Width; /* Line width */ - GLfloat _Width; /* Clamped Line width */ + GLboolean SmoothFlag; /**< GL_LINE_SMOOTH enabled? */ + GLboolean StippleFlag; /**< GL_LINE_STIPPLE enabled? */ + GLushort StipplePattern; /**< Stipple pattern */ + GLint StippleFactor; /**< Stipple repeat factor */ + GLfloat Width; /**< Line width */ + GLfloat _Width; /**< Clamped Line width */ }; @@ -632,11 +731,15 @@ struct gl_multisample_attrib { }; +/** + * 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; /**< source buffer for glReadPixels()/glCopyPixels() */ + GLubyte _ReadSrcMask; /**< 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; @@ -647,7 +750,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; /**< Size of each pixel map */ GLint MapItoIsize; GLint MapItoRsize; GLint MapItoGsize; @@ -657,13 +760,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]; /**< 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]; /**< converted to 8-bit color */ GLubyte MapItoG8[MAX_PIXEL_MAP_TABLE]; GLubyte MapItoB8[MAX_PIXEL_MAP_TABLE]; GLubyte MapItoA8[MAX_PIXEL_MAP_TABLE]; @@ -671,17 +774,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]; /**< RGBA */ + GLfloat PostColorMatrixBias[4]; /**< RGBA */ + /** GL_SGI_color_table */ GLfloat ColorTableScale[4]; GLfloat ColorTableBias[4]; GLboolean ColorTableEnabled; @@ -691,10 +794,10 @@ struct gl_pixel_attrib { GLfloat PCMCTscale[4]; GLfloat PCMCTbias[4]; GLboolean PostColorMatrixColorTableEnabled; - /* GL_SGI_texture_color_table */ + /** GL_SGI_texture_color_table */ GLfloat TextureColorTableScale[4]; GLfloat TextureColorTableBias[4]; - /* Convolution */ + /** Convolution */ GLboolean Convolution1DEnabled; GLboolean Convolution2DEnabled; GLboolean Separable2DEnabled; @@ -702,61 +805,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]; /**< RGBA */ + GLfloat PostConvolutionBias[4]; /**< RGBA */ }; +/** + * 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_COORD_UNITS]; /* GL_NV_point_sprite */ - GLenum SpriteRMode; /* GL_NV_point_sprite */ + 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 */ }; +/** + * 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; /**< 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 */ }; +/** + * 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; /**< Scissor test enabled? */ + GLint X, Y; /**< Lower left corner of box */ + GLsizei Width, Height; /**< Size of box */ }; +/** + * 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; /**< 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 */ }; @@ -819,147 +934,187 @@ 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]. +/** + * Texel fetch function prototype. + * + * \param texImage texture image. + * \param col texel column. + * \param row texel row. + * \param img texel level. + * \param texelOut output texel. If \p texImage is color-index, \p texelOut + * returns <tt>GLchan[1]</tt>. If \p texImage is depth, \p texelOut returns + * <tt>GLfloat[1]</tt>. Otherwise, \p texelOut returns <tt>GLchan[4]</tt>. */ typedef void (*FetchTexelFunc)( const struct gl_texture_image *texImage, GLint col, GLint row, GLint img, GLvoid *texelOut ); -/* Texture format record */ +/** + * Texture format record + */ struct gl_texture_format { - GLint MesaFormat; /* One of the MESA_FORMAT_* values */ + GLint MesaFormat; /**< 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; /**< 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; /**< Bits per texel component */ + GLubyte GreenBits; /**< These are just rough approximations for */ + GLubyte BlueBits; /**< compressed texture formats. */ GLubyte AlphaBits; GLubyte LuminanceBits; GLubyte IntensityBits; GLubyte IndexBits; GLubyte DepthBits; - GLint TexelBytes; /* Bytes per texel (0 for compressed formats */ + GLint TexelBytes; /**< Bytes per texel (0 for compressed formats */ - FetchTexelFunc FetchTexel1D; /* Texel fetch function pointers */ + /** + * \name Texel fetch function pointers + */ + /*@{*/ + FetchTexelFunc FetchTexel1D; FetchTexelFunc FetchTexel2D; FetchTexelFunc FetchTexel3D; + /*@}*/ }; -/* Texture image record */ +/** + * 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; /**< 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? */ - GLboolean _IsPowerOfTwo; /* Are all dimensions powers of two? */ + 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? */ + GLboolean _IsPowerOfTwo; /**< Are all dimensions powers of two? */ const struct gl_texture_format *TexFormat; - FetchTexelFunc FetchTexel; /* Texel fetch function pointer */ + FetchTexelFunc FetchTexel; /**< Texel fetch function pointer */ - GLboolean IsCompressed; /* GL_ARB_texture_compression */ - GLuint CompressedSize; /* GL_ARB_texture_compression */ + GLboolean IsCompressed; /**< GL_ARB_texture_compression */ + GLuint CompressedSize; /**< GL_ARB_texture_compression */ - /* For device driver: */ - void *DriverData; /* Arbitrary device driver data */ + /** + * \name For device driver: + */ + /*@{*/ + void *DriverData; /**< Arbitrary device driver data */ + /*@}*/ }; -/* Texture object record */ +/** + * 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; /**< 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 */ + /** \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; /**< 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 */ 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 */ - GLboolean _IsPowerOfTwo; /* Are all image dimensions powers of two? */ + 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 */ + GLboolean _IsPowerOfTwo; /**< Are all image dimensions powers of two? */ 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 */ + /** 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; /**< Is texture object complete? */ + struct gl_texture_object *Next; /**< Next in linked list */ - /* For device driver: */ - void *DriverData; /* Arbitrary device driver data */ + /** + * \name For device driver + */ + /*@{*/ + void *DriverData; /**< Arbitrary device driver data */ + /*@}*/ }; -/* Texture unit record */ +/** + * 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; /**< bitmask of TEXTURE_*_BIT flags */ + GLuint _ReallyEnabled; /**< 0 or exactly one of TEXTURE_*_BIT flags */ - GLenum EnvMode; /* GL_MODULATE, GL_DECAL, GL_BLEND, etc. */ + GLenum EnvMode; /**< 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; /**< 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; /**< bitwise or of GenBit[STRQ] */ GLfloat ObjectPlaneS[4]; GLfloat ObjectPlaneT[4]; GLfloat ObjectPlaneR[4]; @@ -968,27 +1123,31 @@ struct gl_texture_unit { GLfloat EyePlaneT[4]; GLfloat EyePlaneR[4]; GLfloat EyePlaneQ[4]; - GLfloat LodBias; /* 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 */ + GLfloat LodBias; /**< for biasing mipmap levels */ + + /** + * \name 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 */ + /*@}*/ 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; /**< GL_ARB_texture_cube_map */ + struct gl_texture_object *CurrentRect; /**< GL_NV_texture_rectangle */ - struct gl_texture_object *_Current; /* Points to really enabled tex obj */ + struct gl_texture_object *_Current; /**< Points to really enabled tex obj */ - struct gl_texture_object Saved1D; /* only used by glPush/PopAttrib */ + struct gl_texture_object Saved1D; /**< only used by glPush/PopAttrib */ struct gl_texture_object Saved2D; struct gl_texture_object Saved3D; struct gl_texture_object SavedCubeMap; @@ -1001,16 +1160,21 @@ struct gl_texture_unit { }; -/* The texture attribute group */ +/** + * Texture attributes + */ struct gl_texture_attrib { - /* multitexture */ - GLuint CurrentUnit; /* Active texture unit */ - - GLuint _EnabledUnits; /* one bit set for each really-enabled unit */ - GLuint _EnabledCoordUnits; /* one bit per enabled coordinate unit */ - GLuint _GenFlags; /* for texgen */ - GLuint _TexGenEnabled; + /** + * name multitexture + */ + /**@{*/ + GLuint CurrentUnit; /**< Active texture unit */ + GLuint _EnabledUnits; /**< one bit set for each really-enabled unit */ + GLuint _EnabledCoordUnits; /**< one bit per enabled coordinate unit */ + GLuint _GenFlags; /**< for texgen */ + GLuint _TexGenEnabled; GLuint _TexMatEnabled; + /**@}*/ struct gl_texture_unit Unit[MAX_TEXTURE_UNITS]; @@ -1020,32 +1184,40 @@ struct gl_texture_attrib { struct gl_texture_object *ProxyCubeMap; struct gl_texture_object *ProxyRect; - /* GL_EXT_shared_texture_palette */ + /** GL_EXT_shared_texture_palette */ GLboolean SharedPalette; struct gl_color_table Palette; }; +/** + * Transformation attributes. + */ struct gl_transform_attrib { - GLenum MatrixMode; /* 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 */ + GLenum MatrixMode; /**< Matrix mode */ + GLfloat EyeUserPlane[MAX_CLIP_PLANES][4]; /**< User clip planes */ + 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 */ }; +/** + * 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; /**< position */ + GLsizei Width, Height; /**< size */ + GLfloat Near, Far; /**< Depth buffer range */ + GLmatrix _WindowMap; /**< Mapping transformation as a matrix. */ }; -/* For the attribute stack: */ +/** + * Node for the attribute stack + */ struct gl_attrib_node { GLbitfield kind; void *data; @@ -1053,7 +1225,7 @@ struct gl_attrib_node { }; -/* +/** * Client pixel packing/unpacking attributes */ struct gl_pixelstore_attrib { @@ -1061,35 +1233,38 @@ struct gl_pixelstore_attrib { GLint RowLength; GLint SkipPixels; GLint SkipRows; - GLint ImageHeight; /* for GL_EXT_texture3D */ - GLint SkipImages; /* for GL_EXT_texture3D */ + GLint ImageHeight; /**< for GL_EXT_texture3D */ + GLint SkipImages; /**< for GL_EXT_texture3D */ GLboolean SwapBytes; GLboolean LsbFirst; - GLboolean ClientStorage; /* GL_APPLE_client_storage */ - GLboolean Invert; /* GL_MESA_pack_invert */ + GLboolean ClientStorage; /**< GL_APPLE_client_storage */ + GLboolean Invert; /**< GL_MESA_pack_invert */ }; -#define CA_CLIENT_DATA 0x1 /* Data not alloced by mesa */ +#define CA_CLIENT_DATA 0x1 /**< Data not allocated by mesa */ -/* +/** * 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; /**< user-specified stride */ + GLsizei StrideB; /**< actual stride in bytes */ void *Ptr; GLuint Flags; - GLuint Enabled; /* one of the _NEW_ARRAY_ bits */ - GLboolean Normalized; /* GL_ARB_vertex_program */ + GLuint Enabled; /**< one of the _NEW_ARRAY_ bits */ + GLboolean Normalized; /**< GL_ARB_vertex_program */ }; +/** + * Array attributes. + */ struct gl_array_attrib { - struct gl_client_array Vertex; /* client data descriptors */ + struct gl_client_array Vertex; /**< client data descriptors */ struct gl_client_array Normal; struct gl_client_array Color; struct gl_client_array SecondaryColor; @@ -1097,16 +1272,16 @@ struct gl_array_attrib { struct gl_client_array Index; struct gl_client_array TexCoord[MAX_TEXTURE_COORD_UNITS]; struct gl_client_array EdgeFlag; - /* GL_NV_vertex_program */ - struct gl_client_array VertexAttrib[VERT_ATTRIB_MAX]; + + struct gl_client_array VertexAttrib[VERT_ATTRIB_MAX]; /**< GL_NV_vertex_program */ GLint TexCoordInterleaveFactor; - GLint ActiveTexture; /* Client Active Texture */ + GLint ActiveTexture; /**< Client Active Texture */ GLuint LockFirst; GLuint LockCount; - GLuint _Enabled; /* _NEW_ARRAY_* - bit set if array enabled */ - GLuint NewState; /* _NEW_ARRAY_* */ + GLuint _Enabled; /**< _NEW_ARRAY_* - bit set if array enabled */ + GLuint NewState; /**< _NEW_ARRAY_* */ /* GL_ARB_vertex_buffer_object */ GLuint ArrayBufferBinding; @@ -1133,45 +1308,52 @@ struct gl_feedback { }; +/** + * 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 NameStackDepth; - GLuint NameStack[MAX_NAME_STACK_DEPTH]; - GLboolean HitFlag; - GLfloat HitMinZ, HitMaxZ; + GLuint *Buffer; /**< selection buffer */ + GLuint BufferSize; /**< size of the selection buffer */ + GLuint BufferCount; /**< number of values in the selection buffer */ + GLuint Hits; /**< number of records in the selection buffer */ + GLuint NameStackDepth; /**< name stack depth */ + GLuint NameStack[MAX_NAME_STACK_DEPTH]; /**< name stack */ + GLboolean HitFlag; /**< hit flag */ + GLfloat HitMinZ; /**< minimum hit depth */ + GLfloat HitMaxZ; /**< maximum hit depth */ }; -/* +/** * 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; /**< Number of control points */ + GLfloat u1, u2, du; /**< u1, u2, 1.0/(u2-u1) */ + GLfloat *Points; /**< Points to contiguous control points */ }; -/* +/** * 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; /**< Number of control points in U dimension */ + GLuint Vorder; /**< Number of control points in V dimension */ GLfloat u1, u2, du; GLfloat v1, v2, dv; - GLfloat *Points; /* Points to contiguous control points */ + GLfloat *Points; /**< Points to contiguous control points */ }; -/* - * All evalutator control points +/** + * All evaluator 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; @@ -1181,9 +1363,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]; /**< 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; @@ -1193,12 +1379,20 @@ 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]; /**< GL_NV_vertex_program */ + /*@}*/ }; +/** + * \name NV_vertex_program runtime state + */ +/*@{*/ + -/* NV_vertex_program runtime state */ +/** + * Machine state (i.e. the register file) + */ struct vp_machine { GLfloat Registers[MAX_NV_VERTEX_PROGRAM_TEMPS @@ -1209,7 +1403,9 @@ struct vp_machine }; -/* NV_fragment_program runtime state */ +/** + * NV_fragment_program runtime state + */ struct fp_machine { GLfloat Registers[MAX_NV_FRAGMENT_PROGRAM_TEMPS @@ -1225,7 +1421,9 @@ struct fp_machine struct vp_instruction; struct fp_instruction; -/* Program parameters */ +/** + * Program parameters + */ struct program_parameter { const char *Name; @@ -1234,7 +1432,9 @@ struct program_parameter }; -/* Base class for any kind of program object */ +/** + * Base class for any kind of program object + */ struct program { GLuint Id; @@ -1252,7 +1452,7 @@ struct program }; -/* Vertex program object */ +/** Vertex program object */ struct vertex_program { struct program Base; /* base class */ @@ -1263,23 +1463,23 @@ struct vertex_program }; -/* Fragment program object */ +/** Fragment program object */ struct fragment_program { - struct program Base; /* base class */ - struct fp_instruction *Instructions; /* Compiled instructions */ - GLuint InputsRead; /* Bitmask of which input regs are read */ - GLuint OutputsWritten; /* Bitmask of which output regs are written to */ - GLuint TexturesUsed[MAX_TEXTURE_IMAGE_UNITS]; /* TEXTURE_x_INDEX bitmask */ - GLuint NumAluInstructions; /* GL_ARB_fragment_program */ + struct program Base; /**< base class */ + struct fp_instruction *Instructions; /**< Compiled instructions */ + GLuint InputsRead; /**< Bitmask of which input regs are read */ + GLuint OutputsWritten; /**< Bitmask of which output regs are written to */ + GLuint TexturesUsed[MAX_TEXTURE_IMAGE_UNITS]; /**< TEXTURE_x_INDEX bitmask */ + GLuint NumAluInstructions; /**< GL_ARB_fragment_program */ GLuint NumTexInstructions; GLuint NumTexIndirections; - struct program_parameter *Parameters; /* array [NumParameters] */ + struct program_parameter *Parameters; /**< array [NumParameters] */ GLuint NumParameters; }; -/* +/** * State common to vertex and fragment programs. */ struct program_state { @@ -1288,16 +1488,16 @@ struct program_state { }; -/* - * State for GL_ARB/NV_vertex_program +/** + * 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 */ - struct vertex_program *Current; /* ptr to currently bound program */ - struct vp_machine Machine; /* machine state */ + GLboolean Enabled; /**< GL_VERTEX_PROGRAM_NV */ + GLboolean PointSizeEnabled; /**< GL_VERTEX_PROGRAM_POINT_SIZE_NV */ + GLboolean TwoSideEnabled; /**< GL_VERTEX_PROGRAM_TWO_SIDE_NV */ + struct vertex_program *Current; /**< ptr to currently bound program */ + struct vp_machine Machine; /**< machine state */ GLenum TrackMatrix[MAX_NV_VERTEX_PROGRAM_PARAMS / 4]; GLenum TrackMatrixTransform[MAX_NV_VERTEX_PROGRAM_PARAMS / 4]; @@ -1314,6 +1514,7 @@ struct fragment_program_state struct fp_machine Machine; /* machine state */ }; +/*@}*/ /* * State for GL_ARB_occlusion_query @@ -1327,24 +1528,31 @@ struct occlusion_state }; -/* +/** * 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; /**< 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 */ - /* 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 */ + /** + * \name GL_NV_vertex/_program + */ + /*@{*/ struct _mesa_HashTable *Programs; #if FEATURE_ARB_vertex_program struct program *DefaultVertexProgram; @@ -1352,56 +1560,75 @@ struct gl_shared_state { #if FEATURE_ARB_fragment_program struct program *DefaultFragmentProgram; #endif + /*@}*/ - void *DriverData; /* Device driver shared state */ + void *DriverData; /**< Device driver shared state */ }; -/* +/** + * 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; /**< The corresponding visual */ - GLuint Width, Height; /* size of frame buffer in pixels */ + GLuint Width, Height; /**< 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*/ - - /* Software stencil buffer */ - GLstencil *Stencil; /* array [Width*Height] of GLstencil values */ - - /* Software accumulation buffer */ - GLaccum *Accum; /* 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 */ - - /* Drawing bounds: intersection of window size and scissor box */ - GLint _Xmin, _Ymin; /* inclusive */ - GLint _Xmax, _Ymax; /* exclusive */ + /** \name Software depth (aka Z) buffer */ + /*@{*/ + GLvoid *DepthBuffer; /**< array [Width*Height] of GLushort or GLuint*/ + /*@}*/ + + /** \name Software stencil buffer */ + /*@{*/ + GLstencil *Stencil; /**< array [Width*Height] of GLstencil values */ + /*@}*/ + + /** \name Software accumulation buffer */ + /*@{*/ + GLaccum *Accum; /**< array [4*Width*Height] of GLaccum values */ + /*@}*/ + + /** \name 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 Drawing bounds + * + * Intersection of window size and scissor box + */ + /*@{*/ + GLint _Xmin; /**< inclusive */ + GLint _Ymin; /**< inclusive */ + GLint _Xmax; /**< exclusive */ + GLint _Ymax; /**< exclusive */ + /*@}*/ }; -/* - * Constants which may be overriden by device driver during context creation +/** + * Constants which may be overridden by device driver during context creation * but are never changed after that. */ struct gl_constants { - GLint MaxTextureLevels; - GLint Max3DTextureLevels; - GLint MaxCubeTextureLevels; /* GL_ARB_texture_cube_map */ + GLint MaxTextureLevels; /**< Maximum number of allowed mipmap levels. */ + GLint Max3DTextureLevels; /**< Maximum number of allowed mipmap levels for 3D texture targets. */ + GLint MaxCubeTextureLevels; /**< Maximum number of allowed mipmap levels for GL_ARB_texture_cube_map */ GLint MaxTextureRectSize; /* GL_NV_texture_rectangle */ GLuint MaxTextureCoordUnits; GLuint MaxTextureImageUnits; @@ -1447,13 +1674,16 @@ struct gl_constants { }; -/* +/** * List of extensions. */ struct gl_extensions { - /* 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 dummy; /* don't remove this! */ GLboolean ARB_depth_texture; GLboolean ARB_fragment_program; @@ -1525,27 +1755,31 @@ struct gl_extensions { GLboolean SGIX_shadow_ambient; /* or GL_ARB_shadow_ambient */ GLboolean TDFX_texture_compression_FXT1; GLboolean APPLE_client_storage; + /*@}*/ /* The extension string */ const GLubyte *String; }; -/* +/** * 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; /**< 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 */ }; -/* - * Bits for image transfer operations (ctx->ImageTransferState). +/** + * \name Bits for image transfer operations + * + * \sa __GLcontextRec::ImageTransferState. */ +/*@{*/ #define IMAGE_SCALE_BIAS_BIT 0x1 #define IMAGE_SHIFT_OFFSET_BIT 0x2 #define IMAGE_MAP_COLOR_BIT 0x4 @@ -1558,58 +1792,66 @@ 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 | \ IMAGE_POST_COLOR_MATRIX_COLOR_TABLE_BIT |\ IMAGE_HISTOGRAM_BIT | \ IMAGE_MIN_MAX_BIT) +/*@}*/ -/* - * 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 */ +/** + * \name Bits to indicate what state has changed. + * + * 6 unused flags. + */ +/*@{*/ +#define _NEW_MODELVIEW 0x1 /**< __GLcontextRec::ModelView */ +#define _NEW_PROJECTION 0x2 /**< __GLcontextRec::Projection */ +#define _NEW_TEXTURE_MATRIX 0x4 /**< __GLcontextRec::TextureMatrix */ +#define _NEW_COLOR_MATRIX 0x8 /**< __GLcontextRec::ColorMatrix */ +#define _NEW_ACCUM 0x10 /**< __GLcontextRec::Accum */ +#define _NEW_COLOR 0x20 /**< __GLcontextRec::Color */ +#define _NEW_DEPTH 0x40 /**< __GLcontextRec::Depth */ +#define _NEW_EVAL 0x80 /**< __GLcontextRec::Eval, __GLcontextRec::EvalMap */ +#define _NEW_FOG 0x100 /**< __GLcontextRec::Fog */ +#define _NEW_HINT 0x200 /**< __GLcontextRec::Hint */ +#define _NEW_LIGHT 0x400 /**< __GLcontextRec::Light */ +#define _NEW_LINE 0x800 /**< __GLcontextRec::Line */ +#define _NEW_PIXEL 0x1000 /**< __GLcontextRec::Pixel */ +#define _NEW_POINT 0x2000 /**< __GLcontextRec::Point */ +#define _NEW_POLYGON 0x4000 /**< __GLcontextRec::Polygon */ +#define _NEW_POLYGONSTIPPLE 0x8000 /**< __GLcontextRec::PolygonStipple */ +#define _NEW_SCISSOR 0x10000 /**< __GLcontextRec::Scissor */ +#define _NEW_STENCIL 0x20000 /**< __GLcontextRec::Stencil */ +#define _NEW_TEXTURE 0x40000 /**< __GLcontextRec::Texture */ +#define _NEW_TRANSFORM 0x80000 /**< __GLcontextRec::Transform */ +#define _NEW_VIEWPORT 0x100000 /**< __GLcontextRec::Viewport */ +#define _NEW_PACKUNPACK 0x200000 /**< __GLcontextRec::Pack, __GLcontextRec::Unpack */ +#define _NEW_ARRAY 0x400000 /**< __GLcontextRec::Array */ +#define _NEW_RENDERMODE 0x800000 /**< __GLcontextRec::RenderMode, __GLcontextRec::Feedback, __GLcontextRec::Select */ +#define _NEW_BUFFERS 0x1000000 /**< __GLcontextRec::Visual, __GLcontextRec::DrawBuffer, */ +#define _NEW_MULTISAMPLE 0x2000000 /**< __GLcontextRec::Multisample */ +#define _NEW_TRACK_MATRIX 0x4000000 /**< __GLcontextRec::VertexProgram */ +#define _NEW_PROGRAM 0x8000000 /**< __GLcontextRec::VertexProgram */ #define _NEW_ALL ~0 +/*@}*/ - -/* Bits to track array state changes (also used to summarize array enabled) +/** + * \name Bits to track array state changes + * + * Also used to summarize array enabled. */ +/*@{*/ #define _NEW_ARRAY_VERTEX VERT_BIT_POS #define _NEW_ARRAY_WEIGHT VERT_BIT_WEIGHT #define _NEW_ARRAY_NORMAL VERT_BIT_NORMAL @@ -1632,11 +1874,15 @@ struct matrix_stack #define _NEW_ARRAY_TEXCOORD(i) (_NEW_ARRAY_TEXCOORD_0 << (i)) #define _NEW_ARRAY_ATTRIB(i) (_NEW_ARRAY_ATTRIB_0 << (i)) +/*@}*/ -/* A bunch of flags that we think might be useful to drivers. - * Set in the ctx->_TriangleCaps bitfield. +/** + * \name A bunch of flags that we think might be useful to drivers. + * + * Set in the __GLcontextRec::_TriangleCaps bitfield. */ +/*@{*/ #define DD_FLATSHADE 0x1 #define DD_SEPARATE_SPECULAR 0x2 #define DD_TRI_CULL_FRONT_BACK 0x4 /* special case on some hw */ @@ -1651,10 +1897,13 @@ struct matrix_stack #define DD_POINT_SMOOTH 0x800 #define DD_POINT_SIZE 0x1000 #define DD_POINT_ATTEN 0x2000 +/*@}*/ -/* Define the state changes under which each of these bits might change +/** + * \name Define the state changes under which each of these bits might change */ +/*@{*/ #define _DD_NEW_FLATSHADE _NEW_LIGHT #define _DD_NEW_SEPARATE_SPECULAR (_NEW_LIGHT | _NEW_FOG) #define _DD_NEW_TRI_CULL_FRONT_BACK _NEW_POLYGON @@ -1669,6 +1918,8 @@ struct matrix_stack #define _DD_NEW_POINT_SMOOTH _NEW_POINT #define _DD_NEW_POINT_SIZE _NEW_POINT #define _DD_NEW_POINT_ATTEN _NEW_POINT +/*@}*/ + #define _MESA_NEW_NEED_EYE_COORDS (_NEW_LIGHT | \ _NEW_TEXTURE | \ @@ -1681,20 +1932,10 @@ struct matrix_stack #define _IMAGE_NEW_TRANSFER_STATE (_NEW_PIXEL | _NEW_COLOR_MATRIX) -/* Bits for ctx->_NeedNormals */ -#define NEED_NORMALS_TEXGEN 0x1 -#define NEED_NORMALS_LIGHT 0x2 - -/* Bits for ctx->_NeedEyeCoords */ -#define NEED_EYE_TEXGEN 0x1 -#define NEED_EYE_LIGHT 0x2 -#define NEED_EYE_LIGHT_MODELVIEW 0x4 -#define NEED_EYE_POINT_ATTEN 0x8 -#define NEED_EYE_DRIVER 0x10 /* - * Forward declaration of display list datatypes: + * Forward declaration of display list data types: */ union node; typedef union node Node; @@ -1704,25 +1945,31 @@ typedef union node Node; #include "dd.h" -/* - * Core Mesa's support for tnl modules: - */ #define NUM_VERTEX_FORMAT_ENTRIES (sizeof(GLvertexformat) / sizeof(void *)) +/** + * Core Mesa's support for tnl modules: + */ struct gl_tnl_module { - /* Vertex format to be lazily swapped into current dispatch. + /** + * 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; + /*@}*/ }; /** + * 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 @@ -1730,20 +1977,25 @@ 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 */ + /** 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; /**< Display list save functions */ + struct _glapi_table *Exec; /**< Execute functions */ struct _glapi_table *CurrentDispatch; /**< == Save or Exec !! */ + /*@}*/ GLboolean ExecPrefersFloat; /**< What preference for color conversion? */ GLboolean SavePrefersFloat; @@ -1760,127 +2012,153 @@ struct __GLcontextRec { void *DriverCtx; /**< Points to device driver context/state */ void *DriverMgrCtx; /**< Points to device driver manager (optional)*/ - /* Core/Driver constants */ + /** 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_COORD_UNITS]; struct matrix_stack ProgramMatrixStack[MAX_PROGRAM_MATRICES]; - struct matrix_stack *CurrentStack; /* Points to one of the above stacks */ + struct matrix_stack *CurrentStack; /**< Points to one of the above stacks */ + /*@}*/ - /* Combined modelview and projection matrix */ + /** 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 */ - - /* Extensions */ + /** \name 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 */ + /*@}*/ + + /** 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 */ - struct gl_accum_attrib Accum; - struct gl_colorbuffer_attrib Color; - struct gl_current_attrib Current; - struct gl_depthbuffer_attrib Depth; - struct gl_eval_attrib Eval; - struct gl_fog_attrib Fog; - struct gl_hint_attrib Hint; - struct gl_light_attrib Light; - struct gl_line_attrib Line; - struct gl_list_attrib List; + /** \name Renderer attribute groups + * + * 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 Accum; /**< Accumulation buffer attributes */ + struct gl_colorbuffer_attrib Color; /**< Color buffers attributes */ + struct gl_current_attrib Current; /**< Current attributes */ + struct gl_depthbuffer_attrib Depth; /**< Depth buffer attributes */ + struct gl_eval_attrib Eval; /**< Eval attributes */ + struct gl_fog_attrib Fog; /**< Fog attributes */ + struct gl_hint_attrib Hint; /**< Hint attributes */ + struct gl_light_attrib Light; /**< Light attributes */ + struct gl_line_attrib Line; /**< Line attributes */ + struct gl_list_attrib List; /**< List attributes */ struct gl_multisample_attrib Multisample; - struct gl_pixel_attrib Pixel; - struct gl_point_attrib Point; - struct gl_polygon_attrib Polygon; - GLuint PolygonStipple[32]; - struct gl_scissor_attrib Scissor; - struct gl_stencil_attrib Stencil; - struct gl_texture_attrib Texture; - struct gl_transform_attrib Transform; - struct gl_viewport_attrib Viewport; - - /* Other attribute groups */ + struct gl_pixel_attrib Pixel; /**< Pixel attributes */ + struct gl_point_attrib Point; /**< Point attributes */ + struct gl_polygon_attrib Polygon; /**< Polygon attributes */ + GLuint PolygonStipple[32]; /**< Polygon stipple */ + struct gl_scissor_attrib Scissor; /**< Scissor attributes */ + struct gl_stencil_attrib Stencil; /**< Stencil buffer attributes */ + struct gl_texture_attrib Texture; /**< Texture attributes */ + struct gl_transform_attrib Transform; /**< Transformation attributes */ + struct gl_viewport_attrib Viewport; /**< Viewport attributes */ + /*@}*/ + + /** \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; /**< Vertex arrays */ + struct gl_pixelstore_attrib Pack; /**< Pixel packing */ + struct gl_pixelstore_attrib Unpack; /**< Pixel unpacking */ - struct gl_evaluators EvalMap; /* All evaluators */ - struct gl_feedback Feedback; /* Feedback */ - struct gl_selection Select; /* Selection */ + struct gl_evaluators EvalMap; /**< All evaluators */ + struct gl_feedback Feedback; /**< Feedback */ + struct gl_selection Select; /**< Selection */ - struct gl_color_table ColorTable; /* Pre-convolution */ - struct gl_color_table ProxyColorTable; /* Pre-convolution */ + struct gl_color_table ColorTable; /**< Pre-convolution */ + struct gl_color_table ProxyColorTable; /**< Pre-convolution */ struct gl_color_table PostConvolutionColorTable; struct gl_color_table ProxyPostConvolutionColorTable; struct gl_color_table PostColorMatrixColorTable; struct gl_color_table ProxyPostColorMatrixColorTable; - struct program_state Program; /* for vertex or fragment progs */ - struct vertex_program_state VertexProgram; /* GL_NV_vertex_program */ - struct fragment_program_state FragmentProgram; /* GL_NV_fragment_program */ + struct program_state Program; /**< for vertex or fragment progs */ + struct vertex_program_state VertexProgram; /**< GL_NV_vertex_program */ + struct fragment_program_state FragmentProgram; /**< GL_NV_fragment_program */ - struct occlusion_state Occlusion; /* GL_ARB_occlusion_query */ + struct occlusion_state Occlusion; /**< GL_ARB_occlusion_query */ - GLenum ErrorValue; /* Last error code */ - GLenum RenderMode; /* either GL_RENDER, GL_SELECT, GL_FEEDBACK */ - GLuint NewState; /* bitwise-or of _NEW_* flags */ + GLenum ErrorValue; /**< Last error code */ + GLenum RenderMode; /**< either GL_RENDER, GL_SELECT, GL_FEEDBACK */ + GLuint NewState; /**< 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; /**< bitwise-or of DD_* flags */ + GLuint _ImageTransferState;/**< bitwise-or of IMAGE_*_BIT flags */ GLfloat _EyeZDir[3]; GLfloat _ModelViewInvScale; GLuint _NeedEyeCoords; - GLuint _NeedNormals; /* Are vertex normal vectors needed? */ + GLuint _ForceEyeCoords; + GLboolean _RotateMode; - 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]; /**< Active shine tables */ + struct gl_shine_tab *_ShineTabList; /**< MRU list of inactive shine tables */ + /**@}*/ - struct gl_list_extensions listext; /* driver dlist extensions */ + struct gl_list_extensions listext; /**< 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. */ + 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. */ - /* Z buffer stuff */ + /** \name Z buffer stuff */ + /*@{*/ GLuint DepthMax; /**< Max depth buffer value */ GLfloat DepthMaxF; /**< Float max depth buffer value */ GLfloat MRD; /**< minimum resolvable difference in Z values */ + /*@}*/ /** 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 */ GLboolean NoDither; @@ -1895,22 +2173,26 @@ struct __GLcontextRec { void *TraceCtx; #endif - /* Core tnl module support */ + /** 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 */ +/** The string names for GL_POINT, GL_LINE_LOOP, etc */ extern const char *_mesa_prim_name[GL_POLYGON+4]; @@ -1950,7 +2232,17 @@ enum _debug { #define Elements(x) sizeof(x)/sizeof(*(x)) -/* Eventually let the driver specify what statechanges require a flush: +/** + * Flush vertices. + * + * \param ctx GL context. + * \param newstate new state. + * + * Checks if dd_function_table::NeedFlush is marked to flush stored vertices, + * and calls dd_function_table::FlushVertices if so. Marks + * __GLcontextRec::NewState with \p newstate. + * + * \todo Eventually let the driver specify what state changes require a flush: */ #define FLUSH_VERTICES(ctx, newstate) \ do { \ @@ -1961,6 +2253,16 @@ do { \ ctx->NewState |= newstate; \ } while (0) +/** + * Flush current state. + * + * \param ctx GL context. + * \param newstate new state. + * + * Checks if dd_function_table::NeedFlush is marked to flush current state, + * and calls dd_function_table::FlushVertices if so. Marks + * __GLcontextRec::NewState with \p newstate. + */ #define FLUSH_CURRENT(ctx, newstate) \ do { \ if (MESA_VERBOSE & VERBOSE_STATE) \ @@ -1970,6 +2272,13 @@ do { \ ctx->NewState |= newstate; \ } while (0) +/** + * Macro to assert that the API call was made outside the + * glBegin()/glEnd() pair, with return value. + * + * \param ctx GL context. + * \param retval value to return value in case the assertion fails. + */ #define ASSERT_OUTSIDE_BEGIN_END_WITH_RETVAL(ctx, retval) \ do { \ if (ctx->Driver.CurrentExecPrimitive != PRIM_OUTSIDE_BEGIN_END) { \ @@ -1978,6 +2287,12 @@ do { \ } \ } while (0) +/** + * Macro to assert that the API call was made outside the + * glBegin()/glEnd() pair. + * + * \param ctx GL context. + */ #define ASSERT_OUTSIDE_BEGIN_END(ctx) \ do { \ if (ctx->Driver.CurrentExecPrimitive != PRIM_OUTSIDE_BEGIN_END) { \ @@ -1986,12 +2301,25 @@ do { \ } \ } while (0) +/** + * Macro to assert that the API call was made outside the + * glBegin()/glEnd() pair and flush the vertices. + * + * \param ctx GL context. + */ #define ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH(ctx) \ do { \ ASSERT_OUTSIDE_BEGIN_END(ctx); \ FLUSH_VERTICES(ctx, 0); \ } while (0) +/** + * Macro to assert that the API call was made outside the + * glBegin()/glEnd() pair and flush the vertices, with return value. + * + * \param ctx GL context. + * \param retval value to return value in case the assertion fails. + */ #define ASSERT_OUTSIDE_BEGIN_END_AND_FLUSH_WITH_RETVAL(ctx, retval) \ do { \ ASSERT_OUTSIDE_BEGIN_END_WITH_RETVAL(ctx, retval); \ @@ -1999,6 +2327,4 @@ do { \ } while (0) - - #endif /* TYPES_H */ |