// Copyright (c) 2014-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_incremental_present.txt[]

*Last Modified Date*::
    2016-11-02
*IP Status*::
    No known IP claims.
*Contributors*::
  - Ian Elliott, Google
  - Jesse Hall, Google
  - Alon Or-bach, Samsung
  - James Jones, NVIDIA
  - Daniel Rakos, AMD
  - Ray Smith, ARM
  - Mika Isojarvi, Google
  - Jeff Juliano, NVIDIA
  - Jeff Bolz, NVIDIA

This device extension extends slink:vkQueuePresentKHR, from the
`<<VK_KHR_swapchain>>` extension, allowing an application to specify a list
of rectangular, modified regions of each image to present.
This should be used in situations where an application is only changing a
small portion of the presentable images within a swapchain, since it enables
the presentation engine to avoid wasting time presenting parts of the
surface that haven't changed.

This extension is leveraged from the +EGL_KHR_swap_buffers_with_damage+
extension.

=== New Object Types

None.

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_PRESENT_REGIONS_KHR

=== New Enums

None.

=== New Structures

  * slink:VkRectLayerKHR
  * slink:VkPresentRegionKHR
  * slink:VkPresentRegionsKHR

=== New Functions

None.

=== Examples

None.

=== Issues

1) How should we handle steroescopic-3D swapchains? We need to add a layer
for each rectangle.
One approach is to create another struct that contains the slink:VkRect2D
plus layer, and have slink:VkPresentRegionsKHR point to an array of that
struct.
Another approach is to have two parallel arrays, ptext:pRectangles and
ptext:pLayers, where ptext:pRectangles[i] and ptext:pLayers[i] must be used
together.
Which approach should we use, and if the array of a new structure, what
should that be called?

*RESOLVED*: Create a new structure, which is a slink:VkRect2D plus a layer,
and will be called slink:VkRectLayerKHR.

2) Where is the origin of the slink:VkRectLayerKHR?

*RESOLVED*: The upper left corner of the presentable image(s) of the
swapchain, per the definition of framebuffer coordinates.

3) Does the rectangular region, slink:VkRectLayerKHR, specify pixels of the
swapchain's image(s), or of the surface?

*RESOLVED*: Of the image(s).
Some presentation engines may scale the pixels of a swapchain's image(s) to
the size of the surface.
The size of the swapchain's image(s) will be consistent, where the size of
the surface may vary over time.

4) What if all of the rectangles for a given swapchain contain a width
and/or height of zero?

*RESOLVED*: The application is indicating that no pixels changed since the
last present.
The presentation engine may use such a hint and not update any pixels for
the swapchain.
However, all other semantics of flink:vkQueuePresentKHR must still be
honored, including waiting for semaphores to signal.

=== Version History

 * Revision 1, 2016-11-02 (Ian Elliott)
   - Internal revisions