diff options
Diffstat (limited to 'src/mesa/main/dd.h')
| -rw-r--r-- | src/mesa/main/dd.h | 732 |
1 files changed, 492 insertions, 240 deletions
diff --git a/src/mesa/main/dd.h b/src/mesa/main/dd.h index 88ffb8fb473..1829bbc6524 100644 --- a/src/mesa/main/dd.h +++ b/src/mesa/main/dd.h @@ -1,3 +1,7 @@ +/** + * \file dd.h + * Device driver interfaces. + */ /* * Mesa 3-D graphics library @@ -24,7 +28,6 @@ */ - #ifndef DD_INCLUDED #define DD_INCLUDED @@ -46,135 +49,183 @@ struct gl_pixelstore_attrib; #define DD_STENCIL_BIT GL_STENCIL_BUFFER_BIT /* 0x00000400 */ -/* - * Device Driver function table. +/** + * Device driver function table. */ struct dd_function_table { - const GLubyte * (*GetString)( GLcontext *ctx, GLenum name ); - /* Return a string as needed by glGetString(). - * Only the GL_RENDERER token must be implemented. Otherwise, - * NULL can be returned. + /** + * Return a string as needed by glGetString(). + * + * Only the GL_RENDERER token must be implemented. Otherwise, NULL can be + * returned. */ + const GLubyte * (*GetString)( GLcontext *ctx, GLenum name ); - void (*UpdateState)( GLcontext *ctx, GLuint new_state ); - /* - * UpdateState() is called to notify the driver after Mesa has made - * some internal state changes. This is in addition to any - * statechange callbacks Mesa may already have made. + /** + * Notify the driver after Mesa has made some internal state changes. + * + * This is in addition to any state change callbacks Mesa may already have + * made. */ + void (*UpdateState)( GLcontext *ctx, GLuint new_state ); - void (*Clear)( GLcontext *ctx, GLbitfield mask, GLboolean all, - GLint x, GLint y, GLint width, GLint height ); - /* Clear the color/depth/stencil/accum buffer(s). - * 'mask' is a bitmask of the DD_*_BIT values defined above that indicates + /** + * Clear the color/depth/stencil/accum buffer(s). + * + * \param mask a bitmask of the DD_*_BIT values defined above that indicates * which buffers need to be cleared. - * If 'all' is true then the clear the whole buffer, else clear only the - * region defined by (x,y,width,height). - * This function must obey the glColorMask, glIndexMask and glStencilMask + * \param all if true then clear the whole buffer, else clear only the + * region defined by <tt>(x, y, width, height)</tt>. + * + * This function must obey the glColorMask(), glIndexMask() and glStencilMask() * settings! * Software Mesa can do masked clears if the device driver can't. */ + void (*Clear)( GLcontext *ctx, GLbitfield mask, GLboolean all, + GLint x, GLint y, GLint width, GLint height ); - void (*DrawBuffer)( GLcontext *ctx, GLenum buffer ); - /* - * Specifies the current buffer for writing. Called via glDrawBuffer(). - * Note the driver must organize fallbacks (eg with swrast) if it - * cannot implement the requested mode. + /** + * Specify the current buffer for writing. + * + * Called via glDrawBuffer(). Note the driver must organize fallbacks (e.g. + * with swrast) if it cannot implement the requested mode. */ + void (*DrawBuffer)( GLcontext *ctx, GLenum buffer ); - - void (*ReadBuffer)( GLcontext *ctx, GLenum buffer ); - /* - * Specifies the current buffer for reading. Called via glReadBuffer(). + /** + * Specifies the current buffer for reading. + * + * Called via glReadBuffer(). */ + void (*ReadBuffer)( GLcontext *ctx, GLenum buffer ); - void (*GetBufferSize)( GLframebuffer *buffer, - GLuint *width, GLuint *height ); - /* - * Returns the width and height of the named buffer/window. + /** + * Get the width and height of the named buffer/window. + * * Mesa uses this to determine when the driver's window size has changed. */ + void (*GetBufferSize)( GLframebuffer *buffer, + GLuint *width, GLuint *height ); - void (*ResizeBuffers)( GLframebuffer *buffer ); - /* + /** * Resize the driver's depth/stencil/accum/back buffers to match the - * size given in the GLframebuffer struct. This is typically called - * when Mesa detects that a window size has changed. + * size given in the GLframebuffer struct. + * + * This is typically called when Mesa detects that a window size has changed. */ + void (*ResizeBuffers)( GLframebuffer *buffer ); - void (*Finish)( GLcontext *ctx ); - /* + /** * This is called whenever glFinish() is called. */ + void (*Finish)( GLcontext *ctx ); - void (*Flush)( GLcontext *ctx ); - /* + /** * This is called whenever glFlush() is called. */ + void (*Flush)( GLcontext *ctx ); - void (*Error)( GLcontext *ctx ); - /* - * Called whenever an error is generated. ctx->ErrorValue contains - * the error value. + /** + * Called whenever an error is generated. + * + * __GLcontextRec::ErrorValue contains the error value. */ + void (*Error)( GLcontext *ctx ); - /*** - *** For hardware accumulation buffer: - ***/ + /** + * \name For hardware accumulation buffer + */ + /*@{*/ + /** + * Execute glAccum command within the given scissor region. + */ void (*Accum)( GLcontext *ctx, GLenum op, GLfloat value, GLint xpos, GLint ypos, GLint width, GLint height ); - /* Execute glAccum command within the given scissor region. - */ + /*@}*/ - /*** - *** glDraw/Read/CopyPixels and glBitmap functions: - ***/ + /** + * \name glDraw(), glRead(), glCopyPixels() and glBitmap() functions + */ + /*@{*/ + /** + * This is called by glDrawPixels(). + * + * \p unpack describes how to unpack the source image data. + */ void (*DrawPixels)( GLcontext *ctx, GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type, const struct gl_pixelstore_attrib *unpack, const GLvoid *pixels ); - /* This is called by glDrawPixels. - * 'unpack' describes how to unpack the source image data. - */ + /** + * Called by glReadPixels(). + */ void (*ReadPixels)( GLcontext *ctx, GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type, const struct gl_pixelstore_attrib *unpack, GLvoid *dest ); - /* Called by glReadPixels. - */ + /** + * Do a glCopyPixels(). + * + * This function must respect all rasterization state, glPixelTransfer(), + * glPixelZoom(), etc. + */ void (*CopyPixels)( GLcontext *ctx, GLint srcx, GLint srcy, GLsizei width, GLsizei height, GLint dstx, GLint dsty, GLenum type ); - /* Do a glCopyPixels. This function must respect all rasterization - * state, glPixelTransfer, glPixelZoom, etc. - */ + /** + * This is called by glBitmap(). + * + * Works the same as dd_function_table::DrawPixels, above. + */ void (*Bitmap)( GLcontext *ctx, GLint x, GLint y, GLsizei width, GLsizei height, const struct gl_pixelstore_attrib *unpack, const GLubyte *bitmap ); - /* This is called by glBitmap. Works the same as DrawPixels, above. + /*@}*/ + + + /** + * \name Texture image functions */ + /*@{*/ - /*** - *** Texture image functions: - ***/ + /** + * Choose texture format. + * + * This is called by the \c _mesa_store_tex[sub]image[123]d() fallback + * functions. The driver should examine \p internalFormat and return a + * pointer to an appropriate gl_texture_format. + */ const struct gl_texture_format * (*ChooseTextureFormat)( GLcontext *ctx, GLint internalFormat, GLenum srcFormat, GLenum srcType ); - /* This is called by the _mesa_store_tex[sub]image[123]d() fallback - * functions. The driver should examine <internalFormat> and return a - * pointer to an appropriate gl_texture_format. - */ + /** + * Called by glTexImage1D(). + * + * \param target user specified. + * \param format user specified. + * \param type user specified. + * \param pixels user specified. + * \param packing indicates the image packing of pixels. + * \param texObj is the target texture object. + * \param texImage is the target texture image. It will have the texture \p + * width, \p height, \p depth, \p border and \p internalFormat information. + * + * \p retainInternalCopy is returned by this function and indicates whether + * core Mesa should keep an internal copy of the texture image. + * + * Drivers should call a fallback routine from texstore.c if needed. + */ void (*TexImage1D)( GLcontext *ctx, GLenum target, GLint level, GLint internalFormat, GLint width, GLint border, @@ -182,6 +233,12 @@ struct dd_function_table { const struct gl_pixelstore_attrib *packing, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); + + /** + * Called by glTexImage2D(). + * + * \sa dd_function_table::TexImage1D. + */ void (*TexImage2D)( GLcontext *ctx, GLenum target, GLint level, GLint internalFormat, GLint width, GLint height, GLint border, @@ -189,6 +246,12 @@ struct dd_function_table { const struct gl_pixelstore_attrib *packing, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); + + /** + * Called by glTexImage3D(). + * + * \sa dd_function_table::TexImage1D. + */ void (*TexImage3D)( GLcontext *ctx, GLenum target, GLint level, GLint internalFormat, GLint width, GLint height, GLint depth, GLint border, @@ -196,18 +259,28 @@ struct dd_function_table { const struct gl_pixelstore_attrib *packing, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); - /* Called by glTexImage1/2/3D. - * Arguments: - * <target>, <level>, <format>, <type> and <pixels> are user specified. - * <packing> indicates the image packing of pixels. - * <texObj> is the target texture object. - * <texImage> is the target texture image. It will have the texture - * width, height, depth, border and internalFormat information. - * <retainInternalCopy> is returned by this function and indicates whether - * core Mesa should keep an internal copy of the texture image. - * Drivers should call a fallback routine from texstore.c if needed. - */ + /** + * Called by glTexSubImage1D(). + * + * \param target user specified. + * \param level user specified. + * \param xoffset user specified. + * \param yoffset user specified. + * \param zoffset user specified. + * \param width user specified. + * \param height user specified. + * \param depth user specified. + * \param format user specified. + * \param type user specified. + * \param pixels user specified. + * \param packing indicates the image packing of pixels. + * \param texObj is the target texture object. + * \param texImage is the target texture image. It will have the texture \p + * width, \p height, \p border and \p internalFormat information. + * + * The driver should use a fallback routine from texstore.c if needed. + */ void (*TexSubImage1D)( GLcontext *ctx, GLenum target, GLint level, GLint xoffset, GLsizei width, GLenum format, GLenum type, @@ -215,6 +288,12 @@ struct dd_function_table { const struct gl_pixelstore_attrib *packing, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); + + /** + * Called by glTexSubImage2D(). + * + * \sa dd_function_table::TexSubImage1D. + */ void (*TexSubImage2D)( GLcontext *ctx, GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLsizei height, @@ -223,6 +302,12 @@ struct dd_function_table { const struct gl_pixelstore_attrib *packing, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); + + /** + * Called by glTexSubImage3D(). + * + * \sa dd_function_table::TexSubImage1D. + */ void (*TexSubImage3D)( GLcontext *ctx, GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLint depth, @@ -231,68 +316,108 @@ struct dd_function_table { const struct gl_pixelstore_attrib *packing, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); - /* Called by glTexSubImage1/2/3D. - * Arguments: - * <target>, <level>, <xoffset>, <yoffset>, <zoffset>, <width>, <height>, - * <depth>, <format>, <type> and <pixels> are user specified. - * <packing> indicates the image packing of pixels. - * <texObj> is the target texture object. - * <texImage> is the target texture image. It will have the texture - * width, height, border and internalFormat information. - * The driver should use a fallback routine from texstore.c if needed. - */ + /** + * Called by glCopyTexImage1D(). + * + * Drivers should use a fallback routine from texstore.c if needed. + */ void (*CopyTexImage1D)( GLcontext *ctx, GLenum target, GLint level, GLenum internalFormat, GLint x, GLint y, GLsizei width, GLint border ); + + /** + * Called by glCopyTexImage2D(). + * + * Drivers should use a fallback routine from texstore.c if needed. + */ void (*CopyTexImage2D)( GLcontext *ctx, GLenum target, GLint level, GLenum internalFormat, GLint x, GLint y, GLsizei width, GLsizei height, GLint border ); - /* Called by glCopyTexImage1D and glCopyTexImage2D. + + /** + * Called by glCopyTexSubImage1D(). + * * Drivers should use a fallback routine from texstore.c if needed. */ - void (*CopyTexSubImage1D)( GLcontext *ctx, GLenum target, GLint level, GLint xoffset, GLint x, GLint y, GLsizei width ); + /** + * Called by glCopyTexSubImage2D(). + * + * Drivers should use a fallback routine from texstore.c if needed. + */ void (*CopyTexSubImage2D)( GLcontext *ctx, GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint x, GLint y, GLsizei width, GLsizei height ); + /** + * Called by glCopyTexSubImage3D(). + * + * Drivers should use a fallback routine from texstore.c if needed. + */ void (*CopyTexSubImage3D)( GLcontext *ctx, GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLint x, GLint y, GLsizei width, GLsizei height ); - /* Called by glCopyTexSubImage1/2/3D. - * Drivers should use a fallback routine from texstore.c if needed. - */ + /** + * Called by glTexImage[123]D when user specifies a proxy texture + * target. + * + * \return GL_TRUE if the proxy test passes, or GL_FALSE if the test fails. + */ GLboolean (*TestProxyTexImage)(GLcontext *ctx, GLenum target, GLint level, GLint internalFormat, GLenum format, GLenum type, GLint width, GLint height, GLint depth, GLint border); - /* Called by glTexImage[123]D when user specifies a proxy texture - * target. Return GL_TRUE if the proxy test passes, return GL_FALSE - * if the test fails. - */ + /*@}*/ - /*** - *** Compressed texture functions: - ***/ + + /** + * \name Compressed texture functions + */ + /*@{*/ + /** + * Called by glCompressedTexImage1D(). + * + * \param target user specified. + * \param format user specified. + * \param type user specified. + * \param pixels user specified. + * \param packing indicates the image packing of pixels. + * \param texObj is the target texture object. + * \param texImage is the target texture image. It will have the texture \p + * width, \p height, \p depth, \p border and \p internalFormat information. + * + * \a retainInternalCopy is returned by this function and indicates whether + * core Mesa should keep an internal copy of the texture image. + */ void (*CompressedTexImage1D)( GLcontext *ctx, GLenum target, GLint level, GLint internalFormat, GLsizei width, GLint border, GLsizei imageSize, const GLvoid *data, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); + /** + * Called by glCompressedTexImage2D(). + * + * \sa dd_function_table::CompressedTexImage1D. + */ void (*CompressedTexImage2D)( GLcontext *ctx, GLenum target, GLint level, GLint internalFormat, GLsizei width, GLsizei height, GLint border, GLsizei imageSize, const GLvoid *data, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); + /** + * Called by glCompressedTexImage3D(). + * + * \sa dd_function_table::CompressedTexImage3D. + */ void (*CompressedTexImage3D)( GLcontext *ctx, GLenum target, GLint level, GLint internalFormat, GLsizei width, GLsizei height, GLsizei depth, @@ -300,24 +425,35 @@ struct dd_function_table { GLsizei imageSize, const GLvoid *data, struct gl_texture_object *texObj, struct gl_texture_image *texImage ); - /* Called by glCompressedTexImage1/2/3D. - * Arguments: - * <target>, <level>, <internalFormat>, <data> are user specified. - * <texObj> is the target texture object. - * <texImage> is the target texture image. It will have the texture - * width, height, depth, border and internalFormat information. - * <retainInternalCopy> is returned by this function and indicates whether - * core Mesa should keep an internal copy of the texture image. - * Return GL_TRUE if operation completed, return GL_FALSE if core Mesa - * should do the job. - */ + /** + * Called by glCompressedTexSubImage1D(). + * + * \param target user specified. + * \param level user specified. + * \param xoffset user specified. + * \param yoffset user specified. + * \param zoffset user specified. + * \param width user specified. + * \param height user specified. + * \param depth user specified. + * \param imageSize user specified. + * \param data user specified. + * \param texObj is the target texture object. + * \param texImage is the target texture image. It will have the texture \p + * width, \p height, \p depth, \p border and \p internalFormat information. + */ void (*CompressedTexSubImage1D)(GLcontext *ctx, GLenum target, GLint level, GLint xoffset, GLsizei width, GLenum format, GLsizei imageSize, const GLvoid *data, struct gl_texture_object *texObj, struct gl_texture_image *texImage); + /** + * Called by glCompressedTexSubImage2D(). + * + * \sa dd_function_table::CompressedTexImage3D. + */ void (*CompressedTexSubImage2D)(GLcontext *ctx, GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLint height, @@ -325,6 +461,11 @@ struct dd_function_table { GLsizei imageSize, const GLvoid *data, struct gl_texture_object *texObj, struct gl_texture_image *texImage); + /** + * Called by glCompressedTexSubImage3D(). + * + * \sa dd_function_table::CompressedTexImage3D. + */ void (*CompressedTexSubImage3D)(GLcontext *ctx, GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLint height, GLint depth, @@ -332,67 +473,77 @@ struct dd_function_table { GLsizei imageSize, const GLvoid *data, struct gl_texture_object *texObj, struct gl_texture_image *texImage); - /* Called by glCompressedTexSubImage1/2/3D. - * Arguments: - * <target>, <level>, <x/z/zoffset>, <width>, <height>, <depth>, - * <imageSize>, and <data> are user specified. - * <texObj> is the target texture object. - * <texImage> is the target texture image. It will have the texture - * width, height, depth, border and internalFormat information. - * Return GL_TRUE if operation completed, return GL_FALSE if core Mesa - * should do the job. - */ + /*@}*/ - /*** - *** Texture object functions: - ***/ + /** + * \name Texture object functions + */ + /*@{*/ + /** + * Called by glBindTexture(). + */ void (*BindTexture)( GLcontext *ctx, GLenum target, struct gl_texture_object *tObj ); - /* Called by glBindTexture(). + + /** + * Called when a texture object is created. */ + void (*CreateTexture)( GLcontext *ctx, struct gl_texture_object *tObj ); - struct gl_texture_object * (*NewTextureObject)( GLcontext *ctx, GLuint name, - GLenum target ); - /* Called to allocate a new texture object. - * NOTE: this function pointer should be initialized by drivers _BEFORE_ + /** + * Called to allocate a new texture object. + * + * \note This function pointer should be initialized by drivers \e before * calling _mesa_initialize_context() since context initialization involves * allocating some texture objects! */ - - void (*DeleteTexture)( GLcontext *ctx, struct gl_texture_object *tObj ); - /* Called when a texture object is about to be deallocated. Driver - * should free anything attached to the DriverData pointers. + struct gl_texture_object * (*NewTextureObject)( GLcontext *ctx, GLuint name, + GLenum target ); + /** + * Called when a texture object is about to be deallocated. + * + * Driver should free anything attached to the DriverData pointers. */ + void (*DeleteTexture)( GLcontext *ctx, struct gl_texture_object *tObj ); - struct gl_texture_image * (*NewTextureImage)( GLcontext *ctx ); - /* Called to allocate a new texture image object. + /** + * Called to allocate a new texture image object. */ + struct gl_texture_image * (*NewTextureImage)( GLcontext *ctx ); + /** + * Called by glAreTextureResident(). + */ GLboolean (*IsTextureResident)( GLcontext *ctx, struct gl_texture_object *t ); - /* Called by glAreTextureResident(). - */ + /** + * Called by glPrioritizeTextures(). + */ void (*PrioritizeTexture)( GLcontext *ctx, struct gl_texture_object *t, GLclampf priority ); - /* Called by glPrioritizeTextures(). - */ - void (*ActiveTexture)( GLcontext *ctx, GLuint texUnitNumber ); - /* Called by glActiveTextureARB to set current texture unit. + /** + * Called by glActiveTextureARB() to set current texture unit. */ + void (*ActiveTexture)( GLcontext *ctx, GLuint texUnitNumber ); + /** + * Called when the texture's color lookup table is changed. + * + * If \p tObj is NULL then the shared texture palette + * gl_texture_object::Palette is to be updated. + */ void (*UpdateTexturePalette)( GLcontext *ctx, struct gl_texture_object *tObj ); - /* Called when the texture's color lookup table is changed. - * If tObj is NULL then the shared texture palette ctx->Texture.Palette - * is to be updated. - */ + /*@}*/ - /*** - *** Imaging functionality: - ***/ + + /** + * \name Imaging functionality + */ + /*@{*/ void (*CopyColorTable)( GLcontext *ctx, GLenum target, GLenum internalformat, GLint x, GLint y, GLsizei width ); @@ -409,74 +560,119 @@ struct dd_function_table { GLenum internalFormat, GLint x, GLint y, GLsizei width, GLsizei height ); + /*@}*/ - - /*** - *** State-changing functions (drawing functions are above) - *** - *** These functions are called by their corresponding OpenGL API functions. - *** They're ALSO called by the gl_PopAttrib() function!!! - *** May add more functions like these to the device driver in the future. - ***/ + /** + * \name State-changing functions. + * + * \note drawing functions are above. + * + * These functions are called by their corresponding OpenGL API functions. + * They are \e also called by the gl_PopAttrib() function!!! + * May add more functions like these to the device driver in the future. + */ + /*@{*/ + /** Specify the alpha test function */ void (*AlphaFunc)(GLcontext *ctx, GLenum func, GLfloat ref); + /** Set the blend color */ void (*BlendColor)(GLcontext *ctx, const GLfloat color[4]); + /** Set the blend equation */ void (*BlendEquation)(GLcontext *ctx, GLenum mode); + /** Specify pixel arithmetic */ void (*BlendFunc)(GLcontext *ctx, GLenum sfactor, GLenum dfactor); void (*BlendFuncSeparate)(GLcontext *ctx, GLenum sfactorRGB, GLenum dfactorRGB, GLenum sfactorA, GLenum dfactorA); + /** Specify clear values for the color buffers */ void (*ClearColor)(GLcontext *ctx, const GLfloat color[4]); + /** Specify the clear value for the depth buffer */ void (*ClearDepth)(GLcontext *ctx, GLclampd d); + /** Specify the clear value for the color index buffers */ void (*ClearIndex)(GLcontext *ctx, GLuint index); + /** Specify the clear value for the stencil buffer */ void (*ClearStencil)(GLcontext *ctx, GLint s); + /** Specify a plane against which all geometry is clipped */ void (*ClipPlane)(GLcontext *ctx, GLenum plane, const GLfloat *equation ); + /** Enable and disable writing of frame buffer color components */ void (*ColorMask)(GLcontext *ctx, GLboolean rmask, GLboolean gmask, GLboolean bmask, GLboolean amask ); + /** Cause a material color to track the current color */ void (*ColorMaterial)(GLcontext *ctx, GLenum face, GLenum mode); + /** Specify whether front- or back-facing facets can be culled */ void (*CullFace)(GLcontext *ctx, GLenum mode); + /** Define front- and back-facing polygons */ void (*FrontFace)(GLcontext *ctx, GLenum mode); + /** Specify the value used for depth buffer comparisons */ void (*DepthFunc)(GLcontext *ctx, GLenum func); + /** Enable or disable writing into the depth buffer */ void (*DepthMask)(GLcontext *ctx, GLboolean flag); + /** Specify mapping of depth values from normalized device coordinates to window coordinates */ void (*DepthRange)(GLcontext *ctx, GLclampd nearval, GLclampd farval); - void (*Enable)(GLcontext* ctx, GLenum cap, GLboolean state); + /** Enable or disable server-side gl capabilities */ + void (*Enable)(GLcontext *ctx, GLenum cap, GLboolean state); + /** Specify fog parameters */ void (*Fogfv)(GLcontext *ctx, GLenum pname, const GLfloat *params); + /** Specify implementation-specific hints */ void (*Hint)(GLcontext *ctx, GLenum target, GLenum mode); + /** Control the writing of individual bits in the color index buffers */ void (*IndexMask)(GLcontext *ctx, GLuint mask); + /** Set light source parameters */ void (*Lightfv)(GLcontext *ctx, GLenum light, GLenum pname, const GLfloat *params ); + /** Set the lighting model parameters */ void (*LightModelfv)(GLcontext *ctx, GLenum pname, const GLfloat *params); + /** Specify the line stipple pattern */ void (*LineStipple)(GLcontext *ctx, GLint factor, GLushort pattern ); + /** Specify the width of rasterized lines */ void (*LineWidth)(GLcontext *ctx, GLfloat width); + /** Specify a logical pixel operation for color index rendering */ void (*LogicOpcode)(GLcontext *ctx, GLenum opcode); void (*PointParameterfv)(GLcontext *ctx, GLenum pname, const GLfloat *params); + /** Specify the diameter of rasterized points */ void (*PointSize)(GLcontext *ctx, GLfloat size); + /** Select a polygon rasterization mode */ void (*PolygonMode)(GLcontext *ctx, GLenum face, GLenum mode); + /** Set the scale and units used to calculate depth values */ void (*PolygonOffset)(GLcontext *ctx, GLfloat factor, GLfloat units); + /** Set the polygon stippling pattern */ void (*PolygonStipple)(GLcontext *ctx, const GLubyte *mask ); + /** Set rasterization mode */ void (*RenderMode)(GLcontext *ctx, GLenum mode ); + /** Define the scissor box */ void (*Scissor)(GLcontext *ctx, GLint x, GLint y, GLsizei w, GLsizei h); + /** Select flat or smooth shading */ void (*ShadeModel)(GLcontext *ctx, GLenum mode); + /** Set function and reference value for stencil testing */ void (*StencilFunc)(GLcontext *ctx, GLenum func, GLint ref, GLuint mask); + /** Control the writing of individual bits in the stencil planes */ void (*StencilMask)(GLcontext *ctx, GLuint mask); + /** Set stencil test actions */ void (*StencilOp)(GLcontext *ctx, GLenum fail, GLenum zfail, GLenum zpass); void (*ActiveStencilFace)(GLcontext *ctx, GLuint face); + /** Control the generation of texture coordinates */ void (*TexGen)(GLcontext *ctx, GLenum coord, GLenum pname, const GLfloat *params); + /** Set texture environment parameters */ void (*TexEnv)(GLcontext *ctx, GLenum target, GLenum pname, const GLfloat *param); + /** Set texture parameters */ void (*TexParameter)(GLcontext *ctx, GLenum target, struct gl_texture_object *texObj, GLenum pname, const GLfloat *params); void (*TextureMatrix)(GLcontext *ctx, GLuint unit, const GLmatrix *mat); + /** Set the viewport */ void (*Viewport)(GLcontext *ctx, GLint x, GLint y, GLsizei w, GLsizei h); + /*@}*/ + - /*** - *** Vertex array functions - *** - *** Called by the corresponding OpenGL functions. - ***/ + /** + * \name Vertex array functions + * + * Called by the corresponding OpenGL functions. + */ + /*@{*/ void (*VertexPointer)(GLcontext *ctx, GLint size, GLenum type, GLsizei stride, const GLvoid *ptr); void (*NormalPointer)(GLcontext *ctx, GLenum type, @@ -494,111 +690,171 @@ struct dd_function_table { void (*EdgeFlagPointer)(GLcontext *ctx, GLsizei stride, const GLvoid *ptr); void (*VertexAttribPointer)(GLcontext *ctx, GLuint index, GLint size, GLenum type, GLsizei stride, const GLvoid *ptr); + /*@}*/ - /*** State-query functions - *** - *** Return GL_TRUE if query was completed, GL_FALSE otherwise. - ***/ + /** + * \name State-query functions + * + * Return GL_TRUE if query was completed, GL_FALSE otherwise. + */ + /*@{*/ + /** Return the value or values of a selected parameter */ GLboolean (*GetBooleanv)(GLcontext *ctx, GLenum pname, GLboolean *result); + /** Return the value or values of a selected parameter */ GLboolean (*GetDoublev)(GLcontext *ctx, GLenum pname, GLdouble *result); + /** Return the value or values of a selected parameter */ GLboolean (*GetFloatv)(GLcontext *ctx, GLenum pname, GLfloat *result); + /** Return the value or values of a selected parameter */ GLboolean (*GetIntegerv)(GLcontext *ctx, GLenum pname, GLint *result); + /** Return the value or values of a selected parameter */ GLboolean (*GetPointerv)(GLcontext *ctx, GLenum pname, GLvoid **result); + /*@}*/ + - /*** - *** Support for multiple t&l engines - ***/ + /** + * \name Support for multiple T&L engines + */ + /*@{*/ - GLuint NeedValidate; - /* Bitmask of state changes that require the current tnl module to be + /** + * Bitmask of state changes that require the current T&L module to be * validated, using ValidateTnlModule() below. */ + GLuint NeedValidate; - void (*ValidateTnlModule)( GLcontext *ctx, GLuint new_state ); - /* Validate the current tnl module. This is called directly after - * UpdateState() when a state change that has occured matches the - * NeedValidate bitmask above. This ensures all computed values are - * up to date, thus allowing the driver to decide if the current tnl - * module needs to be swapped out. + /** + * Validate the current T&L module. + * + * This is called directly after UpdateState() when a state change that has + * occurred matches the dd_function_table::NeedValidate bitmask above. This + * ensures all computed values are up to date, thus allowing the driver to + * decide if the current T&L module needs to be swapped out. * - * This must be non-NULL if a driver installs a custom tnl module and - * sets the NeedValidate bitmask, but may be NULL otherwise. + * This must be non-NULL if a driver installs a custom T&L module and sets + * the dd_function_table::NeedValidate bitmask, but may be NULL otherwise. */ + void (*ValidateTnlModule)( GLcontext *ctx, GLuint new_state ); #define PRIM_OUTSIDE_BEGIN_END GL_POLYGON+1 #define PRIM_INSIDE_UNKNOWN_PRIM GL_POLYGON+2 #define PRIM_UNKNOWN GL_POLYGON+3 - GLuint CurrentExecPrimitive; - /* Set by the driver-supplied t&l engine. Set to - * PRIM_OUTSIDE_BEGIN_END when outside begin/end. + /** + * Set by the driver-supplied T&L engine. + * + * Set to PRIM_OUTSIDE_BEGIN_END when outside glBegin()/glEnd(). */ + GLuint CurrentExecPrimitive; - GLuint CurrentSavePrimitive; - /* Current state of an in-progress compilation. May take on any of - * the additional values defined above. + /** + * Current state of an in-progress compilation. + * + * May take on any of the additional values PRIM_OUTSIDE_BEGIN_END, + * PRIM_INSIDE_UNKNOWN_PRIM or PRIM_UNKNOWN defined above. */ + GLuint CurrentSavePrimitive; #define FLUSH_STORED_VERTICES 0x1 #define FLUSH_UPDATE_CURRENT 0x2 - GLuint NeedFlush; - /* Set by the driver-supplied t&l engine whenever vertices are - * buffered between begin/end objects or ctx->Current is not uptodate. + /** + * Set by the driver-supplied T&L engine whenever vertices are buffered + * between glBegin()/glEnd() objects or __GLcontextRec::Current is not + * updated. * - * The FlushVertices() call below may be used to resolve + * The dd_function_table::FlushVertices call below may be used to resolve * these conditions. */ + GLuint NeedFlush; - void (*FlushVertices)( GLcontext *ctx, GLuint flags ); - /* If inside begin/end, ASSERT(0). - * Otherwise, - * if (flags & FLUSH_STORED_VERTICES) flushes any buffered vertices, - * if (flags & FLUSH_UPDATE_CURRENT) updates ctx->Current - * and ctx->Light.Material + /** + * If inside glBegin()/glEnd(), it should ASSERT(0). Otherwise, if + * FLUSH_STORED_VERTICES bit in \p flags is set flushes any buffered + * vertices, if FLUSH_UPDATE_CURRENT bit is set updates + * __GLcontextRec::Current and gl_light_attrib::Material * - * Note that the default t&l engine never clears the + * Note that the default T&L engine never clears the * FLUSH_UPDATE_CURRENT bit, even after performing the update. */ + void (*FlushVertices)( GLcontext *ctx, GLuint flags ); - void (*LightingSpaceChange)( GLcontext *ctx ); - /* Notify driver that the special derived value _NeedEyeCoords has + /** + * Notify driver that the special derived value _NeedEyeCoords has * changed. */ + void (*LightingSpaceChange)( GLcontext *ctx ); - void (*NewList)( GLcontext *ctx, GLuint list, GLenum mode ); - void (*EndList)( GLcontext *ctx ); - /* Let the t&l component know what is going on with display lists + /** + * Called by glNewList(). + * + * Let the T&L component know what is going on with display lists * in time to make changes to dispatch tables, etc. - * Called by glNewList() and glEndList(), respectively. */ + void (*NewList)( GLcontext *ctx, GLuint list, GLenum mode ); + /** + * Called by glEndList(). + * + * \sa dd_function_table::NewList. + */ + void (*EndList)( GLcontext *ctx ); - void (*BeginCallList)( GLcontext *ctx, GLuint list ); - void (*EndCallList)( GLcontext *ctx ); - /* Notify the t&l component before and after calling a display list. + /** + * Called by glCallList(s), but not recursively. + * + * Notify the T&L component before and after calling a display list. * Called by glCallList(s), but not recursively. */ + void (*BeginCallList)( GLcontext *ctx, GLuint list ); + /** + * Called by glEndCallList(). + * + * \sa dd_function_table::BeginCallList. + */ + void (*EndCallList)( GLcontext *ctx ); + /** + * Let the T&L component know when the context becomes current. + */ void (*MakeCurrent)( GLcontext *ctx, GLframebuffer *drawBuffer, GLframebuffer *readBuffer ); - /* Let the t&l component know when the context becomes current. - */ - + /** + * Called by glLockArraysEXT(). + */ void (*LockArraysEXT)( GLcontext *ctx, GLint first, GLsizei count ); - void (*UnlockArraysEXT)( GLcontext *ctx ); - /* Called by glLockArraysEXT() and glUnlockArraysEXT(), respectively. + /** + * Called by UnlockArraysEXT(). */ + void (*UnlockArraysEXT)( GLcontext *ctx ); + /*@}*/ }; - -/* +/** * Transform/Clip/Lighting interface + * + * Drivers present a reduced set of the functions possible in + * glBegin()/glEnd() objects. Core mesa provides translation stubs for the + * remaining functions to map down to these entry points. + * + * These are the initial values to be installed into dispatch by + * mesa. If the T&L driver wants to modify the dispatch table + * while installed, it must do so itself. It would be possible for + * the vertexformat to install it's own initial values for these + * functions, but this way there is an obvious list of what is + * expected of the driver. + * + * If the driver wants to hook in entry points other than those + * listed, it must restore them to their original values in + * the disable() callback, below. */ typedef struct { + /** + * \name Vertex + */ + /*@{*/ void (*ArrayElement)( GLint ); /* NOTE */ void (*Color3f)( GLfloat, GLfloat, GLfloat ); void (*Color3fv)( const GLfloat * ); @@ -654,52 +910,48 @@ typedef struct { void (*End)( void ); void (*VertexAttrib4fNV)( GLuint index, GLfloat x, GLfloat y, GLfloat z, GLfloat w ); void (*VertexAttrib4fvNV)( GLuint index, const GLfloat *v ); + /*@}*/ - /* Drivers present a reduced set of the functions possible in - * begin/end objects. Core mesa provides translation stubs for the - * remaining functions to map down to these entrypoints. - * - * These are the initial values to be installed into dispatch by - * mesa. If the t&l driver wants to modify the dispatch table - * while installed, it must do so itself. It would be possible for - * the vertexformat to install it's own initial values for these - * functions, but this way there is an obvious list of what is - * expected of the driver. - * - * If the driver wants to hook in entrypoints other than those - * listed above, it must restore them to their original values in - * the disable() callback, below. - */ - - void (*Rectf)( GLfloat, GLfloat, GLfloat, GLfloat ); /* */ + void (*Rectf)( GLfloat, GLfloat, GLfloat, GLfloat ); + /** + * \name Array + * + * These may or may not belong here. Heuristic: if an array is + * enabled, the installed vertex format should support that array and + * its current size natively. + */ + /*@{*/ void (*DrawArrays)( GLenum mode, GLint start, GLsizei count ); void (*DrawElements)( GLenum mode, GLsizei count, GLenum type, const GLvoid *indices ); void (*DrawRangeElements)( GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); - /* These may or may not belong here. Heuristic: If an array is - * enabled, the installed vertex format should support that array and - * it's current size natively. - */ + /*@}*/ - void (*EvalMesh1)( GLenum mode, GLint i1, GLint i2 ); - void (*EvalMesh2)( GLenum mode, GLint i1, GLint i2, GLint j1, GLint j2 ); - /* If you don't support eval, fallback to the default vertex format + /** + * \name Eval + * + * If you don't support eval, fallback to the default vertex format * on receiving an eval call and use the pipeline mechanism to - * provide partial t&l acceleration. + * provide partial T&L acceleration. * * Mesa will provide a set of helper functions to do eval within * accelerated vertex formats, eventually... */ + /*@{*/ + void (*EvalMesh1)( GLenum mode, GLint i1, GLint i2 ); + void (*EvalMesh2)( GLenum mode, GLint i1, GLint i2, GLint j1, GLint j2 ); + /*@}*/ - GLboolean prefer_float_colors; - /* Should core try to send colors to glColor4f or glColor4chan, + /** + * Should core try to send colors to glColor4f or glColor4chan, * where it has a choice? */ + GLboolean prefer_float_colors; } GLvertexformat; |