VK_KHR_timeline_semaphore(3)

# VK_KHR_timeline_semaphore(3) Manual Page

## Name

VK_KHR_timeline_semaphore - device extension

Loading… please wait.

## Registered Extension Number

208

## Revision

2

## Ratification Status

Ratified

## Extension and Version Dependencies

VK_KHR_get_physical_device_properties2

## Deprecation State

- Promoted to Vulkan 1.2

## Contact

- Faith Ekstrand gfxstrand

## Other Extension Metadata

Last Modified Date

  2019-06-12

IP Status

  No known IP claims.

Interactions and External Dependencies

  - This extension interacts with `VK_KHR_external_semaphore_capabilities`

  - This extension interacts with `VK_KHR_external_semaphore`

  - This extension interacts with `VK_KHR_external_semaphore_win32`

Contributors

  - Jeff Bolz, NVIDIA

  - Yuriy O’Donnell, Epic Games

  - Faith Ekstrand, Intel

  - Jesse Hall, Google

  - James Jones, NVIDIA

  - Jeff Juliano, NVIDIA

  - Daniel Rakos, AMD

  - Ray Smith, Arm

## Description

This extension introduces a new type of semaphore that has an integer payload identifying a point in a timeline. Such timeline semaphores support the following operations:

- Host query - A host operation that allows querying the payload of the timeline semaphore.

- Host wait - A host operation that allows a blocking wait for a timeline semaphore to reach a specified value.

- Host signal - A host operation that allows advancing the timeline semaphore to a specified value.

- Device wait - A device operation that allows waiting for a timeline semaphore to reach a specified value.

- Device signal - A device operation that allows advancing the timeline semaphore to a specified value.

## Promotion to Vulkan 1.2

All functionality in this extension is included in core Vulkan 1.2, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

## New Commands

- vkGetSemaphoreCounterValueKHR

- vkSignalSemaphoreKHR

- vkWaitSemaphoresKHR

## New Structures

- VkSemaphoreSignalInfoKHR

- VkSemaphoreWaitInfoKHR

- Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:

  - VkPhysicalDeviceTimelineSemaphoreFeaturesKHR

- Extending VkPhysicalDeviceProperties2:

  - VkPhysicalDeviceTimelineSemaphorePropertiesKHR

- Extending VkSemaphoreCreateInfo, VkPhysicalDeviceExternalSemaphoreInfo:

  - VkSemaphoreTypeCreateInfoKHR

- Extending VkSubmitInfo, VkBindSparseInfo:

  - VkTimelineSemaphoreSubmitInfoKHR

## New Enums

- VkSemaphoreTypeKHR

- VkSemaphoreWaitFlagBitsKHR

## New Bitmasks

- VkSemaphoreWaitFlagsKHR

## New Enum Constants

- `VK_KHR_TIMELINE_SEMAPHORE_EXTENSION_NAME`

- `VK_KHR_TIMELINE_SEMAPHORE_SPEC_VERSION`

- Extending VkSemaphoreType:

  - `VK_SEMAPHORE_TYPE_BINARY_KHR`

  - `VK_SEMAPHORE_TYPE_TIMELINE_KHR`

- Extending VkSemaphoreWaitFlagBits:

  - `VK_SEMAPHORE_WAIT_ANY_BIT_KHR`

- Extending VkStructureType:

  - `VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES_KHR`

  - `VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_PROPERTIES_KHR`

  - `VK_STRUCTURE_TYPE_SEMAPHORE_SIGNAL_INFO_KHR`

  - `VK_STRUCTURE_TYPE_SEMAPHORE_TYPE_CREATE_INFO_KHR`

  - `VK_STRUCTURE_TYPE_SEMAPHORE_WAIT_INFO_KHR`

  - `VK_STRUCTURE_TYPE_TIMELINE_SEMAPHORE_SUBMIT_INFO_KHR`

## Issues

1) Do we need a new object type for this?

RESOLVED: No, we just introduce a new type of semaphore object, as `VK_KHR_external_semaphore_win32` already uses semaphores as the destination for importing D3D12 fence objects, which are semantically close/identical to the proposed synchronization primitive.

2) What type of payload the new synchronization primitive has?

RESOLVED: A 64-bit unsigned integer that can only be set to strictly increasing values by signal operations and is not changed by wait operations.

3) Does the new synchronization primitive have the same signal-before-wait requirement as the existing semaphores do?

RESOLVED: No. Timeline semaphores support signaling and waiting entirely asynchronously. It is the responsibility of the client to avoid deadlock.

4) Does the new synchronization primitive allow resetting its payload?

RESOLVED: No, allowing the payload value to “go backwards” is problematic. Applications looking for reset behavior should create a new instance of the synchronization primitive instead.

5) How do we enable host waits on the synchronization primitive?

RESOLVED: Both a non-blocking query of the current payload value of the synchronization primitive, and a blocking wait operation are provided.

6) How do we enable device waits and signals on the synchronization primitive?

RESOLVED: Similar to `VK_KHR_external_semaphore_win32`, this extension introduces a new structure that can be chained to VkSubmitInfo to specify the values signaled semaphores should be set to, and the values waited semaphores need to reach.

7) Can the new synchronization primitive be used to synchronize presentation and swapchain image acquisition operations?

RESOLVED: Some implementations may have problems with supporting that directly, thus it is not allowed in this extension.

8) Do we want to support external sharing of the new synchronization primitive type?

RESOLVED: Yes. Timeline semaphore specific external sharing capabilities can be queried using vkGetPhysicalDeviceExternalSemaphoreProperties by chaining the new VkSemaphoreTypeCreateInfoKHR structure to its `pExternalSemaphoreInfo` structure. This allows having a different set of external semaphore handle types supported for timeline semaphores vs. binary semaphores.

9) Do we need to add a host signal operation for the new synchronization primitive type?

RESOLVED: Yes. This helps in situations where one host thread submits a workload but another host thread has the information on when the workload is ready to be executed.

10) How should the new synchronization primitive interact with the ordering requirements of the original `VkSemaphore`?

RESOLVED: Prior to calling any command which may cause a wait operation on a binary semaphore, the client must ensure that the semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends (if any) must have also been submitted for execution.

11) Should we have separate feature bits for different sub-features of timeline semaphores?

RESOLVED: No. The only feature which cannot be supported universally is timeline semaphore import/export. For import/export, the client is already required to query available external handle types via vkGetPhysicalDeviceExternalSemaphoreProperties and provide the semaphore type by adding a VkSemaphoreTypeCreateInfoKHR structure to the `pNext` chain of VkPhysicalDeviceExternalSemaphoreInfo so no new feature bit is required.

## Version History

- Revision 1, 2018-05-10 (Faith Ekstrand)

  - Initial version

- Revision 2, 2019-06-12 (Faith Ekstrand)

  - Added an initialValue parameter to timeline semaphore creation

## See Also

VkPhysicalDeviceTimelineSemaphoreFeaturesKHR, VkPhysicalDeviceTimelineSemaphorePropertiesKHR, VkSemaphoreSignalInfoKHR, VkSemaphoreTypeCreateInfoKHR, VkSemaphoreTypeKHR, VkSemaphoreWaitFlagBitsKHR, VkSemaphoreWaitFlagsKHR, VkSemaphoreWaitInfoKHR, VkTimelineSemaphoreSubmitInfoKHR, vkGetSemaphoreCounterValueKHR, vkSignalSemaphoreKHR, vkWaitSemaphoresKHR

## Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

## Copyright

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0