src/mesa/swrast/swrast.h

   1 /* $Id: swrast.h,v 1.35 2003/02/23 04:10:54 brianp Exp $ */
   2
   3 /*
   4  * Mesa 3-D graphics library
   5  * Version:  5.1
   6  *
   7  * Copyright (C) 1999-2003  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 Public interface to the software rasterization functions.
  31  * \author Keith Whitwell <keith@tungstengraphics.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    /** win[0], win[1] are the screen-coords of SWvertex. win[2] is the
  67     * z-coord. what is win[3]? */
  68    GLfloat win[4];
  69    GLfloat texcoord[MAX_TEXTURE_COORD_UNITS][4];
  70    GLchan color[4];
  71    GLchan specular[4];
  72    GLfloat fog;
  73    GLuint index;
  74    GLfloat pointSize;
  75 } SWvertex;
  76
  77
  78 struct swrast_device_driver;
  79
  80
  81 /* These are the public-access functions exported from swrast.
  82  */
  83 extern void
  84 _swrast_alloc_buffers( GLframebuffer *buffer );
  85
  86 extern void
  87 _swrast_use_read_buffer( GLcontext *ctx );
  88
  89 extern void
  90 _swrast_use_draw_buffer( GLcontext *ctx );
  91
  92 extern GLboolean
  93 _swrast_CreateContext( GLcontext *ctx );
  94
  95 extern void
  96 _swrast_DestroyContext( GLcontext *ctx );
  97
  98 /* Get a (non-const) reference to the device driver struct for swrast.
  99  */
 100 extern struct swrast_device_driver *
 101 _swrast_GetDeviceDriverReference( GLcontext *ctx );
 102
 103 extern void
 104 _swrast_Bitmap( GLcontext *ctx,
 105                 GLint px, GLint py,
 106                 GLsizei width, GLsizei height,
 107                 const struct gl_pixelstore_attrib *unpack,
 108                 const GLubyte *bitmap );
 109
 110 extern void
 111 _swrast_CopyPixels( GLcontext *ctx,
 112                     GLint srcx, GLint srcy,
 113                     GLint destx, GLint desty,
 114                     GLsizei width, GLsizei height,
 115                     GLenum type );
 116
 117 extern void
 118 _swrast_DrawPixels( GLcontext *ctx,
 119                     GLint x, GLint y,
 120                     GLsizei width, GLsizei height,
 121                     GLenum format, GLenum type,
 122                     const struct gl_pixelstore_attrib *unpack,
 123                     const GLvoid *pixels );
 124
 125 extern void
 126 _swrast_ReadPixels( GLcontext *ctx,
 127                     GLint x, GLint y, GLsizei width, GLsizei height,
 128                     GLenum format, GLenum type,
 129                     const struct gl_pixelstore_attrib *unpack,
 130                     GLvoid *pixels );
 131
 132 extern void
 133 _swrast_Clear( GLcontext *ctx, GLbitfield mask, GLboolean all,
 134                GLint x, GLint y, GLint width, GLint height );
 135
 136 extern void
 137 _swrast_Accum( GLcontext *ctx, GLenum op,
 138                GLfloat value, GLint xpos, GLint ypos,
 139                GLint width, GLint height );
 140
 141
 142 extern void
 143 _swrast_DrawBuffer( GLcontext *ctx, GLenum mode );
 144
 145
 146 /* Reset the stipple counter
 147  */
 148 extern void
 149 _swrast_ResetLineStipple( GLcontext *ctx );
 150
 151 /* These will always render the correct point/line/triangle for the
 152  * current state.
 153  *
 154  * For flatshaded primitives, the provoking vertex is the final one.
 155  */
 156 extern void
 157 _swrast_Point( GLcontext *ctx, const SWvertex *v );
 158
 159 extern void
 160 _swrast_Line( GLcontext *ctx, const SWvertex *v0, const SWvertex *v1 );
 161
 162 extern void
 163 _swrast_Triangle( GLcontext *ctx, const SWvertex *v0,
 164                   const SWvertex *v1, const SWvertex *v2 );
 165
 166 extern void
 167 _swrast_Quad( GLcontext *ctx,
 168               const SWvertex *v0, const SWvertex *v1,
 169               const SWvertex *v2,  const SWvertex *v3);
 170
 171 extern void
 172 _swrast_flush( GLcontext *ctx );
 173
 174 extern void
 175 _swrast_render_primitive( GLcontext *ctx, GLenum mode );
 176
 177 extern void
 178 _swrast_render_start( GLcontext *ctx );
 179
 180 extern void
 181 _swrast_render_finish( GLcontext *ctx );
 182
 183 /* Tell the software rasterizer about core state changes.
 184  */
 185 extern void
 186 _swrast_InvalidateState( GLcontext *ctx, GLuint new_state );
 187
 188 /* Configure software rasterizer to match hardware rasterizer characteristics:
 189  */
 190 extern void
 191 _swrast_allow_vertex_fog( GLcontext *ctx, GLboolean value );
 192
 193 extern void
 194 _swrast_allow_pixel_fog( GLcontext *ctx, GLboolean value );
 195
 196 /* Debug:
 197  */
 198 extern void
 199 _swrast_print_vertex( GLcontext *ctx, const SWvertex *v );
 200
 201
 202 /*
 203  * Imaging fallbacks (a better solution should be found, perhaps
 204  * moving all the imaging fallback code to a new module)
 205  */
 206 extern void
 207 _swrast_CopyConvolutionFilter2D(GLcontext *ctx, GLenum target,
 208                                 GLenum internalFormat,
 209                                 GLint x, GLint y, GLsizei width,
 210                                 GLsizei height);
 211 extern void
 212 _swrast_CopyConvolutionFilter1D(GLcontext *ctx, GLenum target,
 213                                 GLenum internalFormat,
 214                                 GLint x, GLint y, GLsizei width);
 215 extern void
 216 _swrast_CopyColorSubTable( GLcontext *ctx,GLenum target, GLsizei start,
 217                            GLint x, GLint y, GLsizei width);
 218 extern void
 219 _swrast_CopyColorTable( GLcontext *ctx,
 220                         GLenum target, GLenum internalformat,
 221                         GLint x, GLint y, GLsizei width);
 222
 223
 224 /*
 225  * Texture fallbacks, Brian Paul.  Could also live in a new module
 226  * with the rest of the texture store fallbacks?
 227  */
 228 extern void
 229 _swrast_copy_teximage1d(GLcontext *ctx, GLenum target, GLint level,
 230                         GLenum internalFormat,
 231                         GLint x, GLint y, GLsizei width, GLint border);
 232
 233 extern void
 234 _swrast_copy_teximage2d(GLcontext *ctx, GLenum target, GLint level,
 235                         GLenum internalFormat,
 236                         GLint x, GLint y, GLsizei width, GLsizei height,
 237                         GLint border);
 238
 239
 240 extern void
 241 _swrast_copy_texsubimage1d(GLcontext *ctx, GLenum target, GLint level,
 242                            GLint xoffset, GLint x, GLint y, GLsizei width);
 243
 244 extern void
 245 _swrast_copy_texsubimage2d(GLcontext *ctx,
 246                            GLenum target, GLint level,
 247                            GLint xoffset, GLint yoffset,
 248                            GLint x, GLint y, GLsizei width, GLsizei height);
 249
 250 extern void
 251 _swrast_copy_texsubimage3d(GLcontext *ctx,
 252                            GLenum target, GLint level,
 253                            GLint xoffset, GLint yoffset, GLint zoffset,
 254                            GLint x, GLint y, GLsizei width, GLsizei height);
 255
 256
 257
 258 /* The driver interface for the software rasterizer.
 259  * Unless otherwise noted, all functions are mandatory.
 260  */
 261 struct swrast_device_driver {
 262
 263    void (*SetBuffer)( GLcontext *ctx, GLframebuffer *buffer, GLuint bufferBit);
 264    /*
 265     * Specifies the current buffer for span/pixel writing/reading.
 266     * buffer indicates which window to write to / read from.  Normally,
 267     * this'll be the buffer currently bound to the context, but it doesn't
 268     * have to be!
 269     * bufferBit indicates which color buffer, one of:
 270     *    FRONT_LEFT_BIT - this buffer always exists
 271     *    BACK_LEFT_BIT - when double buffering
 272     *    FRONT_RIGHT_BIT - when using stereo
 273     *    BACK_RIGHT_BIT - when using stereo and double buffering
 274     *    AUXn_BIT - if aux buffers are implemented
 275     */
 276
 277
 278    /***
 279     *** Functions for synchronizing access to the framebuffer:
 280     ***/
 281
 282    void (*SpanRenderStart)(GLcontext *ctx);
 283    void (*SpanRenderFinish)(GLcontext *ctx);
 284    /* OPTIONAL.
 285     *
 286     * Called before and after all rendering operations, including DrawPixels,
 287     * ReadPixels, Bitmap, span functions, and CopyTexImage, etc commands.
 288     * These are a suitable place for grabbing/releasing hardware locks.
 289     *
 290     * NOTE: The swrast triangle/line/point routines *DO NOT* call
 291     * these functions.  Locking in that case must be organized by the
 292     * driver by other mechanisms.
 293     */
 294
 295    /***
 296     *** Functions for writing pixels to the frame buffer:
 297     ***/
 298
 299    void (*WriteRGBASpan)( const GLcontext *ctx,
 300                           GLuint n, GLint x, GLint y,
 301                           CONST GLchan rgba[][4], const GLubyte mask[] );
 302    void (*WriteRGBSpan)( const GLcontext *ctx,
 303                          GLuint n, GLint x, GLint y,
 304                          CONST GLchan rgb[][3], const GLubyte mask[] );
 305    /* Write a horizontal run of RGBA or RGB pixels.
 306     * If mask is NULL, draw all pixels.
 307     * If mask is not null, only draw pixel [i] when mask [i] is true.
 308     */
 309
 310    void (*WriteMonoRGBASpan)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 311                               const GLchan color[4], const GLubyte mask[] );
 312    /* Write a horizontal run of RGBA pixels all with the same color.
 313     * If mask is NULL, draw all pixels.
 314     * If mask is not null, only draw pixel [i] when mask [i] is true.
 315     */
 316
 317    void (*WriteRGBAPixels)( const GLcontext *ctx,
 318                             GLuint n, const GLint x[], const GLint y[],
 319                             CONST GLchan rgba[][4], const GLubyte mask[] );
 320    /* Write array of RGBA pixels at random locations.
 321     */
 322
 323    void (*WriteMonoRGBAPixels)( const GLcontext *ctx,
 324                                 GLuint n, const GLint x[], const GLint y[],
 325                                 const GLchan color[4], const GLubyte mask[] );
 326    /* Write an array of mono-RGBA pixels at random locations.
 327     */
 328
 329    void (*WriteCI32Span)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 330                           const GLuint index[], const GLubyte mask[] );
 331    void (*WriteCI8Span)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 332                          const GLubyte index[], const GLubyte mask[] );
 333    /* Write a horizontal run of CI pixels.  One function is for 32bpp
 334     * indexes and the other for 8bpp pixels (the common case).  You mus
 335     * implement both for color index mode.
 336     * If mask is NULL, draw all pixels.
 337     * If mask is not null, only draw pixel [i] when mask [i] is true.
 338     */
 339
 340    void (*WriteMonoCISpan)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 341                             GLuint colorIndex, const GLubyte mask[] );
 342    /* Write a horizontal run of color index pixels using the color index
 343     * last specified by the Index() function.
 344     * If mask is NULL, draw all pixels.
 345     * If mask is not null, only draw pixel [i] when mask [i] is true.
 346     */
 347
 348    void (*WriteCI32Pixels)( const GLcontext *ctx,
 349                             GLuint n, const GLint x[], const GLint y[],
 350                             const GLuint index[], const GLubyte mask[] );
 351    /*
 352     * Write a random array of CI pixels.
 353     */
 354
 355    void (*WriteMonoCIPixels)( const GLcontext *ctx,
 356                               GLuint n, const GLint x[], const GLint y[],
 357                               GLuint colorIndex, const GLubyte mask[] );
 358    /* Write a random array of color index pixels using the color index
 359     * last specified by the Index() function.
 360     */
 361
 362
 363    /***
 364     *** Functions to read pixels from frame buffer:
 365     ***/
 366
 367    void (*ReadCI32Span)( const GLcontext *ctx,
 368                          GLuint n, GLint x, GLint y, GLuint index[] );
 369    /* Read a horizontal run of color index pixels.
 370     */
 371
 372    void (*ReadRGBASpan)( const GLcontext *ctx, GLuint n, GLint x, GLint y,
 373                          GLchan rgba[][4] );
 374    /* Read a horizontal run of RGBA pixels.
 375     */
 376
 377    void (*ReadCI32Pixels)( const GLcontext *ctx,
 378                            GLuint n, const GLint x[], const GLint y[],
 379                            GLuint indx[], const GLubyte mask[] );
 380    /* Read a random array of CI pixels.
 381     */
 382
 383    void (*ReadRGBAPixels)( const GLcontext *ctx,
 384                            GLuint n, const GLint x[], const GLint y[],
 385                            GLchan rgba[][4], const GLubyte mask[] );
 386    /* Read a random array of RGBA pixels.
 387     */
 388
 389
 390
 391    /***
 392     *** For supporting hardware Z buffers:
 393     *** Either ALL or NONE of these functions must be implemented!
 394     *** NOTE that Each depth value is a 32-bit GLuint.  If the depth
 395     *** buffer is less than 32 bits deep then the extra upperbits are zero.
 396     ***/
 397
 398    void (*WriteDepthSpan)( GLcontext *ctx, GLuint n, GLint x, GLint y,
 399                            const GLdepth depth[], const GLubyte mask[] );
 400    /* Write a horizontal span of values into the depth buffer.  Only write
 401     * depth[i] value if mask[i] is nonzero.
 402     */
 403
 404    void (*ReadDepthSpan)( GLcontext *ctx, GLuint n, GLint x, GLint y,
 405                           GLdepth depth[] );
 406    /* Read a horizontal span of values from the depth buffer.
 407     */
 408
 409
 410    void (*WriteDepthPixels)( GLcontext *ctx, GLuint n,
 411                              const GLint x[], const GLint y[],
 412                              const GLdepth depth[], const GLubyte mask[] );
 413    /* Write an array of randomly positioned depth values into the
 414     * depth buffer.  Only write depth[i] value if mask[i] is nonzero.
 415     */
 416
 417    void (*ReadDepthPixels)( GLcontext *ctx, GLuint n,
 418                             const GLint x[], const GLint y[],
 419                             GLdepth depth[] );
 420    /* Read an array of randomly positioned depth values from the depth buffer.
 421     */
 422
 423
 424
 425    /***
 426     *** For supporting hardware stencil buffers:
 427     *** Either ALL or NONE of these functions must be implemented!
 428     ***/
 429
 430    void (*WriteStencilSpan)( GLcontext *ctx, GLuint n, GLint x, GLint y,
 431                              const GLstencil stencil[], const GLubyte mask[] );
 432    /* Write a horizontal span of stencil values into the stencil buffer.
 433     * If mask is NULL, write all stencil values.
 434     * Else, only write stencil[i] if mask[i] is non-zero.
 435     */
 436
 437    void (*ReadStencilSpan)( GLcontext *ctx, GLuint n, GLint x, GLint y,
 438                             GLstencil stencil[] );
 439    /* Read a horizontal span of stencil values from the stencil buffer.
 440     */
 441
 442    void (*WriteStencilPixels)( GLcontext *ctx, GLuint n,
 443                                const GLint x[], const GLint y[],
 444                                const GLstencil stencil[],
 445                                const GLubyte mask[] );
 446    /* Write an array of stencil values into the stencil buffer.
 447     * If mask is NULL, write all stencil values.
 448     * Else, only write stencil[i] if mask[i] is non-zero.
 449     */
 450
 451    void (*ReadStencilPixels)( GLcontext *ctx, GLuint n,
 452                               const GLint x[], const GLint y[],
 453                               GLstencil stencil[] );
 454    /* Read an array of stencil values from the stencil buffer.
 455     */
 456 };
 457
 458
 459
 460 #endif