include/GL/xmesa.h

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