Shaders
XnaFiddle compiles user HLSL .fx to KNI .mgfx entirely in the browser via the ShadowDusk.Wasm NuGet package (DXC + SPIRV-Cross WASM modules), then loads the result as an Effect through InMemoryContentManager. No MGCB/content pipeline, no server round-trip.
Build wiring
ShadowDusk.Wasm is a PackageReference conditioned to net10.0-browser (XnaFiddle.BlazorGL.csproj). It targets net8.0-browser1.0 in its own nuspec (its [JSImport] backends); a net10.0-browser consumer resolves it fine via NuGet's upward TFM compatibility, but a plain net10.0 reference still fails NU1201. This is the same browser-vs-test-build split as XnaFiddle.Core (issue #26): the test-only net10.0 build cannot reference it.
- The
SHADOWDUSK DefineConstants is set only for net10.0-browser. All shader-compile code is wrapped in #if SHADOWDUSK; the net10.0 build #ifs it out and CompileRegisteredShadersAsync becomes a no-op returning null.
- Version is pinned by
$(ShadowDuskVersion) in Directory.Build.props — the only file to touch when bumping (the number quoted in this skill drifts; read the prop for the live value). All ShadowDusk packages release in lockstep on one version, so this property feeds both the editor's ShadowDusk.Wasm reference and the exporter's PackageVersions.ShadowDusk (generated const) — because exported projects now compile their .fx at runtime via ShadowDusk too (issue #39, see "Export" below). 0.5.0+ is required for the exported path: it added InitializeAsync() + a synchronous Compile().
- All three packages (
ShadowDusk.Core / .Wasm / .Compiler) come from nuget.org — not the KniSB submodule (the nuget.config comment about "sibling ShadowDusk projects" is misleading; that's a historical CPM/NU1507 note). Confirm a version exists before bumping: https://api.nuget.org/v3-flatcontainer/shadowdusk.core/index.json. After a bump, only XnaFiddle.BlazorGL exercises the new package at build time (web/editor side); exported projects are built later by the end user, so the exporter just writes the version string.
- The DXC + SPIRV-Cross wasm modules ship inside the package as static web assets served automatically at
_content/ShadowDusk.Wasm/. Nothing to copy or configure.
Compile flow (Index.razor.cs -> CompileRegisteredShadersAsync)
Called from DoCompileAndRun before the game is built (around line 1007), so user code can Content.Load<Effect>("Name") immediately. Its await is deliberately outside the synchronous game-swap window (see the game-lifecycle skill for that window).
For each tab in _shaderTabs:
- Pull current HLSL via
monacoInterop.getModelValue.
new ShadowDusk.Wasm.WasmShaderCompiler().CompileAsync(source, options, _compileCts.Token) with CompilerOptions { Target = PlatformTarget.OpenGL, SourceFileName = fileName }.
- On failure, returns a formatted error string (joined
FxcFormattedMessage lines) -> caller shows "Shader compilation failed." and aborts the run.
- On success,
RegisterContentFile(bareName, result.Value.Data) registers the .mgfx bytes under the extension-stripped name.
Lazy DXC download: the loop is guarded by if (_shaderTabs.Count > 0). With no shader tabs, the WasmShaderCompiler is never constructed and the ~17 MB DXC wasm is never fetched.
Profile-agnostic output: PlatformTarget.OpenGL emits one .mgfx that loads under KNI Reach (WebGL1), HiDef (WebGL2), and desktop GL alike — a single compile works regardless of the game's GraphicsProfile. Web is GL-only: ShadowDusk in the browser can compile only OpenGL targets — it cannot emit DirectX output, and even the upcoming FNA DX9 .fxb support won't produce .fxb on web. Any DirectX/.fxb target requires a desktop-side compile.
Stale-effect cleanup: _lastCompiledShaders (a HashSet) tracks what was compiled last Run. After compiling, any bare name in the old set not in the current set is InMemoryContentManager.RemoveFiled, so a removed/renamed shader can't resolve old bytes via a stale Content.Load<Effect>.
Headless compile-checking & HLSL gotchas
- Compile-gate
.fx without the browser with the official ShadowDusk.Cli dotnet tool: ShadowDuskCLI <in.fx> <out.mgfx> /Profile:OpenGL. Its output is byte-identical to the editor's ShadowDusk.Wasm, so a green run is an authoritative check for a shader edit (gate edits without launching the app). /Profile:OpenGL is mandatory — the default is DirectX_11, which is not what the editor targets. Pin the tool to $(ShadowDuskVersion).
- Install the CLI to a short
--tool-path. From a deeply nested path its native DXC load fails with DllNotFoundException: dxcompiler.dll ... The filename or extension is too long (0x800700CE), which reads like a missing dependency but is only path length.
- Legacy LOD/sampling intrinsics are rejected on the OpenGL target.
tex2Dlod (and friends) won't compile; use the modern texture-object form Texture.SampleLevel(sampler, uv, lod). The compiler error names the rewrite.
Effect resolution (InMemoryContentManager)
Load<Effect> has a branch: new Effect(GetGraphicsDevice(), bytes). The .mgfx bytes carry MGFB magic (never XNB), so the XNB short-circuit skips them. Because RegisterContentFile stores under the bare name, Content.Load<Effect>("Grayscale") resolves the bytes registered for Grayscale.fx. See the file-loading skill for RegisterContentFile / the static _files store.
Editor tabs
The editor is tabbed: one C# program tab (CSharpTabName) plus one Monaco model per .fx, tracked in _shaderTabs (filenames including extension, e.g. Grayscale.fx). Shader models use the hlsl Monaco language.
Tab switching goes through monacoInterop.switchToModel (monaco-interop.js), which swaps the editor model via setModel(). Monaco does not persist per-model scroll/cursor across setModel(), so switchToModel saves the outgoing tab's saveViewState() into _viewStates[name] and restores the incoming tab's on the way in (issue #70). disposeModel/resetToCSharpOnly/createModel-replace clear stale entries, and renameModel carries the entry to the new name — so a reused tab name never inherits a closed tab's position.
| Operation |
Notes |
OpenShaderTabFromSourceAsync |
Creates/replaces the Monaco model; used by [+], example load, gist/snippet import, and drag-drop |
AddShaderTab |
[+] button; seeds DefaultShaderTemplate, auto-names Shader.fx, Shader1.fx, ... |
CloseShaderTab |
Confirms first (window.confirm) — closing disposes the model, source is unrecoverable |
CommitRenameAsync |
Inline rename; the filename minus .fx is the Content.Load<Effect> key, so renaming changes how user code refers to it |
ResetShaderTabsAsync |
Drops all shader tabs (used when loading an example/fiddle that brings its own or none) |
OnFileDropped |
A dropped .fx opens as a shader tab (10 MB limit) instead of routing to the asset list |
Examples
Shader examples are Examples/{Name}.cs plus flat-named assets (Examples/{Name}.{Shader}.fx, usually a KniIcon.png), registered in ExampleGallery.Catalog under "2D Shaders" / "3D Shaders". The example .cs files set GraphicsProfile.HiDef like every other example — shaders run HiDef. (The ExampleGallery.cs line-37 comment "run as Reach/WebGL1" is stale; the profile-agnostic .mgfx runs under whatever profile the game selects.)
An example may ship the same effect in both languages ({Name}.{Shader}.fx and {Name}.{Shader}.slang); the example browser's HLSL/Slang segmented control picks which one opens as a tab. Exactly one may open — both compile to the same bare content key — see ExampleGallery.SlangExamples (probed from the embedded resources, never a Catalog flag) and LoadExampleAssetsAsync/IsUnpickedShaderLanguage in Index.razor.cs.
User-facing pattern: Content.Load<Effect>("Name") in LoadContent, optionally effect.Parameters["X"]?.SetValue(...), then spriteBatch.Begin(SpriteSortMode.Immediate, BlendState.AlphaBlend, ..., effect). The examples draw an un-shaded pass first to prime SpriteBatch's vertex shader, which the pixel-only effects rely on.
How shaders travel
| Channel |
Shaders carried? |
Share URL (#code=...&shaders=...) |
Yes — _shareShaders JSON in a &shaders= fragment |
Snippet (#snippet=...) |
Yes — SnippetModel.Shaders (List<ShaderFile>). Not consumed by SnippetExpander; the page applies them separately via ApplyShaderFilesAsync |
| Gist |
Partly — the copy-to-clipboard puts only the C#; the UI warns the user to add each .fx as a separate gist file (same filename). Gist import reads every .fx file back into tabs |
| Export |
Yes (issue #39) — the .fx source ships in the export Content/ (or the Content Builder's Assets/, see below) and, by default, the exported project recompiles it at runtime via ShadowDusk, exactly like the editor. ProjectExporter.Export takes a shaders (name.fx -> HLSL) map; the export call site re-collects via CollectShaderFilesAsync(). Wired for desktop GL/DX (ShadowDusk.Compiler, PlatformTarget.OpenGL/DirectX), Blazor (ShadowDusk.Wasm, awaits InitializeAsync before the render loop), FNA (ShadowDusk.Compiler, PlatformTarget.Fna → legacy D3D9 .fxb, loaded by FNA's MojoShader Effect ctor — issue #54), Android (ShadowDusk.Compiler with on-device native backends — issue #88), MonoGame DesktopVK (ShadowDusk 0.12.0+ Vulkan backend), and MonoGame WindowsDX12 (ShadowDusk 0.14.0+ DirectX12 backend — issue #122). Only iOS is gated under ShadowDusk (ship .fx, no compiler wired) — issue #52. Opt-in alternative: Export's shaderCompileMode (default ShadowDusk) can be Native (renamed from ContentPipeline) to compile user .fx at build time via whichever ContentBuildMode content strategy is selected (classic MGCB's EffectProcessor, or the Content Builder's own pipeline) instead. See the project-export skill for the full two-axis (ContentBuildMode x ShaderCompileMode) model. |
ShaderFile (ShaderFile.cs) is the model: Name (filename incl. .fx) + Source (HLSL). CollectShaderFilesAsync snapshots open tabs into _shareShaders (refreshed on share/snippet build because shader edits don't fire the C#-only content callback). ApplyShaderFilesAsync clears stale tabs then re-opens the payload's shaders.
Key files
| File |
Role |
XnaFiddle.BlazorGL/Pages/Index.razor.cs |
CompileRegisteredShadersAsync, _shaderTabs, tab ops, _lastCompiledShaders, share/snippet/gist shader handling |
XnaFiddle.BlazorGL/Pages/Index.razor |
Tab strip, gist shader warning (200), export-dialog runtime-compile message (244) |
XnaFiddle.Core/ProjectExporter.cs |
Runtime shader export (issue #39): GetShaderExportInfo/SupportsRuntimeShaders, WriteShaderSources, the IShaderCompiler-seam content manager + per-platform compiler injection |
XnaFiddle.BlazorGL/InMemoryContentManager.cs |
Load<Effect> branch: new Effect(gd, bytes) from registered .mgfx |
XnaFiddle.Core/ShaderFile.cs |
Shader-tab model for share/snippet/gist payloads |
XnaFiddle.Core/SnippetModel.cs |
Shaders field on the snippet payload |
XnaFiddle.BlazorGL/ExampleGallery.cs |
Shaders category catalog entries |
XnaFiddle.BlazorGL/Examples/Shader*.{cs,fx} |
Example shaders + the Content.Load<Effect> usage pattern |
XnaFiddle.BlazorGL/XnaFiddle.BlazorGL.csproj |
ShadowDusk.Wasm ref (net10.0-browser), SHADOWDUSK gate |
Directory.Build.props |
$(ShadowDuskVersion) — single source of truth for editor + exported PackageVersions.ShadowDusk |
1---2name: shaders-23description: The in-browser HLSL shader (.fx) subsystem in XnaFiddle — ShadowDusk.Wasm compiling .fx to profile-agnostic .mgfx, the SHADOWDUSK build gate, shader editor tabs, Content.Load<Effect> resolution, example shaders, and how shaders travel in share/snippet/gist payloads. Load when working on shader compilation, .fx tabs, ShadowDusk, Effect loading, CompileRegisteredShadersAsync, the net10.0-browser vs net10.0 split, or shader examples.4---56# Shaders78XnaFiddle compiles user HLSL `.fx` to KNI `.mgfx` entirely in the browser via the **ShadowDusk.Wasm** NuGet package (DXC + SPIRV-Cross WASM modules), then loads the result as an `Effect` through `InMemoryContentManager`. No MGCB/content pipeline, no server round-trip.910## Build wiring1112- `ShadowDusk.Wasm` is a `PackageReference` **conditioned to `net10.0-browser`** (`XnaFiddle.BlazorGL.csproj`). It targets `net8.0-browser1.0` in its own nuspec (its `[JSImport]` backends); a `net10.0-browser` consumer resolves it fine via NuGet's upward TFM compatibility, but a plain `net10.0` reference still fails NU1201. This is the same browser-vs-test-build split as `XnaFiddle.Core` (issue #26): the test-only `net10.0` build cannot reference it.13- The `SHADOWDUSK` `DefineConstants` is set **only** for `net10.0-browser`. All shader-compile code is wrapped in `#if SHADOWDUSK`; the `net10.0` build `#if`s it out and `CompileRegisteredShadersAsync` becomes a no-op returning `null`.14- Version is pinned by `$(ShadowDuskVersion)` in `Directory.Build.props` — the **only** file to touch when bumping (the number quoted in this skill drifts; read the prop for the live value). All ShadowDusk packages release in lockstep on one version, so this property feeds **both** the editor's `ShadowDusk.Wasm` reference **and** the exporter's `PackageVersions.ShadowDusk` (generated const) — because exported projects now compile their `.fx` at runtime via ShadowDusk too (issue #39, see "Export" below). 0.5.0+ is required for the exported path: it added `InitializeAsync()` + a synchronous `Compile()`.15- All three packages (`ShadowDusk.Core` / `.Wasm` / `.Compiler`) come from **nuget.org** — *not* the KniSB submodule (the `nuget.config` comment about "sibling ShadowDusk projects" is misleading; that's a historical CPM/NU1507 note). Confirm a version exists before bumping: `https://api.nuget.org/v3-flatcontainer/shadowdusk.core/index.json`. After a bump, only `XnaFiddle.BlazorGL` exercises the new package at build time (web/editor side); exported projects are built later by the end user, so the exporter just writes the version string.16- The DXC + SPIRV-Cross wasm modules ship inside the package as static web assets served automatically at `_content/ShadowDusk.Wasm/`. Nothing to copy or configure.1718## Compile flow (`Index.razor.cs` -> `CompileRegisteredShadersAsync`)1920Called from `DoCompileAndRun` **before** the game is built (around line 1007), so user code can `Content.Load<Effect>("Name")` immediately. Its `await` is deliberately **outside** the synchronous game-swap window (see the `game-lifecycle` skill for that window).2122For each tab in `_shaderTabs`:231. Pull current HLSL via `monacoInterop.getModelValue`.242. `new ShadowDusk.Wasm.WasmShaderCompiler().CompileAsync(source, options, _compileCts.Token)` with `CompilerOptions { Target = PlatformTarget.OpenGL, SourceFileName = fileName }`.253. On failure, returns a formatted error string (joined `FxcFormattedMessage` lines) -> caller shows "Shader compilation failed." and aborts the run.264. On success, `RegisterContentFile(bareName, result.Value.Data)` registers the `.mgfx` bytes under the **extension-stripped** name.2728**Lazy DXC download:** the loop is guarded by `if (_shaderTabs.Count > 0)`. With no shader tabs, the `WasmShaderCompiler` is never constructed and the ~17 MB DXC wasm is never fetched.2930**Profile-agnostic output:** `PlatformTarget.OpenGL` emits one `.mgfx` that loads under KNI Reach (WebGL1), HiDef (WebGL2), and desktop GL alike — a single compile works regardless of the game's `GraphicsProfile`. **Web is GL-only:** ShadowDusk in the browser can compile only OpenGL targets — it cannot emit DirectX output, and even the upcoming FNA DX9 `.fxb` support won't produce `.fxb` on web. Any DirectX/`.fxb` target requires a desktop-side compile.3132**Stale-effect cleanup:** `_lastCompiledShaders` (a `HashSet`) tracks what was compiled last Run. After compiling, any bare name in the old set not in the current set is `InMemoryContentManager.RemoveFile`d, so a removed/renamed shader can't resolve old bytes via a stale `Content.Load<Effect>`.3334## Headless compile-checking & HLSL gotchas3536- **Compile-gate `.fx` without the browser** with the official `ShadowDusk.Cli` dotnet tool: `ShadowDuskCLI <in.fx> <out.mgfx> /Profile:OpenGL`. Its output is byte-identical to the editor's `ShadowDusk.Wasm`, so a green run is an authoritative check for a shader edit (gate edits without launching the app). `/Profile:OpenGL` is **mandatory** — the default is `DirectX_11`, which is not what the editor targets. Pin the tool to `$(ShadowDuskVersion)`.37- **Install the CLI to a short `--tool-path`.** From a deeply nested path its native DXC load fails with `DllNotFoundException: dxcompiler.dll ... The filename or extension is too long (0x800700CE)`, which reads like a missing dependency but is only path length.38- **Legacy LOD/sampling intrinsics are rejected on the OpenGL target.** `tex2Dlod` (and friends) won't compile; use the modern texture-object form `Texture.SampleLevel(sampler, uv, lod)`. The compiler error names the rewrite.3940## Effect resolution (`InMemoryContentManager`)4142`Load<Effect>` has a branch: `new Effect(GetGraphicsDevice(), bytes)`. The `.mgfx` bytes carry MGFB magic (never XNB), so the XNB short-circuit skips them. Because `RegisterContentFile` stores under the bare name, `Content.Load<Effect>("Grayscale")` resolves the bytes registered for `Grayscale.fx`. See the `file-loading` skill for `RegisterContentFile` / the static `_files` store.4344## Editor tabs4546The editor is tabbed: one C# program tab (`CSharpTabName`) plus one Monaco model per `.fx`, tracked in `_shaderTabs` (filenames including extension, e.g. `Grayscale.fx`). Shader models use the **`hlsl`** Monaco language.4748Tab switching goes through `monacoInterop.switchToModel` (`monaco-interop.js`), which swaps the editor model via `setModel()`. Monaco does **not** persist per-model scroll/cursor across `setModel()`, so `switchToModel` saves the outgoing tab's `saveViewState()` into `_viewStates[name]` and restores the incoming tab's on the way in (issue #70). `disposeModel`/`resetToCSharpOnly`/`createModel`-replace clear stale entries, and `renameModel` carries the entry to the new name — so a reused tab name never inherits a closed tab's position.4950| Operation | Notes |51|---|---|52| `OpenShaderTabFromSourceAsync` | Creates/replaces the Monaco model; used by `[+]`, example load, gist/snippet import, and drag-drop |53| `AddShaderTab` | `[+]` button; seeds `DefaultShaderTemplate`, auto-names `Shader.fx`, `Shader1.fx`, ... |54| `CloseShaderTab` | **Confirms first** (`window.confirm`) — closing disposes the model, source is unrecoverable |55| `CommitRenameAsync` | Inline rename; the filename minus `.fx` is the `Content.Load<Effect>` key, so renaming changes how user code refers to it |56| `ResetShaderTabsAsync` | Drops all shader tabs (used when loading an example/fiddle that brings its own or none) |57| `OnFileDropped` | A dropped `.fx` opens as a shader tab (10 MB limit) instead of routing to the asset list |5859## Examples6061Shader examples are `Examples/{Name}.cs` plus flat-named assets (`Examples/{Name}.{Shader}.fx`, usually a `KniIcon.png`), registered in `ExampleGallery.Catalog` under `"2D Shaders"` / `"3D Shaders"`. The example `.cs` files set `GraphicsProfile.HiDef` like every other example — shaders run HiDef. (The `ExampleGallery.cs` line-37 comment "run as Reach/WebGL1" is **stale**; the profile-agnostic `.mgfx` runs under whatever profile the game selects.)6263An example may ship the same effect in both languages (`{Name}.{Shader}.fx` **and** `{Name}.{Shader}.slang`); the example browser's HLSL/Slang segmented control picks which one opens as a tab. Exactly one may open — both compile to the same bare content key — see `ExampleGallery.SlangExamples` (probed from the embedded resources, never a `Catalog` flag) and `LoadExampleAssetsAsync`/`IsUnpickedShaderLanguage` in `Index.razor.cs`.6465User-facing pattern: `Content.Load<Effect>("Name")` in `LoadContent`, optionally `effect.Parameters["X"]?.SetValue(...)`, then `spriteBatch.Begin(SpriteSortMode.Immediate, BlendState.AlphaBlend, ..., effect)`. The examples draw an un-shaded pass first to prime SpriteBatch's vertex shader, which the pixel-only effects rely on.6667## How shaders travel6869| Channel | Shaders carried? |70|---|---|71| **Share URL** (`#code=...&shaders=...`) | Yes — `_shareShaders` JSON in a `&shaders=` fragment |72| **Snippet** (`#snippet=...`) | Yes — `SnippetModel.Shaders` (`List<ShaderFile>`). Not consumed by `SnippetExpander`; the page applies them separately via `ApplyShaderFilesAsync` |73| **Gist** | Partly — the copy-to-clipboard puts **only the C#**; the UI warns the user to add each `.fx` as a separate gist file (same filename). Gist **import** reads every `.fx` file back into tabs |74| **Export** | Yes (issue #39) — the `.fx` **source** ships in the export `Content/` (or the Content Builder's `Assets/`, see below) and, by default, the exported project recompiles it at runtime via ShadowDusk, exactly like the editor. `ProjectExporter.Export` takes a `shaders` (`name.fx -> HLSL`) map; the export call site re-collects via `CollectShaderFilesAsync()`. Wired for desktop GL/DX (`ShadowDusk.Compiler`, `PlatformTarget.OpenGL`/`DirectX`), Blazor (`ShadowDusk.Wasm`, awaits `InitializeAsync` before the render loop), FNA (`ShadowDusk.Compiler`, `PlatformTarget.Fna` → legacy D3D9 `.fxb`, loaded by FNA's MojoShader `Effect` ctor — issue #54), Android (`ShadowDusk.Compiler` with on-device native backends — issue #88), MonoGame DesktopVK (ShadowDusk 0.12.0+ Vulkan backend), and MonoGame WindowsDX12 (ShadowDusk 0.14.0+ DirectX12 backend — issue #122). Only iOS is **gated** under ShadowDusk (ship `.fx`, no compiler wired) — issue #52. **Opt-in alternative:** `Export`'s `shaderCompileMode` (default `ShadowDusk`) can be `Native` (renamed from `ContentPipeline`) to compile user `.fx` at build time via whichever `ContentBuildMode` content strategy is selected (classic MGCB's `EffectProcessor`, or the Content Builder's own pipeline) instead. See the `project-export` skill for the full two-axis (`ContentBuildMode` x `ShaderCompileMode`) model. |7576`ShaderFile` (`ShaderFile.cs`) is the model: `Name` (filename incl. `.fx`) + `Source` (HLSL). `CollectShaderFilesAsync` snapshots open tabs into `_shareShaders` (refreshed on share/snippet build because shader edits don't fire the C#-only content callback). `ApplyShaderFilesAsync` clears stale tabs then re-opens the payload's shaders.7778## Key files7980| File | Role |81|---|---|82| `XnaFiddle.BlazorGL/Pages/Index.razor.cs` | `CompileRegisteredShadersAsync`, `_shaderTabs`, tab ops, `_lastCompiledShaders`, share/snippet/gist shader handling |83| `XnaFiddle.BlazorGL/Pages/Index.razor` | Tab strip, gist shader warning (~200), export-dialog runtime-compile message (~244) |84| `XnaFiddle.Core/ProjectExporter.cs` | Runtime shader export (issue #39): `GetShaderExportInfo`/`SupportsRuntimeShaders`, `WriteShaderSources`, the `IShaderCompiler`-seam content manager + per-platform compiler injection |85| `XnaFiddle.BlazorGL/InMemoryContentManager.cs` | `Load<Effect>` branch: `new Effect(gd, bytes)` from registered `.mgfx` |86| `XnaFiddle.Core/ShaderFile.cs` | Shader-tab model for share/snippet/gist payloads |87| `XnaFiddle.Core/SnippetModel.cs` | `Shaders` field on the snippet payload |88| `XnaFiddle.BlazorGL/ExampleGallery.cs` | `Shaders` category catalog entries |89| `XnaFiddle.BlazorGL/Examples/Shader*.{cs,fx}` | Example shaders + the `Content.Load<Effect>` usage pattern |90| `XnaFiddle.BlazorGL/XnaFiddle.BlazorGL.csproj` | `ShadowDusk.Wasm` ref (net10.0-browser), `SHADOWDUSK` gate |91| `Directory.Build.props` | `$(ShadowDuskVersion)` — single source of truth for editor + exported `PackageVersions.ShadowDusk` |