VKIMAGESUBRESOURCERA(3)

NAME
VkImageSubresourceRange - Structure specifying a image subresource range

C SPECIFICATION

The VkImageSubresourceRange structure is defined as:

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

MEMBERS

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

DESCRIPTION

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. Valid Usage

    • If levelCount is not VK_REMAINING_MIP_LEVELS, levelCount must be non-zero and (baseMipLevel + levelCount) must be less than or equal to the mipLevels specified in VkImageCreateInfo when the image was created

    • If layerCount is not VK_REMAINING_ARRAY_LAYERS, layerCount must be non-zero and (baseArrayLayer + layerCount) must be less than or equal to the arrayLayers specified in VkImageCreateInfo when the image was created
Valid Usage (Implicit)

    • aspectMask must be a valid combination of VkImageAspectFlagBits values

    • aspectMask must not be 0

SEE ALSO

VkImageAspectFlags, VkImageMemoryBarrier, VkImageViewCreateInfo, vkCmdClearColorImage, vkCmdClearDepthStencilImage

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#VkImageSubresourceRange

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly.

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.