---
title: "oneshader"
url: https://recursiveai.org/oneshader/
description: "An HLSL compiler for .NET, written in C# with no dependency beyond .NET itself. Modern HLSL for vertex, pixel and compute shaders in; SPIR-V, Metal Shading Language and WGSL out, compiled during dotnet build with C# bindings that match the shader. MIT or Apache-2.0."
---

# oneshader

An HLSL compiler for .NET, written in C# with no dependency beyond .NET itself. Modern HLSL goes in; SPIR-V, Metal Shading Language and WGSL come out, during `dotnet build`.

```sh
dotnet add package RecursiveAI.OneShader.Build
```

- [Getting started](https://recursiveai.org/oneshader/docs/getting-started/)
- [Docs](https://recursiveai.org/oneshader/docs/)
- [Cookbook](https://recursiveai.org/oneshader/cookbook/)
- [Articles](https://recursiveai.org/oneshader/articles/)
- [GitHub](https://github.com/recursive-ai-oss/oneshader-csharp)
- [NuGet](https://www.nuget.org/packages/RecursiveAI.OneShader.Build)

## A quick look

Put `Shaders/Sprite.hlsl` in a project. After `dotnet build`, the compiled shader and C# that matches its layout are in your assembly, with no reflection and no file I/O at run time.

[The generated bindings](https://recursiveai.org/oneshader/docs/generated-bindings/)

*Program.cs · C#*

```
using MyGame.Shaders;   // <RootNamespace>.Shaders
 
// embedded SPIR-V
ReadOnlySpan<byte> vs = Sprite.VSMain.SpirV;
// explicit layout, Size = 64
var frame = new Sprite.Frame { ViewProjection = camera };
uint set = Sprite.Bindings.Atlas.Set, binding = Sprite.Bindings.Atlas.Binding;
```

### Shader errors are build errors

A mistake shows up on the HLSL line with a stable code, such as `error OSH0300: 'Atlass' is not declared. Did you mean 'Atlas'?`, not as a black screen at run time.

### C# that matches the shader

Constant buffers, vertex inputs and bindings become blittable structs whose offsets equal the compiled shader’s, so a CPU/GPU layout mismatch fails the build.

### Three targets from one front end

SPIR-V for Vulkan 1.2+ by default; Metal Shading Language and WGSL are opt-in per project. A feature a target can’t express is a diagnostic naming the target.

### Checked against DXC and real GPUs

SPIR-V is validated with `spirv-val` and run on the GPU next to DXC’s output. WGSL goes through naga and a browser WebGPU run, MSL through Apple’s compiler and Metal.

## About 2.4× faster than DXC as a NativeAOT binary

Compiling 68 corpus entry points, one process each, against the released DXC binary with SPIR-V output, warm. Every one of the 68 is faster.

[Every result and the method](https://recursiveai.org/oneshader/docs/performance/)

## The packages

- **.Build**: `RecursiveAI.OneShader.Build` compiles your `*.hlsl` files during `dotnet build`, embeds the targets you pick (`OneShaderTargets`), builds shader variants from keyword axes and generates the C# bindings.
- **The compiler**: `RecursiveAI.OneShader` compiles at run time, for tools and hot reload, with a layout-compatibility check and a compile cache.
- **.Tool**: `RecursiveAI.OneShader.Tool` is the `oneshader` command, with DXC’s core flags, for CMake, Make and scripts.
- **Shaders**: Vertex, pixel and compute shaders in modern HLSL, HLSL 2021 templates included. Wave and quad intrinsics on all three targets, specialization constants, and 16-bit and 64-bit types where the target has them.
- **Pipeline layouts**: Plain-data helpers turn a shader into the Vulkan, Metal or WebGPU layouts a renderer creates.
- **Safe on text you didn’t write**: Bad input yields diagnostics, never an exception or a stack overflow, and the front end is fuzzed. No `unsafe` code and no reflection.
- **Version**: 1.2.0, the same for all three packages.
- **.NET**: .NET 10, built with the .NET SDK. NativeAOT and trimming are supported. MIT or Apache-2.0.

## Go further

- [GitHub](https://github.com/recursive-ai-oss/oneshader-csharp)
- [NuGet](https://www.nuget.org/packages/RecursiveAI.OneShader.Build)
- [Build package](https://recursiveai.org/oneshader/docs/build-package/)
- [Compiler](https://recursiveai.org/oneshader/docs/compiler/)
- [Command line](https://recursiveai.org/oneshader/docs/command-line/)
- [Generated bindings](https://recursiveai.org/oneshader/docs/generated-bindings/)
- [Performance](https://recursiveai.org/oneshader/docs/performance/)
- [Changelog](https://recursiveai.org/oneshader/docs/changelog/)