registry/vulkan/chapters/VK_KHR_incremental_present/wsi.txt

// 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/

[open,refpage='VkPresentRegionsKHR',desc='Structure hint of rectangular regions changed by vkQueuePresentKHR',type='structs']
--

When the `VK_KHR_incremental_present` extension is enabled, additional
fields can: be specified that allow an application to specify that only
certain rectangular regions of the presentable images of a swapchain are
changed.
This is an optimization hint that a presentation engine may: use to only
update the region of a surface that is actually changing.
The application still must: ensure that all pixels of a presented image
contain the desired values, in case the presentation engine ignores this
hint.
An application can: provide this hint by including the
sname:VkPresentRegionsKHR structure in the pname:pNext chain of the
sname:VkPresentInfoKHR structure.

The sname:VkPresentRegionsKHR structure is defined as:

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

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:swapchainCount is the number of swapchains being presented to by
    this command.
  * pname:pRegions is `NULL` or a pointer to an array of
    sname:VkPresentRegionKHR elements with pname:swapchainCount entries.
    If not `NULL`, each element of pname:pRegions contains the region that
    has changed since the last present to the swapchain in the corresponding
    entry in the sname:VkPresentInfoKHR::pname:pSwapchains array.

.Valid Usage
****
  * [[VUID-VkPresentRegionsKHR-swapchainCount-01260]]
    pname:swapchainCount must: be the same value as
    sname:VkPresentInfoKHR::pname:swapchainCount, where
    sname:VkPresentInfoKHR is in the pNext-chain of this
    sname:VkPresentRegionsKHR structure.
****

include::../../validity/structs/VkPresentRegionsKHR.txt[]
--

[open,refpage='VkPresentRegionKHR',desc='Structure containing rectangular region changed by vkQueuePresentKHR for a given VkImage',type='structs']
--

For a given image and swapchain, the region to present is specified by the
sname:VkPresentRegionKHR structure, which is defined as:

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

  * pname:rectangleCount is the number of rectangles in pname:pRectangles,
    or zero if the entire image has changed and should be presented.
  * pname:pRectangles is either `NULL` or a pointer to an array of
    sname:VkRectLayerKHR structures.
    The sname:VkRectLayerKHR structure is the framebuffer coordinates, plus
    layer, of a portion of a presentable image that has changed and must: be
    presented.
    If non-`NULL`, each entry in pname:pRectangles is a rectangle of the
    given image that has changed since the last image was presented to the
    given swapchain.

include::../../validity/structs/VkPresentRegionKHR.txt[]
--

[open,refpage='VkRectLayerKHR',desc='Structure containing a rectangle, including layer, changed by vkQueuePresentKHR for a given VkImage',type='structs']
--

The sname:VkRectLayerKHR structure is defined as:

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

    * pname:offset is the origin of the rectangle, in pixels.
    * pname:extent is the size of the rectangle, in pixels.
    * pname:layer is the layer of the image.
      For images with only one layer, the value of pname:layer must: be 0.

.Valid Usage
****
  * [[VUID-VkRectLayerKHR-offset-01261]]
    The sum of pname:offset and pname:extent must: be no greater than the
    pname:imageExtent member of the sname:VkSwapchainCreateInfoKHR structure
    given to flink:vkCreateSwapchainKHR.
  * [[VUID-VkRectLayerKHR-layer-01262]]
    pname:layer must: be less than pname:imageArrayLayers member of the
    sname:VkSwapchainCreateInfoKHR structure given to
    flink:vkCreateSwapchainKHR.
****

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

Some platforms allow the size of a surface to change, and then scale the
pixels of the image to fit the surface.
sname:VkRectLayerKHR specifies pixels of the swapchain's image(s), which
will be constant for the life of the swapchain.

--