vkReleaseSwapchainImagesEXT - 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.

Note

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

Return Codes

Success

• SUCCESS

Failure

• ERROR_SURFACE_LOST_KHR

See Also

VK_EXT_swapchain_maintenance1, Device, ReleaseSwapchainImagesInfoEXT

VkPhysicalDeviceSwapchainMaintenance1FeaturesEXT - Structure describing whether implementation supports swapchain maintenance1 functionality

Members

This structure describes the following feature:

Description

If the PhysicalDeviceSwapchainMaintenance1FeaturesEXT 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. PhysicalDeviceSwapchainMaintenance1FeaturesEXT can also be used in the pNext chain of DeviceCreateInfo to selectively enable these features.

Valid Usage (Implicit)

See Also

VK_EXT_swapchain_maintenance1, Bool32, StructureType

VkSwapchainPresentFenceInfoEXT - 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 when all such queue operations have completed and the presentation engine has taken a reference to the payload of any objects it accesses as part of the present operation. 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 SwapchainPresentFenceInfoEXT structure in the pNext chain of the PresentInfoKHR structure.

Valid Usage

• swapchainCount must be equal to PresentInfoKHR::swapchainCount

• Each element of pFences must be unsignaled
• Each element of pFences 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_EXT

• pFences must be a valid pointer to an array of swapchainCount valid Fence handles
• swapchainCount must be greater than 0

See Also

VK_EXT_swapchain_maintenance1, Fence, StructureType

VkSwapchainPresentModesCreateInfoEXT - 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

• The entries in pPresentModes must be a subset of the present modes returned in SurfacePresentModeCompatibilityEXT::pPresentModes, given SwapchainCreateInfoKHR::presentMode in SurfacePresentModeEXT
• SwapchainCreateInfoKHR::presentMode must be included in pPresentModes

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODES_CREATE_INFO_EXT

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

See Also

VK_EXT_swapchain_maintenance1, PresentModeKHR, StructureType

VkSwapchainPresentModeInfoEXT - Presentation modes for a vkQueuePresentKHR operation

Description

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

When the application changes present modes with SwapchainPresentModeInfoEXT, 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: 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: Presentation in both 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 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.
• 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 SwapchainPresentModesCreateInfoEXT::pPresentModes when creating the entry’s corresponding swapchain

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SWAPCHAIN_PRESENT_MODE_INFO_EXT

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

See Also

VK_EXT_swapchain_maintenance1, PresentModeKHR, StructureType

VkSwapchainPresentScalingCreateInfoEXT - 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 a valid scaling method for the surface as returned in SurfacePresentScalingCapabilitiesEXT::supportedPresentScaling, given SwapchainCreateInfoKHR::presentMode in SurfacePresentModeEXT
• If the swapchain is created with SwapchainPresentModesCreateInfoEXT, scalingBehavior must be a valid scaling method for the surface as returned in SurfacePresentScalingCapabilitiesEXT::supportedPresentScaling, given each present mode in SwapchainPresentModesCreateInfoEXT::pPresentModes in SurfacePresentModeEXT
• presentGravityX must be a valid x-axis present gravity for the surface as returned in SurfacePresentScalingCapabilitiesEXT::supportedPresentGravityX, given SwapchainCreateInfoKHR::presentMode in SurfacePresentModeEXT
• If the swapchain is created with SwapchainPresentModesCreateInfoEXT, presentGravityX must be a valid x-axis present gravity for the surface as returned in SurfacePresentScalingCapabilitiesEXT::supportedPresentGravityX, given each present mode in SwapchainPresentModesCreateInfoEXT::pPresentModes in SurfacePresentModeEXT
• presentGravityY must be a valid y-axis present gravity for the surface as returned in SurfacePresentScalingCapabilitiesEXT::supportedPresentGravityY, given SwapchainCreateInfoKHR::presentMode in SurfacePresentModeEXT
• If the swapchain is created with SwapchainPresentModesCreateInfoEXT, presentGravityY must be a valid y-axis present gravity for the surface as returned in SurfacePresentScalingCapabilitiesEXT::supportedPresentGravityY, given each present mode in SwapchainPresentModesCreateInfoEXT::pPresentModes in SurfacePresentModeEXT

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SWAPCHAIN_PRESENT_SCALING_CREATE_INFO_EXT

• scalingBehavior must be a valid combination of PresentScalingFlagBitsEXT values
• presentGravityX must be a valid combination of PresentGravityFlagBitsEXT values
• presentGravityY must be a valid combination of PresentGravityFlagBitsEXT values

See Also

VK_EXT_swapchain_maintenance1, PresentGravityFlagsEXT, PresentScalingFlagsEXT, StructureType

VkReleaseSwapchainImagesInfoEXT - 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_EXT

• 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, StructureType, SwapchainKHR, releaseSwapchainImagesEXT

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.

Note

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 releaseSwapchainImagesEXT, 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.

Note

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_KHR_swapchain, AcquireNextImageInfoKHR, BindImageMemorySwapchainInfoKHR, ImageSwapchainCreateInfoKHR, PresentInfoKHR, ReleaseSwapchainImagesInfoEXT, SwapchainCreateInfoKHR, acquireFullScreenExclusiveModeEXT, acquireNextImageKHR, createSharedSwapchainsKHR, createSwapchainKHR, destroySwapchainKHR, getLatencyTimingsNV, getPastPresentationTimingGOOGLE, getRefreshCycleDurationGOOGLE, getSwapchainCounterEXT, getSwapchainImagesKHR, getSwapchainStatusKHR, latencySleepNV, queuePresentKHR, releaseFullScreenExclusiveModeEXT, setHdrMetadataEXT, setLatencyMarkerNV, setLatencySleepModeNV, setLocalDimmingAMD, waitForPresentKHR

VkPresentModeKHR - Presentation mode supported for a surface

Description

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

Note

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, SurfacePresentModeCompatibilityEXT, SurfacePresentModeEXT, SwapchainCreateInfoKHR, SwapchainPresentModeInfoEXT, SwapchainPresentModesCreateInfoEXT, getPhysicalDeviceSurfacePresentModes2EXT, getPhysicalDeviceSurfacePresentModesKHR

VkSwapchainCreateFlagBitsKHR - Bitmask controlling swapchain creation

See Also

VK_KHR_swapchain, SwapchainCreateFlagsKHR

VkPresentScalingFlagBitsEXT - Bitmask specifying presentation scaling methods

See Also

VK_EXT_surface_maintenance1, PresentScalingFlagsEXT

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

Description

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, PresentGravityFlagsEXT