Shader Compilation

D3D12

The following variants of generating source shader debug information for HLSL shaders using the Microsoft DirectX Shader Compiler are supported:

Compile and use full shader blobs

Compile the shaders with the debug information. Use the full (i.e., not stripped) shader binary when running the application and make it accessible through ShaderLookupCallback. In this case there is no need to provide a ShaderSourceDebugDataLookupCallback.

Compilation example:
dxc -Zi [..] -Fo shader.bin shader.hlsl
Compile and strip

Compile the shaders with debug information and then strip off the debug information. Use the stripped shader binary data when running the application. Make the stripped shader binary data accessible through ShaderLookupCallback. In addition, make the non-stripped shader binary data accessible through ShaderSourceDebugDataLookupCallback.

Compilation example:
```
dxc -Zi [..] -Fo full_shader.bin shader.hlsl
dxc -dumpbin -Qstrip_debug -Fo shader.bin full_shader.bin
```
The shader’s DebugName required for implementing the ShaderSourceDebugDataLookupCallback may be extracted from the stripped or the non-stripped shader binary data with GFSDK_Aftermath_GetShaderDebugName.
Compile with separate debug information (and auto-generated debug data file name)

Compile the shaders with debug information and instruct the compiler to store the debug meta data in a separate shader debug information file. The name of the file generated by the compiler will match the DebugName of the shader. Make the shader binary data accessible through ShaderLookupCallback. In addition, make the data from the compiler generated shader debug data file accessible through ShaderSourceDebugDataLookupCallback.

Compilation example:
```
dxc -Zi [..] -Fo shader.bin -Fd debugInfo\ shader.hlsl
```
The debug data file generated by the compiler does not contain any reference to the shader’s DebugName. It is the responsibility of the user providing the ShaderSourceDebugDataLookupCallback callback to implement a solution to lookup the debug data based on the name of the generated debug data file.
Compile with separate debug information (and user-defined debug data file name)

Compile the shaders with debug information and instruct the compiler to store the debug meta data in a separate shader debug information file. The name of the file is freely chosen by the user. Make the shader binary data accessible through ShaderLookupCallback. In addition, make the data from the compiler generated shader debug data file accessible through ShaderSourceDebugDataLookupCallback.

Compilation example:
```
dxc -Zi [..] -Fo shader.bin -Fd debugInfo\shader.dbg shader.hlsl
```
The debug data file generated by the compiler does not contain any reference to the shader’s DebugName. It is the responsibility of the user providing the ShaderSourceDebugDataLookupCallback callback to implement a solution that performs the lookup of the debug data based on a mapping between the shader’s DebugName the debug data file’s name that was chosen for the compilation. The shader’s DebugName may be extracted from the shader binary data with GFSDK_Aftermath_GetShaderDebugName.

Vulkan (SPIR-V)

For SPIR-V shaders, the Aftermath SDK provides support for the following variants of generating source shader debug information:

Compile and use a full shader blob

Compile the shaders with the debug information. Use the full (i.e., not stripped) shader binary when running the application and make it accessible through ShaderLookupCallback. In this case there is no need to provide ShaderSourceDebugInfoLookupCallback.

Compilation example using the Vulkan SDK toolchain:
```
glslangValidator -V -g -o shader.spv shader.vert
```
Compilation example using the DirectX Shader Compiler:
```
dxc -spirv -Zi [..] -Fo shader.spv shader.hlsl
```
Compile and strip

Compile the shaders with debug information and then strip off the debug information. Use the stripped shader binary data when running the application. Make the stripped shader binary data accessible through shaderLookupCb. In addition, make the non-stripped shader binary data accessible through ShaderSourceDebugInfoLookupCallback.

Compilation example using the Vulkan SDK toolchain:
```
glslangValidator -V -g -o ./full/shader.spv shader.vert
spirv-remap --map all --strip-all --input full/shader.spv --output ./stripped/
```
Compilation example using the Microsoft DirectX Shader Compiler:
```
dxc -spirv -Zi [..] -Fo ./full/shader.spv shader.hlsl
spirv-remap --map all --strip-all --input full/shader.spv --output ./stripped/
```
The (crash dump decoder) application then needs to pass the contents of the full/shader.spv and stripped/shader.spv pair to GFSDK_Aftermath_GetDebugNameSpirv to generate the shader DebugName to use with ShaderSourceDebugInfoLookupCallback.