XenoAtom.ShaderCompiler

https://github.com/xenoatom/xenoatom.shadercompiler
Admin
XenoAtom.ShaderCompiler provides a high-level integration of shaderc to compile HLSL and GLSL shader...
Tokens:11,428
Snippets:60
Trust Score:8.6
License:BSD-2-Clause
Update:2 days ago
Show doc for...
Tokens:
Raw
### Install dotnet-shaderc as a global tool

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/doc/readme.md

Installs the dotnet-shaderc tool globally using the .NET 8 SDK. The command is `dotnet tool -g dotnet-shaderc`.

```sh
$ dotnet tool -g dotnet-shaderc
```

--------------------------------

### MSBuild project with ShaderCompilerOption properties

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/doc/readme.md

Example MSBuild project that sets a default entry point for all ShaderCompile items and overrides description and defines for a specific shader file. Note the source contains a typo: the closing tag for ShaderCompilerOption_defines is written as ShaderCompilerOption_description.

```xml
<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <!-- Sets a default shader entry point name for all ShaderCompile items  -->
    <ShaderCompilerOption_entry_point>shader_main</ShaderCompilerOption_entry_point>    
  </PropertyGroup>

  <ItemGroup>
    <!-- Update a specific shaders with specific options -->
    <ShaderCompile Include="Test.vert.hlsl">
      <ShaderCompilerOption_description>This is a description of this special shader.</ShaderCompilerOption_description>
      <ShaderCompilerOption_defines>MY_DEFINE=1;MY_OTHER_DEFINE</ShaderCompilerOption_description>
    </ShaderCompile>

  </ItemGroup>

</Project>
```

--------------------------------

### HLSL vertex shader example (Test.vert.hlsl)

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/src/XenoAtom.ShaderCompiler.Build/readme.md

Example HLSL vertex shader file that will be compiled to SPIR-V by the package. It uses the #pragma shader_stage(vertex) directive and returns a float4 position.

```hlsl
#pragma shader_stage(vertex)
float4 main(float2 pos : POSITION) : SV_POSITION
{
    return float4(pos, 0, 1);
}
```

--------------------------------

### Define ShaderCompile items and include directory in MSBuild project

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/doc/readme.md

Shows how to manually include shader files with the ShaderCompile item and add an include directory using ShaderCompilerGlobalOption_include_directory. The example includes a recursive glob pattern and a Link metadata to preserve the relative directory structure.

```xml
<Project Sdk="Microsoft.NET.Sdk">
  
  <!-- ... -->

  <ItemGroup>
    <!-- Manually include recursively shaders to compile from another directory -->
    <ShaderCompile Include="../GlobalShaders/**/*.vert">
      <Link>%(RelativeDir)%(Filename)%(Extension)</Link>
    </ShaderCompile>

    <!-- Adds folder in the include search path -->
    <ShaderCompilerGlobalOption_include_directory Include="SharedIncludes"/>
  </ItemGroup>

</Project>
```

--------------------------------

### Run dotnet-shaderc --help

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/doc/readme.md

Displays the help and usage information for the dotnet-shaderc command.

```sh
$ dotnet-shaderc --help
```

--------------------------------

### dotnet-shaderc --help output

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/doc/readme.md

The full help output showing all options and usage for dotnet-shaderc.

