VKGETPHYSICALDEVICEI(3)

NAME
vkGetPhysicalDeviceImageFormatProperties - Lists physical device's image format capabilities.

C SPECIFICATION

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

PARAMETERS

physicalDevice
    A handle to the physical device upon which to perform the query.

format
    The format of the image.

type
    The type of the image.

tiling
    The tiling mode of the image.

usage
    The usage of the image.

flags
    Additional flags describing the image.

pImageFormatProperties
    A pointer to a structure in which the requested information is returned.

DESCRIPTION

vkGetPhysicalDeviceImageFormatProperties queries the physical device specified in physicalDevice about its support for images as if they had been created using the remaining parameters to the command. These parameters, format, type, tiling and usage have the same meanings as they do in the VkImageCreateInfo structure, the definition of which is:

    typedef struct VkImageCreateInfo {
        VkStructureType          sType;
        const void*              pNext;
        VkImageCreateFlags       flags;
        VkImageType              imageType;
        VkFormat                 format;
        VkExtent3D               extent;
        uint32_t                 mipLevels;
        uint32_t                 arrayLayers;
        VkSampleCountFlagBits    samples;
        VkImageTiling            tiling;
        VkImageUsageFlags        usage;
        VkSharingMode            sharingMode;
        uint32_t                 queueFamilyIndexCount;
        const uint32_t*          pQueueFamilyIndices;
        VkImageLayout            initialLayout;
    } VkImageCreateInfo;

In this call, format specifies the format of the image and must be a member of the VkFormat enumeration. type specifies the type of image for which the format will be used. This is a member of the VkImageType enumeration, the definition of which is:

    typedef enum VkImageType {
        VK_IMAGE_TYPE_1D = 0,
        VK_IMAGE_TYPE_2D = 1,
        VK_IMAGE_TYPE_3D = 2,
    } VkImageType;

The tiling parameter specifies the tiling layout for the image and must be one of VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_OPTIMAL. The usage parameter specifies the intended usage for the image and should be a bitwise combination of one or more members of the VkImageUsageFlagBits enumeration, the definition of which is:

    typedef enum VkImageUsageFlagBits {
        VK_IMAGE_USAGE_TRANSFER_SRC_BIT = 0x00000001,
        VK_IMAGE_USAGE_TRANSFER_DST_BIT = 0x00000002,
        VK_IMAGE_USAGE_SAMPLED_BIT = 0x00000004,
        VK_IMAGE_USAGE_STORAGE_BIT = 0x00000008,
        VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT = 0x00000010,
        VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000020,
        VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT = 0x00000040,
        VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT = 0x00000080,
    } VkImageUsageFlagBits;

If the image format is supported for the specified combination of the format, type, tiling, usage, and flags parameters, then vkGetPhysicalDeviceImageFormatProperties places information about how such an image may be used in the instance of the VkImageFormatProperties structure pointed to by pImageFormatProperties. The definition of VkImageFormatProperties is:

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

The maxExtent member of the output structure contains the maximum dimensions of an image in the specified format. The maxMipLevels and maxArrayLayers contain the maximum number of mipmap levels and maximum number of layers in array forms of images, respectively. If array images are not supported for the specified format, then maxArrayLayers will be zero. If multisampling is supported for the specified format, then sampleCounts contains a bitwise combination of the supported sample counts using members of the VkSampleCountFlagBits enumeration, the definition of which is:

    typedef enum VkSampleCountFlagBits {
        VK_SAMPLE_COUNT_1_BIT = 0x00000001,
        VK_SAMPLE_COUNT_2_BIT = 0x00000002,
        VK_SAMPLE_COUNT_4_BIT = 0x00000004,
        VK_SAMPLE_COUNT_8_BIT = 0x00000008,
        VK_SAMPLE_COUNT_16_BIT = 0x00000010,
        VK_SAMPLE_COUNT_32_BIT = 0x00000020,
        VK_SAMPLE_COUNT_64_BIT = 0x00000040,
    } VkSampleCountFlagBits;

Additional sample counts not listed in the VkSampleCountFlagBits enumeration are reserved and their presence should not be used to imply higher sample counts than listed.

If multisampling is not supported for the specified format, then sampleCounts will contain zero.

The maxResourceSize member contains the maximum size in memory of any resource in this format. Note that it may not be possible to create a resource of the maximum supported extent and array layer count in every dimension that still fits within the maxium in-memory resource size.

If the format is not supported in the specified configuration, then vkGetPhysicalDeviceImageFormatProperties fills the VkImageFormatProperties structure pointed to by pImageFormatProperties with zeros.

VALID USAGE

    • physicalDevice must be a valid VkPhysicalDevice handle

    • format must be a valid VkFormat value

    • type must be a valid VkImageType value

    • tiling must be a valid VkImageTiling value

    • usage must be a valid combination of VkImageUsageFlagBits values

    • usage must not be 0

    • flags must be a valid combination of VkImageCreateFlagBits values

    • pImageFormatProperties must be a pointer to a VkImageFormatProperties structure

RETURN CODES

On success, this command returns

        • VK_SUCCESS

On failure, this command returns

        • VK_ERROR_OUT_OF_HOST_MEMORY

        • VK_ERROR_OUT_OF_DEVICE_MEMORY

        • VK_ERROR_FORMAT_NOT_SUPPORTED

SEE ALSO

vkGetPhysicalDeviceProperties, vkGetPhysicalDeviceFeatures

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.