Recursive AI

HLSL compiler diagnostics: original file and line

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

Read errors in Color.hlsli, included by Shader.hlsl. Both files are in the zip.

Terminal
dotnet add package RecursiveAI.OneShader

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using OneShader;
var result = ShaderCompiler
    .CompileFile("Shader.hlsl");
foreach (var item in result.Diagnostics)
    Console.WriteLine(item);
return result.Success ? 0 : 1;

The diagnostic names the included file, line 3, column 12:

Text
Color.hlsli(3,12): error OSH0300: 'missingColor' is not declared. Declare it before this use, or check the spelling.

Keep both files in the same folder as the project. Here is Shader.hlsl:

HLSL
#include "Color.hlsli"
[shader("pixel")]
float4 PSMain() : SV_Target { return Tint(); }

And Color.hlsli:

HLSL
float4 Tint()
{
    return missingColor;
}

The compile error is returned in Diagnostics; the program exits with code 1 because Success is false.

Unzip the example, then dotnet run.

Variations

Use the structured location instead of parsing the message. Replace the loop in the snippet at the top with this one to print Color.hlsli:3:12:

C#
foreach (var item in result.Diagnostics)
{
    var span = item.Span;
    if (span.IsKnown)
        Console.WriteLine($"{span.Path}:{span.Line}:{span.Column}");
}

The short answer

Compile the main shader with ShaderCompiler.CompileFile and read CompileResult.Diagnostics. The compiler guide says errors are “returned as diagnostics with file, line and column.” Here the compiler reads the include and reports Color.hlsli(3,12) for the use of missingColor, rather than reporting a line in the main shader or in a flattened copy of the source.

How do I read the file, line, and column in an HLSL error?

In Color.hlsli(3,12), the first number is the line and the second is the column. Both start at 1. In the example, column 12 is the m of missingColor; open the include there, not the line that calls Tint(). The text after the position gives the severity, a stable diagnostic code (OSH0300 here), and a message. For an editor or build integration, use the structured Span fields. Span.IsKnown can be false for a diagnostic without a file location; show its message without trying to jump to a file. Columns count UTF-16 code units, so convert the column if your editor uses a different position encoding.

What if the HLSL compiler can’t open an include file?

A missing include is different from an error inside an include. If the compiler can’t find the file, start at the #include in the file that requested it. OneShader’s missing-include diagnostic lists the paths it searched. For the quoted include in this recipe, put Color.hlsli next to Shader.hlsl. If shared headers live in a separate directory, pass it in CompileOptions.IncludeDirectories, as shown in the compiler guide. If the reported path already names Color.hlsli and the message is about missingColor, the include was found; changing the search path won’t fix the undeclared name.

All oneshader recipes