```text
Usage: dotnet-shaderc [Options] input_file+

A command-line GLSL/HLSL to SPIR-V compiler with Clang-compatible arguments.

Overall Options:

  -h, -?, --help             Show this message and exit
  -v, --version              Show the version of this command
  -o=<output_file>           The SPIR-V <output_file>, expecting a single input
                               file.
      --batch=<file>         A batch <file> containing a JSON representation of
                               the items to compile.
      --generate-deps        Generates deps file used by build system.
      --max-thread-count=<number>
                             The maximum <number> of threads to use to compile
                               all the inputs. Default is 0 (Maximum number of
                               cores available)

Language and Mode Selection Options:

      --invert-y             Invert the Y axis of the coordinate system.
      --shader-stage=<stage> lets you specify the shader <stage> for one or
                               more inputs from the command line. Possible
                               values are: anyhit, callable, closesthit,
                               compute, fragment, geometry, intersection, miss,
                               raygen, tesscontrol, tesseval, vertex.
      --target-env=<value>   The target environment <value> for the shader.
                               Possible values are: opengl, opengl4.5, vulkan,
                               vulkan1.0, vulkan1.1, vulkan1.2.
      --target-spv=<version> Specify the SPIR-V <version> to be used by the
                               generated module. Possible values are: spv1.0,
                               spv1.1, spv1.2, spv1.3, spv1.4, spv1.5, spv1.6.
  -x=<lang>                  specify the <lang> of the input shader files.
                               Possible values are: glsl, hlsl.

Compilation Stage Selection Options:
  -c                         Run the preprocessing and compiling stage.
  -E                         Run the preprocessing stage.
  -S                         Run the preprocessing, compiling, and then
                               disassembling stage.

Preprocessor Options:
  -D, --define[=name:value]  Add a macro name and an optional value
  -I, --include-dir=<directory>
                             Adds the specified <directory> to the search path
                               for include files.

Code Generation Options:

  -g                         Generate debug information.
  -O[=VALUE]                 -O0 No optimization. This level generates the most
                               debuggable code. -Os Enables optimizations to
                               reduce code size. -O The default optimization
                               level for better performance.
      --hlsl-16bit-types     Enables 16bit types for HLSL compilation.
      --hlsl-offsets         Use HLSL packing rules instead of GLSL rules when
                               determining offsets of members of blocks. This
                               option is always on when compiling for HLSL.
      --hlsl-functionality1  Enable extension SPV_GOOGLE_hlsl_functionality1.
      --entry-point=<name>   The entry point function <name>.
      --auto-map-locations   Automatically assign locations to all shader
                               inputs and outputs. For HLSL compilation, this
                               option is on by default.
      --auto-bind-uniforms   Directs the compiler to automatically assign
                               binding numbers to uniform variables, when an
                               explicit binding is not specified in the shader
                               source.
  @file                      Read response file for more options.
```

--------------------------------

### Run the preprocessor to standard output

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/doc/readme.md

Runs the preprocessing stage (-E) and outputs the preprocessed shader to standard output.

```sh
$ dotnet-shaderc -E Test.vert.hlsl
```

--------------------------------

### Compile a shader with dotnet-shaderc

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/doc/readme.md

Compiles a shader file (Test.vert.hlsl) to SPIR-V. The output file is not specified, so it defaults to the input name with .spv extension.

```sh
$ dotnet-shaderc Test.vert.hlsl
```

--------------------------------

### Run the disassembler

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/doc/readme.md

Runs the disassembler (-S) to produce SPIR-V assembly output, writing to the specified file.

```sh
$ dotnet-shaderc -S Test.vert.hlsl -o my_vert.spvasm
```

--------------------------------

### Compile a shader to a specific output file

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/doc/readme.md

Compiles a shader and writes the SPIR-V output to the specified file using the -o option.

```sh
$ dotnet-shaderc Test.vert.hlsl -o my_vert.spv
```

--------------------------------

### Define ShaderCompiler global properties in MSBuild project

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/doc/readme.md

Shows how to set ShaderCompilerGlobalOption_root_namespace and ShaderCompilerGlobalOption_class_name in an MSBuild project. These properties control the namespace and class name of the generated C# source.

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <!-- ... -->

    <ShaderCompilerGlobalOption_root_namespace>MyCustomNamespace</ShaderCompilerGlobalOption_root_namespace>
    <ShaderCompilerGlobalOption_class_name>MyCompiledShaders</ShaderCompilerGlobalOption_class_name>
  </PropertyGroup>
  <!-- ... -->
</Project>
```

--------------------------------

### SPIR-V Disassembly of VSMain Vertex Shader

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/src/XenoAtom.ShaderCompiler.Tests/Verified/AppTests.TestDisassembly2.verified.txt

This is the complete SPIR-V disassembly for the VSMain vertex shader. It shows the shader's module structure, including the entry point, input/output variables, and the main function that adds a constant vector to the input and stores it to the position output.

```spirv
; SPIR-V
; Version: 1.0
; Generator: Google Shaderc over Glslang; 11
; Bound: 34
; Schema: 0
               OpCapability Shader
          %1 = OpExtInstImport "GLSL.std.450"
               OpMemoryModel Logical GLSL450
               OpEntryPoint Vertex %4 "VSMain" %21 %gl_Position
               OpDecorate %21 Location 0
               OpDecorate %gl_Position BuiltIn Position
       %void = OpTypeVoid
          %3 = OpTypeFunction %void
      %float = OpTypeFloat 32
    %v4float = OpTypeVector %float 4
  %float_256 = OpConstant %float 256
