11.5. Image Views

Image objects are not directly accessed by pipeline shaders for reading or writing image data. Instead, image views representing contiguous ranges of the image subresources and containing additional metadata are used for that purpose. Views must be created on images of compatible types, and must represent a valid subset of image subresources.

The types of image views that can be created are:

 

typedef enum VkImageViewType {
    VK_IMAGE_VIEW_TYPE_1D = 0,
    VK_IMAGE_VIEW_TYPE_2D = 1,
    VK_IMAGE_VIEW_TYPE_3D = 2,
    VK_IMAGE_VIEW_TYPE_CUBE = 3,
    VK_IMAGE_VIEW_TYPE_1D_ARRAY = 4,
    VK_IMAGE_VIEW_TYPE_2D_ARRAY = 5,
    VK_IMAGE_VIEW_TYPE_CUBE_ARRAY = 6,
} VkImageViewType;

The exact image view type is partially implicit, based on the image’s type and sample count, as well as the view creation parameters as described in the table below. This table also shows which SPIR-V OpTypeImage Dim and Arrayed parameters correspond to each image view type.

To create an image view, call:

 

VkResult vkCreateImageView(
    VkDevice                                    device,
    const VkImageViewCreateInfo*                pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkImageView*                                pView);

Some of the image creation parameters are inherited by the view. The remaining parameters are contained in the pCreateInfo.

The VkImageViewCreateInfo structure is defined as:

 

typedef struct VkImageViewCreateInfo {
    VkStructureType            sType;
    const void*                pNext;
    VkImageViewCreateFlags     flags;
    VkImage                    image;
    VkImageViewType            viewType;
    VkFormat                   format;
    VkComponentMapping         components;
    VkImageSubresourceRange    subresourceRange;
} VkImageViewCreateInfo;

If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, format can be different from the image’s format, but if they are not equal they must be compatible. Image format compatibility is defined in the Format Compatibility Classes section.

Table 11.1. Image and image view parameter compatibility requirements

Dim, Arrayed, MS Image parameters View parameters

1D, 0, 0

imageType = IMAGE_TYPE_1D width >= 1 height = 1 depth = 1 arrayLayers >= 1 samples = 1

viewType = VIEW_TYPE_1D baseArrayLayer >= 0 arrayLayers = 1

1D, 1, 0

imageType = IMAGE_TYPE_1D width >= 1 height = 1 depth = 1 arrayLayers >= 1 samples = 1

viewType = VIEW_TYPE_1D_ARRAY baseArrayLayer >= 0 arrayLayers >= 1

2D, 0, 0

imageType = IMAGE_TYPE_2D width >= 1 height >= 1 depth = 1 arrayLayers >= 1 samples = 1

viewType = VIEW_TYPE_2D baseArrayLayer >= 0 arrayLayers = 1

2D, 1, 0

imageType = IMAGE_TYPE_2D width >= 1 height >= 1 depth = 1 arrayLayers >= 1 samples = 1

viewType = VIEW_TYPE_2D_ARRAY baseArrayLayer >= 0 arrayLayers >= 1

2D, 0, 1

imageType = IMAGE_TYPE_2D width >= 1 height >= 1 depth = 1 arrayLayers >= 1 samples > 1

viewType = VIEW_TYPE_2D baseArrayLayer >= 0 arrayLayers = 1

2D, 1, 1

imageType = IMAGE_TYPE_2D width >= 1 height >= 1 depth = 1 arrayLayers >= 1 samples > 1

viewType = VIEW_TYPE_2D_ARRAY baseArrayLayer >= 0 arrayLayers >= 1

CUBE, 0, 0

imageType = IMAGE_TYPE_2D width >= 1 height = width depth = 1 arrayLayers >= 6 samples = 1 flags include VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT

viewType = VIEW_TYPE_CUBE baseArrayLayer >= 0 arrayLayers = 6

CUBE, 1, 0

imageType = IMAGE_TYPE_2D width >= 1 height = width depth = 1 arrayLayers >= 6×N samples = 1 flags include VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT

viewType = VIEW_TYPE_CUBE_ARRAY baseArrayLayer >= 0 arrayLayers = 6×N

3D, 0, 0

imageType = IMAGE_TYPE_3D width >= 1 height >= 1 depth >= 1 arrayLayers = 1 samples = 1

