vkCreateImageView - Create an image view from an existing image

Parameters

• device is the logical device that creates the image view.

• pCreateInfo is a pointer to a ImageViewCreateInfo structure containing parameters to be used to create the image view.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.
• pView is a pointer to a ImageView handle in which the resulting image view object is returned.

Valid Usage (Implicit)

• device must be a valid Device handle

• pCreateInfo must be a valid pointer to a valid ImageViewCreateInfo structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pView must be a valid pointer to a ImageView handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

AllocationCallbacks, Device, ImageView, ImageViewCreateInfo

A convenience wrapper to make a compatible pair of calls to createImageView and destroyImageView

To ensure that destroyImageView is always called: pass bracket (or the allocate function from your favourite resource management library) as the first argument. To just extract the pair pass (,) as the first argument.

vkDestroyImageView - Destroy an image view object

Parameters

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

Valid Usage

• All submitted commands that refer to imageView must have completed execution

• If AllocationCallbacks were provided when imageView was created, a compatible set of callbacks must be provided here
• If no AllocationCallbacks were provided when imageView was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid Device handle

• If imageView is not NULL_HANDLE, imageView must be a valid ImageView handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• If imageView is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to imageView must be externally synchronized

See Also

AllocationCallbacks, Device, ImageView

VkComponentMapping - Structure specifying a color component mapping

Valid Usage (Implicit)

See Also

AndroidHardwareBufferFormatPropertiesANDROID, ComponentSwizzle, ImageViewCreateInfo, SamplerYcbcrConversionCreateInfo

VkImageViewCreateInfo - Structure specifying parameters of a newly created image view

Description

Some of the image creation parameters are inherited by the view. In particular, image view creation inherits the implicit parameter usage specifying the allowed usages of the image view that, by default, takes the value of the corresponding usage parameter specified in ImageCreateInfo at image creation time. If the image was has a depth-stencil format and was created with a ImageStencilUsageCreateInfo structure included in the pNext chain of ImageCreateInfo, the usage is calculated based on the subresource.aspectMask provided:

• If aspectMask includes only IMAGE_ASPECT_STENCIL_BIT, the implicit usage is equal to ImageStencilUsageCreateInfo::stencilUsage.
• If aspectMask includes only IMAGE_ASPECT_DEPTH_BIT, the implicit usage is equal to ImageCreateInfo::usage.
• If both aspects are included in aspectMask, the implicit usage is equal to the intersection of ImageCreateInfo::usage and ImageStencilUsageCreateInfo::stencilUsage. The implicit usage can be overriden by adding a ImageViewUsageCreateInfo structure to the pNext chain.

If image was created with the IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, and if the format of the image is not multi-planar, format can be different from the image’s format, but if image was created without the IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and they are not equal they must be compatible. Image format compatibility is defined in the Format Compatibility Classes section. Views of compatible formats will have the same mapping between texel coordinates and memory locations irrespective of the format, with only the interpretation of the bit pattern changing.

Note

Values intended to be used with one view format may not be exactly preserved when written or read through a different format. For example, an integer value that happens to have the bit pattern of a floating point denorm or NaN may be flushed or canonicalized when written or read through a view with a floating point format. Similarly, a value written through a signed normalized format that has a bit pattern exactly equal to -2b may be changed to -2b + 1 as described in Conversion from Normalized Fixed-Point to Floating-Point.

If image was created with the IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, format must be compatible with the image’s format as described above, or must be an uncompressed format in which case it must be size-compatible with the image’s format, as defined for copying data between images In this case the resulting image view’s texel dimensions equal the dimensions of the selected mip level divided by the compressed texel block size and rounded up.

If the image view is to be used with a sampler which supports sampler Y′CBCR conversion, an identically defined object of type SamplerYcbcrConversion to that used to create the sampler must be passed to createImageView in a SamplerYcbcrConversionInfo included in the pNext chain of ImageViewCreateInfo. Conversely, if a SamplerYcbcrConversion object is passed to createImageView, an identically defined SamplerYcbcrConversion object must be used when sampling the image.

If the image has a multi-planar format and subresourceRange.aspectMask is IMAGE_ASPECT_COLOR_BIT, format must be identical to the image format, and the sampler to be used with the image view must enable sampler Y′CBCR conversion.

If image was created with the IMAGE_CREATE_MUTABLE_FORMAT_BIT and the image has a multi-planar format, and if subresourceRange.aspectMask is IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or IMAGE_ASPECT_PLANE_2_BIT, format must be compatible with the corresponding plane of the image, and the sampler to be used with the image view must not enable sampler Y′CBCR conversion. The width and height of the single-plane image view must be derived from the multi-planar image’s dimensions in the manner listed for plane compatibility for the plane.

