VKIMAGECREATEINFO(3)

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

C SPECIFICATION

    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;

FIELDS

sType
    Structure type. Must be VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO.

pNext
    Pointer to next structure in the structure chain when applicable.

imageType
    Type of the image (see VkImageType for more detail).

format
    Format of the texels of the image (see VkFormat for more detail).

extent
    Width, height, and depth of the image in texels.

mipLevels
    Number of mip levels of the image.

arrayLayers
    Number of layers of the image.

samples
    Number of samples of the image.

tiling
    Image tiling mode of the image (see VkImageTiling for more detail).

usage
    Allowed usages of the image (see VkImageUsageFlags for more detail).

flags
    Other properties of the image (see VkImageCreateFlags for more detail).

sharingMode
    Sharing mode used for the image (see VkSharingMode for more detail).

queueFamilyIndexCount
    Number of queue families that can access the image in case sharingMode is VK_SHARING_MODE_CONCURRENT.

pQueueFamilyIndices
    Array of queueFamilyIndexCount queue family indices specifying the set of queue families that can access the image in case sharingMode is VK_SHARING_MODE_CONCURRENT.

DESCRIPTION

This structure is used to specify the parameters of image objects created using vkCreateImage.

VALID USAGE

    • sType must be VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO

    • pNext must be NULL

    • flags must be a valid combination of VkImageCreateFlagBits values

    • imageType must be a valid VkImageType value

    • format must be a valid VkFormat value

    • samples must be a valid VkSampleCountFlagBits value

    • tiling must be a valid VkImageTiling value

    • usage must be a valid combination of VkImageUsageFlagBits values

    • usage must not be 0

    • sharingMode must be a valid VkSharingMode value

    • initialLayout must be a valid VkImageLayout value

    • If sharingMode is VK_SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a pointer to an array of queueFamilyIndexCount uint32_t values

    • If sharingMode is VK_SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1

    • format must not be VK_FORMAT_UNDEFINED

    • The width, height, and depth members of extent must all be greater than 0

    • mipLevels must be greater than 0

    • arrayLayers must be greater than 0

    • If imageType is VK_IMAGE_TYPE_1D, extent.width must be less than or equal to VkPhysicalDeviceLimits::maxImageDimension1D, or VkImageFormatProperties::maxExtent.width (as returned by vkGetPhysicalDeviceImageFormatProperties with format, type, tiling, usage and flags equal to those in this structure) - whichever is higher

    • If imageType is VK_IMAGE_TYPE_2D and flags does not contain VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, extent.width and extent.height must be less than or equal to VkPhysicalDeviceLimits::maxImageDimension2D, or VkImageFormatProperties::maxExtent.width/height (as returned by vkGetPhysicalDeviceImageFormatProperties with format, type, tiling, usage and flags equal to those in this structure) - whichever is higher

    • If imageType is VK_IMAGE_TYPE_2D and flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, extent.width and extent.height must be less than or equal to VkPhysicalDeviceLimits::maxImageDimensionCube, or VkImageFormatProperties::maxExtent.width/height (as returned by vkGetPhysicalDeviceImageFormatProperties with format, type, tiling, usage and flags equal to those in this structure) - whichever is higher

    • If imageType is VK_IMAGE_TYPE_2D and flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, extent.width and extent.height must be equal

    • If imageType is VK_IMAGE_TYPE_3D, extent.width, extent.height and extent.depth must be less than or equal to VkPhysicalDeviceLimits::maxImageDimension3D, or VkImageFormatProperties::maxExtent.width/height/depth (as returned by vkGetPhysicalDeviceImageFormatProperties with format, type, tiling, usage and flags equal to those in this structure) - whichever is higher

    • If imageType is VK_IMAGE_TYPE_1D, both extent.height and extent.depth must be 1

    • If imageType is VK_IMAGE_TYPE_2D, extent.depth must be 1

    • mipLevels must be less than or equal to [ $loor + 1$ ]

    • If any of extent.width, extent.height or extent.depth are greater than the equivalently named members of VkPhysicalDeviceLimits::maxImageDimension3D, mipLevels must be less than or equal to VkImageFormatProperties::maxMipLevels (as returned by vkGetPhysicalDeviceImageFormatProperties with format, type, tiling, usage and flags equal to those in this structure)

    • arrayLayers must be less than or equal to VkPhysicalDeviceLimits::maxImageArrayLayers, or VkImageFormatProperties::maxArrayLayers (as returned by vkGetPhysicalDeviceImageFormatProperties with format, type, tiling, usage and flags equal to those in this structure) - whichever is higher

    • samples must be a bit value that is set in VkPhysicalDeviceLimits::sampleCounts returned by vkGetPhysicalDeviceProperties, or VkImageFormatProperties::sampleCounts returned by vkGetPhysicalDeviceImageFormatProperties with format, type, tiling, usage and flags equal to those in this structure

    • If usage includes VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.width must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferWidth

    • If usage includes VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.height must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferHeight

    • If usage includes VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, samples must be a bit value that is set in VkPhysicalDeviceLimits::framebufferColorSampleCounts

    • If usage includes VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and format includes a depth aspect, samples must be a bit value that is set in VkPhysicalDeviceLimits::framebufferDepthSampleCounts

    • If usage includes VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and format includes a stencil aspect, samples must be a bit value that is set in VkPhysicalDeviceLimits::framebufferStencilSampleCounts

    • If usage includes VK_IMAGE_USAGE_SAMPLED_BIT, and format includes a color aspect, samples must be a bit value that is set in VkPhysicalDeviceLimits::sampledImageColorSampleCounts

    • If usage includes VK_IMAGE_USAGE_SAMPLED_BIT, and format includes a depth aspect, samples must be a bit value that is set in VkPhysicalDeviceLimits::sampledImageDepthSampleCounts

    • If usage includes VK_IMAGE_USAGE_SAMPLED_BIT, and format is an integer format, samples must be a bit value that is set in VkPhysicalDeviceLimits::sampledImageIntegerSampleCounts

    • If usage includes VK_IMAGE_USAGE_STORAGE_BIT, samples must be a bit value that is set in VkPhysicalDeviceLimits::storageImageSampleCounts

    • If the ETC2 texture compression feature is not enabled, format must not be VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK, VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK, VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK, VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK, VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK, VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK, VK_FORMAT_EAC_R11_UNORM_BLOCK, VK_FORMAT_EAC_R11_SNORM_BLOCK, VK_FORMAT_EAC_R11G11_UNORM_BLOCK, or VK_FORMAT_EAC_R11G11_SNORM_BLOCK

    • If the ASTC LDR texture compression feature is not enabled, format must not be VK_FORMAT_ASTC_4x4_UNORM_BLOCK, VK_FORMAT_ASTC_4x4_SRGB_BLOCK, VK_FORMAT_ASTC_5x4_UNORM_BLOCK, VK_FORMAT_ASTC_5x4_SRGB_BLOCK, VK_FORMAT_ASTC_5x5_UNORM_BLOCK, VK_FORMAT_ASTC_5x5_SRGB_BLOCK, VK_FORMAT_ASTC_6x5_UNORM_BLOCK, VK_FORMAT_ASTC_6x5_SRGB_BLOCK, VK_FORMAT_ASTC_6x6_UNORM_BLOCK, VK_FORMAT_ASTC_6x6_SRGB_BLOCK, VK_FORMAT_ASTC_8x5_UNORM_BLOCK, VK_FORMAT_ASTC_8x5_SRGB_BLOCK, VK_FORMAT_ASTC_8x6_UNORM_BLOCK, VK_FORMAT_ASTC_8x6_SRGB_BLOCK, VK_FORMAT_ASTC_8x8_UNORM_BLOCK, VK_FORMAT_ASTC_8x8_SRGB_BLOCK, VK_FORMAT_ASTC_10x5_UNORM_BLOCK, VK_FORMAT_ASTC_10x5_SRGB_BLOCK, VK_FORMAT_ASTC_10x6_UNORM_BLOCK, VK_FORMAT_ASTC_10x6_SRGB_BLOCK, VK_FORMAT_ASTC_10x8_UNORM_BLOCK, VK_FORMAT_ASTC_10x8_SRGB_BLOCK, VK_FORMAT_ASTC_10x10_UNORM_BLOCK, VK_FORMAT_ASTC_10x10_SRGB_BLOCK, VK_FORMAT_ASTC_12x10_UNORM_BLOCK, VK_FORMAT_ASTC_12x10_SRGB_BLOCK, VK_FORMAT_ASTC_12x12_UNORM_BLOCK, or VK_FORMAT_ASTC_12x12_SRGB_BLOCK

    • If the BC texture compression feature is not enabled, format must not be VK_FORMAT_BC1_RGB_UNORM_BLOCK, VK_FORMAT_BC1_RGB_SRGB_BLOCK, VK_FORMAT_BC1_RGBA_UNORM_BLOCK, VK_FORMAT_BC1_RGBA_SRGB_BLOCK, VK_FORMAT_BC2_UNORM_BLOCK, VK_FORMAT_BC2_SRGB_BLOCK, VK_FORMAT_BC3_UNORM_BLOCK, VK_FORMAT_BC3_SRGB_BLOCK, VK_FORMAT_BC4_UNORM_BLOCK, VK_FORMAT_BC4_SNORM_BLOCK, VK_FORMAT_BC5_UNORM_BLOCK, VK_FORMAT_BC5_SNORM_BLOCK, VK_FORMAT_BC6H_UFLOAT_BLOCK, VK_FORMAT_BC6H_SFLOAT_BLOCK, VK_FORMAT_BC7_UNORM_BLOCK, or VK_FORMAT_BC7_SRGB_BLOCK

    • If the multisampled storage images feature is not enabled, and usage contains VK_IMAGE_USAGE_STORAGE_BIT, samples must be VK_SAMPLE_COUNT_1_BIT

    • If the sparse bindings feature is not enabled, flags must not contain VK_IMAGE_CREATE_SPARSE_BINDING_BIT

    • If the sparse residency for 2D images feature is not enabled, and imageType is VK_IMAGE_TYPE_2D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

    • If the sparse residency for 3D images feature is not enabled, and imageType is VK_IMAGE_TYPE_3D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

    • If the sparse residency for images with 2 samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_2_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

    • If the sparse residency for images with 4 samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_4_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

    • If the sparse residency for images with 8 samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_8_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

    • If the sparse residency for images with 16 samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_16_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT

    • If tiling is VK_IMAGE_TILING_LINEAR, and VkFormatProperties::linearTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT, usage must not contain VK_IMAGE_USAGE_SAMPLED_BIT

    • If tiling is VK_IMAGE_TILING_LINEAR, and VkFormatProperties::linearTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT, usage must not contain VK_IMAGE_USAGE_STORAGE_BIT

    • If tiling is VK_IMAGE_TILING_LINEAR, and VkFormatProperties::linearTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT, usage must not contain VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

    • If tiling is VK_IMAGE_TILING_LINEAR, and VkFormatProperties::linearTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT, usage must not contain VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

    • If tiling is VK_IMAGE_TILING_OPTIMAL, and VkFormatProperties::optimalTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT, usage must not contain VK_IMAGE_USAGE_SAMPLED_BIT

    • If tiling is VK_IMAGE_TILING_OPTIMAL, and VkFormatProperties::optimalTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT, usage must not contain VK_IMAGE_USAGE_STORAGE_BIT

    • If tiling is VK_IMAGE_TILING_OPTIMAL, and VkFormatProperties::optimalTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT, usage must not contain VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

    • If tiling is VK_IMAGE_TILING_OPTIMAL, and VkFormatProperties::optimalTilingFeatures (as returned by vkGetPhysicalDeviceFormatProperties with the same value of format) does not include VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT, usage must not contain VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

    • If flags contains VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, it must also contain VK_IMAGE_CREATE_SPARSE_BINDING_BIT

SEE ALSO

vkCreateImage

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.