VKWAITFORFENCES(3)

NAME
vkWaitForFences - Wait for one or more fences to become signaled.

C SPECIFICATION

To cause the host to wait until any one or all of a group of fences is signaled, use the command:

    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 up to timeout nanoseconds for the condition to become satisfied.

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 specified timeout period expires before the condition is satisfied, vkWaitForFences returns VK_TIMEOUT. If the condition is satisfied before timeout nanoseconds has expired, vkWaitForFences returns VK_SUCCESS.

vkWaitForFences defines the second half of a memory dependency with the host, for each fence being waited on. The memory dependency defined by signaling a fence and waiting on the host does not guarantee that the results of memory accesses will be visible to the host, or that the memory is available. To provide that guarantee, the application must insert a memory barrier between the device writes and the end of the submission that will signal the fence, with dstAccessMask having the VK_ACCESS_HOST_READ_BIT bit set, with dstStageMask having the VK_PIPELINE_STAGE_HOST_BIT bit set, and with the appropriate srcStageMask and srcAccessMask members set to guarantee completion of the writes. If the memory was allocated without the VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, then vkInvalidateMappedMemoryRanges must be called after the fence is signaled in order to ensure the writes are visible to the host, as described in Host Access to Device Memory Objects.

VALID USAGE

    • device must be a valid VkDevice handle

    • pFences must be a pointer to an array of fenceCount valid VkFence handles

    • fenceCount must be greater than 0

    • Each element of pFences must have been created, allocated or retrieved from device

    • Each of device and the elements of pFences must have been created, allocated or retrieved from the same VkPhysicalDevice

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

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

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.