Vulkan.Extensions.VK_EXT_swapchain_maintenance1

VkSwapchainKHR - Opaque handle to a swapchain object

Description

A swapchain is an abstraction for an array of presentable images that are associated with a surface. The presentable images are represented by Image objects created by the platform. One image (which can be an array image for multiview/stereoscopic-3D surfaces) is displayed at a time, but multiple images can be queued for presentation. An application renders to the image, and then queues the image for presentation to the surface.

A native window cannot be associated with more than one non-retired swapchain at a time. Further, swapchains cannot be created for native windows that have a non-Vulkan graphics API surface associated with them.

The presentation engine is an abstraction for the platform’s compositor or display engine.

The presentation engine may be synchronous or asynchronous with respect to the application and/or logical device.

Some implementations may use the device’s graphics queue or dedicated presentation hardware to perform presentation.

The presentable images of a swapchain are owned by the presentation engine. An application can acquire use of a presentable image from the presentation engine. Use of a presentable image must occur only after the image is returned by acquireNextImageKHR, and before it is released by queuePresentKHR. This includes transitioning the image layout and rendering commands.

An application can acquire use of a presentable image with acquireNextImageKHR. After acquiring a presentable image and before modifying it, the application must use a synchronization primitive to ensure that the presentation engine has finished reading from the image. The application can then transition the image’s layout, queue rendering commands to it, etc. Finally, the application presents the image with queuePresentKHR, which releases the acquisition of the image. The application can also release the acquisition of the image through releaseSwapchainImagesKHR, if the image is not in use by the device, and skip the present operation.

The presentation engine controls the order in which presentable images are acquired for use by the application.

This allows the platform to handle situations which require out-of-order return of images after presentation. At the same time, it allows the application to generate command buffers referencing all of the images in the swapchain at initialization time, rather than in its main loop.

See Also

VK_DEFINE_NON_DISPATCHABLE_HANDLE, VK_KHR_swapchain, AcquireNextImageInfoKHR, BindImageMemorySwapchainInfoKHR, ImageSwapchainCreateInfoKHR, PastPresentationTimingInfoEXT, PresentInfoKHR, ReleaseSwapchainImagesInfoKHR, SwapchainCalibratedTimestampInfoEXT, SwapchainCreateInfoKHR, acquireFullScreenExclusiveModeEXT, acquireNextImageKHR, createSharedSwapchainsKHR, createSwapchainKHR, destroySwapchainKHR, getLatencyTimingsNV, getPastPresentationTimingGOOGLE, getRefreshCycleDurationGOOGLE, getSwapchainCounterEXT, getSwapchainImagesKHR, getSwapchainStatusKHR, getSwapchainTimeDomainPropertiesEXT, getSwapchainTimingPropertiesEXT, latencySleepNV, queuePresentKHR, releaseFullScreenExclusiveModeEXT, setHdrMetadataEXT, setLatencyMarkerNV, setLatencySleepModeNV, setLocalDimmingAMD, setSwapchainPresentTimingQueueSizeEXT, waitForPresent2KHR, waitForPresentKHR

VkPhysicalDeviceSwapchainMaintenance1FeaturesKHR - Structure describing whether implementation supports swapchain maintenance1 functionality

Members

This structure describes the following feature:

Description

If the PhysicalDeviceSwapchainMaintenance1FeaturesKHR structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. If the application wishes to use a Device with any features described by PhysicalDeviceSwapchainMaintenance1FeaturesKHR, it must add an instance of the structure, with the desired feature members set to TRUE, to the pNext chain of DeviceCreateInfo when creating the Device.

Structure Chaining

Extends the structures

• DeviceCreateInfo

• PhysicalDeviceFeatures2

See Also

VK_EXT_swapchain_maintenance1, VK_KHR_swapchain_maintenance1, Bool32, StructureType

VkSwapchainPresentFenceInfoKHR - Fences associated with a vkQueuePresentKHR operation

Description

The set of queue operations defined by queuing an image for presentation, as well as operations performed by the presentation engine, access the payloads of objects associated with the presentation operation. The associated objects include:

• The swapchain image, its implicitly bound memory, and any other resources bound to that memory.

