vkGetPhysicalDeviceSparseImageFormatProperties(3)

# vkGetPhysicalDeviceSparseImageFormatProperties(3) Manual Page

## Name

vkGetPhysicalDeviceSparseImageFormatProperties - Retrieve properties of an image format applied to sparse images

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

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

- `format` is the image format.

- `type` is the dimensionality of image.

- `samples` is the number of samples per texel as defined in VkSampleCountFlagBits.

- `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

- `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)

- `physicalDevice` must be a valid `VkPhysicalDevice` handle

- `format` must be a valid VkFormat value

- `type` must be a valid VkImageType value

- `samples` must be a valid VkSampleCountFlagBits value

- `usage` must be a valid combination of VkImageUsageFlagBits values

- `usage` must not be `0`

- `tiling` must be a valid VkImageTiling value

- `pPropertyCount` must be a valid pointer to a `uint32_t` value

- 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

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 (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.