src/mesa/drivers/x11/xmesa.h

   1 /*
   2  * Mesa 3-D graphics library
   3  *
   4  * Copyright (C) 1999-2007  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/X11 interface.  This header file serves as the documentation for
  28  * the Mesa/X11 interface functions.
  29  *
  30  * Note: this interface isn't intended for user programs.  It's primarily
  31  * just for implementing the pseudo-GLX interface.
  32  */
  33
  34
  35 /* Sample Usage:
  36
  37 In addition to the usual X calls to select a visual, create a colormap
  38 and create a window, you must do the following to use the X/Mesa interface:
  39
  40 1. Call XMesaCreateVisual() to make an XMesaVisual from an XVisualInfo.
  41
  42 2. Call XMesaCreateContext() to create an X/Mesa rendering context, given
  43    the XMesaVisual.
  44
  45 3. Call XMesaCreateWindowBuffer() to create an XMesaBuffer from an X window
  46    and XMesaVisual.
  47
  48 4. Call XMesaMakeCurrent() to bind the XMesaBuffer to an XMesaContext and
  49    to make the context the current one.
  50
  51 5. Make gl* calls to render your graphics.
  52
  53 6. Use XMesaSwapBuffers() when double buffering to swap front/back buffers.
  54
  55 7. Before the X window is destroyed, call XMesaDestroyBuffer().
  56
  57 8. Before exiting, call XMesaDestroyVisual and XMesaDestroyContext.
  58
  59 */
  60
  61
  62
  63
  64 #ifndef XMESA_H
  65 #define XMESA_H
  66
  67 #include <X11/Xlib.h>
  68 #include <X11/Xutil.h>
  69 #include "xmesa_x.h"
  70 #include "GL/gl.h"
  71
  72 #ifdef __cplusplus
  73 extern "C" {
  74 #endif
  75
  76 #define XMESA_MAJOR_VERSION 6
  77 #define XMESA_MINOR_VERSION 3
  78
  79
  80
  81 /*
  82  * Values passed to XMesaGetString:
  83  */
  84 #define XMESA_VERSION 1
  85 #define XMESA_EXTENSIONS 2
  86
  87
  88 typedef struct xmesa_context *XMesaContext;
  89
  90 typedef struct xmesa_visual *XMesaVisual;
  91
  92 typedef struct xmesa_buffer *XMesaBuffer;
  93
  94
  95
  96 /*
  97  * Create a new X/Mesa visual.
  98  * Input:  display - X11 display
  99  *         visinfo - an XVisualInfo pointer
 100  *         rgb_flag - GL_TRUE = RGB mode,
 101  *                    GL_FALSE = color index mode
 102  *         alpha_flag - alpha buffer requested?
 103  *         db_flag - GL_TRUE = double-buffered,
 104  *                   GL_FALSE = single buffered
 105  *         stereo_flag - stereo visual?
 106  *         ximage_flag - GL_TRUE = use an XImage for back buffer,
 107  *                       GL_FALSE = use an off-screen pixmap for back buffer
 108  *         depth_size - requested bits/depth values, or zero
 109  *         stencil_size - requested bits/stencil values, or zero
 110  *         accum_red_size - requested bits/red accum values, or zero
 111  *         accum_green_size - requested bits/green accum values, or zero
 112  *         accum_blue_size - requested bits/blue accum values, or zero
 113  *         accum_alpha_size - requested bits/alpha accum values, or zero
 114  *         num_samples - number of samples/pixel if multisampling, or zero
 115  *         level - visual level, usually 0
 116  *         visualCaveat - ala the GLX extension, usually GLX_NONE_EXT
 117  * Return;  a new XMesaVisual or 0 if error.
 118  */
 119 extern XMesaVisual XMesaCreateVisual( XMesaDisplay *display,
 120                                       XMesaVisualInfo visinfo,
 121                                       GLboolean rgb_flag,
 122                                       GLboolean alpha_flag,
 123                                       GLboolean db_flag,
 124                                       GLboolean stereo_flag,
 125                                       GLboolean ximage_flag,
 126                                       GLint depth_size,
 127                                       GLint stencil_size,
 128                                       GLint accum_red_size,
 129                                       GLint accum_green_size,
 130                                       GLint accum_blue_size,
 131                                       GLint accum_alpha_size,
 132                                       GLint num_samples,
 133                                       GLint level,
 134                                       GLint visualCaveat );
 135
 136 /*
 137  * Destroy an XMesaVisual, but not the associated XVisualInfo.
 138  */
 139 extern void XMesaDestroyVisual( XMesaVisual v );
 140
 141
 142
 143 /*
 144  * Create a new XMesaContext for rendering into an X11 window.
 145  *
 146  * Input:  visual - an XMesaVisual
 147  *         share_list - another XMesaContext with which to share display
 148  *                      lists or NULL if no sharing is wanted.
 149  * Return:  an XMesaContext or NULL if error.
 150  */
 151 extern XMesaContext XMesaCreateContext( XMesaVisual v,
 152                                         XMesaContext share_list );
 153
 154
 155 /*
 156  * Destroy a rendering context as returned by XMesaCreateContext()
 157  */
 158 extern void XMesaDestroyContext( XMesaContext c );
 159
 160
 161
 162
 163 /*
 164  * Create an XMesaBuffer from an X window.
 165  */
 166 extern XMesaBuffer XMesaCreateWindowBuffer( XMesaVisual v, XMesaWindow w );
 167
 168
 169 /*
 170  * Create an XMesaBuffer from an X pixmap.
 171  */
 172 extern XMesaBuffer XMesaCreatePixmapBuffer( XMesaVisual v,
 173                                             XMesaPixmap p,
 174                                             XMesaColormap cmap );
 175
 176
 177 /*
 178  * Destroy an XMesaBuffer, but not the corresponding window or pixmap.
 179  */
 180 extern void XMesaDestroyBuffer( XMesaBuffer b );
 181
 182
 183 /*
 184  * Return the XMesaBuffer handle which corresponds to an X drawable, if any.
 185  *
 186  * New in Mesa 2.3.
 187  */
 188 extern XMesaBuffer XMesaFindBuffer( XMesaDisplay *dpy,
 189                                     XMesaDrawable d );
 190
 191
 192
 193 /*
 194  * Bind a buffer to a context and make the context the current one.
 195  */
 196 extern GLboolean XMesaMakeCurrent( XMesaContext c,
 197                                    XMesaBuffer b );
 198
 199
 200 /*
 201  * Bind two buffers (read and draw) to a context and make the
 202  * context the current one.
 203  * New in Mesa 3.3
 204  */
 205 extern GLboolean XMesaMakeCurrent2( XMesaContext c,
 206                                     XMesaBuffer drawBuffer,
 207                                     XMesaBuffer readBuffer );
 208
 209
 210 /*
 211  * Unbind the current context from its buffer.
 212  */
 213 extern GLboolean XMesaUnbindContext( XMesaContext c );
 214
 215
 216 /*
 217  * Return a handle to the current context.
 218  */
 219 extern XMesaContext XMesaGetCurrentContext( void );
 220
 221
 222 /*
 223  * Return handle to the current (draw) buffer.
 224  */
 225 extern XMesaBuffer XMesaGetCurrentBuffer( void );
 226
 227
 228 /*
 229  * Return handle to the current read buffer.
 230  * New in Mesa 3.3
 231  */
 232 extern XMesaBuffer XMesaGetCurrentReadBuffer( void );
 233
 234
 235 /*
 236  * Return display of current context.
 237  */
 238 extern Display *XMesaGetCurrentDisplay( void );
 239
 240
 241 /*
 242  * Swap the front and back buffers for the given buffer.  No action is
 243  * taken if the buffer is not double buffered.
 244  */
 245 extern void XMesaSwapBuffers( XMesaBuffer b );
 246
 247
 248 /*
 249  * Copy a sub-region of the back buffer to the front buffer.
 250  *
 251  * New in Mesa 2.6
 252  */
 253 extern void XMesaCopySubBuffer( XMesaBuffer b,
 254                                 int x,
 255                                 int y,
 256                                 int width,
 257                                 int height );
 258
 259
 260 /*
 261  * Return a pointer to the Pixmap or XImage being used as the back
 262  * color buffer of an XMesaBuffer.  This function is a way to get "under
 263  * the hood" of X/Mesa so one can manipulate the back buffer directly.
 264  * Input:  b - the XMesaBuffer
 265  * Output:  pixmap - pointer to back buffer's Pixmap, or 0
 266  *          ximage - pointer to back buffer's XImage, or NULL
 267  * Return:  GL_TRUE = context is double buffered
 268  *          GL_FALSE = context is single buffered
 269  */
 270 extern GLboolean XMesaGetBackBuffer( XMesaBuffer b,
 271                                      XMesaPixmap *pixmap,
 272                                      XMesaImage **ximage );
 273
 274
 275
 276 /*
 277  * Return the depth buffer associated with an XMesaBuffer.
 278  * Input:  b - the XMesa buffer handle
 279  * Output:  width, height - size of buffer in pixels
 280  *          bytesPerValue - bytes per depth value (2 or 4)
 281  *          buffer - pointer to depth buffer values
 282  * Return:  GL_TRUE or GL_FALSE to indicate success or failure.
 283  *
 284  * New in Mesa 2.4.
 285  */
 286 extern GLboolean XMesaGetDepthBuffer( XMesaBuffer b,
 287                                       GLint *width,
 288                                       GLint *height,
 289                                       GLint *bytesPerValue,
 290                                       void **buffer );
 291
 292
 293
 294 /*
 295  * Flush/sync a context
 296  */
 297 extern void XMesaFlush( XMesaContext c );
 298
 299
 300
 301 /*
 302  * Get an X/Mesa-specific string.
 303  * Input:  name - either XMESA_VERSION or XMESA_EXTENSIONS
 304  */
 305 extern const char *XMesaGetString( XMesaContext c, int name );
 306
 307
 308
 309 /*
 310  * Scan for XMesaBuffers whose window/pixmap has been destroyed, then free
 311  * any memory used by that buffer.
 312  *
 313  * New in Mesa 2.3.
 314  */
 315 extern void XMesaGarbageCollect( XMesaDisplay* dpy );
 316
 317
 318
 319 /*
 320  * Return a dithered pixel value.
 321  * Input:  c - XMesaContext
 322  *         x, y - window coordinate
 323  *         red, green, blue, alpha - color components in [0,1]
 324  * Return:  pixel value
 325  *
 326  * New in Mesa 2.3.
 327  */
 328 extern unsigned long XMesaDitherColor( XMesaContext xmesa,
 329                                        GLint x,
 330                                        GLint y,
 331                                        GLfloat red,
 332                                        GLfloat green,
 333                                        GLfloat blue,
 334                                        GLfloat alpha );
 335
 336
 337
 338 /*
 339  * Reallocate the back/depth/stencil/accum/etc/ buffers associated with
 340  * buffer <b> if its size has changed.
 341  *
 342  * New in Mesa 4.0.2
 343  */
 344 extern void XMesaResizeBuffers( XMesaBuffer b );
 345
 346
 347
 348 /*
 349  * Create a pbuffer.
 350  * New in Mesa 4.1
 351  */
 352 extern XMesaBuffer XMesaCreatePBuffer(XMesaVisual v, XMesaColormap cmap,
 353                                       unsigned int width, unsigned int height);
 354
 355
 356
 357 /*
 358  * Texture from Pixmap
 359  * New in Mesa 7.1
 360  */
 361 extern void
 362 XMesaBindTexImage(XMesaDisplay *dpy, XMesaBuffer drawable, int buffer,
 363                   const int *attrib_list);
 364
 365 extern void
 366 XMesaReleaseTexImage(XMesaDisplay *dpy, XMesaBuffer drawable, int buffer);
 367
 368
 369 extern XMesaBuffer
 370 XMesaCreatePixmapTextureBuffer(XMesaVisual v, XMesaPixmap p,
 371                                XMesaColormap cmap,
 372                                int format, int target, int mipmap);
 373
 374
 375
 376 #ifdef __cplusplus
 377 }
 378 #endif
 379
 380
 381 #endif