VKACQUIRENEXTIMAGEKH(3)

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 assocated with swapchain.

    • swapchain is the swapchain from which an image is being acquired.

    • timeout indicates 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 that is set to the index of the next image to use (i.e. an index into the array of images returned by vkGetSwapchainImagesKHR).

DESCRIPTION

VALID USAGE

    • 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 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

    • If semaphore is not VK_NULL_HANDLE it must be unsignaled

    • 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

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

SEE ALSO

VkDevice, VkFence, VkSemaphore, VkSwapchainKHR

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkAcquireNextImageKHR

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

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.