C Specification

To acquire an available presentable image to use, and retrieve the index of that image, call:

// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
VkResult vkAcquireNextImage2KHR(
    VkDevice                                    device,
    const VkAcquireNextImageInfoKHR*            pAcquireInfo,
    uint32_t*                                   pImageIndex);

Parameters

  • device is the device associated with swapchain.

  • pAcquireInfo is a pointer to a VkAcquireNextImageInfoKHR structure containing parameters of the acquire.

  • pImageIndex is a pointer to a uint32_t that is set to the index of the next image to use.

Description

If the swapchain has been created with the VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT flag, the image whose index is returned in pImageIndex will be fully backed by memory before this call returns to the application.

Valid Usage

  • VUID-vkAcquireNextImage2KHR-surface-07784
    If forward progress cannot be guaranteed for the surface used to create swapchain, the timeout member of pAcquireInfo must not be UINT64_MAX

Valid Usage (Implicit)

  • VUID-vkAcquireNextImage2KHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkAcquireNextImage2KHR-pAcquireInfo-parameter
    pAcquireInfo must be a valid pointer to a valid VkAcquireNextImageInfoKHR structure

  • VUID-vkAcquireNextImage2KHR-pImageIndex-parameter
    pImageIndex must be a valid pointer to a uint32_t value

Return Codes
On success, this command returns

  • VK_SUCCESS

  • VK_TIMEOUT

  • VK_NOT_READY

  • VK_SUBOPTIMAL_KHR

On failure, this command returns

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

  • VK_ERROR_OUT_OF_DATE_KHR

  • VK_ERROR_SURFACE_LOST_KHR

  • VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

See Also

VK_KHR_device_group, VK_KHR_swapchain, VK_VERSION_1_1, VkAcquireNextImageInfoKHR, VkDevice

Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0