src/mesa/swrast/swrast.h

   1
   2 /*
   3  * Mesa 3-D graphics library
   4  * Version:  5.1
   5  *
   6  * Copyright (C) 1999-2003  Brian Paul   All Rights Reserved.
   7  *
   8  * Permission is hereby granted, free of charge, to any person obtaining a
   9  * copy of this software and associated documentation files (the "Software"),
  10  * to deal in the Software without restriction, including without limitation
  11  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  12  * and/or sell copies of the Software, and to permit persons to whom the
  13  * Software is furnished to do so, subject to the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included
  16  * in all copies or substantial portions of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  19  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  21  * BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  22  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  23  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  24  *
  25  */
  26
  27 /**
  28  * \file swrast/swrast.h
  29  * \brief Public interface to the software rasterization functions.
  30  * \author Keith Whitwell <keith@tungstengraphics.com>
  31  */
  32
  33 #ifndef SWRAST_H
  34 #define SWRAST_H
  35
  36 #include "mtypes.h"
  37
  38 /**
  39  * \struct SWvertex
  40  * \brief Data-structure to handle vertices in the software rasterizer.
  41  *
  42  * The software rasterizer now uses this format for vertices.  Thus a
  43  * 'RasterSetup' stage or other translation is required between the
  44  * tnl module and the swrast rasterization functions.  This serves to
  45  * isolate the swrast module from the internals of the tnl module, and
  46  * improve its usefulness as a fallback mechanism for hardware
  47  * drivers.
  48  *
  49  * Full software drivers:
  50  *   - Register the rastersetup and triangle functions from
  51  *     utils/software_helper.
  52  *   - On statechange, update the rasterization pointers in that module.
  53  *
  54  * Rasterization hardware drivers:
  55  *   - Keep native rastersetup.
  56  *   - Implement native twoside,offset and unfilled triangle setup.
  57  *   - Implement a translator from native vertices to swrast vertices.
  58  *   - On partial fallback (mix of accelerated and unaccelerated
  59  *   prims), call a pass-through function which translates native
  60  *   vertices to SWvertices and calls the appropriate swrast function.
  61  *   - On total fallback (vertex format insufficient for state or all
  62  *     primitives unaccelerated), hook in swrast_setup instead.
  63  */
  64 typedef struct {
  65    /** win[0], win[1] are the screen-coords of SWvertex. win[2] is the
  66     * z-coord. what is win[3]? */
  67    GLfloat win[4];
  68    GLfloat texcoord[MAX_TEXTURE_COORD_UNITS][4];
  69    GLchan color[4];
  70    GLchan specular[4];
  71    GLfloat fog;
  72    GLuint index;
  73    GLfloat pointSize;
  74 } SWvertex;
  75
  76
  77 struct swrast_device_driver;
  78
  79
  80 /* These are the public-access functions exported from swrast.
  81  */
  82 extern void
  83 _swrast_alloc_buffers( GLframebuffer *buffer );
  84
  85 extern void
  86 _swrast_use_read_buffer( GLcontext *ctx );
  87
  88 extern void
  89 _swrast_use_draw_buffer( GLcontext *ctx );
  90
  91 extern GLboolean
  92 _swrast_CreateContext( GLcontext *ctx );
  93
  94 extern void
  95 _swrast_DestroyContext( GLcontext *ctx );
  96
  97 /* Get a (non-const) reference to the device driver struct for swrast.
  98  */
  99 extern struct swrast_device_driver *
 100 _swrast_GetDeviceDriverReference( GLcontext *ctx );
 101
 102 extern void
 103 _swrast_Bitmap( GLcontext *ctx,
 104                 GLint px, GLint py,
 105                 GLsizei width, GLsizei height,
 106                 const struct gl_pixelstore_attrib *unpack,
 107                 const GLubyte *bitmap );
 108
 109 extern void
 110 _swrast_CopyPixels( GLcontext *ctx,
 111                     GLint srcx, GLint srcy,
 112                     GLint destx, GLint desty,
 113                     GLsizei width, GLsizei height,
 114                     GLenum type );
 115
 116 extern void
 117 _swrast_DrawPixels( GLcontext *ctx,
 118                     GLint x, GLint y,
 119                     GLsizei width, GLsizei height,
 120                     GLenum format, GLenum type,
 121                     const struct gl_pixelstore_attrib *unpack,
 122                     const GLvoid *pixels );
 123
 124 extern void
 125 _swrast_ReadPixels( GLcontext *ctx,
 126                     GLint x, GLint y, GLsizei width, GLsizei height,
 127                     GLenum format, GLenum type,
 128                     const struct gl_pixelstore_attrib *unpack,
 129                     GLvoid *pixels );
 130
 131 extern void
 132 _swrast_Clear( GLcontext *ctx, GLbitfield mask, GLboolean all,
 133                GLint x, GLint y, GLint width, GLint height );
 134
 135 extern void
 136 _swrast_Accum( GLcontext *ctx, GLenum op,
 137                GLfloat value, GLint xpos, GLint ypos,
 138                GLint width, GLint height );
 139
 140
 141 extern void
 142 _swrast_DrawBuffer( GLcontext *ctx, GLenum mode );
 143
 144
 145 /* Reset the stipple counter
 146  */
 147 extern void
 148 _swrast_ResetLineStipple( GLcontext *ctx );
 149
 150 /* These will always render the correct point/line/triangle for the
 151  * current state.
 152  *
 153  * For flatshaded primitives, the provoking vertex is the final one.
 154  */
 155 extern void
 156 _swrast_Point( GLcontext *ctx, const SWvertex *v );
 157
 158 extern void
 159 _swrast_Line( GLcontext *ctx, const SWvertex *v0, const SWvertex *v1 );
 160
 161 extern void
 162 _swrast_Triangle( GLcontext *ctx, const SWvertex *v0,
 163                   const SWvertex *v1, const SWvertex *v2 );
 164
 165 extern void
 166 _swrast_Quad( GLcontext *ctx,
 167               const SWvertex *v0, const SWvertex *v1,
 168               const SWvertex *v2,  const SWvertex *v3);
 169
 170 extern void
 171 _swrast_flush( GLcontext *ctx );
 172
 173 extern void
 174 _swrast_render_primitive( GLcontext *ctx, GLenum mode );
 175
 176 extern void
 177 _swrast_render_start( GLcontext *ctx );
 178
 179 extern void
 180 _swrast_render_finish( GLcontext *ctx );
 181
 182 /* Tell the software rasterizer about core state changes.
 183  */
 184 extern void
 185 _swrast_InvalidateState( GLcontext *ctx, GLuint new_state );
 186
 187 /* Configure software rasterizer to match hardware rasterizer characteristics:
 188  */
 189 extern void
 190 _swrast_allow_vertex_fog( GLcontext *ctx, GLboolean value );
 191
 192 extern void
 193 _swrast_allow_pixel_fog( GLcontext *ctx, GLboolean value );
 194
 195 /* Debug:
 196  */
 197 extern void
 198 _swrast_print_vertex( GLcontext *ctx, const SWvertex *v );
 199
 200
 201 /*
 202  * Imaging fallbacks (a better solution should be found, perhaps
 203  * moving all the imaging fallback code to a new module)
 204  */
 205 extern void
 206 _swrast_CopyConvolutionFilter2D(GLcontext *ctx, GLenum target,
 207                                 GLenum internalFormat,
 208                                 GLint x, GLint y, GLsizei width,
 209                                 GLsizei height);
 210 extern void
 211 _swrast_CopyConvolutionFilter1D(GLcontext *ctx, GLenum target,
 212                                 GLenum internalFormat,
 213                                 GLint x, GLint y, GLsizei width);
 214 extern void
 215 _swrast_CopyColorSubTable( GLcontext *ctx,GLenum target, GLsizei start,
 216                            GLint x, GLint y, GLsizei width);
 217 extern void
 218 _swrast_CopyColorTable( GLcontext *ctx,
 219                         GLenum target, GLenum internalformat,
 220                         GLint x, GLint y, GLsizei width);
 221
 222
 223 /*
 224  * Texture fallbacks, Brian Paul.  Could also live in a new module
 225  * with the rest of the texture store fallbacks?
 226  */
 227 extern void
 228 _swrast_copy_teximage1d(GLcontext *ctx, GLenum target, GLint level,
 229                         GLenum internalFormat,
 230                         GLint x, GLint y, GLsizei width, GLint border);
 231
 232 extern void
 233 _swrast_copy_teximage2d(GLcontext *ctx, GLenum target, GLint level,
 234                         GLenum internalFormat,
 235                         GLint x, GLint y, GLsizei width, GLsizei height,
 236                         GLint border);
 237
 238
 239 extern void
 240 _swrast_copy_texsubimage1d(GLcontext *ctx, GLenum target, GLint level,
 241                            GLint xoffset, GLint x, GLint y, GLsizei width);
 242
 243 extern void
 244 _swrast_copy_texsubimage2d(GLcontext *ctx,
 245                            GLenum target, GLint level,
 246                            GLint xoffset, GLint yoffset,
 247                            GLint x, GLint y, GLsizei width, GLsizei height);
 248
 249 extern void
 250 _swrast_copy_texsubimage3d(GLcontext *ctx,
 251                            GLenum target, GLint level,
 252                            GLint xoffset, GLint yoffset, GLint zoffset,
 253                            GLint x, GLint y, GLsizei width, GLsizei height);
 254
 255
 256
 257 /* The driver interface for the software rasterizer.
 258  * Unless otherwise noted, all functions are mandatory.
 259  */
 260 struct swrast_device_driver {
 261
 262    void (*SetBuffer)( GLcontext *ctx, GLframebuffer *buffer, GLuint bufferBit);
 263    /*
 264     * Specifies the current buffer for span/pixel writing/reading.
 265     * buffer indicates which window to write to / read from.  Normally,
 266     * this'll be the buffer currently bound to the context, but it doesn't
 267     * have to be!
 268     * bufferBit indicates which color buffer, one of:
 269     *    FRONT_LEFT_BIT - this buffer always exists
 270     *    BACK_LEFT_BIT - when double buffering
 271     *    FRONT_RIGHT_BIT - when using stereo
 272     *    BACK_RIGHT_BIT - when using stereo and double buffering
 273     *    AUXn_BIT - if aux buffers are implemented
 274     */
 275
 276
 277    /***
 278     *** Functions for synchronizing access to the framebuffer:
 279     ***/
 280
 281    void (*SpanRenderStart)(GLcontext *ctx);
 282    void (*SpanRenderFinish)(GLcontext *ctx);
 283    /* OPTIONAL.
 284     *
 285     * Called before and after all rendering operations, including DrawPixels,
 286     * ReadPixels, Bitmap, span functions, and CopyTexImage, etc commands.
 287     * These are a suitable place for grabbing/releasing hardware locks.
 288     *
 289     * NOTE: The swrast triangle/line/point routines *DO NOT* call
 290     * these functions.  Locking in that case must be organized by the
 291     * driver by other mechanisms.
 292     */
 293
 294    /***
 295     *** Functions for writing pixels to the frame buffer:
 296     ***/
 297
 298    void (*WriteRGBASpan)( const GLcontext *ctx,
 299                           GLuint n, GLint x, GLint y,
 300                           CONST GLchan rgba[][4], const GLubyte mask[] );
 301    void (*WriteRGBSpan)( const GLcontext *ctx,
 302                          GLuint n, GLint x, GLint y,
 303                          CONST GLchan rgb[][3], const GLubyte mask[] );
 304    /* Write a horizontal run of RGBA or RGB pixels.
 305     * If mask is NULL, draw all pixels.
 306     * If mask is not null, only draw pixel [i] when mask [i] is true.
 307     */
 308
 309    void (*WriteMonoRGBASpan)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 310                               const GLchan color[4], const GLubyte mask[] );
 311    /* Write a horizontal run of RGBA pixels all with the same color.
 312     * If mask is NULL, draw all pixels.
 313     * If mask is not null, only draw pixel [i] when mask [i] is true.
 314     */
 315
 316    void (*WriteRGBAPixels)( const GLcontext *ctx,
 317                             GLuint n, const GLint x[], const GLint y[],
 318                             CONST GLchan rgba[][4], const GLubyte mask[] );
 319    /* Write array of RGBA pixels at random locations.
 320     */
 321
 322    void (*WriteMonoRGBAPixels)( const GLcontext *ctx,
 323                                 GLuint n, const GLint x[], const GLint y[],
 324                                 const GLchan color[4], const GLubyte mask[] );
 325    /* Write an array of mono-RGBA pixels at random locations.
 326     */
 327
 328    void (*WriteCI32Span)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 329                           const GLuint index[], const GLubyte mask[] );
 330    void (*WriteCI8Span)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 331                          const GLubyte index[], const GLubyte mask[] );
 332    /* Write a horizontal run of CI pixels.  One function is for 32bpp
 333     * indexes and the other for 8bpp pixels (the common case).  You mus
 334     * implement both for color index mode.
 335     * If mask is NULL, draw all pixels.
 336     * If mask is not null, only draw pixel [i] when mask [i] is true.
 337     */
 338
 339    void (*WriteMonoCISpan)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 340                             GLuint colorIndex, const GLubyte mask[] );
 341    /* Write a horizontal run of color index pixels using the color index
 342     * last specified by the Index() function.
 343     * If mask is NULL, draw all pixels.
 344     * If mask is not null, only draw pixel [i] when mask [i] is true.
 345     */
 346
 347    void (*WriteCI32Pixels)( const GLcontext *ctx,
 348                             GLuint n, const GLint x[], const GLint y[],
 349                             const GLuint index[], const GLubyte mask[] );
 350    /*
 351     * Write a random array of CI pixels.
 352     */
 353
 354    void (*WriteMonoCIPixels)( const GLcontext *ctx,
 355                               GLuint n, const GLint x[], const GLint y[],
 356                               GLuint colorIndex, const GLubyte mask[] );
 357    /* Write a random array of color index pixels using the color index
 358     * last specified by the Index() function.
 359     */
 360
 361
 362    /***
 363     *** Functions to read pixels from frame buffer:
 364     ***/
 365
 366    void (*ReadCI32Span)( const GLcontext *ctx,
 367                          GLuint n, GLint x, GLint y, GLuint index[] );
 368    /* Read a horizontal run of color index pixels.
 369     */
 370
 371    void (*ReadRGBASpan)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 372                          GLchan rgba[][4] );
 373    /* Read a horizontal run of RGBA pixels.
 374     */
 375
 376    void (*ReadCI32Pixels)( const GLcontext *ctx,
 377                            GLuint n, const GLint x[], const GLint y[],
 378                            GLuint indx[], const GLubyte mask[] );
 379    /* Read a random array of CI pixels.
 380     */
 381
 382    void (*ReadRGBAPixels)( const GLcontext *ctx,
 383                            GLuint n, const GLint x[], const GLint y[],
 384                            GLchan rgba[][4], const GLubyte mask[] );
 385    /* Read a random array of RGBA pixels.
 386     */
 387
 388
 389
 390    /***
 391     *** For supporting hardware Z buffers:
 392     *** Either ALL or NONE of these functions must be implemented!
 393     *** NOTE that Each depth value is a 32-bit GLuint.  If the depth
 394     *** buffer is less than 32 bits deep then the extra upperbits are zero.
 395     ***/
 396
 397    void (*WriteDepthSpan)( GLcontext *ctx, GLuint n, GLint x, GLint y,
 398                            const GLdepth depth[], const GLubyte mask[] );
 399    /* Write a horizontal span of values into the depth buffer.  Only write
 400     * depth[i] value if mask[i] is nonzero.
 401     */
 402
 403    void (*ReadDepthSpan)( GLcontext *ctx, GLuint n, GLint x, GLint y,
 404                           GLdepth depth[] );
 405    /* Read a horizontal span of values from the depth buffer.
 406     */
 407
 408
 409    void (*WriteDepthPixels)( GLcontext *ctx, GLuint n,
 410                              const GLint x[], const GLint y[],
 411                              const GLdepth depth[], const GLubyte mask[] );
 412    /* Write an array of randomly positioned depth values into the
 413     * depth buffer.  Only write depth[i] value if mask[i] is nonzero.
 414     */
 415
 416    void (*ReadDepthPixels)( GLcontext *ctx, GLuint n,
 417                             const GLint x[], const GLint y[],
 418                             GLdepth depth[] );
 419    /* Read an array of randomly positioned depth values from the depth buffer.
 420     */
 421
 422
 423
 424    /***
 425     *** For supporting hardware stencil buffers:
 426     *** Either ALL or NONE of these functions must be implemented!
 427     ***/
 428
 429    void (*WriteStencilSpan)( GLcontext *ctx, GLuint n, GLint x, GLint y,
 430                              const GLstencil stencil[], const GLubyte mask[] );
 431    /* Write a horizontal span of stencil values into the stencil buffer.
 432     * If mask is NULL, write all stencil values.
 433     * Else, only write stencil[i] if mask[i] is non-zero.
 434     */
 435
 436    void (*ReadStencilSpan)( GLcontext *ctx, GLuint n, GLint x, GLint y,
 437                             GLstencil stencil[] );
 438    /* Read a horizontal span of stencil values from the stencil buffer.
 439     */
 440
 441    void (*WriteStencilPixels)( GLcontext *ctx, GLuint n,
 442                                const GLint x[], const GLint y[],
 443                                const GLstencil stencil[],
 444                                const GLubyte mask[] );
 445    /* Write an array of stencil values into the stencil buffer.
 446     * If mask is NULL, write all stencil values.
 447     * Else, only write stencil[i] if mask[i] is non-zero.
 448     */
 449
 450    void (*ReadStencilPixels)( GLcontext *ctx, GLuint n,
 451                               const GLint x[], const GLint y[],
 452                               GLstencil stencil[] );
 453    /* Read an array of stencil values from the stencil buffer.
 454     */
 455 };
 456
 457
 458
 459 #endif