Vulkan Logo

    35. Additional Capabilities

    This chapter describes additional capabilities beyond the minimum capabilities described in the Limits and Formats chapters, including:

    35.1. Additional Image Capabilities

    Additional image capabilities, such as larger dimensions or additional sample counts for certain image types, or additional capabilities for linear tiling format images, are described in this section.

    To query additional capabilities specific to image types, call:

    // Provided by VK_VERSION_1_0
VkResult vkGetPhysicalDeviceImageFormatProperties(
    VkPhysicalDevice                            physicalDevice,
    VkFormat                                    format,
    VkImageType                                 type,
    VkImageTiling                               tiling,
    VkImageUsageFlags                           usage,
    VkImageCreateFlags                          flags,
    VkImageFormatProperties*                    pImageFormatProperties);

    The format, type, tiling, usage, and flags parameters correspond to parameters that would be consumed by vkCreateImage (as members of VkImageCreateInfo).

    If format is not a supported image format, or if the combination of format, type, tiling, usage, and flags is not supported for images, then vkGetPhysicalDeviceImageFormatProperties returns VK_ERROR_FORMAT_NOT_SUPPORTED.

    The limitations on an image format that are reported by vkGetPhysicalDeviceImageFormatProperties have the following property: if usage1 and usage2 of type VkImageUsageFlags are such that the bits set in usage1 are a subset of the bits set in usage2, and flags1 and flags2 of type VkImageCreateFlags are such that the bits set in flags1 are a subset of the bits set in flags2, then the limitations for usage1 and flags1 must be no more strict than the limitations for usage2 and flags2, for all values of format, type, and tiling.

    Valid Usage (Implicit)

    • VUID-vkGetPhysicalDeviceImageFormatProperties-physicalDevice-parameter
      physicalDevice must be a valid VkPhysicalDevice handle

    • VUID-vkGetPhysicalDeviceImageFormatProperties-format-parameter
      format must be a valid VkFormat value

    • VUID-vkGetPhysicalDeviceImageFormatProperties-type-parameter
      type must be a valid VkImageType value

    • VUID-vkGetPhysicalDeviceImageFormatProperties-tiling-parameter
      tiling must be a valid VkImageTiling value

    • VUID-vkGetPhysicalDeviceImageFormatProperties-usage-parameter
      usage must be a valid combination of VkImageUsageFlagBits values

    • VUID-vkGetPhysicalDeviceImageFormatProperties-usage-requiredbitmask
      usage must not be 0

    • VUID-vkGetPhysicalDeviceImageFormatProperties-flags-parameter
      flags must be a valid combination of VkImageCreateFlagBits values

    • VUID-vkGetPhysicalDeviceImageFormatProperties-pImageFormatProperties-parameter
      pImageFormatProperties must be a valid pointer to a VkImageFormatProperties structure

    Return Codes
    Success

    • VK_SUCCESS

    Failure

    • VK_ERROR_OUT_OF_HOST_MEMORY

    • VK_ERROR_OUT_OF_DEVICE_MEMORY

    • VK_ERROR_FORMAT_NOT_SUPPORTED

    The VkImageFormatProperties structure is defined as:

    // Provided by VK_VERSION_1_0
typedef struct VkImageFormatProperties {
    VkExtent3D            maxExtent;
    uint32_t              maxMipLevels;
    uint32_t              maxArrayLayers;
    VkSampleCountFlags    sampleCounts;
    VkDeviceSize          maxResourceSize;
} VkImageFormatProperties;

    • maxExtent are the maximum image dimensions. See the Allowed Extent Values section below for how these values are constrained by type.

    • maxMipLevels is the maximum number of mipmap levels. maxMipLevels must be equal to the number of levels in the complete mipmap chain based on the maxExtent.width, maxExtent.height, and maxExtent.depth, except when one of the following conditions is true, in which case it may instead be 1:

    • maxArrayLayers is the maximum number of array layers. maxArrayLayers must be no less than VkPhysicalDeviceLimits::maxImageArrayLayers, except when one of the following conditions is true, in which case it may instead be 1:

    • sampleCounts is a bitmask of VkSampleCountFlagBits specifying all the supported sample counts for this image as described below.

    • 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. maxResourceSize must be at least 231.

    Note

    There is no mechanism to query the size of an image before creating it, to compare that size against maxResourceSize. If an application attempts to create an image that exceeds this limit, the creation will fail and vkCreateImage will return VK_ERROR_OUT_OF_DEVICE_MEMORY. While the advertised limit must be at least 231, it may not be possible to create an image that approaches that size, particularly for VK_IMAGE_TYPE_1D.

    If the combination of parameters to vkGetPhysicalDeviceImageFormatProperties is not supported by the implementation for use in vkCreateImage, then all members of VkImageFormatProperties will be filled with zero.

    Note

    Filling 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.

    To query additional capabilities specific to image types, call:

    // Provided by VK_VERSION_1_1
