## 31.4. Additional Image Capabilities

In addition to the minimum capabilities described in the previous sections (Limits and Formats), implementations may support additional capabilities for certain types of images. For example, larger dimensions or additional sample counts for certain image types, or additional capabilities for linear tiling format images.

To query additional capabilities specific to image types, call:

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

- `physicalDevice` is the physical device from which to query the image capabilities.
- `format` is the image format, corresponding to `VkImageCreateInfo`::`format`.
- `type` is the image type, corresponding to `VkImageCreateInfo`::`imageType`.
- `tiling` is the image tiling, corresponding to `VkImageCreateInfo`::`tiling`.
- `usage` is the intended usage of the image, corresponding to `VkImageCreateInfo`::`usage`.
- `flags` is a bitmask describing additional parameters of the image, corresponding to `VkImageCreateInfo`::`flags`.
- `pImageFormatProperties` points to an instance of the `VkImageFormatProperties` structure in which capabilities are returned.

The `format`, `type`, `tiling`, `usage`, and `flags` parameters correspond to parameters that would be consumed by `vkCreateImage`.

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

The `VkImageFormatProperties` structure is defined as:

    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 either be equal to 1 (valid only if `tiling` is `VK_IMAGE_TILING_LINEAR`) or be equal to $\left\lceil\log_2(\max( \mathit{width},\mathit{height},\mathit{depth})) \right\rceil + 1$ where $\mathit{width}$ , $\mathit{height}$ , and $\mathit{depth}$ are taken from the corresponding members of `maxExtent`.
- `maxArrayLayers` is the maximum number of array layers. `maxArrayLayers` must either be equal to 1 or be greater than or equal to the `maxImageArrayLayers` member of `VkPhysicalDeviceLimits`. A value of 1 is valid only if `tiling` is `VK_IMAGE_TILING_LINEAR` or if `type` is `VK_IMAGE_TYPE_3D`.
- `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 or the image will be invalid. 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.

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

- `tiling` is `VK_IMAGE_TILING_LINEAR`
- `type` is not `VK_IMAGE_TYPE_2D`
- The `VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT` flag in `VkFormatProperties`::`optimalTilingFeatures` returned by `vkGetPhysicalDeviceFormatProperties` is not set

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`, a superset of `VkPhysicalDeviceLimits`::`framebufferColorSampleCounts`
- If `usage` includes `VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT`, and `format` includes a depth aspect, a superset of `VkPhysicalDeviceLimits`::`framebufferDepthSampleCounts`
- If `usage` includes `VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT`, and `format` includes a stencil aspect, a superset of `VkPhysicalDeviceLimits`::`framebufferStencilSampleCounts`
- If `usage` includes `VK_IMAGE_USAGE_SAMPLED_BIT`, and `format` includes a color aspect, a superset of `VkPhysicalDeviceLimits`::`sampledImageColorSampleCounts`
- If `usage` includes `VK_IMAGE_USAGE_SAMPLED_BIT`, and `format` includes a depth aspect, 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.

### 31.4.2. Allowed Extent Values Based On Image Type

For `VK_IMAGE_TYPE_1D`:

- $\mathit{maxExtent.width} \leq \mathit{VkPhysicalDeviceLimits.maxImageDimension1D}$
- $\mathit{maxExtent.height} = 1$
- $\mathit{maxExtent.depth} = 1$

For `VK_IMAGE_TYPE_2D`:

- $\mathit{maxExtent.width} \leq \mathit{VkPhysicalDeviceLimits.maxImageDimension2D}$
- $\mathit{maxExtent.height} \leq \mathit{VkPhysicalDeviceLimits.maxImageDimension2D}$
- $\mathit{maxExtent.depth} = 1$

For `VK_IMAGE_TYPE_3D`:

- $\mathit{maxExtent.width} \leq \mathit{VkPhysicalDeviceLimits.maxImageDimension3D}$
- $\mathit{maxExtent.height} \leq \mathit{VkPhysicalDeviceLimits.maxImageDimension3D}$
- $\mathit{maxExtent.depth} \leq \mathit{VkPhysicalDeviceLimits.maxImageDimension3D}$