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 |
|
|
1D, 1, 0 |
|
|
2D, 0, 0 |
|
|
2D, 1, 0 |
|
|
2D, 0, 1 |
|
|
2D, 1, 1 |
|
|
CUBE, 0, 0 |
|
|
CUBE, 1, 0 |
|
|
3D, 0, 0 |
|
|
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 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,
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 |
|---|---|
|
|
|
|
|
|
|
|
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.