• The wait semaphores specified when queuing the image for presentation.

The application can provide a fence that the implementation will signal after all such queue operations have completed, and after the presentation engine has taken a reference to the payloads of all objects provided in PresentInfoKHR that the presentation engine accesses as part of the present operation. The fence may not wait for the present operation to complete. For all binary wait semaphores imported by the presentation engine using the equivalent of reference transference, as described in Importing Semaphore Payloads, this fence must not signal until all such semaphore payloads have been reset by the presentation engine.

The application can destroy the wait semaphores associated with a given presentation operation when at least one of the associated fences is signaled, and can destroy the swapchain when the fences associated with all past presentation requests referring to that swapchain have signaled.

Fences associated with presentations to the same swapchain on the same Queue must be signaled in the same order as the present operations.

To specify a fence for each swapchain in a present operation, include the SwapchainPresentFenceInfoKHR structure in the pNext chain of the PresentInfoKHR structure.

Valid Usage

• swapchainCount must be equal to PresentInfoKHR::swapchainCount

• Each element of pFences that is not NULL_HANDLE must be unsignaled

• Each element of pFences that is not NULL_HANDLE must not be associated with any other queue command that has not yet completed execution on that queue

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SWAPCHAIN_PRESENT_FENCE_INFO_KHR

• pFences must be a valid pointer to an array of swapchainCount valid or NULL_HANDLE Fence handles

• swapchainCount must be greater than 0

Structure Chaining

Extends the structure

• PresentInfoKHR

See Also

VK_EXT_swapchain_maintenance1, VK_KHR_swapchain_maintenance1, Fence, StructureType

VkSwapchainPresentModesCreateInfoKHR - All presentation modes usable by the swapchain

Valid Usage

• Each entry in pPresentModes must be one of the PresentModeKHR values returned by getPhysicalDeviceSurfacePresentModesKHR for the surface

• If the presentModeFifoLatestReady feature is not enabled, pPresentModes must not contain PRESENT_MODE_FIFO_LATEST_READY_KHR

• The entries in pPresentModes must be a subset of the present modes returned in SurfacePresentModeCompatibilityKHR::pPresentModes, given SwapchainCreateInfoKHR::presentMode in SurfacePresentModeKHR

• SwapchainCreateInfoKHR::presentMode must be included in pPresentModes

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODES_CREATE_INFO_KHR

• pPresentModes must be a valid pointer to an array of presentModeCount valid PresentModeKHR values

• presentModeCount must be greater than 0

Structure Chaining

Extends the structure

• SwapchainCreateInfoKHR

See Also

VK_EXT_swapchain_maintenance1, VK_KHR_swapchain_maintenance1, PresentModeKHR, StructureType

VkSwapchainPresentModeInfoKHR - Presentation modes for a vkQueuePresentKHR operation

Description

If the pNext chain of PresentInfoKHR includes a SwapchainPresentModeInfoKHR structure, then that structure defines the presentation modes used for the current and subsequent presentation operations.

When the application changes present modes with SwapchainPresentModeInfoKHR, 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.

• Transition from PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR to PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR: the presentation engine updates the shared presentable image according to the behavior of PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR.

• Transition from PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR to 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 PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR.

• Transition between PRESENT_MODE_FIFO_KHR and 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 PRESENT_MODE_IMMEDIATE_KHR to PRESENT_MODE_FIFO_KHR or PRESENT_MODE_FIFO_RELAXED_KHR or PRESENT_MODE_FIFO_LATEST_READY_KHR : As all prior present requests in the 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 PRESENT_MODE_MAILBOX_KHR to PRESENT_MODE_FIFO_KHR or PRESENT_MODE_FIFO_RELAXED_KHR or PRESENT_MODE_FIFO_LATEST_READY_KHR : Presentation in FIFO modes require waiting for the next vertical blanking period, with 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 PRESENT_MODE_FIFO_KHR or PRESENT_MODE_FIFO_RELAXED_KHR or PRESENT_MODE_FIFO_LATEST_READY_KHR to PRESENT_MODE_IMMEDIATE_KHR or 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.

