include/GL/xmesa.h

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