// Copyright 2019-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[open,refpage='VkSwapchainPresentModeInfoEXT',desc='Presentation modes for a vkQueuePresentKHR operation',type='structs']
--
The sname:VkSwapchainPresentModeInfoEXT structure is defined as:

include::{generated}/api/structs/VkSwapchainPresentModeInfoEXT.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:pPresentModes is a list of presentation modes with
    pname:swapchainCount entries.

If the pname:pNext chain of slink:VkPresentInfoKHR includes a
sname:VkSwapchainPresentModeInfoEXT structure, then that structure defines
the presentation modes used for the current and subsequent presentation
operations.

When the application changes present modes with
slink:VkSwapchainPresentModeInfoEXT, images that have already been queued
for presentation will continue to be presented according to the previous
present mode.
The current image being queued for presentation and subsequent images will
be presented according to the new present mode.
The behavior during the transition between the two modes is defined as
follows.

ifdef::VK_KHR_shared_presentable_image[]
  * Transition from ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR to
    ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR: the presentation engine
    updates the shared presentable image according to the behavior of
    ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR.
  * Transition from ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR to
    ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR: the presentation
    engine may: update the shared presentable image or defer that to its
    regular refresh cycle, according to the behavior of
    ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR.
endif::VK_KHR_shared_presentable_image[]
  * Transition between ename:VK_PRESENT_MODE_FIFO_KHR and
    ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR: Images continue to be appended
    to the same FIFO queue, and the behavior with respect to waiting for
    vertical blanking period will follow the new mode for current and
    subsequent images.
  * Transition from ename:VK_PRESENT_MODE_IMMEDIATE_KHR to
    ename:VK_PRESENT_MODE_FIFO_KHR or
    ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR: As all prior present requests in
    the ename:VK_PRESENT_MODE_IMMEDIATE_KHR mode are applied immediately,
    there are no outstanding present operations in this mode, and current
    and subsequent images are appended to the FIFO queue and presented
    according to the new mode.
  * Transition from ename:VK_PRESENT_MODE_MAILBOX_KHR to
    ename:VK_PRESENT_MODE_FIFO_KHR or
    ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR: Presentation in both modes
    require waiting for the next vertical blanking period, with
    ename:VK_PRESENT_MODE_MAILBOX_KHR allowing the pending present operation
    to be replaced by a new one.
    In this case, the current present operation will replace the pending
    present operation and is applied according to the new mode.
  * Transition from ename:VK_PRESENT_MODE_FIFO_KHR or
    ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR to
    ename:VK_PRESENT_MODE_IMMEDIATE_KHR or
    ename:VK_PRESENT_MODE_MAILBOX_KHR: If the FIFO queue is empty,
    presentation is done according to the behavior of the new mode.
    If there are present operations in the FIFO queue, once the last present
    operation is performed based on the respective vertical blanking period,
    the current and subsequent updates are applied according to the new
    mode.
  * The behavior during transition between any other present modes, if
    possible, is implementation defined.

.Valid Usage
****
  * [[VUID-VkSwapchainPresentModeInfoEXT-swapchainCount-07760]]
    pname:swapchainCount must: be equal to
    slink:VkPresentInfoKHR::pname:swapchainCount
  * [[VUID-VkSwapchainPresentModeInfoEXT-pPresentModes-07761]]
    Each entry in pname:pPresentModes must be a presentation mode specified
    in slink:VkSwapchainPresentModesCreateInfoEXT::pname:pPresentModes when
    creating the entry's corresponding swapchain
****

include::{generated}/validity/structs/VkSwapchainPresentModeInfoEXT.adoc[]
--