• Transition between PRESENT_MODE_FIFO_KHR or PRESENT_MODE_FIFO_RELAXED_KHR, and PRESENT_MODE_FIFO_LATEST_READY_KHR: Images continue to be appended to the same FIFO queue, and the behavior with respect to waiting for vertical blanking period and dequeuing requests will follow the new mode for current and subsequent images.

• The behavior during transition between any other present modes, if possible, is implementation defined.

Valid Usage

• swapchainCount must be equal to PresentInfoKHR::swapchainCount

• Each entry in pPresentModes must be a presentation mode specified in SwapchainPresentModesCreateInfoKHR::pPresentModes when creating the entry’s corresponding swapchain

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODE_INFO_KHR

• pPresentModes must be a valid pointer to an array of swapchainCount valid PresentModeKHR values

• swapchainCount must be greater than 0

Structure Chaining

Extends the structure

• PresentInfoKHR

See Also

VK_EXT_swapchain_maintenance1, VK_KHR_swapchain_maintenance1, PresentModeKHR, StructureType

VkSwapchainPresentScalingCreateInfoKHR - Scaling behavior when presenting to the surface

Description

If scalingBehavior is 0, the result of presenting a swapchain image with dimensions that do not match the surface dimensions is implementation and platform-dependent. If presentGravityX or presentGravityY are 0, the presentation gravity must match that defined by the native platform surface on platforms which define surface gravity.

Valid Usage

• If presentGravityX is 0, presentGravityY must be 0

• If presentGravityX is not 0, presentGravityY must not be 0

• scalingBehavior must not have more than one bit set

• presentGravityX must not have more than one bit set

• presentGravityY must not have more than one bit set

• scalingBehavior must be 0 or a valid scaling method for the surface as returned in SurfacePresentScalingCapabilitiesKHR::supportedPresentScaling, given SwapchainCreateInfoKHR::presentMode in SurfacePresentModeKHR

• If the swapchain is created with SwapchainPresentModesCreateInfoKHR, scalingBehavior must be 0 or a valid scaling method for the surface as returned in SurfacePresentScalingCapabilitiesKHR::supportedPresentScaling, given each present mode in SwapchainPresentModesCreateInfoKHR::pPresentModes in SurfacePresentModeKHR

• presentGravityX must be 0 or a valid x-axis present gravity for the surface as returned in SurfacePresentScalingCapabilitiesKHR::supportedPresentGravityX, given SwapchainCreateInfoKHR::presentMode in SurfacePresentModeKHR

• If the swapchain is created with SwapchainPresentModesCreateInfoKHR, presentGravityX must be 0 or a valid x-axis present gravity for the surface as returned in SurfacePresentScalingCapabilitiesKHR::supportedPresentGravityX, given each present mode in SwapchainPresentModesCreateInfoKHR::pPresentModes in SurfacePresentModeKHR

• presentGravityY must be 0 or a valid y-axis present gravity for the surface as returned in SurfacePresentScalingCapabilitiesKHR::supportedPresentGravityY, given SwapchainCreateInfoKHR::presentMode in SurfacePresentModeKHR

• If the swapchain is created with SwapchainPresentModesCreateInfoKHR, presentGravityY must be 0 or a valid y-axis present gravity for the surface as returned in SurfacePresentScalingCapabilitiesKHR::supportedPresentGravityY, given each present mode in SwapchainPresentModesCreateInfoKHR::pPresentModes in SurfacePresentModeKHR

• If the swapchainMaintenance1 feature is not enabled, then scalingBehavior, presentGravityX, and presentGravityY must be 0

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SWAPCHAIN_PRESENT_SCALING_CREATE_INFO_KHR

• scalingBehavior must be a valid combination of PresentScalingFlagBitsKHR values

• presentGravityX must be a valid combination of PresentGravityFlagBitsKHR values

• presentGravityY must be a valid combination of PresentGravityFlagBitsKHR values

Structure Chaining

Extends the structure

• SwapchainCreateInfoKHR

See Also

VK_EXT_swapchain_maintenance1, VK_KHR_swapchain_maintenance1, PresentGravityFlagsKHR, PresentScalingFlagsKHR, StructureType

VkReleaseSwapchainImagesInfoKHR - Structure describing a list of swapchain image indices to be released