VkResult vkGetPhysicalDeviceImageFormatProperties2(
    VkPhysicalDevice                            physicalDevice,
    const VkPhysicalDeviceImageFormatInfo2*     pImageFormatInfo,
    VkImageFormatProperties2*                   pImageFormatProperties);

    vkGetPhysicalDeviceImageFormatProperties2 behaves similarly to vkGetPhysicalDeviceImageFormatProperties, with the ability to return extended information in a pNext chain of output structures.

    Valid Usage (Implicit)

    • VUID-vkGetPhysicalDeviceImageFormatProperties2-physicalDevice-parameter
      physicalDevice must be a valid VkPhysicalDevice handle

    • VUID-vkGetPhysicalDeviceImageFormatProperties2-pImageFormatInfo-parameter
      pImageFormatInfo must be a valid pointer to a valid VkPhysicalDeviceImageFormatInfo2 structure

    • VUID-vkGetPhysicalDeviceImageFormatProperties2-pImageFormatProperties-parameter
      pImageFormatProperties must be a valid pointer to a VkImageFormatProperties2 structure

    Return Codes
    Success

    • VK_SUCCESS

    Failure

    • VK_ERROR_OUT_OF_HOST_MEMORY

    • VK_ERROR_OUT_OF_DEVICE_MEMORY

    • VK_ERROR_FORMAT_NOT_SUPPORTED

    The VkPhysicalDeviceImageFormatInfo2 structure is defined as:

    // Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceImageFormatInfo2 {
    VkStructureType       sType;
    const void*           pNext;
    VkFormat              format;
    VkImageType           type;
    VkImageTiling         tiling;
    VkImageUsageFlags     usage;
    VkImageCreateFlags    flags;
} VkPhysicalDeviceImageFormatInfo2;

    The members of VkPhysicalDeviceImageFormatInfo2 correspond to the arguments to vkGetPhysicalDeviceImageFormatProperties, with sType and pNext added for extensibility.

    Valid Usage (Implicit)

    • VUID-VkPhysicalDeviceImageFormatInfo2-sType-sType
      sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_FORMAT_INFO_2

    • VUID-VkPhysicalDeviceImageFormatInfo2-pNext-pNext
      Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkImageFormatListCreateInfo, VkImageStencilUsageCreateInfo, or VkPhysicalDeviceExternalImageFormatInfo

    • VUID-VkPhysicalDeviceImageFormatInfo2-sType-unique
      The sType value of each struct in the pNext chain must be unique

    • VUID-VkPhysicalDeviceImageFormatInfo2-format-parameter
      format must be a valid VkFormat value

    • VUID-VkPhysicalDeviceImageFormatInfo2-type-parameter
      type must be a valid VkImageType value

    • VUID-VkPhysicalDeviceImageFormatInfo2-tiling-parameter
      tiling must be a valid VkImageTiling value

    • VUID-VkPhysicalDeviceImageFormatInfo2-usage-parameter
      usage must be a valid combination of VkImageUsageFlagBits values

    • VUID-VkPhysicalDeviceImageFormatInfo2-usage-requiredbitmask
      usage must not be 0

    • VUID-VkPhysicalDeviceImageFormatInfo2-flags-parameter
      flags must be a valid combination of VkImageCreateFlagBits values

    The VkImageFormatProperties2 structure is defined as:

    // Provided by VK_VERSION_1_1
