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