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