vkWaitForFences(3)

# vkWaitForFences(3) Manual Page

## Name

vkWaitForFences - Wait for one or more fences to become signaled

Loading… please wait.

## C Specification

To wait for one or more fences to enter the signaled state on the host, call:

    // Provided by VK_VERSION_1_0
    VkResult vkWaitForFences(
        VkDevice                                    device,
        uint32_t                                    fenceCount,
        const VkFence*                              pFences,
        VkBool32                                    waitAll,
        uint64_t                                    timeout);

## Parameters

- `device` is the logical device that owns the fences.

- `fenceCount` is the number of fences to wait on.

- `pFences` is a pointer to an array of `fenceCount` fence handles.

- `waitAll` is the condition that must be satisfied to successfully unblock the wait. If `waitAll` is `VK_TRUE`, then the condition is that all fences in `pFences` are signaled. Otherwise, the condition is that at least one fence in `pFences` is signaled.

- `timeout` is the timeout period in units of nanoseconds. `timeout` is adjusted to the closest value allowed by the implementation-dependent timeout accuracy, which may be substantially longer than one nanosecond, and may be longer than the requested period.

## Description

If the condition is satisfied when `vkWaitForFences` is called, then `vkWaitForFences` returns immediately. If the condition is not satisfied at the time `vkWaitForFences` is called, then `vkWaitForFences` will block and wait until the condition is satisfied or the `timeout` has expired, whichever is sooner.

If `timeout` is zero, then `vkWaitForFences` does not wait, but simply returns the current state of the fences. `VK_TIMEOUT` will be returned in this case if the condition is not satisfied, even though no actual wait was performed.

If the condition is satisfied before the `timeout` has expired, `vkWaitForFences` returns `VK_SUCCESS`. Otherwise, `vkWaitForFences` returns `VK_TIMEOUT` after the `timeout` has expired.

If device loss occurs (see Lost Device) before the timeout has expired, `vkWaitForFences` must return in finite time with either `VK_SUCCESS` or `VK_ERROR_DEVICE_LOST`.

| Note While we guarantee that `vkWaitForFences` must return in finite time, no guarantees are made that it returns immediately upon device loss. However, the client can reasonably expect that the delay will be on the order of seconds and that calling `vkWaitForFences` will not result in a permanently (or seemingly permanently) dead process.

Valid Usage (Implicit)

- VUID-vkWaitForFences-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkWaitForFences-pFences-parameter
  `pFences` must be a valid pointer to an array of `fenceCount` valid VkFence handles

- VUID-vkWaitForFences-fenceCount-arraylength
  `fenceCount` must be greater than `0`

- VUID-vkWaitForFences-pFences-parent
  Each element of `pFences` must have been created, allocated, or retrieved from `device`

Return Codes

On success, this command returns

  - `VK_SUCCESS`

  - `VK_TIMEOUT`

On failure, this command returns

  - `VK_ERROR_OUT_OF_HOST_MEMORY`

  - `VK_ERROR_OUT_OF_DEVICE_MEMORY`

  - `VK_ERROR_DEVICE_LOST`

## See Also

`VkBool32`, VkDevice, VkFence

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