swrast.h revision 9ac51f57efe07ed43a1e4224a7f5daddec401b36 
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 */
64typedef 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
77struct swrast_device_driver;
78
79
80/* These are the public-access functions exported from swrast.
81 */
82extern void
83_swrast_alloc_buffers( GLframebuffer *buffer );
84
85extern void
86_swrast_use_read_buffer( GLcontext *ctx );
87
88extern void
89_swrast_use_draw_buffer( GLcontext *ctx );
90
91extern GLboolean
92_swrast_CreateContext( GLcontext *ctx );
93
94extern void
95_swrast_DestroyContext( GLcontext *ctx );
96
97/* Get a (non-const) reference to the device driver struct for swrast.
98 */
99extern struct swrast_device_driver *
100_swrast_GetDeviceDriverReference( GLcontext *ctx );
101
102extern 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
109extern 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
116extern 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
124extern 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
131extern void
132_swrast_Clear( GLcontext *ctx, GLbitfield mask, GLboolean all,
133	       GLint x, GLint y, GLint width, GLint height );
134
135extern void
136_swrast_Accum( GLcontext *ctx, GLenum op,
137	       GLfloat value, GLint xpos, GLint ypos,
138	       GLint width, GLint height );
139
140
141extern void
142_swrast_DrawBuffer( GLcontext *ctx, GLenum mode );
143
144
145/* Reset the stipple counter
146 */
147extern 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 */
155extern void
156_swrast_Point( GLcontext *ctx, const SWvertex *v );
157
158extern void
159_swrast_Line( GLcontext *ctx, const SWvertex *v0, const SWvertex *v1 );
160
161extern void
162_swrast_Triangle( GLcontext *ctx, const SWvertex *v0,
163                  const SWvertex *v1, const SWvertex *v2 );
164
165extern void
166_swrast_Quad( GLcontext *ctx,
167              const SWvertex *v0, const SWvertex *v1,
168	      const SWvertex *v2,  const SWvertex *v3);
169
170extern void
171_swrast_flush( GLcontext *ctx );
172
173extern void
174_swrast_render_primitive( GLcontext *ctx, GLenum mode );
175
176extern void
177_swrast_render_start( GLcontext *ctx );
178
179extern void
180_swrast_render_finish( GLcontext *ctx );
181
182/* Tell the software rasterizer about core state changes.
183 */
184extern void
185_swrast_InvalidateState( GLcontext *ctx, GLuint new_state );
186
187/* Configure software rasterizer to match hardware rasterizer characteristics:
188 */
189extern void
190_swrast_allow_vertex_fog( GLcontext *ctx, GLboolean value );
191
192extern void
193_swrast_allow_pixel_fog( GLcontext *ctx, GLboolean value );
194
195/* Debug:
196 */
197extern 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 */
205extern void
206_swrast_CopyConvolutionFilter2D(GLcontext *ctx, GLenum target,
207				GLenum internalFormat,
208				GLint x, GLint y, GLsizei width,
209				GLsizei height);
210extern void
211_swrast_CopyConvolutionFilter1D(GLcontext *ctx, GLenum target,
212				GLenum internalFormat,
213				GLint x, GLint y, GLsizei width);
214extern void
215_swrast_CopyColorSubTable( GLcontext *ctx,GLenum target, GLsizei start,
216			   GLint x, GLint y, GLsizei width);
217extern 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 */
227extern void
228_swrast_copy_teximage1d(GLcontext *ctx, GLenum target, GLint level,
229                        GLenum internalFormat,
230                        GLint x, GLint y, GLsizei width, GLint border);
231
232extern 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
239extern void
240_swrast_copy_texsubimage1d(GLcontext *ctx, GLenum target, GLint level,
241                           GLint xoffset, GLint x, GLint y, GLsizei width);
242
243extern 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
249extern 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 */
260struct 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
460