VkImageCreateInfo(3)

Name

VkImageCreateInfo - Structure specifying the parameters of a newly created image object

C Specification

The VkImageCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
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;

Members

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkImageCreateFlagBits describing additional parameters of the image.

  • imageType is a VkImageType value specifying the basic dimensionality of the image. Layers in array textures do not count as a dimension for the purposes of the image type.

  • format is a VkFormat describing the format and type of the texel blocks that will be contained in the image.

  • extent is a VkExtent3D describing the number of texels/pixels in each dimension of the base level.

  • mipLevels describes the number of levels of detail available for minified sampling of the image.

  • arrayLayers is the number of layers in the image.

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

  • tiling is a VkImageTiling value specifying the tiling arrangement of the texel blocks in memory.

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

  • sharingMode is a VkSharingMode value specifying the sharing mode of the image when it will be accessed by multiple queue families.

  • queueFamilyIndexCount is the number of entries in the pQueueFamilyIndices array.

  • pQueueFamilyIndices is a pointer to an array of queue families that will access this image. It is ignored if sharingMode is not VK_SHARING_MODE_CONCURRENT.

  • initialLayout is a VkImageLayout value specifying the initial VkImageLayout of all image subresources of the image. See Image Layouts.

Description

Images created with tiling equal to VK_IMAGE_TILING_LINEAR have further restrictions on their limits and capabilities compared to images created with tiling equal to VK_IMAGE_TILING_OPTIMAL. Creation of images with tiling VK_IMAGE_TILING_LINEAR may not be supported unless other parameters meet all of the constraints:

Images created with one of the formats that require a sampler Y′CBCR conversion, have further restrictions on their limits and capabilities compared to images created with other formats. Creation of images with a format requiring Y′CBCR conversion may not be supported unless other parameters meet all of the constraints:

Images created with the VK_IMAGE_USAGE_TILE_MEMORY_BIT_QCOM usage flag set have further restrictions on their limits and capabilities compared to images created without this flag. Creation of images with usage including VK_IMAGE_USAGE_TILE_MEMORY_BIT_QCOM may not be supported unless parameters meet all of the constraints:

Implementations may support additional limits and capabilities beyond those listed above.

To determine the set of valid usage bits for a given format, call vkGetPhysicalDeviceFormatProperties.

If the size of the resultant image would exceed maxResourceSize, then vkCreateImage must fail and return VK_ERROR_OUT_OF_DEVICE_MEMORY. This failure may occur even when all image creation parameters satisfy their valid usage requirements.

If the implementation reports VK_TRUE in VkPhysicalDeviceHostImageCopyProperties::identicalMemoryTypeRequirements, usage of VK_IMAGE_USAGE_HOST_TRANSFER_BIT must not affect the memory type requirements of the image as described in Sparse Resource Memory Requirements and Resource Memory Association.

For images created without the VK_IMAGE_CREATE_EXTENDED_USAGE_BIT flag set, a usage bit is valid if it is supported for the format the image is created with.

For images created with VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a usage bit is valid if it is supported for at least one of the formats a VkImageView created from the image can have (see Image Views for more detail).
Image Creation Limits

Valid values for some image creation parameters are limited by a numerical upper bound or by inclusion in a bitset. For example, VkImageCreateInfo::arrayLayers is limited by imageCreateMaxArrayLayers, defined below; and VkImageCreateInfo::samples is limited by imageCreateSampleCounts, also defined below.

Several limiting values are defined below, as well as assisting values from which the limiting values are derived. The limiting values are referenced by the relevant valid usage statements of VkImageCreateInfo.

Valid Usage
Valid Usage (Implicit)

See Also

VK_VERSION_1_0, VkDeviceImageMemoryRequirements, VkDeviceImageSubresourceInfo, VkExtent3D, VkFormat, VkImageCreateFlags, VkImageFormatConstraintsInfoFUCHSIA, VkImageLayout, VkImageTiling, VkImageType, VkImageUsageFlags, VkSampleCountFlagBits, VkSharingMode, VkStructureType, vkCreateImage

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.