// Copyright (c) 2016-2017 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-04-28
*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 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.

=== Input Attachment Specification Example

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

Attachment 0 has the format 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,
            .inputAttachment = 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