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 disk_cache; 62 struct driOptionCache; 63 struct u_transfer_helper; 64 65 /** 66 * Gallium screen/adapter context. Basically everything 67 * hardware-specific that doesn't actually require a rendering 68 * context. 69 */ 70 struct pipe_screen { 71 72 /** 73 * For drivers using u_transfer_helper: 74 */ 75 struct u_transfer_helper *transfer_helper; 76 77 void (*destroy)( struct pipe_screen * ); 78 79 const char *(*get_name)( struct pipe_screen * ); 80 81 const char *(*get_vendor)( struct pipe_screen * ); 82 83 /** 84 * Returns the device vendor. 85 * 86 * The returned value should return the actual device vendor/manufacturer, 87 * rather than a potentially generic driver string. 88 */ 89 const char *(*get_device_vendor)( struct pipe_screen * ); 90 91 /** 92 * Query an integer-valued capability/parameter/limit 93 * \param param one of PIPE_CAP_x 94 */ 95 int (*get_param)( struct pipe_screen *, enum pipe_cap param ); 96 97 /** 98 * Query a float-valued capability/parameter/limit 99 * \param param one of PIPE_CAP_x 100 */ 101 float (*get_paramf)( struct pipe_screen *, enum pipe_capf param ); 102 103 /** 104 * Query a per-shader-stage integer-valued capability/parameter/limit 105 * \param param one of PIPE_CAP_x 106 */ 107 int (*get_shader_param)( struct pipe_screen *, enum pipe_shader_type shader, 108 enum pipe_shader_cap param ); 109 110 /** 111 * Query an integer-valued capability/parameter/limit for a codec/profile 112 * \param param one of PIPE_VIDEO_CAP_x 113 */ 114 int (*get_video_param)( struct pipe_screen *, 115 enum pipe_video_profile profile, 116 enum pipe_video_entrypoint entrypoint, 117 enum pipe_video_cap param ); 118 119 /** 120 * Query a compute-specific capability/parameter/limit. 121 * \param ir_type shader IR type for which the param applies, or don't care 122 * if the param is not shader related 123 * \param param one of PIPE_COMPUTE_CAP_x 124 * \param ret pointer to a preallocated buffer that will be 125 * initialized to the parameter value, or NULL. 126 * \return size in bytes of the parameter value that would be 127 * returned. 128 */ 129 int (*get_compute_param)(struct pipe_screen *, 130 enum pipe_shader_ir ir_type, 131 enum pipe_compute_cap param, 132 void *ret); 133 134 /** 135 * Get the sample pixel grid's size. This function requires 136 * PIPE_CAP_PROGRAMMABLE_SAMPLE_LOCATIONS to be callable. 137 * 138 * \param sample_count - total number of samples 139 * \param out_width - the width of the pixel grid 140 * \param out_height - the height of the pixel grid 141 */ 142 void (*get_sample_pixel_grid)(struct pipe_screen *, unsigned sample_count, 143 unsigned *out_width, unsigned *out_height); 144 145 /** 146 * Query a timestamp in nanoseconds. The returned value should match 147 * PIPE_QUERY_TIMESTAMP. This function returns immediately and doesn't 148 * wait for rendering to complete (which cannot be achieved with queries). 149 */ 150 uint64_t (*get_timestamp)(struct pipe_screen *); 151 152 /** 153 * Create a context. 154 * 155 * \param screen pipe screen 156 * \param priv a pointer to set in pipe_context::priv 157 * \param flags a mask of PIPE_CONTEXT_* flags 158 */ 159 struct pipe_context * (*context_create)(struct pipe_screen *screen, 160 void *priv, unsigned flags); 161 162 /** 163 * Check if the given pipe_format is supported as a texture or 164 * drawing surface. 165 * \param bindings bitmask of PIPE_BIND_* 166 */ 167 bool (*is_format_supported)( struct pipe_screen *, 168 enum pipe_format format, 169 enum pipe_texture_target target, 170 unsigned sample_count, 171 unsigned storage_sample_count, 172 unsigned bindings ); 173 174 /** 175 * Check if the given pipe_format is supported as output for this codec/profile. 176 * \param profile profile to check, may also be PIPE_VIDEO_PROFILE_UNKNOWN 177 */ 178 bool (*is_video_format_supported)( struct pipe_screen *, 179 enum pipe_format format, 180 enum pipe_video_profile profile, 181 enum pipe_video_entrypoint entrypoint ); 182 183 /** 184 * Check if we can actually create the given resource (test the dimension, 185 * overall size, etc). Used to implement proxy textures. 186 * \return TRUE if size is OK, FALSE if too large. 187 */ 188 bool (*can_create_resource)(struct pipe_screen *screen, 189 const struct pipe_resource *templat); 190 191 /** 192 * Create a new texture object, using the given template info. 193 */ 194 struct pipe_resource * (*resource_create)(struct pipe_screen *, 195 const struct pipe_resource *templat); 196 197 struct pipe_resource * (*resource_create_front)(struct pipe_screen *, 198 const struct pipe_resource *templat, 199 const void *map_front_private); 200 201 /** 202 * Create a texture from a winsys_handle. The handle is often created in 203 * another process by first creating a pipe texture and then calling 204 * resource_get_handle. 205 * 206 * NOTE: in the case of WINSYS_HANDLE_TYPE_FD handles, the caller 207 * retains ownership of the FD. (This is consistent with 208 * EGL_EXT_image_dma_buf_import) 209 * 210 * \param usage A combination of PIPE_HANDLE_USAGE_* flags. 211 */ 212 struct pipe_resource * (*resource_from_handle)(struct pipe_screen *, 213 const struct pipe_resource *templat, 214 struct winsys_handle *handle, 215 unsigned usage); 216 217 /** 218 * Create a resource from user memory. This maps the user memory into 219 * the device address space. 220 */ 221 struct pipe_resource * (*resource_from_user_memory)(struct pipe_screen *, 222 const struct pipe_resource *t, 223 void *user_memory); 224 225 /** 226 * Unlike pipe_resource::bind, which describes what gallium frontends want, 227 * resources can have much greater capabilities in practice, often implied 228 * by the tiling layout or memory placement. This function allows querying 229 * whether a capability is supported beyond what was requested by state 230 * trackers. It's also useful for querying capabilities of imported 231 * resources where the capabilities are unknown at first. 232 * 233 * Only these flags are allowed: 234 * - PIPE_BIND_SCANOUT 235 * - PIPE_BIND_CURSOR 236 * - PIPE_BIND_LINEAR 237 */ 238 bool (*check_resource_capability)(struct pipe_screen *screen, 239 struct pipe_resource *resource, 240 unsigned bind); 241 242 /** 243 * Get a winsys_handle from a texture. Some platforms/winsys requires 244 * that the texture is created with a special usage flag like 245 * DISPLAYTARGET or PRIMARY. 246 * 247 * The context parameter can optionally be used to flush the resource and 248 * the context to make sure the resource is coherent with whatever user 249 * will use it. Some drivers may also use the context to convert 250 * the resource into a format compatible for sharing. The use case is 251 * OpenGL-OpenCL interop. The context parameter is allowed to be NULL. 252 * 253 * NOTE: for multi-planar resources (which may or may not have the planes 254 * chained through the pipe_resource next pointer) the frontend will 255 * always call this function with the first resource of the chain. It is 256 * the pipe drivers responsibility to walk the resources as needed when 257 * called with handle->plane != 0. 258 * 259 * NOTE: in the case of WINSYS_HANDLE_TYPE_FD handles, the caller 260 * takes ownership of the FD. (This is consistent with 261 * EGL_MESA_image_dma_buf_export) 262 * 263 * \param usage A combination of PIPE_HANDLE_USAGE_* flags. 264 */ 265 bool (*resource_get_handle)(struct pipe_screen *, 266 struct pipe_context *context, 267 struct pipe_resource *tex, 268 struct winsys_handle *handle, 269 unsigned usage); 270 271 /** 272 * Get info for the given pipe resource without the need to get a 273 * winsys_handle. 274 * 275 * The context parameter can optionally be used to flush the resource and 276 * the context to make sure the resource is coherent with whatever user 277 * will use it. Some drivers may also use the context to convert 278 * the resource into a format compatible for sharing. The context parameter 279 * is allowed to be NULL. 280 */ 281 bool (*resource_get_param)(struct pipe_screen *screen, 282 struct pipe_context *context, 283 struct pipe_resource *resource, 284 unsigned plane, 285 unsigned layer, 286 unsigned level, 287 enum pipe_resource_param param, 288 unsigned handle_usage, 289 uint64_t *value); 290 291 /** 292 * Get stride and offset for the given pipe resource without the need to get 293 * a winsys_handle. 294 */ 295 void (*resource_get_info)(struct pipe_screen *screen, 296 struct pipe_resource *resource, 297 unsigned *stride, 298 unsigned *offset); 299 300 /** 301 * Mark the resource as changed so derived internal resources will be 302 * recreated on next use. 303 * 304 * This is necessary when reimporting external images that can't be directly 305 * used as texture sampler source, to avoid sampling from old copies. 306 */ 307 void (*resource_changed)(struct pipe_screen *, struct pipe_resource *pt); 308 309 void (*resource_destroy)(struct pipe_screen *, 310 struct pipe_resource *pt); 311 312 313 /** 314 * Do any special operations to ensure frontbuffer contents are 315 * displayed, eg copy fake frontbuffer. 316 * \param winsys_drawable_handle an opaque handle that the calling context 317 * gets out-of-band 318 * \param subbox an optional sub region to flush 319 */ 320 void (*flush_frontbuffer)( struct pipe_screen *screen, 321 struct pipe_resource *resource, 322 unsigned level, unsigned layer, 323 void *winsys_drawable_handle, 324 struct pipe_box *subbox ); 325 326 /** Set ptr = fence, with reference counting */ 327 void (*fence_reference)( struct pipe_screen *screen, 328 struct pipe_fence_handle **ptr, 329 struct pipe_fence_handle *fence ); 330 331 /** 332 * Wait for the fence to finish. 333 * 334 * If the fence was created with PIPE_FLUSH_DEFERRED, and the context is 335 * still unflushed, and the ctx parameter of fence_finish is equal to 336 * the context where the fence was created, fence_finish will flush 337 * the context prior to waiting for the fence. 338 * 339 * In all other cases, the ctx parameter has no effect. 340 * 341 * \param timeout in nanoseconds (may be PIPE_TIMEOUT_INFINITE). 342 */ 343 bool (*fence_finish)(struct pipe_screen *screen, 344 struct pipe_context *ctx, 345 struct pipe_fence_handle *fence, 346 uint64_t timeout); 347 348 /** 349 * For fences created with PIPE_FLUSH_FENCE_FD (exported fd) or 350 * by create_fence_fd() (imported fd), return the native fence fd 351 * associated with the fence. This may return -1 for fences 352 * created with PIPE_FLUSH_DEFERRED if the fence command has not 353 * been flushed yet. 354 */ 355 int (*fence_get_fd)(struct pipe_screen *screen, 356 struct pipe_fence_handle *fence); 357 358 /** 359 * Returns a driver-specific query. 360 * 361 * If \p info is NULL, the number of available queries is returned. 362 * Otherwise, the driver query at the specified \p index is returned 363 * in \p info. The function returns non-zero on success. 364 */ 365 int (*get_driver_query_info)(struct pipe_screen *screen, 366 unsigned index, 367 struct pipe_driver_query_info *info); 368 369 /** 370 * Returns a driver-specific query group. 371 * 372 * If \p info is NULL, the number of available groups is returned. 373 * Otherwise, the driver query group at the specified \p index is returned 374 * in \p info. The function returns non-zero on success. 375 */ 376 int (*get_driver_query_group_info)(struct pipe_screen *screen, 377 unsigned index, 378 struct pipe_driver_query_group_info *info); 379 380 /** 381 * Query information about memory usage. 382 */ 383 void (*query_memory_info)(struct pipe_screen *screen, 384 struct pipe_memory_info *info); 385 386 /** 387 * Get IR specific compiler options struct. For PIPE_SHADER_IR_NIR this 388 * returns a 'struct nir_shader_compiler_options'. Drivers reporting 389 * NIR as the preferred IR must implement this. 390 */ 391 const void *(*get_compiler_options)(struct pipe_screen *screen, 392 enum pipe_shader_ir ir, 393 enum pipe_shader_type shader); 394 395 /** 396 * Returns a pointer to a driver-specific on-disk shader cache. If the 397 * driver failed to create the cache or does not support an on-disk shader 398 * cache NULL is returned. The callback itself may also be NULL if the 399 * driver doesn't support an on-disk shader cache. 400 */ 401 struct disk_cache *(*get_disk_shader_cache)(struct pipe_screen *screen); 402 403 /** 404 * Create a new texture object from the given template info, taking 405 * format modifiers into account. \p modifiers specifies a list of format 406 * modifier tokens, as defined in drm_fourcc.h. The driver then picks the 407 * best modifier among these and creates the resource. \p count must 408 * contain the size of \p modifiers array. 409 * 410 * Returns NULL if an entry in \p modifiers is unsupported by the driver, 411 * or if only DRM_FORMAT_MOD_INVALID is provided. 412 */ 413 struct pipe_resource * (*resource_create_with_modifiers)( 414 struct pipe_screen *, 415 const struct pipe_resource *templat, 416 const uint64_t *modifiers, int count); 417 418 /** 419 * Get supported modifiers for a format. 420 * If \p max is 0, the total number of supported modifiers for the supplied 421 * format is returned in \p count, with no modification to \p modifiers. 422 * Otherwise, \p modifiers is filled with upto \p max supported modifier 423 * codes, and \p count with the number of modifiers copied. 424 * The \p external_only array is used to return whether the format and 425 * modifier combination can only be used with an external texture target. 426 */ 427 void (*query_dmabuf_modifiers)(struct pipe_screen *screen, 428 enum pipe_format format, int max, 429 uint64_t *modifiers, 430 unsigned int *external_only, int *count); 431 432 /** 433 * Create a memory object from a winsys handle 434 * 435 * The underlying memory is most often allocated in by a foregin API. 436 * Then the underlying memory object is then exported through interfaces 437 * compatible with EXT_external_resources. 438 * 439 * Note: For WINSYS_HANDLE_TYPE_FD handles, the caller retains ownership 440 * of the fd. 441 * 442 * \param handle A handle representing the memory object to import 443 */ 444 struct pipe_memory_object *(*memobj_create_from_handle)(struct pipe_screen *screen, 445 struct winsys_handle *handle, 446 bool dedicated); 447 448 /** 449 * Destroy a memory object 450 * 451 * \param memobj The memory object to destroy 452 */ 453 void (*memobj_destroy)(struct pipe_screen *screen, 454 struct pipe_memory_object *memobj); 455 456 /** 457 * Create a texture from a memory object 458 * 459 * \param t texture template 460 * \param memobj The memory object used to back the texture 461 */ 462 struct pipe_resource * (*resource_from_memobj)(struct pipe_screen *screen, 463 const struct pipe_resource *t, 464 struct pipe_memory_object *memobj, 465 uint64_t offset); 466 467 /** 468 * Fill @uuid with a unique driver identifier 469 * 470 * \param uuid pointer to a memory region of PIPE_UUID_SIZE bytes 471 */ 472 void (*get_driver_uuid)(struct pipe_screen *screen, char *uuid); 473 474 /** 475 * Fill @uuid with a unique device identifier 476 * 477 * \param uuid pointer to a memory region of PIPE_UUID_SIZE bytes 478 */ 479 void (*get_device_uuid)(struct pipe_screen *screen, char *uuid); 480 481 /** 482 * Set the maximum number of parallel shader compiler threads. 483 */ 484 void (*set_max_shader_compiler_threads)(struct pipe_screen *screen, 485 unsigned max_threads); 486 487 /** 488 * Return whether parallel shader compilation has finished. 489 */ 490 bool (*is_parallel_shader_compilation_finished)(struct pipe_screen *screen, 491 void *shader, 492 unsigned shader_type); 493 494 /** 495 * Set the damage region (called when KHR_partial_update() is invoked). 496 * This function is passed an array of rectangles encoding the damage area. 497 * rects are using the bottom-left origin convention. 498 * nrects = 0 means 'reset the damage region'. What 'reset' implies is HW 499 * specific. For tile-based renderers, the damage extent is typically set 500 * to cover the whole resource with no damage rect (or a 0-size damage 501 * rect). This way, the existing resource content is reloaded into the 502 * local tile buffer for every tile thus making partial tile update 503 * possible. For HW operating in immediate mode, this reset operation is 504 * likely to be a NOOP. 505 */ 506 void (*set_damage_region)(struct pipe_screen *screen, 507 struct pipe_resource *resource, 508 unsigned int nrects, 509 const struct pipe_box *rects); 510 511 /** 512 * Run driver-specific NIR lowering and optimization passes. 513 * 514 * gallium frontends should call this before passing shaders to drivers, 515 * and ideally also before shader caching. 516 * 517 * \param optimize Whether the input shader hasn't been optimized and 518 * should be. 519 */ 520 void (*finalize_nir)(struct pipe_screen *screen, void *nir, bool optimize); 521 522 /*Separated memory/resource allocations interfaces for Vulkan */ 523 524 /** 525 * Create a resource, and retrieve the required size for it but don't allocate 526 * any backing memory. 527 */ 528 struct pipe_resource * (*resource_create_unbacked)(struct pipe_screen *, 529 const struct pipe_resource *templat, 530 uint64_t *size_required); 531 532 /** 533 * Allocate backing memory to be bound to resources. 534 */ 535 struct pipe_memory_allocation *(*allocate_memory)(struct pipe_screen *screen, 536 uint64_t size); 537 /** 538 * Free previously allocated backing memory. 539 */ 540 void (*free_memory)(struct pipe_screen *screen, 541 struct pipe_memory_allocation *); 542 543 /** 544 * Bind memory to a resource. 545 */ 546 void (*resource_bind_backing)(struct pipe_screen *screen, 547 struct pipe_resource *pt, 548 struct pipe_memory_allocation *pmem, 549 uint64_t offset); 550 551 /** 552 * Map backing memory. 553 */ 554 void *(*map_memory)(struct pipe_screen *screen, 555 struct pipe_memory_allocation *pmem); 556 557 /** 558 * Unmap backing memory. 559 */ 560 void (*unmap_memory)(struct pipe_screen *screen, 561 struct pipe_memory_allocation *pmem); 562 }; 563 564 565 /** 566 * Global configuration options for screen creation. 567 */ 568 struct pipe_screen_config { 569 const struct driOptionCache *options; 570 }; 571 572 573 #ifdef __cplusplus 574 } 575 #endif 576 577 #endif /* P_SCREEN_H */ 578