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