oneshaderDocs
oneshader docs
Everything about OneShader: getting started, the build package, the compiler and the command line, the generated C# bindings, the SPIR-V, Metal and WGSL backends, how the compiler is built and tested, its performance against DXC, and the cookbook.
Start
Getting startedCompile HLSL shaders during dotnet build with errors on the HLSL line, use the C# structs and bindings generated from them, emit Metal and WGSL next to SPIR-V, build pipeline layouts, and compile at run time or from the command line.OverviewWhat OneShader is and why: shader errors as build errors, C# that matches the shader, three targets from one front end, checked against DXC and real GPUs, and its speed against DXC with the losses shown.
Packages
The build packageRecursiveAI.OneShader.Build: HLSL compiled during dotnet build, the generated C# per file, choosing targets, shader variants with Axes and OneShaderVariant, item metadata and properties.The compiler packageRecursiveAI.OneShader: compile HLSL at run time, hot reload with an interface check, the compile cache, pipeline layouts for Vulkan, Metal and WebGPU, and specialization values.The command lineRecursiveAI.OneShader.Tool: the oneshader command, its DXC-compatible flags and its own options, exit codes, and the reflection JSON schema.
Building shaders into C#
Generated bindingsWhat RecursiveAI.OneShader.Build generates from each .hlsl file: constant-buffer structs with the shader’s offsets, binding constants, push constants, specialization constants, variants, 16-bit and 64-bit members, and pipeline layouts.Reflection file formatThe line-based reflection file the build task writes for each shader and the source generator reads: records, attributes and versioning rules.
Targets
SPIR-V (Vulkan)How OneShader maps HLSL to SPIR-V 1.5 for Vulkan 1.2: matrices, layouts, bindings, stage variables, precise, wave intrinsics, 16-bit and 64-bit types, specialization constants, and the errors it reports instead of wrong code.Metal Shading LanguageHow OneShader writes Metal Shading Language 2.4: functions, argument indices, push constants, function constants, wave intrinsics, precise, 16-bit types, what Metal can’t express, and how the output is checked.WGSL (WebGPU)How OneShader writes WGSL for WebGPU: push constants as uniform buffers, layouts, subgroups, f16, overrides, what WGSL can’t express (error OSH5202), known differences and how the output is checked.
Inside the compiler
The intermediate representationThe typed SSA intermediate representation between OneShader’s HLSL front end and its SPIR-V, MSL and WGSL backends, and the optimizer passes that run on it.WebGPU execution parityHow OneShader’s WGSL output is run in headless Chromium on a real WebGPU adapter and compared with DXC’s SPIR-V on Vulkan.Performance against DXCOneShader against DXC on 68 entry points: about 2.4 times faster as a NativeAOT binary, 5 to 14 times slower as an ordinary .NET process, SPIR-V size, allocations and the method.