Valid Usage

• Each element of pImageIndices must be the index of a presentable image acquired from the swapchain specified by swapchain

• All uses of presentable images identified by elements of pImageIndices must have completed execution

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_RELEASE_SWAPCHAIN_IMAGES_INFO_KHR

• pNext must be NULL

• swapchain must be a valid SwapchainKHR handle

• pImageIndices must be a valid pointer to an array of imageIndexCount uint32_t values

• imageIndexCount must be greater than 0

Host Synchronization

• Host access to swapchain must be externally synchronized

See Also

VK_EXT_swapchain_maintenance1, VK_KHR_swapchain_maintenance1, StructureType, SwapchainKHR, releaseSwapchainImagesKHR, releaseSwapchainImagesKHR

vkReleaseSwapchainImagesKHR - Release previously acquired but unused images

Description

Only images that are not in use by the device can be released.

Releasing images is a read-only operation that will not affect the content of the released images. Upon reacquiring the image, the image contents and its layout will be the same as they were prior to releasing it. However, if a mechanism other than Vulkan is used to modify the platform window associated with the swapchain, the content of all presentable images in the swapchain becomes undefined.

This functionality is useful during swapchain recreation, where acquired images from the old swapchain can be released instead of presented.

Valid Usage

• Feature swapchainMaintenance1 must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pReleaseInfo must be a valid pointer to a valid ReleaseSwapchainImagesInfoKHR structure

Return Codes

Success

• SUCCESS

Failure

• ERROR_SURFACE_LOST_KHR

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_EXT_swapchain_maintenance1, VK_KHR_swapchain_maintenance1, Device, ReleaseSwapchainImagesInfoKHR

VkPresentModeKHR - Presentation mode supported for a surface

Description

• PRESENT_MODE_IMMEDIATE_KHR specifies that the presentation engine does not wait for a vertical blanking period to update the current image, meaning this mode may result in visible tearing. No internal queuing of presentation requests is needed, as the requests are applied immediately.

• PRESENT_MODE_MAILBOX_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for reuse by the application. One request is removed from the queue and processed during each vertical blanking period in which the queue is non-empty.

• PRESENT_MODE_FIFO_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty. This is the only value of presentMode that is required to be supported.

• PRESENT_MODE_FIFO_RELAXED_KHR specifies that the presentation engine generally waits for the next vertical blanking period to update the current image. If a vertical blanking period has already passed since the last update of the current image then the presentation engine does not wait for another vertical blanking period for the update, meaning this mode may result in visible tearing in this case. This mode is useful for reducing visual stutter with an application that will mostly present a new image before the next vertical blanking period, but may occasionally be late, and present a new image just after the next vertical blanking period. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during or after each vertical blanking period in which the queue is non-empty.

• PRESENT_MODE_FIFO_LATEST_READY_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue. At each vertical blanking period, the presentation engine dequeues all successive requests that are ready to be presented from the beginning of the queue. If using the VK_GOOGLE_display_timing extension or the presentAtAbsoluteTime feature to provide a target present time, the presentation engine checks the specified time for each image. If the target present time is less-than or equal-to the current time, the presentation engine dequeues the image and checks the next one. The image of the last dequeued request is presented. The other dequeued requests are dropped.

• PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine is only required to update the current image after a new presentation request is received. Therefore the application must make a presentation request whenever an update is required. However, the presentation engine may update the current image at any point, meaning this mode may result in visible tearing.

• PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine periodically updates the current image on its regular refresh cycle. The application is only required to make one initial presentation request, after which the presentation engine must update the current image without any need for further presentation requests. The application can indicate the image contents have been updated by making a presentation request, but this does not guarantee the timing of when it will be updated. This mode may result in visible tearing if rendering to the image is not timed correctly.

The supported ImageUsageFlagBits of the presentable images of a swapchain created for a surface may differ depending on the presentation mode, and can be determined as per the table below:

Presentable Image Usage Queries

