home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Amiga 5 / MA_Cover_5.iso / ppc / mesa / src / dd.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-01-31  |  17.2 KB  |  539 lines
  1. /* $Id: dd.h,v 1.13 1997/10/29 02:23:54 brianp Exp $ */
  2.  
  3. /*
  4.  * Mesa 3-D graphics library
  5.  * Version:  2.5
  6.  * Copyright (C) 1995-1997  Brian Paul
  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.13  1997/10/29 02:23:54  brianp
  27.  * added UseGlobalTexturePalette() dd function (David Bucciarelli v20 3dfx)
  28.  *
  29.  * Revision 1.12  1997/10/16 02:27:53  brianp
  30.  * more comments
  31.  *
  32.  * Revision 1.11  1997/10/14 00:07:40  brianp
  33.  * added DavidB's fxmesa v19 changes
  34.  *
  35.  * Revision 1.10  1997/09/29 23:26:50  brianp
  36.  * new texture functions
  37.  *
  38.  * Revision 1.9  1997/04/29 01:31:07  brianp
  39.  * added RasterSetup() function to device driver
  40.  *
  41.  * Revision 1.8  1997/04/20 19:47:27  brianp
  42.  * added RenderVB to device driver
  43.  *
  44.  * Revision 1.7  1997/04/20 16:31:08  brianp
  45.  * added NearFar device driver function
  46.  *
  47.  * Revision 1.6  1997/04/12 12:27:31  brianp
  48.  * added QuadFunc and RectFunc
  49.  *
  50.  * Revision 1.5  1997/03/21 01:57:07  brianp
  51.  * added RendererString() function
  52.  *
  53.  * Revision 1.4  1997/02/10 19:22:47  brianp
  54.  * added device driver Error() function
  55.  *
  56.  * Revision 1.3  1997/01/16 03:34:33  brianp
  57.  * added preliminary texture mapping functions and cleaned up documentation
  58.  *
  59.  * Revision 1.2  1996/11/13 03:51:59  brianp
  60.  * updated comments
  61.  *
  62.  * Revision 1.1  1996/09/13 01:38:16  brianp
  63.  * Initial revision
  64.  *
  65.  */
  66.  
  67.  
  68. #ifndef DD_INCLUDED
  69. #define DD_INCLUDED
  70.  
  71.  
  72. /* THIS FILE ONLY INCLUDED BY types.h !!!!! */
  73.  
  74.  
  75. /*
  76.  *                      Device Driver (DD) interface
  77.  *
  78.  *
  79.  * All device driver functions are accessed through pointers in the
  80.  * dd_function_table struct (defined below) which is stored in the GLcontext
  81.  * struct.  Since the device driver is strictly accessed trough a table of
  82.  * function pointers we can:
  83.  *   1. switch between a number of different device drivers at runtime.
  84.  *   2. use optimized functions dependant on current rendering state or
  85.  *      frame buffer configuration.
  86.  *
  87.  * The function pointers in the dd_function_table struct are divided into
  88.  * two groups:  mandatory and optional.
  89.  * Mandatory functions have to be implemented by every device driver.
  90.  * Optional functions may or may not be implemented by the device driver.
  91.  * The optional functions provide ways to take advantage of special hardware
  92.  * or optimized algorithms.
  93.  *
  94.  * The function pointers in the dd_function_table struct are first
  95.  * initialized in the "MakeCurrent" function.  The "MakeCurrent" function
  96.  * is a little different in each device driver.  See the X/Mesa, GLX, or
  97.  * OS/Mesa drivers for examples.
  98.  *
  99.  * Later, Mesa may call the dd_function_table's UpdateState() function.
  100.  * This function should initialize the dd_function_table's pointers again.
  101.  * The UpdateState() function is called whenever the core (GL) rendering
  102.  * state is changed in a way which may effect rasterization.  For example,
  103.  * the TriangleFunc() pointer may have to point to different functions
  104.  * depending on whether smooth or flat shading is enabled.
  105.  *
  106.  * Note that the first argument to every device driver function is a
  107.  * GLcontext *.  In turn, the GLcontext->DriverCtx pointer points to
  108.  * the driver-specific context struct.  See the X/Mesa or OS/Mesa interface
  109.  * for an example.
  110.  *
  111.  * For more information about writing a device driver see the ddsample.c
  112.  * file and other device drivers (xmesa[123].c, osmesa.c, etc) for examples.
  113.  *
  114.  *
  115.  * Look below in the dd_function_table struct definition for descriptions
  116.  * of each device driver function.
  117.  * 
  118.  *
  119.  * In the future more function pointers may be added for glReadPixels
  120.  * glCopyPixels, etc.
  121.  *
  122.  *
  123.  * Notes:
  124.  * ------
  125.  *   RGBA = red/green/blue/alpha
  126.  *   CI = color index (color mapped mode)
  127.  *   mono = all pixels have the same color or index
  128.  *
  129.  *   The write_ functions all take an array of mask flags which indicate
  130.  *   whether or not the pixel should be written.  One special case exists
  131.  *   in the write_color_span function: if the mask array is NULL, then
  132.  *   draw all pixels.  This is an optimization used for glDrawPixels().
  133.  *
  134.  * IN ALL CASES:
  135.  *      X coordinates start at 0 at the left and increase to the right
  136.  *      Y coordinates start at 0 at the bottom and increase upward
  137.  *
  138.  */
  139.  
  140.  
  141.  
  142.  
  143.  
  144. /*
  145.  * Device Driver function table.
  146.  */
  147. struct dd_function_table {
  148.  
  149.    /**********************************************************************
  150.     *** Mandatory functions:  these functions must be implemented by   ***
  151.     *** every device driver.                                           ***
  152.     **********************************************************************/
  153.  
  154.    const char * (*RendererString)(void);
  155.    /*
  156.     * Return a string which uniquely identifies this device driver.
  157.     * The string should contain no whitespace.  Examples: "X11" "OffScreen"
  158.     * "MSWindows" "SVGA".
  159.     */
  160.  
  161.    void (*UpdateState)( GLcontext *ctx );
  162.    /*
  163.     * UpdateState() is called whenver Mesa thinks the device driver should
  164.     * update its state and/or the other pointers (such as PointsFunc,
  165.     * LineFunc, or TriangleFunc).
  166.     */
  167.  
  168.    void (*ClearIndex)( GLcontext *ctx, GLuint index );
  169.    /*
  170.     * Called whenever glClearIndex() is called.  Set the index for clearing
  171.     * the color buffer.
  172.     */
  173.  
  174.    void (*ClearColor)( GLcontext *ctx, GLubyte red, GLubyte green,
  175.                                         GLubyte blue, GLubyte alpha );
  176.    /*
  177.     * Called whenever glClearColor() is called.  Set the color for clearing
  178.     * the color buffer.
  179.     */
  180.  
  181.    void (*Clear)( GLcontext *ctx,
  182.                   GLboolean all, GLint x, GLint y, GLint width, GLint height );
  183.    /*
  184.     * Clear the current color buffer.  If 'all' is set the clear the whole
  185.     * buffer, else clear the region defined by (x,y,width,height).
  186.     */
  187.  
  188.    void (*Index)( GLcontext *ctx, GLuint index );
  189.    /*
  190.     * Sets current color index for drawing flat-shaded primitives.
  191.     */
  192.  
  193.    void (*Color)( GLcontext *ctx,
  194.                   GLubyte red, GLubyte green, GLubyte glue, GLubyte alpha );
  195.    /*
  196.     * Sets current color for drawing flat-shaded primitives.
  197.     */
  198.  
  199.    GLboolean (*SetBuffer)( GLcontext *ctx, GLenum mode );
  200.    /*
  201.     * Selects either the front or back color buffer for reading and writing.
  202.     * mode is either GL_FRONT or GL_BACK.
  203.     */
  204.  
  205.    void (*GetBufferSize)( GLcontext *ctx,
  206.                           GLuint *width, GLuint *height );
  207.    /*
  208.     * Returns the width and height of the current color buffer.
  209.     */
  210.  
  211.  
  212.    /***
  213.     *** Functions for writing pixels to the frame buffer:
  214.     ***/
  215.    void (*WriteColorSpan)( GLcontext *ctx,
  216.                            GLuint n, GLint x, GLint y,
  217.                const GLubyte red[], const GLubyte green[],
  218.                const GLubyte blue[], const GLubyte alpha[],
  219.                const GLubyte mask[] );
  220.    /*
  221.     * Write a horizontal run of RGBA pixels.
  222.     */
  223.  
  224.    void (*WriteMonocolorSpan)( GLcontext *ctx,
  225.                                GLuint n, GLint x, GLint y,
  226.                    const GLubyte mask[] );
  227.    /*
  228.     * Write a horizontal run of mono-RGBA pixels.
  229.     */
  230.  
  231.    void (*WriteColorPixels)( GLcontext *ctx,
  232.                              GLuint n, const GLint x[], const GLint y[],
  233.                  const GLubyte red[], const GLubyte green[],
  234.                  const GLubyte blue[], const GLubyte alpha[],
  235.                  const GLubyte mask[] );
  236.    /*
  237.     * Write an array of RGBA pixels at random locations.
  238.     */
  239.  
  240.    void (*WriteMonocolorPixels)( GLcontext *ctx,
  241.                                  GLuint n, const GLint x[], const GLint y[],
  242.                  const GLubyte mask[] );
  243.    /*
  244.     * Write an array of mono-RGBA pixels at random locations.
  245.     */
  246.  
  247.    void (*WriteIndexSpan)( GLcontext *ctx,
  248.                            GLuint n, GLint x, GLint y, const GLuint index[],
  249.                            const GLubyte mask[] );
  250.    /*
  251.     * Write a horizontal run of CI pixels.
  252.     */
  253.  
  254.    void (*WriteMonoindexSpan)( GLcontext *ctx,
  255.                                GLuint n, GLint x, GLint y,
  256.                    const GLubyte mask[] );
  257.    /*
  258.     * Write a horizontal run of mono-CI pixels.
  259.     */
  260.  
  261.    void (*WriteIndexPixels)( GLcontext *ctx,
  262.                              GLuint n, const GLint x[], const GLint y[],
  263.                              const GLuint index[], const GLubyte mask[] );
  264.    /*
  265.     * Write a random array of CI pixels.
  266.     */
  267.  
  268.    void (*WriteMonoindexPixels)( GLcontext *ctx,
  269.                                  GLuint n, const GLint x[], const GLint y[],
  270.                  const GLubyte mask[] );
  271.    /*
  272.     * Write a random array of mono-CI pixels.
  273.     */
  274.  
  275.    /***
  276.     *** Functions to read pixels from frame buffer:
  277.     ***/
  278.    void (*ReadIndexSpan)( GLcontext *ctx,
  279.                           GLuint n, GLint x, GLint y, GLuint index[] );
  280.    /*
  281.     * Read a horizontal run of color index pixels.
  282.     */
  283.  
  284.    void (*ReadColorSpan)( GLcontext *ctx,
  285.                           GLuint n, GLint x, GLint y,
  286.               GLubyte red[], GLubyte green[],
  287.               GLubyte blue[], GLubyte alpha[] );
  288.    /*
  289.     * Read a horizontal run of RGBA pixels.
  290.     */
  291.  
  292.    void (*ReadIndexPixels)( GLcontext *ctx,
  293.                             GLuint n, const GLint x[], const GLint y[],
  294.                 GLuint indx[], const GLubyte mask[] );
  295.    /*
  296.     * Read a random array of CI pixels.
  297.     */
  298.  
  299.    void (*ReadColorPixels)( GLcontext *ctx,
  300.                             GLuint n, const GLint x[], const GLint y[],
  301.                 GLubyte red[], GLubyte green[],
  302.                 GLubyte blue[], GLubyte alpha[],
  303.                             const GLubyte mask[] );
  304.    /*
  305.     * Read a random array of RGBA pixels.
  306.     */
  307.  
  308.  
  309.    /**********************************************************************
  310.     *** Optional functions:  these functions may or may not be         ***
  311.     *** implemented by the device driver.  If the device driver        ***
  312.     *** doesn't implement them it should never touch these pointers    ***
  313.     *** since Mesa will either set them to NULL or point them at a     ***
  314.     *** fall-back function.                                            ***
  315.     **********************************************************************/
  316.  
  317.    void (*Finish)( GLcontext *ctx );
  318.    /*
  319.     * Called whenever glFinish() is called.
  320.     */
  321.  
  322.    void (*Flush)( GLcontext *ctx );
  323.    /*
  324.     * Called whenever glFlush() is called.
  325.     */
  326.  
  327.    GLboolean (*IndexMask)( GLcontext *ctx, GLuint mask );
  328.    /*
  329.     * Implements glIndexMask() if possible, else return GL_FALSE.
  330.     */
  331.  
  332.    GLboolean (*ColorMask)( GLcontext *ctx,
  333.                            GLboolean rmask, GLboolean gmask,
  334.                            GLboolean bmask, GLboolean amask );
  335.    /*
  336.     * Implements glColorMask() if possible, else return GL_FALSE.
  337.     */
  338.  
  339.    GLboolean (*LogicOp)( GLcontext *ctx, GLenum op );
  340.    /*
  341.     * Implements glLogicOp() if possible, else return GL_FALSE.
  342.     */
  343.  
  344.    void (*Dither)( GLcontext *ctx, GLboolean enable );
  345.    /*
  346.     * Enable/disable dithering.
  347.     */
  348.  
  349.    void (*Error)( GLcontext *ctx );
  350.    /*
  351.     * Called whenever an error is generated.  ctx->ErrorValue contains
  352.     * the error value.
  353.     */
  354.  
  355.    void (*NearFar)( GLcontext *ctx, GLfloat nearVal, GLfloat farVal );
  356.    /*
  357.     * Called from glFrustum and glOrtho to tell device driver the
  358.     * near and far clipping plane Z values.  The 3Dfx driver, for example,
  359.     * uses this.
  360.     */
  361.  
  362.  
  363.    /***
  364.     *** For supporting hardware Z buffers:
  365.     ***/
  366.  
  367.    void (*AllocDepthBuffer)( GLcontext *ctx );
  368.    /*
  369.     * Called when the depth buffer must be allocated or possibly resized.
  370.     */
  371.  
  372.    void (*ClearDepthBuffer)( GLcontext *ctx );
  373.    /*
  374.     * Clear the depth buffer to depth specified by CC.Depth.Clear value.
  375.     */
  376.  
  377.    GLuint (*DepthTestSpan)( GLcontext *ctx,
  378.                             GLuint n, GLint x, GLint y, const GLdepth z[],
  379.                             GLubyte mask[] );
  380.    void (*DepthTestPixels)( GLcontext *ctx,
  381.                             GLuint n, const GLint x[], const GLint y[],
  382.                             const GLdepth z[], GLubyte mask[] );
  383.    /*
  384.     * Apply the depth buffer test to an span/array of pixels and return
  385.     * an updated pixel mask.  This function is not used when accelerated
  386.     * point, line, polygon functions are used.
  387.     */
  388.  
  389.    void (*ReadDepthSpanFloat)( GLcontext *ctx,
  390.                                GLuint n, GLint x, GLint y, GLfloat depth[]);
  391.    void (*ReadDepthSpanInt)( GLcontext *ctx,
  392.                              GLuint n, GLint x, GLint y, GLdepth depth[] );
  393.    /*
  394.     * Return depth values as integers for glReadPixels.
  395.     * Floats should be returned in the range [0,1].
  396.     * Ints (GLdepth) values should be in the range [0,MAXDEPTH].
  397.     */
  398.  
  399.  
  400.    /***
  401.     *** Accelerated point, line, polygon, glDrawPixels and glBitmap functions:
  402.     ***/
  403.  
  404.    points_func PointsFunc;
  405.    /*
  406.     * Called to draw an array of points.
  407.     */
  408.  
  409.    line_func LineFunc;
  410.    /*
  411.     * Called to draw a line segment.
  412.     */
  413.  
  414.    triangle_func TriangleFunc;
  415.    /* 
  416.     * Called to draw a filled triangle.
  417.     */
  418.  
  419.    quad_func QuadFunc;
  420.    /* 
  421.     * Called to draw a filled quadrilateral.
  422.     */
  423.  
  424.    rect_func RectFunc;
  425.    /* 
  426.     * Called to draw a filled, screen-aligned 2-D rectangle.
  427.     */
  428.  
  429.    GLboolean (*DrawPixels)( GLcontext *ctx,
  430.                             GLint x, GLint y, GLsizei width, GLsizei height,
  431.                             GLenum format, GLenum type, GLboolean packed,
  432.                             const GLvoid *pixels );
  433.    /*
  434.     * Called from glDrawPixels().
  435.     */
  436.  
  437.    GLboolean (*Bitmap)( GLcontext *ctx, GLsizei width, GLsizei height,
  438.                         GLfloat xorig, GLfloat yorig,
  439.                         GLfloat xmove, GLfloat ymove,
  440.                         const struct gl_image *bitmap );
  441.    /*
  442.     * Called from glBitmap().
  443.     */
  444.  
  445.    void (*Begin)( GLcontext *ctx, GLenum mode );
  446.    void (*End)( GLcontext *ctx );
  447.    /*
  448.     * These are called whenever glBegin() or glEnd() are called.
  449.     * The device driver may do some sort of window locking/unlocking here.
  450.     */
  451.  
  452.  
  453.    void (*RasterSetup)( GLcontext *ctx, GLuint start, GLuint end );
  454.    /*
  455.     * This function, if not NULL, is called whenever new window coordinates
  456.     * are put in the vertex buffer.  The vertices in question are those n
  457.     * such that start <= n < end.
  458.     * The device driver can convert the window coords to its own specialized
  459.     * format.  The 3Dfx driver uses this.
  460.     */
  461.  
  462.    GLboolean (*RenderVB)( GLcontext *ctx, GLboolean allDone );
  463.    /*
  464.     * This function allows the device driver to rasterize an entire
  465.     * buffer of primitives at once.  See the gl_render_vb() function
  466.     * in vbrender.c for more details.
  467.     * Return GL_TRUE if vertex buffer successfully rendered.
  468.     * Return GL_FALSE if failure, let core Mesa render the vertex buffer.
  469.     */
  470.  
  471.    /***
  472.     *** Texture mapping functions:
  473.     ***/
  474.  
  475.    void (*TexEnv)( GLcontext *ctx, GLenum pname, const GLfloat *param );
  476.    /*
  477.     * Called whenever glTexEnv*() is called.
  478.     * Pname will be one of GL_TEXTURE_ENV_MODE or GL_TEXTURE_ENV_COLOR.
  479.     * If pname is GL_TEXTURE_ENV_MODE then param will be one
  480.     * of GL_MODULATE, GL_BLEND, GL_DECAL, or GL_REPLACE.
  481.     */
  482.  
  483.    void (*TexImage)( GLcontext *ctx, GLenum target,
  484.                      struct gl_texture_object *tObj, GLint level,
  485.                      GLint internalFormat,
  486.                      const struct gl_texture_image *image );
  487.    /*
  488.     * Called whenever a texture object's image is changed.
  489.     *    texObject is the number of the texture object being changed.
  490.     *    level indicates the mipmap level.
  491.     *    internalFormat is the format in which the texture is to be stored.
  492.     *    image is a pointer to a gl_texture_image struct which contains
  493.     *       the actual image data.
  494.     */
  495.  
  496.    void (*TexParameter)( GLcontext *ctx, GLenum target,
  497.                          struct gl_texture_object *tObj,
  498.                          GLenum pname, const GLfloat *params );
  499.    /*
  500.     * Called whenever glTexParameter*() is called.
  501.     *    target is GL_TEXTURE_1D or GL_TEXTURE_2D
  502.     *    texObject is the texture object to modify
  503.     *    pname is one of GL_TEXTURE_MIN_FILTER, GL_TEXTURE_MAG_FILTER,
  504.     *       GL_TEXTURE_WRAP_S, GL_TEXTURE_WRAP_T, or GL_TEXTURE_BORDER_COLOR.
  505.     *    params is dependant on pname.  See man glTexParameter.
  506.     */
  507.  
  508.    void (*BindTexture)( GLcontext *ctx, GLenum target,
  509.                         struct gl_texture_object *tObj );
  510.    /*
  511.     * Called whenever glBindTexture() is called.  This specifies which
  512.     * texture is to be the current one.
  513.     */
  514.  
  515.    void (*DeleteTexture)( GLcontext *ctx, struct gl_texture_object *tObj );
  516.    /*
  517.     * Called when a texture object can be deallocated.
  518.     */
  519.  
  520.    void (*UpdateTexturePalette)( GLcontext *ctx,
  521.                                  struct gl_texture_object *tObj );
  522.    /*
  523.     * Called when the texture's color lookup table is changed.
  524.     * If tObj is NULL then the shared texture palette ctx->Texture.Palette
  525.     * was changed.
  526.     */
  527.  
  528.    void (*UseGlobalTexturePalette)( GLcontext *ctx, GLboolean state );
  529.    /*
  530.     * Called via glEnable/Disable(GL_SHARED_TEXTURE_PALETTE_EXT)
  531.     */
  532.  
  533. };
  534.  
  535.  
  536.  
  537. #endif
  538.  
  539.