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