1// Copyright 2014-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[display_swapchain_present]]
6When the `apiext:VK_KHR_display_swapchain` extension is enabled, additional
7fields can: be specified when presenting an image to a swapchain by setting
8slink:VkPresentInfoKHR::pname:pNext to point to a
9slink:VkDisplayPresentInfoKHR structure.
10
11[open,refpage='VkDisplayPresentInfoKHR',desc='Structure describing parameters of a queue presentation to a swapchain',type='structs']
12--
13The sname:VkDisplayPresentInfoKHR structure is defined as:
14
15include::{generated}/api/structs/VkDisplayPresentInfoKHR.adoc[]
16
17  * pname:sType is a elink:VkStructureType value identifying this structure.
18  * pname:pNext is `NULL` or a pointer to a structure extending this
19    structure.
20  * pname:srcRect is a rectangular region of pixels to present.
21    It must: be a subset of the image being presented.
22    If sname:VkDisplayPresentInfoKHR is not specified, this region will be
23    assumed to be the entire presentable image.
24  * pname:dstRect is a rectangular region within the visible region of the
25    swapchain's display mode.
26    If sname:VkDisplayPresentInfoKHR is not specified, this region will be
27    assumed to be the entire visible region of the swapchain's mode.
28    If the specified rectangle is a subset of the display mode's visible
29    region, content from display planes below the swapchain's plane will be
30    visible outside the rectangle.
31    If there are no planes below the swapchain's, the area outside the
32    specified rectangle will be black.
33    If portions of the specified rectangle are outside of the display's
34    visible region, pixels mapping only to those portions of the rectangle
35    will be discarded.
36  * pname:persistent: If this is ename:VK_TRUE, the display engine will
37    enable buffered mode on displays that support it.
38    This allows the display engine to stop sending content to the display
39    until a new image is presented.
40    The display will instead maintain a copy of the last presented image.
41    This allows less power to be used, but may: increase presentation
42    latency.
43    If sname:VkDisplayPresentInfoKHR is not specified, persistent mode will
44    not be used.
45
46If the extent of the pname:srcRect and pname:dstRect are not equal, the
47presented pixels will be scaled accordingly.
48
49.Valid Usage
50****
51  * [[VUID-VkDisplayPresentInfoKHR-srcRect-01257]]
52    pname:srcRect must: specify a rectangular region that is a subset of the
53    image being presented
54  * [[VUID-VkDisplayPresentInfoKHR-dstRect-01258]]
55    pname:dstRect must: specify a rectangular region that is a subset of the
56    pname:visibleRegion parameter of the display mode the swapchain being
57    presented uses
58  * [[VUID-VkDisplayPresentInfoKHR-persistentContent-01259]]
59    If the pname:persistentContent member of the
60    sname:VkDisplayPropertiesKHR structure returned by
61    fname:vkGetPhysicalDeviceDisplayPropertiesKHR for the display the
62    present operation targets is ename:VK_FALSE, then pname:persistent must:
63    be ename:VK_FALSE
64****
65
66include::{generated}/validity/structs/VkDisplayPresentInfoKHR.adoc[]
67--
68