.. _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 * 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_INTEROP_MEM_DESC ` :ref:`UR_STRUCTURE_TYPE_EXP_INTEROP_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-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_INTEROP_MEMORY_IMPORT_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_INTEROP_MEMORY_EXPORT_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_INTEROP_SEMAPHORE_IMPORT_SUPPORT_EXP ` * :ref:`UR_DEVICE_INFO_INTEROP_SEMAPHORE_EXPORT_SUPPORT_EXP ` * :ref:`ur-command-t` * :ref:`UR_COMMAND_INTEROP_SEMAPHORE_WAIT_EXP ` * :ref:`UR_COMMAND_INTEROP_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-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_OPAQUE_FD_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_MAP_EXTERNAL_ARRAY_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_RELEASE_INTEROP_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_SEMAPHORE_OPAQUE_FD_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_DESTROY_EXTERNAL_SEMAPHORE_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_WAIT_EXTERNAL_SEMAPHORE_EXP ` * :ref:`UR_FUNCTION_BINDLESS_IMAGES_SIGNAL_EXTERNAL_SEMAPHORE_EXP ` Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :ref:`ur-exp-sampler-mip-properties-t` * ur_exp_image_handle_t * ur_exp_image_mem_handle_t * ur_exp_interop_mem_handle_t * ur_exp_interop_semaphore_handle_t * :ref:`ur-exp-interop-mem-desc-t` * :ref:`ur-exp-interop-semaphore-desc-t` * :ref:`ur-exp-file-descriptor-t` * :ref:`ur-exp-win32-handle-t` * :ref:`ur-exp-sampler-addr-modes-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:`urBindlessImagesImportOpaqueFDExp` * :ref:`urBindlessImagesMapExternalArrayExp` * :ref:`urBindlessImagesReleaseInteropExp` * :ref:`urBindlessImagesImportExternalSemaphoreOpaqueFDExp` * :ref:`urBindlessImagesDestroyExternalSemaphoreExp` * :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. | +------------------------------------------------------------------------+ 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 `_