registry/vulkan/chapters/VK_KHR_incremental_present/wsi.txt

// Copyright 2014-2021 The Khronos Group, Inc.
//
// SPDX-License-Identifier: CC-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 adding a sname:VkPresentRegionsKHR
structure to the pname:pNext chain of the sname:VkPresentInfoKHR structure.

The sname:VkPresentRegionsKHR structure is defined as:

include::{generated}/api/structs/VkPresentRegionsKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    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 included in the pname:pNext chain of this
    sname:VkPresentRegionsKHR structure
****

include::{generated}/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::{generated}/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.
    The rectangles must: be specified relative to
    slink:VkSurfaceCapabilitiesKHR::pname:currentTransform, regardless of
    the swapchain's pname:preTransform.
    The presentation engine will apply the pname:preTransform transformation
    to the rectangles, along with any further transformation it applies to
    the image content.

include::{generated}/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::{generated}/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.

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.

.Valid Usage
****
  * [[VUID-VkRectLayerKHR-offset-04864]]
    The sum of pname:offset and pname:extent, after being transformed
    according to the pname:preTransform member of the
    slink:VkSwapchainCreateInfoKHR structure, must: be no greater than the
    pname:imageExtent member of the slink:VkSwapchainCreateInfoKHR structure
    passed to flink:vkCreateSwapchainKHR
  * [[VUID-VkRectLayerKHR-layer-01262]]
    pname:layer must: be less than the pname:imageArrayLayers member of the
    slink:VkSwapchainCreateInfoKHR structure passed to
    flink:vkCreateSwapchainKHR
****

include::{generated}/validity/structs/VkRectLayerKHR.txt[]
--