Class CompilerOptions

Namespace

ShadowDusk.Core

Assembly

ShadowDusk.Core.dll

Settings that control a single CompileAsync(string, CompilerOptions, CancellationToken) call: the target backend, how #include directives are resolved, debug output, the MGFX container version, and (for DirectX) which DXBC backend to use.

public sealed class CompilerOptions

Inheritance

object

CompilerOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Properties

AdditionalIncludePaths

Additional directories searched, in order, when resolving #include directives. Equivalent to the CLI's /I flag.

public IReadOnlyList<string> AdditionalIncludePaths { get; init; }

Property Value

IReadOnlyList<string>

Container

Which effect container to emit. Defaults to Mgfx (MGFX v10), which loads on every MonoGame/KNI runtime, the seamless default. Set Knifx to opt into KNI's additive KNIFX v11 container (KNI v4.02+). This is a non-required escape hatch / additive target, never needed for correct v10 output. Ignored for Fna.

public EffectContainer Container { get; init; }

Property Value

EffectContainer

Debug

When true, compiles with debug information enabled. Deliberately a no-op for Fna: MojoShader is stricter on fxc debug-style codegen, so the FNA path always compiles optimized — Debug can never produce a .fxb the FNA runtime rejects.

Debug output depends only on the source and these options, never on the files on the host's disk: the source text embedded in SPIR-V debug information (Vulkan, and the SPIR-V behind OpenGL) is the text ShadowDusk compiled, on every host.

public bool Debug { get; init; }

Property Value

bool

Defines

User preprocessor macros injected into the compile after the platform macros — the library-level equivalent of mgfxc's /Defines: flag (which the CLI maps here). They ride through both macro renderers (the #define prepend and the DXC -D flags), so every backend sees them. Empty by default.

public IReadOnlyList<UserDefine> Defines { get; init; }

Property Value

IReadOnlyList<UserDefine>

DxbcBackend

Which backend compiles HLSL to SM5 DXBC when Target is DirectX. Defaults to Vkd3d, the cross-platform shipping backend: it runs on every desktop OS and is host-independent, so a default DirectX compile produces the same bytes on Linux, macOS, and Windows. Set D3DCompiler to opt in to the Windows-only d3dcompiler_47 correctness oracle (it hard-fails off Windows). Ignored for non-DirectX targets — Fna always uses vkd3d-shader. On the browser/WASM host this option is moot: WasmShaderCompiler always compiles DXBC via the vkd3d-shader WASM backend (there is no d3dcompiler_47 in a browser), which matches the desktop default.

public DxbcBackend DxbcBackend { get; init; }

Property Value

DxbcBackend

EmbeddedSourceFileName

The source-file string stored inside the compiled effect, for the containers that have one (MGFX v11: always for DirectX12 and Vulkan, and for any target compiled with MgfxVersion 11). The runtime only ever shows it in shader error messages; it has no effect on rendering.

Defaults to null, which stores SourceFileName exactly as passed (what mgfxc does), or <unknown> when that is null too. Only null falls back: any other value is stored verbatim, so an empty string stores an empty string. Set it when the name the compiler needs is not a name the output should carry: a build tool that compiles from absolute paths can keep SourceFileName absolute, so #include resolution and ShaderError locations stay exact, while the effect records a stable string and stops changing with the checkout directory. ShadowDusk's own MonoGame content processor, and the CLI when it writes an .xnb, set it to <unknown>, which is what MonoGame's stock EffectProcessor writes.

This never changes diagnostics, include resolution, or the debug information emitted under Debug, all of which use SourceFileName. Ignored by the containers with no such field (MGFX v10, KNIFX, FNA fx_2_0).

public string? EmbeddedSourceFileName { get; init; }

Property Value

string

IncludeResolver

Optional custom resolver for #include directives. When null, includes are resolved relative to SourceFileName and AdditionalIncludePaths. Supply an in-memory resolver to compile without touching disk (e.g. in WASM/in-browser scenarios).

public IIncludeResolver? IncludeResolver { get; init; }

Property Value

IIncludeResolver

MgfxVersion

The MGFX container version to emit. Defaults to 10, which loads across the supported MonoGame/KNI runtimes (the backwards-compatible choice). Ignored for Fna, whose output is the D3D9 fx_2_0 container, not MGFX. Also ignored when Container is Knifx.

public int MgfxVersion { get; init; }

Property Value

int

Profile

An optional, render-proven CapabilityProfile naming a full (runtime, format) contract: when set it selects the effect container/version and the GL ShaderDialect, overriding Container / MgfxVersion. Defaults to null, which reproduces today's behavior exactly (the container comes from Container / MgfxVersion and the dialect from Target). A profile is never required for correct output, only an additive, named convenience the runtime-detection helper also returns.

public CapabilityProfile? Profile { get; init; }

Property Value

CapabilityProfile

SourceFileName

The logical source file name used for include resolution and for the file path reported in ShaderError diagnostics. Optional when compiling a string literal in memory.

It can also reach the output bytes. An MGFX v11 container stores a source-file string per shader, and DirectX12 and Vulkan are always v11 (as is any target compiled with MgfxVersion 11). Unless EmbeddedSourceFileName says otherwise, that string is this value exactly as passed, which is what mgfxc does with its own source argument: pass an absolute path and the compiled effect carries it, and changes with it. With Debug set, the same name also goes into the SPIR-V / DXIL debug information. MGFX v10, KNIFX and the FNA fx_2_0 container store no source name, so OpenGL, DirectX and Fna output does not depend on it.

public string? SourceFileName { get; init; }

Property Value

string

Target

The platform backend to compile for. Defaults to OpenGL. Note this differs from the CLI's default profile (DirectX_11).

public PlatformTarget Target { get; init; }

Property Value

PlatformTarget

Methods

WithGraphicsTarget(PlatformTarget)

Returns a copy with Target replaced by graphicsTarget, preserving every other setting. The pipeline uses this to apply a GraphicsTarget (a profile fully specifies its output backend, so a set Profile determines the backend).

public CompilerOptions WithGraphicsTarget(PlatformTarget graphicsTarget)

Parameters

graphicsTarget PlatformTarget

Returns

CompilerOptions