KhronosGroup / KhronosGroup/Vulkan-Docs
docs: Should `vkWaitSemaphores()` list synchronization scopes and exclude access scopes?
- Dominant language
- JavaScript
- Stars
- 3.3k
- Forks
- 549
- Avg merge
- 5d 5h
- Merged PRs (30d)
- 2
Description
When reading [the synchronization chapter](https://docs.vulkan.org/spec/latest/chapters/synchronization.html), [host write ordering guarantees](https://docs.vulkan.org/spec/latest/chapters/synchronization.html#synchronization-submission-host-writes) (i.e. access scopes) for queue submits are clarified. [`vkWaitForFences()`](https://docs.vulkan.org/spec/latest/chapters/synchronization.html#vkWaitForFences) only defines synchronization scopes, but no access scopes. This is expected, because a note is included that precludes any memory order:
> [!NOTE]
> Signaling a fence and waiting on the host **does not guarantee that the results of memory accesses will be visible to the host**, as the access scope of a memory dependency defined by a fence only includes device access. A [memory barrier](https://docs.vulkan.org/spec/latest/chapters/synchronization.html#synchronization-memory-barriers) or other memory dependency **must** be used to guarantee this. See the description of [host access types](https://docs.vulkan.org/spec/latest/chapters/synchronization.html#synchronization-host-access-types) for more information.
[For `vkSignalSemaphore()`](https://docs.vulkan.org/spec/latest/chapters/synchronization.html#vkSignalSemaphore), only synchronization scopes are listed, but such a note on memory order appears to be missing.
Finally, [`vkWaitSemaphores()`](https://docs.vulkan.org/spec/latest/chapters/synchronization.html#vkWaitSemaphores) is entirely missing synchronization scopes, as well as a note on memory ordering: I assume excludes any memory ordering guarantees like `vkWaitForFences()`?
---
On a separate note, documentation pages like this are slightly hard to read when the last paragraph for one command like `vkWaitSemaphores()` flows directly into the first paragraph (description) of the next command like `vkSignalSemaphore()` without a clear separator like a horizontal line. Is that something that can be added?
Contributor guide
Assessment
This issue has not been assessed yet.