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

Image views are represented by VkImageView handles:

VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImageView)

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);

• device is the logical device that creates the image view.
• pCreateInfo is a pointer to an instance of the VkImageViewCreateInfo structure containing parameters to be used to create the image view.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.
• pView points to a VkImageView handle in which the resulting image view object is returned.

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;

• sType is the type of this structure.
• pNext is NULL or a pointer to an extension-specific structure.
• flags is reserved for future use.
• image is a VkImage on which the view will be created.
• viewType is the type of the image view.
• format is a VkFormat describing the format and type used to interpret data elements in the image.
• components specifies a remapping of color components (or of depth or stencil components after they have been converted into color components). See VkComponentMapping.
• subresourceRange is a VkImageSubresourceRange selecting the set of mipmap levels and array layers to be accessible to the view.

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

imageType = ci.imageType width = ci.extent.width height = ci.extent.height depth = ci.extent.depth arrayLayers = ci.arrayLayers samples = ci.samples where ci is the VkImageCreateInfo used to create image.

baseArrayLayer and layerCount are members of the subresourceRange member.

1D, 0, 0

imageType = VK_IMAGE_TYPE_1D width ≥ 1 height = 1 depth = 1 arrayLayers ≥ 1 samples = 1

viewType = VK_VIEW_TYPE_1D baseArrayLayer ≥ 0 layerCount = 1

1D, 1, 0

imageType = VK_IMAGE_TYPE_1D width ≥ 1 height = 1 depth = 1 arrayLayers ≥ 1 samples = 1

viewType = VK_VIEW_TYPE_1D_ARRAY baseArrayLayer ≥ 0 layerCount ≥ 1

2D, 0, 0

imageType = VK_IMAGE_TYPE_2D width ≥ 1 height ≥ 1 depth = 1 arrayLayers ≥ 1 samples = 1

viewType = VK_VIEW_TYPE_2D baseArrayLayer ≥ 0 layerCount = 1

2D, 1, 0

imageType = VK_IMAGE_TYPE_2D width ≥ 1 height ≥ 1 depth = 1 arrayLayers ≥ 1 samples = 1

viewType = VK_VIEW_TYPE_2D_ARRAY baseArrayLayer ≥ 0 layerCount ≥ 1

2D, 0, 1

imageType = VK_IMAGE_TYPE_2D width ≥ 1 height ≥ 1 depth = 1 arrayLayers ≥ 1 samples > 1

viewType = VK_VIEW_TYPE_2D baseArrayLayer ≥ 0 layerCount = 1

2D, 1, 1

imageType = VK_IMAGE_TYPE_2D width ≥ 1 height ≥ 1 depth = 1 arrayLayers ≥ 1 samples > 1

viewType = VK_VIEW_TYPE_2D_ARRAY baseArrayLayer ≥ 0 layerCount ≥ 1

CUBE, 0, 0

imageType = VK_IMAGE_TYPE_2D width ≥ 1 height = width depth = 1 arrayLayers ≥ 6 samples = 1 flags includes VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT

viewType = VK_VIEW_TYPE_CUBE baseArrayLayer ≥ 0 layerCount = 6

CUBE, 1, 0

imageType = VK_IMAGE_TYPE_2D width ≥ 1 height = width depth = 1 N ≥ 1 arrayLayers ≥ 6 × N samples = 1 flags includes VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT

viewType = VK_VIEW_TYPE_CUBE_ARRAY baseArrayLayer ≥ 0 layerCount = 6 × N, N ≥ 1

3D, 0, 0

imageType = VK_IMAGE_TYPE_3D width ≥ 1 height ≥ 1 depth ≥ 1 arrayLayers = 1 samples = 1

viewType = VK_VIEW_TYPE_3D baseArrayLayer = 0 layerCount = 1

The VkImageSubresourceRange structure is defined as:

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

• aspectMask is a bitmask indicating which aspect(s) of the image are included in the view. See VkImageAspectFlagBits.
• baseMipLevel is the first mipmap level accessible to the view.
• levelCount is the number of mipmap levels (starting from baseMipLevel) accessible to the view.
• baseArrayLayer is the first array layer accessible to the view.
• layerCount is the number of array layers (starting from baseArrayLayer) accessible to the view.

The number of mipmap 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,
} 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, 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 VkComponentMapping structure is defined as:

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

• r determines the component value placed in the R component of the output vector.
• g determines the component value placed in the G component of the output vector.
• b determines the component value placed in the B component of the output vector.
• a determines the component value placed in the A component of the output vector.

Each of r, g, b, and a is one of the values:

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;

• VK_COMPONENT_SWIZZLE_IDENTITY: the component is set to the identity swizzle.
• VK_COMPONENT_SWIZZLE_ZERO: the component is set to zero.
• VK_COMPONENT_SWIZZLE_ONE: the component is set to either 1 or 1.0 depending on whether the type of the image view format is integer or floating-point respectively, as determined by the Format Definition section for each VkFormat.
• VK_COMPONENT_SWIZZLE_R: the component is set to the value of the R component of the image.
• VK_COMPONENT_SWIZZLE_G: the component is set to the value of the G component of the image.
• VK_COMPONENT_SWIZZLE_B: the component is set to the value of the B component of the image.
• VK_COMPONENT_SWIZZLE_A: the component is set to the value of the A component of the image.

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);

• device is the logical device that destroys the image view.
• imageView is the image view to destroy.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.