typedef struct VkImageFormatProperties2 {
    VkStructureType            sType;
    void*                      pNext;
    VkImageFormatProperties    imageFormatProperties;
} VkImageFormatProperties2;

    • sType is a VkStructureType value identifying this structure.

    • pNext is NULL or a pointer to a structure extending this structure. The pNext chain of VkImageFormatProperties2 is used to allow the specification of additional capabilities to be returned from vkGetPhysicalDeviceImageFormatProperties2.

    • imageFormatProperties is a VkImageFormatProperties structure in which capabilities are returned.

    If the combination of parameters to vkGetPhysicalDeviceImageFormatProperties2 is not supported by the implementation for use in vkCreateImage, then all members of imageFormatProperties will be filled with zero.

    Note

    Filling 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 imageFormatProperties, not sType, pNext, or any structures chained from pNext.
    Valid Usage (Implicit)

    • VUID-VkImageFormatProperties2-sType-sType
      sType must be VK_STRUCTURE_TYPE_IMAGE_FORMAT_PROPERTIES_2

    • VUID-VkImageFormatProperties2-pNext-pNext
      Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkExternalImageFormatProperties or VkSamplerYcbcrConversionImageFormatProperties

    • VUID-VkImageFormatProperties2-sType-unique
      The sType value of each struct in the pNext chain must be unique

    To determine the image capabilities compatible with an external memory handle type, add a VkPhysicalDeviceExternalImageFormatInfo structure to the pNext chain of the VkPhysicalDeviceImageFormatInfo2 structure and a VkExternalImageFormatProperties structure to the pNext chain of the VkImageFormatProperties2 structure.

    The VkPhysicalDeviceExternalImageFormatInfo structure is defined as:

    // Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceExternalImageFormatInfo {
    VkStructureType                       sType;
    const void*                           pNext;
    VkExternalMemoryHandleTypeFlagBits    handleType;
} VkPhysicalDeviceExternalImageFormatInfo;

    • sType is a VkStructureType value identifying this structure.

    • pNext is NULL or a pointer to a structure extending this structure.

    • handleType is a VkExternalMemoryHandleTypeFlagBits value specifying the memory handle type that will be used with the memory associated with the image.

    If handleType is 0, vkGetPhysicalDeviceImageFormatProperties2 will behave as if VkPhysicalDeviceExternalImageFormatInfo was not present, and VkExternalImageFormatProperties will be ignored.

    If handleType is not compatible with the format, type, tiling, usage, and flags specified in VkPhysicalDeviceImageFormatInfo2, then vkGetPhysicalDeviceImageFormatProperties2 returns VK_ERROR_FORMAT_NOT_SUPPORTED.

    Valid Usage (Implicit)

    • VUID-VkPhysicalDeviceExternalImageFormatInfo-sType-sType
      sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_IMAGE_FORMAT_INFO

    • VUID-VkPhysicalDeviceExternalImageFormatInfo-handleType-parameter
      If handleType is not 0, handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

    Possible values of VkPhysicalDeviceExternalImageFormatInfo::handleType, specifying an external memory handle type, are:

    // Provided by VK_VERSION_1_1
typedef enum VkExternalMemoryHandleTypeFlagBits {
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT = 0x00000001,
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT = 0x00000002,
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT = 0x00000004,
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT = 0x00000008,
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT = 0x00000010,
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT = 0x00000020,
    VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT = 0x00000040,
} VkExternalMemoryHandleTypeFlagBits;

    • 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 dup, dup2, close, and the non-standard system call dup3. Additionally, it must be transportable over a socket using an SCM_RIGHTS control message. It owns a reference to the underlying memory resource represented by its Vulkan memory object.

    • 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 DuplicateHandle, CloseHandle, CompareObjectHandles, GetHandleInformation, and SetHandleInformation. It owns a reference to the underlying memory resource represented by its Vulkan memory object.

    • 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.

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT specifies an NT handle returned by IDXGIResource1::CreateSharedHandle referring to a Direct3D 10 or 11 texture resource. It owns a reference to the memory used by the Direct3D resource.

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT specifies a global share handle returned by IDXGIResource::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.

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT specifies an NT handle returned by ID3D12Device::CreateSharedHandle referring to a Direct3D 12 heap resource. It owns a reference to the resources used by the Direct3D heap.

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT specifies an NT handle returned by ID3D12Device::CreateSharedHandle referring to a Direct3D 12 committed resource. It owns a reference to the memory used by the Direct3D resource.

    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:

    Table 59. External memory handle types compatibility

    Handle type

    VkPhysicalDeviceIDProperties::driverUUID

    VkPhysicalDeviceIDProperties::deviceUUID

    VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT

    Must match

    Must match

    VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT

    Must match

    Must match

    VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT

    Must match

    Must match

    VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT

    Must match

    Must match

    VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT

    Must match

    Must match

    VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT

    Must match

    Must match

    VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT

    Must match

    Must match

    		 
    // Provided by VK_VERSION_1_1
