VKACQUIRENEXTIMAGEKH(3)

NAME
vkAcquireNextImageKHR - retrieve the index of the next available presentable image.

C SPECIFICATION

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

PARAMETERS

device
    The VkDevice associated with the swapchain.

swapchain
    The swapchain from which an image is being acquired.

timeout
    Indicates how long the function waits, in nanoseconds.

semaphore
    A VkSemaphore that will become signaled when the presentation engine has released ownership of the image.

fence
    A VkFence that will become signaled when the presentation engine has released ownership of the image.

pImageIndex
    A pointer to an integer that is set to the index of the next image to use.

DESCRIPTION

vkAcquireNextImageKHR acquires the next image from the swapchain.

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

    • Each of swapchain, device, semaphore and fence that are valid handles must have been created, allocated or retrieved from the same VkInstance

    • 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

vkGetSwapchainImagesKHR

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.