# vkAcquireNextImageKHR(3) Manual Page

## Name

vkAcquireNextImageKHR - Retrieve the index of the next available presentable image

## C Specification

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

    VkResult vkAcquireNextImageKHR(
        VkDevice                                    device,
        VkSwapchainKHR                              swapchain,
        uint64_t                                    timeout,
        VkSemaphore                                 semaphore,
        VkFence                                     fence,
        uint32_t*                                   pImageIndex);

## Parameters

- `device` is the device associated with `swapchain`.

- `swapchain` is the non-retired swapchain from which an image is being acquired.

- `timeout` specifies how long the function waits, in nanoseconds, if no image is available.

- `semaphore` is VK_NULL_HANDLE or a semaphore to signal.

- `fence` is VK_NULL_HANDLE or a fence to signal.

- `pImageIndex` is a pointer to a `uint32_t` in which the index of the next image to use (i.e. an index into the array of images returned by `vkGetSwapchainImagesKHR`) is returned.

## Description

Valid Usage

- `swapchain` must not be in the retired state

- If `semaphore` is not VK_NULL_HANDLE it must be unsignaled

- If `semaphore` is not VK_NULL_HANDLE it must not have any uncompleted signal or wait operations pending

- If `fence` is not VK_NULL_HANDLE it must be unsignaled and must not be associated with any other queue command that has not yet completed execution on that queue

- `semaphore` and `fence` must not both be equal to VK_NULL_HANDLE

- If the number of currently acquired images is greater than the difference between the number of images in `swapchain` and the value of VkSurfaceCapabilitiesKHR::`minImageCount` as returned by a call to vkGetPhysicalDeviceSurfaceCapabilities2KHR with the `surface` used to create `swapchain`, `timeout` must not be `UINT64_MAX`

- `semaphore` must have a VkSemaphoreType of `VK_SEMAPHORE_TYPE_BINARY`

Valid Usage (Implicit)

- `device` must be a valid VkDevice handle

- `swapchain` must be a valid VkSwapchainKHR handle

- If `semaphore` is not VK_NULL_HANDLE, `semaphore` must be a valid VkSemaphore handle

- If `fence` is not VK_NULL_HANDLE, `fence` must be a valid VkFence handle

- `pImageIndex` must be a valid pointer to a `uint32_t` value

- If `semaphore` is a valid handle, it must have been created, allocated, or retrieved from `device`

- If `fence` is a valid handle, it must have been created, allocated, or retrieved from `device`

- Both of `device`, and `swapchain` that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkInstance

Host Synchronization

- Host access to `swapchain` must be externally synchronized

- Host access to `semaphore` must be externally synchronized

- Host access to `fence` must be externally synchronized

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

VkDevice, VkFence, VkSemaphore, VkSwapchainKHR

## 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 (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.