For reference, the mode indicated by PRESENT_MODE_FIFO_KHR is equivalent to the behavior of {wgl|glX|egl}SwapBuffers with a swap interval of 1, while the mode indicated by PRESENT_MODE_FIFO_RELAXED_KHR is equivalent to the behavior of {wgl|glX}SwapBuffers with a swap interval of -1 (from the {WGL|GLX}_EXT_swap_control_tear extensions).

See Also

VK_KHR_surface, LatencySurfaceCapabilitiesNV, SurfacePresentModeCompatibilityKHR, SurfacePresentModeKHR, SwapchainCreateInfoKHR, SwapchainPresentModeInfoKHR, SwapchainPresentModesCreateInfoKHR, getPhysicalDeviceSurfacePresentModes2EXT, getPhysicalDeviceSurfacePresentModesKHR

VkSwapchainCreateFlagBitsKHR - Bitmask controlling swapchain creation

Description

• SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR specifies that images created from the swapchain (i.e. with the swapchain member of ImageSwapchainCreateInfoKHR set to this swapchain’s handle) must use IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT.

• SWAPCHAIN_CREATE_PROTECTED_BIT_KHR specifies that images created from the swapchain are protected images.

• SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR specifies that the images of the swapchain can be used to create a ImageView with a different format than what the swapchain was created with. The list of allowed image view formats is specified by adding a ImageFormatListCreateInfo structure to the pNext chain of SwapchainCreateInfoKHR. In addition, this flag also specifies that the swapchain can be created with usage flags that are not supported for the format the swapchain is created with but are supported for at least one of the allowed image view formats.

• SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHR specifies that the implementation may defer allocation of memory associated with each swapchain image until its index is to be returned from acquireNextImageKHR or acquireNextImage2KHR for the first time.

• SWAPCHAIN_CREATE_PRESENT_ID_2_BIT_KHR specifies that applications can include the PresentId2KHR structure in the pNext chain of the PresentInfoKHR structure to associate an identifier with each presentation request.

• SWAPCHAIN_CREATE_PRESENT_WAIT_2_BIT_KHR specifies that applications can use waitForPresent2KHR to wait for the presentation engine to have begun presentation of the presentation request associated with PresentWait2InfoKHR::presentId on swapchain.

• SWAPCHAIN_CREATE_PRESENT_TIMING_BIT_EXT specifies that features supported by the swapchain device in PhysicalDevicePresentTimingFeaturesEXT can be used to collect timing information or schedule presentation requests at specific times.

See Also

VK_KHR_swapchain, SwapchainCreateFlagsKHR

VkPresentScalingFlagBitsKHR - Bitmask specifying presentation scaling methods

Description

• PRESENT_SCALING_ONE_TO_ONE_BIT_KHR specifies that no scaling occurs, and pixels in the swapchain image are mapped to one and only one pixel in the surface. The mapping between pixels is defined by the chosen presentation gravity.

• PRESENT_SCALING_ASPECT_RATIO_STRETCH_BIT_KHR specifies that the swapchain image will be minified or magnified such that at least one of the resulting width or height is equal to the corresponding surface dimension, and the other resulting dimension is less than or equal to the corresponding surface dimension, with the aspect ratio of the resulting image being identical to that of the original swapchain image.

• PRESENT_SCALING_STRETCH_BIT_KHR specifies that the swapchain image will be minified or magnified such that the resulting image dimensions are equal to those of the surface.

See Also

VK_EXT_surface_maintenance1, VK_KHR_surface_maintenance1, PresentScalingFlagsKHR

VkPresentGravityFlagBitsKHR - Bitmask specifying presentation pixel gravity on either the x or y axis

Description

• PRESENT_GRAVITY_MIN_BIT_KHR means that the pixels will gravitate towards the top or left side of the surface.

• PRESENT_GRAVITY_MAX_BIT_KHR means that the pixels will gravitate towards the bottom or right side of the surface.

• PRESENT_GRAVITY_CENTERED_BIT_KHR means that the pixels will be centered in the surface.

If the value in SurfaceCapabilitiesKHR::currentTransform is not SURFACE_TRANSFORM_IDENTITY_BIT_KHR, it is implementation-defined whether the gravity configuration applies to the presented image before or after transformation.

See Also

VK_EXT_surface_maintenance1, VK_KHR_surface_maintenance1, PresentGravityFlagsKHR