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 _API_H_ 28#define _API_H_ 29 30#include "pipe/p_format.h" 31 32/** 33 * \file API for communication between gallium frontends and supporting 34 * frontends such as DRI. 35 * 36 * This file defines an API to be implemented by both gallium frontends and 37 * their managers. 38 */ 39 40/** 41 * The supported rendering API. 42 */ 43enum st_api_type { 44 ST_API_OPENGL, 45 ST_API_OPENVG, 46 47 ST_API_COUNT 48}; 49 50/** 51 * The profile of a context. 52 */ 53enum st_profile_type 54{ 55 ST_PROFILE_DEFAULT, /**< OpenGL compatibility profile */ 56 ST_PROFILE_OPENGL_CORE, /**< OpenGL 3.2+ core profile */ 57 ST_PROFILE_OPENGL_ES1, /**< OpenGL ES 1.x */ 58 ST_PROFILE_OPENGL_ES2 /**< OpenGL ES 2.0 */ 59}; 60 61/* for profile_mask in st_api */ 62#define ST_PROFILE_DEFAULT_MASK (1 << ST_PROFILE_DEFAULT) 63#define ST_PROFILE_OPENGL_CORE_MASK (1 << ST_PROFILE_OPENGL_CORE) 64#define ST_PROFILE_OPENGL_ES1_MASK (1 << ST_PROFILE_OPENGL_ES1) 65#define ST_PROFILE_OPENGL_ES2_MASK (1 << ST_PROFILE_OPENGL_ES2) 66 67/** 68 * Optional API features. 69 */ 70enum st_api_feature 71{ 72 ST_API_FEATURE_MS_VISUALS /**< support for multisample visuals */ 73}; 74 75/* for feature_mask in st_api */ 76#define ST_API_FEATURE_MS_VISUALS_MASK (1 << ST_API_FEATURE_MS_VISUALS) 77 78/** 79 * New context flags for GL 3.0 and beyond. 80 * 81 * Profile information (core vs. compatibilty for OpenGL 3.2+) is communicated 82 * through the \c st_profile_type, not through flags. 83 */ 84#define ST_CONTEXT_FLAG_DEBUG (1 << 0) 85#define ST_CONTEXT_FLAG_FORWARD_COMPATIBLE (1 << 1) 86#define ST_CONTEXT_FLAG_ROBUST_ACCESS (1 << 2) 87#define ST_CONTEXT_FLAG_RESET_NOTIFICATION_ENABLED (1 << 3) 88#define ST_CONTEXT_FLAG_NO_ERROR (1 << 4) 89#define ST_CONTEXT_FLAG_RELEASE_NONE (1 << 5) 90#define ST_CONTEXT_FLAG_HIGH_PRIORITY (1 << 6) 91#define ST_CONTEXT_FLAG_LOW_PRIORITY (1 << 7) 92 93/** 94 * Reasons that context creation might fail. 95 */ 96enum 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 */ 109enum 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 */ 119enum 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 127 ST_ATTACHMENT_COUNT, 128 ST_ATTACHMENT_INVALID = -1 129}; 130 131/* for buffer_mask in st_visual */ 132#define ST_ATTACHMENT_FRONT_LEFT_MASK (1 << ST_ATTACHMENT_FRONT_LEFT) 133#define ST_ATTACHMENT_BACK_LEFT_MASK (1 << ST_ATTACHMENT_BACK_LEFT) 134#define ST_ATTACHMENT_FRONT_RIGHT_MASK (1 << ST_ATTACHMENT_FRONT_RIGHT) 135#define ST_ATTACHMENT_BACK_RIGHT_MASK (1 << ST_ATTACHMENT_BACK_RIGHT) 136#define ST_ATTACHMENT_DEPTH_STENCIL_MASK (1 << ST_ATTACHMENT_DEPTH_STENCIL) 137#define ST_ATTACHMENT_ACCUM_MASK (1 << ST_ATTACHMENT_ACCUM) 138 139/** 140 * Flush flags. 141 */ 142#define ST_FLUSH_FRONT (1 << 0) 143#define ST_FLUSH_END_OF_FRAME (1 << 1) 144#define ST_FLUSH_WAIT (1 << 2) 145#define ST_FLUSH_FENCE_FD (1 << 3) 146 147/** 148 * State invalidation flags to notify frontends that states have been changed 149 * behind their back. 150 */ 151#define ST_INVALIDATE_FS_SAMPLER_VIEWS (1 << 0) 152#define ST_INVALIDATE_FS_CONSTBUF0 (1 << 1) 153#define ST_INVALIDATE_VS_CONSTBUF0 (1 << 2) 154#define ST_INVALIDATE_VERTEX_BUFFERS (1 << 3) 155 156/** 157 * Value to st_manager->get_param function. 158 */ 159enum st_manager_param { 160 /** 161 * The DRI frontend on old libGL's doesn't do the right thing 162 * with regards to invalidating the framebuffers. 163 * 164 * For the GL gallium frontend that means that it needs to invalidate 165 * the framebuffer in glViewport itself. 166 */ 167 ST_MANAGER_BROKEN_INVALIDATE 168}; 169 170struct pipe_context; 171struct pipe_resource; 172struct pipe_fence_handle; 173struct util_queue_monitoring; 174 175/** 176 * Used in st_manager_iface->get_egl_image. 177 */ 178struct st_egl_image 179{ 180 /* this is owned by the caller */ 181 struct pipe_resource *texture; 182 183 /* format only differs from texture->format for multi-planar (YUV): */ 184 enum pipe_format format; 185 186 unsigned level; 187 unsigned layer; 188 /* GL internal format. */ 189 unsigned internalformat; 190 191 /* one of __DRI_YUV_COLOR_SPACE_* */ 192 unsigned yuv_color_space; 193 194 /* one of __DRI_YUV_RANGE_* */ 195 unsigned yuv_range; 196}; 197 198/** 199 * Represent the visual of a framebuffer. 200 */ 201struct st_visual 202{ 203 /** 204 * Available buffers. Bitfield of ST_ATTACHMENT_*_MASK bits. 205 */ 206 unsigned buffer_mask; 207 208 /** 209 * Buffer formats. The formats are always set even when the buffer is 210 * not available. 211 */ 212 enum pipe_format color_format; 213 enum pipe_format depth_stencil_format; 214 enum pipe_format accum_format; 215 unsigned samples; 216}; 217 218 219/** 220 * Configuration options from driconf 221 */ 222struct st_config_options 223{ 224 bool disable_blend_func_extended; 225 bool disable_glsl_line_continuations; 226 bool disable_arb_gpu_shader5; 227 bool force_compat_shaders; 228 bool force_glsl_extensions_warn; 229 unsigned force_glsl_version; 230 bool allow_extra_pp_tokens; 231 bool allow_glsl_extension_directive_midshader; 232 bool allow_glsl_120_subset_in_110; 233 bool allow_glsl_builtin_const_expression; 234 bool allow_glsl_relaxed_es; 235 bool allow_glsl_builtin_variable_redeclaration; 236 bool allow_higher_compat_version; 237 bool allow_glsl_compat_shaders; 238 bool glsl_ignore_write_to_readonly_var; 239 bool glsl_zero_init; 240 bool vs_position_always_invariant; 241 bool vs_position_always_precise; 242 bool force_glsl_abs_sqrt; 243 bool allow_glsl_cross_stage_interpolation_mismatch; 244 bool do_dce_before_clip_cull_analysis; 245 bool allow_draw_out_of_order; 246 bool glthread_nop_check_framebuffer_status; 247 bool ignore_map_unsynchronized; 248 bool force_integer_tex_nearest; 249 bool force_gl_names_reuse; 250 bool force_gl_map_buffer_synchronized; 251 bool transcode_etc; 252 bool transcode_astc; 253 char *force_gl_vendor; 254 char *force_gl_renderer; 255 char *mesa_extension_override; 256 unsigned char config_options_sha1[20]; 257}; 258 259/** 260 * Represent the attributes of a context. 261 */ 262struct st_context_attribs 263{ 264 /** 265 * The profile and minimal version to support. 266 * 267 * The valid profiles and versions are rendering API dependent. The latest 268 * version satisfying the request should be returned. 269 */ 270 enum st_profile_type profile; 271 int major, minor; 272 273 /** Mask of ST_CONTEXT_FLAG_x bits */ 274 unsigned flags; 275 276 /** 277 * The visual of the framebuffers the context will be bound to. 278 */ 279 struct st_visual visual; 280 281 /** 282 * Configuration options. 283 */ 284 struct st_config_options options; 285}; 286 287struct st_context_iface; 288struct st_manager; 289 290/** 291 * Represent a windowing system drawable. 292 * 293 * The framebuffer is implemented by the frontend manager and 294 * used by gallium frontends. 295 * 296 * Instead of the winsys poking into the frontend context to figure 297 * out what buffers that might be needed in the future by the frontend 298 * context, it calls into the framebuffer to get the textures. 299 * 300 * This structure along with the notify_invalid_framebuffer 301 * allows framebuffers to be shared between different threads 302 * but at the same make the API context free from thread 303 * synchronization primitves, with the exception of a small 304 * atomic flag used for notification of framebuffer dirty status. 305 * 306 * The thread synchronization is put inside the framebuffer 307 * and only called once the framebuffer has become dirty. 308 */ 309struct st_framebuffer_iface 310{ 311 /** 312 * Atomic stamp which changes when framebuffers need to be updated. 313 */ 314 int32_t stamp; 315 316 /** 317 * Identifier that uniquely identifies the framebuffer interface object. 318 */ 319 uint32_t ID; 320 321 /** 322 * The frontend manager that manages this object. 323 */ 324 struct st_manager *state_manager; 325 326 /** 327 * Available for the frontend manager to use. 328 */ 329 void *st_manager_private; 330 331 /** 332 * The visual of a framebuffer. 333 */ 334 const struct st_visual *visual; 335 336 /** 337 * Flush the front buffer. 338 * 339 * On some window systems, changes to the front buffers are not immediately 340 * visible. They need to be flushed. 341 * 342 * @att is one of the front buffer attachments. 343 */ 344 bool (*flush_front)(struct st_context_iface *stctx, 345 struct st_framebuffer_iface *stfbi, 346 enum st_attachment_type statt); 347 348 /** 349 * the gallium frontend asks for the textures it needs. 350 * 351 * It should try to only ask for attachments that it currently renders 352 * to, thus allowing the winsys to delay the allocation of textures not 353 * needed. For example front buffer attachments are not needed if you 354 * only do back buffer rendering. 355 * 356 * The implementor of this function needs to also ensure 357 * thread safty as this call might be done from multiple threads. 358 * 359 * The returned textures are owned by the caller. They should be 360 * unreferenced when no longer used. If this function is called multiple 361 * times with different sets of attachments, those buffers not included in 362 * the last call might be destroyed. This behavior might change in the 363 * future. 364 */ 365 bool (*validate)(struct st_context_iface *stctx, 366 struct st_framebuffer_iface *stfbi, 367 const enum st_attachment_type *statts, 368 unsigned count, 369 struct pipe_resource **out); 370 bool (*flush_swapbuffers) (struct st_context_iface *stctx, 371 struct st_framebuffer_iface *stfbi); 372}; 373 374/** 375 * Represent a rendering context. 376 * 377 * This entity is created from st_api and used by the frontend manager. 378 */ 379struct st_context_iface 380{ 381 /** 382 * Available for the gallium frontend and the manager to use. 383 */ 384 void *st_context_private; 385 void *st_manager_private; 386 387 /** 388 * The frontend manager that manages this object. 389 */ 390 struct st_manager *state_manager; 391 392 /** 393 * The CSO context associated with this context in case we need to draw 394 * something before swap buffers. 395 */ 396 struct cso_context *cso_context; 397 398 /** 399 * The gallium context. 400 */ 401 struct pipe_context *pipe; 402 403 /** 404 * Destroy the context. 405 */ 406 void (*destroy)(struct st_context_iface *stctxi); 407 408 /** 409 * Flush all drawing from context to the pipe also flushes the pipe. 410 */ 411 void (*flush)(struct st_context_iface *stctxi, unsigned flags, 412 struct pipe_fence_handle **fence, 413 void (*notify_before_flush_cb) (void*), 414 void* notify_before_flush_cb_args); 415 416 /** 417 * Replace the texture image of a texture object at the specified level. 418 * 419 * This function is optional. 420 */ 421 bool (*teximage)(struct st_context_iface *stctxi, 422 enum st_texture_type target, 423 int level, enum pipe_format internal_format, 424 struct pipe_resource *tex, bool mipmap); 425 426 /** 427 * Used to implement glXCopyContext. 428 */ 429 void (*copy)(struct st_context_iface *stctxi, 430 struct st_context_iface *stsrci, unsigned mask); 431 432 /** 433 * Used to implement wglShareLists. 434 */ 435 bool (*share)(struct st_context_iface *stctxi, 436 struct st_context_iface *stsrci); 437 438 /** 439 * Start the thread if the API has a worker thread. 440 * Called after the context has been created and fully initialized on both 441 * sides (e.g. st/mesa and st/dri). 442 */ 443 void (*start_thread)(struct st_context_iface *stctxi); 444 445 /** 446 * If the API is multithreaded, wait for all queued commands to complete. 447 * Called from the main thread. 448 */ 449 void (*thread_finish)(struct st_context_iface *stctxi); 450 451 /** 452 * Invalidate states to notify the frontend that states have been changed 453 * behind its back. 454 */ 455 void (*invalidate_state)(struct st_context_iface *stctxi, unsigned flags); 456}; 457 458 459/** 460 * Represent a frontend manager. 461 * 462 * This interface is implemented by the frontend manager. It corresponds 463 * to a "display" in the window system. 464 */ 465struct st_manager 466{ 467 struct pipe_screen *screen; 468 469 /** 470 * Look up and return the info of an EGLImage. 471 * 472 * This is used to implement for example EGLImageTargetTexture2DOES. 473 * The GLeglImageOES agrument of that call is passed directly to this 474 * function call and the information needed to access this is returned 475 * in the given struct out. 476 * 477 * @smapi: manager owning the caller context 478 * @stctx: caller context 479 * @egl_image: EGLImage that caller recived 480 * @out: return struct filled out with access information. 481 * 482 * This function is optional. 483 */ 484 bool (*get_egl_image)(struct st_manager *smapi, 485 void *egl_image, 486 struct st_egl_image *out); 487 488 /** 489 * Validate EGLImage passed to get_egl_image. 490 */ 491 bool (*validate_egl_image)(struct st_manager *smapi, 492 void *egl_image); 493 494 /** 495 * Query an manager param. 496 */ 497 int (*get_param)(struct st_manager *smapi, 498 enum st_manager_param param); 499 500 /** 501 * Call the loader function setBackgroundContext. Called from the worker 502 * thread. 503 */ 504 void (*set_background_context)(struct st_context_iface *stctxi, 505 struct util_queue_monitoring *queue_info); 506 507 /** 508 * Destroy any private data used by the frontend manager. 509 */ 510 void (*destroy)(struct st_manager *smapi); 511 512 /** 513 * Available for the frontend manager to use. 514 */ 515 void *st_manager_private; 516}; 517 518/** 519 * Represent a rendering API such as OpenGL or OpenVG. 520 * 521 * Implemented by the gallium frontend and used by the frontend manager. 522 */ 523struct st_api 524{ 525 /** 526 * The name of the rendering API. This is informative. 527 */ 528 const char *name; 529 530 /** 531 * The supported rendering API. 532 */ 533 enum st_api_type api; 534 535 /** 536 * The supported profiles. Tested with ST_PROFILE_*_MASK. 537 */ 538 unsigned profile_mask; 539 540 /** 541 * The supported optional features. Tested with ST_FEATURE_*_MASK. 542 */ 543 unsigned feature_mask; 544 545 /** 546 * Destroy the API. 547 */ 548 void (*destroy)(struct st_api *stapi); 549 550 /** 551 * Query supported OpenGL versions. (if applicable) 552 * The format is (major*10+minor). 553 */ 554 void (*query_versions)(struct st_api *stapi, struct st_manager *sm, 555 struct st_config_options *options, 556 int *gl_core_version, 557 int *gl_compat_version, 558 int *gl_es1_version, 559 int *gl_es2_version); 560 561 /** 562 * Create a rendering context. 563 */ 564 struct st_context_iface *(*create_context)(struct st_api *stapi, 565 struct st_manager *smapi, 566 const struct st_context_attribs *attribs, 567 enum st_context_error *error, 568 struct st_context_iface *stsharei); 569 570 /** 571 * Bind the context to the calling thread with draw and read as drawables. 572 * 573 * The framebuffers might be NULL, or might have different visuals than the 574 * context does. 575 */ 576 bool (*make_current)(struct st_api *stapi, 577 struct st_context_iface *stctxi, 578 struct st_framebuffer_iface *stdrawi, 579 struct st_framebuffer_iface *streadi); 580 581 /** 582 * Get the currently bound context in the calling thread. 583 */ 584 struct st_context_iface *(*get_current)(struct st_api *stapi); 585 586 /** 587 * Notify the st manager the framebuffer interface object 588 * is no longer valid. 589 */ 590 void (*destroy_drawable)(struct st_api *stapi, 591 struct st_framebuffer_iface *stfbi); 592}; 593 594/** 595 * Return true if the visual has the specified buffers. 596 */ 597static inline bool 598st_visual_have_buffers(const struct st_visual *visual, unsigned mask) 599{ 600 return ((visual->buffer_mask & mask) == mask); 601} 602 603#endif /* _API_H_ */ 604