C Specification

vkGetPhysicalDeviceSparseImageFormatProperties returns an array of VkSparseImageFormatProperties. Each element will describe properties for one set of image aspects that are bound simultaneously in the image. This is usually one element for each aspect in the image, but for interleaved depth/stencil images there is only one element describing the combined aspects.

// Provided by VK_VERSION_1_0
void vkGetPhysicalDeviceSparseImageFormatProperties(
    VkPhysicalDevice                            physicalDevice,
    VkFormat                                    format,
    VkImageType                                 type,
    VkSampleCountFlagBits                       samples,
    VkImageUsageFlags                           usage,
    VkImageTiling                               tiling,
    uint32_t*                                   pPropertyCount,
    VkSparseImageFormatProperties*              pProperties);

Parameters

  • physicalDevice is the physical device from which to query the sparse image format properties.

  • format is the image format.

  • type is the dimensionality of image.

  • samples is a VkSampleCountFlagBits value specifying the number of samples per texel.

  • usage is a bitmask describing the intended usage of the image.

  • tiling is the tiling arrangement of the texel blocks in memory.

  • pPropertyCount is a pointer to an integer related to the number of sparse format properties available or queried, as described below.

  • pProperties is either NULL or a pointer to an array of VkSparseImageFormatProperties structures.

Description

If pProperties is NULL, then the number of sparse format properties available is returned in pPropertyCount. Otherwise, pPropertyCount must point to a variable set by the user to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If pPropertyCount is less than the number of sparse format properties available, at most pPropertyCount structures will be written.

If VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT is not supported for the given arguments, pPropertyCount will be set to zero upon return, and no data will be written to pProperties.

Multiple aspects are returned for depth/stencil images that are implemented as separate planes by the implementation. The depth and stencil data planes each have unique VkSparseImageFormatProperties data.

Depth/stencil images with depth and stencil data interleaved into a single plane will return a single VkSparseImageFormatProperties structure with the aspectMask set to VK_IMAGE_ASPECT_DEPTH_BIT | VK_IMAGE_ASPECT_STENCIL_BIT.

Valid Usage

  • VUID-vkGetPhysicalDeviceSparseImageFormatProperties-samples-01094
    samples must be a bit value that is set in VkImageFormatProperties::sampleCounts returned by vkGetPhysicalDeviceImageFormatProperties with format, type, tiling, and usage equal to those in this command and flags equal to the value that is set in VkImageCreateInfo::flags when the image is created

Valid Usage (Implicit)

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

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

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

  • VUID-vkGetPhysicalDeviceSparseImageFormatProperties-samples-parameter
    samples must be a valid VkSampleCountFlagBits value

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

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

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

  • VUID-vkGetPhysicalDeviceSparseImageFormatProperties-pPropertyCount-parameter
    pPropertyCount must be a valid pointer to a uint32_t value

  • VUID-vkGetPhysicalDeviceSparseImageFormatProperties-pProperties-parameter
    If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount VkSparseImageFormatProperties structures

See Also

VK_VERSION_1_0, VkFormat, VkImageTiling, VkImageType, VkImageUsageFlags, VkPhysicalDevice, VkSampleCountFlagBits, VkSparseImageFormatProperties

Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0