1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
// Copyright 2014-2024 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 `apiext: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.adoc[]
* pname:sType is a elink:VkStructureType value identifying 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.adoc[]
--
[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.adoc[]
* 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.adoc[]
--
[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.adoc[]
* 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.adoc[]
--
|
