osmesa.h revision af69d88d 
1/*
2 * Mesa 3-D graphics library
3 *
4 * Copyright (C) 1999-2005  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 Off-Screen rendering interface.
28 *
29 * This is an operating system and window system independent interface to
30 * Mesa which allows one to render images into a client-supplied buffer in
31 * main memory.  Such images may manipulated or saved in whatever way the
32 * client wants.
33 *
34 * These are the API functions:
35 *   OSMesaCreateContext - create a new Off-Screen Mesa rendering context
36 *   OSMesaMakeCurrent - bind an OSMesaContext to a client's image buffer
37 *                       and make the specified context the current one.
38 *   OSMesaDestroyContext - destroy an OSMesaContext
39 *   OSMesaGetCurrentContext - return thread's current context ID
40 *   OSMesaPixelStore - controls how pixels are stored in image buffer
41 *   OSMesaGetIntegerv - return OSMesa state parameters
42 *
43 *
44 * The limits on the width and height of an image buffer are MAX_WIDTH and
45 * MAX_HEIGHT as defined in Mesa/src/config.h.  Defaults are 1280 and 1024.
46 * You can increase them as needed but beware that many temporary arrays in
47 * Mesa are dimensioned by MAX_WIDTH or MAX_HEIGHT.
48 */
49
50
51#ifndef OSMESA_H
52#define OSMESA_H
53
54
55#ifdef __cplusplus
56extern "C" {
57#endif
58
59
60#include <GL/gl.h>
61
62
63#define OSMESA_MAJOR_VERSION 10
64#define OSMESA_MINOR_VERSION 0
65#define OSMESA_PATCH_VERSION 0
66
67
68
69/*
70 * Values for the format parameter of OSMesaCreateContext()
71 * New in version 2.0.
72 */
73#define OSMESA_COLOR_INDEX	GL_COLOR_INDEX
74#define OSMESA_RGBA		GL_RGBA
75#define OSMESA_BGRA		0x1
76#define OSMESA_ARGB		0x2
77#define OSMESA_RGB		GL_RGB
78#define OSMESA_BGR		0x4
79#define OSMESA_RGB_565		0x5
80
81
82/*
83 * OSMesaPixelStore() parameters:
84 * New in version 2.0.
85 */
86#define OSMESA_ROW_LENGTH	0x10
87#define OSMESA_Y_UP		0x11
88
89
90/*
91 * Accepted by OSMesaGetIntegerv:
92 */
93#define OSMESA_WIDTH		0x20
94#define OSMESA_HEIGHT		0x21
95#define OSMESA_FORMAT		0x22
96#define OSMESA_TYPE		0x23
97#define OSMESA_MAX_WIDTH	0x24  /* new in 4.0 */
98#define OSMESA_MAX_HEIGHT	0x25  /* new in 4.0 */
99
100
101typedef struct osmesa_context *OSMesaContext;
102
103
104/*
105 * Create an Off-Screen Mesa rendering context.  The only attribute needed is
106 * an RGBA vs Color-Index mode flag.
107 *
108 * Input:  format - one of OSMESA_COLOR_INDEX, OSMESA_RGBA, OSMESA_BGRA,
109 *                  OSMESA_ARGB, OSMESA_RGB, or OSMESA_BGR.
110 *         sharelist - specifies another OSMesaContext with which to share
111 *                     display lists.  NULL indicates no sharing.
112 * Return:  an OSMesaContext or 0 if error
113 */
114GLAPI OSMesaContext GLAPIENTRY
115OSMesaCreateContext( GLenum format, OSMesaContext sharelist );
116
117
118
119/*
120 * Create an Off-Screen Mesa rendering context and specify desired
121 * size of depth buffer, stencil buffer and accumulation buffer.
122 * If you specify zero for depthBits, stencilBits, accumBits you
123 * can save some memory.
124 *
125 * New in Mesa 3.5
126 */
127GLAPI OSMesaContext GLAPIENTRY
128OSMesaCreateContextExt( GLenum format, GLint depthBits, GLint stencilBits,
129                        GLint accumBits, OSMesaContext sharelist);
130
131
132/*
133 * Destroy an Off-Screen Mesa rendering context.
134 *
135 * Input:  ctx - the context to destroy
136 */
137GLAPI void GLAPIENTRY
138OSMesaDestroyContext( OSMesaContext ctx );
139
140
141
142/*
143 * Bind an OSMesaContext to an image buffer.  The image buffer is just a
144 * block of memory which the client provides.  Its size must be at least
145 * as large as width*height*sizeof(type).  Its address should be a multiple
146 * of 4 if using RGBA mode.
147 *
148 * Image data is stored in the order of glDrawPixels:  row-major order
149 * with the lower-left image pixel stored in the first array position
150 * (ie. bottom-to-top).
151 *
152 * Since the only type initially supported is GL_UNSIGNED_BYTE, if the
153 * context is in RGBA mode, each pixel will be stored as a 4-byte RGBA
154 * value.  If the context is in color indexed mode, each pixel will be
155 * stored as a 1-byte value.
156 *
157 * If the context's viewport hasn't been initialized yet, it will now be
158 * initialized to (0,0,width,height).
159 *
160 * Input:  ctx - the rendering context
161 *         buffer - the image buffer memory
162 *         type - data type for pixel components, only GL_UNSIGNED_BYTE
163 *                supported now
164 *         width, height - size of image buffer in pixels, at least 1
165 * Return:  GL_TRUE if success, GL_FALSE if error because of invalid ctx,
166 *          invalid buffer address, type!=GL_UNSIGNED_BYTE, width<1, height<1,
167 *          width>internal limit or height>internal limit.
168 */
169GLAPI GLboolean GLAPIENTRY
170OSMesaMakeCurrent( OSMesaContext ctx, void *buffer, GLenum type,
171                   GLsizei width, GLsizei height );
172
173
174
175
176/*
177 * Return the current Off-Screen Mesa rendering context handle.
178 */
179GLAPI OSMesaContext GLAPIENTRY
180OSMesaGetCurrentContext( void );
181
182
183
184/*
185 * Set pixel store/packing parameters for the current context.
186 * This is similar to glPixelStore.
187 * Input:  pname - OSMESA_ROW_LENGTH
188 *                    specify actual pixels per row in image buffer
189 *                    0 = same as image width (default)
190 *                 OSMESA_Y_UP
191 *                    zero = Y coordinates increase downward
192 *                    non-zero = Y coordinates increase upward (default)
193 *         value - the value for the parameter pname
194 *
195 * New in version 2.0.
196 */
197GLAPI void GLAPIENTRY
198OSMesaPixelStore( GLint pname, GLint value );
199
200
201
202/*
203 * Return an integer value like glGetIntegerv.
204 * Input:  pname -
205 *                 OSMESA_WIDTH  return current image width
206 *                 OSMESA_HEIGHT  return current image height
207 *                 OSMESA_FORMAT  return image format
208 *                 OSMESA_TYPE  return color component data type
209 *                 OSMESA_ROW_LENGTH return row length in pixels
210 *                 OSMESA_Y_UP returns 1 or 0 to indicate Y axis direction
211 *         value - pointer to integer in which to return result.
212 */
213GLAPI void GLAPIENTRY
214OSMesaGetIntegerv( GLint pname, GLint *value );
215
216
217
218/*
219 * Return the depth buffer associated with an OSMesa context.
220 * Input:  c - the OSMesa context
221 * Output:  width, height - size of buffer in pixels
222 *          bytesPerValue - bytes per depth value (2 or 4)
223 *          buffer - pointer to depth buffer values
224 * Return:  GL_TRUE or GL_FALSE to indicate success or failure.
225 *
226 * New in Mesa 2.4.
227 */
228GLAPI GLboolean GLAPIENTRY
229OSMesaGetDepthBuffer( OSMesaContext c, GLint *width, GLint *height,
230                      GLint *bytesPerValue, void **buffer );
231
232
233
234/*
235 * Return the color buffer associated with an OSMesa context.
236 * Input:  c - the OSMesa context
237 * Output:  width, height - size of buffer in pixels
238 *          format - buffer format (OSMESA_FORMAT)
239 *          buffer - pointer to depth buffer values
240 * Return:  GL_TRUE or GL_FALSE to indicate success or failure.
241 *
242 * New in Mesa 3.3.
243 */
244GLAPI GLboolean GLAPIENTRY
245OSMesaGetColorBuffer( OSMesaContext c, GLint *width, GLint *height,
246                      GLint *format, void **buffer );
247
248
249
250/**
251 * This typedef is new in Mesa 6.3.
252 */
253typedef void (*OSMESAproc)();
254
255
256/*
257 * Return pointer to the named function.
258 * New in Mesa 4.1
259 * Return OSMESAproc in 6.3.
260 */
261GLAPI OSMESAproc GLAPIENTRY
262OSMesaGetProcAddress( const char *funcName );
263
264
265
266/**
267 * Enable/disable color clamping, off by default.
268 * New in Mesa 6.4.2
269 */
270GLAPI void GLAPIENTRY
271OSMesaColorClamp(GLboolean enable);
272
273
274/**
275 * Enable/disable Gallium post-process filters.
276 * This should be called after a context is created, but before it is
277 * made current for the first time.  After a context has been made
278 * current, this function has no effect.
279 * If the enable_value param is zero, the filter is disabled.  Otherwise
280 * the filter is enabled, and the value may control the filter's quality.
281 * New in Mesa 10.0
282 */
283GLAPI void GLAPIENTRY
284OSMesaPostprocess(OSMesaContext osmesa, const char *filter,
285                  unsigned enable_value);
286
287
288#ifdef __cplusplus
289}
290#endif
291
292
293#endif
294