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.