1 /* $Id: dd.h,v 1.15 1997/12/05 04:38:28 brianp Exp $ */
4 * Mesa 3-D graphics library
6 * Copyright (C) 1995-1997 Brian Paul
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the Free
20 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
26 * Revision 1.15 1997/12/05 04:38:28 brianp
27 * added ClearColorAndDepth() function pointer (David Bucciarelli)
29 * Revision 1.14 1997/11/25 03:39:41 brianp
30 * added TexSubImage() function pointer (David Bucciarelli)
32 * Revision 1.13 1997/10/29 02:23:54 brianp
33 * added UseGlobalTexturePalette() dd function (David Bucciarelli v20 3dfx)
35 * Revision 1.12 1997/10/16 02:27:53 brianp
38 * Revision 1.11 1997/10/14 00:07:40 brianp
39 * added DavidB's fxmesa v19 changes
41 * Revision 1.10 1997/09/29 23:26:50 brianp
42 * new texture functions
44 * Revision 1.9 1997/04/29 01:31:07 brianp
45 * added RasterSetup() function to device driver
47 * Revision 1.8 1997/04/20 19:47:27 brianp
48 * added RenderVB to device driver
50 * Revision 1.7 1997/04/20 16:31:08 brianp
51 * added NearFar device driver function
53 * Revision 1.6 1997/04/12 12:27:31 brianp
54 * added QuadFunc and RectFunc
56 * Revision 1.5 1997/03/21 01:57:07 brianp
57 * added RendererString() function
59 * Revision 1.4 1997/02/10 19:22:47 brianp
60 * added device driver Error() function
62 * Revision 1.3 1997/01/16 03:34:33 brianp
63 * added preliminary texture mapping functions and cleaned up documentation
65 * Revision 1.2 1996/11/13 03:51:59 brianp
68 * Revision 1.1 1996/09/13 01:38:16 brianp
78 /* THIS FILE ONLY INCLUDED BY types.h !!!!! */
82 * Device Driver (DD) interface
85 * All device driver functions are accessed through pointers in the
86 * dd_function_table struct (defined below) which is stored in the GLcontext
87 * struct. Since the device driver is strictly accessed trough a table of
88 * function pointers we can:
89 * 1. switch between a number of different device drivers at runtime.
90 * 2. use optimized functions dependant on current rendering state or
91 * frame buffer configuration.
93 * The function pointers in the dd_function_table struct are divided into
94 * two groups: mandatory and optional.
95 * Mandatory functions have to be implemented by every device driver.
96 * Optional functions may or may not be implemented by the device driver.
97 * The optional functions provide ways to take advantage of special hardware
98 * or optimized algorithms.
100 * The function pointers in the dd_function_table struct are first
101 * initialized in the "MakeCurrent" function. The "MakeCurrent" function
102 * is a little different in each device driver. See the X/Mesa, GLX, or
103 * OS/Mesa drivers for examples.
105 * Later, Mesa may call the dd_function_table's UpdateState() function.
106 * This function should initialize the dd_function_table's pointers again.
107 * The UpdateState() function is called whenever the core (GL) rendering
108 * state is changed in a way which may effect rasterization. For example,
109 * the TriangleFunc() pointer may have to point to different functions
110 * depending on whether smooth or flat shading is enabled.
112 * Note that the first argument to every device driver function is a
113 * GLcontext *. In turn, the GLcontext->DriverCtx pointer points to
114 * the driver-specific context struct. See the X/Mesa or OS/Mesa interface
117 * For more information about writing a device driver see the ddsample.c
118 * file and other device drivers (xmesa[123].c, osmesa.c, etc) for examples.
121 * Look below in the dd_function_table struct definition for descriptions
122 * of each device driver function.
125 * In the future more function pointers may be added for glReadPixels
131 * RGBA = red/green/blue/alpha
132 * CI = color index (color mapped mode)
133 * mono = all pixels have the same color or index
135 * The write_ functions all take an array of mask flags which indicate
136 * whether or not the pixel should be written. One special case exists
137 * in the write_color_span function: if the mask array is NULL, then
138 * draw all pixels. This is an optimization used for glDrawPixels().
141 * X coordinates start at 0 at the left and increase to the right
142 * Y coordinates start at 0 at the bottom and increase upward
151 * Device Driver function table.
153 struct dd_function_table
{
155 /**********************************************************************
156 *** Mandatory functions: these functions must be implemented by ***
157 *** every device driver. ***
158 **********************************************************************/
160 const char * (*RendererString
)(void);
162 * Return a string which uniquely identifies this device driver.
163 * The string should contain no whitespace. Examples: "X11" "OffScreen"
164 * "MSWindows" "SVGA".
167 void (*UpdateState
)( GLcontext
*ctx
);
169 * UpdateState() is called whenver Mesa thinks the device driver should
170 * update its state and/or the other pointers (such as PointsFunc,
171 * LineFunc, or TriangleFunc).
174 void (*ClearIndex
)( GLcontext
*ctx
, GLuint index
);
176 * Called whenever glClearIndex() is called. Set the index for clearing
180 void (*ClearColor
)( GLcontext
*ctx
, GLubyte red
, GLubyte green
,
181 GLubyte blue
, GLubyte alpha
);
183 * Called whenever glClearColor() is called. Set the color for clearing
187 void (*Clear
)( GLcontext
*ctx
,
188 GLboolean all
, GLint x
, GLint y
, GLint width
, GLint height
);
190 * Clear the current color buffer. If 'all' is set the clear the whole
191 * buffer, else clear the region defined by (x,y,width,height).
194 void (*Index
)( GLcontext
*ctx
, GLuint index
);
196 * Sets current color index for drawing flat-shaded primitives.
199 void (*Color
)( GLcontext
*ctx
,
200 GLubyte red
, GLubyte green
, GLubyte glue
, GLubyte alpha
);
202 * Sets current color for drawing flat-shaded primitives.
205 GLboolean (*SetBuffer
)( GLcontext
*ctx
, GLenum mode
);
207 * Selects either the front or back color buffer for reading and writing.
208 * mode is either GL_FRONT or GL_BACK.
211 void (*GetBufferSize
)( GLcontext
*ctx
,
212 GLuint
*width
, GLuint
*height
);
214 * Returns the width and height of the current color buffer.
219 *** Functions for writing pixels to the frame buffer:
221 void (*WriteColorSpan
)( GLcontext
*ctx
,
222 GLuint n
, GLint x
, GLint y
,
223 const GLubyte red
[], const GLubyte green
[],
224 const GLubyte blue
[], const GLubyte alpha
[],
225 const GLubyte mask
[] );
227 * Write a horizontal run of RGBA pixels.
230 void (*WriteMonocolorSpan
)( GLcontext
*ctx
,
231 GLuint n
, GLint x
, GLint y
,
232 const GLubyte mask
[] );
234 * Write a horizontal run of mono-RGBA pixels.
237 void (*WriteColorPixels
)( GLcontext
*ctx
,
238 GLuint n
, const GLint x
[], const GLint y
[],
239 const GLubyte red
[], const GLubyte green
[],
240 const GLubyte blue
[], const GLubyte alpha
[],
241 const GLubyte mask
[] );
243 * Write an array of RGBA pixels at random locations.
246 void (*WriteMonocolorPixels
)( GLcontext
*ctx
,
247 GLuint n
, const GLint x
[], const GLint y
[],
248 const GLubyte mask
[] );
250 * Write an array of mono-RGBA pixels at random locations.
253 void (*WriteIndexSpan
)( GLcontext
*ctx
,
254 GLuint n
, GLint x
, GLint y
, const GLuint index
[],
255 const GLubyte mask
[] );
257 * Write a horizontal run of CI pixels.
260 void (*WriteMonoindexSpan
)( GLcontext
*ctx
,
261 GLuint n
, GLint x
, GLint y
,
262 const GLubyte mask
[] );
264 * Write a horizontal run of mono-CI pixels.
267 void (*WriteIndexPixels
)( GLcontext
*ctx
,
268 GLuint n
, const GLint x
[], const GLint y
[],
269 const GLuint index
[], const GLubyte mask
[] );
271 * Write a random array of CI pixels.
274 void (*WriteMonoindexPixels
)( GLcontext
*ctx
,
275 GLuint n
, const GLint x
[], const GLint y
[],
276 const GLubyte mask
[] );
278 * Write a random array of mono-CI pixels.
282 *** Functions to read pixels from frame buffer:
284 void (*ReadIndexSpan
)( GLcontext
*ctx
,
285 GLuint n
, GLint x
, GLint y
, GLuint index
[] );
287 * Read a horizontal run of color index pixels.
290 void (*ReadColorSpan
)( GLcontext
*ctx
,
291 GLuint n
, GLint x
, GLint y
,
292 GLubyte red
[], GLubyte green
[],
293 GLubyte blue
[], GLubyte alpha
[] );
295 * Read a horizontal run of RGBA pixels.
298 void (*ReadIndexPixels
)( GLcontext
*ctx
,
299 GLuint n
, const GLint x
[], const GLint y
[],
300 GLuint indx
[], const GLubyte mask
[] );
302 * Read a random array of CI pixels.
305 void (*ReadColorPixels
)( GLcontext
*ctx
,
306 GLuint n
, const GLint x
[], const GLint y
[],
307 GLubyte red
[], GLubyte green
[],
308 GLubyte blue
[], GLubyte alpha
[],
309 const GLubyte mask
[] );
311 * Read a random array of RGBA pixels.
315 /**********************************************************************
316 *** Optional functions: these functions may or may not be ***
317 *** implemented by the device driver. If the device driver ***
318 *** doesn't implement them it should never touch these pointers ***
319 *** since Mesa will either set them to NULL or point them at a ***
320 *** fall-back function. ***
321 **********************************************************************/
323 void (*Finish
)( GLcontext
*ctx
);
325 * Called whenever glFinish() is called.
328 void (*Flush
)( GLcontext
*ctx
);
330 * Called whenever glFlush() is called.
333 GLboolean (*IndexMask
)( GLcontext
*ctx
, GLuint mask
);
335 * Implements glIndexMask() if possible, else return GL_FALSE.
338 GLboolean (*ColorMask
)( GLcontext
*ctx
,
339 GLboolean rmask
, GLboolean gmask
,
340 GLboolean bmask
, GLboolean amask
);
342 * Implements glColorMask() if possible, else return GL_FALSE.
345 GLboolean (*LogicOp
)( GLcontext
*ctx
, GLenum op
);
347 * Implements glLogicOp() if possible, else return GL_FALSE.
350 void (*Dither
)( GLcontext
*ctx
, GLboolean enable
);
352 * Enable/disable dithering.
355 void (*Error
)( GLcontext
*ctx
);
357 * Called whenever an error is generated. ctx->ErrorValue contains
361 void (*NearFar
)( GLcontext
*ctx
, GLfloat nearVal
, GLfloat farVal
);
363 * Called from glFrustum and glOrtho to tell device driver the
364 * near and far clipping plane Z values. The 3Dfx driver, for example,
370 *** For supporting hardware Z buffers:
373 void (*AllocDepthBuffer
)( GLcontext
*ctx
);
375 * Called when the depth buffer must be allocated or possibly resized.
378 void (*ClearDepthBuffer
)( GLcontext
*ctx
);
380 * Clear the depth buffer to depth specified by CC.Depth.Clear value.
383 GLuint (*DepthTestSpan
)( GLcontext
*ctx
,
384 GLuint n
, GLint x
, GLint y
, const GLdepth z
[],
386 void (*DepthTestPixels
)( GLcontext
*ctx
,
387 GLuint n
, const GLint x
[], const GLint y
[],
388 const GLdepth z
[], GLubyte mask
[] );
390 * Apply the depth buffer test to an span/array of pixels and return
391 * an updated pixel mask. This function is not used when accelerated
392 * point, line, polygon functions are used.
395 void (*ReadDepthSpanFloat
)( GLcontext
*ctx
,
396 GLuint n
, GLint x
, GLint y
, GLfloat depth
[]);
397 void (*ReadDepthSpanInt
)( GLcontext
*ctx
,
398 GLuint n
, GLint x
, GLint y
, GLdepth depth
[] );
400 * Return depth values as integers for glReadPixels.
401 * Floats should be returned in the range [0,1].
402 * Ints (GLdepth) values should be in the range [0,MAXDEPTH].
406 void (*ClearColorAndDepth
)( GLcontext
*ctx
,
407 GLboolean all
, GLint x
, GLint y
,
408 GLint width
, GLint height
);
410 * If this function is implemented then it will be called when both the
411 * color and depth buffers are to be cleared.
416 *** Accelerated point, line, polygon, glDrawPixels and glBitmap functions:
419 points_func PointsFunc
;
421 * Called to draw an array of points.
426 * Called to draw a line segment.
429 triangle_func TriangleFunc
;
431 * Called to draw a filled triangle.
436 * Called to draw a filled quadrilateral.
441 * Called to draw a filled, screen-aligned 2-D rectangle.
444 GLboolean (*DrawPixels
)( GLcontext
*ctx
,
445 GLint x
, GLint y
, GLsizei width
, GLsizei height
,
446 GLenum format
, GLenum type
, GLboolean packed
,
447 const GLvoid
*pixels
);
449 * Called from glDrawPixels().
452 GLboolean (*Bitmap
)( GLcontext
*ctx
, GLsizei width
, GLsizei height
,
453 GLfloat xorig
, GLfloat yorig
,
454 GLfloat xmove
, GLfloat ymove
,
455 const struct gl_image
*bitmap
);
457 * Called from glBitmap().
460 void (*Begin
)( GLcontext
*ctx
, GLenum mode
);
461 void (*End
)( GLcontext
*ctx
);
463 * These are called whenever glBegin() or glEnd() are called.
464 * The device driver may do some sort of window locking/unlocking here.
468 void (*RasterSetup
)( GLcontext
*ctx
, GLuint start
, GLuint end
);
470 * This function, if not NULL, is called whenever new window coordinates
471 * are put in the vertex buffer. The vertices in question are those n
472 * such that start <= n < end.
473 * The device driver can convert the window coords to its own specialized
474 * format. The 3Dfx driver uses this.
477 GLboolean (*RenderVB
)( GLcontext
*ctx
, GLboolean allDone
);
479 * This function allows the device driver to rasterize an entire
480 * buffer of primitives at once. See the gl_render_vb() function
481 * in vbrender.c for more details.
482 * Return GL_TRUE if vertex buffer successfully rendered.
483 * Return GL_FALSE if failure, let core Mesa render the vertex buffer.
487 *** Texture mapping functions:
490 void (*TexEnv
)( GLcontext
*ctx
, GLenum pname
, const GLfloat
*param
);
492 * Called whenever glTexEnv*() is called.
493 * Pname will be one of GL_TEXTURE_ENV_MODE or GL_TEXTURE_ENV_COLOR.
494 * If pname is GL_TEXTURE_ENV_MODE then param will be one
495 * of GL_MODULATE, GL_BLEND, GL_DECAL, or GL_REPLACE.
498 void (*TexImage
)( GLcontext
*ctx
, GLenum target
,
499 struct gl_texture_object
*tObj
, GLint level
,
500 GLint internalFormat
,
501 const struct gl_texture_image
*image
);
503 * Called whenever a texture object's image is changed.
504 * texObject is the number of the texture object being changed.
505 * level indicates the mipmap level.
506 * internalFormat is the format in which the texture is to be stored.
507 * image is a pointer to a gl_texture_image struct which contains
508 * the actual image data.
511 void (*TexSubImage
)( GLcontext
*ctx
, GLenum target
,
512 struct gl_texture_object
*tObj
, GLint level
,
513 GLint xoffset
, GLint yoffset
,
514 GLsizei width
, GLsizei height
,
515 GLint internalFormat
,
516 const struct gl_texture_image
*image
);
518 * Called from glTexSubImage() to define a sub-region of a texture.
521 void (*TexParameter
)( GLcontext
*ctx
, GLenum target
,
522 struct gl_texture_object
*tObj
,
523 GLenum pname
, const GLfloat
*params
);
525 * Called whenever glTexParameter*() is called.
526 * target is GL_TEXTURE_1D or GL_TEXTURE_2D
527 * texObject is the texture object to modify
528 * pname is one of GL_TEXTURE_MIN_FILTER, GL_TEXTURE_MAG_FILTER,
529 * GL_TEXTURE_WRAP_S, GL_TEXTURE_WRAP_T, or GL_TEXTURE_BORDER_COLOR.
530 * params is dependant on pname. See man glTexParameter.
533 void (*BindTexture
)( GLcontext
*ctx
, GLenum target
,
534 struct gl_texture_object
*tObj
);
536 * Called whenever glBindTexture() is called. This specifies which
537 * texture is to be the current one.
540 void (*DeleteTexture
)( GLcontext
*ctx
, struct gl_texture_object
*tObj
);
542 * Called when a texture object can be deallocated.
545 void (*UpdateTexturePalette
)( GLcontext
*ctx
,
546 struct gl_texture_object
*tObj
);
548 * Called when the texture's color lookup table is changed.
549 * If tObj is NULL then the shared texture palette ctx->Texture.Palette