---
title: "Disable HLSL optimization for shader debugging"
url: https://recursiveai.org/oneshader/cookbook/step-through-hlsl-without-optimization/
description: "Disable HLSL optimization with OneShader’s Optimize = false and emit full SPIR-V debug information to inspect local variables when stepping through a shader."
version: "1.7.1"
---

# Disable HLSL optimization for shader debugging

**OneShader** is a free, open-source HLSL compiler library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneShader) · [GitHub](https://github.com/recursive-ai-oss/oneshader-csharp) · [Docs](https://recursiveai.org/oneshader/docs/) · [Download example (.zip)](https://recursiveai.org/oneshader/cookbook/step-through-hlsl-without-optimization/step-through-hlsl-without-optimization.zip)

Use `Optimize = false` and full debug info to inspect locals in Vulkan SPIR-V. `Shader.hlsl` is in the zip.

```shell
dotnet add package RecursiveAI.OneShader
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
using OneShader;
var options = new CompileOptions {
    Optimize = false,
    DebugInfo = DebugInfoLevel.Full
};
var result = ShaderCompiler
    .CompileFile("Shader.hlsl", options);
foreach (var item in result.Diagnostics)
    Console.Error.WriteLine(item);
if (!result.Success) return 1;
var blob = result.Blobs[0].ToArray();
File.WriteAllBytes("debug.spv", blob);
Console.WriteLine($"debug.spv: {blob.Length} bytes");
return 0;
```

Unzip [the example](https://recursiveai.org/oneshader/cookbook/step-through-hlsl-without-optimization/step-through-hlsl-without-optimization.zip), then `dotnet run`.

The snippet writes `debug.spv` and prints:

```text
debug.spv: 3332 bytes
```

## The full program

`Shader.hlsl` has two locals, `x` and `shade`:

```hlsl
[shader("pixel")]
float4 PSMain(float4 pos : SV_Position) : SV_Target
{
    float x = pos.x * 0.25;
    float shade = x + pos.y;
    return float4(shade, shade, shade, 1);
}
```

The project compiles the same entry point twice with full debug information, changing only `Optimize`. That keeps the effect of the optimization setting separate from the effect of adding debug information.

```csharp
using OneShader;

foreach (bool optimize in new[] { false, true })
{
    var result = ShaderCompiler.CompileFile("Shader.hlsl", new()
    {
        Targets = [CompileTarget.SpirV],
        DebugInfo = DebugInfoLevel.Full,
        Optimize = optimize
    });
    foreach (var item in result.Diagnostics)
        Console.Error.WriteLine(item);
    if (!result.Success) return 1;

    var blob = result.Find("PSMain", CompileTarget.SpirV)!.ToArray();
    string file = optimize ? "optimized.spv" : "debug.spv";
    File.WriteAllBytes(file, blob);
    Console.WriteLine($"{file}: {blob.Length} bytes");
}
return 0;
```

`dotnet run` prints:

```text
debug.spv: 3332 bytes
optimized.spv: 1976 bytes
```

Load `debug.spv` in your Vulkan application, then [capture a frame in RenderDoc and step through the shader](https://recursiveai.org/oneshader/cookbook/debug-hlsl-renderdoc/).

If the shader doesn’t compile, the project prints the compiler diagnostics and stops before writing that variant. This run compiles the shader; it doesn’t launch a debugger or execute the shader on a GPU.

## Variations

If you need source lines but not local variable records, use `Lines`. Replace the options in the snippet at the top with:

```csharp
var options = new CompileOptions {
    Optimize = false,
    DebugInfo = DebugInfoLevel.Lines
};
```

## Related recipes

- [Debug HLSL in RenderDoc](https://recursiveai.org/oneshader/cookbook/debug-hlsl-renderdoc/)
- [Compile HLSL to SPIR-V](https://recursiveai.org/oneshader/cookbook/hlsl-to-spirv/)

## The short answer

Set `DebugInfo = DebugInfoLevel.Full` and `Optimize = false` when compiling HLSL for source-level debugging with Vulkan. In [OneShader’s debugging guide](https://recursiveai.org/oneshader/docs/debugging/#optimization-and-debug-information), the key distinction is that “the optimizer keeps running when debug information is on.” Set both options: one adds the source and variable records, and the other preserves the local storage those records describe. For Vulkan SPIR-V, these settings correspond to `-Od -fspv-debug=vulkan-with-source`; `-Zi` alone adds source lines but not variable records.

## Why are my local variables optimized out when debugging a shader?

Optimization can inline calls, fold expressions, or promote a local from memory to a register. A debugger can still have a source line for an instruction even when the original variable has no storage it can display. With full SPIR-V debug information, a `DebugDeclare` record links a source variable to storage; the guide explains that a local promoted to a register by the optimizer has no such record. Turning optimization off gives the debugger declarations for the locals and parameters and keeps stepping closer to the original statements. For this shader, the unoptimized file has declarations for `pos`, `x`, and `shade`; the optimized file has none. The line-only level supplies source locations without those declarations. Full variable records in this recipe are specific to SPIR-V; OneShader emits `#line` directives for Metal and leaves WGSL unchanged when you select a debug information level.

## How do I turn on debug information and turn off HLSL optimization only in Debug builds?

If you compile through the runtime API, select both options for the shader build you want to inspect, and keep the regular shader build separate. If your project already uses the [OneShader build package](https://recursiveai.org/oneshader/docs/build-package/), its [Debug-build settings](https://recursiveai.org/oneshader/docs/debugging/#in-debug-builds-only) are `OneShaderDebugInfo` set to `true` and `OneShaderOptimize` set to `false`, in a property group conditioned on `Debug`. Full debug info embeds the shader source; don’t strip the records from the SPIR-V sent to the debugger. The two file sizes above are for this shader, not a rule for how much disk space another shader will need.
