include/GL/osmesa.h

   1 /* $Id: osmesa.h,v 1.9 2001/09/23 16:06:13 brianp Exp $ */
   2
   3 /*
   4  * Mesa 3-D graphics library
   5  * Version:  4.0
   6  *
   7  * Copyright (C) 1999-2001  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  * Mesa Off-Screen rendering interface.
  30  *
  31  * This is an operating system and window system independent interface to
  32  * Mesa which allows one to render images into a client-supplied buffer in
  33  * main memory.  Such images may manipulated or saved in whatever way the
  34  * client wants.
  35  *
  36  * These are the API functions:
  37  *   OSMesaCreateContext - create a new Off-Screen Mesa rendering context
  38  *   OSMesaMakeCurrent - bind an OSMesaContext to a client's image buffer
  39  *                       and make the specified context the current one.
  40  *   OSMesaDestroyContext - destroy an OSMesaContext
  41  *   OSMesaGetCurrentContext - return thread's current context ID
  42  *   OSMesaPixelStore - controls how pixels are stored in image buffer
  43  *   OSMesaGetIntegerv - return OSMesa state parameters
  44  *
  45  *
  46  * The limits on the width and height of an image buffer are MAX_WIDTH and
  47  * MAX_HEIGHT as defined in Mesa/src/config.h.  Defaults are 1280 and 1024.
  48  * You can increase them as needed but beware that many temporary arrays in
  49  * Mesa are dimensioned by MAX_WIDTH or MAX_HEIGHT.
  50  */
  51
  52
  53 #ifndef OSMESA_H
  54 #define OSMESA_H
  55
  56
  57 #ifdef __cplusplus
  58 extern "C" {
  59 #endif
  60
  61
  62 #include <GL/gl.h>
  63
  64
  65 #define OSMESA_MAJOR_VERSION 4
  66 #define OSMESA_MINOR_VERSION 0
  67 #define OSMESA_PATCH_VERSION 0
  68
  69
  70
  71 /*
  72  * Values for the format parameter of OSMesaCreateContext()
  73  * New in version 2.0.
  74  */
  75 #define OSMESA_COLOR_INDEX      GL_COLOR_INDEX
  76 #define OSMESA_RGBA             GL_RGBA
  77 #define OSMESA_BGRA             0x1
  78 #define OSMESA_ARGB             0x2
  79 #define OSMESA_RGB              GL_RGB
  80 #define OSMESA_BGR              0x4
  81 #define OSMESA_RGB_565          0x5
  82
  83
  84 /*
  85  * OSMesaPixelStore() parameters:
  86  * New in version 2.0.
  87  */
  88 #define OSMESA_ROW_LENGTH       0x10
  89 #define OSMESA_Y_UP             0x11
  90
  91
  92 /*
  93  * Accepted by OSMesaGetIntegerv:
  94  */
  95 #define OSMESA_WIDTH            0x20
  96 #define OSMESA_HEIGHT           0x21
  97 #define OSMESA_FORMAT           0x22
  98 #define OSMESA_TYPE             0x23
  99 #define OSMESA_MAX_WIDTH        0x24  /* new in 4.0 */
 100 #define OSMESA_MAX_HEIGHT       0x25  /* new in 4.0 */
 101
 102
 103 typedef struct osmesa_context *OSMesaContext;
 104
 105
 106 #if defined(__BEOS__) || defined(__QUICKDRAW__)
 107 #pragma export on
 108 #endif
 109
 110
 111 /*
 112  * Create an Off-Screen Mesa rendering context.  The only attribute needed is
 113  * an RGBA vs Color-Index mode flag.
 114  *
 115  * Input:  format - one of OSMESA_COLOR_INDEX, OSMESA_RGBA, OSMESA_BGRA,
 116  *                  OSMESA_ARGB, OSMESA_RGB, or OSMESA_BGR.
 117  *         sharelist - specifies another OSMesaContext with which to share
 118  *                     display lists.  NULL indicates no sharing.
 119  * Return:  an OSMesaContext or 0 if error
 120  */
 121 GLAPI OSMesaContext GLAPIENTRY
 122 OSMesaCreateContext( GLenum format, OSMesaContext sharelist );
 123
 124
 125
 126 /*
 127  * Create an Off-Screen Mesa rendering context and specify desired
 128  * size of depth buffer, stencil buffer and accumulation buffer.
 129  * If you specify zero for depthBits, stencilBits, accumBits you
 130  * can save some memory.
 131  *
 132  * New in Mesa 3.5
 133  */
 134 GLAPI OSMesaContext GLAPIENTRY
 135 OSMesaCreateContextExt( GLenum format, GLint depthBits, GLint stencilBits,
 136                         GLint accumBits, OSMesaContext sharelist);
 137
 138
 139 /*
 140  * Destroy an Off-Screen Mesa rendering context.
 141  *
 142  * Input:  ctx - the context to destroy
 143  */
 144 GLAPI void GLAPIENTRY
 145 OSMesaDestroyContext( OSMesaContext ctx );
 146
 147
 148
 149 /*
 150  * Bind an OSMesaContext to an image buffer.  The image buffer is just a
 151  * block of memory which the client provides.  Its size must be at least
 152  * as large as width*height*sizeof(type).  Its address should be a multiple
 153  * of 4 if using RGBA mode.
 154  *
 155  * Image data is stored in the order of glDrawPixels:  row-major order
 156  * with the lower-left image pixel stored in the first array position
 157  * (ie. bottom-to-top).
 158  *
 159  * Since the only type initially supported is GL_UNSIGNED_BYTE, if the
 160  * context is in RGBA mode, each pixel will be stored as a 4-byte RGBA
 161  * value.  If the context is in color indexed mode, each pixel will be
 162  * stored as a 1-byte value.
 163  *
 164  * If the context's viewport hasn't been initialized yet, it will now be
 165  * initialized to (0,0,width,height).
 166  *
 167  * Input:  ctx - the rendering context
 168  *         buffer - the image buffer memory
 169  *         type - data type for pixel components, only GL_UNSIGNED_BYTE
 170  *                supported now
 171  *         width, height - size of image buffer in pixels, at least 1
 172  * Return:  GL_TRUE if success, GL_FALSE if error because of invalid ctx,
 173  *          invalid buffer address, type!=GL_UNSIGNED_BYTE, width<1, height<1,
 174  *          width>internal limit or height>internal limit.
 175  */
 176 GLAPI GLboolean GLAPIENTRY
 177 OSMesaMakeCurrent( OSMesaContext ctx, void *buffer, GLenum type,
 178                    GLsizei width, GLsizei height );
 179
 180
 181
 182
 183 /*
 184  * Return the current Off-Screen Mesa rendering context handle.
 185  */
 186 GLAPI OSMesaContext GLAPIENTRY
 187 OSMesaGetCurrentContext( void );
 188
 189
 190
 191 /*
 192  * Set pixel store/packing parameters for the current context.
 193  * This is similar to glPixelStore.
 194  * Input:  pname - OSMESA_ROW_LENGTH
 195  *                    specify actual pixels per row in image buffer
 196  *                    0 = same as image width (default)
 197  *                 OSMESA_Y_UP
 198  *                    zero = Y coordinates increase downward
 199  *                    non-zero = Y coordinates increase upward (default)
 200  *         value - the value for the parameter pname
 201  *
 202  * New in version 2.0.
 203  */
 204 GLAPI void GLAPIENTRY
 205 OSMesaPixelStore( GLint pname, GLint value );
 206
 207
 208
 209 /*
 210  * Return an integer value like glGetIntegerv.
 211  * Input:  pname -
 212  *                 OSMESA_WIDTH  return current image width
 213  *                 OSMESA_HEIGHT  return current image height
 214  *                 OSMESA_FORMAT  return image format
 215  *                 OSMESA_TYPE  return color component data type
 216  *                 OSMESA_ROW_LENGTH return row length in pixels
 217  *                 OSMESA_Y_UP returns 1 or 0 to indicate Y axis direction
 218  *         value - pointer to integer in which to return result.
 219  */
 220 GLAPI void GLAPIENTRY
 221 OSMesaGetIntegerv( GLint pname, GLint *value );
 222
 223
 224
 225 /*
 226  * Return the depth buffer associated with an OSMesa context.
 227  * Input:  c - the OSMesa context
 228  * Output:  width, height - size of buffer in pixels
 229  *          bytesPerValue - bytes per depth value (2 or 4)
 230  *          buffer - pointer to depth buffer values
 231  * Return:  GL_TRUE or GL_FALSE to indicate success or failure.
 232  *
 233  * New in Mesa 2.4.
 234  */
 235 GLAPI GLboolean GLAPIENTRY
 236 OSMesaGetDepthBuffer( OSMesaContext c, GLint *width, GLint *height,
 237                       GLint *bytesPerValue, void **buffer );
 238
 239
 240
 241 /*
 242  * Return the color buffer associated with an OSMesa context.
 243  * Input:  c - the OSMesa context
 244  * Output:  width, height - size of buffer in pixels
 245  *          format - buffer format (OSMESA_FORMAT)
 246  *          buffer - pointer to depth buffer values
 247  * Return:  GL_TRUE or GL_FALSE to indicate success or failure.
 248  *
 249  * New in Mesa 3.3.
 250  */
 251 GLAPI GLboolean GLAPIENTRY
 252 OSMesaGetColorBuffer( OSMesaContext c, GLint *width, GLint *height,
 253                       GLint *format, void **buffer );
 254
 255
 256
 257 #if defined(__BEOS__) || defined(__QUICKDRAW__)
 258 #pragma export off
 259 #endif
 260
 261
 262 #ifdef __cplusplus
 263 }
 264 #endif
 265
 266
 267 #endif