From a8016a6470a3b9e47bbdbc3152efeb0c2b721505 Mon Sep 17 00:00:00 2001 From: Hans-Kristian Arntzen Date: Fri, 4 Feb 2022 12:51:32 +0100 Subject: [PATCH] Update documentation for descriptor set support in MSL/HLSL. Ancient outdated README. --- README.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7d6520c9..1b302437 100644 --- a/README.md +++ b/README.md @@ -381,10 +381,28 @@ for (auto &remap : compiler->get_combined_image_samplers()) If your target is Vulkan GLSL, `--vulkan-semantics` will emit separate image samplers as you'd expect. The command line client calls `Compiler::build_combined_image_samplers` automatically, but if you're calling the library, you'll need to do this yourself. -#### Descriptor sets (Vulkan GLSL) for backends which do not support them (HLSL/GLSL/Metal) +#### Descriptor sets (Vulkan GLSL) for backends which do not support them (pre HLSL 5.1 / GLSL) Descriptor sets are unique to Vulkan, so make sure that descriptor set + binding is remapped to a flat binding scheme (set always 0), so that other APIs can make sense of the bindings. -This can be done with `Compiler::set_decoration(id, spv::DecorationDescriptorSet)`. +This can be done with `Compiler::set_decoration(id, spv::DecorationDescriptorSet)`. For other backends like MSL and HLSL, descriptor sets +can be used, with some minor caveats, see below. + +##### MSL 2.0+ + +Metal supports indirect argument buffers (--msl-argument-buffers). In this case, descriptor sets become argument buffers, +and bindings are mapped to [[id(N)]] within the argument buffer. One quirk is that arrays of resources consume multiple ids, +where Vulkan does not. This can be worked around either from shader authoring stage +or remapping bindings as needed to avoid the overlap. +There is also a rich API to declare remapping schemes which is intended to work like +the pipeline layout in Vulkan. See `CompilerMSL::add_msl_resource_binding`. Remapping combined image samplers for example +must be split into two bindings in MSL, so it's possible to declare an id for the texture and sampler binding separately. + +##### HLSL - SM 5.1+ + +In SM 5.1+, descriptor set bindings are interpreted as register spaces directly. In HLSL however, arrays of resources consume +multiple binding slots where Vulkan does not, so there might be overlap if the SPIR-V was not authored with this in mind. +This can be worked around either from shader authoring stage (don't assign overlapping bindings) +or remap bindings in SPIRV-Cross as needed to avoid the overlap. #### Linking by name for targets which do not support explicit locations (legacy GLSL/ESSL)