DXC Cookbook: HLSL Coding Patterns for SPIR-V

[JeGX]

This document provides a set of examples that demonstrate what will and will not be accepted by the DXC compiler when generating SPIR-V. The difficulty in defining what is acceptable is that it cannot be specified by a grammar. The entire program must be taken into consideration. Hopefully this will be useful.

We are interested in how global resources are used. For a SPIR-V shader to be valid, accesses to global resources like structured buffers and images must be done directly on the global resources. They cannot be copied or have their address returned from functions. However, in HLSL, it is possible to copy a global resource or to pass it by reference to a function. Since this can be arbitrarily complex, DXC can generate valid SPIR-V only if the compiler is able to remove all of these copies.

The transformations that are used to remove the copies will be the same for both structured buffers and images, so we have chosen to focus on structured buffer. The process of transforming the code in this way is called legalization.

Support evolves over time as the optimizations in SPIRV-Tools are improved. At GDC 2018, Greg Fischer from LunarG presented earlier results in this space. The DXC, Glslang, and SPIRV-Tools maintainers work together to handle new HLSL code patterns. This document represents the state of the DXC compiler in October 2018.

Glslang does legalization as well. However, what it is able to legalize is different from DXC because of features it chooses to support, and the optimizations from SPIRV-Tools it choose to run. For example, Glslang does not support structured buffer aliasing yet, so many of these examples will not work with Glslang.

All of the examples are available in the DXC repository, at
https://github.com/Microsoft/DirectXShaderCompiler/tree/master/tools/clang/test/CodeGenSPIRV/legal-examples 
To open a link to Tim Jones' Shader Playground for an example, you can follow the url in the comments of each example.

Link: https://github.com/Microsoft/DirectXShaderCompiler/blob/master/docs/SPIRV-Cookbook.rst