typedef VkFlags VkExternalMemoryHandleTypeFlags;

    VkExternalMemoryHandleTypeFlags is a bitmask type for setting a mask of zero or more VkExternalMemoryHandleTypeFlagBits.

    The VkExternalImageFormatProperties structure is defined as:

    // Provided by VK_VERSION_1_1
typedef struct VkExternalImageFormatProperties {
    VkStructureType               sType;
    void*                         pNext;
    VkExternalMemoryProperties    externalMemoryProperties;
} VkExternalImageFormatProperties;

    • sType is a VkStructureType value identifying this structure.

    • pNext is NULL or a pointer to a structure extending this structure.

    • externalMemoryProperties is a VkExternalMemoryProperties structure specifying various capabilities of the external handle type when used with the specified image creation parameters.

    Valid Usage (Implicit)

    • VUID-VkExternalImageFormatProperties-sType-sType
      sType must be VK_STRUCTURE_TYPE_EXTERNAL_IMAGE_FORMAT_PROPERTIES

    The VkExternalMemoryProperties structure is defined as:

    // Provided by VK_VERSION_1_1
typedef struct VkExternalMemoryProperties {
    VkExternalMemoryFeatureFlags       externalMemoryFeatures;
    VkExternalMemoryHandleTypeFlags    exportFromImportedHandleTypes;
    VkExternalMemoryHandleTypeFlags    compatibleHandleTypes;
} VkExternalMemoryProperties;

    compatibleHandleTypes must include at least handleType. Inclusion of a handle type in compatibleHandleTypes does not imply the values returned in VkImageFormatProperties2 will be the same when VkPhysicalDeviceExternalImageFormatInfo::handleType is set to that type. The application is responsible for querying the capabilities of all handle types intended for concurrent use in a single image and intersecting them to obtain the compatible set of capabilities.

    Bits which may be set in VkExternalMemoryProperties::externalMemoryFeatures, specifying features of an external memory handle type, are:

    // Provided by VK_VERSION_1_1
typedef enum VkExternalMemoryFeatureFlagBits {
    VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT = 0x00000001,
    VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT = 0x00000002,
    VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT = 0x00000004,
} VkExternalMemoryFeatureFlagBits;

    • 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 VkMemoryDedicatedRequirements and VkMemoryDedicatedAllocateInfo to create (or import) a dedicated allocation for the image or buffer.

    • VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT specifies that handles of this type can be exported from Vulkan memory objects.

    • 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 VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for the following external handle types:

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT

    • VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT

    // Provided by VK_VERSION_1_1
typedef VkFlags VkExternalMemoryFeatureFlags;

    VkExternalMemoryFeatureFlags is a bitmask type for setting a mask of zero or more VkExternalMemoryFeatureFlagBits.

    To determine the number of combined image samplers required to support a multi-planar format, add VkSamplerYcbcrConversionImageFormatProperties to the pNext chain of the VkImageFormatProperties2 structure in a call to vkGetPhysicalDeviceImageFormatProperties2.

    The VkSamplerYcbcrConversionImageFormatProperties structure is defined as:

    // Provided by VK_VERSION_1_1
