Interface IShaderCompiler

Namespace

ShadowDusk.Core

Assembly

ShadowDusk.Core.dll

The core consumer contract: compiles HLSL .fx source into a compiled effect entirely in memory, with no fxc.exe, mgfxc, Wine, or Windows SDK required. For the MonoGame/KNI targets the output is a .mgfx effect; for Fna it is the D3D9 fx_2_0 effects binary (.fxb) FNA loads. This is the product's public entry point — add the library to a project and call CompileAsync(string, CompilerOptions, CancellationToken) at runtime or build time.

public interface IShaderCompiler

Remarks

The same contract abstracts every delivery shape: the in-process desktop library (EffectCompiler), the CLI, and the in-browser WASM compiler all implement it and produce the same bytes for a given source and target. Output is behaviorally equivalent to the reference compiler's (mgfxc for MonoGame/KNI targets; fxc /T fx_2_0 for FNA) — it loads into the real runtime's Effect and renders the same image — but is not byte-identical to it (different compilers). Determinism is ShadowDusk's own reproducibility only: the same ShadowDusk version, source, and target yield the same bytes.

Methods

Compile(string, CompilerOptions, CancellationToken)

Synchronous counterpart of CompileAsync(string, CompilerOptions, CancellationToken): compiles the given HLSL source into a compiled effect for the target in options, on the calling thread, returning the effect bytes in memory. Intended for synchronous call sites that cannot await — e.g. compiling inside MonoGame/KNI's Content.Load<Effect>.

Result<CompiledShader, ShaderError[]> Compile(string hlslSource, CompilerOptions options, CancellationToken cancellationToken = default)

Parameters

hlslSource string

The HLSL .fx effect source to compile.

options CompilerOptions

Compilation settings: the PlatformTarget, include resolution, debug mode, MGFX version, and DirectX DXBC backend selection.

cancellationToken CancellationToken

Token observed between pipeline stages.

Returns

Result<CompiledShader, ShaderError[]>

A Result<T, TError> that is either a successful CompiledShader (the target plus its effect bytes) or, on failure, an array of ShaderError with source file, line, column, code, and message. Compilation failures are returned as errors, not thrown as exceptions.

Remarks

Runs the exact same pipeline as CompileAsync(string, CompilerOptions, CancellationToken) (one shared implementation, never a fork), so for the same source, options, and compiler version the output bytes are identical. The whole compile runs on the calling thread and never blocks on a task internally — safe on single-threaded browser WASM. Precondition on the browser/WASM host: InitializeAsync(CancellationToken) must have completed first (the WASM compiler modules load asynchronously); otherwise this returns a clear ShaderError (code SD1903) telling the caller to await InitializeAsync(CancellationToken). On desktop no prior initialization is required.

CompileAsync(string, CompilerOptions, CancellationToken)

Compiles the given HLSL source into a compiled effect for the target in options, returning the effect bytes in memory.

Task<Result<CompiledShader, ShaderError[]>> CompileAsync(string hlslSource, CompilerOptions options, CancellationToken cancellationToken = default)

Parameters

hlslSource string

The HLSL .fx effect source to compile.

options CompilerOptions

Compilation settings: the PlatformTarget, include resolution, debug mode, MGFX version, and DirectX DXBC backend selection.

cancellationToken CancellationToken

Token used to cancel a long-running compile.

Returns

Task<Result<CompiledShader, ShaderError[]>>

A Result<T, TError> that is either a successful CompiledShader (the target plus its effect bytes) or, on failure, an array of ShaderError with source file, line, column, code, and message. Compilation failures are returned as errors, not thrown as exceptions.

InitializeAsync(CancellationToken)

One-time warm-up that makes the synchronous Compile(string, CompilerOptions, CancellationToken) usable from a synchronous call site. Idempotent and safe to await repeatedly. On the browser/WASM host this loads and instantiates every WASM compiler module a subsequent Compile(string, CompilerOptions, CancellationToken) of any supported target needs (DXC, SPIRV-Cross, and vkd3d-shader); on desktop it is effectively a no-op (the native compilers load lazily on first use).

Task InitializeAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Token used to cancel the warm-up.

Returns

Task

A task that completes when the compiler is ready for synchronous compiles.

Remarks

Await this once from a legal async context — e.g. the Blazor bootstrap or an async Main — before calling Compile(string, CompilerOptions, CancellationToken) from synchronous code such as MonoGame/KNI's Content.Load<Effect>. Never block on it (.Result / .Wait()): on single-threaded browser WASM that is the exact sync-over-async deadlock this API exists to avoid. A failure to load a required module (e.g. the module asset cannot be fetched) is thrown from the returned task — loudly, with the underlying loader diagnostics.