Structures

VkAcquireNextImageInfoKHR

Structure specifying parameters of the acquire

The VkAcquireNextImageInfoKHR structure is defined as:

typedef struct VkAcquireNextImageInfoKHR {
    VkStructureType sType;
    const void* pNext;
    VkSwapchainKHR swapchain;
    uint64_t timeout;
    VkSemaphore semaphore;
    VkFence fence;
    uint32_t deviceMask;
} VkAcquireNextImageInfoKHR;
  • sType is a VkStructureType value identifying this structure.
  • pNext is NULL or a pointer to a structure extending this structure.
  • swapchain is a non-retired swapchain from which an image is 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.
  • deviceMask is a mask of physical devices for which the swapchain image will be ready to use when the semaphore or fence is signaled.

If vkAcquireNextImageKHR is used, the device mask is considered to include all physical devices in the logical device.

vkAcquireNextImage2KHR signals at most one semaphore, even if the application requests waiting for multiple physical devices to be ready via the deviceMask. However, only a single physical device can wait on that semaphore, since the semaphore becomes unsignaled when the wait succeeds. For other physical devices to wait for the image to be ready, it is necessary for the application to submit semaphore signal operation(s) to that first physical device to signal additional semaphore(s) after the wait succeeds, which the other physical device(s) can wait upon.

Valid Usage

VUID-VkAcquireNextImageInfoKHR-swapchain-01675

swapchain must not be in the retired state

VUID-VkAcquireNextImageInfoKHR-semaphore-01288

If semaphore is not VK_NULL_HANDLE, it must be unsignaled

VUID-VkAcquireNextImageInfoKHR-semaphore-01781

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

VUID-VkAcquireNextImageInfoKHR-fence-01289

If fence is not VK_NULL_HANDLE, fence must be unsignaled

VUID-VkAcquireNextImageInfoKHR-fence-10067

If fence is not VK_NULL_HANDLE, fence must not be associated with any other queue command that has not yet completed execution on that queue

VUID-VkAcquireNextImageInfoKHR-semaphore-01782

semaphore and fence must not both be equal to VK_NULL_HANDLE

VUID-VkAcquireNextImageInfoKHR-deviceMask-01290

deviceMask must be a valid device mask

VUID-VkAcquireNextImageInfoKHR-semaphore-03266

semaphore must have a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY

Valid Usage (Implicit)

VUID-VkAcquireNextImageInfoKHR-sType-sType

sType must be VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR

VUID-VkAcquireNextImageInfoKHR-semaphore-parameter

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

VUID-VkAcquireNextImageInfoKHR-fence-parameter

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

VUID-VkAcquireNextImageInfoKHR-commonparent

Each of fence, semaphore, and swapchain that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

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