VkAcquireNextImageInfoKHR(3)

# VkAcquireNextImageInfoKHR(3) Manual Page

## Name

VkAcquireNextImageInfoKHR - Structure specifying parameters of the acquire

Loading… please wait.

## C Specification

The `VkAcquireNextImageInfoKHR` structure is defined as:

    // Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_swapchain
    typedef struct VkAcquireNextImageInfoKHR {
        VkStructureType    sType;
        const void*        pNext;
        VkSwapchainKHR     swapchain;
        uint64_t           timeout;
        VkSemaphore        semaphore;
        VkFence            fence;
        uint32_t           deviceMask;
    } VkAcquireNextImageInfoKHR;

## Members

- `sType` is the type of 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.

## Description

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

| Note 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 it must be unsignaled and 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-deviceMask-01291
  `deviceMask` must not be zero

- 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-pNext-pNext
  `pNext` must be `NULL`

- VUID-VkAcquireNextImageInfoKHR-swapchain-parameter
  `swapchain` must be a valid VkSwapchainKHR handle

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

## See Also

VkFence, VkSemaphore, VkStructureType, VkSwapchainKHR, vkAcquireNextImage2KHR

## 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 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0