.. _experimental-bindless-images: ================================================================================ Bindless Images ================================================================================ .. warning:: Experimental features: * May be replaced, updated, or removed at any time. * Do not require maintaining API/ABI stability of their own additions over time. * Do not require conformance testing of their own additions. Terminology -------------------------------------------------------------------------------- For the purposes of this document, a bindless image is one which provides access to the underlying data via image reference handles. At the application level, this allows the user to implement programs where the number of images is not known at compile-time, and store all handles to images -- irrespective of varying formats and layouts -- in some container, e.g. a dynamic array. Motivation -------------------------------------------------------------------------------- The `DPC++ bindless images extension `_ has sought to provide the flexibility of bindless images at the SYCL application level. This extension has been implemented using the CUDA backend of the DPC++ PI. With the movement to migrate from PI to the Unified Runtime in DPC++, as seen in `Port CUDA plugin to Unified Runtime `_, the Unified Runtime's support for this experimental feature would enable the DPC++ bindless images extension to be migrated to UR without issue. Overview -------------------------------------------------------------------------------- In this document, we propose the following experimental additions to the Unified Runtime: * Bindless images support * Sampled images * Unsampled images * Mipmaps * Image arrays * Cubemaps * USM backed images * Interoperability support * External memory * Semaphores API -------------------------------------------------------------------------------- Enums ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :ref:`ur-structure-type-t` :ref:`UR_STRUCTURE_TYPE_EXP_SAMPLER_MIP_PROPERTIES ` :ref:`UR_STRUCTURE_TYPE_EXP_EXTERNAL_MEM_DESC ` :ref:`UR_STRUCTURE_TYPE_EXP_EXTERNAL_SEMAPHORE_DESC ` :ref:`UR_STRUCTURE_TYPE_EXP_FILE_DESCRIPTOR ` :ref:`UR_STRUCTURE_TYPE_EXP_WIN32_HANDLE ` :ref:`UR_STRUCTURE_TYPE_EXP_SAMPLER_ADDR_MODES ` :ref:`UR_STRUCTURE_TYPE_EXP_SAMPLER_CUBEMAP_PROPERTIES ` * :ref:`ur-device-info-t` * :ref:`UR_DEVICE_INFO_BINDLESS_IMAGES_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_BINDLESS_IMAGES_SHARED_USM_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_BINDLESS_IMAGES_1D_USM_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_BINDLESS_IMAGES_2D_USM_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_IMAGE_PITCH_ALIGN_EXP ` * :ref:`UR_DEVICE_INFO_MAX_IMAGE_LINEAR_WIDTH_EXP ` * :ref:`UR_DEVICE_INFO_MAX_IMAGE_LINEAR_HEIGHT_EXP ` * :ref:`UR_DEVICE_INFO_MAX_IMAGE_LINEAR_PITCH_EXP ` * :ref:`UR_DEVICE_INFO_MIPMAP_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_MIPMAP_ANISOTROPY_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_MIPMAP_MAX_ANISOTROPY_EXP ` * :ref:`UR_DEVICE_INFO_MIPMAP_LEVEL_REFERENCE_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_EXTERNAL_MEMORY_IMPORT_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_EXTERNAL_SEMAPHORE_IMPORT_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_CUBEMAP_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_CUBEMAP_SEAMLESS_FILTERING_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_BINDLESS_SAMPLED_IMAGE_FETCH_1D_USM_EXP ` * :ref:`UR_DEVICE_INFO_BINDLESS_SAMPLED_IMAGE_FETCH_1D_EXP ` * :ref:`UR_DEVICE_INFO_BINDLESS_SAMPLED_IMAGE_FETCH_2D_USM_EXP ` * :ref:`UR_DEVICE_INFO_BINDLESS_SAMPLED_IMAGE_FETCH_2D_EXP ` * :ref:`UR_DEVICE_INFO_BINDLESS_SAMPLED_IMAGE_FETCH_3D_EXP ` * :ref:`UR_DEVICE_INFO_IMAGE_ARRAY_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_BINDLESS_UNIQUE_ADDRESSING_PER_DIM_EXP ` * :ref:`UR_DEVICE_INFO_BINDLESS_SAMPLE_1D_USM_EXP ` * :ref:`UR_DEVICE_INFO_BINDLESS_SAMPLE_2D_USM_EXP ` * :ref:`ur-command-t` * :ref:`UR_COMMAND_EXTERNAL_SEMAPHORE_WAIT_EXP ` * :ref:`UR_COMMAND_EXTERNAL_SEMAPHORE_SIGNAL_EXP ` * :ref:`ur-exp-image-copy-flags-t` * :ref:`UR_EXP_IMAGE_COPY_FLAG_HOST_TO_DEVICE ` * :ref:`UR_EXP_IMAGE_COPY_FLAG_DEVICE_TO_HOST ` * :ref:`UR_EXP_IMAGE_COPY_FLAG_DEVICE_TO_DEVICE ` * :ref:`ur-exp-sampler-cubemap-filter-mode-t` * :ref:`UR_EXP_SAMPLER_CUBEMAP_FILTER_MODE_SEAMLESS ` * :ref:`UR_EXP_SAMPLER_CUBEMAP_FILTER_MODE_DISJOINTED ` * :ref:`ur-exp-external-mem-type-t` * :ref:`UR_EXP_EXTERNAL_MEM_TYPE_OPAQUE_FD ` * :ref:`UR_EXP_EXTERNAL_MEM_TYPE_WIN32_NT ` * :ref:`UR_EXP_EXTERNAL_MEM_TYPE_WIN32_NT_DX12_RESOURCE ` * :ref:`ur-exp-external-semaphore-type-t` * :ref:`UR_EXP_EXTERNAL_SEMAPHORE_TYPE_OPAQUE_FD ` * :ref:`UR_EXP_EXTERNAL_SEMAPHORE_TYPE_WIN32_NT ` * :ref:`UR_EXP_EXTERNAL_SEMAPHORE_TYPE_WIN32_NT_DX12_FENCE ` * :ref:`ur-function-t` * :ref:`UR_FUNCTION_USM_PITCHED_ALLOC_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_UNSAMPLED_IMAGE_HANDLE_DESTROY_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_SAMPLED_IMAGE_HANDLE_DESTROY_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_IMAGE_ALLOCATE_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_IMAGE_FREE_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_UNSAMPLED_IMAGE_CREATE_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_SAMPLED_IMAGE_CREATE_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_IMAGE_COPY_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_IMAGE_GET_INFO_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_MIPMAP_GET_LEVEL_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_MIPMAP_FREE_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_MEMORY_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_MAP_EXTERNAL_ARRAY_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_RELEASE_EXTERNAL_MEMORY_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_SEMAPHORE_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_RELEASE_EXTERNAL_SEMAPHORE_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_WAIT_EXTERNAL_SEMAPHORE_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_SIGNAL_EXTERNAL_SEMAPHORE_EXP ` * :ref:`ur-mem-type-t` * :ref:`UR_MEM_TYPE_IMAGE_CUBEMAP_EXP ` Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :ref:`ur-exp-sampler-mip-properties-t` * ur_exp_image_native_handle_t * ur_exp_image_mem_native_handle_t * ur_exp_external_mem_handle_t * ur_exp_external_semaphore_handle_t * :ref:`ur-exp-external-mem-desc-t` * :ref:`ur-exp-external-semaphore-desc-t` * :ref:`ur-exp-file-descriptor-t` * :ref:`ur-exp-win32-handle-t` * :ref:`ur-exp-sampler-addr-modes-t` * :ref:`ur-exp-sampler-cubemap-properties-t` * :ref:`ur-exp-image-copy-region-t` Functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * USM * :ref:`urUSMPitchedAllocExp` * Bindless Images * :ref:`urBindlessImagesUnsampledImageHandleDestroyExp` * :ref:`urBindlessImagesSampledImageHandleDestroyExp` * :ref:`urBindlessImagesImageAllocateExp` * :ref:`urBindlessImagesImageFreeExp` * :ref:`urBindlessImagesUnsampledImageCreateExp` * :ref:`urBindlessImagesSampledImageCreateExp` * :ref:`urBindlessImagesImageCopyExp` * :ref:`urBindlessImagesImageGetInfoExp` * :ref:`urBindlessImagesMipmapGetLevelExp` * :ref:`urBindlessImagesMipmapFreeExp` * Interop * :ref:`urBindlessImagesImportExternalMemoryExp` * :ref:`urBindlessImagesMapExternalArrayExp` * :ref:`urBindlessImagesMapExternalLinearMemoryExp` * :ref:`urBindlessImagesReleaseExternalMemoryExp` * :ref:`urBindlessImagesImportExternalSemaphoreExp` * :ref:`urBindlessImagesReleaseExternalSemaphoreExp` * :ref:`urBindlessImagesWaitExternalSemaphoreExp` * :ref:`urBindlessImagesSignalExternalSemaphoreExp` Changelog -------------------------------------------------------------------------------- +----------+----------------------------------------------------------+ | Revision | Changes | +==========+==========================================================+ | 1.0 | Initial Draft | +----------+----------------------------------------------------------+ | 2.0 || Added device parameters to UR functions. | | || Added sub-region copy parameters to image copy function.| | || Removed 3D USM capabilities. | | || Added mip filter mode. | +----------+----------------------------------------------------------+ | 3.0 | Added device query for bindless images on shared USM | +----------+-------------------------------------------------------------+ | 4.0 || Added platform specific interop resource handles. | | || Added and updated to use new interop resource descriptors. | +----------+-------------------------------------------------------------+ | 5.0 | Update interop struct and func param names to adhere to convention. | +----------+-------------------------------------------------------------+ | 6.0 | Fix semaphore import function parameter name. | +----------+-------------------------------------------------------------+ | 7.0 | Add layered image properties struct. | +----------+-------------------------------------------------------------+ | 8.0 | Added structure for sampler addressing modes per dimension. | +------------------------------------------------------------------------+ | 9.0 | Remove layered image properties struct. | +------------------------------------------------------------------------+ | 10.0 | Added cubemap image type, sampling properties, and device | | | queries. | +------------------------------------------------------------------------+ | 11.0 | Added device queries for sampled image fetch capabilities. | +----------+-------------------------------------------------------------+ | 12.0 | Added image arrays to list of supported bindless images | +----------+-------------------------------------------------------------+ | 13.0 || Interop import API has been adapted to cater to multiple | | || external memory and semaphore handle types | | || Removed the following APIs: | | || - ImportExternalOpaqueFDExp | | || - ImportExternalSemaphoreOpaqueFDExp | | || Added the following APIs: | | || - ImportExternalMemoryExp | | || - ImportExternalSemaphoreExp | | || Added the following enums: | | || - exp_external_mem_type_t | | || - exp_external_semaphore_type_t | | || Semaphore oparations now take value parameters which set | | || the state the semaphore should wait on or signal. | | || Introduced resource enums for DX12 interop: | | || - :ref:`UR_EXP_EXTERNAL_MEM_TYPE_WIN32_NT_DX12_RESOURCE ` | | || - :ref:`UR_EXP_EXTERNAL_SEMAPHORE_TYPE_WIN32_NT_DX12_FENCE ` | +------------------------------------------------------------------------+ | 14.0 || Rename func BindlessImagesDestroyExternalSemaphoreExp to | | || BindlessImagesReleaseExternalSemaphoreExp | +------------------------------------------------------------------------+ | 15.0 | Added structures for supporting copying. | +----------+-------------------------------------------------------------+ | 16.0 || Update device queries to resolve inconsistencies and | | || missing queries. | +----------+-------------------------------------------------------------+ | 17.0 || Rename interop related structs and funcs with "external" | | || keyword over "interop". | +----------+-------------------------------------------------------------+ | 18.0 | Added BindlessImagesMapExternalLinearMemoryExp function. | +----------+-------------------------------------------------------------+ Contributors -------------------------------------------------------------------------------- * Isaac Ault `isaac.ault@codeplay.com `_ * Duncan Brawley `duncan.brawley@codeplay.com `_ * Przemek Malon `przemek.malon@codeplay.com `_ * Chedy Najjar `chedy.najjar@codeplay.com `_ * Sean Stirling `sean.stirling@codeplay.com `_ * Peter Zuzek `peter@codeplay.com peter@codeplay.com `_