VkFenceCreateFlagBits - Bitmask specifying initial state and behavior of a fence

See Also

VkFenceCreateFlags

VK_FENCE_CREATE_SIGNALED_BIT specifies that the fence object is created in the signaled state. Otherwise, it is created in the unsignaled state.

vkCreateFence - Create a new fence object

Parameters

• device is the logical device that creates the fence.

• pCreateInfo is a pointer to an instance of the VkFenceCreateInfo structure which contains information about how the fence is to be created.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.
• pFence points to a handle in which the resulting fence object is returned.

Description

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pCreateInfo must be a valid pointer to a valid VkFenceCreateInfo structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• pFence must be a valid pointer to a VkFence handle

Return Codes

Success

- VK_SUCCESS

Failure

- VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkAllocationCallbacks, VkDevice, VkFence, VkFenceCreateInfo

vkDestroyFence - Destroy a fence object

Parameters

• device is the logical device that destroys the fence.

• fence is the handle of the fence to destroy.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Description

Valid Usage

• All queue submission commands that refer to fence must have completed execution

• If VkAllocationCallbacks were provided when fence was created, a compatible set of callbacks must be provided here
• If no VkAllocationCallbacks were provided when fence was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• If fence is not VK_NULL_HANDLE, fence must be a valid VkFence handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• If fence is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to fence must be externally synchronized

See Also

VkAllocationCallbacks, VkDevice, VkFence

vkResetFences - Resets one or more fence objects

Parameters

• device is the logical device that owns the fences.

• fenceCount is the number of fences to reset.
• pFences is a pointer to an array of fence handles to reset.

Description

If any member of pFences currently has its payload imported with temporary permanence, that fence’s prior permanent payload is first restored. The remaining operations described therefore operate on the restored payload.

When vkResetFences is executed on the host, it defines a /fence unsignal operation/ for each fence, which resets the fence to the unsignaled state.

If any member of pFences is already in the unsignaled state when vkResetFences is executed, then vkResetFences has no effect on that fence.

Valid Usage

• Each element of pFences must not be currently associated with any queue command that has not yet completed execution on that queue

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pFences must be a valid 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

Host Synchronization

• Host access to each member of pFences must be externally synchronized

Return Codes

Success

- VK_SUCCESS

Failure

- VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkDevice, VkFence

vkGetFenceStatus - Return the status of a fence

Parameters

• device is the logical device that owns the fence.

• fence is the handle of the fence to query.

Description

Upon success, vkGetFenceStatus returns the status of the fence object, with the following return codes:

+-----------------------------------+-----------------------------------+
| Status                            | Meaning                           |
+===================================+===================================+
| @VK_SUCCESS@                      | The fence specified by @fence@ is |
|                                   | signaled.                         |
+-----------------------------------+-----------------------------------+
| @VK_NOT_READY@                    | The fence specified by @fence@ is |
|                                   | unsignaled.                       |
+-----------------------------------+-----------------------------------+
| @VK_ERROR_DEVICE_LOST@            | The device has been lost. See     |
|                                   | <{html_spec_relative}#devsandqueu |
|                                   | es-lost-device Lost Device>.      |
+-----------------------------------+-----------------------------------+

Fence Object Status Codes

If a queue submission command is pending execution, then the value returned by this command may immediately be out of date.

If the device has been lost (see Lost Device), vkGetFenceStatus may return any of the above status codes. If the device has been lost and vkGetFenceStatus is called repeatedly, it will eventually return either VK_SUCCESS or VK_ERROR_DEVICE_LOST.

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• fence must be a valid VkFence handle
• fence must have been created, allocated, or retrieved from device

Return Codes

Success

- VK_SUCCESS

• VK_NOT_READY

Failure

- VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_DEVICE_LOST

See Also

VkDevice, VkFence

vkWaitForFences - Wait for one or more fences to become signaled

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.

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)

• device must be a valid VkDevice handle

• pFences must be a valid 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

Return Codes

Success

- VK_SUCCESS

• VK_TIMEOUT

Failure

- VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_DEVICE_LOST

See Also

VkBool32, VkDevice, VkFence

VkFenceCreateInfo - Structure specifying parameters of a newly created fence

Description

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_FENCE_CREATE_INFO

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkExportFenceCreateInfo or VkExportFenceWin32HandleInfoKHR
• Each sType member in the pNext chain must be unique
• flags must be a valid combination of VkFenceCreateFlagBits values

See Also

VkFenceCreateFlags, VkStructureType, vkCreateFence

VkFenceCreateFlags - Bitmask of VkFenceCreateFlagBits

Description

VkFenceCreateFlags is a bitmask type for setting a mask of zero or more VkFenceCreateFlagBits.

See Also

VkFenceCreateFlagBits, VkFenceCreateInfo