RecursiveAI.OneShader.Tool 1.2.0

OneShader.Tool

oneshader: the OneShader HLSL compiler on the command line. It compiles a vertex, pixel or compute shader to SPIR-V (Vulkan 1.2+), Metal Shading Language or WGSL, and takes DXC's core flags, so a DXC command line mostly works unchanged. Use it from CMake, Make, scripts or any build system that is not MSBuild. (In an MSBuild project, RecursiveAI.OneShader.Build compiles shaders during dotnet build and generates C# bindings.)

Install

dotnet tool install -g RecursiveAI.OneShader.Tool
oneshader --version

Needs the .NET 10 runtime. For a single native binary with no runtime and the fastest start-up (about 2.4 times faster per process than DXC), publish it with NativeAOT from this repository:

dotnet publish src/OneShader.Tool -c Release -r linux-x64 -o out    # out/oneshader

Use

oneshader -T ps_6_0 -E PSMain -spirv sprite.hlsl -Fo sprite.ps.spv
oneshader --target msl --target wgsl --all-entries sprite.hlsl -Fo build/sprite.out
oneshader -T cs_6_0 -E CSMain -D TILE=16 -I include --reflect histogram.json --depfile histogram.d histogram.hlsl -Fo histogram.spv

Diagnostics go to standard error as file(line,col): error OSH0102: message, the form IDEs and CMake parse. Exit code: 0 success, 1 the shader did not compile (or an output could not be written), 2 the command line is wrong. Warnings print and do not change the exit code unless -WX is given.

DXC-compatible options

Values may follow the flag after a space or directly (-T ps_6_0, -Tps_6_0). Every other -fvk-* and -fspv-* option, and DXC options such as -Zi or -Fh, is rejected with a message naming it. oneshader always uses DXC's default Vulkan layout and binding rules; use [[vk::binding]], [[vk::location]] and [[vk::offset]] in the shader.

oneshader options

Reflection JSON, schema version 1

The same data as the library's ShaderReflection, keys in camelCase, enums by name, output in a fixed order, \n line ends and no machine paths, so the same compile gives the same bytes. Changes that break readers raise schemaVersion.

{ "schemaVersion": 1, "source": "<file name>", "targets": ["SpirV", ...],
  "resources": [ { "name", "kind", "hlslType", "resourceType", "count", "stages": ["Vertex"|"Pixel"|"Compute"],
                   "slots": [ { "target", "set", "binding" } ], "counterSlots": [ ... ], "layout": <type> } ],
  "pushConstants": [ { "name", "stages", "slots", "layout": <type> } ],
  "specConstants": [ { "name", "id", "type": "Bool"|"Int"|"UInt"|"Float", "defaultBits", "slots": [ { "target", "index", "name" } ] } ]  (only when the shader has some),
  "entryPoints": [ { "name", "stage", "workgroupSize": [x, y, z] (compute), "vertexStride" (vertex),
                     "inputs": [ <variable> ], "outputs": [ <variable> ], "usedResources": [ names ],
                     "pushConstant": name (optional), "usedSpecConstants": [ names ] (optional) } ] }

<variable> = { "name", "semantic", "semanticIndex", "location" (optional), "builtIn", "scalar", "components",
               "format" (optional), "offset", "interpolation" }
<type>     = { "kind": "Scalar|Vector|Matrix|Array|Struct", "size", "alignment", and by kind:
               Scalar: "scalar" | Vector: "scalar", "components" | Matrix: "scalar", "rows", "columns", "matrixStride", "packing"
               Array: "length", "stride", "element": <type> | Struct: "name", "members": [ { "name", "offset", "type": <type> } ] }

Sizes, offsets and strides are the byte layout of the buffer, equal for every target.

Licensed under MIT OR Apache-2.0.