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