home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / mesa-1.2.8 / src / dd.h < prev    next >
C/C++ Source or Header  |  1996-05-27  |  13KB  |  377 lines
  1. /* $Id: dd.h,v 1.22 1996/05/01 15:47:07 brianp Exp $ */
  2.  
  3. /*
  4.  * Mesa 3-D graphics library
  5.  * Version:  1.2
  6.  * Copyright (C) 1995-1996  Brian Paul  (brianp@ssec.wisc.edu)
  7.  *
  8.  * This library is free software; you can redistribute it and/or
  9.  * modify it under the terms of the GNU Library General Public
  10.  * License as published by the Free Software Foundation; either
  11.  * version 2 of the License, or (at your option) any later version.
  12.  *
  13.  * This library is distributed in the hope that it will be useful,
  14.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16.  * Library General Public License for more details.
  17.  *
  18.  * You should have received a copy of the GNU Library General Public
  19.  * License along with this library; if not, write to the Free
  20.  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  21.  */
  22.  
  23.  
  24. /*
  25. $Log: dd.h,v $
  26.  * Revision 1.22  1996/05/01  15:47:07  brianp
  27.  * added read_depth_span_float() and read_depth_span_int() functions
  28.  *
  29.  * Revision 1.21  1996/04/25  20:54:57  brianp
  30.  * redesigned DD: optional function pointers, new depth buffer functions
  31.  *
  32.  * Revision 1.20  1995/11/10  20:42:57  brianp
  33.  * removed old comments
  34.  *
  35.  * Revision 1.19  1995/10/30  15:30:48  brianp
  36.  * added mask[] argument to read_[color|index]_pixels
  37.  *
  38.  * Revision 1.18  1995/10/19  15:46:31  brianp
  39.  * changed clear_color and color arguments to GLubytes
  40.  *
  41.  * Revision 1.17  1995/10/17  21:43:22  brianp
  42.  * finished changes for new device driver interface
  43.  *
  44.  * Revision 1.16  1995/09/21  14:07:55  brianp
  45.  * more new DD prototyping
  46.  *
  47.  * Revision 1.15  1995/09/20  18:19:58  brianp
  48.  * prototype device driver changes described
  49.  *
  50.  * Revision 1.14  1995/09/15  18:46:39  brianp
  51.  * new functions pointers for all device driver functions
  52.  *
  53.  * Revision 1.13  1995/07/24  18:55:20  brianp
  54.  * added dd_finish()
  55.  *
  56.  * Revision 1.12  1995/06/12  15:38:23  brianp
  57.  * changed color arrays to GLubyte
  58.  *
  59.  * Revision 1.11  1995/05/22  20:59:34  brianp
  60.  * Release 1.2
  61.  *
  62.  * Revision 1.10  1995/04/12  15:37:05  brianp
  63.  * removed dd_draw_pixel(), dd_draw_line(), and dd_draw_polygon()
  64.  *
  65.  * Revision 1.9  1995/04/11  14:04:57  brianp
  66.  * introduced DD struct of function pointers
  67.  *
  68.  * Revision 1.8  1995/03/30  21:07:49  brianp
  69.  * updated to use pointers to CC.write_* functions
  70.  *
  71.  * Revision 1.7  1995/03/22  21:36:53  brianp
  72.  * removed mode from dd_buffer_info()
  73.  *
  74.  * Revision 1.6  1995/03/08  15:10:02  brianp
  75.  * added support for dd_logicop
  76.  * added dd_clear_index and dd_clear_color
  77.  *
  78.  * Revision 1.5  1995/03/07  19:01:39  brianp
  79.  * added dd_read_index_pixels() and dd_read_color_pixels()
  80.  *
  81.  * Revision 1.4  1995/03/07  14:20:41  brianp
  82.  * updated for new XSetForeground/GC scheme
  83.  *
  84.  * Revision 1.3  1995/03/04  19:25:29  brianp
  85.  * 1.1 beta revision
  86.  *
  87.  * Revision 1.2  1995/02/27  22:48:36  brianp
  88.  * modified for PB
  89.  *
  90.  * Revision 1.1  1995/02/24  14:20:25  brianp
  91.  * Initial revision
  92.  *
  93.  */
  94.  
  95.  
  96. #ifndef DD_INCLUDED
  97. #define DD_INCLUDED
  98.  
  99.  
  100. #include "context.h"
  101.  
  102.  
  103.  
  104. /*
  105.  *                      Device Driver (DD) interface
  106.  *
  107.  *
  108.  * All device driver functions are accessed via pointers in the global
  109.  * DD struct.  The reason we use function pointers is to:
  110.  *   1. allow switching between a number of different device drivers at
  111.  *      runtime.
  112.  *   2. use optimized functions dependant on frame buffer configuration
  113.  *
  114.  * The function pointers in the DD struct are divided into two groups:
  115.  * mandatory and optional.  Mandatory functions have to be implemented by
  116.  * every device driver.  Optional functions may or may not be implemented
  117.  * by the device driver.  Optional functions provide ways to take advantage
  118.  * of special hardware or optimized algorithms.
  119.  *
  120.  * When should the device driver set the DD pointers?
  121.  *   1. When a "MakeCurrent" function is called such as GLXMakeCurrent(),
  122.  *      XMesaMakeCurrent(), WMesaMakeCurrent(), etc.  In this case, _all_
  123.  *      the mandatory DD pointers must be updated.  But do this after
  124.  *      the call to gl_set_context().
  125.  *   2. Whenever the DD.update_state() function is called.  In this case
  126.  *      only some DD pointers may need to be updated.
  127.  *
  128.  * In either case, the device driver should re-examine the GL context state
  129.  * and update the DD pointers as necessary.
  130.  *
  131.  *
  132.  * Here's a quick description of most device driver function's purpose:
  133.  *
  134.  * Mandatory functions:
  135.  * --------------------
  136.  * update_state - called by Mesa whenever it thinks the device driver
  137.  *                should update its DD pointers.
  138.  * clear_index - implements glClearIndex()
  139.  * clear_color - implements glClearColor()
  140.  * clear_color_buffer - implements glClear(), with some special arguments
  141.  * index - implements glIndex()
  142.  * color - implements glColor()
  143.  *
  144.  * set_buffer - selects the front or back buffer for reading and writing.
  145.  *              The default value is the buffer selected for writing pixels.
  146.  *              When pixels have to be read from the color buffer, the core
  147.  *              library will  call this function to temporarily select the
  148.  *              "read" buffer, then restore it to the "draw" buffer.
  149.  *
  150.  * buffer_size - return width, height, depth of image buffer
  151.  *
  152.  * write_color_span - write a horizontal run of RGBA pixels
  153.  * write_monocolor_span - write a horizontal run of mono-RGBA pixels
  154.  * write_color_pixels - write a random array of RGBA pixels
  155.  * write_monocolor_pixels - write a random array of mono-RGBA pixels
  156.  *
  157.  * write_index_span - write a horizontal run of CI pixels
  158.  * write_monoindex_span - write a horizontal run of mono-CI pixels
  159.  * write_index_pixels - write a random array of CI pixels
  160.  * write_monoindex_pixels - write a random array of mono-CI pixels
  161.  *
  162.  * read_index_span - read a horizontal run of color index pixels
  163.  * read_color_span - read a horizontal run of RGBA pixels
  164.  * read_index_pixels - read a random array of CI pixels
  165.  * read_color_pixels - read a random array of RGBA pixels
  166.  *
  167.  *
  168.  * Optional functions:
  169.  * -------------------
  170.  * finish - implements glFinish()
  171.  * flush - implements glFlush()
  172.  *
  173.  * index_mask - implements glIndexMask() if possible, else return GL_FALSE
  174.  * color_mask - implements glColorMask() if possible, else return GL_FALSE
  175.  * logicop - implements glLogicOp() if possible, else return GL_FALSE
  176.  * dither - enable/disable dithering
  177.  *
  178.  *
  179.  * Depth (Z) buffer functions may be implemented by drivers for systems
  180.  * with hardware Z buffers.  The functions are:
  181.  *
  182.  * alloc_depth_buffer - called when the depth buffer must be allocated or
  183.  *     possibly resized.
  184.  * clear_depth_buffer - clear the depth buffer to depth specified by
  185.  *     CC.Depth.Clear value.
  186.  * depth_test_span/pixels - apply the depth buffer test to an span/array of
  187.  *     pixels and return an updated pixel mask.  This function is not used
  188.  *     when accelerated point, line, polygon functions are used.
  189.  * read_depth_span_float - return depth values in [0,1] for glReadPixels
  190.  * read_depth_span_int - return depth values as integers for glReadPixels
  191.  *
  192.  *
  193.  * Accelerated point, line, polygon drawing:
  194.  *
  195.  * get_points_func - returns a pointer to an accelerated point drawing function
  196.  * get_line_func - returns a pointer to an accelerated line drawing function
  197.  * get_polygon_func - returns a pointer to an accelerated polygon function
  198.  *
  199.  *
  200.  * Miscellaneous
  201.  *
  202.  * draw_pixels - implements glDrawPixels or returns GL_FALSE if it can't do
  203.  *     the job.
  204.  * begin, end - called by glBegin/glEnd so the device driver can do whatever
  205.  *     it may need to do (window system synchronization, for example)
  206.  *
  207.  *
  208.  * Notes:
  209.  * ------
  210.  *   RGBA = red/green/blue/alpha
  211.  *   CI = color index (color mapped mode)
  212.  *   mono = all pixels have the same color or index
  213.  *
  214.  *   The write_ functions all take an array of mask flags which indicate
  215.  *   whether or not the pixel should be written.  One special case exists
  216.  *   in the write_color_span function: if the mask array is NULL, then
  217.  *   draw all pixels.  This is an optimization used for glDrawPixels().
  218.  *
  219.  * IN ALL CASES:
  220.  *      X coordinates start at 0 at the left and increase to the right
  221.  *      Y coordinates start at 0 at the bottom and increase upward
  222.  */
  223.  
  224.  
  225.  
  226. struct dd_function_table {
  227.  
  228.    /***
  229.     *** Mandatory functions:  these functions must be implemented by
  230.     *** every device driver.
  231.     ***/
  232.  
  233.    /*
  234.     * This is called by Mesa whenever it thinks the device driver should
  235.     * re-examine the GL state and update its DD pointers.
  236.     */
  237.    void (*update_state)( void );
  238.  
  239.    /* Implements glClearIndex() */
  240.    void (*clear_index)( GLuint index );
  241.  
  242.    /* Implements glClearColor() */
  243.    void (*clear_color)( GLubyte red, GLubyte green,
  244.                         GLubyte glue, GLubyte alpha );
  245.  
  246.    /* Implements glClear(GL_COLOR_BUFFER_BIT) */
  247.    void (*clear)( GLboolean all, GLint x, GLint y, GLint width, GLint height );
  248.  
  249.    /* Implements glIndex() */
  250.    void (*index)( GLuint index );
  251.  
  252.    /* Implements glColor() */
  253.    void (*color)( GLubyte red, GLubyte green, GLubyte glue, GLubyte alpha );
  254.  
  255.    /* Select front/back buffer as the read source and write destination */
  256.    GLboolean (*set_buffer)( GLenum mode );
  257.  
  258.    /* Returns dimensions of the color buffer */
  259.    void (*buffer_size)( GLuint *width, GLuint *height, GLuint *depth );
  260.  
  261.    /*
  262.     * Return pointers to accelerated point, line, polygon rendering functions:
  263.     * May return NULL.
  264.     */
  265.    points_func (*get_points_func)( void );
  266.    line_func (*get_line_func)( void );
  267.    polygon_func (*get_polygon_func)( void );
  268.  
  269.    /*
  270.     * Functions for writing pixels to the frame buffer:
  271.     */
  272.    void (*write_color_span)( GLuint n, GLint x, GLint y,
  273.                  const GLubyte red[], const GLubyte green[],
  274.                  const GLubyte blue[], const GLubyte alpha[],
  275.                  const GLubyte mask[] );
  276.    void (*write_monocolor_span)( GLuint n, GLint x, GLint y,
  277.                  const GLubyte mask[] );
  278.    void (*write_color_pixels)( GLuint n, const GLint x[], const GLint y[],
  279.                    const GLubyte red[], const GLubyte green[],
  280.                    const GLubyte blue[], const GLubyte alpha[],
  281.                    const GLubyte mask[] );
  282.    void (*write_monocolor_pixels)( GLuint n, const GLint x[], const GLint y[],
  283.                    const GLubyte mask[] );
  284.    void (*write_index_span)( GLuint n, GLint x, GLint y, const GLuint index[],
  285.                  const GLubyte mask[] );
  286.    void (*write_monoindex_span)( GLuint n, GLint x, GLint y,
  287.                  const GLubyte mask[] );
  288.    void (*write_index_pixels)( GLuint n, const GLint x[], const GLint y[],
  289.                    const GLuint index[], const GLubyte mask[] );
  290.    void (*write_monoindex_pixels)( GLuint n, const GLint x[], const GLint y[],
  291.                    const GLubyte mask[] );
  292.  
  293.    /*
  294.     * Functions to read pixels from frame buffer:
  295.     */
  296.    void (*read_index_span)( GLuint n, GLint x, GLint y, GLuint index[] );
  297.    void (*read_color_span)( GLuint n, GLint x, GLint y,
  298.                 GLubyte red[], GLubyte green[],
  299.                 GLubyte blue[], GLubyte alpha[] );
  300.    void (*read_index_pixels)( GLuint n, const GLint x[], const GLint y[],
  301.                   GLuint indx[], const GLubyte mask[] );
  302.    void (*read_color_pixels)( GLuint n, const GLint x[], const GLint y[],
  303.                   GLubyte red[], GLubyte green[],
  304.                   GLubyte blue[], GLubyte alpha[],
  305.                               const GLubyte mask[] );
  306.  
  307.  
  308.  
  309.    /***
  310.     *** Optional functions:  these functions may or may not be implemented
  311.     *** by the device driver.  If the device driver doesn't implement them
  312.     *** it should never touch these pointers since Mesa will either set them
  313.     *** to NULL or point them at a fall-back function.
  314.     ***/
  315.  
  316.    /* Implementes glFinish() */
  317.    void (*finish)( void );
  318.  
  319.    /* Implements glFlush() */
  320.    void (*flush)( void );
  321.  
  322.    /* Implements glIndexMask(), returns GL_FALSE if can't be implemented */
  323.    GLboolean (*index_mask)( GLuint mask );
  324.  
  325.    /* Implements glColorMask(), returns GL_FALSE if can't be implemented */
  326.    GLboolean (*color_mask)( GLboolean rmask, GLboolean gmask,
  327.                             GLboolean bmask, GLboolean amask );
  328.  
  329.    /* Implements glLogicOp(), returns GL_FALSE if can't be implemented */
  330.    GLboolean (*logicop)( GLenum op );
  331.  
  332.    /* Implements glEn/Disable( GL_DITHER ) */
  333.    void (*dither)( GLboolean enable );
  334.  
  335.  
  336.    /*
  337.     * For supporting hardware Z buffers:
  338.     */
  339.    void (*alloc_depth_buffer)( void );
  340.    void (*clear_depth_buffer)( void );
  341.  
  342.    GLuint (*depth_test_span)( GLuint n, GLint x, GLint y, const GLdepth z[],
  343.                               GLubyte mask[] );
  344.    void (*depth_test_pixels)( GLuint n, const GLint x[], const GLint y[],
  345.                               const GLdepth z[], GLubyte mask[] );
  346.    void (*read_depth_span_float)( GLuint n, GLint x, GLint y, GLfloat depth[]);
  347.    void (*read_depth_span_int)( GLuint n, GLint x, GLint y, GLdepth depth[] );
  348.  
  349.    /*
  350.     * Implements glDrawPixels, returns GL_FALSE if can't be done.
  351.     * 'packed' indicates whether or not the pixels are in packed or unpacked
  352.     * format.
  353.     */
  354.    GLboolean (*draw_pixels)( GLint x, GLint y, GLsizei width, GLsizei height,
  355.                              GLenum format, GLenum type, GLboolean packed,
  356.                              const GLvoid *pixels );
  357.  
  358.    /*
  359.     * glBegin/glEnd functions: these are called whenever glBegin or glEnd
  360.     * are executed in case the device driver needs to do something special.
  361.     */
  362.    void (*begin)( GLenum mode );
  363.    void (*end)( void );
  364.  
  365. };
  366.  
  367.  
  368.  
  369. extern struct dd_function_table DD;
  370.  
  371.  
  372. extern void gl_init_dd_function_table( void );
  373.  
  374.  
  375. #endif
  376.  
  377.