// Copyright 2015-2024 The Khronos Group Inc. // // SPDX-License-Identifier: CC-BY-4.0 [[capabilities]] = Additional Capabilities This chapter describes additional capabilities beyond the minimum capabilities described in the <> and <> chapters, including: * <> ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] * <> endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] * <> endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] * <> endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] ifdef::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] * <> endif::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] [[capabilities-image]] == Additional Image Capabilities Additional image capabilities, such as larger dimensions or additional sample counts for certain image types, or additional capabilities for _linear_ tiling format images, are described in this section. [open,refpage='vkGetPhysicalDeviceImageFormatProperties',desc='Lists physical device\'s image format capabilities',type='protos'] -- :refpage: vkGetPhysicalDeviceImageFormatProperties To query additional capabilities specific to image types, call: include::{generated}/api/protos/vkGetPhysicalDeviceImageFormatProperties.adoc[] * pname:physicalDevice is the physical device from which to query the image capabilities. * pname:format is a elink:VkFormat value specifying the image format, corresponding to slink:VkImageCreateInfo::pname:format. * pname:type is a elink:VkImageType value specifying the image type, corresponding to slink:VkImageCreateInfo::pname:imageType. * pname:tiling is a elink:VkImageTiling value specifying the image tiling, corresponding to slink:VkImageCreateInfo::pname:tiling. * pname:usage is a bitmask of elink:VkImageUsageFlagBits specifying the intended usage of the image, corresponding to slink:VkImageCreateInfo::pname:usage. * pname:flags is a bitmask of elink:VkImageCreateFlagBits specifying additional parameters of the image, corresponding to slink:VkImageCreateInfo::pname:flags. * pname:pImageFormatProperties is a pointer to a slink:VkImageFormatProperties structure in which capabilities are returned. The pname:format, pname:type, pname:tiling, pname:usage, and pname:flags parameters correspond to parameters that would be consumed by flink:vkCreateImage (as members of slink:VkImageCreateInfo). If pname:format is not a supported image format, or if the combination of pname:format, pname:type, pname:tiling, pname:usage, and pname:flags is not supported for images, then fname:vkGetPhysicalDeviceImageFormatProperties returns ename:VK_ERROR_FORMAT_NOT_SUPPORTED. The limitations on an image format that are reported by fname:vkGetPhysicalDeviceImageFormatProperties have the following property: if code:usage1 and code:usage2 of type tlink:VkImageUsageFlags are such that the bits set in code:usage1 are a subset of the bits set in code:usage2, and code:flags1 and code:flags2 of type tlink:VkImageCreateFlags are such that the bits set in code:flags1 are a subset of the bits set in code:flags2, then the limitations for code:usage1 and code:flags1 must: be no more strict than the limitations for code:usage2 and code:flags2, for all values of pname:format, pname:type, and pname:tiling. ifdef::VK_EXT_host_image_copy[] If `apiext:VK_EXT_host_image_copy` is supported, pname:usage includes ename:VK_IMAGE_USAGE_SAMPLED_BIT, and pname:flags does not include either of ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, then the result of calls to fname:vkGetPhysicalDeviceImageFormatProperties with identical parameters except for the inclusion of ename:VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT in pname:usage must: be identical. endif::VK_EXT_host_image_copy[] include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] ifdef::VK_EXT_image_drm_format_modifier[] .Valid Usage **** * [[VUID-vkGetPhysicalDeviceImageFormatProperties-tiling-02248]] pname:tiling must: not be ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. (Use flink:vkGetPhysicalDeviceImageFormatProperties2 instead) **** endif::VK_EXT_image_drm_format_modifier[] include::{generated}/validity/protos/vkGetPhysicalDeviceImageFormatProperties.adoc[] -- [open,refpage='VkImageFormatProperties',desc='Structure specifying an image format properties',type='structs'] -- The sname:VkImageFormatProperties structure is defined as: include::{generated}/api/structs/VkImageFormatProperties.adoc[] * pname:maxExtent are the maximum image dimensions. See the <> section below for how these values are constrained by pname:type. * pname:maxMipLevels is the maximum number of mipmap levels. pname:maxMipLevels must: be equal to the number of levels in the complete mipmap chain based on the [eq]#pname:maxExtent.width#, [eq]#pname:maxExtent.height#, and [eq]#pname:maxExtent.depth#, except when one of the following conditions is true, in which case it may: instead be `1`: ** fname:vkGetPhysicalDeviceImageFormatProperties::pname:tiling was ename:VK_IMAGE_TILING_LINEAR ifdef::VK_EXT_image_drm_format_modifier[] ** slink:VkPhysicalDeviceImageFormatInfo2::pname:tiling was ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT endif::VK_EXT_image_drm_format_modifier[] ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] ** the slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext chain included a slink:VkPhysicalDeviceExternalImageFormatInfo structure with a handle type included in the pname:handleTypes member for which mipmap image support is not required endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ** image pname:format is one of the <> endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ifdef::VK_EXT_fragment_density_map[] ** pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT endif::VK_EXT_fragment_density_map[] * pname:maxArrayLayers is the maximum number of array layers. pname:maxArrayLayers must: be no less than slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers, except when one of the following conditions is true, in which case it may: instead be `1`: ** pname:tiling is ename:VK_IMAGE_TILING_LINEAR ** pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL and pname:type is ename:VK_IMAGE_TYPE_3D ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ** pname:format is one of the <> endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ifdef::VK_EXT_image_drm_format_modifier[] * If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then pname:maxArrayLayers must: not be 0. endif::VK_EXT_image_drm_format_modifier[] * pname:sampleCounts is a bitmask of elink:VkSampleCountFlagBits specifying all the supported sample counts for this image as described <>. * pname:maxResourceSize is an upper bound on the total image size in bytes, inclusive of all image subresources. Implementations may: have an address space limit on total size of a resource, which is advertised by this property. pname:maxResourceSize must: be at least 2^31^. [NOTE] .Note ==== There is no mechanism to query the size of an image before creating it, to compare that size against pname:maxResourceSize. If an application attempts to create an image that exceeds this limit, the creation will fail and flink:vkCreateImage will return ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. While the advertised limit must: be at least 2^31^, it may: not be possible to create an image that approaches that size, particularly for ename:VK_IMAGE_TYPE_1D. ==== If the combination of parameters to fname:vkGetPhysicalDeviceImageFormatProperties is not supported by the implementation for use in flink:vkCreateImage, then all members of sname:VkImageFormatProperties will be filled with zero. [NOTE] .Note ==== Filling sname:VkImageFormatProperties with zero for unsupported formats is an exception to the usual rule that output structures have undefined: contents on error. This exception was unintentional, but is preserved for backwards compatibility. ==== include::{generated}/validity/structs/VkImageFormatProperties.adoc[] -- ifdef::VK_NV_external_memory_capabilities[] include::{chapters}/VK_NV_external_memory_capabilities/external_image_format.adoc[] endif::VK_NV_external_memory_capabilities[] ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] [open,refpage='vkGetPhysicalDeviceImageFormatProperties2',desc='Lists physical device\'s image format capabilities',type='protos'] -- :refpage: vkGetPhysicalDeviceImageFormatProperties2 To query additional capabilities specific to image types, call: ifdef::VK_VERSION_1_1[] include::{generated}/api/protos/vkGetPhysicalDeviceImageFormatProperties2.adoc[] endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] ifdef::VK_KHR_get_physical_device_properties2[] include::{generated}/api/protos/vkGetPhysicalDeviceImageFormatProperties2KHR.adoc[] endif::VK_KHR_get_physical_device_properties2[] * pname:physicalDevice is the physical device from which to query the image capabilities. * pname:pImageFormatInfo is a pointer to a slink:VkPhysicalDeviceImageFormatInfo2 structure describing the parameters that would be consumed by flink:vkCreateImage. * pname:pImageFormatProperties is a pointer to a slink:VkImageFormatProperties2 structure in which capabilities are returned. fname:vkGetPhysicalDeviceImageFormatProperties2 behaves similarly to flink:vkGetPhysicalDeviceImageFormatProperties, with the ability to return extended information in a pname:pNext chain of output structures. ifdef::VK_KHR_video_queue[] If the pname:pNext chain of pname:pImageFormatInfo includes a slink:VkVideoProfileListInfoKHR structure with a pname:profileCount member greater than `0`, then this command returns format capabilities specific to image types used in conjunction with the specified <>. In this case, this command will return one of the <> if any of the profiles specified via slink:VkVideoProfileListInfoKHR::pname:pProfiles are not supported. Furthermore, if slink:VkPhysicalDeviceImageFormatInfo2::pname:usage includes any image usage flag not supported by the specified video profiles, then this command returns ename:VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR. endif::VK_KHR_video_queue[] include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer,VK_EXT_host_image_copy[] .Valid Usage **** ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkGetPhysicalDeviceImageFormatProperties2-pNext-01868]] If the pname:pNext chain of pname:pImageFormatProperties includes a slink:VkAndroidHardwareBufferUsageANDROID structure, the pname:pNext chain of pname:pImageFormatInfo must: include a slink:VkPhysicalDeviceExternalImageFormatInfo structure with pname:handleType set to ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_EXT_host_image_copy[] * [[VUID-vkGetPhysicalDeviceImageFormatProperties2-pNext-09004]] If the pname:pNext chain of pname:pImageFormatProperties includes a slink:VkHostImageCopyDevicePerformanceQueryEXT structure, pname:pImageFormatInfo->usage must: contain ename:VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT endif::VK_EXT_host_image_copy[] **** endif::VK_ANDROID_external_memory_android_hardware_buffer,VK_EXT_host_image_copy[] include::{generated}/validity/protos/vkGetPhysicalDeviceImageFormatProperties2.adoc[] -- [open,refpage='VkPhysicalDeviceImageFormatInfo2',desc='Structure specifying image creation parameters',type='structs'] -- The sname:VkPhysicalDeviceImageFormatInfo2 structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceImageFormatInfo2.adoc[] ifdef::VK_KHR_get_physical_device_properties2[] or the equivalent include::{generated}/api/structs/VkPhysicalDeviceImageFormatInfo2KHR.adoc[] endif::VK_KHR_get_physical_device_properties2[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. The pname:pNext chain of sname:VkPhysicalDeviceImageFormatInfo2 is used to provide additional image parameters to fname:vkGetPhysicalDeviceImageFormatProperties2. * pname:format is a elink:VkFormat value indicating the image format, corresponding to slink:VkImageCreateInfo::pname:format. * pname:type is a elink:VkImageType value indicating the image type, corresponding to slink:VkImageCreateInfo::pname:imageType. * pname:tiling is a elink:VkImageTiling value indicating the image tiling, corresponding to slink:VkImageCreateInfo::pname:tiling. * pname:usage is a bitmask of elink:VkImageUsageFlagBits indicating the intended usage of the image, corresponding to slink:VkImageCreateInfo::pname:usage. * pname:flags is a bitmask of elink:VkImageCreateFlagBits indicating additional parameters of the image, corresponding to slink:VkImageCreateInfo::pname:flags. The members of sname:VkPhysicalDeviceImageFormatInfo2 correspond to the arguments to flink:vkGetPhysicalDeviceImageFormatProperties, with pname:sType and pname:pNext added for extensibility. ifdef::VK_EXT_image_drm_format_modifier[] .Valid Usage **** * [[VUID-VkPhysicalDeviceImageFormatInfo2-tiling-02249]] pname:tiling must: be ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT if and only if the pname:pNext chain includes slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT * [[VUID-VkPhysicalDeviceImageFormatInfo2-tiling-02313]] If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and pname:flags contains ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, then the pname:pNext chain must: include a slink:VkImageFormatListCreateInfo structure with non-zero pname:viewFormatCount **** endif::VK_EXT_image_drm_format_modifier[] include::{generated}/validity/structs/VkPhysicalDeviceImageFormatInfo2.adoc[] -- [open,refpage='VkImageFormatProperties2',desc='Structure specifying an image format properties',type='structs'] -- The sname:VkImageFormatProperties2 structure is defined as: include::{generated}/api/structs/VkImageFormatProperties2.adoc[] ifdef::VK_KHR_get_physical_device_properties2[] or the equivalent include::{generated}/api/structs/VkImageFormatProperties2KHR.adoc[] endif::VK_KHR_get_physical_device_properties2[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. The pname:pNext chain of sname:VkImageFormatProperties2 is used to allow the specification of additional capabilities to be returned from fname:vkGetPhysicalDeviceImageFormatProperties2. * pname:imageFormatProperties is a slink:VkImageFormatProperties structure in which capabilities are returned. If the combination of parameters to fname:vkGetPhysicalDeviceImageFormatProperties2 is not supported by the implementation for use in flink:vkCreateImage, then all members of pname:imageFormatProperties will be filled with zero. [NOTE] .Note ==== Filling pname:imageFormatProperties with zero for unsupported formats is an exception to the usual rule that output structures have undefined: contents on error. This exception was unintentional, but is preserved for backwards compatibility. This exception only applies to pname:imageFormatProperties, not pname:sType, pname:pNext, or any structures chained from pname:pNext. ==== include::{generated}/validity/structs/VkImageFormatProperties2.adoc[] -- ifdef::VK_AMD_texture_gather_bias_lod[] [open,refpage='VkTextureLODGatherFormatPropertiesAMD',desc='Structure informing whether or not texture gather bias/LOD functionality is supported for a given image format and a given physical device.',type='structs'] -- To determine if texture gather functions that take explicit LOD and/or bias argument values can: be used with a given image format, add a slink:VkTextureLODGatherFormatPropertiesAMD structure to the pname:pNext chain of the slink:VkImageFormatProperties2 structure in a call to fname:vkGetPhysicalDeviceImageFormatProperties2. The sname:VkTextureLODGatherFormatPropertiesAMD structure is defined as: include::{generated}/api/structs/VkTextureLODGatherFormatPropertiesAMD.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:supportsTextureGatherLODBiasAMD tells if the image format can be used with texture gather bias/LOD functions, as introduced by the `apiext:VK_AMD_texture_gather_bias_lod` extension. This field is set by the implementation. User-specified value is ignored. include::{generated}/validity/structs/VkTextureLODGatherFormatPropertiesAMD.adoc[] -- endif::VK_AMD_texture_gather_bias_lod[] ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] [open,refpage='VkPhysicalDeviceExternalImageFormatInfo',desc='Structure specifying external image creation parameters',type='structs'] -- To determine the image capabilities compatible with an external memory handle type, add a slink:VkPhysicalDeviceExternalImageFormatInfo structure to the pname:pNext chain of the slink:VkPhysicalDeviceImageFormatInfo2 structure and a sname:VkExternalImageFormatProperties structure to the pname:pNext chain of the slink:VkImageFormatProperties2 structure. The sname:VkPhysicalDeviceExternalImageFormatInfo structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceExternalImageFormatInfo.adoc[] ifdef::VK_KHR_external_memory_capabilities[] or the equivalent include::{generated}/api/structs/VkPhysicalDeviceExternalImageFormatInfoKHR.adoc[] endif::VK_KHR_external_memory_capabilities[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value specifying the memory handle type that will be used with the memory associated with the image. If pname:handleType is 0, flink:vkGetPhysicalDeviceImageFormatProperties2 will behave as if slink:VkPhysicalDeviceExternalImageFormatInfo was not present, and slink:VkExternalImageFormatProperties will be ignored. If pname:handleType is not compatible with the pname:format, pname:type, pname:tiling, pname:usage, and pname:flags specified in slink:VkPhysicalDeviceImageFormatInfo2, then flink:vkGetPhysicalDeviceImageFormatProperties2 returns ename:VK_ERROR_FORMAT_NOT_SUPPORTED. include::{generated}/validity/structs/VkPhysicalDeviceExternalImageFormatInfo.adoc[] -- [open,refpage='VkExternalMemoryHandleTypeFlagBits',desc='Bit specifying external memory handle types',type='enums'] -- Possible values of slink:VkPhysicalDeviceExternalImageFormatInfo::pname:handleType, specifying an external memory handle type, are: include::{generated}/api/enums/VkExternalMemoryHandleTypeFlagBits.adoc[] ifdef::VK_KHR_external_memory_capabilities[] or the equivalent include::{generated}/api/enums/VkExternalMemoryHandleTypeFlagBitsKHR.adoc[] endif::VK_KHR_external_memory_capabilities[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT specifies a POSIX file descriptor handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must: be compatible with the POSIX system calls code:dup, code:dup2, code:close, and the non-standard system call code:dup3. Additionally, it must: be transportable over a socket using an code:SCM_RIGHTS control message. It owns a reference to the underlying memory resource represented by its Vulkan memory object. * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT specifies an NT handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must: be compatible with the functions code:DuplicateHandle, code:CloseHandle, code:CompareObjectHandles, code:GetHandleInformation, and code:SetHandleInformation. It owns a reference to the underlying memory resource represented by its Vulkan memory object. * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT specifies a global share handle that has only limited valid usage outside of Vulkan and other compatible APIs. It is not compatible with any native APIs. It does not own a reference to the underlying memory resource represented by its Vulkan memory object, and will therefore become invalid when all Vulkan memory objects associated with it are destroyed. * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT specifies an NT handle returned by code:IDXGIResource1::code:CreateSharedHandle referring to a Direct3D 10 or 11 texture resource. It owns a reference to the memory used by the Direct3D resource. * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT specifies a global share handle returned by code:IDXGIResource::code:GetSharedHandle referring to a Direct3D 10 or 11 texture resource. It does not own a reference to the underlying Direct3D resource, and will therefore become invalid when all Vulkan memory objects and Direct3D resources associated with it are destroyed. * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT specifies an NT handle returned by code:ID3D12Device::code:CreateSharedHandle referring to a Direct3D 12 heap resource. It owns a reference to the resources used by the Direct3D heap. * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT specifies an NT handle returned by code:ID3D12Device::code:CreateSharedHandle referring to a Direct3D 12 committed resource. It owns a reference to the memory used by the Direct3D resource. ifdef::VK_EXT_external_memory_host[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT specifies a host pointer returned by a host memory allocation command. It does not own a reference to the underlying memory resource, and will therefore become invalid if the host memory is freed. * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT specifies a host pointer to _host mapped foreign memory_. It does not own a reference to the underlying memory resource, and will therefore become invalid if the foreign memory is unmapped or otherwise becomes no longer available. endif::VK_EXT_external_memory_host[] ifdef::VK_EXT_external_memory_dma_buf[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT is a file descriptor for a Linux dma_buf. It owns a reference to the underlying memory resource represented by its Vulkan memory object. endif::VK_EXT_external_memory_dma_buf[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID specifies an basetype:AHardwareBuffer object defined by the Android NDK. See <> for more details of this handle type. endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_FUCHSIA_external_memory[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA is a Zircon handle to a virtual memory object. endif::VK_FUCHSIA_external_memory[] ifdef::VK_NV_external_memory_rdma[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NV is a handle to an allocation accessible by remote devices. It owns a reference to the underlying memory resource represented by its Vulkan memory object. endif::VK_NV_external_memory_rdma[] ifdef::VK_NV_external_memory_sci_buf[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCI_BUF_BIT_NV specifies a volatile memory object (stext:NvSciBufObj) that is backed by a buffer and shareable across various hardware engines including the CPU, and software (intra-process and inter-process) and hardware (system memory) operating domains. endif::VK_NV_external_memory_sci_buf[] ifdef::VK_QNX_external_memory_screen_buffer[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX specifies a code:_screen_buffer object defined by the QNX SDP. See <> for more details of this handle type. endif::VK_QNX_external_memory_screen_buffer[] <<< Some external memory handle types can only be shared within the same underlying physical device and/or the same driver version, as defined in the following table: [[external-memory-handle-types-compatibility]] .External memory handle types compatibility |==== | Handle type | sname:VkPhysicalDeviceIDProperties{wbro}::pname:driverUUID | sname:VkPhysicalDeviceIDProperties{wbro}::pname:deviceUUID | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT | Must match | Must match | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT | Must match | Must match | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT | Must match | Must match | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT | Must match | Must match | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT | Must match | Must match | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT | Must match | Must match | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT | Must match | Must match ifdef::VK_EXT_external_memory_host[] | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT | No restriction | No restriction | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT | No restriction | No restriction endif::VK_EXT_external_memory_host[] ifdef::VK_EXT_external_memory_dma_buf[] | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT | No restriction | No restriction endif::VK_EXT_external_memory_dma_buf[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID | No restriction | No restriction endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_FUCHSIA_external_memory[] | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA | No restriction | No restriction endif::VK_FUCHSIA_external_memory[] ifdef::VK_NV_external_memory_rdma[] | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NV | No restriction | No restriction endif::VK_NV_external_memory_rdma[] ifdef::VK_NV_external_memory_sci_buf[] | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCI_BUF_BIT_NV | No restriction | No restriction endif::VK_NV_external_memory_sci_buf[] ifdef::VK_QNX_external_memory_screen_buffer[] | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX | No restriction | No restriction endif::VK_QNX_external_memory_screen_buffer[] |==== ifdef::VK_EXT_external_memory_host[] [NOTE] .Note ==== The above table does not restrict the drivers and devices with which ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT and ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT may: be shared, as these handle types inherently mean memory that does not come from the same device, as they import memory from the host or a foreign device, respectively. ==== endif::VK_EXT_external_memory_host[] ifdef::VK_EXT_external_memory_dma_buf[] [NOTE] .Note ==== Even though the above table does not restrict the drivers and devices with which ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT may: be shared, query mechanisms exist in the Vulkan API that prevent the import of incompatible dma-bufs (such as flink:vkGetMemoryFdPropertiesKHR) and that prevent incompatible usage of dma-bufs (such as slink:VkPhysicalDeviceExternalBufferInfo and slink:VkPhysicalDeviceExternalImageFormatInfo). ==== endif::VK_EXT_external_memory_dma_buf[] -- [open,refpage='VkExternalMemoryHandleTypeFlags',desc='Bitmask of VkExternalMemoryHandleTypeFlagBits',type='flags'] -- include::{generated}/api/flags/VkExternalMemoryHandleTypeFlags.adoc[] ifdef::VK_KHR_external_memory_capabilities[] or the equivalent include::{generated}/api/flags/VkExternalMemoryHandleTypeFlagsKHR.adoc[] endif::VK_KHR_external_memory_capabilities[] tname:VkExternalMemoryHandleTypeFlags is a bitmask type for setting a mask of zero or more elink:VkExternalMemoryHandleTypeFlagBits. -- [open,refpage='VkExternalImageFormatProperties',desc='Structure specifying supported external handle properties',type='structs'] -- The sname:VkExternalImageFormatProperties structure is defined as: include::{generated}/api/structs/VkExternalImageFormatProperties.adoc[] ifdef::VK_KHR_external_memory_capabilities[] or the equivalent include::{generated}/api/structs/VkExternalImageFormatPropertiesKHR.adoc[] endif::VK_KHR_external_memory_capabilities[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:externalMemoryProperties is a slink:VkExternalMemoryProperties structure specifying various capabilities of the external handle type when used with the specified image creation parameters. include::{generated}/validity/structs/VkExternalImageFormatProperties.adoc[] -- [open,refpage='VkExternalMemoryProperties',desc='Structure specifying external memory handle type capabilities',type='structs'] -- The sname:VkExternalMemoryProperties structure is defined as: include::{generated}/api/structs/VkExternalMemoryProperties.adoc[] ifdef::VK_KHR_external_memory_capabilities[] or the equivalent include::{generated}/api/structs/VkExternalMemoryPropertiesKHR.adoc[] endif::VK_KHR_external_memory_capabilities[] * pname:externalMemoryFeatures is a bitmask of elink:VkExternalMemoryFeatureFlagBits specifying the features of pname:handleType. * pname:exportFromImportedHandleTypes is a bitmask of elink:VkExternalMemoryHandleTypeFlagBits specifying which types of imported handle pname:handleType can: be exported from. * pname:compatibleHandleTypes is a bitmask of elink:VkExternalMemoryHandleTypeFlagBits specifying handle types which can: be specified at the same time as pname:handleType when creating an image compatible with external memory. pname:compatibleHandleTypes must: include at least pname:handleType. Inclusion of a handle type in pname:compatibleHandleTypes does not imply the values returned in slink:VkImageFormatProperties2 will be the same when slink:VkPhysicalDeviceExternalImageFormatInfo::pname:handleType is set to that type. The application is responsible for querying the capabilities of all handle types intended for concurrent use in a single image and intersecting them to obtain the compatible set of capabilities. include::{generated}/validity/structs/VkExternalMemoryProperties.adoc[] -- [open,refpage='VkExternalMemoryFeatureFlagBits',desc='Bitmask specifying features of an external memory handle type',type='enums'] -- Bits which may: be set in slink:VkExternalMemoryProperties::pname:externalMemoryFeatures, specifying features of an external memory handle type, are: include::{generated}/api/enums/VkExternalMemoryFeatureFlagBits.adoc[] ifdef::VK_KHR_external_memory_capabilities[] or the equivalent include::{generated}/api/enums/VkExternalMemoryFeatureFlagBitsKHR.adoc[] endif::VK_KHR_external_memory_capabilities[] * ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT specifies that images or buffers created with the specified parameters and handle type must: use the mechanisms defined by slink:VkMemoryDedicatedRequirements and slink:VkMemoryDedicatedAllocateInfo to create (or import) a dedicated allocation for the image or buffer. * ename:VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT specifies that handles of this type can: be exported from Vulkan memory objects. * ename:VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT specifies that handles of this type can: be imported as Vulkan memory objects. Because their semantics in external APIs roughly align with that of an image or buffer with a dedicated allocation in Vulkan, implementations are required: to report ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for the following external handle types: * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID for images only endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_QNX_external_memory_screen_buffer[] * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX for images only endif::VK_QNX_external_memory_screen_buffer[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] Implementations must: not report ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for buffers with external handle type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID. endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_QNX_external_memory_screen_buffer[] Implementations must: not report ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for buffers with external handle type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX. endif::VK_QNX_external_memory_screen_buffer[] ifdef::VK_EXT_external_memory_host[] Implementations must: not report ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for images or buffers with external handle type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT, or ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT. endif::VK_EXT_external_memory_host[] -- [open,refpage='VkExternalMemoryFeatureFlags',desc='Bitmask of VkExternalMemoryFeatureFlagBits',type='flags'] -- include::{generated}/api/flags/VkExternalMemoryFeatureFlags.adoc[] ifdef::VK_KHR_external_memory_capabilities[] or the equivalent include::{generated}/api/flags/VkExternalMemoryFeatureFlagsKHR.adoc[] endif::VK_KHR_external_memory_capabilities[] tname:VkExternalMemoryFeatureFlags is a bitmask type for setting a mask of zero or more elink:VkExternalMemoryFeatureFlagBits. -- endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] ifdef::VK_EXT_image_drm_format_modifier[] [open,refpage='VkPhysicalDeviceImageDrmFormatModifierInfoEXT',desc='Structure specifying a DRM format modifier as image creation parameter',type='structs'] -- To query the image capabilities that are compatible with a <>, set slink:VkPhysicalDeviceImageFormatInfo2::pname:tiling to ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and add a slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure to the pname:pNext chain of slink:VkPhysicalDeviceImageFormatInfo2. The slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceImageDrmFormatModifierInfoEXT.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:drmFormatModifier is the image's _Linux DRM format modifier_, corresponding to slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:modifier or to slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pModifiers. * pname:sharingMode specifies how the image will be accessed by multiple queue families. * pname:queueFamilyIndexCount is the number of entries in the pname:pQueueFamilyIndices array. * pname:pQueueFamilyIndices is a pointer to an array of queue families that will access the image. It is ignored if pname:sharingMode is not ename:VK_SHARING_MODE_CONCURRENT. If the pname:drmFormatModifier is incompatible with the parameters specified in slink:VkPhysicalDeviceImageFormatInfo2 and its pname:pNext chain, then flink:vkGetPhysicalDeviceImageFormatProperties2 returns ename:VK_ERROR_FORMAT_NOT_SUPPORTED. The implementation must: support the query of any pname:drmFormatModifier, including unknown and invalid modifier values. .Valid Usage **** * [[VUID-VkPhysicalDeviceImageDrmFormatModifierInfoEXT-sharingMode-02314]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, then pname:pQueueFamilyIndices must: be a valid pointer to an array of pname:queueFamilyIndexCount code:uint32_t values * [[VUID-VkPhysicalDeviceImageDrmFormatModifierInfoEXT-sharingMode-02315]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, then pname:queueFamilyIndexCount must: be greater than `1` * [[VUID-VkPhysicalDeviceImageDrmFormatModifierInfoEXT-sharingMode-02316]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element of pname:pQueueFamilyIndices must: be unique and must: be less than the pname:pQueueFamilyPropertyCount returned by flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the pname:physicalDevice that was used to create pname:device **** include::{generated}/validity/structs/VkPhysicalDeviceImageDrmFormatModifierInfoEXT.adoc[] -- endif::VK_EXT_image_drm_format_modifier[] ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] [open,refpage='VkSamplerYcbcrConversionImageFormatProperties',desc='Structure specifying combined image sampler descriptor count for multi-planar images',type='structs'] -- To determine the number of combined image samplers required to support a multi-planar format, add slink:VkSamplerYcbcrConversionImageFormatProperties to the pname:pNext chain of the slink:VkImageFormatProperties2 structure in a call to fname:vkGetPhysicalDeviceImageFormatProperties2. The sname:VkSamplerYcbcrConversionImageFormatProperties structure is defined as: include::{generated}/api/structs/VkSamplerYcbcrConversionImageFormatProperties.adoc[] ifdef::VK_KHR_sampler_ycbcr_conversion[] or the equivalent include::{generated}/api/structs/VkSamplerYcbcrConversionImageFormatPropertiesKHR.adoc[] endif::VK_KHR_sampler_ycbcr_conversion[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:combinedImageSamplerDescriptorCount is the number of combined image sampler descriptors that the implementation uses to access the format. include::{generated}/validity/structs/VkSamplerYcbcrConversionImageFormatProperties.adoc[] -- pname:combinedImageSamplerDescriptorCount is a number between 1 and the number of planes in the format. A descriptor set layout binding with immutable {YCbCr} conversion samplers will have a maximum pname:combinedImageSamplerDescriptorCount which is the maximum across all formats supported by its samplers of the pname:combinedImageSamplerDescriptorCount for each format. Descriptor sets with that layout will internally use that maximum pname:combinedImageSamplerDescriptorCount descriptors for each descriptor in the binding. This expanded number of descriptors will be consumed from the descriptor pool when a descriptor set is allocated, and counts towards the pname:maxDescriptorSetSamplers, pname:maxDescriptorSetSampledImages, pname:maxPerStageDescriptorSamplers, and pname:maxPerStageDescriptorSampledImages limits. .Note [NOTE] ==== All descriptors in a binding use the same maximum pname:combinedImageSamplerDescriptorCount descriptors to allow implementations to use a uniform stride for dynamic indexing of the descriptors in the binding. For example, consider a descriptor set layout binding with two descriptors and immutable samplers for multi-planar formats that have sname:VkSamplerYcbcrConversionImageFormatProperties::pname:combinedImageSamplerDescriptorCount values of `2` and `3` respectively. There are two descriptors in the binding and the maximum pname:combinedImageSamplerDescriptorCount is `3`, so descriptor sets with this layout consume `6` descriptors from the descriptor pool. To create a descriptor pool that allows allocating four descriptor sets with this layout, pname:descriptorCount must be at least `24`. ==== ifdef::VK_KHR_maintenance6[] Instead of querying all the potential formats that the application might use in the descriptor layout, the application can: use the slink:VkPhysicalDeviceMaintenance6PropertiesKHR::pname:maxCombinedImageSamplerDescriptorCount property to determine the maximum descriptor size that that will accommodate any and all <> supported by the implementation. endif::VK_KHR_maintenance6[] endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] [open,refpage='VkAndroidHardwareBufferUsageANDROID',desc='Struct containing Android hardware buffer usage flags',type='structs'] -- To obtain optimal Android hardware buffer usage flags for specific image creation parameters, add a sname:VkAndroidHardwareBufferUsageANDROID structure to the pname:pNext chain of a slink:VkImageFormatProperties2 structure passed to flink:vkGetPhysicalDeviceImageFormatProperties2. This structure is defined as: include::{generated}/api/structs/VkAndroidHardwareBufferUsageANDROID.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:androidHardwareBufferUsage returns the Android hardware buffer usage flags. The pname:androidHardwareBufferUsage field must: include Android hardware buffer usage flags listed in the <> table when the corresponding Vulkan image usage or image creation flags are included in the pname:usage or pname:flags fields of slink:VkPhysicalDeviceImageFormatInfo2. It must: include at least one GPU usage flag (code:AHARDWAREBUFFER_USAGE_GPU_*), even if none of the corresponding Vulkan usages or flags are requested. .Note [NOTE] ==== Requiring at least one GPU usage flag ensures that Android hardware buffer memory will be allocated in a memory pool accessible to the Vulkan implementation, and that specializing the memory layout based on usage flags does not prevent it from being compatible with Vulkan. Implementations may: avoid unnecessary restrictions caused by this requirement by using vendor usage flags to indicate that only the Vulkan uses indicated in slink:VkImageFormatProperties2 are required. ==== include::{generated}/validity/structs/VkAndroidHardwareBufferUsageANDROID.adoc[] -- endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_EXT_host_image_copy[] [open,refpage='VkHostImageCopyDevicePerformanceQueryEXT',desc='Struct containing information about optimality of device access',type='structs'] -- To query if using ename:VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT has a negative impact on device performance when accessing an image, add ename:VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT to slink:VkPhysicalDeviceImageFormatInfo2::pname:usage, and add a sname:VkHostImageCopyDevicePerformanceQueryEXT structure to the pname:pNext chain of a slink:VkImageFormatProperties2 structure passed to flink:vkGetPhysicalDeviceImageFormatProperties2. This structure is defined as: include::{generated}/api/structs/VkHostImageCopyDevicePerformanceQueryEXT.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:optimalDeviceAccess returns ename:VK_TRUE if use of host image copy has no adverse effect on device access performance, compared to an image that is created with exact same creation parameters, and bound to the same slink:VkDeviceMemory, except that ename:VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT is replaced with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT and ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT. * pname:identicalMemoryLayout returns ename:VK_TRUE if use of host image copy has no impact on memory layout compared to an image that is created with exact same creation parameters, and bound to the same slink:VkDeviceMemory, except that ename:VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT is replaced with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT and ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT. The implementation may: return ename:VK_FALSE in pname:optimalDeviceAccess if pname:identicalMemoryLayout is ename:VK_FALSE. If pname:identicalMemoryLayout is ename:VK_TRUE, pname:optimalDeviceAccess must: be ename:VK_TRUE. The implementation may: return ename:VK_TRUE in pname:optimalDeviceAccess while pname:identicalMemoryLayout is ename:VK_FALSE. In this situation, any device performance impact should: not be measurable. If slink:VkPhysicalDeviceImageFormatInfo2::pname:format is a block-compressed format and flink:vkGetPhysicalDeviceImageFormatProperties2 returns ename:VK_SUCCESS, the implementation must: return ename:VK_TRUE in pname:optimalDeviceAccess. .Note [NOTE] ==== Applications can make use of pname:optimalDeviceAccess to determine their resource copying strategy. If a resource is expected to be accessed more on device than on the host, and the implementation considers the resource sub-optimally accessed, it is likely better to use device copies instead. ==== .Note [NOTE] ==== Layout not being identical yet still considered optimal for device access could happen if the implementation has different memory layout patterns, some of which are easier to access on the host. ==== .Note [NOTE] ==== The most practical reason for pname:optimalDeviceAccess to be ename:VK_FALSE is that host image access may disable framebuffer compression where it would otherwise have been enabled. This represents far more efficient host image access since no compression algorithm is required to read or write to the image, but it would impact device access performance. Some implementations may only set pname:optimalDeviceAccess to ename:VK_FALSE if certain conditions are met, such as specific image usage flags or creation flags. ==== include::{generated}/validity/structs/VkHostImageCopyDevicePerformanceQueryEXT.adoc[] -- endif::VK_EXT_host_image_copy[] ifdef::VK_EXT_filter_cubic[] To determine if cubic filtering can be used with a given image format and a given image view type add a slink:VkPhysicalDeviceImageViewImageFormatInfoEXT structure to the pname:pNext chain of the slink:VkPhysicalDeviceImageFormatInfo2 structure, and a slink:VkFilterCubicImageViewImageFormatPropertiesEXT structure to the pname:pNext chain of the slink:VkImageFormatProperties2 structure. [open,refpage='VkPhysicalDeviceImageViewImageFormatInfoEXT',desc='Structure for providing image view type',type='structs'] -- The sname:VkPhysicalDeviceImageViewImageFormatInfoEXT structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceImageViewImageFormatInfoEXT.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:imageViewType is a elink:VkImageViewType value specifying the type of the image view. include::{generated}/validity/structs/VkPhysicalDeviceImageViewImageFormatInfoEXT.adoc[] -- [open,refpage='VkFilterCubicImageViewImageFormatPropertiesEXT',desc='Structure for querying cubic filtering capabilities of an image view type',type='structs'] -- The sname:VkFilterCubicImageViewImageFormatPropertiesEXT structure is defined as: include::{generated}/api/structs/VkFilterCubicImageViewImageFormatPropertiesEXT.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:filterCubic tells if image format, image type and image view type can: be used with cubic filtering. This field is set by the implementation. User-specified value is ignored. * pname:filterCubicMinmax tells if image format, image type and image view type can: be used with cubic filtering and minmax filtering. This field is set by the implementation. User-specified value is ignored. include::{generated}/validity/structs/VkFilterCubicImageViewImageFormatPropertiesEXT.adoc[] .Valid Usage **** * [[VUID-VkFilterCubicImageViewImageFormatPropertiesEXT-pNext-02627]] If the pname:pNext chain of the slink:VkImageFormatProperties2 structure includes a slink:VkFilterCubicImageViewImageFormatPropertiesEXT structure, the pname:pNext chain of the slink:VkPhysicalDeviceImageFormatInfo2 structure must: include a slink:VkPhysicalDeviceImageViewImageFormatInfoEXT structure with an pname:imageViewType that is compatible with pname:imageType **** -- endif::VK_EXT_filter_cubic[] endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] [[features-supported-sample-counts]] === Supported Sample Counts fname:vkGetPhysicalDeviceImageFormatProperties returns a bitmask of elink:VkSampleCountFlagBits in pname:sampleCounts specifying the supported sample counts for the image parameters. pname:sampleCounts will be set to ename:VK_SAMPLE_COUNT_1_BIT if at least one of the following conditions is true: * pname:tiling is ename:VK_IMAGE_TILING_LINEAR * pname:type is not ename:VK_IMAGE_TYPE_2D * pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT * Neither the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag nor the ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT flag in sname:VkFormatProperties::pname:optimalTilingFeatures returned by flink:vkGetPhysicalDeviceFormatProperties is set ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] * slink:VkPhysicalDeviceExternalImageFormatInfo::pname:handleType is an external handle type for which multisampled image support is not required. endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] * pname:format is one of the <> endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] * pname:usage contains ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] ifdef::VK_EXT_fragment_density_map[] * pname:usage contains ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT endif::VK_EXT_fragment_density_map[] Otherwise, the bits set in pname:sampleCounts will be the sample counts supported for the specified values of pname:usage and pname:format. For each bit set in pname:usage, the supported sample counts relate to the limits in sname:VkPhysicalDeviceLimits as follows: * If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT and pname:format is a floating- or fixed-point color format, a superset of sname:VkPhysicalDeviceLimits::pname:framebufferColorSampleCounts ifdef::VK_VERSION_1_2[] * If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT and pname:format is an integer format, a superset of sname:VkPhysicalDeviceVulkan12Properties::pname:framebufferIntegerColorSampleCounts endif::VK_VERSION_1_2[] * If pname:usage includes ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and pname:format includes a depth component, a superset of sname:VkPhysicalDeviceLimits::pname:framebufferDepthSampleCounts * If pname:usage includes ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and pname:format includes a stencil component, a superset of sname:VkPhysicalDeviceLimits::pname:framebufferStencilSampleCounts * If pname:usage includes ename:VK_IMAGE_USAGE_SAMPLED_BIT, and pname:format includes a color component, a superset of sname:VkPhysicalDeviceLimits::pname:sampledImageColorSampleCounts * If pname:usage includes ename:VK_IMAGE_USAGE_SAMPLED_BIT, and pname:format includes a depth component, a superset of sname:VkPhysicalDeviceLimits::pname:sampledImageDepthSampleCounts * If pname:usage includes ename:VK_IMAGE_USAGE_SAMPLED_BIT, and pname:format is an integer format, a superset of sname:VkPhysicalDeviceLimits::pname:sampledImageIntegerSampleCounts * If pname:usage includes ename:VK_IMAGE_USAGE_STORAGE_BIT, a superset of sname:VkPhysicalDeviceLimits::pname:storageImageSampleCounts If multiple bits are set in pname:usage, pname:sampleCounts will be the intersection of the per-usage values described above. If none of the bits described above are set in pname:usage, then there is no corresponding limit in sname:VkPhysicalDeviceLimits. In this case, pname:sampleCounts must: include at least ename:VK_SAMPLE_COUNT_1_BIT. [[features-extentperimagetype]] === Allowed Extent Values Based on Image Type Implementations may: support extent values larger than the <> for certain types of images. slink:VkImageFormatProperties::pname:maxExtent for each type is subject to the constraints below. [NOTE] .Note ==== Implementations must: support images with dimensions up to the <> for all types of images. It follows that the query for additional capabilities must: return extent values that are at least as large as the required values. ==== For ename:VK_IMAGE_TYPE_1D: * [eq]#pname:maxExtent.width {geq} slink:VkPhysicalDeviceLimits::pname:maxImageDimension1D# * [eq]#pname:maxExtent.height = 1# * [eq]#pname:maxExtent.depth = 1# For ename:VK_IMAGE_TYPE_2D when pname:flags does not contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT: * [eq]#pname:maxExtent.width {geq} slink:VkPhysicalDeviceLimits::pname:maxImageDimension2D# * [eq]#pname:maxExtent.height {geq} slink:VkPhysicalDeviceLimits::pname:maxImageDimension2D# * [eq]#pname:maxExtent.depth = 1# For ename:VK_IMAGE_TYPE_2D when pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT: * [eq]#pname:maxExtent.width {geq} slink:VkPhysicalDeviceLimits::pname:maxImageDimensionCube# * [eq]#pname:maxExtent.height {geq} slink:VkPhysicalDeviceLimits::pname:maxImageDimensionCube# * [eq]#pname:maxExtent.depth = 1# For ename:VK_IMAGE_TYPE_3D: * [eq]#pname:maxExtent.width {geq} slink:VkPhysicalDeviceLimits::pname:maxImageDimension3D# * [eq]#pname:maxExtent.height {geq} slink:VkPhysicalDeviceLimits::pname:maxImageDimension3D# * [eq]#pname:maxExtent.depth {geq} slink:VkPhysicalDeviceLimits::pname:maxImageDimension3D# ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] [[capabilities-buffer]] == Additional Buffer Capabilities [open,refpage='vkGetPhysicalDeviceExternalBufferProperties',desc='Query external handle types supported by buffers',type='protos'] -- To query the external handle types supported by buffers, call: ifdef::VK_VERSION_1_1[] include::{generated}/api/protos/vkGetPhysicalDeviceExternalBufferProperties.adoc[] endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1+VK_KHR_external_memory_capabilities[or the equivalent command] ifdef::VK_KHR_external_memory_capabilities[] include::{generated}/api/protos/vkGetPhysicalDeviceExternalBufferPropertiesKHR.adoc[] endif::VK_KHR_external_memory_capabilities[] * pname:physicalDevice is the physical device from which to query the buffer capabilities. * pname:pExternalBufferInfo is a pointer to a slink:VkPhysicalDeviceExternalBufferInfo structure describing the parameters that would be consumed by flink:vkCreateBuffer. * pname:pExternalBufferProperties is a pointer to a slink:VkExternalBufferProperties structure in which capabilities are returned. include::{generated}/validity/protos/vkGetPhysicalDeviceExternalBufferProperties.adoc[] -- [open,refpage='VkPhysicalDeviceExternalBufferInfo',desc='Structure specifying buffer creation parameters',type='structs'] -- :refpage: VkPhysicalDeviceExternalBufferInfo The sname:VkPhysicalDeviceExternalBufferInfo structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceExternalBufferInfo.adoc[] ifdef::VK_KHR_external_memory_capabilities[] or the equivalent include::{generated}/api/structs/VkPhysicalDeviceExternalBufferInfoKHR.adoc[] endif::VK_KHR_external_memory_capabilities[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is a bitmask of elink:VkBufferCreateFlagBits describing additional parameters of the buffer, corresponding to slink:VkBufferCreateInfo::pname:flags. * pname:usage is a bitmask of elink:VkBufferUsageFlagBits describing the intended usage of the buffer, corresponding to slink:VkBufferCreateInfo::pname:usage. * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value specifying the memory handle type that will be used with the memory associated with the buffer. Only usage flags representable in elink:VkBufferUsageFlagBits are returned in this structure's pname:usage. ifdef::VK_KHR_maintenance5[] If a slink:VkBufferUsageFlags2CreateInfoKHR structure is present in the pname:pNext chain, all usage flags of the buffer are returned in slink:VkBufferUsageFlags2CreateInfoKHR::pname:usage. endif::VK_KHR_maintenance5[] .Valid Usage **** include::{chapters}/commonvalidity/buffer_usage_flags_common.adoc[] **** include::{generated}/validity/structs/VkPhysicalDeviceExternalBufferInfo.adoc[] -- [open,refpage='VkExternalBufferProperties',desc='Structure specifying supported external handle capabilities',type='structs'] -- The sname:VkExternalBufferProperties structure is defined as: include::{generated}/api/structs/VkExternalBufferProperties.adoc[] ifdef::VK_KHR_external_memory_capabilities[] or the equivalent include::{generated}/api/structs/VkExternalBufferPropertiesKHR.adoc[] endif::VK_KHR_external_memory_capabilities[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:externalMemoryProperties is a slink:VkExternalMemoryProperties structure specifying various capabilities of the external handle type when used with the specified buffer creation parameters. include::{generated}/validity/structs/VkExternalBufferProperties.adoc[] -- endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] [[capabilities-semaphore]] == Optional Semaphore Capabilities [open,refpage='vkGetPhysicalDeviceExternalSemaphoreProperties',desc='Function for querying external semaphore handle capabilities.',type='protos'] -- Semaphores may: support import and export of their <> to external handles. To query the external handle types supported by semaphores, call: ifdef::VK_VERSION_1_1[] include::{generated}/api/protos/vkGetPhysicalDeviceExternalSemaphoreProperties.adoc[] endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1+VK_KHR_external_semaphore_capabilities[or the equivalent command] ifdef::VK_KHR_external_semaphore_capabilities[] include::{generated}/api/protos/vkGetPhysicalDeviceExternalSemaphorePropertiesKHR.adoc[] endif::VK_KHR_external_semaphore_capabilities[] * pname:physicalDevice is the physical device from which to query the semaphore capabilities. * pname:pExternalSemaphoreInfo is a pointer to a slink:VkPhysicalDeviceExternalSemaphoreInfo structure describing the parameters that would be consumed by flink:vkCreateSemaphore. * pname:pExternalSemaphoreProperties is a pointer to a slink:VkExternalSemaphoreProperties structure in which capabilities are returned. include::{generated}/validity/protos/vkGetPhysicalDeviceExternalSemaphoreProperties.adoc[] -- [open,refpage='VkPhysicalDeviceExternalSemaphoreInfo',desc='Structure specifying semaphore creation parameters.',type='structs'] -- The sname:VkPhysicalDeviceExternalSemaphoreInfo structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceExternalSemaphoreInfo.adoc[] ifdef::VK_KHR_external_semaphore_capabilities[] or the equivalent include::{generated}/api/structs/VkPhysicalDeviceExternalSemaphoreInfoKHR.adoc[] endif::VK_KHR_external_semaphore_capabilities[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:handleType is a elink:VkExternalSemaphoreHandleTypeFlagBits value specifying the external semaphore handle type for which capabilities will be returned. include::{generated}/validity/structs/VkPhysicalDeviceExternalSemaphoreInfo.adoc[] -- [open,refpage='VkExternalSemaphoreHandleTypeFlagBits',desc='Bitmask of valid external semaphore handle types',type='enums'] -- Bits which may: be set in slink:VkPhysicalDeviceExternalSemaphoreInfo::pname:handleType, specifying an external semaphore handle type, are: include::{generated}/api/enums/VkExternalSemaphoreHandleTypeFlagBits.adoc[] ifdef::VK_KHR_external_semaphore_capabilities[] or the equivalent include::{generated}/api/enums/VkExternalSemaphoreHandleTypeFlagBitsKHR.adoc[] endif::VK_KHR_external_semaphore_capabilities[] * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT specifies a POSIX file descriptor handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must: be compatible with the POSIX system calls code:dup, code:dup2, code:close, and the non-standard system call code:dup3. Additionally, it must: be transportable over a socket using an code:SCM_RIGHTS control message. It owns a reference to the underlying synchronization primitive represented by its Vulkan semaphore object. * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT specifies an NT handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must: be compatible with the functions code:DuplicateHandle, code:CloseHandle, code:CompareObjectHandles, code:GetHandleInformation, and code:SetHandleInformation. It owns a reference to the underlying synchronization primitive represented by its Vulkan semaphore object. * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT specifies a global share handle that has only limited valid usage outside of Vulkan and other compatible APIs. It is not compatible with any native APIs. It does not own a reference to the underlying synchronization primitive represented by its Vulkan semaphore object, and will therefore become invalid when all Vulkan semaphore objects associated with it are destroyed. * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT specifies an NT handle returned by code:ID3D12Device::code:CreateSharedHandle referring to a Direct3D 12 fence, or code:ID3D11Device5::code:CreateFence referring to a Direct3D 11 fence. It owns a reference to the underlying synchronization primitive associated with the Direct3D fence. * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE_BIT is an alias of ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT with the same meaning. It is provided for convenience and code clarity when interacting with D3D11 fences. * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT specifies a POSIX file descriptor handle to a Linux Sync File or Android Fence object. It can be used with any native API accepting a valid sync file or fence as input. It owns a reference to the underlying synchronization primitive associated with the file descriptor. Implementations which support importing this handle type must: accept any type of sync or fence FD supported by the native system they are running on. ifdef::VK_FUCHSIA_external_semaphore[] * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_ZIRCON_EVENT_BIT_FUCHSIA specifies a handle to a Zircon event object. It can be used with any native API that accepts a Zircon event handle. Zircon event handles are created with code:ZX_RIGHTS_BASIC and code:ZX_RIGHTS_SIGNAL rights. Vulkan on Fuchsia uses only the ZX_EVENT_SIGNALED bit when signaling or waiting. endif::VK_FUCHSIA_external_semaphore[] ifdef::VK_NV_external_sci_sync[] * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SCI_SYNC_OBJ_BIT_NV specifies a synchronization object (code:NvSciSyncObj) shareable across various hardware engines including the CPU and software (intra-process and inter-process) operating domains and perform signal and wait operations. endif::VK_NV_external_sci_sync[] [NOTE] .Note ==== Handles of type ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT generated by the implementation may represent either Linux Sync Files or Android Fences at the implementation's discretion. Applications should: only use operations defined for both types of file descriptors, unless they know via means external to Vulkan the type of the file descriptor, or are prepared to deal with the system-defined operation failures resulting from using the wrong type. ==== <<< Some external semaphore handle types can only be shared within the same underlying physical device and/or the same driver version, as defined in the following table: [[external-semaphore-handle-types-compatibility]] .External semaphore handle types compatibility |==== | Handle type | sname:VkPhysicalDeviceIDProperties{wbro}::pname:driverUUID | sname:VkPhysicalDeviceIDProperties{wbro}::pname:deviceUUID | ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT | Must match | Must match | ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT | Must match | Must match | ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT | Must match | Must match | ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT | Must match | Must match | ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT | No restriction | No restriction | ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_ZIRCON_EVENT_BIT_FUCHSIA | No restriction | No restriction ifdef::VK_NV_external_sci_sync[] | ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SCI_SYNC_OBJ_BIT_NV | No restriction | No restriction endif::VK_NV_external_sci_sync[] |==== -- [open,refpage='VkExternalSemaphoreHandleTypeFlags',desc='Bitmask of VkExternalSemaphoreHandleTypeFlagBits',type='flags'] -- include::{generated}/api/flags/VkExternalSemaphoreHandleTypeFlags.adoc[] ifdef::VK_KHR_external_semaphore_capabilities[] or the equivalent include::{generated}/api/flags/VkExternalSemaphoreHandleTypeFlagsKHR.adoc[] endif::VK_KHR_external_semaphore_capabilities[] tname:VkExternalSemaphoreHandleTypeFlags is a bitmask type for setting a mask of zero or more elink:VkExternalSemaphoreHandleTypeFlagBits. -- [open,refpage='VkExternalSemaphoreProperties',desc='Structure describing supported external semaphore handle features',type='structs'] -- The sname:VkExternalSemaphoreProperties structure is defined as: include::{generated}/api/structs/VkExternalSemaphoreProperties.adoc[] ifdef::VK_KHR_external_semaphore_capabilities[] or the equivalent include::{generated}/api/structs/VkExternalSemaphorePropertiesKHR.adoc[] endif::VK_KHR_external_semaphore_capabilities[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:exportFromImportedHandleTypes is a bitmask of elink:VkExternalSemaphoreHandleTypeFlagBits specifying which types of imported handle pname:handleType can: be exported from. * pname:compatibleHandleTypes is a bitmask of elink:VkExternalSemaphoreHandleTypeFlagBits specifying handle types which can: be specified at the same time as pname:handleType when creating a semaphore. * pname:externalSemaphoreFeatures is a bitmask of elink:VkExternalSemaphoreFeatureFlagBits describing the features of pname:handleType. If pname:handleType is not supported by the implementation, then slink:VkExternalSemaphoreProperties::pname:externalSemaphoreFeatures will be set to zero. include::{generated}/validity/structs/VkExternalSemaphoreProperties.adoc[] -- [open,refpage='VkExternalSemaphoreFeatureFlagBits',desc='Bitfield describing features of an external semaphore handle type',type='enums'] -- Bits which may: be set in slink:VkExternalSemaphoreProperties::pname:externalSemaphoreFeatures, specifying the features of an external semaphore handle type, are: include::{generated}/api/enums/VkExternalSemaphoreFeatureFlagBits.adoc[] ifdef::VK_KHR_external_semaphore_capabilities[] or the equivalent include::{generated}/api/enums/VkExternalSemaphoreFeatureFlagBitsKHR.adoc[] endif::VK_KHR_external_semaphore_capabilities[] * ename:VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BIT specifies that handles of this type can: be exported from Vulkan semaphore objects. * ename:VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT specifies that handles of this type can: be imported as Vulkan semaphore objects. -- [open,refpage='VkExternalSemaphoreFeatureFlags',desc='Bitmask of VkExternalSemaphoreFeatureFlagBitsKHR',type='flags'] -- include::{generated}/api/flags/VkExternalSemaphoreFeatureFlags.adoc[] ifdef::VK_KHR_external_semaphore_capabilities[] or the equivalent include::{generated}/api/flags/VkExternalSemaphoreFeatureFlagsKHR.adoc[] endif::VK_KHR_external_semaphore_capabilities[] tname:VkExternalSemaphoreFeatureFlags is a bitmask type for setting a mask of zero or more elink:VkExternalSemaphoreFeatureFlagBits. -- endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] [[capabilities-fence]] == Optional Fence Capabilities [open,refpage='vkGetPhysicalDeviceExternalFenceProperties',desc='Function for querying external fence handle capabilities.',type='protos'] -- Fences may: support import and export of their <> to external handles. To query the external handle types supported by fences, call: ifdef::VK_VERSION_1_1[] include::{generated}/api/protos/vkGetPhysicalDeviceExternalFenceProperties.adoc[] endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1+VK_KHR_external_fence_capabilities[or the equivalent command] ifdef::VK_KHR_external_fence_capabilities[] include::{generated}/api/protos/vkGetPhysicalDeviceExternalFencePropertiesKHR.adoc[] endif::VK_KHR_external_fence_capabilities[] * pname:physicalDevice is the physical device from which to query the fence capabilities. * pname:pExternalFenceInfo is a pointer to a slink:VkPhysicalDeviceExternalFenceInfo structure describing the parameters that would be consumed by flink:vkCreateFence. * pname:pExternalFenceProperties is a pointer to a slink:VkExternalFenceProperties structure in which capabilities are returned. include::{generated}/validity/protos/vkGetPhysicalDeviceExternalFenceProperties.adoc[] -- [open,refpage='VkPhysicalDeviceExternalFenceInfo',desc='Structure specifying fence creation parameters.',type='structs'] -- The sname:VkPhysicalDeviceExternalFenceInfo structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceExternalFenceInfo.adoc[] ifdef::VK_KHR_external_fence_capabilities[] or the equivalent include::{generated}/api/structs/VkPhysicalDeviceExternalFenceInfoKHR.adoc[] endif::VK_KHR_external_fence_capabilities[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:handleType is a elink:VkExternalFenceHandleTypeFlagBits value specifying an external fence handle type for which capabilities will be returned. [NOTE] .Note ==== Handles of type ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT generated by the implementation may represent either Linux Sync Files or Android Fences at the implementation's discretion. Applications should: only use operations defined for both types of file descriptors, unless they know via means external to Vulkan the type of the file descriptor, or are prepared to deal with the system-defined operation failures resulting from using the wrong type. ==== include::{generated}/validity/structs/VkPhysicalDeviceExternalFenceInfo.adoc[] -- [open,refpage='VkExternalFenceHandleTypeFlagBits',desc='Bitmask of valid external fence handle types',type='enums'] -- Bits which may: be set in * slink:VkPhysicalDeviceExternalFenceInfo::pname:handleType * slink:VkExternalFenceProperties::pname:exportFromImportedHandleTypes * slink:VkExternalFenceProperties::pname:compatibleHandleTypes indicate external fence handle types, and are: include::{generated}/api/enums/VkExternalFenceHandleTypeFlagBits.adoc[] ifdef::VK_KHR_external_fence_capabilities[] or the equivalent include::{generated}/api/enums/VkExternalFenceHandleTypeFlagBitsKHR.adoc[] endif::VK_KHR_external_fence_capabilities[] * ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT specifies a POSIX file descriptor handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must: be compatible with the POSIX system calls code:dup, code:dup2, code:close, and the non-standard system call code:dup3. Additionally, it must: be transportable over a socket using an code:SCM_RIGHTS control message. It owns a reference to the underlying synchronization primitive represented by its Vulkan fence object. * ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT specifies an NT handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must: be compatible with the functions code:DuplicateHandle, code:CloseHandle, code:CompareObjectHandles, code:GetHandleInformation, and code:SetHandleInformation. It owns a reference to the underlying synchronization primitive represented by its Vulkan fence object. * ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT specifies a global share handle that has only limited valid usage outside of Vulkan and other compatible APIs. It is not compatible with any native APIs. It does not own a reference to the underlying synchronization primitive represented by its Vulkan fence object, and will therefore become invalid when all Vulkan fence objects associated with it are destroyed. * ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT specifies a POSIX file descriptor handle to a Linux Sync File or Android Fence. It can be used with any native API accepting a valid sync file or fence as input. It owns a reference to the underlying synchronization primitive associated with the file descriptor. Implementations which support importing this handle type must: accept any type of sync or fence FD supported by the native system they are running on. ifdef::VK_NV_external_sci_sync,VK_NV_external_sci_sync2[] * ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SCI_SYNC_OBJ_BIT_NV specifies a synchronization object (code:NvSciSyncObj) shareable across various hardware engines including the CPU and software (intra-process and inter-process) operating domains and perform signal and wait operations. * ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SCI_SYNC_FENCE_BIT_NV specifies a struct of code:NvSciSyncFence that is a snapshot of a synchronization object’s underlying primitive and represents its possible state. endif::VK_NV_external_sci_sync,VK_NV_external_sci_sync2[] <<< Some external fence handle types can only be shared within the same underlying physical device and/or the same driver version, as defined in the following table: [[external-fence-handle-types-compatibility]] .External fence handle types compatibility |==== | Handle type | sname:VkPhysicalDeviceIDProperties{wbro}::pname:driverUUID | sname:VkPhysicalDeviceIDProperties{wbro}::pname:deviceUUID | ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT | Must match | Must match | ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT | Must match | Must match | ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT | Must match | Must match | ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT | No restriction | No restriction ifdef::VK_NV_external_sci_sync,VK_NV_external_sci_sync2[] | ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SCI_SYNC_OBJ_BIT_NV | Must match | Must match | ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SCI_SYNC_FENCE_BIT_NV | Must match | Must match endif::VK_NV_external_sci_sync,VK_NV_external_sci_sync2[] |==== -- [open,refpage='VkExternalFenceHandleTypeFlags',desc='Bitmask of VkExternalFenceHandleTypeFlagBits',type='flags'] -- include::{generated}/api/flags/VkExternalFenceHandleTypeFlags.adoc[] ifdef::VK_KHR_external_fence_capabilities[] or the equivalent include::{generated}/api/flags/VkExternalFenceHandleTypeFlagsKHR.adoc[] endif::VK_KHR_external_fence_capabilities[] tname:VkExternalFenceHandleTypeFlags is a bitmask type for setting a mask of zero or more elink:VkExternalFenceHandleTypeFlagBits. -- [open,refpage='VkExternalFenceProperties',desc='Structure describing supported external fence handle features',type='structs'] -- The sname:VkExternalFenceProperties structure is defined as: include::{generated}/api/structs/VkExternalFenceProperties.adoc[] ifdef::VK_KHR_external_fence_capabilities[] or the equivalent include::{generated}/api/structs/VkExternalFencePropertiesKHR.adoc[] endif::VK_KHR_external_fence_capabilities[] * pname:exportFromImportedHandleTypes is a bitmask of elink:VkExternalFenceHandleTypeFlagBits indicating which types of imported handle pname:handleType can: be exported from. * pname:compatibleHandleTypes is a bitmask of elink:VkExternalFenceHandleTypeFlagBits specifying handle types which can: be specified at the same time as pname:handleType when creating a fence. * pname:externalFenceFeatures is a bitmask of elink:VkExternalFenceFeatureFlagBits indicating the features of pname:handleType. If pname:handleType is not supported by the implementation, then slink:VkExternalFenceProperties::pname:externalFenceFeatures will be set to zero. include::{generated}/validity/structs/VkExternalFenceProperties.adoc[] -- [open,refpage='VkExternalFenceFeatureFlagBits',desc='Bitfield describing features of an external fence handle type',type='enums'] -- Bits which may: be set in slink:VkExternalFenceProperties::pname:externalFenceFeatures, indicating features of a fence external handle type, are: include::{generated}/api/enums/VkExternalFenceFeatureFlagBits.adoc[] ifdef::VK_KHR_external_fence_capabilities[] or the equivalent include::{generated}/api/enums/VkExternalFenceFeatureFlagBitsKHR.adoc[] endif::VK_KHR_external_fence_capabilities[] * ename:VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BIT specifies handles of this type can: be exported from Vulkan fence objects. * ename:VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BIT specifies handles of this type can: be imported to Vulkan fence objects. -- [open,refpage='VkExternalFenceFeatureFlags',desc='Bitmask of VkExternalFenceFeatureFlagBits',type='flags'] -- include::{generated}/api/flags/VkExternalFenceFeatureFlags.adoc[] ifdef::VK_KHR_external_fence_capabilities[] or the equivalent include::{generated}/api/flags/VkExternalFenceFeatureFlagsKHR.adoc[] endif::VK_KHR_external_fence_capabilities[] tname:VkExternalFenceFeatureFlags is a bitmask type for setting a mask of zero or more elink:VkExternalFenceFeatureFlagBits. -- endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] ifdef::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] [[features-timestamp-calibration]] == Timestamp Calibration Capabilities [open,refpage='vkGetPhysicalDeviceCalibrateableTimeDomainsKHR',desc='Query calibrateable time domains',type='protos',alias='vkGetPhysicalDeviceCalibrateableTimeDomainsEXT'] -- :refpage: vkGetPhysicalDeviceCalibrateableTimeDomainsKHR To query the set of time domains for which a physical device supports timestamp calibration, call: ifdef::VK_KHR_calibrated_timestamps[] include::{generated}/api/protos/vkGetPhysicalDeviceCalibrateableTimeDomainsKHR.adoc[] endif::VK_KHR_calibrated_timestamps[] ifdef::VK_KHR_calibrated_timestamps+VK_EXT_calibrated_timestamps[or the equivalent command] ifdef::VK_EXT_calibrated_timestamps[] include::{generated}/api/protos/vkGetPhysicalDeviceCalibrateableTimeDomainsEXT.adoc[] endif::VK_EXT_calibrated_timestamps[] * pname:physicalDevice is the physical device from which to query the set of calibrateable time domains. * pname:pTimeDomainCount is a pointer to an integer related to the number of calibrateable time domains available or queried, as described below. * pname:pTimeDomains is either `NULL` or a pointer to an array of elink:VkTimeDomainKHR values, indicating the supported calibrateable time domains. If pname:pTimeDomains is `NULL`, then the number of calibrateable time domains supported for the given pname:physicalDevice is returned in pname:pTimeDomainCount. Otherwise, pname:pTimeDomainCount must: point to a variable set by the user to the number of elements in the pname:pTimeDomains array, and on return the variable is overwritten with the number of values actually written to pname:pTimeDomains. If the value of pname:pTimeDomainCount is less than the number of calibrateable time domains supported, at most pname:pTimeDomainCount values will be written to pname:pTimeDomains, and ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to indicate that not all the available time domains were returned. include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] include::{generated}/validity/protos/vkGetPhysicalDeviceCalibrateableTimeDomainsKHR.adoc[] -- endif::VK_KHR_calibrated_timestamps,VK_EXT_calibrated_timestamps[] ifdef::VK_KHR_object_refresh[] include::{chapters}/VK_KHR_object_refresh/capabilities.adoc[] endif::VK_KHR_object_refresh[]