VkImageFormatProperties(3)

# VkImageFormatProperties(3) Manual Page

## Name

VkImageFormatProperties - Structure specifying an image format properties

## C Specification

The `VkImageFormatProperties` structure is defined as:

    typedef struct VkImageFormatProperties {
        VkExtent3D            maxExtent;
        uint32_t              maxMipLevels;
        uint32_t              maxArrayLayers;
        VkSampleCountFlags    sampleCounts;
        VkDeviceSize          maxResourceSize;
    } VkImageFormatProperties;

## Members

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

  - `vkGetPhysicalDeviceImageFormatProperties`::`tiling` was `VK_IMAGE_TILING_LINEAR`

  - VkPhysicalDeviceImageFormatInfo2::`tiling` was `VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT`

  - the VkPhysicalDeviceImageFormatInfo2::`pNext` chain included a VkPhysicalDeviceExternalImageFormatInfo structure with a handle type included in the `handleTypes` member for which mipmap image support is not required

  - image `format` is one of those listed in https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#formats-requiring-sampler-ycbcr-conversion

  - `flags` contains `VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT`

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

  - `tiling` is `VK_IMAGE_TILING_LINEAR`

  - `tiling` is `VK_IMAGE_TILING_OPTIMAL` and `type` is `VK_IMAGE_TYPE_3D`

  - `format` is one of those listed in https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#formats-requiring-sampler-ycbcr-conversion

- If `tiling` is `VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT`, then `maxArrayLayers` must not be 0.

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

## Description

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

## See Also

`VkDeviceSize`, VkExtent3D, VkExternalImageFormatPropertiesNV, VkImageFormatProperties2, VkSampleCountFlags, vkGetPhysicalDeviceImageFormatProperties

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