Any view of an image plane will have the same mapping between texel coordinates and memory locations as used by the channels of the color aspect, subject to the formulae relating texel coordinates to lower-resolution planes as described in Chroma Reconstruction. That is, if an R or B plane has a reduced resolution relative to the G plane of the multi-planar image, the image view operates using the (uplane, vplane) unnormalized coordinates of the reduced-resolution plane, and these coordinates access the same memory locations as the (ucolor, vcolor) unnormalized coordinates of the color aspect for which chroma reconstruction operations operate on the same (uplane, vplane) or (iplane, jplane) coordinates.

Image and image view parameter compatibility requirements

Valid Usage

• If image was not created with IMAGE_CREATE_CUBE_COMPATIBLE_BIT then viewType must not be IMAGE_VIEW_TYPE_CUBE or IMAGE_VIEW_TYPE_CUBE_ARRAY

• If the image cubemap arrays feature is not enabled, viewType must not be IMAGE_VIEW_TYPE_CUBE_ARRAY
• If image was created with IMAGE_TYPE_3D but without IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set then viewType must not be IMAGE_VIEW_TYPE_2D or IMAGE_VIEW_TYPE_2D_ARRAY
• image must have been created with a usage value containing at least one of IMAGE_USAGE_SAMPLED_BIT, IMAGE_USAGE_STORAGE_BIT, IMAGE_USAGE_COLOR_ATTACHMENT_BIT, IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, IMAGE_USAGE_INPUT_ATTACHMENT_BIT, IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, or IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
• The format features of the resultant image view must contain at least one bit
• If usage contains IMAGE_USAGE_SAMPLED_BIT, then the format features of the resultant image view must contain FORMAT_FEATURE_SAMPLED_IMAGE_BIT
• If usage contains IMAGE_USAGE_STORAGE_BIT, then the image view’s format features must contain FORMAT_FEATURE_STORAGE_IMAGE_BIT
• If usage contains IMAGE_USAGE_COLOR_ATTACHMENT_BIT, then the image view’s format features must contain FORMAT_FEATURE_COLOR_ATTACHMENT_BIT
• If usage contains IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, then the image view’s format features must contain FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT
• If usage contains IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then the image view’s format features must contain at least one of FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT
• subresourceRange.baseMipLevel must be less than the mipLevels specified in ImageCreateInfo when image was created
• If subresourceRange.levelCount is not REMAINING_MIP_LEVELS, subresourceRange.baseMipLevel + subresourceRange.levelCount must be less than or equal to the mipLevels specified in ImageCreateInfo when image was created
• If image was created with usage containing IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, subresourceRange.levelCount must be 1
• If image is not a 3D image created with IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or viewType is not IMAGE_VIEW_TYPE_2D or IMAGE_VIEW_TYPE_2D_ARRAY, subresourceRange.baseArrayLayer must be less than the arrayLayers specified in ImageCreateInfo when image was created
• If subresourceRange.layerCount is not REMAINING_ARRAY_LAYERS, image is not a 3D image created with IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or viewType is not IMAGE_VIEW_TYPE_2D or IMAGE_VIEW_TYPE_2D_ARRAY, subresourceRange.layerCount must be non-zero and subresourceRange.baseArrayLayer + subresourceRange.layerCount must be less than or equal to the arrayLayers specified in ImageCreateInfo when image was created
• If image is a 3D image created with IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, and viewType is IMAGE_VIEW_TYPE_2D or IMAGE_VIEW_TYPE_2D_ARRAY, subresourceRange.baseArrayLayer must be less than the depth computed from baseMipLevel and extent.depth specified in ImageCreateInfo when image was created, according to the formula defined in Image Miplevel Sizing
• If subresourceRange.layerCount is not REMAINING_ARRAY_LAYERS, image is a 3D image created with IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, and viewType is IMAGE_VIEW_TYPE_2D or IMAGE_VIEW_TYPE_2D_ARRAY, subresourceRange.layerCount must be non-zero and subresourceRange.baseArrayLayer + subresourceRange.layerCount must be less than or equal to the depth computed from baseMipLevel and extent.depth specified in ImageCreateInfo when image was created, according to the formula defined in Image Miplevel Sizing
• If image was created with the IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, but without the IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, and if the format of the image is not a multi-planar format, format must be compatible with the format used to create image, as defined in Format Compatibility Classes
• If image was created with the IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, format must be compatible with, or must be an uncompressed format that is size-compatible with, the format used to create image
• If image was created with the IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, the levelCount and layerCount members of subresourceRange must both be 1
• If a ImageFormatListCreateInfo structure was included in the pNext chain of the ImageCreateInfo structure used when creating image and the viewFormatCount field of ImageFormatListCreateInfo is not zero then format must be one of the formats in ImageFormatListCreateInfo::pViewFormats
• If image was created with the IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, if the format of the image is a multi-planar format, and if subresourceRange.aspectMask is one of IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or IMAGE_ASPECT_PLANE_2_BIT, then format must be compatible with the Format for the plane of the image format indicated by subresourceRange.aspectMask, as defined in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-compatible-planes
• If image was not created with the IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, or if the format of the image is a multi-planar format and if subresourceRange.aspectMask is IMAGE_ASPECT_COLOR_BIT, format must be identical to the format used to create image
• If the pNext chain includes a SamplerYcbcrConversionInfo structure with a conversion value other than NULL_HANDLE, all members of components must have the value COMPONENT_SWIZZLE_IDENTITY
• If image is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• subresourceRange and viewType must be compatible with the image, as described in the compatibility table
• If image has an external format, format must be FORMAT_UNDEFINED
• If image has an external format, the pNext chain must include a SamplerYcbcrConversionInfo structure with a conversion object created with the same external format as image
• If image has an external format, all members of components must be COMPONENT_SWIZZLE_IDENTITY
• If image was created with usage containing IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, viewType must be IMAGE_VIEW_TYPE_2D or IMAGE_VIEW_TYPE_2D_ARRAY
• If image was created with usage containing IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, format must be FORMAT_R8_UINT
• If dynamic fragment density map feature is not enabled, flags must not contain IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT
• If dynamic fragment density map feature is not enabled and image was created with usage containing IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, flags must not contain any of IMAGE_CREATE_PROTECTED_BIT, IMAGE_CREATE_SPARSE_BINDING_BIT, IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or IMAGE_CREATE_SPARSE_ALIASED_BIT
• If the pNext chain includes a ImageViewUsageCreateInfo structure, and image was not created with a ImageStencilUsageCreateInfo structure included in the pNext chain of ImageCreateInfo, its usage member must not include any bits that were not set in the usage member of the ImageCreateInfo structure used to create image
• If the pNext chain includes a ImageViewUsageCreateInfo structure, image was created with a ImageStencilUsageCreateInfo structure included in the pNext chain of ImageCreateInfo, and subResourceRange.aspectMask includes IMAGE_ASPECT_STENCIL_BIT, the usage member of the ImageViewUsageCreateInfo instance must not include any bits that were not set in the usage member of the ImageStencilUsageCreateInfo structure used to create image
• If the pNext chain includes a ImageViewUsageCreateInfo structure, image was created with a ImageStencilUsageCreateInfo structure included in the pNext chain of ImageCreateInfo, and subResourceRange.aspectMask includes bits other than IMAGE_ASPECT_STENCIL_BIT, the usage member of the ImageViewUsageCreateInfo structure must not include any bits that were not set in the usage member of the ImageCreateInfo structure used to create image
• If viewType is IMAGE_VIEW_TYPE_CUBE and subresourceRange.layerCount is not REMAINING_ARRAY_LAYERS, subresourceRange.layerCount must be 6
• If viewType is IMAGE_VIEW_TYPE_CUBE_ARRAY and subresourceRange.layerCount is not REMAINING_ARRAY_LAYERS, subresourceRange.layerCount must be a multiple of 6
• If viewType is IMAGE_VIEW_TYPE_CUBE and subresourceRange.layerCount is REMAINING_ARRAY_LAYERS, the remaining number of layers must be 6
• If viewType is IMAGE_VIEW_TYPE_CUBE_ARRAY and subresourceRange.layerCount is REMAINING_ARRAY_LAYERS, the remaining number of layers must be a multiple of 6

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of ImageViewASTCDecodeModeEXT, ImageViewUsageCreateInfo, or SamplerYcbcrConversionInfo
• The sType value of each struct in the pNext chain must be unique
• flags must be a valid combination of ImageViewCreateFlagBits values
• image must be a valid Image handle
• viewType must be a valid ImageViewType value
• format must be a valid Format value
• components must be a valid ComponentMapping structure
• subresourceRange must be a valid ImageSubresourceRange structure

See Also

ComponentMapping, Format, Image, ImageSubresourceRange, ImageViewCreateFlags, ImageViewType, StructureType, createImageView