typedef struct VkSamplerYcbcrConversionImageFormatProperties {
    VkStructureType    sType;
    void*              pNext;
    uint32_t           combinedImageSamplerDescriptorCount;
} VkSamplerYcbcrConversionImageFormatProperties;

    • sType is a VkStructureType value identifying this structure.

    • pNext is NULL or a pointer to a structure extending this structure.

    • combinedImageSamplerDescriptorCount is the number of combined image sampler descriptors that the implementation uses to access the format.

    Valid Usage (Implicit)

    • VUID-VkSamplerYcbcrConversionImageFormatProperties-sType-sType
      sType must be VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_IMAGE_FORMAT_PROPERTIES

    combinedImageSamplerDescriptorCount is a number between 1 and the number of planes in the format. A descriptor set layout binding with immutable Y′CBCR conversion samplers will have a maximum combinedImageSamplerDescriptorCount which is the maximum across all formats supported by its samplers of the combinedImageSamplerDescriptorCount for each format. Descriptor sets with that layout will internally use that maximum combinedImageSamplerDescriptorCount descriptors for each descriptor in the binding. This expanded number of descriptors will be consumed from the descriptor pool when a descriptor set is allocated, and counts towards the maxDescriptorSetSamplers, maxDescriptorSetSampledImages, maxPerStageDescriptorSamplers, and maxPerStageDescriptorSampledImages limits.

    Note

    All descriptors in a binding use the same maximum 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 VkSamplerYcbcrConversionImageFormatProperties::combinedImageSamplerDescriptorCount values of 2 and 3 respectively. There are two descriptors in the binding and the maximum 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, descriptorCount must be at least 24.

    35.1.1. Supported Sample Counts

    vkGetPhysicalDeviceImageFormatProperties returns a bitmask of VkSampleCountFlagBits in sampleCounts specifying the supported sample counts for the image parameters.

    sampleCounts will be set to VK_SAMPLE_COUNT_1_BIT if at least one of the following conditions is true:

    Otherwise, the bits set in sampleCounts will be the sample counts supported for the specified values of usage and format. For each bit set in usage, the supported sample counts relate to the limits in VkPhysicalDeviceLimits as follows:

    • If usage includes VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT and format is a floating- or fixed-point color format, a superset of VkPhysicalDeviceLimits::framebufferColorSampleCounts

    • If usage includes VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT and format is an integer format, a superset of VkPhysicalDeviceVulkan12Properties::framebufferIntegerColorSampleCounts

    • If usage includes VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and format includes a depth component, a superset of VkPhysicalDeviceLimits::framebufferDepthSampleCounts

    • If usage includes VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and format includes a stencil component, a superset of VkPhysicalDeviceLimits::framebufferStencilSampleCounts

    • If usage includes VK_IMAGE_USAGE_SAMPLED_BIT, and format includes a color component, a superset of VkPhysicalDeviceLimits::sampledImageColorSampleCounts

    • If usage includes VK_IMAGE_USAGE_SAMPLED_BIT, and format includes a depth component, a superset of VkPhysicalDeviceLimits::sampledImageDepthSampleCounts

    • If usage includes VK_IMAGE_USAGE_SAMPLED_BIT, and format is an integer format, a superset of VkPhysicalDeviceLimits::sampledImageIntegerSampleCounts

    • If usage includes VK_IMAGE_USAGE_STORAGE_BIT, a superset of VkPhysicalDeviceLimits::storageImageSampleCounts

    If multiple bits are set in usage, sampleCounts will be the intersection of the per-usage values described above.

    If none of the bits described above are set in usage, then there is no corresponding limit in VkPhysicalDeviceLimits. In this case, sampleCounts must include at least VK_SAMPLE_COUNT_1_BIT.

    35.1.2. Allowed Extent Values Based on Image Type

    Implementations may support extent values larger than the required minimum/maximum values for certain types of images. VkImageFormatProperties::maxExtent for each type is subject to the constraints below.

    Note

    Implementations must support images with dimensions up to the required minimum/maximum values for all types of images. It follows that the query for additional capabilities must return extent values that are at least as large as the required values.

    For VK_IMAGE_TYPE_1D:

    For VK_IMAGE_TYPE_2D when flags does not contain VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT:

    For VK_IMAGE_TYPE_2D when flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT:

    For VK_IMAGE_TYPE_3D:

    35.2. Additional Buffer Capabilities

    To query the external handle types supported by buffers, call:

    // Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceExternalBufferProperties(
    VkPhysicalDevice                            physicalDevice,
    const VkPhysicalDeviceExternalBufferInfo*   pExternalBufferInfo,
    VkExternalBufferProperties*                 pExternalBufferProperties);
    Valid Usage (Implicit)

    • VUID-vkGetPhysicalDeviceExternalBufferProperties-physicalDevice-parameter
      physicalDevice must be a valid VkPhysicalDevice handle

    • VUID-vkGetPhysicalDeviceExternalBufferProperties-pExternalBufferInfo-parameter
      pExternalBufferInfo must be a valid pointer to a valid VkPhysicalDeviceExternalBufferInfo structure

    • VUID-vkGetPhysicalDeviceExternalBufferProperties-pExternalBufferProperties-parameter
      pExternalBufferProperties must be a valid pointer to a VkExternalBufferProperties structure

    The VkPhysicalDeviceExternalBufferInfo structure is defined as:

    // Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceExternalBufferInfo {
    VkStructureType                       sType;
    const void*                           pNext;
    VkBufferCreateFlags                   flags;
    VkBufferUsageFlags                    usage;
    VkExternalMemoryHandleTypeFlagBits    handleType;
} VkPhysicalDeviceExternalBufferInfo;

    Only usage flags representable in VkBufferUsageFlagBits are returned in this structure’s usage.

    Valid Usage

    • VUID-VkPhysicalDeviceExternalBufferInfo-None-09499
      usage must be a valid combination of VkBufferUsageFlagBits values

    • VUID-VkPhysicalDeviceExternalBufferInfo-None-09500
      usage must not be 0

    Valid Usage (Implicit)

    • VUID-VkPhysicalDeviceExternalBufferInfo-sType-sType
      sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_BUFFER_INFO

    • VUID-VkPhysicalDeviceExternalBufferInfo-pNext-pNext
      pNext must be NULL

    • VUID-VkPhysicalDeviceExternalBufferInfo-flags-parameter
      flags must be a valid combination of VkBufferCreateFlagBits values

    • VUID-VkPhysicalDeviceExternalBufferInfo-handleType-parameter
      handleType must be a valid VkExternalMemoryHandleTypeFlagBits value

    The VkExternalBufferProperties structure is defined as:

    // Provided by VK_VERSION_1_1
