Go to most recent revision | Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
4358 | Serge | 1 | /********************************************************** |
2 | * Copyright 2010 VMware, Inc. All rights reserved. |
||
3 | * |
||
4 | * Permission is hereby granted, free of charge, to any person |
||
5 | * obtaining a copy of this software and associated documentation |
||
6 | * files (the "Software"), to deal in the Software without |
||
7 | * restriction, including without limitation the rights to use, copy, |
||
8 | * modify, merge, publish, distribute, sublicense, and/or sell copies |
||
9 | * of the Software, and to permit persons to whom the Software is |
||
10 | * furnished to do so, subject to the following conditions: |
||
11 | * |
||
12 | * The above copyright notice and this permission notice shall be |
||
13 | * included in all copies or substantial portions of the Software. |
||
14 | * |
||
15 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
||
16 | * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
||
17 | * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND |
||
18 | * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS |
||
19 | * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN |
||
20 | * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN |
||
21 | * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
||
22 | * SOFTWARE. |
||
23 | * |
||
24 | **********************************************************/ |
||
25 | |||
26 | |||
27 | #ifndef _ST_API_H_ |
||
28 | #define _ST_API_H_ |
||
29 | |||
30 | #include "pipe/p_compiler.h" |
||
31 | #include "pipe/p_format.h" |
||
32 | |||
33 | /** |
||
34 | * \file API for communication between state trackers and state tracker |
||
35 | * managers. |
||
36 | * |
||
37 | * While both are state tackers, we use the term state tracker for rendering |
||
38 | * APIs such as OpenGL or OpenVG, and state tracker manager for window system |
||
39 | * APIs such as EGL or GLX in this file. |
||
40 | * |
||
41 | * This file defines an API to be implemented by both state trackers and state |
||
42 | * tracker managers. |
||
43 | */ |
||
44 | |||
45 | /** |
||
46 | * The supported rendering API of a state tracker. |
||
47 | */ |
||
48 | enum st_api_type { |
||
49 | ST_API_OPENGL, |
||
50 | ST_API_OPENVG, |
||
51 | |||
52 | ST_API_COUNT |
||
53 | }; |
||
54 | |||
55 | /** |
||
56 | * The profile of a context. |
||
57 | */ |
||
58 | enum st_profile_type |
||
59 | { |
||
60 | ST_PROFILE_DEFAULT, /**< OpenGL compatibility profile */ |
||
61 | ST_PROFILE_OPENGL_CORE, /**< OpenGL 3.2+ core profile */ |
||
62 | ST_PROFILE_OPENGL_ES1, /**< OpenGL ES 1.x */ |
||
63 | ST_PROFILE_OPENGL_ES2 /**< OpenGL ES 2.0 */ |
||
64 | }; |
||
65 | |||
66 | /* for profile_mask in st_api */ |
||
67 | #define ST_PROFILE_DEFAULT_MASK (1 << ST_PROFILE_DEFAULT) |
||
68 | #define ST_PROFILE_OPENGL_CORE_MASK (1 << ST_PROFILE_OPENGL_CORE) |
||
69 | #define ST_PROFILE_OPENGL_ES1_MASK (1 << ST_PROFILE_OPENGL_ES1) |
||
70 | #define ST_PROFILE_OPENGL_ES2_MASK (1 << ST_PROFILE_OPENGL_ES2) |
||
71 | |||
72 | /** |
||
73 | * Optional API/state tracker features. |
||
74 | */ |
||
75 | enum st_api_feature |
||
76 | { |
||
77 | ST_API_FEATURE_MS_VISUALS /**< support for multisample visuals */ |
||
78 | }; |
||
79 | |||
80 | /* for feature_mask in st_api */ |
||
81 | #define ST_API_FEATURE_MS_VISUALS_MASK (1 << ST_API_FEATURE_MS_VISUALS) |
||
82 | |||
83 | /** |
||
84 | * New context flags for GL 3.0 and beyond. |
||
85 | * |
||
86 | * Profile information (core vs. compatibilty for OpenGL 3.2+) is communicated |
||
87 | * through the \c st_profile_type, not through flags. |
||
88 | */ |
||
89 | #define ST_CONTEXT_FLAG_DEBUG (1 << 0) |
||
90 | #define ST_CONTEXT_FLAG_FORWARD_COMPATIBLE (1 << 1) |
||
91 | #define ST_CONTEXT_FLAG_ROBUST_ACCESS (1 << 2) |
||
92 | |||
93 | /** |
||
94 | * Reasons that context creation might fail. |
||
95 | */ |
||
96 | enum st_context_error { |
||
97 | ST_CONTEXT_SUCCESS = 0, |
||
98 | ST_CONTEXT_ERROR_NO_MEMORY, |
||
99 | ST_CONTEXT_ERROR_BAD_API, |
||
100 | ST_CONTEXT_ERROR_BAD_VERSION, |
||
101 | ST_CONTEXT_ERROR_BAD_FLAG, |
||
102 | ST_CONTEXT_ERROR_UNKNOWN_ATTRIBUTE, |
||
103 | ST_CONTEXT_ERROR_UNKNOWN_FLAG |
||
104 | }; |
||
105 | |||
106 | /** |
||
107 | * Used in st_context_iface->teximage. |
||
108 | */ |
||
109 | enum st_texture_type { |
||
110 | ST_TEXTURE_1D, |
||
111 | ST_TEXTURE_2D, |
||
112 | ST_TEXTURE_3D, |
||
113 | ST_TEXTURE_RECT |
||
114 | }; |
||
115 | |||
116 | /** |
||
117 | * Available attachments of framebuffer. |
||
118 | */ |
||
119 | enum st_attachment_type { |
||
120 | ST_ATTACHMENT_FRONT_LEFT, |
||
121 | ST_ATTACHMENT_BACK_LEFT, |
||
122 | ST_ATTACHMENT_FRONT_RIGHT, |
||
123 | ST_ATTACHMENT_BACK_RIGHT, |
||
124 | ST_ATTACHMENT_DEPTH_STENCIL, |
||
125 | ST_ATTACHMENT_ACCUM, |
||
126 | ST_ATTACHMENT_SAMPLE, |
||
127 | |||
128 | ST_ATTACHMENT_COUNT, |
||
129 | ST_ATTACHMENT_INVALID = -1 |
||
130 | }; |
||
131 | |||
132 | /* for buffer_mask in st_visual */ |
||
133 | #define ST_ATTACHMENT_FRONT_LEFT_MASK (1 << ST_ATTACHMENT_FRONT_LEFT) |
||
134 | #define ST_ATTACHMENT_BACK_LEFT_MASK (1 << ST_ATTACHMENT_BACK_LEFT) |
||
135 | #define ST_ATTACHMENT_FRONT_RIGHT_MASK (1 << ST_ATTACHMENT_FRONT_RIGHT) |
||
136 | #define ST_ATTACHMENT_BACK_RIGHT_MASK (1 << ST_ATTACHMENT_BACK_RIGHT) |
||
137 | #define ST_ATTACHMENT_DEPTH_STENCIL_MASK (1 << ST_ATTACHMENT_DEPTH_STENCIL) |
||
138 | #define ST_ATTACHMENT_ACCUM_MASK (1 << ST_ATTACHMENT_ACCUM) |
||
139 | #define ST_ATTACHMENT_SAMPLE_MASK (1 << ST_ATTACHMENT_SAMPLE) |
||
140 | |||
141 | /** |
||
142 | * Enumerations of state tracker context resources. |
||
143 | */ |
||
144 | enum st_context_resource_type { |
||
145 | ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_2D, |
||
146 | ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_3D, |
||
147 | ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_CUBE_MAP_POSITIVE_X, |
||
148 | ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_CUBE_MAP_NEGATIVE_X, |
||
149 | ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_CUBE_MAP_POSITIVE_Y, |
||
150 | ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_CUBE_MAP_NEGATIVE_Y, |
||
151 | ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_CUBE_MAP_POSITIVE_Z, |
||
152 | ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_CUBE_MAP_NEGATIVE_Z, |
||
153 | ST_CONTEXT_RESOURCE_OPENGL_RENDERBUFFER, |
||
154 | ST_CONTEXT_RESOURCE_OPENVG_PARENT_IMAGE |
||
155 | }; |
||
156 | |||
157 | /** |
||
158 | * Flush flags. |
||
159 | */ |
||
160 | #define ST_FLUSH_FRONT (1 << 0) |
||
161 | #define ST_FLUSH_END_OF_FRAME (1 << 1) |
||
162 | |||
163 | /** |
||
164 | * Value to st_manager->get_param function. |
||
165 | */ |
||
166 | enum st_manager_param { |
||
167 | /** |
||
168 | * The dri state tracker on old libGL's doesn't do the right thing |
||
169 | * with regards to invalidating the framebuffers. |
||
170 | * |
||
171 | * For the mesa state tracker that means that it needs to invalidate |
||
172 | * the framebuffer in glViewport itself. |
||
173 | */ |
||
174 | ST_MANAGER_BROKEN_INVALIDATE |
||
175 | }; |
||
176 | |||
177 | /** |
||
178 | * The return type of st_api->get_proc_address. |
||
179 | */ |
||
180 | typedef void (*st_proc_t)(void); |
||
181 | |||
182 | struct pipe_context; |
||
183 | struct pipe_resource; |
||
184 | struct pipe_fence_handle; |
||
185 | |||
186 | /** |
||
187 | * Used in st_context_iface->get_resource_for_egl_image. |
||
188 | */ |
||
189 | struct st_context_resource |
||
190 | { |
||
191 | /* these fields are filled in by the caller */ |
||
192 | enum st_context_resource_type type; |
||
193 | void *resource; |
||
194 | |||
195 | /* this is owned by the caller */ |
||
196 | struct pipe_resource *texture; |
||
197 | }; |
||
198 | |||
199 | /** |
||
200 | * Used in st_manager_iface->get_egl_image. |
||
201 | */ |
||
202 | struct st_egl_image |
||
203 | { |
||
204 | /* this is owned by the caller */ |
||
205 | struct pipe_resource *texture; |
||
206 | |||
207 | unsigned level; |
||
208 | unsigned layer; |
||
209 | }; |
||
210 | |||
211 | /** |
||
212 | * Represent the visual of a framebuffer. |
||
213 | */ |
||
214 | struct st_visual |
||
215 | { |
||
216 | /** |
||
217 | * Available buffers. Tested with ST_FRAMEBUFFER_*_MASK. |
||
218 | */ |
||
219 | unsigned buffer_mask; |
||
220 | |||
221 | /** |
||
222 | * Buffer formats. The formats are always set even when the buffer is |
||
223 | * not available. |
||
224 | */ |
||
225 | enum pipe_format color_format; |
||
226 | enum pipe_format depth_stencil_format; |
||
227 | enum pipe_format accum_format; |
||
228 | int samples; |
||
229 | |||
230 | /** |
||
231 | * Desired render buffer. |
||
232 | */ |
||
233 | enum st_attachment_type render_buffer; |
||
234 | }; |
||
235 | |||
236 | |||
237 | /** |
||
238 | * Configuration options from driconf |
||
239 | */ |
||
240 | struct st_config_options |
||
241 | { |
||
242 | boolean disable_blend_func_extended; |
||
243 | boolean disable_glsl_line_continuations; |
||
244 | boolean disable_shader_bit_encoding; |
||
245 | boolean force_glsl_extensions_warn; |
||
246 | unsigned force_glsl_version; |
||
247 | boolean force_s3tc_enable; |
||
248 | }; |
||
249 | |||
250 | /** |
||
251 | * Represent the attributes of a context. |
||
252 | */ |
||
253 | struct st_context_attribs |
||
254 | { |
||
255 | /** |
||
256 | * The profile and minimal version to support. |
||
257 | * |
||
258 | * The valid profiles and versions are rendering API dependent. The latest |
||
259 | * version satisfying the request should be returned. |
||
260 | */ |
||
261 | enum st_profile_type profile; |
||
262 | int major, minor; |
||
263 | |||
264 | /** Mask of ST_CONTEXT_FLAG_x bits */ |
||
265 | unsigned flags; |
||
266 | |||
267 | /** |
||
268 | * The visual of the framebuffers the context will be bound to. |
||
269 | */ |
||
270 | struct st_visual visual; |
||
271 | |||
272 | /** |
||
273 | * Configuration options. |
||
274 | */ |
||
275 | struct st_config_options options; |
||
276 | }; |
||
277 | |||
278 | struct st_context_iface; |
||
279 | |||
280 | /** |
||
281 | * Represent a windowing system drawable. |
||
282 | * |
||
283 | * The framebuffer is implemented by the state tracker manager and |
||
284 | * used by the state trackers. |
||
285 | * |
||
286 | * Instead of the winsys poking into the API context to figure |
||
287 | * out what buffers that might be needed in the future by the API |
||
288 | * context, it calls into the framebuffer to get the textures. |
||
289 | * |
||
290 | * This structure along with the notify_invalid_framebuffer |
||
291 | * allows framebuffers to be shared between different threads |
||
292 | * but at the same make the API context free from thread |
||
293 | * synchronization primitves, with the exception of a small |
||
294 | * atomic flag used for notification of framebuffer dirty status. |
||
295 | * |
||
296 | * The thread synchronization is put inside the framebuffer |
||
297 | * and only called once the framebuffer has become dirty. |
||
298 | */ |
||
299 | struct st_framebuffer_iface |
||
300 | { |
||
301 | /** |
||
302 | * Atomic stamp which changes when framebuffers need to be updated. |
||
303 | */ |
||
304 | int32_t stamp; |
||
305 | |||
306 | /** |
||
307 | * Available for the state tracker manager to use. |
||
308 | */ |
||
309 | void *st_manager_private; |
||
310 | |||
311 | /** |
||
312 | * The visual of a framebuffer. |
||
313 | */ |
||
314 | const struct st_visual *visual; |
||
315 | |||
316 | /** |
||
317 | * Flush the front buffer. |
||
318 | * |
||
319 | * On some window systems, changes to the front buffers are not immediately |
||
320 | * visible. They need to be flushed. |
||
321 | * |
||
322 | * @att is one of the front buffer attachments. |
||
323 | */ |
||
324 | boolean (*flush_front)(struct st_context_iface *stctx, |
||
325 | struct st_framebuffer_iface *stfbi, |
||
326 | enum st_attachment_type statt); |
||
327 | |||
328 | /** |
||
329 | * The state tracker asks for the textures it needs. |
||
330 | * |
||
331 | * It should try to only ask for attachments that it currently renders |
||
332 | * to, thus allowing the winsys to delay the allocation of textures not |
||
333 | * needed. For example front buffer attachments are not needed if you |
||
334 | * only do back buffer rendering. |
||
335 | * |
||
336 | * The implementor of this function needs to also ensure |
||
337 | * thread safty as this call might be done from multiple threads. |
||
338 | * |
||
339 | * The returned textures are owned by the caller. They should be |
||
340 | * unreferenced when no longer used. If this function is called multiple |
||
341 | * times with different sets of attachments, those buffers not included in |
||
342 | * the last call might be destroyed. This behavior might change in the |
||
343 | * future. |
||
344 | */ |
||
345 | boolean (*validate)(struct st_context_iface *stctx, |
||
346 | struct st_framebuffer_iface *stfbi, |
||
347 | const enum st_attachment_type *statts, |
||
348 | unsigned count, |
||
349 | struct pipe_resource **out); |
||
350 | }; |
||
351 | |||
352 | /** |
||
353 | * Represent a rendering context. |
||
354 | * |
||
355 | * This entity is created from st_api and used by the state tracker manager. |
||
356 | */ |
||
357 | struct st_context_iface |
||
358 | { |
||
359 | /** |
||
360 | * Available for the state tracker and the manager to use. |
||
361 | */ |
||
362 | void *st_context_private; |
||
363 | void *st_manager_private; |
||
364 | |||
365 | /** |
||
366 | * The CSO context associated with this context in case we need to draw |
||
367 | * something before swap buffers. |
||
368 | */ |
||
369 | struct cso_context *cso_context; |
||
370 | |||
371 | /** |
||
372 | * The gallium context. |
||
373 | */ |
||
374 | struct pipe_context *pipe; |
||
375 | |||
376 | /** |
||
377 | * Destroy the context. |
||
378 | */ |
||
379 | void (*destroy)(struct st_context_iface *stctxi); |
||
380 | |||
381 | /** |
||
382 | * Flush all drawing from context to the pipe also flushes the pipe. |
||
383 | */ |
||
384 | void (*flush)(struct st_context_iface *stctxi, unsigned flags, |
||
385 | struct pipe_fence_handle **fence); |
||
386 | |||
387 | /** |
||
388 | * Replace the texture image of a texture object at the specified level. |
||
389 | * |
||
390 | * This function is optional. |
||
391 | */ |
||
392 | boolean (*teximage)(struct st_context_iface *stctxi, |
||
393 | enum st_texture_type target, |
||
394 | int level, enum pipe_format internal_format, |
||
395 | struct pipe_resource *tex, boolean mipmap); |
||
396 | |||
397 | /** |
||
398 | * Used to implement glXCopyContext. |
||
399 | */ |
||
400 | void (*copy)(struct st_context_iface *stctxi, |
||
401 | struct st_context_iface *stsrci, unsigned mask); |
||
402 | |||
403 | /** |
||
404 | * Used to implement wglShareLists. |
||
405 | */ |
||
406 | boolean (*share)(struct st_context_iface *stctxi, |
||
407 | struct st_context_iface *stsrci); |
||
408 | |||
409 | /** |
||
410 | * Look up and return the info of a resource for EGLImage. |
||
411 | * |
||
412 | * This function is optional. |
||
413 | */ |
||
414 | boolean (*get_resource_for_egl_image)(struct st_context_iface *stctxi, |
||
415 | struct st_context_resource *stres); |
||
416 | }; |
||
417 | |||
418 | |||
419 | /** |
||
420 | * Represent a state tracker manager. |
||
421 | * |
||
422 | * This interface is implemented by the state tracker manager. It corresponds |
||
423 | * to a "display" in the window system. |
||
424 | */ |
||
425 | struct st_manager |
||
426 | { |
||
427 | struct pipe_screen *screen; |
||
428 | |||
429 | /** |
||
430 | * Look up and return the info of an EGLImage. |
||
431 | * |
||
432 | * This is used to implement for example EGLImageTargetTexture2DOES. |
||
433 | * The GLeglImageOES agrument of that call is passed directly to this |
||
434 | * function call and the information needed to access this is returned |
||
435 | * in the given struct out. |
||
436 | * |
||
437 | * @smapi: manager owning the caller context |
||
438 | * @stctx: caller context |
||
439 | * @egl_image: EGLImage that caller recived |
||
440 | * @out: return struct filled out with access information. |
||
441 | * |
||
442 | * This function is optional. |
||
443 | */ |
||
444 | boolean (*get_egl_image)(struct st_manager *smapi, |
||
445 | void *egl_image, |
||
446 | struct st_egl_image *out); |
||
447 | |||
448 | /** |
||
449 | * Query an manager param. |
||
450 | */ |
||
451 | int (*get_param)(struct st_manager *smapi, |
||
452 | enum st_manager_param param); |
||
453 | }; |
||
454 | |||
455 | /** |
||
456 | * Represent a rendering API such as OpenGL or OpenVG. |
||
457 | * |
||
458 | * Implemented by the state tracker and used by the state tracker manager. |
||
459 | */ |
||
460 | struct st_api |
||
461 | { |
||
462 | /** |
||
463 | * The name of the rendering API. This is informative. |
||
464 | */ |
||
465 | const char *name; |
||
466 | |||
467 | /** |
||
468 | * The supported rendering API. |
||
469 | */ |
||
470 | enum st_api_type api; |
||
471 | |||
472 | /** |
||
473 | * The supported profiles. Tested with ST_PROFILE_*_MASK. |
||
474 | */ |
||
475 | unsigned profile_mask; |
||
476 | |||
477 | /** |
||
478 | * The supported optional features. Tested with ST_FEATURE_*_MASK. |
||
479 | */ |
||
480 | unsigned feature_mask; |
||
481 | |||
482 | /** |
||
483 | * Destroy the API. |
||
484 | */ |
||
485 | void (*destroy)(struct st_api *stapi); |
||
486 | |||
487 | /** |
||
488 | * Return an API entry point. |
||
489 | * |
||
490 | * For GL this is the same as _glapi_get_proc_address. |
||
491 | */ |
||
492 | st_proc_t (*get_proc_address)(struct st_api *stapi, const char *procname); |
||
493 | |||
494 | /** |
||
495 | * Create a rendering context. |
||
496 | */ |
||
497 | struct st_context_iface *(*create_context)(struct st_api *stapi, |
||
498 | struct st_manager *smapi, |
||
499 | const struct st_context_attribs *attribs, |
||
500 | enum st_context_error *error, |
||
501 | struct st_context_iface *stsharei); |
||
502 | |||
503 | /** |
||
504 | * Bind the context to the calling thread with draw and read as drawables. |
||
505 | * |
||
506 | * The framebuffers might be NULL, or might have different visuals than the |
||
507 | * context does. |
||
508 | */ |
||
509 | boolean (*make_current)(struct st_api *stapi, |
||
510 | struct st_context_iface *stctxi, |
||
511 | struct st_framebuffer_iface *stdrawi, |
||
512 | struct st_framebuffer_iface *streadi); |
||
513 | |||
514 | /** |
||
515 | * Get the currently bound context in the calling thread. |
||
516 | */ |
||
517 | struct st_context_iface *(*get_current)(struct st_api *stapi); |
||
518 | }; |
||
519 | |||
520 | /** |
||
521 | * Return true if the visual has the specified buffers. |
||
522 | */ |
||
523 | static INLINE boolean |
||
524 | st_visual_have_buffers(const struct st_visual *visual, unsigned mask) |
||
525 | { |
||
526 | return ((visual->buffer_mask & mask) == mask); |
||
527 | } |
||
528 | |||
529 | #endif /* _ST_API_H_ */><>><>><>><>><>><>><>><>><>><>><>><>><>>><>><>><>><>>>>> |