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

Valid Usage

  • VUID-vkAcquireNextImage2KHR-swapchain-01803
    If the number of currently acquired images is greater than the difference between the number of images in the swapchain member of pAcquireInfo and the value of VkSurfaceCapabilitiesKHR::minImageCount as returned by a call to vkGetPhysicalDeviceSurfaceCapabilities2KHR with 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-2022 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0