--- /dev/null
+/* $Id: dd.h,v 1.15 1997/12/05 04:38:28 brianp Exp $ */
+
+/*
+ * Mesa 3-D graphics library
+ * Version: 2.6
+ * Copyright (C) 1995-1997 Brian Paul
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the Free
+ * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+
+/*
+ * $Log: dd.h,v $
+ * Revision 1.15 1997/12/05 04:38:28 brianp
+ * added ClearColorAndDepth() function pointer (David Bucciarelli)
+ *
+ * Revision 1.14 1997/11/25 03:39:41 brianp
+ * added TexSubImage() function pointer (David Bucciarelli)
+ *
+ * Revision 1.13 1997/10/29 02:23:54 brianp
+ * added UseGlobalTexturePalette() dd function (David Bucciarelli v20 3dfx)
+ *
+ * Revision 1.12 1997/10/16 02:27:53 brianp
+ * more comments
+ *
+ * Revision 1.11 1997/10/14 00:07:40 brianp
+ * added DavidB's fxmesa v19 changes
+ *
+ * Revision 1.10 1997/09/29 23:26:50 brianp
+ * new texture functions
+ *
+ * Revision 1.9 1997/04/29 01:31:07 brianp
+ * added RasterSetup() function to device driver
+ *
+ * Revision 1.8 1997/04/20 19:47:27 brianp
+ * added RenderVB to device driver
+ *
+ * Revision 1.7 1997/04/20 16:31:08 brianp
+ * added NearFar device driver function
+ *
+ * Revision 1.6 1997/04/12 12:27:31 brianp
+ * added QuadFunc and RectFunc
+ *
+ * Revision 1.5 1997/03/21 01:57:07 brianp
+ * added RendererString() function
+ *
+ * Revision 1.4 1997/02/10 19:22:47 brianp
+ * added device driver Error() function
+ *
+ * Revision 1.3 1997/01/16 03:34:33 brianp
+ * added preliminary texture mapping functions and cleaned up documentation
+ *
+ * Revision 1.2 1996/11/13 03:51:59 brianp
+ * updated comments
+ *
+ * Revision 1.1 1996/09/13 01:38:16 brianp
+ * Initial revision
+ *
+ */
+
+
+#ifndef DD_INCLUDED
+#define DD_INCLUDED
+
+
+/* THIS FILE ONLY INCLUDED BY types.h !!!!! */
+
+
+/*
+ * Device Driver (DD) interface
+ *
+ *
+ * All device driver functions are accessed through pointers in the
+ * dd_function_table struct (defined below) which is stored in the GLcontext
+ * struct. Since the device driver is strictly accessed trough a table of
+ * function pointers we can:
+ * 1. switch between a number of different device drivers at runtime.
+ * 2. use optimized functions dependant on current rendering state or
+ * frame buffer configuration.
+ *
+ * The function pointers in the dd_function_table struct are divided into
+ * two groups: mandatory and optional.
+ * Mandatory functions have to be implemented by every device driver.
+ * Optional functions may or may not be implemented by the device driver.
+ * The optional functions provide ways to take advantage of special hardware
+ * or optimized algorithms.
+ *
+ * The function pointers in the dd_function_table struct are first
+ * initialized in the "MakeCurrent" function. The "MakeCurrent" function
+ * is a little different in each device driver. See the X/Mesa, GLX, or
+ * OS/Mesa drivers for examples.
+ *
+ * Later, Mesa may call the dd_function_table's UpdateState() function.
+ * This function should initialize the dd_function_table's pointers again.
+ * The UpdateState() function is called whenever the core (GL) rendering
+ * state is changed in a way which may effect rasterization. For example,
+ * the TriangleFunc() pointer may have to point to different functions
+ * depending on whether smooth or flat shading is enabled.
+ *
+ * Note that the first argument to every device driver function is a
+ * GLcontext *. In turn, the GLcontext->DriverCtx pointer points to
+ * the driver-specific context struct. See the X/Mesa or OS/Mesa interface
+ * for an example.
+ *
+ * For more information about writing a device driver see the ddsample.c
+ * file and other device drivers (xmesa[123].c, osmesa.c, etc) for examples.
+ *
+ *
+ * Look below in the dd_function_table struct definition for descriptions
+ * of each device driver function.
+ *
+ *
+ * In the future more function pointers may be added for glReadPixels
+ * glCopyPixels, etc.
+ *
+ *
+ * Notes:
+ * ------
+ * RGBA = red/green/blue/alpha
+ * CI = color index (color mapped mode)
+ * mono = all pixels have the same color or index
+ *
+ * The write_ functions all take an array of mask flags which indicate
+ * whether or not the pixel should be written. One special case exists
+ * in the write_color_span function: if the mask array is NULL, then
+ * draw all pixels. This is an optimization used for glDrawPixels().
+ *
+ * IN ALL CASES:
+ * X coordinates start at 0 at the left and increase to the right
+ * Y coordinates start at 0 at the bottom and increase upward
+ *
+ */
+
+
+
+
+
+/*
+ * Device Driver function table.
+ */
+struct dd_function_table {
+
+ /**********************************************************************
+ *** Mandatory functions: these functions must be implemented by ***
+ *** every device driver. ***
+ **********************************************************************/
+
+ const char * (*RendererString)(void);
+ /*
+ * Return a string which uniquely identifies this device driver.
+ * The string should contain no whitespace. Examples: "X11" "OffScreen"
+ * "MSWindows" "SVGA".
+ */
+
+ void (*UpdateState)( GLcontext *ctx );
+ /*
+ * UpdateState() is called whenver Mesa thinks the device driver should
+ * update its state and/or the other pointers (such as PointsFunc,
+ * LineFunc, or TriangleFunc).
+ */
+
+ void (*ClearIndex)( GLcontext *ctx, GLuint index );
+ /*
+ * Called whenever glClearIndex() is called. Set the index for clearing
+ * the color buffer.
+ */
+
+ void (*ClearColor)( GLcontext *ctx, GLubyte red, GLubyte green,
+ GLubyte blue, GLubyte alpha );
+ /*
+ * Called whenever glClearColor() is called. Set the color for clearing
+ * the color buffer.
+ */
+
+ void (*Clear)( GLcontext *ctx,
+ GLboolean all, GLint x, GLint y, GLint width, GLint height );
+ /*
+ * Clear the current color buffer. If 'all' is set the clear the whole
+ * buffer, else clear the region defined by (x,y,width,height).
+ */
+
+ void (*Index)( GLcontext *ctx, GLuint index );
+ /*
+ * Sets current color index for drawing flat-shaded primitives.
+ */
+
+ void (*Color)( GLcontext *ctx,
+ GLubyte red, GLubyte green, GLubyte glue, GLubyte alpha );
+ /*
+ * Sets current color for drawing flat-shaded primitives.
+ */
+
+ GLboolean (*SetBuffer)( GLcontext *ctx, GLenum mode );
+ /*
+ * Selects either the front or back color buffer for reading and writing.
+ * mode is either GL_FRONT or GL_BACK.
+ */
+
+ void (*GetBufferSize)( GLcontext *ctx,
+ GLuint *width, GLuint *height );
+ /*
+ * Returns the width and height of the current color buffer.
+ */
+
+
+ /***
+ *** Functions for writing pixels to the frame buffer:
+ ***/
+ void (*WriteColorSpan)( GLcontext *ctx,
+ GLuint n, GLint x, GLint y,
+ const GLubyte red[], const GLubyte green[],
+ const GLubyte blue[], const GLubyte alpha[],
+ const GLubyte mask[] );
+ /*
+ * Write a horizontal run of RGBA pixels.
+ */
+
+ void (*WriteMonocolorSpan)( GLcontext *ctx,
+ GLuint n, GLint x, GLint y,
+ const GLubyte mask[] );
+ /*
+ * Write a horizontal run of mono-RGBA pixels.
+ */
+
+ void (*WriteColorPixels)( GLcontext *ctx,
+ GLuint n, const GLint x[], const GLint y[],
+ const GLubyte red[], const GLubyte green[],
+ const GLubyte blue[], const GLubyte alpha[],
+ const GLubyte mask[] );
+ /*
+ * Write an array of RGBA pixels at random locations.
+ */
+
+ void (*WriteMonocolorPixels)( GLcontext *ctx,
+ GLuint n, const GLint x[], const GLint y[],
+ const GLubyte mask[] );
+ /*
+ * Write an array of mono-RGBA pixels at random locations.
+ */
+
+ void (*WriteIndexSpan)( GLcontext *ctx,
+ GLuint n, GLint x, GLint y, const GLuint index[],
+ const GLubyte mask[] );
+ /*
+ * Write a horizontal run of CI pixels.
+ */
+
+ void (*WriteMonoindexSpan)( GLcontext *ctx,
+ GLuint n, GLint x, GLint y,
+ const GLubyte mask[] );
+ /*
+ * Write a horizontal run of mono-CI pixels.
+ */
+
+ void (*WriteIndexPixels)( GLcontext *ctx,
+ GLuint n, const GLint x[], const GLint y[],
+ const GLuint index[], const GLubyte mask[] );
+ /*
+ * Write a random array of CI pixels.
+ */
+
+ void (*WriteMonoindexPixels)( GLcontext *ctx,
+ GLuint n, const GLint x[], const GLint y[],
+ const GLubyte mask[] );
+ /*
+ * Write a random array of mono-CI pixels.
+ */
+
+ /***
+ *** Functions to read pixels from frame buffer:
+ ***/
+ void (*ReadIndexSpan)( GLcontext *ctx,
+ GLuint n, GLint x, GLint y, GLuint index[] );
+ /*
+ * Read a horizontal run of color index pixels.
+ */
+
+ void (*ReadColorSpan)( GLcontext *ctx,
+ GLuint n, GLint x, GLint y,
+ GLubyte red[], GLubyte green[],
+ GLubyte blue[], GLubyte alpha[] );
+ /*
+ * Read a horizontal run of RGBA pixels.
+ */
+
+ void (*ReadIndexPixels)( GLcontext *ctx,
+ GLuint n, const GLint x[], const GLint y[],
+ GLuint indx[], const GLubyte mask[] );
+ /*
+ * Read a random array of CI pixels.
+ */
+
+ void (*ReadColorPixels)( GLcontext *ctx,
+ GLuint n, const GLint x[], const GLint y[],
+ GLubyte red[], GLubyte green[],
+ GLubyte blue[], GLubyte alpha[],
+ const GLubyte mask[] );
+ /*
+ * Read a random array of RGBA pixels.
+ */
+
+
+ /**********************************************************************
+ *** Optional functions: these functions may or may not be ***
+ *** implemented by the device driver. If the device driver ***
+ *** doesn't implement them it should never touch these pointers ***
+ *** since Mesa will either set them to NULL or point them at a ***
+ *** fall-back function. ***
+ **********************************************************************/
+
+ void (*Finish)( GLcontext *ctx );
+ /*
+ * Called whenever glFinish() is called.
+ */
+
+ void (*Flush)( GLcontext *ctx );
+ /*
+ * Called whenever glFlush() is called.
+ */
+
+ GLboolean (*IndexMask)( GLcontext *ctx, GLuint mask );
+ /*
+ * Implements glIndexMask() if possible, else return GL_FALSE.
+ */
+
+ GLboolean (*ColorMask)( GLcontext *ctx,
+ GLboolean rmask, GLboolean gmask,
+ GLboolean bmask, GLboolean amask );
+ /*
+ * Implements glColorMask() if possible, else return GL_FALSE.
+ */
+
+ GLboolean (*LogicOp)( GLcontext *ctx, GLenum op );
+ /*
+ * Implements glLogicOp() if possible, else return GL_FALSE.
+ */
+
+ void (*Dither)( GLcontext *ctx, GLboolean enable );
+ /*
+ * Enable/disable dithering.
+ */
+
+ void (*Error)( GLcontext *ctx );
+ /*
+ * Called whenever an error is generated. ctx->ErrorValue contains
+ * the error value.
+ */
+
+ void (*NearFar)( GLcontext *ctx, GLfloat nearVal, GLfloat farVal );
+ /*
+ * Called from glFrustum and glOrtho to tell device driver the
+ * near and far clipping plane Z values. The 3Dfx driver, for example,
+ * uses this.
+ */
+
+
+ /***
+ *** For supporting hardware Z buffers:
+ ***/
+
+ void (*AllocDepthBuffer)( GLcontext *ctx );
+ /*
+ * Called when the depth buffer must be allocated or possibly resized.
+ */
+
+ void (*ClearDepthBuffer)( GLcontext *ctx );
+ /*
+ * Clear the depth buffer to depth specified by CC.Depth.Clear value.
+ */
+
+ GLuint (*DepthTestSpan)( GLcontext *ctx,
+ GLuint n, GLint x, GLint y, const GLdepth z[],
+ GLubyte mask[] );
+ void (*DepthTestPixels)( GLcontext *ctx,
+ GLuint n, const GLint x[], const GLint y[],
+ const GLdepth z[], GLubyte mask[] );
+ /*
+ * Apply the depth buffer test to an span/array of pixels and return
+ * an updated pixel mask. This function is not used when accelerated
+ * point, line, polygon functions are used.
+ */
+
+ void (*ReadDepthSpanFloat)( GLcontext *ctx,
+ GLuint n, GLint x, GLint y, GLfloat depth[]);
+ void (*ReadDepthSpanInt)( GLcontext *ctx,
+ GLuint n, GLint x, GLint y, GLdepth depth[] );
+ /*
+ * Return depth values as integers for glReadPixels.
+ * Floats should be returned in the range [0,1].
+ * Ints (GLdepth) values should be in the range [0,MAXDEPTH].
+ */
+
+
+ void (*ClearColorAndDepth)( GLcontext *ctx,
+ GLboolean all, GLint x, GLint y,
+ GLint width, GLint height );
+ /*
+ * If this function is implemented then it will be called when both the
+ * color and depth buffers are to be cleared.
+ */
+
+
+ /***
+ *** Accelerated point, line, polygon, glDrawPixels and glBitmap functions:
+ ***/
+
+ points_func PointsFunc;
+ /*
+ * Called to draw an array of points.
+ */
+
+ line_func LineFunc;
+ /*
+ * Called to draw a line segment.
+ */
+
+ triangle_func TriangleFunc;
+ /*
+ * Called to draw a filled triangle.
+ */
+
+ quad_func QuadFunc;
+ /*
+ * Called to draw a filled quadrilateral.
+ */
+
+ rect_func RectFunc;
+ /*
+ * Called to draw a filled, screen-aligned 2-D rectangle.
+ */
+
+ GLboolean (*DrawPixels)( GLcontext *ctx,
+ GLint x, GLint y, GLsizei width, GLsizei height,
+ GLenum format, GLenum type, GLboolean packed,
+ const GLvoid *pixels );
+ /*
+ * Called from glDrawPixels().
+ */
+
+ GLboolean (*Bitmap)( GLcontext *ctx, GLsizei width, GLsizei height,
+ GLfloat xorig, GLfloat yorig,
+ GLfloat xmove, GLfloat ymove,
+ const struct gl_image *bitmap );
+ /*
+ * Called from glBitmap().
+ */
+
+ void (*Begin)( GLcontext *ctx, GLenum mode );
+ void (*End)( GLcontext *ctx );
+ /*
+ * These are called whenever glBegin() or glEnd() are called.
+ * The device driver may do some sort of window locking/unlocking here.
+ */
+
+
+ void (*RasterSetup)( GLcontext *ctx, GLuint start, GLuint end );
+ /*
+ * This function, if not NULL, is called whenever new window coordinates
+ * are put in the vertex buffer. The vertices in question are those n
+ * such that start <= n < end.
+ * The device driver can convert the window coords to its own specialized
+ * format. The 3Dfx driver uses this.
+ */
+
+ GLboolean (*RenderVB)( GLcontext *ctx, GLboolean allDone );
+ /*
+ * This function allows the device driver to rasterize an entire
+ * buffer of primitives at once. See the gl_render_vb() function
+ * in vbrender.c for more details.
+ * Return GL_TRUE if vertex buffer successfully rendered.
+ * Return GL_FALSE if failure, let core Mesa render the vertex buffer.
+ */
+
+ /***
+ *** Texture mapping functions:
+ ***/
+
+ void (*TexEnv)( GLcontext *ctx, GLenum pname, const GLfloat *param );
+ /*
+ * Called whenever glTexEnv*() is called.
+ * Pname will be one of GL_TEXTURE_ENV_MODE or GL_TEXTURE_ENV_COLOR.
+ * If pname is GL_TEXTURE_ENV_MODE then param will be one
+ * of GL_MODULATE, GL_BLEND, GL_DECAL, or GL_REPLACE.
+ */
+
+ void (*TexImage)( GLcontext *ctx, GLenum target,
+ struct gl_texture_object *tObj, GLint level,
+ GLint internalFormat,
+ const struct gl_texture_image *image );
+ /*
+ * Called whenever a texture object's image is changed.
+ * texObject is the number of the texture object being changed.
+ * level indicates the mipmap level.
+ * internalFormat is the format in which the texture is to be stored.
+ * image is a pointer to a gl_texture_image struct which contains
+ * the actual image data.
+ */
+
+ void (*TexSubImage)( GLcontext *ctx, GLenum target,
+ struct gl_texture_object *tObj, GLint level,
+ GLint xoffset, GLint yoffset,
+ GLsizei width, GLsizei height,
+ GLint internalFormat,
+ const struct gl_texture_image *image );
+ /*
+ * Called from glTexSubImage() to define a sub-region of a texture.
+ */
+
+ void (*TexParameter)( GLcontext *ctx, GLenum target,
+ struct gl_texture_object *tObj,
+ GLenum pname, const GLfloat *params );
+ /*
+ * Called whenever glTexParameter*() is called.
+ * target is GL_TEXTURE_1D or GL_TEXTURE_2D
+ * texObject is the texture object to modify
+ * pname is one of GL_TEXTURE_MIN_FILTER, GL_TEXTURE_MAG_FILTER,
+ * GL_TEXTURE_WRAP_S, GL_TEXTURE_WRAP_T, or GL_TEXTURE_BORDER_COLOR.
+ * params is dependant on pname. See man glTexParameter.
+ */
+
+ void (*BindTexture)( GLcontext *ctx, GLenum target,
+ struct gl_texture_object *tObj );
+ /*
+ * Called whenever glBindTexture() is called. This specifies which
+ * texture is to be the current one.
+ */
+
+ void (*DeleteTexture)( GLcontext *ctx, struct gl_texture_object *tObj );
+ /*
+ * Called when a texture object can be deallocated.
+ */
+
+ 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
+ * was changed.
+ */
+};
+
+
+
+#endif
+