1549 lines
68 KiB
Plaintext
1549 lines
68 KiB
Plaintext
// Copyright (c) 2015-2019 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/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']
|
|
--
|
|
To query additional capabilities specific to image types, call:
|
|
|
|
include::{generated}/api/protos/vkGetPhysicalDeviceImageFormatProperties.txt[]
|
|
|
|
* 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 points to an instance of the
|
|
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 sname: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_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.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageFormatProperties',desc='Structure specifying an image format properties',type='structs']
|
|
--
|
|
The sname:VkImageFormatProperties structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkImageFormatProperties.txt[]
|
|
|
|
* 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
|
|
an instance of slink:VkPhysicalDeviceExternalImageFormatInfo 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 those listed in
|
|
<<formats-requiring-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 those listed in
|
|
<<formats-requiring-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.txt[]
|
|
--
|
|
|
|
ifdef::VK_NV_external_memory_capabilities[]
|
|
include::./VK_NV_external_memory_capabilities/external_image_format.txt[]
|
|
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']
|
|
--
|
|
To query additional capabilities specific to image types, call:
|
|
|
|
ifdef::VK_VERSION_1_1[]
|
|
include::{generated}/api/protos/vkGetPhysicalDeviceImageFormatProperties2.txt[]
|
|
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.txt[]
|
|
endif::VK_KHR_get_physical_device_properties2[]
|
|
|
|
* pname:physicalDevice is the physical device from which to query the
|
|
image capabilities.
|
|
* pname:pImageFormatInfo points to an instance of the
|
|
slink:VkPhysicalDeviceImageFormatInfo2 structure, describing the
|
|
parameters that would be consumed by flink:vkCreateImage.
|
|
* pname:pImageFormatProperties points to an instance of the
|
|
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_ANDROID_external_memory_android_hardware_buffer[]
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkGetPhysicalDeviceImageFormatProperties2-pNext-01868]]
|
|
If the pname:pNext chain of pname:pImageFormatProperties contains an
|
|
instance of slink:VkAndroidHardwareBufferUsageANDROID, the pname:pNext
|
|
chain of pname:pImageFormatInfo must: contain an instance of
|
|
slink:VkPhysicalDeviceExternalImageFormatInfo with pname:handleType set
|
|
to
|
|
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID.
|
|
****
|
|
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
|
|
include::{generated}/validity/protos/vkGetPhysicalDeviceImageFormatProperties2.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPhysicalDeviceImageFormatInfo2',desc='Structure specifying image creation parameters',type='structs']
|
|
--
|
|
The sname:VkPhysicalDeviceImageFormatInfo2 structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkPhysicalDeviceImageFormatInfo2.txt[]
|
|
|
|
ifdef::VK_KHR_get_physical_device_properties2[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/structs/VkPhysicalDeviceImageFormatInfo2KHR.txt[]
|
|
endif::VK_KHR_get_physical_device_properties2[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific 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 contains
|
|
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: contain slink:VkImageFormatListCreateInfoKHR
|
|
with non-zero pname:viewFormatCount.
|
|
****
|
|
endif::VK_EXT_image_drm_format_modifier[]
|
|
|
|
include::{generated}/validity/structs/VkPhysicalDeviceImageFormatInfo2.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageFormatProperties2',desc='Structure specifying an image format properties',type='structs']
|
|
--
|
|
The sname:VkImageFormatProperties2 structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkImageFormatProperties2.txt[]
|
|
|
|
ifdef::VK_KHR_get_physical_device_properties2[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/structs/VkImageFormatProperties2KHR.txt[]
|
|
endif::VK_KHR_get_physical_device_properties2[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific 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 an instance of 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 exeption only applies to pname:imageFormatProperties, not pname:sType,
|
|
pname:pNext, or any structures chained from pname:pNext.
|
|
====
|
|
|
|
include::{generated}/validity/structs/VkImageFormatProperties2.txt[]
|
|
--
|
|
|
|
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
|
|
slink:VkImageFormatProperties2 to the pname:pNext chain of the
|
|
slink:VkPhysicalDeviceImageFormatInfo2 structure and
|
|
slink:VkTextureLODGatherFormatPropertiesAMD to the pname:pNext chain of the
|
|
slink:VkImageFormatProperties2 structure.
|
|
|
|
The sname:VkTextureLODGatherFormatPropertiesAMD structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkTextureLODGatherFormatPropertiesAMD.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL`.
|
|
* pname:supportsTextureGatherLODBiasAMD tells if the image format can be
|
|
used with texture gather bias/LOD functions, as introduced by the
|
|
`<<VK_AMD_texture_gather_bias_lod>>` extension.
|
|
This field is set by the implementation.
|
|
User-specified value is ignored.
|
|
|
|
include::{generated}/validity/structs/VkTextureLODGatherFormatPropertiesAMD.txt[]
|
|
--
|
|
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 slink:VkPhysicalDeviceExternalImageFormatInfo to the
|
|
pname:pNext chain of the slink:VkPhysicalDeviceImageFormatInfo2 structure
|
|
and sname:VkExternalImageFormatProperties to the pname:pNext chain of the
|
|
slink:VkImageFormatProperties2 structure.
|
|
|
|
The sname:VkPhysicalDeviceExternalImageFormatInfo structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkPhysicalDeviceExternalImageFormatInfo.txt[]
|
|
|
|
ifdef::VK_KHR_external_memory_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/structs/VkPhysicalDeviceExternalImageFormatInfoKHR.txt[]
|
|
endif::VK_KHR_external_memory_capabilities[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific 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.txt[]
|
|
--
|
|
|
|
[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.txt[]
|
|
|
|
ifdef::VK_KHR_external_memory_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/enums/VkExternalMemoryHandleTypeFlagBitsKHR.txt[]
|
|
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 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 dlink: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[]
|
|
|
|
<<<
|
|
|
|
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_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:VkPhysicalDeviceExternalBufferInfoKHR and
|
|
slink:VkPhysicalDeviceExternalImageFormatInfoKHR).
|
|
====
|
|
endif::VK_EXT_external_memory_dma_buf[]
|
|
--
|
|
|
|
[open,refpage='VkExternalMemoryHandleTypeFlags',desc='Bitmask of VkExternalMemoryHandleTypeFlagBits',type='flags']
|
|
--
|
|
include::{generated}/api/flags/VkExternalMemoryHandleTypeFlags.txt[]
|
|
|
|
ifdef::VK_KHR_external_memory_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/flags/VkExternalMemoryHandleTypeFlagsKHR.txt[]
|
|
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.txt[]
|
|
|
|
ifdef::VK_KHR_external_memory_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/structs/VkExternalImageFormatPropertiesKHR.txt[]
|
|
endif::VK_KHR_external_memory_capabilities[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:externalMemoryProperties is an instance of the
|
|
slink:VkExternalMemoryProperties structure specifying various
|
|
capabilities of the external handle type when used with the specified
|
|
image creation parameters.
|
|
|
|
include::{generated}/validity/structs/VkExternalImageFormatProperties.txt[]
|
|
--
|
|
|
|
[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.txt[]
|
|
|
|
ifdef::VK_KHR_external_memory_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/structs/VkExternalMemoryPropertiesKHR.txt[]
|
|
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.txt[]
|
|
--
|
|
|
|
[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.txt[]
|
|
|
|
ifdef::VK_KHR_external_memory_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/enums/VkExternalMemoryFeatureFlagBitsKHR.txt[]
|
|
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_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[]
|
|
|
|
--
|
|
|
|
[open,refpage='VkExternalMemoryFeatureFlags',desc='Bitmask of VkExternalMemoryFeatureFlagBits',type='flags']
|
|
--
|
|
include::{generated}/api/flags/VkExternalMemoryFeatureFlags.txt[]
|
|
|
|
ifdef::VK_KHR_external_memory_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/flags/VkExternalMemoryFeatureFlagsKHR.txt[]
|
|
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
|
|
slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT to the pname:pNext chain
|
|
of slink:VkPhysicalDeviceImageFormatInfo2.
|
|
|
|
The slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure is defined
|
|
as:
|
|
|
|
include::{generated}/api/structs/VkPhysicalDeviceImageDrmFormatModifierInfoEXT.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific 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 list of queue families that will access
|
|
the image (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.txt[]
|
|
--
|
|
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.txt[]
|
|
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/structs/VkSamplerYcbcrConversionImageFormatPropertiesKHR.txt[]
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:combinedImageSamplerDescriptorCount is the number of combined
|
|
image sampler descriptors that the implementation uses to access the
|
|
format.
|
|
|
|
include::{generated}/validity/structs/VkSamplerYcbcrConversionImageFormatProperties.txt[]
|
|
--
|
|
|
|
pname:combinedImageSamplerDescriptorCount is a number between 1 and the
|
|
number of planes in the format.
|
|
A descriptor set layout binding with immutable Y'C~b~C~r~ 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.
|
|
====
|
|
|
|
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, attach an instance of
|
|
sname:VkAndroidHardwareBufferUsageANDROID to the pname:pNext chain of a
|
|
slink:VkImageFormatProperties2 structure passed to
|
|
flink:vkGetPhysicalDeviceImageFormatProperties2.
|
|
This structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkAndroidHardwareBufferUsageANDROID.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific 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.txt[]
|
|
--
|
|
|
|
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
|
|
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 slink:VkPhysicalDeviceImageViewImageFormatInfoEXT
|
|
to the pname:pNext chain of the slink:VkPhysicalDeviceImageFormatInfo2
|
|
structure and slink:VkFilterCubicImageViewImageFormatPropertiesEXT 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.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:imageViewType is a elink:VkImageViewType value specifying the type
|
|
of the image view.
|
|
|
|
include::{generated}/validity/structs/VkPhysicalDeviceImageViewImageFormatInfoEXT.txt[]
|
|
--
|
|
|
|
[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.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific 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.txt[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkFilterCubicImageViewImageFormatPropertiesEXT-pNext-02627]]
|
|
If the pname:pNext chain of the slink:VkImageFormatProperties2 structure
|
|
contains an instance of
|
|
slink:VkFilterCubicImageViewImageFormatPropertiesEXT, the pname:pNext
|
|
chain of the slink:VkPhysicalDeviceImageFormatInfo2 structure must:
|
|
contain an instance of slink:VkPhysicalDeviceImageViewImageFormatInfoEXT
|
|
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:VkPhysicalDeviceExternalImageFormatInfoKHR::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 those listed in
|
|
<<formats-requiring-sampler-ycbcr-conversion>>
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_NV_shading_rate_image[]
|
|
* pname:usage contains ename:VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV
|
|
endif::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
|
|
* If pname:usage includes
|
|
ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and pname:format
|
|
includes a depth aspect, 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 aspect, a superset of
|
|
sname:VkPhysicalDeviceLimits::pname:framebufferStencilSampleCounts
|
|
* If pname:usage includes ename:VK_IMAGE_USAGE_SAMPLED_BIT, and
|
|
pname:format includes a color aspect, a superset of
|
|
sname:VkPhysicalDeviceLimits::pname:sampledImageColorSampleCounts
|
|
* If pname:usage includes ename:VK_IMAGE_USAGE_SAMPLED_BIT, and
|
|
pname:format includes a depth aspect, 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 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.txt[]
|
|
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.txt[]
|
|
endif::VK_KHR_external_memory_capabilities[]
|
|
|
|
* pname:physicalDevice is the physical device from which to query the
|
|
buffer capabilities.
|
|
* pname:pExternalBufferInfo points to an instance of the
|
|
slink:VkPhysicalDeviceExternalBufferInfo structure, describing the
|
|
parameters that would be consumed by flink:vkCreateBuffer.
|
|
* pname:pExternalBufferProperties points to an instance of the
|
|
slink:VkExternalBufferProperties structure in which capabilities are
|
|
returned.
|
|
|
|
include::{generated}/validity/protos/vkGetPhysicalDeviceExternalBufferProperties.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPhysicalDeviceExternalBufferInfo',desc='Structure specifying buffer creation parameters',type='structs']
|
|
--
|
|
The sname:VkPhysicalDeviceExternalBufferInfo structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkPhysicalDeviceExternalBufferInfo.txt[]
|
|
|
|
ifdef::VK_KHR_external_memory_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/structs/VkPhysicalDeviceExternalBufferInfoKHR.txt[]
|
|
endif::VK_KHR_external_memory_capabilities[]
|
|
|
|
* pname:sType is the type of this structure
|
|
* pname:pNext is NULL or a pointer to an extension-specific 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.
|
|
|
|
include::{generated}/validity/structs/VkPhysicalDeviceExternalBufferInfo.txt[]
|
|
--
|
|
|
|
[open,refpage='VkExternalBufferProperties',desc='Structure specifying supported external handle capabilities',type='structs']
|
|
--
|
|
The sname:VkExternalBufferProperties structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkExternalBufferProperties.txt[]
|
|
|
|
ifdef::VK_KHR_external_memory_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/structs/VkExternalBufferPropertiesKHR.txt[]
|
|
endif::VK_KHR_external_memory_capabilities[]
|
|
|
|
* pname:sType is the type of this structure
|
|
* pname:pNext is NULL or a pointer to an extension-specific structure.
|
|
* pname:externalMemoryProperties is an instance of the
|
|
slink:VkExternalMemoryProperties structure specifying various
|
|
capabilities of the external handle type when used with the specified
|
|
buffer creation parameters.
|
|
|
|
include::{generated}/validity/structs/VkExternalBufferProperties.txt[]
|
|
--
|
|
|
|
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.txt[]
|
|
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.txt[]
|
|
endif::VK_KHR_external_semaphore_capabilities[]
|
|
|
|
* pname:physicalDevice is the physical device from which to query the
|
|
semaphore capabilities.
|
|
* pname:pExternalSemaphoreInfo points to an instance of the
|
|
slink:VkPhysicalDeviceExternalSemaphoreInfo structure, describing the
|
|
parameters that would be consumed by flink:vkCreateSemaphore.
|
|
* pname:pExternalSemaphoreProperties points to an instance of the
|
|
slink:VkExternalSemaphoreProperties structure in which capabilities are
|
|
returned.
|
|
|
|
include::{generated}/validity/protos/vkGetPhysicalDeviceExternalSemaphoreProperties.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPhysicalDeviceExternalSemaphoreInfo',desc='Structure specifying semaphore creation parameters.',type='structs']
|
|
--
|
|
The sname:VkPhysicalDeviceExternalSemaphoreInfo structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkPhysicalDeviceExternalSemaphoreInfo.txt[]
|
|
|
|
ifdef::VK_KHR_external_semaphore_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/structs/VkPhysicalDeviceExternalSemaphoreInfoKHR.txt[]
|
|
endif::VK_KHR_external_semaphore_capabilities[]
|
|
|
|
* pname:sType is the type of this structure
|
|
* pname:pNext is NULL or a pointer to an extension-specific 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.txt[]
|
|
--
|
|
|
|
[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.txt[]
|
|
|
|
ifdef::VK_KHR_external_semaphore_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/enums/VkExternalSemaphoreHandleTypeFlagBitsKHR.txt[]
|
|
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 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.
|
|
It owns a reference to the underlying synchronization primitive
|
|
associated with the Direct3D fence.
|
|
* 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.
|
|
|
|
[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
|
|
|====
|
|
--
|
|
|
|
[open,refpage='VkExternalSemaphoreHandleTypeFlags',desc='Bitmask of VkExternalSemaphoreHandleTypeFlagBits',type='flags']
|
|
--
|
|
include::{generated}/api/flags/VkExternalSemaphoreHandleTypeFlags.txt[]
|
|
|
|
ifdef::VK_KHR_external_semaphore_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/flags/VkExternalSemaphoreHandleTypeFlagsKHR.txt[]
|
|
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.txt[]
|
|
|
|
ifdef::VK_KHR_external_semaphore_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/structs/VkExternalSemaphorePropertiesKHR.txt[]
|
|
endif::VK_KHR_external_semaphore_capabilities[]
|
|
|
|
* 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.txt[]
|
|
--
|
|
|
|
[open,refpage='VkExternalSemaphoreFeatureFlagBits',desc='Bitfield describing features of an external semaphore handle type',type='enums']
|
|
--
|
|
Possible values of
|
|
slink:VkExternalSemaphoreProperties::pname:externalSemaphoreFeatures,
|
|
specifying the features of an external semaphore handle type, are:
|
|
|
|
include::{generated}/api/enums/VkExternalSemaphoreFeatureFlagBits.txt[]
|
|
|
|
ifdef::VK_KHR_external_semaphore_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/enums/VkExternalSemaphoreFeatureFlagBitsKHR.txt[]
|
|
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.txt[]
|
|
|
|
ifdef::VK_KHR_external_semaphore_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/flags/VkExternalSemaphoreFeatureFlagsKHR.txt[]
|
|
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.txt[]
|
|
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.txt[]
|
|
endif::VK_KHR_external_fence_capabilities[]
|
|
|
|
* pname:physicalDevice is the physical device from which to query the
|
|
fence capabilities.
|
|
* pname:pExternalFenceInfo points to an instance of the
|
|
slink:VkPhysicalDeviceExternalFenceInfo structure, describing the
|
|
parameters that would be consumed by flink:vkCreateFence.
|
|
* pname:pExternalFenceProperties points to an instance of the
|
|
slink:VkExternalFenceProperties structure in which capabilities are
|
|
returned.
|
|
|
|
include::{generated}/validity/protos/vkGetPhysicalDeviceExternalFenceProperties.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPhysicalDeviceExternalFenceInfo',desc='Structure specifying fence creation parameters.',type='structs']
|
|
--
|
|
The sname:VkPhysicalDeviceExternalFenceInfo structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkPhysicalDeviceExternalFenceInfo.txt[]
|
|
|
|
ifdef::VK_KHR_external_fence_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/structs/VkPhysicalDeviceExternalFenceInfoKHR.txt[]
|
|
endif::VK_KHR_external_fence_capabilities[]
|
|
|
|
* pname:sType is the type of this structure
|
|
* pname:pNext is NULL or a pointer to an extension-specific structure.
|
|
* pname:handleType is a elink:VkExternalFenceHandleTypeFlagBits value
|
|
indicating 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.txt[]
|
|
--
|
|
|
|
[open,refpage='VkExternalFenceHandleTypeFlagBits',desc='Bitmask of valid external fence handle types',type='enums']
|
|
--
|
|
Bits which may: be set in
|
|
slink:VkPhysicalDeviceExternalFenceInfo::pname:handleType, and in the
|
|
pname:exportFromImportedHandleTypes and pname:compatibleHandleTypes members
|
|
of slink:VkExternalFenceProperties, to indicate external fence handle types,
|
|
are:
|
|
|
|
include::{generated}/api/enums/VkExternalFenceHandleTypeFlagBits.txt[]
|
|
|
|
ifdef::VK_KHR_external_fence_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/enums/VkExternalFenceHandleTypeFlagBitsKHR.txt[]
|
|
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.
|
|
|
|
<<<
|
|
|
|
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
|
|
|====
|
|
--
|
|
|
|
[open,refpage='VkExternalFenceHandleTypeFlags',desc='Bitmask of VkExternalFenceHandleTypeFlagBits',type='flags']
|
|
--
|
|
include::{generated}/api/flags/VkExternalFenceHandleTypeFlags.txt[]
|
|
|
|
ifdef::VK_KHR_external_fence_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/flags/VkExternalFenceHandleTypeFlagsKHR.txt[]
|
|
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.txt[]
|
|
|
|
ifdef::VK_KHR_external_fence_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/structs/VkExternalFencePropertiesKHR.txt[]
|
|
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.txt[]
|
|
--
|
|
|
|
[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.txt[]
|
|
|
|
ifdef::VK_KHR_external_fence_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/enums/VkExternalFenceFeatureFlagBitsKHR.txt[]
|
|
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.txt[]
|
|
|
|
ifdef::VK_KHR_external_fence_capabilities[]
|
|
or the equivalent
|
|
|
|
include::{generated}/api/flags/VkExternalFenceFeatureFlagsKHR.txt[]
|
|
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']
|
|
--
|
|
To query the set of time domains for which a physical device supports
|
|
timestamp calibration, call:
|
|
|
|
include::{generated}/api/protos/vkGetPhysicalDeviceCalibrateableTimeDomainsEXT.txt[]
|
|
|
|
* 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.
|
|
If pname:pTimeDomainCount is smaller than the number of calibrateable time
|
|
domains supported for the given pname:physicalDevice, ename:VK_INCOMPLETE
|
|
will be returned instead of ename:VK_SUCCESS to indicate that not all the
|
|
available values were returned.
|
|
|
|
include::{generated}/validity/protos/vkGetPhysicalDeviceCalibrateableTimeDomainsEXT.txt[]
|
|
--
|
|
|
|
endif::VK_EXT_calibrated_timestamps[]
|