50. Additional Capabilities
This chapter describes additional capabilities beyond the minimum capabilities described in the Limits and Formats chapters, including:
50.1. 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.
To query additional capabilities specific to image types, call:
// Provided by VK_VERSION_1_0
VkResult vkGetPhysicalDeviceImageFormatProperties(
VkPhysicalDevice physicalDevice,
VkFormat format,
VkImageType type,
VkImageTiling tiling,
VkImageUsageFlags usage,
VkImageCreateFlags flags,
VkImageFormatProperties* pImageFormatProperties);
-
physicalDeviceis the physical device from which to query the image capabilities. -
formatis a VkFormat value specifying the image format, corresponding to VkImageCreateInfo::format. -
typeis a VkImageType value specifying the image type, corresponding to VkImageCreateInfo::imageType. -
tilingis a VkImageTiling value specifying the image tiling, corresponding to VkImageCreateInfo::tiling. -
usageis a bitmask of VkImageUsageFlagBits specifying the intended usage of the image, corresponding to VkImageCreateInfo::usage. -
flagsis a bitmask of VkImageCreateFlagBits specifying additional parameters of the image, corresponding to VkImageCreateInfo::flags. -
pImageFormatPropertiesis a pointer to a VkImageFormatProperties structure in which capabilities are returned.
The format, type, tiling, usage, and flags
parameters correspond to parameters that would be consumed by
vkCreateImage (as members of VkImageCreateInfo).
If format is not a supported image format, or if the combination of
format, type, tiling, usage, and flags is not
supported for images, then vkGetPhysicalDeviceImageFormatProperties
returns VK_ERROR_FORMAT_NOT_SUPPORTED.
The limitations on an image format that are reported by
vkGetPhysicalDeviceImageFormatProperties have the following property:
if usage1 and usage2 of type VkImageUsageFlags are such that
the bits set in usage1 are a subset of the bits set in usage2, and
flags1 and flags2 of type VkImageCreateFlags are such that
the bits set in flags1 are a subset of the bits set in flags2,
then the limitations for usage1 and flags1 must be no more strict
than the limitations for usage2 and flags2, for all values of
format, type, and tiling.
If VK_EXT_host_image_copy is supported, usage includes
VK_IMAGE_USAGE_SAMPLED_BIT, and flags does not include either of
VK_IMAGE_CREATE_SPARSE_BINDING_BIT,
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or
VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, then the result of calls to
vkGetPhysicalDeviceImageFormatProperties with identical parameters
except for the inclusion of VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT in
usage must be identical.
The VkImageFormatProperties structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageFormatProperties {
VkExtent3D maxExtent;
uint32_t maxMipLevels;
uint32_t maxArrayLayers;
VkSampleCountFlags sampleCounts;
VkDeviceSize maxResourceSize;
} VkImageFormatProperties;
-
maxExtentare the maximum image dimensions. See the Allowed Extent Values section below for how these values are constrained bytype. -
maxMipLevelsis the maximum number of mipmap levels.maxMipLevelsmust be equal to the number of levels in the complete mipmap chain based on themaxExtent.width,maxExtent.height, andmaxExtent.depth, except when one of the following conditions is true, in which case it may instead be1:-
vkGetPhysicalDeviceImageFormatProperties::tilingwasVK_IMAGE_TILING_LINEAR -
VkPhysicalDeviceImageFormatInfo2::
tilingwasVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT -
the VkPhysicalDeviceImageFormatInfo2::
pNextchain included a VkPhysicalDeviceExternalImageFormatInfo structure with a handle type included in thehandleTypesmember for which mipmap image support is not required -
image
formatis one of the formats that require a sampler Y′CBCR conversion -
flagscontainsVK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
-
-
maxArrayLayersis the maximum number of array layers.maxArrayLayersmust be no less than VkPhysicalDeviceLimits::maxImageArrayLayers, except when one of the following conditions is true, in which case it may instead be1:-
tilingisVK_IMAGE_TILING_LINEAR -
tilingisVK_IMAGE_TILING_OPTIMALandtypeisVK_IMAGE_TYPE_3D -
formatis one of the formats that require a sampler Y′CBCR conversion
-
-
If
tilingisVK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, thenmaxArrayLayersmust not be 0. -
sampleCountsis a bitmask of VkSampleCountFlagBits specifying all the supported sample counts for this image as described below. -
maxResourceSizeis 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.maxResourceSizemust be at least 231.
|
Note
There is no mechanism to query the size of an image before creating it, to
compare that size against |
If the combination of parameters to
vkGetPhysicalDeviceImageFormatProperties is not supported by the
implementation for use in vkCreateImage, then all members of
VkImageFormatProperties will be filled with zero.
|
Note
Filling |
To determine the image capabilities compatible with an external memory handle type, call:
// Provided by VK_NV_external_memory_capabilities
VkResult vkGetPhysicalDeviceExternalImageFormatPropertiesNV(
VkPhysicalDevice physicalDevice,
VkFormat format,
VkImageType type,
VkImageTiling tiling,
VkImageUsageFlags usage,
VkImageCreateFlags flags,
VkExternalMemoryHandleTypeFlagsNV externalHandleType,
VkExternalImageFormatPropertiesNV* pExternalImageFormatProperties);
-
physicalDeviceis the physical device from which to query the image capabilities -
formatis the image format, corresponding to VkImageCreateInfo::format. -
typeis the image type, corresponding to VkImageCreateInfo::imageType. -
tilingis the image tiling, corresponding to VkImageCreateInfo::tiling. -
usageis the intended usage of the image, corresponding to VkImageCreateInfo::usage. -
flagsis a bitmask describing additional parameters of the image, corresponding to VkImageCreateInfo::flags. -
externalHandleTypeis either one of the bits from VkExternalMemoryHandleTypeFlagBitsNV, or 0. -
pExternalImageFormatPropertiesis a pointer to a VkExternalImageFormatPropertiesNV structure in which capabilities are returned.
If externalHandleType is 0,
pExternalImageFormatProperties->imageFormatProperties will return the
same values as a call to vkGetPhysicalDeviceImageFormatProperties, and
the other members of pExternalImageFormatProperties will all be 0.
Otherwise, they are filled in as described for
VkExternalImageFormatPropertiesNV.
The VkExternalImageFormatPropertiesNV structure is defined as:
// Provided by VK_NV_external_memory_capabilities
typedef struct VkExternalImageFormatPropertiesNV {
VkImageFormatProperties imageFormatProperties;
VkExternalMemoryFeatureFlagsNV externalMemoryFeatures;
VkExternalMemoryHandleTypeFlagsNV exportFromImportedHandleTypes;
VkExternalMemoryHandleTypeFlagsNV compatibleHandleTypes;
} VkExternalImageFormatPropertiesNV;
-
imageFormatPropertieswill be filled in as when calling vkGetPhysicalDeviceImageFormatProperties, but the values returned may vary depending on the external handle type requested. -
externalMemoryFeaturesis a bitmask of VkExternalMemoryFeatureFlagBitsNV, indicating properties of the external memory handle type (vkGetPhysicalDeviceExternalImageFormatPropertiesNV::externalHandleType) being queried, or 0 if the external memory handle type is 0. -
exportFromImportedHandleTypesis a bitmask of VkExternalMemoryHandleTypeFlagBitsNV containing a bit set for every external handle type that may be used to create memory from which the handles of the type specified in vkGetPhysicalDeviceExternalImageFormatPropertiesNV::externalHandleTypecan be exported, or 0 if the external memory handle type is 0. -
compatibleHandleTypesis a bitmask of VkExternalMemoryHandleTypeFlagBitsNV containing a bit set for every external handle type that may be specified simultaneously with the handle type specified by vkGetPhysicalDeviceExternalImageFormatPropertiesNV::externalHandleTypewhen calling vkAllocateMemory, or 0 if the external memory handle type is 0.compatibleHandleTypeswill always contain vkGetPhysicalDeviceExternalImageFormatPropertiesNV::externalHandleType
Bits which can be set in
VkExternalImageFormatPropertiesNV::externalMemoryFeatures,
indicating properties of the external memory handle type, are:
// Provided by VK_NV_external_memory_capabilities
typedef enum VkExternalMemoryFeatureFlagBitsNV {
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NV = 0x00000001,
VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT_NV = 0x00000002,
VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_NV = 0x00000004,
} VkExternalMemoryFeatureFlagBitsNV;
-
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_NVspecifies that external memory of the specified type must be created as a dedicated allocation when used in the manner specified. -
VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT_NVspecifies that the implementation supports exporting handles of the specified type. -
VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_NVspecifies that the implementation supports importing handles of the specified type.
// Provided by VK_NV_external_memory_capabilities
typedef VkFlags VkExternalMemoryFeatureFlagsNV;
VkExternalMemoryFeatureFlagsNV is a bitmask type for setting a mask of
zero or more VkExternalMemoryFeatureFlagBitsNV.
To query additional capabilities specific to image types, call:
// Provided by VK_VERSION_1_1
VkResult vkGetPhysicalDeviceImageFormatProperties2(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceImageFormatInfo2* pImageFormatInfo,
VkImageFormatProperties2* pImageFormatProperties);
or the equivalent command
// Provided by VK_KHR_get_physical_device_properties2
VkResult vkGetPhysicalDeviceImageFormatProperties2KHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceImageFormatInfo2* pImageFormatInfo,
VkImageFormatProperties2* pImageFormatProperties);
-
physicalDeviceis the physical device from which to query the image capabilities. -
pImageFormatInfois a pointer to a VkPhysicalDeviceImageFormatInfo2 structure describing the parameters that would be consumed by vkCreateImage. -
pImageFormatPropertiesis a pointer to a VkImageFormatProperties2 structure in which capabilities are returned.
vkGetPhysicalDeviceImageFormatProperties2 behaves similarly to
vkGetPhysicalDeviceImageFormatProperties, with the ability to return
extended information in a pNext chain of output structures.
If the pNext chain of pImageFormatInfo includes a
VkVideoProfileListInfoKHR structure with a profileCount member
greater than 0, then this command returns format capabilities specific to
image types used in conjunction with the specified video
profiles.
In this case, this command will return one of the
video-profile-specific error codes if any of
the profiles specified via VkVideoProfileListInfoKHR::pProfiles
are not supported.
Furthermore, if VkPhysicalDeviceImageFormatInfo2::usage includes
any image usage flag not supported by the specified video profiles, then
this command returns VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.
The VkPhysicalDeviceImageFormatInfo2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceImageFormatInfo2 {
VkStructureType sType;
const void* pNext;
VkFormat format;
VkImageType type;
VkImageTiling tiling;
VkImageUsageFlags usage;
VkImageCreateFlags flags;
} VkPhysicalDeviceImageFormatInfo2;
or the equivalent
// Provided by VK_KHR_get_physical_device_properties2
typedef VkPhysicalDeviceImageFormatInfo2 VkPhysicalDeviceImageFormatInfo2KHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. ThepNextchain ofVkPhysicalDeviceImageFormatInfo2is used to provide additional image parameters tovkGetPhysicalDeviceImageFormatProperties2. -
formatis a VkFormat value indicating the image format, corresponding to VkImageCreateInfo::format. -
typeis a VkImageType value indicating the image type, corresponding to VkImageCreateInfo::imageType. -
tilingis a VkImageTiling value indicating the image tiling, corresponding to VkImageCreateInfo::tiling. -
usageis a bitmask of VkImageUsageFlagBits indicating the intended usage of the image, corresponding to VkImageCreateInfo::usage. -
flagsis a bitmask of VkImageCreateFlagBits indicating additional parameters of the image, corresponding to VkImageCreateInfo::flags.
The members of VkPhysicalDeviceImageFormatInfo2 correspond to the
arguments to vkGetPhysicalDeviceImageFormatProperties, with
sType and pNext added for extensibility.
The VkImageFormatProperties2 structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkImageFormatProperties2 {
VkStructureType sType;
void* pNext;
VkImageFormatProperties imageFormatProperties;
} VkImageFormatProperties2;
or the equivalent
// Provided by VK_KHR_get_physical_device_properties2
typedef VkImageFormatProperties2 VkImageFormatProperties2KHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. ThepNextchain ofVkImageFormatProperties2is used to allow the specification of additional capabilities to be returned fromvkGetPhysicalDeviceImageFormatProperties2. -
imageFormatPropertiesis a VkImageFormatProperties structure in which capabilities are returned.
If the combination of parameters to
vkGetPhysicalDeviceImageFormatProperties2 is not supported by the
implementation for use in vkCreateImage, then all members of
imageFormatProperties will be filled with zero.
|
Note
Filling |
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
VkTextureLODGatherFormatPropertiesAMD structure to the pNext
chain of the VkImageFormatProperties2 structure in a call to
vkGetPhysicalDeviceImageFormatProperties2.
The VkTextureLODGatherFormatPropertiesAMD structure is defined as:
// Provided by VK_AMD_texture_gather_bias_lod
typedef struct VkTextureLODGatherFormatPropertiesAMD {
VkStructureType sType;
void* pNext;
VkBool32 supportsTextureGatherLODBiasAMD;
} VkTextureLODGatherFormatPropertiesAMD;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
supportsTextureGatherLODBiasAMDtells if the image format can be used with texture gather bias/LOD functions, as introduced by theVK_AMD_texture_gather_bias_lodextension. This field is set by the implementation. User-specified value is ignored.
To determine the image capabilities compatible with an external memory
handle type, add a VkPhysicalDeviceExternalImageFormatInfo structure
to the pNext chain of the VkPhysicalDeviceImageFormatInfo2
structure and a VkExternalImageFormatProperties structure to the
pNext chain of the VkImageFormatProperties2 structure.
The VkPhysicalDeviceExternalImageFormatInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceExternalImageFormatInfo {
VkStructureType sType;
const void* pNext;
VkExternalMemoryHandleTypeFlagBits handleType;
} VkPhysicalDeviceExternalImageFormatInfo;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkPhysicalDeviceExternalImageFormatInfo VkPhysicalDeviceExternalImageFormatInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the memory handle type that will be used with the memory associated with the image.
If handleType is 0, vkGetPhysicalDeviceImageFormatProperties2
will behave as if VkPhysicalDeviceExternalImageFormatInfo was not
present, and VkExternalImageFormatProperties will be ignored.
If handleType is not compatible with the format, type,
tiling, usage, and flags specified in
VkPhysicalDeviceImageFormatInfo2, then
vkGetPhysicalDeviceImageFormatProperties2 returns
VK_ERROR_FORMAT_NOT_SUPPORTED.
Possible values of
VkPhysicalDeviceExternalImageFormatInfo::handleType, specifying
an external memory handle type, are:
// Provided by VK_VERSION_1_1
typedef enum VkExternalMemoryHandleTypeFlagBits {
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT = 0x00000001,
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT = 0x00000002,
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT = 0x00000004,
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT = 0x00000008,
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT = 0x00000010,
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT = 0x00000020,
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT = 0x00000040,
// Provided by VK_EXT_external_memory_dma_buf
VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT = 0x00000200,
// Provided by VK_ANDROID_external_memory_android_hardware_buffer
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID = 0x00000400,
// Provided by VK_EXT_external_memory_host
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT = 0x00000080,
// Provided by VK_EXT_external_memory_host
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT = 0x00000100,
// Provided by VK_FUCHSIA_external_memory
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA = 0x00000800,
// Provided by VK_NV_external_memory_rdma
VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NV = 0x00001000,
// Provided by VK_QNX_external_memory_screen_buffer
VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX = 0x00004000,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHR = VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT,
} VkExternalMemoryHandleTypeFlagBits;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalMemoryHandleTypeFlagBits VkExternalMemoryHandleTypeFlagBitsKHR;
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BITspecifies 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 callsdup,dup2,close, and the non-standard system calldup3. Additionally, it must be transportable over a socket using anSCM_RIGHTScontrol message. It owns a reference to the underlying memory resource represented by its Vulkan memory object. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BITspecifies an NT handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must be compatible with the functionsDuplicateHandle,CloseHandle,CompareObjectHandles,GetHandleInformation, andSetHandleInformation. It owns a reference to the underlying memory resource represented by its Vulkan memory object. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BITspecifies 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. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BITspecifies an NT handle returned byIDXGIResource1::CreateSharedHandlereferring to a Direct3D 10 or 11 texture resource. It owns a reference to the memory used by the Direct3D resource. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BITspecifies a global share handle returned byIDXGIResource::GetSharedHandlereferring 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. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BITspecifies an NT handle returned byID3D12Device::CreateSharedHandlereferring to a Direct3D 12 heap resource. It owns a reference to the resources used by the Direct3D heap. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BITspecifies an NT handle returned byID3D12Device::CreateSharedHandlereferring to a Direct3D 12 committed resource. It owns a reference to the memory used by the Direct3D resource. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXTspecifies 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. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXTspecifies 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. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXTis a file descriptor for a Linux dma_buf. It owns a reference to the underlying memory resource represented by its Vulkan memory object. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROIDspecifies an AHardwareBuffer object defined by the Android NDK. See Android Hardware Buffers for more details of this handle type. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIAis a Zircon handle to a virtual memory object. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NVis a handle to an allocation accessible by remote devices. It owns a reference to the underlying memory resource represented by its Vulkan memory object. -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNXspecifies a_screen_bufferobject defined by the QNX SDP. See QNX Screen Buffer for more details of this handle type.
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:
Handle type |
|
|
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
|
Note
The above table does not restrict the drivers and devices with which
|
|
Note
Even though the above table does not restrict the drivers and devices with
which |
// Provided by VK_VERSION_1_1
typedef VkFlags VkExternalMemoryHandleTypeFlags;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalMemoryHandleTypeFlags VkExternalMemoryHandleTypeFlagsKHR;
VkExternalMemoryHandleTypeFlags is a bitmask type for setting a mask
of zero or more VkExternalMemoryHandleTypeFlagBits.
The VkExternalImageFormatProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalImageFormatProperties {
VkStructureType sType;
void* pNext;
VkExternalMemoryProperties externalMemoryProperties;
} VkExternalImageFormatProperties;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalImageFormatProperties VkExternalImageFormatPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
externalMemoryPropertiesis a VkExternalMemoryProperties structure specifying various capabilities of the external handle type when used with the specified image creation parameters.
The VkExternalMemoryProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalMemoryProperties {
VkExternalMemoryFeatureFlags externalMemoryFeatures;
VkExternalMemoryHandleTypeFlags exportFromImportedHandleTypes;
VkExternalMemoryHandleTypeFlags compatibleHandleTypes;
} VkExternalMemoryProperties;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalMemoryProperties VkExternalMemoryPropertiesKHR;
-
externalMemoryFeaturesis a bitmask of VkExternalMemoryFeatureFlagBits specifying the features ofhandleType. -
exportFromImportedHandleTypesis a bitmask of VkExternalMemoryHandleTypeFlagBits specifying which types of imported handlehandleTypecan be exported from. -
compatibleHandleTypesis a bitmask of VkExternalMemoryHandleTypeFlagBits specifying handle types which can be specified at the same time ashandleTypewhen creating an image compatible with external memory.
compatibleHandleTypes must include at least handleType.
Inclusion of a handle type in compatibleHandleTypes does not imply the
values returned in VkImageFormatProperties2 will be the same when
VkPhysicalDeviceExternalImageFormatInfo::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.
Bits which may be set in
VkExternalMemoryProperties::externalMemoryFeatures, specifying
features of an external memory handle type, are:
// Provided by VK_VERSION_1_1
typedef enum VkExternalMemoryFeatureFlagBits {
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT = 0x00000001,
VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT = 0x00000002,
VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT = 0x00000004,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT_KHR = VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT_KHR = VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT,
// Provided by VK_KHR_external_memory_capabilities
VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_KHR = VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT,
} VkExternalMemoryFeatureFlagBits;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalMemoryFeatureFlagBits VkExternalMemoryFeatureFlagBitsKHR;
-
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BITspecifies that images or buffers created with the specified parameters and handle type must use the mechanisms defined by VkMemoryDedicatedRequirements and VkMemoryDedicatedAllocateInfo to create (or import) a dedicated allocation for the image or buffer. -
VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BITspecifies that handles of this type can be exported from Vulkan memory objects. -
VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BITspecifies 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 VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for
the following external handle types:
-
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROIDfor images only -
VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNXfor images only
Implementations must not report
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for buffers with
external handle type
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID.
Implementations must not report
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for buffers with
external handle type
VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX.
Implementations must not report
VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for images or buffers
with external handle type
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT, or
VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT.
// Provided by VK_VERSION_1_1
typedef VkFlags VkExternalMemoryFeatureFlags;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalMemoryFeatureFlags VkExternalMemoryFeatureFlagsKHR;
VkExternalMemoryFeatureFlags is a bitmask type for setting a mask of
zero or more VkExternalMemoryFeatureFlagBits.
To query the image capabilities that are compatible with a
Linux DRM format modifier, set
VkPhysicalDeviceImageFormatInfo2::tiling to
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and add a
VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure to the
pNext chain of VkPhysicalDeviceImageFormatInfo2.
The VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure is defined as:
// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkPhysicalDeviceImageDrmFormatModifierInfoEXT {
VkStructureType sType;
const void* pNext;
uint64_t drmFormatModifier;
VkSharingMode sharingMode;
uint32_t queueFamilyIndexCount;
const uint32_t* pQueueFamilyIndices;
} VkPhysicalDeviceImageDrmFormatModifierInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
drmFormatModifieris the image’s Linux DRM format modifier, corresponding to VkImageDrmFormatModifierExplicitCreateInfoEXT::modifieror to VkImageDrmFormatModifierListCreateInfoEXT::pModifiers. -
sharingModespecifies how the image will be accessed by multiple queue families. -
queueFamilyIndexCountis the number of entries in thepQueueFamilyIndicesarray. -
pQueueFamilyIndicesis a pointer to an array of queue families that will access the image. It is ignored ifsharingModeis notVK_SHARING_MODE_CONCURRENT.
If the drmFormatModifier is incompatible with the parameters specified
in VkPhysicalDeviceImageFormatInfo2 and its pNext chain, then
vkGetPhysicalDeviceImageFormatProperties2 returns
VK_ERROR_FORMAT_NOT_SUPPORTED.
The implementation must support the query of any drmFormatModifier,
including unknown and invalid modifier values.
To determine the number of combined image samplers required to support a
multi-planar format, add VkSamplerYcbcrConversionImageFormatProperties
to the pNext chain of the VkImageFormatProperties2 structure in
a call to vkGetPhysicalDeviceImageFormatProperties2.
The VkSamplerYcbcrConversionImageFormatProperties structure is defined
as:
// Provided by VK_VERSION_1_1
typedef struct VkSamplerYcbcrConversionImageFormatProperties {
VkStructureType sType;
void* pNext;
uint32_t combinedImageSamplerDescriptorCount;
} VkSamplerYcbcrConversionImageFormatProperties;
or the equivalent
// Provided by VK_KHR_sampler_ycbcr_conversion
typedef VkSamplerYcbcrConversionImageFormatProperties VkSamplerYcbcrConversionImageFormatPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
combinedImageSamplerDescriptorCountis the number of combined image sampler descriptors that the implementation uses to access the format.
combinedImageSamplerDescriptorCount is a number between 1 and the
number of planes in the format.
A descriptor set layout binding with immutable Y′CBCR conversion samplers
will have a maximum combinedImageSamplerDescriptorCount which is the
maximum across all formats supported by its samplers of the
combinedImageSamplerDescriptorCount for each format.
Descriptor sets with that layout will internally use that maximum
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
maxDescriptorSetSamplers, maxDescriptorSetSampledImages,
maxPerStageDescriptorSamplers, and
maxPerStageDescriptorSampledImages limits.
|
Note
All descriptors in a binding use the same maximum
For example, consider a descriptor set layout binding with two descriptors
and immutable samplers for multi-planar formats that have
|
Instead of querying all the potential formats that the application might use
in the descriptor layout, the application can use the
VkPhysicalDeviceMaintenance6PropertiesKHR::maxCombinedImageSamplerDescriptorCount
property to determine the maximum descriptor size that that will accommodate
any and all formats that
require a sampler Y′CBCR conversion supported by the implementation.
To obtain optimal Android hardware buffer usage flags for specific image
creation parameters, add a VkAndroidHardwareBufferUsageANDROID
structure to the pNext chain of a VkImageFormatProperties2
structure passed to vkGetPhysicalDeviceImageFormatProperties2.
This structure is defined as:
// Provided by VK_ANDROID_external_memory_android_hardware_buffer
typedef struct VkAndroidHardwareBufferUsageANDROID {
VkStructureType sType;
void* pNext;
uint64_t androidHardwareBufferUsage;
} VkAndroidHardwareBufferUsageANDROID;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
androidHardwareBufferUsagereturns the Android hardware buffer usage flags.
The androidHardwareBufferUsage field must include Android hardware
buffer usage flags listed in the
AHardwareBuffer Usage
Equivalence table when the corresponding Vulkan image usage or image
creation flags are included in the usage or flags fields of
VkPhysicalDeviceImageFormatInfo2.
It must include at least one GPU usage flag
(AHARDWAREBUFFER_USAGE_GPU_*), even if none of the corresponding Vulkan
usages or flags are requested.
|
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 VkImageFormatProperties2 are required. |
To query if using VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT has a negative
impact on device performance when accessing an image, add
VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT to
VkPhysicalDeviceImageFormatInfo2::usage, and add a
VkHostImageCopyDevicePerformanceQueryEXT structure to the pNext
chain of a VkImageFormatProperties2 structure passed to
vkGetPhysicalDeviceImageFormatProperties2.
This structure is defined as:
// Provided by VK_EXT_host_image_copy
typedef struct VkHostImageCopyDevicePerformanceQueryEXT {
VkStructureType sType;
void* pNext;
VkBool32 optimalDeviceAccess;
VkBool32 identicalMemoryLayout;
} VkHostImageCopyDevicePerformanceQueryEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
optimalDeviceAccessreturnsVK_TRUEif 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 VkDeviceMemory, except thatVK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXTis replaced withVK_IMAGE_USAGE_TRANSFER_SRC_BITandVK_IMAGE_USAGE_TRANSFER_DST_BIT. -
identicalMemoryLayoutreturnsVK_TRUEif 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 VkDeviceMemory, except thatVK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXTis replaced withVK_IMAGE_USAGE_TRANSFER_SRC_BITandVK_IMAGE_USAGE_TRANSFER_DST_BIT.
The implementation may return VK_FALSE in optimalDeviceAccess
if identicalMemoryLayout is VK_FALSE.
If identicalMemoryLayout is VK_TRUE, optimalDeviceAccess
must be VK_TRUE.
The implementation may return VK_TRUE in optimalDeviceAccess
while identicalMemoryLayout is VK_FALSE.
In this situation, any device performance impact should not be measurable.
If VkPhysicalDeviceImageFormatInfo2::format is a
block-compressed format and vkGetPhysicalDeviceImageFormatProperties2
returns VK_SUCCESS, the implementation must return VK_TRUE in
optimalDeviceAccess.
|
Note
Applications can make use of |
|
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
The most practical reason for |
To determine if cubic filtering can be used with a given image format and a
given image view type add a
VkPhysicalDeviceImageViewImageFormatInfoEXT structure to the
pNext chain of the VkPhysicalDeviceImageFormatInfo2 structure,
and a VkFilterCubicImageViewImageFormatPropertiesEXT structure to the
pNext chain of the VkImageFormatProperties2 structure.
The VkPhysicalDeviceImageViewImageFormatInfoEXT structure is defined
as:
// Provided by VK_EXT_filter_cubic
typedef struct VkPhysicalDeviceImageViewImageFormatInfoEXT {
VkStructureType sType;
void* pNext;
VkImageViewType imageViewType;
} VkPhysicalDeviceImageViewImageFormatInfoEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
imageViewTypeis a VkImageViewType value specifying the type of the image view.
The VkFilterCubicImageViewImageFormatPropertiesEXT structure is
defined as:
// Provided by VK_EXT_filter_cubic
typedef struct VkFilterCubicImageViewImageFormatPropertiesEXT {
VkStructureType sType;
void* pNext;
VkBool32 filterCubic;
VkBool32 filterCubicMinmax;
} VkFilterCubicImageViewImageFormatPropertiesEXT;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
filterCubictells 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. -
filterCubicMinmaxtells 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.
50.1.1. Supported Sample Counts
vkGetPhysicalDeviceImageFormatProperties returns a bitmask of
VkSampleCountFlagBits in sampleCounts specifying the supported
sample counts for the image parameters.
sampleCounts will be set to VK_SAMPLE_COUNT_1_BIT if at least
one of the following conditions is true:
-
tilingisVK_IMAGE_TILING_LINEAR -
typeis notVK_IMAGE_TYPE_2D -
flagscontainsVK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT -
Neither the
VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BITflag nor theVK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BITflag inVkFormatProperties::optimalTilingFeaturesreturned by vkGetPhysicalDeviceFormatProperties is set -
VkPhysicalDeviceExternalImageFormatInfo::
handleTypeis an external handle type for which multisampled image support is not required. -
formatis one of the formats that require a sampler Y′CBCR conversion -
usagecontainsVK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR -
usagecontainsVK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
Otherwise, the bits set in sampleCounts will be the sample counts
supported for the specified values of usage and format.
For each bit set in usage, the supported sample counts relate to the
limits in VkPhysicalDeviceLimits as follows:
-
If
usageincludesVK_IMAGE_USAGE_COLOR_ATTACHMENT_BITandformatis a floating- or fixed-point color format, a superset ofVkPhysicalDeviceLimits::framebufferColorSampleCounts -
If
usageincludesVK_IMAGE_USAGE_COLOR_ATTACHMENT_BITandformatis an integer format, a superset ofVkPhysicalDeviceVulkan12Properties::framebufferIntegerColorSampleCounts -
If
usageincludesVK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, andformatincludes a depth component, a superset ofVkPhysicalDeviceLimits::framebufferDepthSampleCounts -
If
usageincludesVK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, andformatincludes a stencil component, a superset ofVkPhysicalDeviceLimits::framebufferStencilSampleCounts -
If
usageincludesVK_IMAGE_USAGE_SAMPLED_BIT, andformatincludes a color component, a superset ofVkPhysicalDeviceLimits::sampledImageColorSampleCounts -
If
usageincludesVK_IMAGE_USAGE_SAMPLED_BIT, andformatincludes a depth component, a superset ofVkPhysicalDeviceLimits::sampledImageDepthSampleCounts -
If
usageincludesVK_IMAGE_USAGE_SAMPLED_BIT, andformatis an integer format, a superset ofVkPhysicalDeviceLimits::sampledImageIntegerSampleCounts -
If
usageincludesVK_IMAGE_USAGE_STORAGE_BIT, a superset ofVkPhysicalDeviceLimits::storageImageSampleCounts
If multiple bits are set in usage, sampleCounts will be the
intersection of the per-usage values described above.
If none of the bits described above are set in usage, then there is no
corresponding limit in VkPhysicalDeviceLimits.
In this case, sampleCounts must include at least
VK_SAMPLE_COUNT_1_BIT.
50.1.2. Allowed Extent Values Based on Image Type
Implementations may support extent values larger than the required minimum/maximum values for certain types of images.
VkImageFormatProperties::maxExtent for each type is subject to
the constraints below.
|
Note
Implementations must support images with dimensions up to the required minimum/maximum values 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 VK_IMAGE_TYPE_1D:
-
maxExtent.width≥ VkPhysicalDeviceLimits::maxImageDimension1D -
maxExtent.height= 1 -
maxExtent.depth= 1
For VK_IMAGE_TYPE_2D when flags does not contain
VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT:
-
maxExtent.width≥ VkPhysicalDeviceLimits::maxImageDimension2D -
maxExtent.height≥ VkPhysicalDeviceLimits::maxImageDimension2D -
maxExtent.depth= 1
For VK_IMAGE_TYPE_2D when flags contains
VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT:
-
maxExtent.width≥ VkPhysicalDeviceLimits::maxImageDimensionCube -
maxExtent.height≥ VkPhysicalDeviceLimits::maxImageDimensionCube -
maxExtent.depth= 1
For VK_IMAGE_TYPE_3D:
-
maxExtent.width≥ VkPhysicalDeviceLimits::maxImageDimension3D -
maxExtent.height≥ VkPhysicalDeviceLimits::maxImageDimension3D -
maxExtent.depth≥ VkPhysicalDeviceLimits::maxImageDimension3D
50.2. Additional Buffer Capabilities
To query the external handle types supported by buffers, call:
// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceExternalBufferProperties(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalBufferInfo* pExternalBufferInfo,
VkExternalBufferProperties* pExternalBufferProperties);
or the equivalent command
// Provided by VK_KHR_external_memory_capabilities
void vkGetPhysicalDeviceExternalBufferPropertiesKHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalBufferInfo* pExternalBufferInfo,
VkExternalBufferProperties* pExternalBufferProperties);
-
physicalDeviceis the physical device from which to query the buffer capabilities. -
pExternalBufferInfois a pointer to a VkPhysicalDeviceExternalBufferInfo structure describing the parameters that would be consumed by vkCreateBuffer. -
pExternalBufferPropertiesis a pointer to a VkExternalBufferProperties structure in which capabilities are returned.
The VkPhysicalDeviceExternalBufferInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceExternalBufferInfo {
VkStructureType sType;
const void* pNext;
VkBufferCreateFlags flags;
VkBufferUsageFlags usage;
VkExternalMemoryHandleTypeFlagBits handleType;
} VkPhysicalDeviceExternalBufferInfo;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkPhysicalDeviceExternalBufferInfo VkPhysicalDeviceExternalBufferInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkBufferCreateFlagBits describing additional parameters of the buffer, corresponding to VkBufferCreateInfo::flags. -
usageis a bitmask of VkBufferUsageFlagBits describing the intended usage of the buffer, corresponding to VkBufferCreateInfo::usage. -
handleTypeis a VkExternalMemoryHandleTypeFlagBits value specifying the memory handle type that will be used with the memory associated with the buffer.
Only usage flags representable in VkBufferUsageFlagBits are returned
in this structure’s usage.
If a VkBufferUsageFlags2CreateInfoKHR structure is present in the
pNext chain, all usage flags of the buffer are returned in
VkBufferUsageFlags2CreateInfoKHR::usage.
The VkExternalBufferProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalBufferProperties {
VkStructureType sType;
void* pNext;
VkExternalMemoryProperties externalMemoryProperties;
} VkExternalBufferProperties;
or the equivalent
// Provided by VK_KHR_external_memory_capabilities
typedef VkExternalBufferProperties VkExternalBufferPropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
externalMemoryPropertiesis a VkExternalMemoryProperties structure specifying various capabilities of the external handle type when used with the specified buffer creation parameters.
50.3. Optional Semaphore Capabilities
Semaphores may support import and export of their payload to external handles. To query the external handle types supported by semaphores, call:
// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceExternalSemaphoreProperties(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalSemaphoreInfo* pExternalSemaphoreInfo,
VkExternalSemaphoreProperties* pExternalSemaphoreProperties);
or the equivalent command
// Provided by VK_KHR_external_semaphore_capabilities
void vkGetPhysicalDeviceExternalSemaphorePropertiesKHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalSemaphoreInfo* pExternalSemaphoreInfo,
VkExternalSemaphoreProperties* pExternalSemaphoreProperties);
-
physicalDeviceis the physical device from which to query the semaphore capabilities. -
pExternalSemaphoreInfois a pointer to a VkPhysicalDeviceExternalSemaphoreInfo structure describing the parameters that would be consumed by vkCreateSemaphore. -
pExternalSemaphorePropertiesis a pointer to a VkExternalSemaphoreProperties structure in which capabilities are returned.
The VkPhysicalDeviceExternalSemaphoreInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceExternalSemaphoreInfo {
VkStructureType sType;
const void* pNext;
VkExternalSemaphoreHandleTypeFlagBits handleType;
} VkPhysicalDeviceExternalSemaphoreInfo;
or the equivalent
// Provided by VK_KHR_external_semaphore_capabilities
typedef VkPhysicalDeviceExternalSemaphoreInfo VkPhysicalDeviceExternalSemaphoreInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypeis a VkExternalSemaphoreHandleTypeFlagBits value specifying the external semaphore handle type for which capabilities will be returned.
Bits which may be set in
VkPhysicalDeviceExternalSemaphoreInfo::handleType, specifying an
external semaphore handle type, are:
// Provided by VK_VERSION_1_1
typedef enum VkExternalSemaphoreHandleTypeFlagBits {
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT = 0x00000001,
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT = 0x00000002,
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT = 0x00000004,
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT = 0x00000008,
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT = 0x00000010,
// Provided by VK_FUCHSIA_external_semaphore
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_ZIRCON_EVENT_BIT_FUCHSIA = 0x00000080,
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE_BIT = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT_KHR = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT_KHR = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT_KHR = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT,
} VkExternalSemaphoreHandleTypeFlagBits;
or the equivalent
// Provided by VK_KHR_external_semaphore_capabilities
typedef VkExternalSemaphoreHandleTypeFlagBits VkExternalSemaphoreHandleTypeFlagBitsKHR;
-
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BITspecifies 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 callsdup,dup2,close, and the non-standard system calldup3. Additionally, it must be transportable over a socket using anSCM_RIGHTScontrol message. It owns a reference to the underlying synchronization primitive represented by its Vulkan semaphore object. -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BITspecifies an NT handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must be compatible with the functionsDuplicateHandle,CloseHandle,CompareObjectHandles,GetHandleInformation, andSetHandleInformation. It owns a reference to the underlying synchronization primitive represented by its Vulkan semaphore object. -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BITspecifies 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. -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BITspecifies an NT handle returned byID3D12Device::CreateSharedHandlereferring to a Direct3D 12 fence, orID3D11Device5::CreateFencereferring to a Direct3D 11 fence. It owns a reference to the underlying synchronization primitive associated with the Direct3D fence. -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE_BITis an alias ofVK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BITwith the same meaning. It is provided for convenience and code clarity when interacting with D3D11 fences. -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BITspecifies 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. -
VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_ZIRCON_EVENT_BIT_FUCHSIAspecifies 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 withZX_RIGHTS_BASICandZX_RIGHTS_SIGNALrights. Vulkan on Fuchsia uses only the ZX_EVENT_SIGNALED bit when signaling or waiting.
|
Note
Handles of 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:
Handle type |
|
|
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
No restriction |
No restriction |
|
No restriction |
No restriction |
// Provided by VK_VERSION_1_1
typedef VkFlags VkExternalSemaphoreHandleTypeFlags;
or the equivalent
// Provided by VK_KHR_external_semaphore_capabilities
typedef VkExternalSemaphoreHandleTypeFlags VkExternalSemaphoreHandleTypeFlagsKHR;
VkExternalSemaphoreHandleTypeFlags is a bitmask type for setting a
mask of zero or more VkExternalSemaphoreHandleTypeFlagBits.
The VkExternalSemaphoreProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalSemaphoreProperties {
VkStructureType sType;
void* pNext;
VkExternalSemaphoreHandleTypeFlags exportFromImportedHandleTypes;
VkExternalSemaphoreHandleTypeFlags compatibleHandleTypes;
VkExternalSemaphoreFeatureFlags externalSemaphoreFeatures;
} VkExternalSemaphoreProperties;
or the equivalent
// Provided by VK_KHR_external_semaphore_capabilities
typedef VkExternalSemaphoreProperties VkExternalSemaphorePropertiesKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
exportFromImportedHandleTypesis a bitmask of VkExternalSemaphoreHandleTypeFlagBits specifying which types of imported handlehandleTypecan be exported from. -
compatibleHandleTypesis a bitmask of VkExternalSemaphoreHandleTypeFlagBits specifying handle types which can be specified at the same time ashandleTypewhen creating a semaphore. -
externalSemaphoreFeaturesis a bitmask of VkExternalSemaphoreFeatureFlagBits describing the features ofhandleType.
If handleType is not supported by the implementation, then
VkExternalSemaphoreProperties::externalSemaphoreFeatures will be
set to zero.
Bits which may be set in
VkExternalSemaphoreProperties::externalSemaphoreFeatures,
specifying the features of an external semaphore handle type, are:
// Provided by VK_VERSION_1_1
typedef enum VkExternalSemaphoreFeatureFlagBits {
VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BIT = 0x00000001,
VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT = 0x00000002,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BIT_KHR = VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BIT,
// Provided by VK_KHR_external_semaphore_capabilities
VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT_KHR = VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT,
} VkExternalSemaphoreFeatureFlagBits;
or the equivalent
// Provided by VK_KHR_external_semaphore_capabilities
typedef VkExternalSemaphoreFeatureFlagBits VkExternalSemaphoreFeatureFlagBitsKHR;
-
VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BITspecifies that handles of this type can be exported from Vulkan semaphore objects. -
VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BITspecifies that handles of this type can be imported as Vulkan semaphore objects.
// Provided by VK_VERSION_1_1
typedef VkFlags VkExternalSemaphoreFeatureFlags;
or the equivalent
// Provided by VK_KHR_external_semaphore_capabilities
typedef VkExternalSemaphoreFeatureFlags VkExternalSemaphoreFeatureFlagsKHR;
VkExternalSemaphoreFeatureFlags is a bitmask type for setting a mask
of zero or more VkExternalSemaphoreFeatureFlagBits.
50.4. Optional Fence Capabilities
Fences may support import and export of their payload to external handles. To query the external handle types supported by fences, call:
// Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceExternalFenceProperties(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalFenceInfo* pExternalFenceInfo,
VkExternalFenceProperties* pExternalFenceProperties);
or the equivalent command
// Provided by VK_KHR_external_fence_capabilities
void vkGetPhysicalDeviceExternalFencePropertiesKHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceExternalFenceInfo* pExternalFenceInfo,
VkExternalFenceProperties* pExternalFenceProperties);
-
physicalDeviceis the physical device from which to query the fence capabilities. -
pExternalFenceInfois a pointer to a VkPhysicalDeviceExternalFenceInfo structure describing the parameters that would be consumed by vkCreateFence. -
pExternalFencePropertiesis a pointer to a VkExternalFenceProperties structure in which capabilities are returned.
The VkPhysicalDeviceExternalFenceInfo structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceExternalFenceInfo {
VkStructureType sType;
const void* pNext;
VkExternalFenceHandleTypeFlagBits handleType;
} VkPhysicalDeviceExternalFenceInfo;
or the equivalent
// Provided by VK_KHR_external_fence_capabilities
typedef VkPhysicalDeviceExternalFenceInfo VkPhysicalDeviceExternalFenceInfoKHR;
-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
handleTypeis a VkExternalFenceHandleTypeFlagBits value specifying an external fence handle type for which capabilities will be returned.
|
Note
Handles of type |
Bits which may be set in
-
VkPhysicalDeviceExternalFenceInfo::
handleType -
VkExternalFenceProperties::
exportFromImportedHandleTypes -
VkExternalFenceProperties::
compatibleHandleTypes
indicate external fence handle types, and are:
// Provided by VK_VERSION_1_1
typedef enum VkExternalFenceHandleTypeFlagBits {
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT = 0x00000001,
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT = 0x00000002,
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT = 0x00000004,
VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT = 0x00000008,
// Provided by VK_KHR_external_fence_capabilities
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT_KHR = VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT,
// Provided by VK_KHR_external_fence_capabilities
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR = VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT,
// Provided by VK_KHR_external_fence_capabilities
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR = VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT,
// Provided by VK_KHR_external_fence_capabilities
VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT_KHR = VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT,
} VkExternalFenceHandleTypeFlagBits;
or the equivalent
// Provided by VK_KHR_external_fence_capabilities
typedef VkExternalFenceHandleTypeFlagBits VkExternalFenceHandleTypeFlagBitsKHR;
-
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BITspecifies 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 callsdup,dup2,close, and the non-standard system calldup3. Additionally, it must be transportable over a socket using anSCM_RIGHTScontrol message. It owns a reference to the underlying synchronization primitive represented by its Vulkan fence object. -
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BITspecifies an NT handle that has only limited valid usage outside of Vulkan and other compatible APIs. It must be compatible with the functionsDuplicateHandle,CloseHandle,CompareObjectHandles,GetHandleInformation, andSetHandleInformation. It owns a reference to the underlying synchronization primitive represented by its Vulkan fence object. -
VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BITspecifies 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. -
VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BITspecifies 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.
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:
Handle type |
|
|
|
Must match |
Must match |
|
Must match |
Must match |
|
Must match |
Must match |
|
No restriction |
No restriction |
// Provided by VK_VERSION_1_1
typedef VkFlags VkExternalFenceHandleTypeFlags;
or the equivalent
// Provided by VK_KHR_external_fence_capabilities
typedef VkExternalFenceHandleTypeFlags VkExternalFenceHandleTypeFlagsKHR;
VkExternalFenceHandleTypeFlags is a bitmask type for setting a mask of
zero or more VkExternalFenceHandleTypeFlagBits.
The VkExternalFenceProperties structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalFenceProperties {
VkStructureType sType;
void* pNext;
VkExternalFenceHandleTypeFlags exportFromImportedHandleTypes;
VkExternalFenceHandleTypeFlags compatibleHandleTypes;
VkExternalFenceFeatureFlags externalFenceFeatures;
} VkExternalFenceProperties;
or the equivalent
// Provided by VK_KHR_external_fence_capabilities
typedef VkExternalFenceProperties VkExternalFencePropertiesKHR;
-
exportFromImportedHandleTypesis a bitmask of VkExternalFenceHandleTypeFlagBits indicating which types of imported handlehandleTypecan be exported from. -
compatibleHandleTypesis a bitmask of VkExternalFenceHandleTypeFlagBits specifying handle types which can be specified at the same time ashandleTypewhen creating a fence. -
externalFenceFeaturesis a bitmask of VkExternalFenceFeatureFlagBits indicating the features ofhandleType.
If handleType is not supported by the implementation, then
VkExternalFenceProperties::externalFenceFeatures will be set to
zero.
Bits which may be set in
VkExternalFenceProperties::externalFenceFeatures, indicating
features of a fence external handle type, are:
// Provided by VK_VERSION_1_1
typedef enum VkExternalFenceFeatureFlagBits {
VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BIT = 0x00000001,
VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BIT = 0x00000002,
// Provided by VK_KHR_external_fence_capabilities
VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BIT_KHR = VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BIT,
// Provided by VK_KHR_external_fence_capabilities
VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BIT_KHR = VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BIT,
} VkExternalFenceFeatureFlagBits;
or the equivalent
// Provided by VK_KHR_external_fence_capabilities
typedef VkExternalFenceFeatureFlagBits VkExternalFenceFeatureFlagBitsKHR;
-
VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BITspecifies handles of this type can be exported from Vulkan fence objects. -
VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BITspecifies handles of this type can be imported to Vulkan fence objects.
// Provided by VK_VERSION_1_1
typedef VkFlags VkExternalFenceFeatureFlags;
or the equivalent
// Provided by VK_KHR_external_fence_capabilities
typedef VkExternalFenceFeatureFlags VkExternalFenceFeatureFlagsKHR;
VkExternalFenceFeatureFlags is a bitmask type for setting a mask of
zero or more VkExternalFenceFeatureFlagBits.
50.5. Timestamp Calibration Capabilities
To query the set of time domains for which a physical device supports timestamp calibration, call:
// Provided by VK_KHR_calibrated_timestamps
VkResult vkGetPhysicalDeviceCalibrateableTimeDomainsKHR(
VkPhysicalDevice physicalDevice,
uint32_t* pTimeDomainCount,
VkTimeDomainKHR* pTimeDomains);
or the equivalent command
// Provided by VK_EXT_calibrated_timestamps
VkResult vkGetPhysicalDeviceCalibrateableTimeDomainsEXT(
VkPhysicalDevice physicalDevice,
uint32_t* pTimeDomainCount,
VkTimeDomainKHR* pTimeDomains);
-
physicalDeviceis the physical device from which to query the set of calibrateable time domains. -
pTimeDomainCountis a pointer to an integer related to the number of calibrateable time domains available or queried, as described below. -
pTimeDomainsis eitherNULLor a pointer to an array of VkTimeDomainKHR values, indicating the supported calibrateable time domains.
If pTimeDomains is NULL, then the number of calibrateable time
domains supported for the given physicalDevice is returned in
pTimeDomainCount.
Otherwise, pTimeDomainCount must point to a variable set by the user
to the number of elements in the pTimeDomains array, and on return the
variable is overwritten with the number of values actually written to
pTimeDomains.
If the value of pTimeDomainCount is less than the number of
calibrateable time domains supported, at most pTimeDomainCount values
will be written to pTimeDomains, and VK_INCOMPLETE will be
returned instead of VK_SUCCESS, to indicate that not all the available
time domains were returned.