vkQueuePresentKHR

After queueing all rendering commands and transitioning the image to the correct layout, to queue an image for presentation, call:

VkResult vkQueuePresentKHR(
    VkQueue queue,
    const VkPresentInfoKHR* pPresentInfo);

• queue is a queue that is capable of presentation to the target surface’s platform on the same device as the image’s swapchain.
• pPresentInfo is a pointer to a VkPresentInfoKHR structure specifying parameters of the presentation.

The result codes VK_ERROR_OUT_OF_DATE_KHR and VK_SUBOPTIMAL_KHR have the same meaning when returned by vkQueuePresentKHR as they do when returned by vkAcquireNextImageKHR. If any swapchain member of pPresentInfo was created with VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT will be returned if that swapchain does not have exclusive full-screen access, possibly for implementation-specific reasons outside of the application’s control. If multiple swapchains are presented, the result code is determined by applying the following rules in order:

• If the device is lost, VK_ERROR_DEVICE_LOST is returned.
• If any of the target surfaces are no longer available the error VK_ERROR_SURFACE_LOST_KHR is returned.
• If any of the presents would have a result of VK_ERROR_OUT_OF_DATE_KHR if issued separately then VK_ERROR_OUT_OF_DATE_KHR is returned.
• If any of the presents would have a result of VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT if issued separately then VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT is returned.
• If any of the presents would have a result of VK_SUBOPTIMAL_KHR if issued separately then VK_SUBOPTIMAL_KHR is returned.
• Otherwise VK_SUCCESS is returned.

Any writes to memory backing the images referenced by the pImageIndices and pSwapchains members of pPresentInfo, that are available before vkQueuePresentKHR is executed, are automatically made visible to the read access performed by the presentation engine. This automatic visibility operation for an image happens-after the semaphore signal operation, and happens-before the presentation engine accesses the image.

Presentation is a read-only operation that will not affect the content of the presentable images. Upon reacquiring the image and transitioning it away from the VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout, the contents will be the same as they were prior to transitioning the image to the present source layout and presenting 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:.

Calls to vkQueuePresentKHR may block, but must return in finite time. The processing of the presentation happens in issue order with other queue operations, but semaphores must be used to ensure that prior rendering and other commands in the specified queue complete before the presentation begins. The presentation command itself does not delay processing of subsequent commands on the queue. However, presentation requests sent to a particular queue are always performed in order. Exact presentation timing is controlled by the semantics of the presentation engine and native platform in use.

If an image is presented to a swapchain created from a display surface, the mode of the associated display will be updated, if necessary, to match the mode specified when creating the display surface. The mode switch and presentation of the specified image will be performed as one atomic operation.

Queueing an image for presentation defines a set of queue operations, including waiting on the semaphores and submitting a presentation request to the presentation engine. However, the scope of this set of queue operations does not include the actual processing of the image by the presentation engine.

If vkQueuePresentKHR fails to enqueue the corresponding set of queue operations, it may return VK_ERROR_OUT_OF_HOST_MEMORY or VK_ERROR_OUT_OF_DEVICE_MEMORY. If it does, the implementation must ensure that the state and contents of any resources or synchronization primitives referenced is unaffected by the call or its failure.

If vkQueuePresentKHR fails in such a way that the implementation is unable to make that guarantee, the implementation must return VK_ERROR_DEVICE_LOST.

However, if the presentation request is rejected by the presentation engine with an error VK_ERROR_OUT_OF_DATE_KHR, VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT, or VK_ERROR_SURFACE_LOST_KHR, the set of queue operations are still considered to be enqueued and thus any semaphore wait operation specified in VkPresentInfoKHR will execute when the corresponding queue operation is complete.

vkQueuePresentKHR releases the acquisition of the images referenced by imageIndices. The queue family corresponding to the queue vkQueuePresentKHR is executed on must have ownership of the presented images as defined in Resource Sharing. vkQueuePresentKHR does not alter the queue family ownership, but the presented images must not be used again before they have been reacquired using vkAcquireNextImageKHR.