rtengine/contrib/simple_vulkan_synchronization/README.md
Kevin Trogant 3bc192b281 dump state
this will be the basis of the framegraph rewrite, because the current
state is fucked
2024-03-25 17:55:03 +01:00

154 lines
6.2 KiB
Markdown

# Simplified Vulkan Synchronization
In an effort to make Vulkan synchronization more accessible, I created this
stb-inspired single-header library in order to somewhat simplify the core
synchronization mechanisms in Vulkan - pipeline barriers and events.
Rather than the complex maze of enums and bitflags in Vulkan - many
combinations of which are invalid or nonsensical - this library collapses
this to a much shorter list of 40 distinct usage types, and a couple of
options for handling image layouts.
Use of other synchonization mechanisms such as semaphores, fences and render
passes are not addressed in this API at present.
## Usage
#define the symbol THSVS_SIMPLER_VULKAN_SYNCHRONIZATION_IMPLEMENTATION in
*one* C/C++ file before the #include of the header; the implementation
will be generated in that file.
## Version
alpha.9
Alpha.9 adds the thsvsGetAccessInfo function to translate access types into a thsvsVkAccessInfo.
## Version History
alpha.8
Alpha.8 adds a host preinitialization state for linear images, as well as a number of new access sets for extensions released since the last update.
alpha.7
Alpha.7 incorporates a number of fixes from @gwihlidal, and fixes
handling of pipeline stages in the presence of multiple access types or
barriers in light of other recent changes.
alpha.6
Alpha.6 fixes a typo (VK_ACCESS_TYPE_MEMORY_READ|WRITE_BIT should have been VK_ACCESS_MEMORY_READ|WRITE_BIT), and sets the pipeline stage src and dst flag bits to VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT and VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT during initialization, not 0 as per alpha.5
alpha.5
Alpha.5 now correctly zeroes out the pipeline stage flags before trying to incrementally set bits on them... common theme here, whoops.
alpha.4
Alpha.4 now correctly zeroes out the access types before trying to incrementally set bits on them (!)
alpha.3
Alpha.3 changes the following:
Uniform and vertex buffer access in one enum, matching D3D12_RESOURCE_STATE_VERTEX_AND_CONSTANT_BUFFER:
- THSVS_ACCESS_ANY_SHADER_READ_UNIFORM_BUFFER_OR_VERTEX_BUFFER
Color read *and* write access, matching D3D12_RESOURCE_STATE_RENDER_TARGET:
- THSVS_ACCESS_COLOR_ATTACHMENT_READ_WRITE
Also the "THSVS_ACCESS_\*\_SHADER_READ_SAMPLED_IMAGE" enums have been renamed to the form "THSVS_ACCESS_\*\_SHADER_READ_SAMPLED_IMAGE_OR_UNIFORM_TEXEL_BUFFER"
alpha.2
Alpha.2 adds four new resource states for "ANY SHADER ACCESS":
- THSVS_ACCESS_ANY_SHADER_READ_UNIFORM_BUFFER
- THSVS_ACCESS_ANY_SHADER_READ_SAMPLED_IMAGE
- THSVS_ACCESS_ANY_SHADER_READ_OTHER
- THSVS_ACCESS_ANY_SHADER_WRITE
alpha.1
Alpha.1 adds three new resource states:
- THSVS_ACCESS_GENERAL (Any access on the device)
- THSVS_ACCESS_DEPTH_ATTACHMENT_WRITE_STENCIL_READ_ONLY (Write access to only the depth aspect of a depth/stencil attachment)
- THSVS_ACCESS_STENCIL_ATTACHMENT_WRITE_DEPTH_READ_ONLY (Write access to only the stencil aspect of a depth/stencil attachment)
It also fixes a couple of typos, and adds clarification as to when extensions need to be enabled to use a feature.
alpha.0
This is the very first public release of this library; future revisions
of this API may change the API in an incompatible manner as feedback is
received.
Once the version becomes stable, incompatible changes will only be made
to major revisions of the API - minor revisions will only contain
bugfixes or minor additions.
## Memory Allocation
The thsvsCmdPipelineBarrier and thsvsCmdWaitEvents commands allocate
temporary storage for the Vulkan barrier equivalents in order to pass them
to the respective Vulkan commands.
These use the `THSVS_TEMP_ALLOC(size)` and `THSVS_TEMP_FREE(x)` macros,
which are by default set to alloca(size) and ((void)(x)), respectively.
If you don't want to use stack space or would rather use your own
allocation strategy, these can be overridden by defining these macros
in before #include-ing the header file with
THSVS_SIMPLER_VULKAN_SYNCHRONIZATION_IMPLEMENTATION defined.
I'd rather avoid the need for these allocations in what are likely to be
high-traffic commands, but currently just want to ship something - may
revisit this at a future date based on feedback.
## Expressiveness Compared to Raw Vulkan
Despite the fact that this API is fairly simple, it expresses 99% of
what you'd actually ever want to do in practice.
Adding the missing expressiveness would result in increased complexity
which didn't seem worth the tradeoff - however I would consider adding
something for them in future if it becomes an issue.
Here's a list of known things you can't express:
* Execution only dependencies cannot be expressed.
These are occasionally useful in conjunction with semaphores, or when
trying to be clever with scheduling - but their usage is both limited
and fairly tricky to get right anyway.
* Depth/Stencil Input Attachments can be read in a shader using either
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL or
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL - this library
*always* uses VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL.
It's possible (though highly unlikely) when aliasing images that this
results in unnecessary transitions.
## Error Checks
By default, as with the Vulkan API, this library does NOT check for
errors.
However, a number of optional error checks (`THSVS_ERROR_CHECK_*`) can be
enabled by uncommenting the relevant #defines.
Currently, error checks simply assert at the point a failure is detected
and do not output an error message.
I certainly do not claim they capture *all* possible errors, but they
capture what should be some of the more common ones.
Use of the Vulkan Validation Layers in tandem with this library is
strongly recommended:
https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers
## Issues
This header was clean of warnings using -Wall as of time of publishing
on both gcc 4.8.4 and clang 3.5, using the c99 standard.
There's a potential pitfall in thsvsCmdPipelineBarrier and thsvsCmdWaitEvents
where alloca is used for temporary allocations. See
[Memory Allocation](#memory-allocation) for more information.
Testing of this library is so far extremely limited with no immediate
plans to add to that - so there's bound to be some amount of bugs.
Please raise these issues on the repo issue tracker, or provide a fix
via a pull request yourself if you're so inclined.