typedef struct VkExternalBufferProperties {
    VkStructureType               sType;
    void*                         pNext;
    VkExternalMemoryProperties    externalMemoryProperties;
} VkExternalBufferProperties;

    • sType is a VkStructureType value identifying this structure.

    • pNext is NULL or a pointer to a structure extending this structure.

    • externalMemoryProperties is a VkExternalMemoryProperties structure specifying various capabilities of the external handle type when used with the specified buffer creation parameters.

    Valid Usage (Implicit)

    • VUID-VkExternalBufferProperties-sType-sType
      sType must be VK_STRUCTURE_TYPE_EXTERNAL_BUFFER_PROPERTIES

    • VUID-VkExternalBufferProperties-pNext-pNext
      pNext must be NULL

    35.3. Optional Semaphore Capabilities

    Semaphores may support import and export of their payload to external handles. To query the external handle types supported by semaphores, call:

    // Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceExternalSemaphoreProperties(
    VkPhysicalDevice                            physicalDevice,
    const VkPhysicalDeviceExternalSemaphoreInfo* pExternalSemaphoreInfo,
    VkExternalSemaphoreProperties*              pExternalSemaphoreProperties);
    Valid Usage (Implicit)

    • VUID-vkGetPhysicalDeviceExternalSemaphoreProperties-physicalDevice-parameter
      physicalDevice must be a valid VkPhysicalDevice handle

    • VUID-vkGetPhysicalDeviceExternalSemaphoreProperties-pExternalSemaphoreInfo-parameter
      pExternalSemaphoreInfo must be a valid pointer to a valid VkPhysicalDeviceExternalSemaphoreInfo structure

    • VUID-vkGetPhysicalDeviceExternalSemaphoreProperties-pExternalSemaphoreProperties-parameter
      pExternalSemaphoreProperties must be a valid pointer to a VkExternalSemaphoreProperties structure

    The VkPhysicalDeviceExternalSemaphoreInfo structure is defined as:

    // Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceExternalSemaphoreInfo {
    VkStructureType                          sType;
    const void*                              pNext;
    VkExternalSemaphoreHandleTypeFlagBits    handleType;
} VkPhysicalDeviceExternalSemaphoreInfo;

    • sType is a VkStructureType value identifying this structure.

    • pNext is NULL or a pointer to a structure extending this structure.

    • handleType is a VkExternalSemaphoreHandleTypeFlagBits value specifying the external semaphore handle type for which capabilities will be returned.

    Valid Usage (Implicit)

    • VUID-VkPhysicalDeviceExternalSemaphoreInfo-sType-sType
      sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_SEMAPHORE_INFO

    • VUID-VkPhysicalDeviceExternalSemaphoreInfo-pNext-pNext
      pNext must be NULL or a pointer to a valid instance of VkSemaphoreTypeCreateInfo

    • VUID-VkPhysicalDeviceExternalSemaphoreInfo-sType-unique
      The sType value of each struct in the pNext chain must be unique

    • VUID-VkPhysicalDeviceExternalSemaphoreInfo-handleType-parameter
      handleType must be a valid VkExternalSemaphoreHandleTypeFlagBits value

    Bits which may be set in VkPhysicalDeviceExternalSemaphoreInfo::handleType, specifying an external semaphore handle type, are:

    // Provided by VK_VERSION_1_1
