// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

VkImageSubresourceRange(3)
==========================

Name
----
VkImageSubresourceRange - Structure specifying a image subresource range

C Specification
---------------

// refBegin VkImageSubresourceRange - Structure specifying a image subresource range

The sname:VkImageSubresourceRange structure is defined as:

include::../api/structs/VkImageSubresourceRange.txt[]


Members
-------

  * pname:aspectMask is a bitmask indicating which aspect(s) of the image
    are included in the view. See elink:VkImageAspectFlagBits.
  * pname:baseMipLevel is the first mipmap level accessible to the view.
  * pname:levelCount is the number of mipmap levels (starting from
    pname:baseMipLevel) accessible to the view.
  * pname:baseArrayLayer is the first array layer accessible to the view.
  * pname:layerCount is the number of array layers (starting from
    pname:baseArrayLayer) accessible to the view.


Description
-----------

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 pname:baseMipLevel or
pname:baseArrayLayer, it can: set pname:levelCount and pname:layerCount to
the special values ename:VK_REMAINING_MIP_LEVELS and
ename: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 pname: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 _pname:layerCount / 6_,
and image array layer _pname:baseArrayLayer + i_ is face index _i mod 6_ of
cube _i / 6_. If the number of layers in the view, whether set explicitly in
pname:layerCount or implied by ename:VK_REMAINING_ARRAY_LAYERS, is not a
multiple of 6, behavior when indexing the last cube is undefined.

pname:aspectMask is a bitmask indicating the format being used. Bits which
may: be set include:

// refBegin VkImageAspectFlagBits - Bitmask specifying which aspects of an image are included in a view
include::../api/enums/VkImageAspectFlagBits.txt[]

The mask must: be only ename:VK_IMAGE_ASPECT_COLOR_BIT,
ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT if
pname:format is a color, depth-only or stencil-only format, respectively. If
using a depth/stencil format with both depth and stencil components,
pname:aspectMask must: include at least one of
ename:VK_IMAGE_ASPECT_DEPTH_BIT and ename: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 pname: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
pname:aspectMask is ignored and both depth and stencil image subresources
are used.

The pname:components member is of type slink: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.

include::../validity/structs/VkImageSubresourceRange.txt[]


See Also
--------

elink:VkImageAspectFlags, slink:VkImageMemoryBarrier, slink:VkImageViewCreateInfo, flink:vkCmdClearColorImage, flink: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.

include::footer.txt[]