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 #define ST_CONTEXT_FLAG_RESET_NOTIFICATION_ENABLED (1 << 3) 93 #define ST_CONTEXT_FLAG_NO_ERROR (1 << 4) 94 #define ST_CONTEXT_FLAG_RELEASE_NONE (1 << 5) 95 #define ST_CONTEXT_FLAG_HIGH_PRIORITY (1 << 6) 96 #define ST_CONTEXT_FLAG_LOW_PRIORITY (1 << 7) 97 98 /** 99 * Reasons that context creation might fail. 100 */ 101 enum st_context_error { 102 ST_CONTEXT_SUCCESS = 0, 103 ST_CONTEXT_ERROR_NO_MEMORY, 104 ST_CONTEXT_ERROR_BAD_API, 105 ST_CONTEXT_ERROR_BAD_VERSION, 106 ST_CONTEXT_ERROR_BAD_FLAG, 107 ST_CONTEXT_ERROR_UNKNOWN_ATTRIBUTE, 108 ST_CONTEXT_ERROR_UNKNOWN_FLAG 109 }; 110 111 /** 112 * Used in st_context_iface->teximage. 113 */ 114 enum st_texture_type { 115 ST_TEXTURE_1D, 116 ST_TEXTURE_2D, 117 ST_TEXTURE_3D, 118 ST_TEXTURE_RECT 119 }; 120 121 /** 122 * Available attachments of framebuffer. 123 */ 124 enum st_attachment_type { 125 ST_ATTACHMENT_FRONT_LEFT, 126 ST_ATTACHMENT_BACK_LEFT, 127 ST_ATTACHMENT_FRONT_RIGHT, 128 ST_ATTACHMENT_BACK_RIGHT, 129 ST_ATTACHMENT_DEPTH_STENCIL, 130 ST_ATTACHMENT_ACCUM, 131 ST_ATTACHMENT_SAMPLE, 132 133 ST_ATTACHMENT_COUNT, 134 ST_ATTACHMENT_INVALID = -1 135 }; 136 137 /* for buffer_mask in st_visual */ 138 #define ST_ATTACHMENT_FRONT_LEFT_MASK (1 << ST_ATTACHMENT_FRONT_LEFT) 139 #define ST_ATTACHMENT_BACK_LEFT_MASK (1 << ST_ATTACHMENT_BACK_LEFT) 140 #define ST_ATTACHMENT_FRONT_RIGHT_MASK (1 << ST_ATTACHMENT_FRONT_RIGHT) 141 #define ST_ATTACHMENT_BACK_RIGHT_MASK (1 << ST_ATTACHMENT_BACK_RIGHT) 142 #define ST_ATTACHMENT_DEPTH_STENCIL_MASK (1 << ST_ATTACHMENT_DEPTH_STENCIL) 143 #define ST_ATTACHMENT_ACCUM_MASK (1 << ST_ATTACHMENT_ACCUM) 144 #define ST_ATTACHMENT_SAMPLE_MASK (1 << ST_ATTACHMENT_SAMPLE) 145 146 /** 147 * Flush flags. 148 */ 149 #define ST_FLUSH_FRONT (1 << 0) 150 #define ST_FLUSH_END_OF_FRAME (1 << 1) 151 #define ST_FLUSH_WAIT (1 << 2) 152 #define ST_FLUSH_FENCE_FD (1 << 3) 153 154 /** 155 * Value to st_manager->get_param function. 156 */ 157 enum st_manager_param { 158 /** 159 * The dri state tracker on old libGL's doesn't do the right thing 160 * with regards to invalidating the framebuffers. 161 * 162 * For the mesa state tracker that means that it needs to invalidate 163 * the framebuffer in glViewport itself. 164 */ 165 ST_MANAGER_BROKEN_INVALIDATE 166 }; 167 168 struct pipe_context; 169 struct pipe_resource; 170 struct pipe_fence_handle; 171 struct util_queue_monitoring; 172 173 /** 174 * Used in st_manager_iface->get_egl_image. 175 */ 176 struct st_egl_image 177 { 178 /* this is owned by the caller */ 179 struct pipe_resource *texture; 180 181 /* format only differs from texture->format for multi-planar (YUV): */ 182 enum pipe_format format; 183 184 unsigned level; 185 unsigned layer; 186 }; 187 188 /** 189 * Represent the visual of a framebuffer. 190 */ 191 struct st_visual 192 { 193 /** 194 * Available buffers. Bitfield of ST_ATTACHMENT_*_MASK bits. 195 */ 196 unsigned buffer_mask; 197 198 /** 199 * Buffer formats. The formats are always set even when the buffer is 200 * not available. 201 */ 202 enum pipe_format color_format; 203 enum pipe_format depth_stencil_format; 204 enum pipe_format accum_format; 205 unsigned samples; 206 207 /** 208 * Desired render buffer. 209 */ 210 enum st_attachment_type render_buffer; 211 }; 212 213 214 /** 215 * Configuration options from driconf 216 */ 217 struct st_config_options 218 { 219 boolean disable_blend_func_extended; 220 boolean disable_glsl_line_continuations; 221 boolean disable_shader_bit_encoding; 222 boolean force_glsl_extensions_warn; 223 unsigned force_glsl_version; 224 boolean allow_glsl_extension_directive_midshader; 225 boolean allow_glsl_builtin_variable_redeclaration; 226 boolean allow_higher_compat_version; 227 boolean glsl_zero_init; 228 boolean force_glsl_abs_sqrt; 229 boolean allow_glsl_cross_stage_interpolation_mismatch; 230 unsigned char config_options_sha1[20]; 231 }; 232 233 /** 234 * Represent the attributes of a context. 235 */ 236 struct st_context_attribs 237 { 238 /** 239 * The profile and minimal version to support. 240 * 241 * The valid profiles and versions are rendering API dependent. The latest 242 * version satisfying the request should be returned. 243 */ 244 enum st_profile_type profile; 245 int major, minor; 246 247 /** Mask of ST_CONTEXT_FLAG_x bits */ 248 unsigned flags; 249 250 /** 251 * The visual of the framebuffers the context will be bound to. 252 */ 253 struct st_visual visual; 254 255 /** 256 * Configuration options. 257 */ 258 struct st_config_options options; 259 }; 260 261 struct st_context_iface; 262 struct st_manager; 263 264 /** 265 * Represent a windowing system drawable. 266 * 267 * The framebuffer is implemented by the state tracker manager and 268 * used by the state trackers. 269 * 270 * Instead of the winsys poking into the API context to figure 271 * out what buffers that might be needed in the future by the API 272 * context, it calls into the framebuffer to get the textures. 273 * 274 * This structure along with the notify_invalid_framebuffer 275 * allows framebuffers to be shared between different threads 276 * but at the same make the API context free from thread 277 * synchronization primitves, with the exception of a small 278 * atomic flag used for notification of framebuffer dirty status. 279 * 280 * The thread synchronization is put inside the framebuffer 281 * and only called once the framebuffer has become dirty. 282 */ 283 struct st_framebuffer_iface 284 { 285 /** 286 * Atomic stamp which changes when framebuffers need to be updated. 287 */ 288 int32_t stamp; 289 290 /** 291 * Identifier that uniquely identifies the framebuffer interface object. 292 */ 293 uint32_t ID; 294 295 /** 296 * The state tracker manager that manages this object. 297 */ 298 struct st_manager *state_manager; 299 300 /** 301 * Available for the state tracker manager to use. 302 */ 303 void *st_manager_private; 304 305 /** 306 * The visual of a framebuffer. 307 */ 308 const struct st_visual *visual; 309 310 /** 311 * Flush the front buffer. 312 * 313 * On some window systems, changes to the front buffers are not immediately 314 * visible. They need to be flushed. 315 * 316 * @att is one of the front buffer attachments. 317 */ 318 boolean (*flush_front)(struct st_context_iface *stctx, 319 struct st_framebuffer_iface *stfbi, 320 enum st_attachment_type statt); 321 322 /** 323 * The state tracker asks for the textures it needs. 324 * 325 * It should try to only ask for attachments that it currently renders 326 * to, thus allowing the winsys to delay the allocation of textures not 327 * needed. For example front buffer attachments are not needed if you 328 * only do back buffer rendering. 329 * 330 * The implementor of this function needs to also ensure 331 * thread safty as this call might be done from multiple threads. 332 * 333 * The returned textures are owned by the caller. They should be 334 * unreferenced when no longer used. If this function is called multiple 335 * times with different sets of attachments, those buffers not included in 336 * the last call might be destroyed. This behavior might change in the 337 * future. 338 */ 339 boolean (*validate)(struct st_context_iface *stctx, 340 struct st_framebuffer_iface *stfbi, 341 const enum st_attachment_type *statts, 342 unsigned count, 343 struct pipe_resource **out); 344 boolean (*flush_swapbuffers) (struct st_context_iface *stctx, 345 struct st_framebuffer_iface *stfbi); 346 }; 347 348 /** 349 * Represent a rendering context. 350 * 351 * This entity is created from st_api and used by the state tracker manager. 352 */ 353 struct st_context_iface 354 { 355 /** 356 * Available for the state tracker and the manager to use. 357 */ 358 void *st_context_private; 359 void *st_manager_private; 360 361 /** 362 * The state tracker manager that manages this object. 363 */ 364 struct st_manager *state_manager; 365 366 /** 367 * The CSO context associated with this context in case we need to draw 368 * something before swap buffers. 369 */ 370 struct cso_context *cso_context; 371 372 /** 373 * The gallium context. 374 */ 375 struct pipe_context *pipe; 376 377 /** 378 * Destroy the context. 379 */ 380 void (*destroy)(struct st_context_iface *stctxi); 381 382 /** 383 * Flush all drawing from context to the pipe also flushes the pipe. 384 */ 385 void (*flush)(struct st_context_iface *stctxi, unsigned flags, 386 struct pipe_fence_handle **fence); 387 388 /** 389 * Replace the texture image of a texture object at the specified level. 390 * 391 * This function is optional. 392 */ 393 boolean (*teximage)(struct st_context_iface *stctxi, 394 enum st_texture_type target, 395 int level, enum pipe_format internal_format, 396 struct pipe_resource *tex, boolean mipmap); 397 398 /** 399 * Used to implement glXCopyContext. 400 */ 401 void (*copy)(struct st_context_iface *stctxi, 402 struct st_context_iface *stsrci, unsigned mask); 403 404 /** 405 * Used to implement wglShareLists. 406 */ 407 boolean (*share)(struct st_context_iface *stctxi, 408 struct st_context_iface *stsrci); 409 410 /** 411 * Start the thread if the API has a worker thread. 412 * Called after the context has been created and fully initialized on both 413 * sides (e.g. st/mesa and st/dri). 414 */ 415 void (*start_thread)(struct st_context_iface *stctxi); 416 417 /** 418 * If the API is multithreaded, wait for all queued commands to complete. 419 * Called from the main thread. 420 */ 421 void (*thread_finish)(struct st_context_iface *stctxi); 422 }; 423 424 425 /** 426 * Represent a state tracker manager. 427 * 428 * This interface is implemented by the state tracker manager. It corresponds 429 * to a "display" in the window system. 430 */ 431 struct st_manager 432 { 433 struct pipe_screen *screen; 434 435 /** 436 * Look up and return the info of an EGLImage. 437 * 438 * This is used to implement for example EGLImageTargetTexture2DOES. 439 * The GLeglImageOES agrument of that call is passed directly to this 440 * function call and the information needed to access this is returned 441 * in the given struct out. 442 * 443 * @smapi: manager owning the caller context 444 * @stctx: caller context 445 * @egl_image: EGLImage that caller recived 446 * @out: return struct filled out with access information. 447 * 448 * This function is optional. 449 */ 450 boolean (*get_egl_image)(struct st_manager *smapi, 451 void *egl_image, 452 struct st_egl_image *out); 453 454 /** 455 * Query an manager param. 456 */ 457 int (*get_param)(struct st_manager *smapi, 458 enum st_manager_param param); 459 460 /** 461 * Call the loader function setBackgroundContext. Called from the worker 462 * thread. 463 */ 464 void (*set_background_context)(struct st_context_iface *stctxi, 465 struct util_queue_monitoring *queue_info); 466 467 /** 468 * Destroy any private data used by the state tracker manager. 469 */ 470 void (*destroy)(struct st_manager *smapi); 471 472 /** 473 * Available for the state tracker manager to use. 474 */ 475 void *st_manager_private; 476 }; 477 478 /** 479 * Represent a rendering API such as OpenGL or OpenVG. 480 * 481 * Implemented by the state tracker and used by the state tracker manager. 482 */ 483 struct st_api 484 { 485 /** 486 * The name of the rendering API. This is informative. 487 */ 488 const char *name; 489 490 /** 491 * The supported rendering API. 492 */ 493 enum st_api_type api; 494 495 /** 496 * The supported profiles. Tested with ST_PROFILE_*_MASK. 497 */ 498 unsigned profile_mask; 499 500 /** 501 * The supported optional features. Tested with ST_FEATURE_*_MASK. 502 */ 503 unsigned feature_mask; 504 505 /** 506 * Destroy the API. 507 */ 508 void (*destroy)(struct st_api *stapi); 509 510 /** 511 * Query supported OpenGL versions. (if applicable) 512 * The format is (major*10+minor). 513 */ 514 void (*query_versions)(struct st_api *stapi, struct st_manager *sm, 515 struct st_config_options *options, 516 int *gl_core_version, 517 int *gl_compat_version, 518 int *gl_es1_version, 519 int *gl_es2_version); 520 521 /** 522 * Create a rendering context. 523 */ 524 struct st_context_iface *(*create_context)(struct st_api *stapi, 525 struct st_manager *smapi, 526 const struct st_context_attribs *attribs, 527 enum st_context_error *error, 528 struct st_context_iface *stsharei); 529 530 /** 531 * Bind the context to the calling thread with draw and read as drawables. 532 * 533 * The framebuffers might be NULL, or might have different visuals than the 534 * context does. 535 */ 536 boolean (*make_current)(struct st_api *stapi, 537 struct st_context_iface *stctxi, 538 struct st_framebuffer_iface *stdrawi, 539 struct st_framebuffer_iface *streadi); 540 541 /** 542 * Get the currently bound context in the calling thread. 543 */ 544 struct st_context_iface *(*get_current)(struct st_api *stapi); 545 546 /** 547 * Notify the st manager the framebuffer interface object 548 * is no longer valid. 549 */ 550 void (*destroy_drawable)(struct st_api *stapi, 551 struct st_framebuffer_iface *stfbi); 552 }; 553 554 /** 555 * Return true if the visual has the specified buffers. 556 */ 557 static inline boolean 558 st_visual_have_buffers(const struct st_visual *visual, unsigned mask) 559 { 560 return ((visual->buffer_mask & mask) == mask); 561 } 562 563 #endif /* _ST_API_H_ */ 564