typedef enum VkExternalSemaphoreHandleTypeFlagBits {
    VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT = 0x00000001,
    VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT = 0x00000002,
    VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT = 0x00000004,
    VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT = 0x00000008,
    VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT = 0x00000010,
    VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE_BIT = VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT,
} VkExternalSemaphoreHandleTypeFlagBits;

    • 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 dup, dup2, close, and the non-standard system call dup3. Additionally, it must be transportable over a socket using an SCM_RIGHTS control message. It owns a reference to the underlying synchronization primitive represented by its Vulkan semaphore object.

    • 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 DuplicateHandle, CloseHandle, CompareObjectHandles, GetHandleInformation, and SetHandleInformation. It owns a reference to the underlying synchronization primitive represented by its Vulkan semaphore object.

    • 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.

    • VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT specifies an NT handle returned by ID3D12Device::CreateSharedHandle referring to a Direct3D 12 fence, or ID3D11Device5::CreateFence referring to a Direct3D 11 fence. It owns a reference to the underlying synchronization primitive associated with the Direct3D fence.

    • VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE_BIT is an alias of 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.

    • 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

    Handles of type 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:

    Table 60. External semaphore handle types compatibility

    Handle type

    VkPhysicalDeviceIDProperties::driverUUID

    VkPhysicalDeviceIDProperties::deviceUUID

    VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT

    Must match

    Must match

    VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT

    Must match

    Must match

    VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT

    Must match

    Must match

    VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT

    Must match

    Must match

    VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT

    No restriction

    No restriction

    VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_ZIRCON_EVENT_BIT_FUCHSIA

    No restriction

    No restriction

    		 
    // Provided by VK_VERSION_1_1
typedef VkFlags VkExternalSemaphoreHandleTypeFlags;

    VkExternalSemaphoreHandleTypeFlags is a bitmask type for setting a mask of zero or more VkExternalSemaphoreHandleTypeFlagBits.

    The VkExternalSemaphoreProperties structure is defined as:

    // Provided by VK_VERSION_1_1
typedef struct VkExternalSemaphoreProperties {
    VkStructureType                       sType;
    void*                                 pNext;
    VkExternalSemaphoreHandleTypeFlags    exportFromImportedHandleTypes;
    VkExternalSemaphoreHandleTypeFlags    compatibleHandleTypes;
    VkExternalSemaphoreFeatureFlags       externalSemaphoreFeatures;
} VkExternalSemaphoreProperties;

    If handleType is not supported by the implementation, then VkExternalSemaphoreProperties::externalSemaphoreFeatures will be set to zero.

    Valid Usage (Implicit)

    • VUID-VkExternalSemaphoreProperties-sType-sType
      sType must be VK_STRUCTURE_TYPE_EXTERNAL_SEMAPHORE_PROPERTIES

    • VUID-VkExternalSemaphoreProperties-pNext-pNext
      pNext must be NULL

    Bits which may be set in VkExternalSemaphoreProperties::externalSemaphoreFeatures, specifying the features of an external semaphore handle type, are:

    // Provided by VK_VERSION_1_1
typedef enum VkExternalSemaphoreFeatureFlagBits {
    VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BIT = 0x00000001,
    VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT = 0x00000002,
} VkExternalSemaphoreFeatureFlagBits;

    • VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BIT specifies that handles of this type can be exported from Vulkan semaphore objects.

    • VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT specifies that handles of this type can be imported as Vulkan semaphore objects.

    // Provided by VK_VERSION_1_1
typedef VkFlags VkExternalSemaphoreFeatureFlags;

    VkExternalSemaphoreFeatureFlags is a bitmask type for setting a mask of zero or more VkExternalSemaphoreFeatureFlagBits.

    35.4. Optional Fence Capabilities

    Fences may support import and export of their payload to external handles. To query the external handle types supported by fences, call:

    // Provided by VK_VERSION_1_1
void vkGetPhysicalDeviceExternalFenceProperties(
    VkPhysicalDevice                            physicalDevice,
    const VkPhysicalDeviceExternalFenceInfo*    pExternalFenceInfo,
    VkExternalFenceProperties*                  pExternalFenceProperties);
    Valid Usage (Implicit)

    • VUID-vkGetPhysicalDeviceExternalFenceProperties-physicalDevice-parameter
      physicalDevice must be a valid VkPhysicalDevice handle

    • VUID-vkGetPhysicalDeviceExternalFenceProperties-pExternalFenceInfo-parameter
      pExternalFenceInfo must be a valid pointer to a valid VkPhysicalDeviceExternalFenceInfo structure

    • VUID-vkGetPhysicalDeviceExternalFenceProperties-pExternalFenceProperties-parameter
      pExternalFenceProperties must be a valid pointer to a VkExternalFenceProperties structure

    The VkPhysicalDeviceExternalFenceInfo structure is defined as:

    // Provided by VK_VERSION_1_1
