1 /* $Id: dd.h,v 1.15 1997/12/05 04:38:28 brianp Exp $ */ 2 3 /* 4 * Mesa 3-D graphics library 5 * Version: 2.6 6 * Copyright (C) 1995-1997 Brian Paul 7 * 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. 12 * 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. 17 * 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. 21 */ 22 23 24 /* 25 * $Log: dd.h,v $ 26 * Revision 1.15 1997/12/05 04:38:28 brianp 27 * added ClearColorAndDepth() function pointer (David Bucciarelli) 28 * 29 * Revision 1.14 1997/11/25 03:39:41 brianp 30 * added TexSubImage() function pointer (David Bucciarelli) 31 * 32 * Revision 1.13 1997/10/29 02:23:54 brianp 33 * added UseGlobalTexturePalette() dd function (David Bucciarelli v20 3dfx) 34 * 35 * Revision 1.12 1997/10/16 02:27:53 brianp 36 * more comments 37 * 38 * Revision 1.11 1997/10/14 00:07:40 brianp 39 * added DavidB's fxmesa v19 changes 40 * 41 * Revision 1.10 1997/09/29 23:26:50 brianp 42 * new texture functions 43 * 44 * Revision 1.9 1997/04/29 01:31:07 brianp 45 * added RasterSetup() function to device driver 46 * 47 * Revision 1.8 1997/04/20 19:47:27 brianp 48 * added RenderVB to device driver 49 * 50 * Revision 1.7 1997/04/20 16:31:08 brianp 51 * added NearFar device driver function 52 * 53 * Revision 1.6 1997/04/12 12:27:31 brianp 54 * added QuadFunc and RectFunc 55 * 56 * Revision 1.5 1997/03/21 01:57:07 brianp 57 * added RendererString() function 58 * 59 * Revision 1.4 1997/02/10 19:22:47 brianp 60 * added device driver Error() function 61 * 62 * Revision 1.3 1997/01/16 03:34:33 brianp 63 * added preliminary texture mapping functions and cleaned up documentation 64 * 65 * Revision 1.2 1996/11/13 03:51:59 brianp 66 * updated comments 67 * 68 * Revision 1.1 1996/09/13 01:38:16 brianp 69 * Initial revision 70 * 71 */ 72 73 74 #ifndef DD_INCLUDED 75 #define DD_INCLUDED 76 77 78 /* THIS FILE ONLY INCLUDED BY types.h !!!!! */ 79 80 81 /* 82 * Device Driver (DD) interface 83 * 84 * 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. 92 * 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. 99 * 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. 104 * 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. 111 * 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 115 * for an example. 116 * 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. 119 * 120 * 121 * Look below in the dd_function_table struct definition for descriptions 122 * of each device driver function. 123 * 124 * 125 * In the future more function pointers may be added for glReadPixels 126 * glCopyPixels, etc. 127 * 128 * 129 * Notes: 130 * ------ 131 * RGBA = red/green/blue/alpha 132 * CI = color index (color mapped mode) 133 * mono = all pixels have the same color or index 134 * 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(). 139 * 140 * IN ALL CASES: 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 143 * 144 */ 145 146 147 148 149 150 /* 151 * Device Driver function table. 152 */ 153 struct dd_function_table { 154 155 /********************************************************************** 156 *** Mandatory functions: these functions must be implemented by *** 157 *** every device driver. *** 158 **********************************************************************/ 159 160 const char * (*RendererString)(void); 161 /* 162 * Return a string which uniquely identifies this device driver. 163 * The string should contain no whitespace. Examples: "X11" "OffScreen" 164 * "MSWindows" "SVGA". 165 */ 166 167 void (*UpdateState)( GLcontext *ctx ); 168 /* 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). 172 */ 173 174 void (*ClearIndex)( GLcontext *ctx, GLuint index ); 175 /* 176 * Called whenever glClearIndex() is called. Set the index for clearing 177 * the color buffer. 178 */ 179 180 void (*ClearColor)( GLcontext *ctx, GLubyte red, GLubyte green, 181 GLubyte blue, GLubyte alpha ); 182 /* 183 * Called whenever glClearColor() is called. Set the color for clearing 184 * the color buffer. 185 */ 186 187 void (*Clear)( GLcontext *ctx, 188 GLboolean all, GLint x, GLint y, GLint width, GLint height ); 189 /* 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). 192 */ 193 194 void (*Index)( GLcontext *ctx, GLuint index ); 195 /* 196 * Sets current color index for drawing flat-shaded primitives. 197 */ 198 199 void (*Color)( GLcontext *ctx, 200 GLubyte red, GLubyte green, GLubyte glue, GLubyte alpha ); 201 /* 202 * Sets current color for drawing flat-shaded primitives. 203 */ 204 205 GLboolean (*SetBuffer)( GLcontext *ctx, GLenum mode ); 206 /* 207 * Selects either the front or back color buffer for reading and writing. 208 * mode is either GL_FRONT or GL_BACK. 209 */ 210 211 void (*GetBufferSize)( GLcontext *ctx, 212 GLuint *width, GLuint *height ); 213 /* 214 * Returns the width and height of the current color buffer. 215 */ 216 217 218 /*** 219 *** Functions for writing pixels to the frame buffer: 220 ***/ 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[] ); 226 /* 227 * Write a horizontal run of RGBA pixels. 228 */ 229 230 void (*WriteMonocolorSpan)( GLcontext *ctx, 231 GLuint n, GLint x, GLint y, 232 const GLubyte mask[] ); 233 /* 234 * Write a horizontal run of mono-RGBA pixels. 235 */ 236 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[] ); 242 /* 243 * Write an array of RGBA pixels at random locations. 244 */ 245 246 void (*WriteMonocolorPixels)( GLcontext *ctx, 247 GLuint n, const GLint x[], const GLint y[], 248 const GLubyte mask[] ); 249 /* 250 * Write an array of mono-RGBA pixels at random locations. 251 */ 252 253 void (*WriteIndexSpan)( GLcontext *ctx, 254 GLuint n, GLint x, GLint y, const GLuint index[], 255 const GLubyte mask[] ); 256 /* 257 * Write a horizontal run of CI pixels. 258 */ 259 260 void (*WriteMonoindexSpan)( GLcontext *ctx, 261 GLuint n, GLint x, GLint y, 262 const GLubyte mask[] ); 263 /* 264 * Write a horizontal run of mono-CI pixels. 265 */ 266 267 void (*WriteIndexPixels)( GLcontext *ctx, 268 GLuint n, const GLint x[], const GLint y[], 269 const GLuint index[], const GLubyte mask[] ); 270 /* 271 * Write a random array of CI pixels. 272 */ 273 274 void (*WriteMonoindexPixels)( GLcontext *ctx, 275 GLuint n, const GLint x[], const GLint y[], 276 const GLubyte mask[] ); 277 /* 278 * Write a random array of mono-CI pixels. 279 */ 280 281 /*** 282 *** Functions to read pixels from frame buffer: 283 ***/ 284 void (*ReadIndexSpan)( GLcontext *ctx, 285 GLuint n, GLint x, GLint y, GLuint index[] ); 286 /* 287 * Read a horizontal run of color index pixels. 288 */ 289 290 void (*ReadColorSpan)( GLcontext *ctx, 291 GLuint n, GLint x, GLint y, 292 GLubyte red[], GLubyte green[], 293 GLubyte blue[], GLubyte alpha[] ); 294 /* 295 * Read a horizontal run of RGBA pixels. 296 */ 297 298 void (*ReadIndexPixels)( GLcontext *ctx, 299 GLuint n, const GLint x[], const GLint y[], 300 GLuint indx[], const GLubyte mask[] ); 301 /* 302 * Read a random array of CI pixels. 303 */ 304 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[] ); 310 /* 311 * Read a random array of RGBA pixels. 312 */ 313 314 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 **********************************************************************/ 322 323 void (*Finish)( GLcontext *ctx ); 324 /* 325 * Called whenever glFinish() is called. 326 */ 327 328 void (*Flush)( GLcontext *ctx ); 329 /* 330 * Called whenever glFlush() is called. 331 */ 332 333 GLboolean (*IndexMask)( GLcontext *ctx, GLuint mask ); 334 /* 335 * Implements glIndexMask() if possible, else return GL_FALSE. 336 */ 337 338 GLboolean (*ColorMask)( GLcontext *ctx, 339 GLboolean rmask, GLboolean gmask, 340 GLboolean bmask, GLboolean amask ); 341 /* 342 * Implements glColorMask() if possible, else return GL_FALSE. 343 */ 344 345 GLboolean (*LogicOp)( GLcontext *ctx, GLenum op ); 346 /* 347 * Implements glLogicOp() if possible, else return GL_FALSE. 348 */ 349 350 void (*Dither)( GLcontext *ctx, GLboolean enable ); 351 /* 352 * Enable/disable dithering. 353 */ 354 355 void (*Error)( GLcontext *ctx ); 356 /* 357 * Called whenever an error is generated. ctx->ErrorValue contains 358 * the error value. 359 */ 360 361 void (*NearFar)( GLcontext *ctx, GLfloat nearVal, GLfloat farVal ); 362 /* 363 * Called from glFrustum and glOrtho to tell device driver the 364 * near and far clipping plane Z values. The 3Dfx driver, for example, 365 * uses this. 366 */ 367 368 369 /*** 370 *** For supporting hardware Z buffers: 371 ***/ 372 373 void (*AllocDepthBuffer)( GLcontext *ctx ); 374 /* 375 * Called when the depth buffer must be allocated or possibly resized. 376 */ 377 378 void (*ClearDepthBuffer)( GLcontext *ctx ); 379 /* 380 * Clear the depth buffer to depth specified by CC.Depth.Clear value. 381 */ 382 383 GLuint (*DepthTestSpan)( GLcontext *ctx, 384 GLuint n, GLint x, GLint y, const GLdepth z[], 385 GLubyte mask[] ); 386 void (*DepthTestPixels)( GLcontext *ctx, 387 GLuint n, const GLint x[], const GLint y[], 388 const GLdepth z[], GLubyte mask[] ); 389 /* 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. 393 */ 394 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[] ); 399 /* 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]. 403 */ 404 405 406 void (*ClearColorAndDepth)( GLcontext *ctx, 407 GLboolean all, GLint x, GLint y, 408 GLint width, GLint height ); 409 /* 410 * If this function is implemented then it will be called when both the 411 * color and depth buffers are to be cleared. 412 */ 413 414 415 /*** 416 *** Accelerated point, line, polygon, glDrawPixels and glBitmap functions: 417 ***/ 418 419 points_func PointsFunc; 420 /* 421 * Called to draw an array of points. 422 */ 423 424 line_func LineFunc; 425 /* 426 * Called to draw a line segment. 427 */ 428 429 triangle_func TriangleFunc; 430 /* 431 * Called to draw a filled triangle. 432 */ 433 434 quad_func QuadFunc; 435 /* 436 * Called to draw a filled quadrilateral. 437 */ 438 439 rect_func RectFunc; 440 /* 441 * Called to draw a filled, screen-aligned 2-D rectangle. 442 */ 443 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 ); 448 /* 449 * Called from glDrawPixels(). 450 */ 451 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 ); 456 /* 457 * Called from glBitmap(). 458 */ 459 460 void (*Begin)( GLcontext *ctx, GLenum mode ); 461 void (*End)( GLcontext *ctx ); 462 /* 463 * These are called whenever glBegin() or glEnd() are called. 464 * The device driver may do some sort of window locking/unlocking here. 465 */ 466 467 468 void (*RasterSetup)( GLcontext *ctx, GLuint start, GLuint end ); 469 /* 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. 475 */ 476 477 GLboolean (*RenderVB)( GLcontext *ctx, GLboolean allDone ); 478 /* 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. 484 */ 485 486 /*** 487 *** Texture mapping functions: 488 ***/ 489 490 void (*TexEnv)( GLcontext *ctx, GLenum pname, const GLfloat *param ); 491 /* 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. 496 */ 497 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 ); 502 /* 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. 509 */ 510 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 ); 517 /* 518 * Called from glTexSubImage() to define a sub-region of a texture. 519 */ 520 521 void (*TexParameter)( GLcontext *ctx, GLenum target, 522 struct gl_texture_object *tObj, 523 GLenum pname, const GLfloat *params ); 524 /* 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. 531 */ 532 533 void (*BindTexture)( GLcontext *ctx, GLenum target, 534 struct gl_texture_object *tObj ); 535 /* 536 * Called whenever glBindTexture() is called. This specifies which 537 * texture is to be the current one. 538 */ 539 540 void (*DeleteTexture)( GLcontext *ctx, struct gl_texture_object *tObj ); 541 /* 542 * Called when a texture object can be deallocated. 543 */ 544 545 void (*UpdateTexturePalette)( GLcontext *ctx, 546 struct gl_texture_object *tObj ); 547 /* 548 * Called when the texture's color lookup table is changed. 549 * If tObj is NULL then the shared texture palette ctx->Texture.Palette 550 * was changed. 551 */ 552 }; 553 554 555 556 #endif 557 558