1 /************************************************************************** 2 * 3 * Copyright 2007 VMware, Inc. 4 * 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 8 * "Software"), to deal in the Software without restriction, including 9 * without limitation the rights to use, copy, modify, merge, publish, 10 * distribute, sub license, and/or sell copies of the Software, and to 11 * permit persons to whom the Software is furnished to do so, subject to 12 * the following conditions: 13 * 14 * The above copyright notice and this permission notice (including the 15 * next paragraph) shall be included in all copies or substantial portions 16 * of the Software. 17 * 18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 19 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 20 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. 21 * IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR 22 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 23 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 24 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 25 * 26 **************************************************************************/ 27 28 /** 29 * @file 30 * 31 * Screen, Adapter or GPU 32 * 33 * These are driver functions/facilities that are context independent. 34 */ 35 36 37 #ifndef P_SCREEN_H 38 #define P_SCREEN_H 39 40 41 #include "pipe/p_compiler.h" 42 #include "pipe/p_format.h" 43 #include "pipe/p_defines.h" 44 #include "pipe/p_video_enums.h" 45 46 47 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 53 /** Opaque types */ 54 struct winsys_handle; 55 struct pipe_fence_handle; 56 struct pipe_resource; 57 struct pipe_surface; 58 struct pipe_transfer; 59 struct pipe_box; 60 struct pipe_memory_info; 61 struct pipe_vertex_buffer; 62 struct pipe_vertex_element; 63 struct pipe_vertex_state; 64 struct disk_cache; 65 struct driOptionCache; 66 struct u_transfer_helper; 67 struct pipe_screen; 68 69 typedef struct pipe_vertex_state * 70 (*pipe_create_vertex_state_func)(struct pipe_screen *screen, 71 struct pipe_vertex_buffer *buffer, 72 const struct pipe_vertex_element *elements, 73 unsigned num_elements, 74 struct pipe_resource *indexbuf, 75 uint32_t full_velem_mask); 76 typedef void (*pipe_vertex_state_destroy_func)(struct pipe_screen *screen, 77 struct pipe_vertex_state *); 78 79 /** 80 * Gallium screen/adapter context. Basically everything 81 * hardware-specific that doesn't actually require a rendering 82 * context. 83 */ 84 struct pipe_screen { 85 /** 86 * Atomically incremented by drivers to track the number of contexts. 87 * If it's 0, it can be assumed that contexts are not tracked. 88 * Used by some places to skip locking if num_contexts == 1. 89 */ 90 unsigned num_contexts; 91 92 /** 93 * For drivers using u_transfer_helper: 94 */ 95 struct u_transfer_helper *transfer_helper; 96 97 void (*destroy)( struct pipe_screen * ); 98 99 const char *(*get_name)( struct pipe_screen * ); 100 101 const char *(*get_vendor)( struct pipe_screen * ); 102 103 /** 104 * Returns the device vendor. 105 * 106 * The returned value should return the actual device vendor/manufacturer, 107 * rather than a potentially generic driver string. 108 */ 109 const char *(*get_device_vendor)( struct pipe_screen * ); 110 111 /** 112 * Query an integer-valued capability/parameter/limit 113 * \param param one of PIPE_CAP_x 114 */ 115 int (*get_param)( struct pipe_screen *, enum pipe_cap param ); 116 117 /** 118 * Query a float-valued capability/parameter/limit 119 * \param param one of PIPE_CAP_x 120 */ 121 float (*get_paramf)( struct pipe_screen *, enum pipe_capf param ); 122 123 /** 124 * Query a per-shader-stage integer-valued capability/parameter/limit 125 * \param param one of PIPE_CAP_x 126 */ 127 int (*get_shader_param)( struct pipe_screen *, enum pipe_shader_type shader, 128 enum pipe_shader_cap param ); 129 130 /** 131 * Query an integer-valued capability/parameter/limit for a codec/profile 132 * \param param one of PIPE_VIDEO_CAP_x 133 */ 134 int (*get_video_param)( struct pipe_screen *, 135 enum pipe_video_profile profile, 136 enum pipe_video_entrypoint entrypoint, 137 enum pipe_video_cap param ); 138 139 /** 140 * Query a compute-specific capability/parameter/limit. 141 * \param ir_type shader IR type for which the param applies, or don't care 142 * if the param is not shader related 143 * \param param one of PIPE_COMPUTE_CAP_x 144 * \param ret pointer to a preallocated buffer that will be 145 * initialized to the parameter value, or NULL. 146 * \return size in bytes of the parameter value that would be 147 * returned. 148 */ 149 int (*get_compute_param)(struct pipe_screen *, 150 enum pipe_shader_ir ir_type, 151 enum pipe_compute_cap param, 152 void *ret); 153 154 /** 155 * Get the sample pixel grid's size. This function requires 156 * PIPE_CAP_PROGRAMMABLE_SAMPLE_LOCATIONS to be callable. 157 * 158 * \param sample_count - total number of samples 159 * \param out_width - the width of the pixel grid 160 * \param out_height - the height of the pixel grid 161 */ 162 void (*get_sample_pixel_grid)(struct pipe_screen *, unsigned sample_count, 163 unsigned *out_width, unsigned *out_height); 164 165 /** 166 * Query a timestamp in nanoseconds. The returned value should match 167 * PIPE_QUERY_TIMESTAMP. This function returns immediately and doesn't 168 * wait for rendering to complete (which cannot be achieved with queries). 169 */ 170 uint64_t (*get_timestamp)(struct pipe_screen *); 171 172 /** 173 * Create a context. 174 * 175 * \param screen pipe screen 176 * \param priv a pointer to set in pipe_context::priv 177 * \param flags a mask of PIPE_CONTEXT_* flags 178 */ 179 struct pipe_context * (*context_create)(struct pipe_screen *screen, 180 void *priv, unsigned flags); 181 182 /** 183 * Check if the given pipe_format is supported as a texture or 184 * drawing surface. 185 * \param bindings bitmask of PIPE_BIND_* 186 */ 187 bool (*is_format_supported)( struct pipe_screen *, 188 enum pipe_format format, 189 enum pipe_texture_target target, 190 unsigned sample_count, 191 unsigned storage_sample_count, 192 unsigned bindings ); 193 194 /** 195 * Check if the given pipe_format is supported as output for this codec/profile. 196 * \param profile profile to check, may also be PIPE_VIDEO_PROFILE_UNKNOWN 197 */ 198 bool (*is_video_format_supported)( struct pipe_screen *, 199 enum pipe_format format, 200 enum pipe_video_profile profile, 201 enum pipe_video_entrypoint entrypoint ); 202 203 /** 204 * Check if we can actually create the given resource (test the dimension, 205 * overall size, etc). Used to implement proxy textures. 206 * \return TRUE if size is OK, FALSE if too large. 207 */ 208 bool (*can_create_resource)(struct pipe_screen *screen, 209 const struct pipe_resource *templat); 210 211 /** 212 * Create a new texture object, using the given template info. 213 */ 214 struct pipe_resource * (*resource_create)(struct pipe_screen *, 215 const struct pipe_resource *templat); 216 217 struct pipe_resource * (*resource_create_front)(struct pipe_screen *, 218 const struct pipe_resource *templat, 219 const void *map_front_private); 220 221 /** 222 * Create a texture from a winsys_handle. The handle is often created in 223 * another process by first creating a pipe texture and then calling 224 * resource_get_handle. 225 * 226 * NOTE: in the case of WINSYS_HANDLE_TYPE_FD handles, the caller 227 * retains ownership of the FD. (This is consistent with 228 * EGL_EXT_image_dma_buf_import) 229 * 230 * \param usage A combination of PIPE_HANDLE_USAGE_* flags. 231 */ 232 struct pipe_resource * (*resource_from_handle)(struct pipe_screen *, 233 const struct pipe_resource *templat, 234 struct winsys_handle *handle, 235 unsigned usage); 236 237 /** 238 * Create a resource from user memory. This maps the user memory into 239 * the device address space. 240 */ 241 struct pipe_resource * (*resource_from_user_memory)(struct pipe_screen *, 242 const struct pipe_resource *t, 243 void *user_memory); 244 245 /** 246 * Unlike pipe_resource::bind, which describes what gallium frontends want, 247 * resources can have much greater capabilities in practice, often implied 248 * by the tiling layout or memory placement. This function allows querying 249 * whether a capability is supported beyond what was requested by state 250 * trackers. It's also useful for querying capabilities of imported 251 * resources where the capabilities are unknown at first. 252 * 253 * Only these flags are allowed: 254 * - PIPE_BIND_SCANOUT 255 * - PIPE_BIND_CURSOR 256 * - PIPE_BIND_LINEAR 257 */ 258 bool (*check_resource_capability)(struct pipe_screen *screen, 259 struct pipe_resource *resource, 260 unsigned bind); 261 262 /** 263 * Get a winsys_handle from a texture. Some platforms/winsys requires 264 * that the texture is created with a special usage flag like 265 * DISPLAYTARGET or PRIMARY. 266 * 267 * The context parameter can optionally be used to flush the resource and 268 * the context to make sure the resource is coherent with whatever user 269 * will use it. Some drivers may also use the context to convert 270 * the resource into a format compatible for sharing. The use case is 271 * OpenGL-OpenCL interop. The context parameter is allowed to be NULL. 272 * 273 * NOTE: for multi-planar resources (which may or may not have the planes 274 * chained through the pipe_resource next pointer) the frontend will 275 * always call this function with the first resource of the chain. It is 276 * the pipe drivers responsibility to walk the resources as needed when 277 * called with handle->plane != 0. 278 * 279 * NOTE: in the case of WINSYS_HANDLE_TYPE_FD handles, the caller 280 * takes ownership of the FD. (This is consistent with 281 * EGL_MESA_image_dma_buf_export) 282 * 283 * \param usage A combination of PIPE_HANDLE_USAGE_* flags. 284 */ 285 bool (*resource_get_handle)(struct pipe_screen *, 286 struct pipe_context *context, 287 struct pipe_resource *tex, 288 struct winsys_handle *handle, 289 unsigned usage); 290 291 /** 292 * Get info for the given pipe resource without the need to get a 293 * winsys_handle. 294 * 295 * The context parameter can optionally be used to flush the resource and 296 * the context to make sure the resource is coherent with whatever user 297 * will use it. Some drivers may also use the context to convert 298 * the resource into a format compatible for sharing. The context parameter 299 * is allowed to be NULL. 300 */ 301 bool (*resource_get_param)(struct pipe_screen *screen, 302 struct pipe_context *context, 303 struct pipe_resource *resource, 304 unsigned plane, 305 unsigned layer, 306 unsigned level, 307 enum pipe_resource_param param, 308 unsigned handle_usage, 309 uint64_t *value); 310 311 /** 312 * Get stride and offset for the given pipe resource without the need to get 313 * a winsys_handle. 314 */ 315 void (*resource_get_info)(struct pipe_screen *screen, 316 struct pipe_resource *resource, 317 unsigned *stride, 318 unsigned *offset); 319 320 /** 321 * Mark the resource as changed so derived internal resources will be 322 * recreated on next use. 323 * 324 * This is necessary when reimporting external images that can't be directly 325 * used as texture sampler source, to avoid sampling from old copies. 326 */ 327 void (*resource_changed)(struct pipe_screen *, struct pipe_resource *pt); 328 329 void (*resource_destroy)(struct pipe_screen *, 330 struct pipe_resource *pt); 331 332 333 /** 334 * Do any special operations to ensure frontbuffer contents are 335 * displayed, eg copy fake frontbuffer. 336 * \param winsys_drawable_handle an opaque handle that the calling context 337 * gets out-of-band 338 * \param subbox an optional sub region to flush 339 */ 340 void (*flush_frontbuffer)( struct pipe_screen *screen, 341 struct pipe_context *ctx, 342 struct pipe_resource *resource, 343 unsigned level, unsigned layer, 344 void *winsys_drawable_handle, 345 struct pipe_box *subbox ); 346 347 /** Set ptr = fence, with reference counting */ 348 void (*fence_reference)( struct pipe_screen *screen, 349 struct pipe_fence_handle **ptr, 350 struct pipe_fence_handle *fence ); 351 352 /** 353 * Wait for the fence to finish. 354 * 355 * If the fence was created with PIPE_FLUSH_DEFERRED, and the context is 356 * still unflushed, and the ctx parameter of fence_finish is equal to 357 * the context where the fence was created, fence_finish will flush 358 * the context prior to waiting for the fence. 359 * 360 * In all other cases, the ctx parameter has no effect. 361 * 362 * \param timeout in nanoseconds (may be PIPE_TIMEOUT_INFINITE). 363 */ 364 bool (*fence_finish)(struct pipe_screen *screen, 365 struct pipe_context *ctx, 366 struct pipe_fence_handle *fence, 367 uint64_t timeout); 368 369 /** 370 * For fences created with PIPE_FLUSH_FENCE_FD (exported fd) or 371 * by create_fence_fd() (imported fd), return the native fence fd 372 * associated with the fence. This may return -1 for fences 373 * created with PIPE_FLUSH_DEFERRED if the fence command has not 374 * been flushed yet. 375 */ 376 int (*fence_get_fd)(struct pipe_screen *screen, 377 struct pipe_fence_handle *fence); 378 379 /** 380 * Returns a driver-specific query. 381 * 382 * If \p info is NULL, the number of available queries is returned. 383 * Otherwise, the driver query at the specified \p index is returned 384 * in \p info. The function returns non-zero on success. 385 */ 386 int (*get_driver_query_info)(struct pipe_screen *screen, 387 unsigned index, 388 struct pipe_driver_query_info *info); 389 390 /** 391 * Returns a driver-specific query group. 392 * 393 * If \p info is NULL, the number of available groups is returned. 394 * Otherwise, the driver query group at the specified \p index is returned 395 * in \p info. The function returns non-zero on success. 396 */ 397 int (*get_driver_query_group_info)(struct pipe_screen *screen, 398 unsigned index, 399 struct pipe_driver_query_group_info *info); 400 401 /** 402 * Query information about memory usage. 403 */ 404 void (*query_memory_info)(struct pipe_screen *screen, 405 struct pipe_memory_info *info); 406 407 /** 408 * Get IR specific compiler options struct. For PIPE_SHADER_IR_NIR this 409 * returns a 'struct nir_shader_compiler_options'. Drivers reporting 410 * NIR as the preferred IR must implement this. 411 */ 412 const void *(*get_compiler_options)(struct pipe_screen *screen, 413 enum pipe_shader_ir ir, 414 enum pipe_shader_type shader); 415 416 /** 417 * Returns a pointer to a driver-specific on-disk shader cache. If the 418 * driver failed to create the cache or does not support an on-disk shader 419 * cache NULL is returned. The callback itself may also be NULL if the 420 * driver doesn't support an on-disk shader cache. 421 */ 422 struct disk_cache *(*get_disk_shader_cache)(struct pipe_screen *screen); 423 424 /** 425 * Create a new texture object from the given template info, taking 426 * format modifiers into account. \p modifiers specifies a list of format 427 * modifier tokens, as defined in drm_fourcc.h. The driver then picks the 428 * best modifier among these and creates the resource. \p count must 429 * contain the size of \p modifiers array. 430 * 431 * Returns NULL if an entry in \p modifiers is unsupported by the driver, 432 * or if only DRM_FORMAT_MOD_INVALID is provided. 433 */ 434 struct pipe_resource * (*resource_create_with_modifiers)( 435 struct pipe_screen *, 436 const struct pipe_resource *templat, 437 const uint64_t *modifiers, int count); 438 439 /** 440 * Get supported modifiers for a format. 441 * If \p max is 0, the total number of supported modifiers for the supplied 442 * format is returned in \p count, with no modification to \p modifiers. 443 * Otherwise, \p modifiers is filled with upto \p max supported modifier 444 * codes, and \p count with the number of modifiers copied. 445 * The \p external_only array is used to return whether the format and 446 * modifier combination can only be used with an external texture target. 447 */ 448 void (*query_dmabuf_modifiers)(struct pipe_screen *screen, 449 enum pipe_format format, int max, 450 uint64_t *modifiers, 451 unsigned int *external_only, int *count); 452 453 /** 454 * Create a memory object from a winsys handle 455 * 456 * The underlying memory is most often allocated in by a foregin API. 457 * Then the underlying memory object is then exported through interfaces 458 * compatible with EXT_external_resources. 459 * 460 * Note: For WINSYS_HANDLE_TYPE_FD handles, the caller retains ownership 461 * of the fd. 462 * 463 * \param handle A handle representing the memory object to import 464 */ 465 struct pipe_memory_object *(*memobj_create_from_handle)(struct pipe_screen *screen, 466 struct winsys_handle *handle, 467 bool dedicated); 468 469 /** 470 * Destroy a memory object 471 * 472 * \param memobj The memory object to destroy 473 */ 474 void (*memobj_destroy)(struct pipe_screen *screen, 475 struct pipe_memory_object *memobj); 476 477 /** 478 * Create a texture from a memory object 479 * 480 * \param t texture template 481 * \param memobj The memory object used to back the texture 482 */ 483 struct pipe_resource * (*resource_from_memobj)(struct pipe_screen *screen, 484 const struct pipe_resource *t, 485 struct pipe_memory_object *memobj, 486 uint64_t offset); 487 488 /** 489 * Fill @uuid with a unique driver identifier 490 * 491 * \param uuid pointer to a memory region of PIPE_UUID_SIZE bytes 492 */ 493 void (*get_driver_uuid)(struct pipe_screen *screen, char *uuid); 494 495 /** 496 * Fill @uuid with a unique device identifier 497 * 498 * \param uuid pointer to a memory region of PIPE_UUID_SIZE bytes 499 */ 500 void (*get_device_uuid)(struct pipe_screen *screen, char *uuid); 501 502 /** 503 * Set the maximum number of parallel shader compiler threads. 504 */ 505 void (*set_max_shader_compiler_threads)(struct pipe_screen *screen, 506 unsigned max_threads); 507 508 /** 509 * Return whether parallel shader compilation has finished. 510 */ 511 bool (*is_parallel_shader_compilation_finished)(struct pipe_screen *screen, 512 void *shader, 513 unsigned shader_type); 514 515 /** 516 * Set the damage region (called when KHR_partial_update() is invoked). 517 * This function is passed an array of rectangles encoding the damage area. 518 * rects are using the bottom-left origin convention. 519 * nrects = 0 means 'reset the damage region'. What 'reset' implies is HW 520 * specific. For tile-based renderers, the damage extent is typically set 521 * to cover the whole resource with no damage rect (or a 0-size damage 522 * rect). This way, the existing resource content is reloaded into the 523 * local tile buffer for every tile thus making partial tile update 524 * possible. For HW operating in immediate mode, this reset operation is 525 * likely to be a NOOP. 526 */ 527 void (*set_damage_region)(struct pipe_screen *screen, 528 struct pipe_resource *resource, 529 unsigned int nrects, 530 const struct pipe_box *rects); 531 532 /** 533 * Run driver-specific NIR lowering and optimization passes. 534 * 535 * gallium frontends should call this before passing shaders to drivers, 536 * and ideally also before shader caching. 537 * 538 * The driver may return a non-NULL string to trigger GLSL link failure and 539 * logging of that message in the GLSL linker log. 540 */ 541 char *(*finalize_nir)(struct pipe_screen *screen, void *nir); 542 543 /*Separated memory/resource allocations interfaces for Vulkan */ 544 545 /** 546 * Create a resource, and retrieve the required size for it but don't allocate 547 * any backing memory. 548 */ 549 struct pipe_resource * (*resource_create_unbacked)(struct pipe_screen *, 550 const struct pipe_resource *templat, 551 uint64_t *size_required); 552 553 /** 554 * Allocate backing memory to be bound to resources. 555 */ 556 struct pipe_memory_allocation *(*allocate_memory)(struct pipe_screen *screen, 557 uint64_t size); 558 /** 559 * Free previously allocated backing memory. 560 */ 561 void (*free_memory)(struct pipe_screen *screen, 562 struct pipe_memory_allocation *); 563 564 /** 565 * Allocate fd-based memory to be bound to resources. 566 */ 567 struct pipe_memory_allocation *(*allocate_memory_fd)(struct pipe_screen *screen, 568 uint64_t size, 569 int *fd); 570 571 /** 572 * Import memory from an fd-handle. 573 */ 574 bool (*import_memory_fd)(struct pipe_screen *screen, 575 int fd, 576 struct pipe_memory_allocation **pmem, 577 uint64_t *size); 578 579 /** 580 * Free previously allocated fd-based memory. 581 */ 582 void (*free_memory_fd)(struct pipe_screen *screen, 583 struct pipe_memory_allocation *pmem); 584 585 /** 586 * Bind memory to a resource. 587 */ 588 bool (*resource_bind_backing)(struct pipe_screen *screen, 589 struct pipe_resource *pt, 590 struct pipe_memory_allocation *pmem, 591 uint64_t offset); 592 593 /** 594 * Map backing memory. 595 */ 596 void *(*map_memory)(struct pipe_screen *screen, 597 struct pipe_memory_allocation *pmem); 598 599 /** 600 * Unmap backing memory. 601 */ 602 void (*unmap_memory)(struct pipe_screen *screen, 603 struct pipe_memory_allocation *pmem); 604 605 /** 606 * Determine whether the screen supports the specified modifier 607 * 608 * Query whether the driver supports a \p modifier in combination with 609 * \p format. If \p external_only is not NULL, the value it points to will 610 * be set to 0 or a non-zero value to indicate whether the modifier and 611 * format combination is supported only with external, or also with non- 612 * external texture targets respectively. The \p external_only parameter is 613 * not used when the function returns false. 614 * 615 * \return true if the format+modifier pair is supported on \p screen, false 616 * otherwise. 617 */ 618 bool (*is_dmabuf_modifier_supported)(struct pipe_screen *screen, 619 uint64_t modifier, enum pipe_format, 620 bool *external_only); 621 622 /** 623 * Get the number of planes required for a given modifier/format pair. 624 * 625 * If not NULL, this function returns the number of planes needed to 626 * represent \p format in the layout specified by \p modifier, including 627 * any driver-specific auxiliary data planes. 628 * 629 * Must only be called on a modifier supported by the screen for the 630 * specified format. 631 * 632 * If NULL, no auxiliary planes are required for any modifier+format pairs 633 * supported by \p screen. Hence, the plane count can be derived directly 634 * from \p format. 635 * 636 * \return Number of planes needed to store image data in the layout defined 637 * by \p format and \p modifier. 638 */ 639 unsigned int (*get_dmabuf_modifier_planes)(struct pipe_screen *screen, 640 uint64_t modifier, 641 enum pipe_format format); 642 643 /** 644 * Vertex state CSO functions for precomputing vertex and index buffer 645 * states for display lists. 646 */ 647 pipe_create_vertex_state_func create_vertex_state; 648 pipe_vertex_state_destroy_func vertex_state_destroy; 649 }; 650 651 652 /** 653 * Global configuration options for screen creation. 654 */ 655 struct pipe_screen_config { 656 struct driOptionCache *options; 657 const struct driOptionCache *options_info; 658 }; 659 660 661 #ifdef __cplusplus 662 } 663 #endif 664 665 #endif /* P_SCREEN_H */ 666