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

include::meta/VK_KHR_maintenance2.txt[]

*Last Modified Date*::
    2017-09-05
*Interactions and External Dependencies*::
  - Promoted to Vulkan 1.1 Core
*Contributors*::
  - Michael Worcester, Imagination Technologies
  - Stuart Smith, Imagination Technologies
  - Jeff Bolz, NVIDIA
  - Daniel Koch, NVIDIA
  - Jan-Harald Fredriksen, ARM
  - Daniel Rakos, AMD
  - Neil Henning, Codeplay
  - Piers Daniell, NVIDIA

`VK_KHR_maintenance2` adds a collection of minor features that were
intentionally left out or overlooked from the original Vulkan 1.0 release.

The new features are as follows:

  * Allow the application to specify which aspect of an input attachment
    might be read for a given subpass.
  * Allow implementations to express the clipping behavior of points.
  * Allow creating images with usage flags that may not be supported for the
    base image's format, but are supported for image views of the image that
    have a different but compatible format.
  * Allow creating uncompressed image views of compressed images.
  * Allow the application to select between an upper-left and lower-left
    origin for the tessellation domain space.
  * Adds two new image layouts for depth stencil images to allow either the
    depth or stencil aspect to be read-only while the other aspect is
    writable.

=== Input Attachment Specification

Input attachment specification allows an application to specify which aspect
of a multi-aspect image (e.g. a combined depth stencil format) will be
accessed via a code:subpassLoad operation.

On some implementations there may: be a performance penalty if the
implementation does not know (at flink:vkCreateRenderPass time) which
aspect(s) of multi-aspect images can: be be accessed as input attachments.



=== New Object Types

None.

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_POINT_CLIPPING_PROPERTIES_KHR
  ** ename:VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_DOMAIN_ORIGIN_STATE_CREATE_INFO_KHR

  * Extending elink:VkImageCreateFlagBits:
  ** ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_KHR
  ** ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR

  * Extending elink:VkImageLayout
  ** ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR
  ** ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR

  * ename:VK_POINT_CLIPPING_BEHAVIOR_ALL_CLIP_PLANES_KHR
  * ename:VK_POINT_CLIPPING_BEHAVIOR_USER_CLIP_PLANES_ONLY_KHR

=== New Enums

  * slink:VkPointClippingBehaviorKHR
  * slink:VkTessellationDomainOriginKHR

=== New Structures

  * slink:VkPhysicalDevicePointClippingPropertiesKHR
  * slink:VkRenderPassInputAttachmentAspectCreateInfoKHR
  * slink:VkInputAttachmentAspectReferenceKHR
  * slink:VkImageViewUsageCreateInfoKHR
  * slink:VkPipelineTessellationDomainOriginStateCreateInfoKHR

=== New Functions

None.

=== Promotion to Vulkan 1.1

All functionality in this extension is included in core Vulkan 1.1, with the
KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.

=== Input Attachment Specification Example

Consider the case where a render pass has two subpasses and two attachments.

Attachment 0 has the format ename:VK_FORMAT_D24_UNORM_S8_UINT, attachment 1
has some color format.

Subpass 0 writes to attachment 0, subpass 1 reads only the depth information
from attachment 0 (using inputAttachmentRead) and writes to attachment 1.

[source,c++]
----------------------------------------
    VkInputAttachmentAspectReferenceKHR references[] = {
        {
            .subpass = 1,
            .inputAttachmentIndex = 0,
            .aspectMask = VK_IMAGE_ASPECT_DEPTH_BIT
        }
    };

    VkRenderPassInputAttachmentAspectCreateInfoKHR specifyAspects = {
        .sType = VK_STRUCTURE_TYPE_RENDER_PASS_INPUT_ATTACHMENT_ASPECT_CREATE_INFO_KHR,
        .pNext = NULL,
        .aspectReferenceCount = 1,
        .pAspectReferences = references
    };


    VkRenderPassCreateInfo createInfo = {
        ...
        .pNext = &specifyAspects,
        ...
    }

    vkCreateRenderPass(...);
----------------------------------------

=== Issues

1) What is the default tessellation domain origin?

*RESOLVED*: Vulkan 1.0 originally inadvertently documented a lower-left
origin, but the conformance tests and all implementations implemented an
upper-left origin.
This extension adds a control to select between lower-left (for
compatibility with OpenGL) and upper-left, and we retroactively fix
unextended Vulkan to have a default of an upper-left origin.

=== Version History

 * Revision 1, 2017-04-28