%_ptr_Input_v4float = OpTypePointer Input %v4float
         %21 = OpVariable %_ptr_Input_v4float Input
%_ptr_Output_v4float = OpTypePointer Output %v4float
%gl_Position = OpVariable %_ptr_Output_v4float Output
         %33 = OpConstantComposite %v4float %float_256 %float_256 %float_256 %float_256
          %4 = OpFunction %void None %3
          %5 = OpLabel
         %22 = OpLoad %v4float %21
         %32 = OpFAdd %v4float %22 %33
               OpStore %gl_Position %32
               OpReturn
               OpFunctionEnd
```

--------------------------------

### Generated C# embedded shader class (CompiledShaders)

Source: https://github.com/xenoatom/xenoatom.shadercompiler/blob/main/doc/readme.md

Shows the C# code generated by the MSBuild integration to embed a compiled HLSL vertex shader as a byte array. It uses conditional compilation to expose a ReadOnlySpan<byte> on .NET 5+ or .NET Standard 2.1, and a byte[] otherwise.

```csharp
using System;

namespace HelloWorld
{
    internal static partial class CompiledShaders
    {
        #if NET5_0_OR_GREATER || NETSTANDARD2_1
        public static ReadOnlySpan<byte> Test_vert_hlsl => new byte[]
        #else
        public static readonly byte[] Test_vert_hlsl = new byte[]
        #endif
        {
            3, 2, 35, 7, 0, 0, 1, 0, 11, 0, 13, 0, 38, 0, 0, 0, 0, 0, 0, 0, 17, 0, 2, 0, 1, 0, 0, 0, 11, 0, 6, 0, 1, 0, 0, 0, 71, 76, 83, 76, 46, 115, 116, 100, 46, 52, 53, 48, 0, 0, 0, 0, 14, 0, 3, 0, 0, 0, 0, 0, 1, 0, 0, 0, 15, 0, 7, 0, 0, 0, 0, 0, 4, 0, 0, 0, 109, 97, 105, 110, 0, 0, 0, 0, 24, 0, 0, 0, 27, 0, 0, 0, 71, 0, 4, 0, 24, 0, 0, 0, 30, 0, 0, 0, 0, 0, 0, 0, 71, 0, 4, 0, 27, 0, 0, 0, 11, 0, 0, 0, 0, 0, 0, 0, 19, 0, 2, 0, 2, 0, 0, 0, 33, 0, 3, 0, 3, 0, 0, 0, 2, 0, 0, 0, 22, 0, 3, 0, 6, 0, 0, 0, 32, 0, 0, 0, 23, 0, 4, 0, 7, 0, 0, 0, 6, 0, 0, 0, 2, 0, 0, 0, 23, 0, 4, 0, 9, 0, 0, 0, 6, 0, 0, 0, 4, 0, 0, 0, 43, 0, 4, 0, 6, 0, 0, 0, 15, 0, 0, 0, 0, 0, 0, 0, 43, 0, 4, 0, 6, 0, 0, 0, 16, 0, 0, 0, 0, 0, 0, 64, 32, 0, 4, 0, 23, 0, 0, 0, 1, 0, 0, 0, 7, 0, 0, 0, 59, 0, 4, 0, 23, 0, 0, 0, 24, 0, 0, 0, 1, 0, 0, 0, 32, 0, 4, 0, 26, 0, 0, 0, 3, 0, 0, 0, 9, 0, 0, 0, 59, 0, 4, 0, 26, 0, 0, 0, 27, 0, 0, 0, 3, 0, 0, 0, 54, 0, 5, 0, 2, 0, 0, 0, 4, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 0, 248, 0, 2, 0, 5, 0, 0, 0, 61, 0, 4, 0, 7, 0, 0, 0, 25, 0, 0, 0, 24, 0, 0, 0, 81, 0, 5, 0, 6, 0, 0, 0, 35, 0, 0, 0, 25, 0, 0, 0, 0, 0, 0, 0, 81, 0, 5, 0, 6, 0, 0, 0, 36, 0, 0, 0, 25, 0, 0, 0, 1, 0, 0, 0, 80, 0, 7, 0, 9, 0, 0, 0, 37, 0, 0, 0, 35, 0, 0, 0, 36, 0, 0, 0, 15, 0, 0, 0, 16, 0, 0, 0, 62, 0, 3, 0, 27, 0, 0, 0, 37, 0, 0, 0, 253, 0, 1, 0, 56, 0, 1, 0
        };
    }
}
```
Tokens:
Raw