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