## 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
--- | --- | ---
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 include `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 \times N$ samples = 1 flags include `VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT` | viewType = `VK_VIEW_TYPE_CUBE_ARRAY` baseArrayLayer >= 0 N >= 1 layerCount = $6 \times N$
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 {
        VkImageAspectFlags    aspectMask;
        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 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`, 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.