src/mesa/swrast/swrast.h

   1 /* $Id: swrast.h,v 1.24 2002/04/19 14:05:50 brianp Exp $ */
   2
   3 /*
   4  * Mesa 3-D graphics library
   5  * Version:  4.1
   6  *
   7  * Copyright (C) 1999-2002  Brian Paul   All Rights Reserved.
   8  *
   9  * Permission is hereby granted, free of charge, to any person obtaining a
  10  * copy of this software and associated documentation files (the "Software"),
  11  * to deal in the Software without restriction, including without limitation
  12  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  13  * and/or sell copies of the Software, and to permit persons to whom the
  14  * Software is furnished to do so, subject to the following conditions:
  15  *
  16  * The above copyright notice and this permission notice shall be included
  17  * in all copies or substantial portions of the Software.
  18  *
  19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  20  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  21  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  22  * BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  23  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  24  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  25  *
  26  */
  27
  28 /**
  29  * \file swrast/swrast.h
  30  * \brief Defines basic structures for sw_rasterizer.
  31  * \author Keith Whitwell <keithw@valinux.com>
  32  */
  33
  34 #ifndef SWRAST_H
  35 #define SWRAST_H
  36
  37 #include "mtypes.h"
  38
  39 /**
  40  * \struct SWvertex
  41  * \brief Data-structure to handle vertices in the software rasterizer.
  42  *
  43  * The software rasterizer now uses this format for vertices.  Thus a
  44  * 'RasterSetup' stage or other translation is required between the
  45  * tnl module and the swrast rasterization functions.  This serves to
  46  * isolate the swrast module from the internals of the tnl module, and
  47  * improve its usefulness as a fallback mechanism for hardware
  48  * drivers.
  49  *
  50  * Full software drivers:
  51  *   - Register the rastersetup and triangle functions from
  52  *     utils/software_helper.
  53  *   - On statechange, update the rasterization pointers in that module.
  54  *
  55  * Rasterization hardware drivers:
  56  *   - Keep native rastersetup.
  57  *   - Implement native twoside,offset and unfilled triangle setup.
  58  *   - Implement a translator from native vertices to swrast vertices.
  59  *   - On partial fallback (mix of accelerated and unaccelerated
  60  *   prims), call a pass-through function which translates native
  61  *   vertices to SWvertices and calls the appropriate swrast function.
  62  *   - On total fallback (vertex format insufficient for state or all
  63  *     primitives unaccelerated), hook in swrast_setup instead.
  64  */
  65 typedef struct {
  66    GLfloat win[4];
  67    GLfloat texcoord[MAX_TEXTURE_UNITS][4];
  68    GLchan color[4];
  69    GLchan specular[4];
  70    GLfloat fog;
  71    GLuint index;
  72    GLfloat pointSize;
  73 } SWvertex;
  74
  75
  76 /**
  77  * \struct sw_span
  78  * \brief Contains data for either a horizontal line or a set of
  79  * pixels that are passed through a pipeline of functions before being
  80  * drawn.
  81  *
  82  * The sw_span structure describes the colors, Z, fogcoord, texcoords,
  83  * etc for either a horizontal run or a set of independent pixels.  We
  84  * can either specify a base/step to indicate interpolated values, or
  85  * fill in arrays of values.  The interpMask and arrayMask bitfields
  86  * indicate which are active.
  87  *
  88  * With this structure it's easy to hand-off span rasterization to
  89  * subroutines instead of doing it all inline in the triangle functions
  90  * like we used to do.
  91  * It also cleans up the local variable namespace a great deal.
  92  *
  93  * It would be interesting to experiment with multiprocessor rasterization
  94  * with this structure.  The triangle rasterizer could simply emit a
  95  * stream of these structures which would be consumed by one or more
  96  * span-processing threads which could run in parallel.
  97  */
  98
  99
 100 /* Values for interpMask and arrayMask */
 101 #define SPAN_RGBA         0x001
 102 #define SPAN_SPEC         0x002
 103 #define SPAN_INDEX        0x004
 104 #define SPAN_Z            0x008
 105 #define SPAN_FOG          0x010
 106 #define SPAN_TEXTURE      0x020
 107 #define SPAN_INT_TEXTURE  0x040
 108 #define SPAN_LAMBDA       0x080
 109 #define SPAN_COVERAGE     0x100
 110 #define SPAN_FLAT         0x200  /* flat shading? */
 111 #define SPAN_XY           0x400  /* arrayMask only - for xArray, yArray */
 112 #define SPAN_MASK         0x800  /* arrayMask only */
 113
 114
 115 struct sw_span {
 116    GLint x, y;
 117
 118    /** Only need to process pixels between start <= i < end */
 119    /** At this time, start is always zero. */
 120    GLuint start, end;
 121
 122    /** This flag indicates that mask[] array is effectively filled with ones */
 123    GLboolean writeAll;
 124
 125    /** either GL_POLYGON, GL_LINE, GL_POLYGON, GL_BITMAP */
 126    GLenum primitive;
 127
 128    /**
 129     * This bitmask (of SPAN_* flags) indicates which of the x/xStep
 130     * variables are relevant.
 131     */
 132    GLuint interpMask;
 133
 134 #if CHAN_TYPE == GL_FLOAT
 135    GLfloat red, redStep;
 136    GLfloat green, greenStep;
 137    GLfloat blue, blueStep;
 138    GLfloat alpha, alphaStep;
 139    GLfloat specRed, specRedStep;
 140    GLfloat specGreen, specGreenStep;
 141    GLfloat specBlue, specBlueStep;
 142 #else /* CHAN_TYPE == GL_UNSIGNED_BYTE or GL_UNSIGNED SHORT */
 143    GLfixed red, redStep;
 144    GLfixed green, greenStep;
 145    GLfixed blue, blueStep;
 146    GLfixed alpha, alphaStep;
 147    GLfixed specRed, specRedStep;
 148    GLfixed specGreen, specGreenStep;
 149    GLfixed specBlue, specBlueStep;
 150 #endif
 151    GLfixed index, indexStep;
 152    GLfixed z, zStep;
 153    GLfloat fog, fogStep;
 154    GLfloat tex[MAX_TEXTURE_UNITS][4];
 155    GLfloat texStepX[MAX_TEXTURE_UNITS][4];
 156    GLfloat texStepY[MAX_TEXTURE_UNITS][4];
 157    GLfixed intTex[2], intTexStep[2];
 158
 159    /**
 160     * This bitmask (of SPAN_* flags) indicates which of the fragment arrays
 161     * are relevant.
 162     */
 163    GLuint arrayMask;
 164
 165    /**
 166     * Arrays of fragment values.  These will either be computed from the
 167     * x/xStep values above or filled in by glDraw/CopyPixels, etc.
 168     */
 169    union {
 170       GLchan rgb[MAX_WIDTH][3];
 171       GLchan rgba[MAX_WIDTH][4];
 172       GLuint index[MAX_WIDTH];
 173    } color;
 174    GLchan  specArray[MAX_WIDTH][4];
 175    GLint   xArray[MAX_WIDTH];  /**< X/Y used for point/line rendering only */
 176    GLint   yArray[MAX_WIDTH];  /**< X/Y used for point/line rendering only */
 177    GLdepth zArray[MAX_WIDTH];
 178    GLfloat fogArray[MAX_WIDTH];
 179    GLfloat texcoords[MAX_TEXTURE_UNITS][MAX_WIDTH][4];
 180    GLfloat lambda[MAX_TEXTURE_UNITS][MAX_WIDTH];
 181    GLfloat coverage[MAX_WIDTH];
 182
 183   /** This mask indicates if fragment is alive or culled */
 184    GLubyte mask[MAX_WIDTH];
 185 };
 186
 187
 188 #define INIT_SPAN(S, PRIMITIVE, END, INTERP_MASK, ARRAY_MASK)  \
 189 do {                              \
 190    S->primitive = (PRIMITIVE);     \
 191    S->interpMask = (INTERP_MASK);  \
 192    S->arrayMask = (ARRAY_MASK);    \
 193    S->start = 0;                   \
 194    S->end = (END);                 \
 195 } while (0)
 196
 197
 198
 199 struct swrast_device_driver;
 200
 201
 202 /* These are the public-access functions exported from swrast.
 203  */
 204 extern void
 205 _swrast_alloc_buffers( GLframebuffer *buffer );
 206
 207 extern GLboolean
 208 _swrast_CreateContext( GLcontext *ctx );
 209
 210 extern void
 211 _swrast_DestroyContext( GLcontext *ctx );
 212
 213 /* Get a (non-const) reference to the device driver struct for swrast.
 214  */
 215 extern struct swrast_device_driver *
 216 _swrast_GetDeviceDriverReference( GLcontext *ctx );
 217
 218 extern void
 219 _swrast_Bitmap( GLcontext *ctx,
 220                 GLint px, GLint py,
 221                 GLsizei width, GLsizei height,
 222                 const struct gl_pixelstore_attrib *unpack,
 223                 const GLubyte *bitmap );
 224
 225 extern void
 226 _swrast_CopyPixels( GLcontext *ctx,
 227                     GLint srcx, GLint srcy,
 228                     GLint destx, GLint desty,
 229                     GLsizei width, GLsizei height,
 230                     GLenum type );
 231
 232 extern void
 233 _swrast_DrawPixels( GLcontext *ctx,
 234                     GLint x, GLint y,
 235                     GLsizei width, GLsizei height,
 236                     GLenum format, GLenum type,
 237                     const struct gl_pixelstore_attrib *unpack,
 238                     const GLvoid *pixels );
 239
 240 extern void
 241 _swrast_ReadPixels( GLcontext *ctx,
 242                     GLint x, GLint y, GLsizei width, GLsizei height,
 243                     GLenum format, GLenum type,
 244                     const struct gl_pixelstore_attrib *unpack,
 245                     GLvoid *pixels );
 246
 247 extern void
 248 _swrast_Clear( GLcontext *ctx, GLbitfield mask, GLboolean all,
 249                GLint x, GLint y, GLint width, GLint height );
 250
 251 extern void
 252 _swrast_Accum( GLcontext *ctx, GLenum op,
 253                GLfloat value, GLint xpos, GLint ypos,
 254                GLint width, GLint height );
 255
 256
 257 /* Reset the stipple counter
 258  */
 259 extern void
 260 _swrast_ResetLineStipple( GLcontext *ctx );
 261
 262 /* These will always render the correct point/line/triangle for the
 263  * current state.
 264  *
 265  * For flatshaded primitives, the provoking vertex is the final one.
 266  */
 267 extern void
 268 _swrast_Point( GLcontext *ctx, const SWvertex *v );
 269
 270 extern void
 271 _swrast_Line( GLcontext *ctx, const SWvertex *v0, const SWvertex *v1 );
 272
 273 extern void
 274 _swrast_Triangle( GLcontext *ctx, const SWvertex *v0,
 275                   const SWvertex *v1, const SWvertex *v2 );
 276
 277 extern void
 278 _swrast_Quad( GLcontext *ctx,
 279               const SWvertex *v0, const SWvertex *v1,
 280               const SWvertex *v2,  const SWvertex *v3);
 281
 282 extern void
 283 _swrast_flush( GLcontext *ctx );
 284
 285
 286 /* Tell the software rasterizer about core state changes.
 287  */
 288 extern void
 289 _swrast_InvalidateState( GLcontext *ctx, GLuint new_state );
 290
 291 /* Configure software rasterizer to match hardware rasterizer characteristics:
 292  */
 293 extern void
 294 _swrast_allow_vertex_fog( GLcontext *ctx, GLboolean value );
 295
 296 extern void
 297 _swrast_allow_pixel_fog( GLcontext *ctx, GLboolean value );
 298
 299 /* Debug:
 300  */
 301 extern void
 302 _swrast_print_vertex( GLcontext *ctx, const SWvertex *v );
 303
 304
 305 /*
 306  * Imaging fallbacks (a better solution should be found, perhaps
 307  * moving all the imaging fallback code to a new module)
 308  */
 309 extern void
 310 _swrast_CopyConvolutionFilter2D(GLcontext *ctx, GLenum target,
 311                                 GLenum internalFormat,
 312                                 GLint x, GLint y, GLsizei width,
 313                                 GLsizei height);
 314 extern void
 315 _swrast_CopyConvolutionFilter1D(GLcontext *ctx, GLenum target,
 316                                 GLenum internalFormat,
 317                                 GLint x, GLint y, GLsizei width);
 318 extern void
 319 _swrast_CopyColorSubTable( GLcontext *ctx,GLenum target, GLsizei start,
 320                            GLint x, GLint y, GLsizei width);
 321 extern void
 322 _swrast_CopyColorTable( GLcontext *ctx,
 323                         GLenum target, GLenum internalformat,
 324                         GLint x, GLint y, GLsizei width);
 325
 326
 327 /*
 328  * Texture fallbacks, Brian Paul.  Could also live in a new module
 329  * with the rest of the texture store fallbacks?
 330  */
 331 extern void
 332 _swrast_copy_teximage1d(GLcontext *ctx, GLenum target, GLint level,
 333                         GLenum internalFormat,
 334                         GLint x, GLint y, GLsizei width, GLint border);
 335
 336 extern void
 337 _swrast_copy_teximage2d(GLcontext *ctx, GLenum target, GLint level,
 338                         GLenum internalFormat,
 339                         GLint x, GLint y, GLsizei width, GLsizei height,
 340                         GLint border);
 341
 342
 343 extern void
 344 _swrast_copy_texsubimage1d(GLcontext *ctx, GLenum target, GLint level,
 345                            GLint xoffset, GLint x, GLint y, GLsizei width);
 346
 347 extern void
 348 _swrast_copy_texsubimage2d(GLcontext *ctx,
 349                            GLenum target, GLint level,
 350                            GLint xoffset, GLint yoffset,
 351                            GLint x, GLint y, GLsizei width, GLsizei height);
 352
 353 extern void
 354 _swrast_copy_texsubimage3d(GLcontext *ctx,
 355                            GLenum target, GLint level,
 356                            GLint xoffset, GLint yoffset, GLint zoffset,
 357                            GLint x, GLint y, GLsizei width, GLsizei height);
 358
 359
 360
 361 /* The driver interface for the software rasterizer.  Unless otherwise
 362  * noted, all functions are mandatory.
 363  */
 364 struct swrast_device_driver {
 365
 366    void (*SetReadBuffer)( GLcontext *ctx, GLframebuffer *colorBuffer,
 367                           GLenum buffer );
 368    /*
 369     * Specifies the current buffer for span/pixel reading.
 370     * colorBuffer will be one of:
 371     *    GL_FRONT_LEFT - this buffer always exists
 372     *    GL_BACK_LEFT - when double buffering
 373     *    GL_FRONT_RIGHT - when using stereo
 374     *    GL_BACK_RIGHT - when using stereo and double buffering
 375     */
 376
 377
 378    /***
 379     *** Functions for synchronizing access to the framebuffer:
 380     ***/
 381
 382    void (*SpanRenderStart)(GLcontext *ctx);
 383    void (*SpanRenderFinish)(GLcontext *ctx);
 384    /* OPTIONAL.
 385     *
 386     * Called before and after all rendering operations, including DrawPixels,
 387     * ReadPixels, Bitmap, span functions, and CopyTexImage, etc commands.
 388     * These are a suitable place for grabbing/releasing hardware locks.
 389     *
 390     * NOTE: The swrast triangle/line/point routines *DO NOT* call
 391     * these functions.  Locking in that case must be organized by the
 392     * driver by other mechanisms.
 393     */
 394
 395    /***
 396     *** Functions for writing pixels to the frame buffer:
 397     ***/
 398
 399    void (*WriteRGBASpan)( const GLcontext *ctx,
 400                           GLuint n, GLint x, GLint y,
 401                           CONST GLchan rgba[][4], const GLubyte mask[] );
 402    void (*WriteRGBSpan)( const GLcontext *ctx,
 403                          GLuint n, GLint x, GLint y,
 404                          CONST GLchan rgb[][3], const GLubyte mask[] );
 405    /* Write a horizontal run of RGBA or RGB pixels.
 406     * If mask is NULL, draw all pixels.
 407     * If mask is not null, only draw pixel [i] when mask [i] is true.
 408     */
 409
 410    void (*WriteMonoRGBASpan)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 411                               const GLchan color[4], const GLubyte mask[] );
 412    /* Write a horizontal run of RGBA pixels all with the same color.
 413     */
 414
 415    void (*WriteRGBAPixels)( const GLcontext *ctx,
 416                             GLuint n, const GLint x[], const GLint y[],
 417                             CONST GLchan rgba[][4], const GLubyte mask[] );
 418    /* Write array of RGBA pixels at random locations.
 419     */
 420
 421    void (*WriteMonoRGBAPixels)( const GLcontext *ctx,
 422                                 GLuint n, const GLint x[], const GLint y[],
 423                                 const GLchan color[4], const GLubyte mask[] );
 424    /* Write an array of mono-RGBA pixels at random locations.
 425     */
 426
 427    void (*WriteCI32Span)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 428                           const GLuint index[], const GLubyte mask[] );
 429    void (*WriteCI8Span)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 430                          const GLubyte index[], const GLubyte mask[] );
 431    /* Write a horizontal run of CI pixels.  One function is for 32bpp
 432     * indexes and the other for 8bpp pixels (the common case).  You mus
 433     * implement both for color index mode.
 434     */
 435
 436    void (*WriteMonoCISpan)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 437                             GLuint colorIndex, const GLubyte mask[] );
 438    /* Write a horizontal run of color index pixels using the color index
 439     * last specified by the Index() function.
 440     */
 441
 442    void (*WriteCI32Pixels)( const GLcontext *ctx,
 443                             GLuint n, const GLint x[], const GLint y[],
 444                             const GLuint index[], const GLubyte mask[] );
 445    /*
 446     * Write a random array of CI pixels.
 447     */
 448
 449    void (*WriteMonoCIPixels)( const GLcontext *ctx,
 450                               GLuint n, const GLint x[], const GLint y[],
 451                               GLuint colorIndex, const GLubyte mask[] );
 452    /* Write a random array of color index pixels using the color index
 453     * last specified by the Index() function.
 454     */
 455
 456
 457    /***
 458     *** Functions to read pixels from frame buffer:
 459     ***/
 460
 461    void (*ReadCI32Span)( const GLcontext *ctx,
 462                          GLuint n, GLint x, GLint y, GLuint index[] );
 463    /* Read a horizontal run of color index pixels.
 464     */
 465
 466    void (*ReadRGBASpan)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 467                          GLchan rgba[][4] );
 468    /* Read a horizontal run of RGBA pixels.
 469     */
 470
 471    void (*ReadCI32Pixels)( const GLcontext *ctx,
 472                            GLuint n, const GLint x[], const GLint y[],
 473                            GLuint indx[], const GLubyte mask[] );
 474    /* Read a random array of CI pixels.
 475     */
 476
 477    void (*ReadRGBAPixels)( const GLcontext *ctx,
 478                            GLuint n, const GLint x[], const GLint y[],
 479                            GLchan rgba[][4], const GLubyte mask[] );
 480    /* Read a random array of RGBA pixels.
 481     */
 482
 483
 484
 485    /***
 486     *** For supporting hardware Z buffers:
 487     *** Either ALL or NONE of these functions must be implemented!
 488     *** NOTE that Each depth value is a 32-bit GLuint.  If the depth
 489     *** buffer is less than 32 bits deep then the extra upperbits are zero.
 490     ***/
 491
 492    void (*WriteDepthSpan)( GLcontext *ctx, GLuint n, GLint x, GLint y,
 493                            const GLdepth depth[], const GLubyte mask[] );
 494    /* Write a horizontal span of values into the depth buffer.  Only write
 495     * depth[i] value if mask[i] is nonzero.
 496     */
 497
 498    void (*ReadDepthSpan)( GLcontext *ctx, GLuint n, GLint x, GLint y,
 499                           GLdepth depth[] );
 500    /* Read a horizontal span of values from the depth buffer.
 501     */
 502
 503
 504    void (*WriteDepthPixels)( GLcontext *ctx, GLuint n,
 505                              const GLint x[], const GLint y[],
 506                              const GLdepth depth[], const GLubyte mask[] );
 507    /* Write an array of randomly positioned depth values into the
 508     * depth buffer.  Only write depth[i] value if mask[i] is nonzero.
 509     */
 510
 511    void (*ReadDepthPixels)( GLcontext *ctx, GLuint n,
 512                             const GLint x[], const GLint y[],
 513                             GLdepth depth[] );
 514    /* Read an array of randomly positioned depth values from the depth buffer.
 515     */
 516
 517
 518
 519    /***
 520     *** For supporting hardware stencil buffers:
 521     *** Either ALL or NONE of these functions must be implemented!
 522     ***/
 523
 524    void (*WriteStencilSpan)( GLcontext *ctx, GLuint n, GLint x, GLint y,
 525                              const GLstencil stencil[], const GLubyte mask[] );
 526    /* Write a horizontal span of stencil values into the stencil buffer.
 527     * If mask is NULL, write all stencil values.
 528     * Else, only write stencil[i] if mask[i] is non-zero.
 529     */
 530
 531    void (*ReadStencilSpan)( GLcontext *ctx, GLuint n, GLint x, GLint y,
 532                             GLstencil stencil[] );
 533    /* Read a horizontal span of stencil values from the stencil buffer.
 534     */
 535
 536    void (*WriteStencilPixels)( GLcontext *ctx, GLuint n,
 537                                const GLint x[], const GLint y[],
 538                                const GLstencil stencil[],
 539                                const GLubyte mask[] );
 540    /* Write an array of stencil values into the stencil buffer.
 541     * If mask is NULL, write all stencil values.
 542     * Else, only write stencil[i] if mask[i] is non-zero.
 543     */
 544
 545    void (*ReadStencilPixels)( GLcontext *ctx, GLuint n,
 546                               const GLint x[], const GLint y[],
 547                               GLstencil stencil[] );
 548    /* Read an array of stencil values from the stencil buffer.
 549     */
 550 };
 551
 552
 553
 554 #endif