include/GL/osmesa.h

   1 /*
   2  * Mesa 3-D graphics library
   3  *
   4  * Copyright (C) 1999-2005  Brian Paul   All Rights Reserved.
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a
   7  * copy of this software and associated documentation files (the "Software"),
   8  * to deal in the Software without restriction, including without limitation
   9  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  10  * and/or sell copies of the Software, and to permit persons to whom the
  11  * Software is furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included
  14  * in all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  17  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  19  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
  20  * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  21  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  22  * OTHER DEALINGS IN THE SOFTWARE.
  23  */
  24
  25
  26 /*
  27  * Mesa Off-Screen rendering interface.
  28  *
  29  * This is an operating system and window system independent interface to
  30  * Mesa which allows one to render images into a client-supplied buffer in
  31  * main memory.  Such images may manipulated or saved in whatever way the
  32  * client wants.
  33  *
  34  * These are the API functions:
  35  *   OSMesaCreateContext - create a new Off-Screen Mesa rendering context
  36  *   OSMesaMakeCurrent - bind an OSMesaContext to a client's image buffer
  37  *                       and make the specified context the current one.
  38  *   OSMesaDestroyContext - destroy an OSMesaContext
  39  *   OSMesaGetCurrentContext - return thread's current context ID
  40  *   OSMesaPixelStore - controls how pixels are stored in image buffer
  41  *   OSMesaGetIntegerv - return OSMesa state parameters
  42  *
  43  *
  44  * The limits on the width and height of an image buffer can be retrieved
  45  * via OSMesaGetIntegerv(OSMESA_MAX_WIDTH/OSMESA_MAX_HEIGHT).
  46  */
  47
  48
  49 #ifndef OSMESA_H
  50 #define OSMESA_H
  51
  52
  53 #ifdef __cplusplus
  54 extern "C" {
  55 #endif
  56
  57
  58 #include <GL/gl.h>
  59
  60
  61 #define OSMESA_MAJOR_VERSION 11
  62 #define OSMESA_MINOR_VERSION 2
  63 #define OSMESA_PATCH_VERSION 0
  64
  65
  66
  67 /*
  68  * Values for the format parameter of OSMesaCreateContext()
  69  * New in version 2.0.
  70  */
  71 #define OSMESA_COLOR_INDEX      GL_COLOR_INDEX
  72 #define OSMESA_RGBA             GL_RGBA
  73 #define OSMESA_BGRA             0x1
  74 #define OSMESA_ARGB             0x2
  75 #define OSMESA_RGB              GL_RGB
  76 #define OSMESA_BGR              0x4
  77 #define OSMESA_RGB_565          0x5
  78
  79
  80 /*
  81  * OSMesaPixelStore() parameters:
  82  * New in version 2.0.
  83  */
  84 #define OSMESA_ROW_LENGTH       0x10
  85 #define OSMESA_Y_UP             0x11
  86
  87
  88 /*
  89  * Accepted by OSMesaGetIntegerv:
  90  */
  91 #define OSMESA_WIDTH            0x20
  92 #define OSMESA_HEIGHT           0x21
  93 #define OSMESA_FORMAT           0x22
  94 #define OSMESA_TYPE             0x23
  95 #define OSMESA_MAX_WIDTH        0x24  /* new in 4.0 */
  96 #define OSMESA_MAX_HEIGHT       0x25  /* new in 4.0 */
  97
  98 /*
  99  * Accepted in OSMesaCreateContextAttrib's attribute list.
 100  */
 101 #define OSMESA_DEPTH_BITS            0x30
 102 #define OSMESA_STENCIL_BITS          0x31
 103 #define OSMESA_ACCUM_BITS            0x32
 104 #define OSMESA_PROFILE               0x33
 105 #define OSMESA_CORE_PROFILE          0x34
 106 #define OSMESA_COMPAT_PROFILE        0x35
 107 #define OSMESA_CONTEXT_MAJOR_VERSION 0x36
 108 #define OSMESA_CONTEXT_MINOR_VERSION 0x37
 109
 110
 111 typedef struct osmesa_context *OSMesaContext;
 112
 113
 114 /*
 115  * Create an Off-Screen Mesa rendering context.  The only attribute needed is
 116  * an RGBA vs Color-Index mode flag.
 117  *
 118  * Input:  format - one of OSMESA_COLOR_INDEX, OSMESA_RGBA, OSMESA_BGRA,
 119  *                  OSMESA_ARGB, OSMESA_RGB, or OSMESA_BGR.
 120  *         sharelist - specifies another OSMesaContext with which to share
 121  *                     display lists.  NULL indicates no sharing.
 122  * Return:  an OSMesaContext or 0 if error
 123  */
 124 GLAPI OSMesaContext GLAPIENTRY
 125 OSMesaCreateContext( GLenum format, OSMesaContext sharelist );
 126
 127
 128
 129 /*
 130  * Create an Off-Screen Mesa rendering context and specify desired
 131  * size of depth buffer, stencil buffer and accumulation buffer.
 132  * If you specify zero for depthBits, stencilBits, accumBits you
 133  * can save some memory.
 134  *
 135  * New in Mesa 3.5
 136  */
 137 GLAPI OSMesaContext GLAPIENTRY
 138 OSMesaCreateContextExt( GLenum format, GLint depthBits, GLint stencilBits,
 139                         GLint accumBits, OSMesaContext sharelist);
 140
 141
 142 /*
 143  * Create an Off-Screen Mesa rendering context with attribute list.
 144  * The list is composed of (attribute, value) pairs and terminated with
 145  * attribute==0.  Supported Attributes:
 146  *
 147  * Attributes                    Values
 148  * --------------------------------------------------------------------------
 149  * OSMESA_FORMAT                 OSMESA_RGBA*, OSMESA_BGRA, OSMESA_ARGB, etc.
 150  * OSMESA_DEPTH_BITS             0*, 16, 24, 32
 151  * OSMESA_STENCIL_BITS           0*, 8
 152  * OSMESA_ACCUM_BITS             0*, 16
 153  * OSMESA_PROFILE                OSMESA_COMPAT_PROFILE*, OSMESA_CORE_PROFILE
 154  * OSMESA_CONTEXT_MAJOR_VERSION  1*, 2, 3
 155  * OSMESA_CONTEXT_MINOR_VERSION  0+
 156  *
 157  * Note: * = default value
 158  *
 159  * We return a context version >= what's specified by OSMESA_CONTEXT_MAJOR/
 160  * MINOR_VERSION for the given profile.  For example, if you request a GL 1.4
 161  * compat profile, you might get a GL 3.0 compat profile.
 162  * Otherwise, null is returned if the version/profile is not supported.
 163  *
 164  * New in Mesa 11.2
 165  */
 166 GLAPI OSMesaContext GLAPIENTRY
 167 OSMesaCreateContextAttribs( const int *attribList, OSMesaContext sharelist );
 168
 169
 170
 171 /*
 172  * Destroy an Off-Screen Mesa rendering context.
 173  *
 174  * Input:  ctx - the context to destroy
 175  */
 176 GLAPI void GLAPIENTRY
 177 OSMesaDestroyContext( OSMesaContext ctx );
 178
 179
 180
 181 /*
 182  * Bind an OSMesaContext to an image buffer.  The image buffer is just a
 183  * block of memory which the client provides.  Its size must be at least
 184  * as large as width*height*sizeof(type).  Its address should be a multiple
 185  * of 4 if using RGBA mode.
 186  *
 187  * Image data is stored in the order of glDrawPixels:  row-major order
 188  * with the lower-left image pixel stored in the first array position
 189  * (ie. bottom-to-top).
 190  *
 191  * Since the only type initially supported is GL_UNSIGNED_BYTE, if the
 192  * context is in RGBA mode, each pixel will be stored as a 4-byte RGBA
 193  * value.  If the context is in color indexed mode, each pixel will be
 194  * stored as a 1-byte value.
 195  *
 196  * If the context's viewport hasn't been initialized yet, it will now be
 197  * initialized to (0,0,width,height).
 198  *
 199  * Input:  ctx - the rendering context
 200  *         buffer - the image buffer memory
 201  *         type - data type for pixel components, only GL_UNSIGNED_BYTE
 202  *                supported now
 203  *         width, height - size of image buffer in pixels, at least 1
 204  * Return:  GL_TRUE if success, GL_FALSE if error because of invalid ctx,
 205  *          invalid buffer address, type!=GL_UNSIGNED_BYTE, width<1, height<1,
 206  *          width>internal limit or height>internal limit.
 207  */
 208 GLAPI GLboolean GLAPIENTRY
 209 OSMesaMakeCurrent( OSMesaContext ctx, void *buffer, GLenum type,
 210                    GLsizei width, GLsizei height );
 211
 212
 213
 214
 215 /*
 216  * Return the current Off-Screen Mesa rendering context handle.
 217  */
 218 GLAPI OSMesaContext GLAPIENTRY
 219 OSMesaGetCurrentContext( void );
 220
 221
 222
 223 /*
 224  * Set pixel store/packing parameters for the current context.
 225  * This is similar to glPixelStore.
 226  * Input:  pname - OSMESA_ROW_LENGTH
 227  *                    specify actual pixels per row in image buffer
 228  *                    0 = same as image width (default)
 229  *                 OSMESA_Y_UP
 230  *                    zero = Y coordinates increase downward
 231  *                    non-zero = Y coordinates increase upward (default)
 232  *         value - the value for the parameter pname
 233  *
 234  * New in version 2.0.
 235  */
 236 GLAPI void GLAPIENTRY
 237 OSMesaPixelStore( GLint pname, GLint value );
 238
 239
 240
 241 /*
 242  * Return an integer value like glGetIntegerv.
 243  * Input:  pname -
 244  *                 OSMESA_WIDTH  return current image width
 245  *                 OSMESA_HEIGHT  return current image height
 246  *                 OSMESA_FORMAT  return image format
 247  *                 OSMESA_TYPE  return color component data type
 248  *                 OSMESA_ROW_LENGTH return row length in pixels
 249  *                 OSMESA_Y_UP returns 1 or 0 to indicate Y axis direction
 250  *         value - pointer to integer in which to return result.
 251  */
 252 GLAPI void GLAPIENTRY
 253 OSMesaGetIntegerv( GLint pname, GLint *value );
 254
 255
 256
 257 /*
 258  * Return the depth buffer associated with an OSMesa context.
 259  * Input:  c - the OSMesa context
 260  * Output:  width, height - size of buffer in pixels
 261  *          bytesPerValue - bytes per depth value (2 or 4)
 262  *          buffer - pointer to depth buffer values
 263  * Return:  GL_TRUE or GL_FALSE to indicate success or failure.
 264  *
 265  * New in Mesa 2.4.
 266  */
 267 GLAPI GLboolean GLAPIENTRY
 268 OSMesaGetDepthBuffer( OSMesaContext c, GLint *width, GLint *height,
 269                       GLint *bytesPerValue, void **buffer );
 270
 271
 272
 273 /*
 274  * Return the color buffer associated with an OSMesa context.
 275  * Input:  c - the OSMesa context
 276  * Output:  width, height - size of buffer in pixels
 277  *          format - buffer format (OSMESA_FORMAT)
 278  *          buffer - pointer to depth buffer values
 279  * Return:  GL_TRUE or GL_FALSE to indicate success or failure.
 280  *
 281  * New in Mesa 3.3.
 282  */
 283 GLAPI GLboolean GLAPIENTRY
 284 OSMesaGetColorBuffer( OSMesaContext c, GLint *width, GLint *height,
 285                       GLint *format, void **buffer );
 286
 287
 288
 289 /**
 290  * This typedef is new in Mesa 6.3.
 291  */
 292 typedef void (*OSMESAproc)();
 293
 294
 295 /*
 296  * Return pointer to the named function.
 297  * New in Mesa 4.1
 298  * Return OSMESAproc in 6.3.
 299  */
 300 GLAPI OSMESAproc GLAPIENTRY
 301 OSMesaGetProcAddress( const char *funcName );
 302
 303
 304
 305 /**
 306  * Enable/disable color clamping, off by default.
 307  * New in Mesa 6.4.2
 308  */
 309 GLAPI void GLAPIENTRY
 310 OSMesaColorClamp(GLboolean enable);
 311
 312
 313 /**
 314  * Enable/disable Gallium post-process filters.
 315  * This should be called after a context is created, but before it is
 316  * made current for the first time.  After a context has been made
 317  * current, this function has no effect.
 318  * If the enable_value param is zero, the filter is disabled.  Otherwise
 319  * the filter is enabled, and the value may control the filter's quality.
 320  * New in Mesa 10.0
 321  */
 322 GLAPI void GLAPIENTRY
 323 OSMesaPostprocess(OSMesaContext osmesa, const char *filter,
 324                   unsigned enable_value);
 325
 326
 327 #ifdef __cplusplus
 328 }
 329 #endif
 330
 331
 332 #endif