typedef struct VkPhysicalDeviceExternalFenceInfo {
    VkStructureType                      sType;
    const void*                          pNext;
    VkExternalFenceHandleTypeFlagBits    handleType;
} VkPhysicalDeviceExternalFenceInfo;

    • sType is a VkStructureType value identifying this structure.

    • pNext is NULL or a pointer to a structure extending this structure.

    • handleType is a VkExternalFenceHandleTypeFlagBits value specifying an external fence handle type for which capabilities will be returned.

    Note

    Handles of type 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.
    Valid Usage (Implicit)

    • VUID-VkPhysicalDeviceExternalFenceInfo-sType-sType
      sType must be VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_FENCE_INFO

    • VUID-VkPhysicalDeviceExternalFenceInfo-pNext-pNext
      pNext must be NULL

    • VUID-VkPhysicalDeviceExternalFenceInfo-handleType-parameter
      handleType must be a valid VkExternalFenceHandleTypeFlagBits value

    Bits which may be set in

    indicate external fence handle types, and are:

    // Provided by VK_VERSION_1_1
typedef enum VkExternalFenceHandleTypeFlagBits {
    VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT = 0x00000001,
    VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT = 0x00000002,
    VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT = 0x00000004,
    VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT = 0x00000008,
} VkExternalFenceHandleTypeFlagBits;

    • 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 dup, dup2, close, and the non-standard system call dup3. Additionally, it must be transportable over a socket using an SCM_RIGHTS control message. It owns a reference to the underlying synchronization primitive represented by its Vulkan fence object.

    • 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 DuplicateHandle, CloseHandle, CompareObjectHandles, GetHandleInformation, and SetHandleInformation. It owns a reference to the underlying synchronization primitive represented by its Vulkan fence object.

    • 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.

    • 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:

    Table 61. External fence handle types compatibility

    Handle type

    VkPhysicalDeviceIDProperties::driverUUID

    VkPhysicalDeviceIDProperties::deviceUUID

    VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT

    Must match

    Must match

    VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT

    Must match

    Must match

    VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT

    Must match

    Must match

    VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT

    No restriction

    No restriction

    		 
    // Provided by VK_VERSION_1_1
typedef VkFlags VkExternalFenceHandleTypeFlags;

    VkExternalFenceHandleTypeFlags is a bitmask type for setting a mask of zero or more VkExternalFenceHandleTypeFlagBits.

    The VkExternalFenceProperties structure is defined as:

    // Provided by VK_VERSION_1_1
typedef struct VkExternalFenceProperties {
    VkStructureType                   sType;
    void*                             pNext;
    VkExternalFenceHandleTypeFlags    exportFromImportedHandleTypes;
    VkExternalFenceHandleTypeFlags    compatibleHandleTypes;
    VkExternalFenceFeatureFlags       externalFenceFeatures;
} VkExternalFenceProperties;

    If handleType is not supported by the implementation, then VkExternalFenceProperties::externalFenceFeatures will be set to zero.

    Valid Usage (Implicit)

    • VUID-VkExternalFenceProperties-sType-sType
      sType must be VK_STRUCTURE_TYPE_EXTERNAL_FENCE_PROPERTIES

    • VUID-VkExternalFenceProperties-pNext-pNext
      pNext must be NULL

    Bits which may be set in VkExternalFenceProperties::externalFenceFeatures, indicating features of a fence external handle type, are:

    // Provided by VK_VERSION_1_1
typedef enum VkExternalFenceFeatureFlagBits {
    VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BIT = 0x00000001,
    VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BIT = 0x00000002,
} VkExternalFenceFeatureFlagBits;

    • VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BIT specifies handles of this type can be exported from Vulkan fence objects.

    • VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BIT specifies handles of this type can be imported to Vulkan fence objects.

    // Provided by VK_VERSION_1_1
typedef VkFlags VkExternalFenceFeatureFlags;

    VkExternalFenceFeatureFlags is a bitmask type for setting a mask of zero or more VkExternalFenceFeatureFlagBits.