viewType = VIEW_TYPE_3D baseArrayLayer = 0 arrayLayers = 1


The subresourceRange member is of type VkImageSubresourceRange.

The VkImageSubresourceRange structure is defined as:

 

typedef struct VkImageSubresourceRange {
    VkImageAspectFlags    aspectMask;
    uint32_t              baseMipLevel;
    uint32_t              levelCount;
    uint32_t              baseArrayLayer;
    uint32_t              layerCount;
} VkImageSubresourceRange;

The number of mip-map levels and array layers must be a subset of the image subresources in the image. If an application wants to use all mip-levels or layers in an image after the baseMipLevel or baseArrayLayer, it can set levelCount and layerCount to the special values VK_REMAINING_MIP_LEVELS and VK_REMAINING_ARRAY_LAYERS without knowing the exact number of mip-levels or layers.

For cube and cube array image views, the layers of the image view starting at baseArrayLayer correspond to faces in the order +X, -X, +Y, -Y, +Z, -Z. For cube arrays, each set of six sequential layers is a single cube, so the number of cube maps in a cube map array view is layerCount / 6, and image array layer baseArrayLayer + i is face index i mod 6 of cube i / 6. If the number of layers in the view, whether set explicitly in layerCount or implied by VK_REMAINING_ARRAY_LAYERS, is not a multiple of 6, behavior when indexing the last cube is undefined.

aspectMask is a bitmask indicating the format being used. Bits which may be set include:

 

typedef enum VkImageAspectFlagBits {
    VK_IMAGE_ASPECT_COLOR_BIT = 0x00000001,
    VK_IMAGE_ASPECT_DEPTH_BIT = 0x00000002,
    VK_IMAGE_ASPECT_STENCIL_BIT = 0x00000004,
    VK_IMAGE_ASPECT_METADATA_BIT = 0x00000008,
} VkImageAspectFlagBits;

The mask must be only VK_IMAGE_ASPECT_COLOR_BIT, VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT if format is a color, depth-only or stencil-only format, respectively. If using a depth/stencil format with both depth and stencil components, aspectMask must include at least one of VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT, and can include both.

When using an imageView of a depth/stencil image to populate a descriptor set (e.g. for sampling in the shader, or for use as an input attachment), the aspectMask must only include one bit and selects whether the imageView is used for depth reads (i.e. using a floating-point sampler or input attachment in the shader) or stencil reads (i.e. using an unsigned integer sampler or input attachment in the shader). When an imageView of a depth/stencil image is used as a depth/stencil framebuffer attachment, the aspectMask is ignored and both depth and stencil image subresources are used.

The components member is of type VkComponentMapping.

The VkComponentMapping structure is defined as:

 

typedef struct VkComponentMapping {
    VkComponentSwizzle    r;
    VkComponentSwizzle    g;
    VkComponentSwizzle    b;
    VkComponentSwizzle    a;
} VkComponentMapping;

and describes a remapping from components of the image to components of the vector returned by shader image instructions. This remapping must be identity for storage image descriptors, input attachment descriptors, and framebuffer attachments. The r, g, b, and a members of components are the values placed in the corresponding components of the output vector:

 

typedef enum VkComponentSwizzle {
    VK_COMPONENT_SWIZZLE_IDENTITY = 0,
    VK_COMPONENT_SWIZZLE_ZERO = 1,
    VK_COMPONENT_SWIZZLE_ONE = 2,
    VK_COMPONENT_SWIZZLE_R = 3,
    VK_COMPONENT_SWIZZLE_G = 4,
    VK_COMPONENT_SWIZZLE_B = 5,
    VK_COMPONENT_SWIZZLE_A = 6,
} VkComponentSwizzle;

Setting the identity swizzle on a component is equivalent to setting the identity mapping on that component. That is:

Table 11.2. Component Mappings Equivalent To VK_COMPONENT_SWIZZLE_IDENTITY

Component Identity Mapping

components.r

VK_COMPONENT_SWIZZLE_R

components.g

VK_COMPONENT_SWIZZLE_G

components.b

VK_COMPONENT_SWIZZLE_B

components.a

VK_COMPONENT_SWIZZLE_A


To destroy an image view, call:

 

void vkDestroyImageView(
    VkDevice                                    device,
    VkImageView                                 imageView,
    const VkAllocationCallbacks*                pAllocator);