src/mesa/swrast/swrast.h

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