Google Git
Sign in
android / platform / hardware / google / gfxstream / 8c226810c7942a36fbe0d74b1644128309d36c2c / . / codegen / vulkan / vulkan-docs-next / chapters / capabilities.adoc
blob: 490c0bca9d729ed2ba0658625882d2de3a56f2e8 [file] [log] [blame]
// Copyright 2015-2023 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 <<limits, Limits>> and <<formats, Formats>>
chapters, including:
* <<capabilities-image, Additional Image Capabilities>>
ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[]
* <<capabilities-buffer, Additional Buffer Capabilities>>
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>>
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>>
endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[]
ifdef::VK_EXT_calibrated_timestamps[]
* <<features-timestamp-calibration, Timestamp Calibration Capabilities>>
endif::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 <<features-extentperimagetype, Allowed Extent Values>> 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
<<formats-requiring-sampler-ycbcr-conversion, formats that require a
sampler {YCbCr} conversion>>
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
<<formats-requiring-sampler-ycbcr-conversion, formats that require a
sampler {YCbCr} conversion>>
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
<<features-supported-sample-counts, below>>.
* 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 <<video-profiles,video
profiles>>.
In this case, this command will return one of the
<<video-profile-error-codes, video-profile-specific error codes>> 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 <<memory-external-android-hardware-buffer,Android Hardware Buffers>>
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 <<memory-external-qnx-screen-buffer,QNX Screen Buffer>> 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
<<glossary-drm-format-modifier,Linux DRM format modifier>>, 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`.
====
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
<<memory-external-android-hardware-buffer-usage,AHardwareBuffer Usage
Equivalence>> 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 <<formats-requiring-sampler-ycbcr-conversion,
formats that require a sampler {YCbCr} conversion>>
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 <<limits-minmax,
required minimum/maximum values>> 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
<<limits-minmax, 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 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']
--
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[]
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
<<synchronization-semaphores-payloads, payload>> 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
<<synchronization-fences-payloads, payload>> 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_EXT_calibrated_timestamps[]
[[features-timestamp-calibration]]
== Timestamp Calibration Capabilities
[open,refpage='vkGetPhysicalDeviceCalibrateableTimeDomainsEXT',desc='Query calibrateable time domains',type='protos']
--
:refpage: vkGetPhysicalDeviceCalibrateableTimeDomainsEXT
To query the set of time domains for which a physical device supports
timestamp calibration, call:
include::{generated}/api/protos/vkGetPhysicalDeviceCalibrateableTimeDomainsEXT.adoc[]
* 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:VkTimeDomainEXT 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/vkGetPhysicalDeviceCalibrateableTimeDomainsEXT.adoc[]
--
endif::VK_EXT_calibrated_timestamps[]
ifdef::VK_KHR_object_refresh[]
include::{chapters}/VK_KHR_object_refresh/capabilities.adoc[]
endif::VK_KHR_object_refresh[]