Write up a section in README about implementation details.

README.md

@@ -122,9 +122,15 @@ Please see `samples/cpp` where some GLSL shaders are compiled to SPIR-V, decompi
 Reading through the samples should explain how to use the C++ interface.
 A simple Makefile is included to build all shaders in the directory.
 
-### Using SPIRV-Cross to output GLSL shaders from glslang HLSL
+### Implementation notes
 
-#### Entry point
+When using SPIR-V and SPIRV-Cross as an intermediate step for cross-compiling between high level languages there are some considerations to take into account,
+as not all features used by one high-level language are necessarily supported natively by the target shader language.
+SPIRV-Cross aims to provide the tools needed to handle these scenarios in a clean and robust way, but some manual action is required to maintain compatibility.
+
+#### HLSL source to GLSL
+
+##### HLSL entry points
 
 When using SPIR-V shaders compiled from HLSL, there are some extra things you need to take care of.
 First make sure that the entry point is used correctly.
@@ -136,7 +142,67 @@ Cannot end a function before ending the current block.
 Likely cause: If this SPIR-V was created from glslang HLSL, make sure the entry point is valid.
 ```
 
-#### Separate image samplers
+##### Vertex/Fragment interface linking
+
+HLSL relies on semantics in order to effectively link together shader stages. In the SPIR-V generated by glslang, the transformation from HLSL to GLSL ends up looking like
+
+```
+struct VSOutput {
+   // SV_Position is rerouted to gl_Position
+   float4 position : SV_Position;
+   float4 coord : TEXCOORD0;
+};
+
+VSOutput main(...) {}
+```
+
+```
+struct VSOutput {
+   float4 coord;
+}
+layout(location = 0) out VSOutput _magicNameGeneratedByGlslang;
+```
+
+While this works, be aware of the type of the struct which is used in the vertex stage and the fragment stage.
+There may be issues if the structure type name differs in vertex stage and fragment stage.
+
+You can make use of the reflection interface to force the name of the struct type.
+
+```
+// Something like this for both vertex outputs and fragment inputs.
+compiler.set_name(varying_resource.base_type_id, "VertexFragmentLinkage");
+```
+
+#### HLSL source to legacy GLSL/ESSL
+
+HLSL tends to emit varying struct types to pass data between vertex and fragment.
+This is not supported in legacy GL/GLES targets, so to support this, varying structs are flattened.
+This is done automatically, but the API user might need to be aware that this is happening in order to support all cases.
+
+Modern GLES code like this:
+```
+struct Output {
+   vec4 a;
+   vec2 b;
+};
+out Output vout;
+```
+
+Is transformed into:
+```
+struct Output {
+   vec4 a;
+   vec2 b;
+};
+varying vec4 Output_a;
+varying vec2 Output_b;
+```
+
+Note that now, both the struct name and the member names will participate in the linking interface between vertex and fragment, so
+API users might want to ensure that both the struct names and member names match so that vertex outputs and fragment inputs can link properly.
+
+
+#### Separate image samplers (HLSL/Vulkan) for backends which do not support it (GLSL)
 
 Another thing you need to remember is when using samplers and textures in HLSL these are separable, and not directly compatible with GLSL. If you need to use this with desktop GL/GLES, you need to call `Compiler::build_combined_image_samplers` first before calling `Compiler::compile`, or you will get an exception.
 
@@ -155,7 +221,12 @@ 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 does this automatically, but if you're calling the library, you'll need to do this yourself.
+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 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)`.
 
 ## Contributing