---
title: "oneshader docs"
url: https://recursiveai.org/oneshader/docs/
description: "Everything about OneShader: getting started, the build package, the compiler and the command line, the generated C# bindings, the SPIR-V, Metal and WGSL…"
version: "1.2.0"
---

# 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 started](https://recursiveai.org/oneshader/docs/getting-started/index.md): Compile 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…
- [Overview](https://recursiveai.org/oneshader/docs/overview/index.md): What 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 package](https://recursiveai.org/oneshader/docs/build-package/index.md): RecursiveAI.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 package](https://recursiveai.org/oneshader/docs/compiler/index.md): RecursiveAI.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 line](https://recursiveai.org/oneshader/docs/command-line/index.md): RecursiveAI.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 bindings](https://recursiveai.org/oneshader/docs/generated-bindings/index.md): What 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 format](https://recursiveai.org/oneshader/docs/reflection-format/index.md): The 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)](https://recursiveai.org/oneshader/docs/spirv-backend/index.md): 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 Language](https://recursiveai.org/oneshader/docs/msl-backend/index.md): How 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)](https://recursiveai.org/oneshader/docs/wgsl-backend/index.md): 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 representation](https://recursiveai.org/oneshader/docs/ir/index.md): The 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 parity](https://recursiveai.org/oneshader/docs/webgpu-parity/index.md): How 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 DXC](https://recursiveai.org/oneshader/docs/performance/index.md): OneShader 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.

## Reference

- [Changelog](https://recursiveai.org/oneshader/docs/changelog/index.md): What changed in each OneShader release, from the first preview to 1.2.0.

## Cookbook

- [All recipes](https://recursiveai.org/oneshader/cookbook/index.md): 18 short, task-first recipes with complete code.