src/mesa/drivers/x11/xmesa.h

   1 /*
   2  * Mesa 3-D graphics library
   3  * Version:  7.1
   4  *
   5  * Copyright (C) 1999-2007  Brian Paul   All Rights Reserved.
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a
   8  * copy of this software and associated documentation files (the "Software"),
   9  * to deal in the Software without restriction, including without limitation
  10  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  11  * and/or sell copies of the Software, and to permit persons to whom the
  12  * Software is furnished to do so, subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included
  15  * in all copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  18  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  20  * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  21  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  22  * CONNECTION WITH THE SOFTWARE OR THE USE OR 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 #ifdef __cplusplus
  68 extern "C" {
  69 #endif
  70
  71 #include <X11/Xlib.h>
  72 #include <X11/Xutil.h>
  73 #include "xmesa_x.h"
  74 #include "GL/gl.h"
  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 /*
  89  * Values passed to XMesaSetFXmode:
  90  */
  91 #define XMESA_FX_WINDOW       1
  92 #define XMESA_FX_FULLSCREEN   2
  93
  94
  95
  96 typedef struct xmesa_context *XMesaContext;
  97
  98 typedef struct xmesa_visual *XMesaVisual;
  99
 100 typedef struct xmesa_buffer *XMesaBuffer;
 101
 102
 103
 104 /*
 105  * Create a new X/Mesa visual.
 106  * Input:  display - X11 display
 107  *         visinfo - an XVisualInfo pointer
 108  *         rgb_flag - GL_TRUE = RGB mode,
 109  *                    GL_FALSE = color index mode
 110  *         alpha_flag - alpha buffer requested?
 111  *         db_flag - GL_TRUE = double-buffered,
 112  *                   GL_FALSE = single buffered
 113  *         stereo_flag - stereo visual?
 114  *         ximage_flag - GL_TRUE = use an XImage for back buffer,
 115  *                       GL_FALSE = use an off-screen pixmap for back buffer
 116  *         depth_size - requested bits/depth values, or zero
 117  *         stencil_size - requested bits/stencil values, or zero
 118  *         accum_red_size - requested bits/red accum values, or zero
 119  *         accum_green_size - requested bits/green accum values, or zero
 120  *         accum_blue_size - requested bits/blue accum values, or zero
 121  *         accum_alpha_size - requested bits/alpha accum values, or zero
 122  *         num_samples - number of samples/pixel if multisampling, or zero
 123  *         level - visual level, usually 0
 124  *         visualCaveat - ala the GLX extension, usually GLX_NONE_EXT
 125  * Return;  a new XMesaVisual or 0 if error.
 126  */
 127 extern XMesaVisual XMesaCreateVisual( XMesaDisplay *display,
 128                                       XMesaVisualInfo visinfo,
 129                                       GLboolean rgb_flag,
 130                                       GLboolean alpha_flag,
 131                                       GLboolean db_flag,
 132                                       GLboolean stereo_flag,
 133                                       GLboolean ximage_flag,
 134                                       GLint depth_size,
 135                                       GLint stencil_size,
 136                                       GLint accum_red_size,
 137                                       GLint accum_green_size,
 138                                       GLint accum_blue_size,
 139                                       GLint accum_alpha_size,
 140                                       GLint num_samples,
 141                                       GLint level,
 142                                       GLint visualCaveat );
 143
 144 /*
 145  * Destroy an XMesaVisual, but not the associated XVisualInfo.
 146  */
 147 extern void XMesaDestroyVisual( XMesaVisual v );
 148
 149
 150
 151 /*
 152  * Create a new XMesaContext for rendering into an X11 window.
 153  *
 154  * Input:  visual - an XMesaVisual
 155  *         share_list - another XMesaContext with which to share display
 156  *                      lists or NULL if no sharing is wanted.
 157  * Return:  an XMesaContext or NULL if error.
 158  */
 159 extern XMesaContext XMesaCreateContext( XMesaVisual v,
 160                                         XMesaContext share_list );
 161
 162
 163 /*
 164  * Destroy a rendering context as returned by XMesaCreateContext()
 165  */
 166 extern void XMesaDestroyContext( XMesaContext c );
 167
 168
 169
 170
 171 /*
 172  * Create an XMesaBuffer from an X window.
 173  */
 174 extern XMesaBuffer XMesaCreateWindowBuffer( XMesaVisual v, XMesaWindow w );
 175
 176
 177 /*
 178  * Create an XMesaBuffer from an X pixmap.
 179  */
 180 extern XMesaBuffer XMesaCreatePixmapBuffer( XMesaVisual v,
 181                                             XMesaPixmap p,
 182                                             XMesaColormap cmap );
 183
 184
 185 /*
 186  * Destroy an XMesaBuffer, but not the corresponding window or pixmap.
 187  */
 188 extern void XMesaDestroyBuffer( XMesaBuffer b );
 189
 190
 191 /*
 192  * Return the XMesaBuffer handle which corresponds to an X drawable, if any.
 193  *
 194  * New in Mesa 2.3.
 195  */
 196 extern XMesaBuffer XMesaFindBuffer( XMesaDisplay *dpy,
 197                                     XMesaDrawable d );
 198
 199
 200
 201 /*
 202  * Bind a buffer to a context and make the context the current one.
 203  */
 204 extern GLboolean XMesaMakeCurrent( XMesaContext c,
 205                                    XMesaBuffer b );
 206
 207
 208 /*
 209  * Bind two buffers (read and draw) to a context and make the
 210  * context the current one.
 211  * New in Mesa 3.3
 212  */
 213 extern GLboolean XMesaMakeCurrent2( XMesaContext c,
 214                                     XMesaBuffer drawBuffer,
 215                                     XMesaBuffer readBuffer );
 216
 217
 218 /*
 219  * Unbind the current context from its buffer.
 220  */
 221 extern GLboolean XMesaUnbindContext( XMesaContext c );
 222
 223
 224 /*
 225  * Return a handle to the current context.
 226  */
 227 extern XMesaContext XMesaGetCurrentContext( void );
 228
 229
 230 /*
 231  * Return handle to the current (draw) buffer.
 232  */
 233 extern XMesaBuffer XMesaGetCurrentBuffer( void );
 234
 235
 236 /*
 237  * Return handle to the current read buffer.
 238  * New in Mesa 3.3
 239  */
 240 extern XMesaBuffer XMesaGetCurrentReadBuffer( void );
 241
 242
 243 /*
 244  * Swap the front and back buffers for the given buffer.  No action is
 245  * taken if the buffer is not double buffered.
 246  */
 247 extern void XMesaSwapBuffers( XMesaBuffer b );
 248
 249
 250 /*
 251  * Copy a sub-region of the back buffer to the front buffer.
 252  *
 253  * New in Mesa 2.6
 254  */
 255 extern void XMesaCopySubBuffer( XMesaBuffer b,
 256                                 int x,
 257                                 int y,
 258                                 int width,
 259                                 int height );
 260
 261
 262 /*
 263  * Return a pointer to the Pixmap or XImage being used as the back
 264  * color buffer of an XMesaBuffer.  This function is a way to get "under
 265  * the hood" of X/Mesa so one can manipulate the back buffer directly.
 266  * Input:  b - the XMesaBuffer
 267  * Output:  pixmap - pointer to back buffer's Pixmap, or 0
 268  *          ximage - pointer to back buffer's XImage, or NULL
 269  * Return:  GL_TRUE = context is double buffered
 270  *          GL_FALSE = context is single buffered
 271  */
 272 extern GLboolean XMesaGetBackBuffer( XMesaBuffer b,
 273                                      XMesaPixmap *pixmap,
 274                                      XMesaImage **ximage );
 275
 276
 277
 278 /*
 279  * Return the depth buffer associated with an XMesaBuffer.
 280  * Input:  b - the XMesa buffer handle
 281  * Output:  width, height - size of buffer in pixels
 282  *          bytesPerValue - bytes per depth value (2 or 4)
 283  *          buffer - pointer to depth buffer values
 284  * Return:  GL_TRUE or GL_FALSE to indicate success or failure.
 285  *
 286  * New in Mesa 2.4.
 287  */
 288 extern GLboolean XMesaGetDepthBuffer( XMesaBuffer b,
 289                                       GLint *width,
 290                                       GLint *height,
 291                                       GLint *bytesPerValue,
 292                                       void **buffer );
 293
 294
 295
 296 /*
 297  * Flush/sync a context
 298  */
 299 extern void XMesaFlush( XMesaContext c );
 300
 301
 302
 303 /*
 304  * Get an X/Mesa-specific string.
 305  * Input:  name - either XMESA_VERSION or XMESA_EXTENSIONS
 306  */
 307 extern const char *XMesaGetString( XMesaContext c, int name );
 308
 309
 310
 311 /*
 312  * Scan for XMesaBuffers whose window/pixmap has been destroyed, then free
 313  * any memory used by that buffer.
 314  *
 315  * New in Mesa 2.3.
 316  */
 317 extern void XMesaGarbageCollect( XMesaDisplay* dpy );
 318
 319
 320
 321 /*
 322  * Return a dithered pixel value.
 323  * Input:  c - XMesaContext
 324  *         x, y - window coordinate
 325  *         red, green, blue, alpha - color components in [0,1]
 326  * Return:  pixel value
 327  *
 328  * New in Mesa 2.3.
 329  */
 330 extern unsigned long XMesaDitherColor( XMesaContext xmesa,
 331                                        GLint x,
 332                                        GLint y,
 333                                        GLfloat red,
 334                                        GLfloat green,
 335                                        GLfloat blue,
 336                                        GLfloat alpha );
 337
 338
 339
 340 /*
 341  * 3Dfx Glide driver only!
 342  * Set 3Dfx/Glide full-screen or window rendering mode.
 343  * Input:  mode - either XMESA_FX_WINDOW (window rendering mode) or
 344  *                XMESA_FX_FULLSCREEN (full-screen rendering mode)
 345  * Return:  GL_TRUE if success
 346  *          GL_FALSE if invalid mode or if not using 3Dfx driver
 347  *
 348  * New in Mesa 2.6.
 349  */
 350 extern GLboolean XMesaSetFXmode( GLint mode );
 351
 352
 353
 354 /*
 355  * Reallocate the back/depth/stencil/accum/etc/ buffers associated with
 356  * buffer <b> if its size has changed.
 357  *
 358  * New in Mesa 4.0.2
 359  */
 360 extern void XMesaResizeBuffers( XMesaBuffer b );
 361
 362
 363
 364 /*
 365  * Create a pbuffer.
 366  * New in Mesa 4.1
 367  */
 368 extern XMesaBuffer XMesaCreatePBuffer(XMesaVisual v, XMesaColormap cmap,
 369                                       unsigned int width, unsigned int height);
 370
 371
 372
 373 /*
 374  * Texture from Pixmap
 375  * New in Mesa 7.1
 376  */
 377 extern void
 378 XMesaBindTexImage(XMesaDisplay *dpy, XMesaBuffer drawable, int buffer,
 379                   const int *attrib_list);
 380
 381 extern void
 382 XMesaReleaseTexImage(XMesaDisplay *dpy, XMesaBuffer drawable, int buffer);
 383
 384
 385 extern XMesaBuffer
 386 XMesaCreatePixmapTextureBuffer(XMesaVisual v, XMesaPixmap p,
 387                                XMesaColormap cmap,
 388                                int format, int target, int mipmap);
 389
 390
 391
 392 #ifdef __cplusplus
 393 }
 394 #endif
 395
 396
 397 #endif