vkWaitForPresent2KHR - Wait for presentation

Description

waitForPresent2KHR waits for the presentation engine to have begun presentation of the presentation request associated with the PresentWait2InfoKHR::presentId on swapchain, or for PresentWait2InfoKHR::timeout to have expired.

The wait request will complete when the timeout expires, or after the corresponding presentation request has either taken effect within the presentation engine or has been replaced without presentation.

The timing relationship between the presentation of the image to the user and the wait request completing is implementation-dependent due to variations in window system implementations.

If the swapchain becomes ERROR_OUT_OF_DATE_KHR either before or during this call, the call may either return SUCCESS (if the image was delivered to the presentation engine and may have been presented to the user) or return early with status ERROR_OUT_OF_DATE_KHR (if the image could not be presented to the user).

As an exception to the normal rules for objects which are externally synchronized, the swapchain passed to waitForPresent2KHR may be simultaneously used by other threads in calls to functions other than destroySwapchainKHR. Access to the swapchain data associated with this extension must be atomic within the implementation.

Valid Usage

• The presentWait2 feature must be enabled

• The SurfaceCapabilitiesPresentWait2KHR surface capability must be present for the underlying surface
• The swapchain must have been created with SWAPCHAIN_CREATE_PRESENT_WAIT_2_BIT_KHR bit set in the SwapchainCreateFlagBitsKHR field
• The presentId value must have been associated with a queuePresentKHR request on the swapchain which returned a non-error value

Valid Usage (Implicit)

• device must be a valid Device handle

• swapchain must be a valid SwapchainKHR handle
• pPresentWait2Info must be a valid pointer to a valid PresentWait2InfoKHR structure
• swapchain must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to swapchain must be externally synchronized

Return Codes

Success

• SUBOPTIMAL_KHR
• SUCCESS
• TIMEOUT

Failure

• ERROR_DEVICE_LOST
• ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
• ERROR_OUT_OF_DATE_KHR
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_OUT_OF_HOST_MEMORY
• ERROR_SURFACE_LOST_KHR
• ERROR_UNKNOWN
• ERROR_VALIDATION_FAILED

See Also

VK_KHR_present_wait2, Device, PresentWait2InfoKHR, SwapchainKHR

A variant of waitForPresent2KHR which makes a *safe* FFI call

VkPresentWait2InfoKHR - Structure describing parameters of a presentation wait

Valid Usage (Implicit)

See Also

VK_KHR_present_wait2, StructureType, waitForPresent2KHR

VkPhysicalDevicePresentWait2FeaturesKHR - Structure indicating support for present wait 2

Members

This structure describes the following feature:

Description

If the PhysicalDevicePresentWait2FeaturesKHR 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 PhysicalDevicePresentWait2FeaturesKHR, 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.

Valid Usage (Implicit)

See Also

VK_KHR_present_wait2, Bool32, StructureType

VkSurfaceCapabilitiesPresentWait2KHR - Structure describing presentation-wait capabilities of a surface

Description

This structure can be included in the pNext chain of SurfaceCapabilities2KHR to determine support for present-wait. If presentWait2Supported is FALSE, it indicates that waiting for presentation is not possible for this surface.

Applications must not attempt to call waitForPresent2KHR on a swapchain if presentWait2Supported is FALSE.

Valid Usage (Implicit)

See Also

VK_KHR_present_wait2, Bool32, StructureType

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

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