Glossary

Plain-language definitions of the shader and compiler terms used across these docs. You don't need most of these to use ShadowDusk; they're here so the deeper pages can stay precise.

File types

  • .fx — an HLSL effect source file: the shader code you write (techniques, passes, vertex/pixel shaders).
  • .mgfx — the compiled effect MonoGame and KNI load via new Effect(graphicsDevice, bytes). This is ShadowDusk's main output (the same thing mgfxc produces).
  • .fxb — the compiled effect FNA loads: a legacy Direct3D 9 "fx_2_0" effect binary. ShadowDusk produces this for the FNA target instead of .mgfx.
  • Content Builder (MonoGame 3.8.5) — the code-centric content project MonoGame 3.8.5 made the template default: a C# console project whose ContentBuilder subclass lists what to build, replacing the .mgcb file. ShadowDusk plugs into it through the ShadowDusk.ContentPipeline library (new ShadowDuskEffectImporter(), new ShadowDuskEffectProcessor()); the .mgcb/MGCB route uses ShadowDusk.MgcbPlugin instead. Both compile the same importer/processor.
  • .xnb — the Content Pipeline container that wraps a .mgfx (or any other content), loaded via Content.Load<Effect>. ShadowDusk can emit it directly — CompiledShader.ToXnb(), or an .xnb output path on the CLI — so Content.Load<Effect> works with no MGCB and no consumer code change; the payload inside is the same .mgfx bytes.

Formats and containers

  • MGFX — MonoGame's compiled-effect format. v10 is the default ShadowDusk emits and loads on MonoGame 3.8.1.263+ (the measured floor) and KNI; v11 is a newer optional container for MonoGame 3.8.5+.
  • KNIFX — KNI's own newer effect container, an optional target: v11 for KNI v4.02+, v12 (kni-knifx-v12) for KNI 4.3.x only.
  • DesktopGL4 — MonoGame 3.8.6's native OpenGL 4.1-core runtime. It loads the same OpenGL .mgfx as DesktopGL; ShadowDusk's GL output is render-proven on it.
  • fx_2_0 — the legacy Direct3D 9 effect format FNA uses (Shader Model 3 and below).
  • Vulkan / DesktopVK — MonoGame 3.8.5's Vulkan platform (DesktopVK). ShadowDusk's Vulkan target emits a .mgfx with profile byte 80 (matching MonoGame's own VulkanShaderProfile) carrying SPIR-V directly; validated end-to-end in a real DesktopVK Effect. MonoGame-only — KNI has no Vulkan platform.
  • DirectX 12 / WindowsDX12 — MonoGame 3.8.5's DirectX 12 platform (WindowsDX12). ShadowDusk's DirectX 12 target emits a .mgfx with profile byte 2 carrying DXIL (SM6) directly; validated end-to-end in a real WindowsDX12 Effect. MonoGame-only — KNI has no DirectX 12 platform.
  • Shader Model (SM) — a versioned GPU feature level. SM3 and below are the old Direct3D 9 era (FNA); SM5 is Direct3D 11; SM6 is DXIL (Vulkan and DirectX 12). Higher numbers mean more features.
  • SkSL — Skia's own shading language, the text SKRuntimeEffect accepts. ShadowDusk's SkslConverter converts a pixel-only .fx to SkSL text, an additive output alongside (not a replacement for) .mgfx/.fxb. There is no .mgfx-style container or version byte for it, and no mgfxc-equivalence claim — SkiaSharp is a different runtime with no reference compiler of its own.
  • raylib glsl330 — the desktop GLSL 3.30 profile raylib (and Raylib-cs) loads fragment shaders in, with fixed interface names: fragTexCoord and fragColor in, finalColor out, the draw texture on texture0. ShadowDusk's RaylibConverter converts a single-pass, pixel-only .fx to it, an additive output alongside .mgfx/.fxb (not a replacement). raylib has no reference compiler, so it is proven by rendered-image fidelity against the same .fx on real MonoGame OpenGL, never mgfxc-equivalence.

Intermediate representations

  • SPIR-V — a portable, binary shader intermediate language. ShadowDusk compiles HLSL to SPIR-V, then converts that to GLSL for the OpenGL path. For the Vulkan target the SPIR-V is the shipped shader payload — the .mgfx carries it directly, no GLSL conversion.
  • DXIL — the binary intermediate DXC emits for Shader Model 6 (Direct3D 12). Carried as-is (no DXBC conversion) for the DirectX 12 target. The DX11 runtime can't load it, which is why ShadowDusk doesn't use DXC for the DX11 path.
  • GLSL — the OpenGL Shading Language (source text). What a .mgfx carries for the OpenGL, WebGL, and Android targets.
  • DXBC — Direct3D bytecode, the compiled GPU program the DirectX 11 runtime loads. What a DirectX .mgfx carries.

Tools (the compilers)

  • mgfxc — MonoGame's stock, Windows-only effect compiler. ShadowDusk is a drop-in replacement for it.
  • fxc — Microsoft's classic HLSL compiler (fxc.exe, part of the Windows DirectX SDK), the original reference for DirectX and FNA output.
  • DXC — Microsoft's modern HLSL compiler (the DirectX Shader Compiler). ShadowDusk uses it to turn HLSL into SPIR-V.
  • SPIRV-Cross — Khronos's tool that converts SPIR-V into GLSL. ShadowDusk uses it for the OpenGL path.
  • vkd3d-shader — a cross-platform HLSL-to-DXBC compiler from the Wine project. ShadowDusk's default DirectX backend, so DirectX compiles work off Windows too.
  • d3dcompiler_47 — a Microsoft HLSL compiler shipped as a system DLL on Windows. An optional, most-fxc-faithful DirectX backend.
  • MojoShader — the runtime that loads legacy GLSL / D3D9 effects in MonoGame's OpenGL path and in FNA. ShadowDusk's output matches the dialect it expects.
  • SkiaSharp — the .NET binding for Google's Skia 2D graphics library. Its SKRuntimeEffect API loads and runs SkSL shader text; ShadowDusk's SkslConverter targets it as an output, and SkiaSharp is a test- and validation-only dependency (CPU raster) used to validate the emitted SkSL renders correctly, including against the same .fx in real KNI (validation/SkiaVsKni).
  • Raylib-cs — the C# binding for raylib, a C game library with its own GL renderer. Raylib.LoadShaderFromMemory(null, fs) loads a fragment shader behind raylib's built-in vertex shader; ShadowDusk's RaylibConverter targets that call, and Raylib-cs is a validation-only dependency (validation/RaylibRoute), never one any shipped package takes.
  • Slang — a shading language from shader-slang. ShadowDusk accepts .slang source as an input format (alongside .fx) in two tiers. The free default, built into ShadowDusk.Compiler, accepts the HLSL-compatible subset: a pure managed text transform converts it to .fx text before the normal pipeline compiles it, with no Slang binary shipped or run anywhere. The optional ShadowDusk.Slang package accepts genuine Slang — import, generics, interface conformances — by bundling the real slangc compiler and routing its HLSL emission to the same unchanged pipeline.
  • slangc — the real Slang compiler's own command-line tool. Two distinct roles: as a test-time oracle for the free subset frontend above (like fxc/mgfxc elsewhere), never shipped or invoked by the product, cross-validating that ShadowDusk's Slang corpus is genuine Slang and that ShadowDusk's reading of it agrees with slangc's own HLSL emission; and as the real compiler the optional ShadowDusk.Slang package bundles and invokes (win-x64, linux-x64, osx-x64, osx-arm64) to compile genuine Slang source for a consumer who opts in. In the browser that same pinned slangc runs in-process as WebAssembly (ShadowDusk.Slang.Wasm), driven by the identical command line, because a browser cannot spawn a process.

Concepts

  • oracle — a trusted reference output you compare against to check correctness. ShadowDusk treats fxc / d3dcompiler_47 (and mgfxc) as oracles: the "right answer" its output should match.
  • faithful — producing output that behaves and renders the same as the reference compiler's, rather than a re-implementation that's merely close. ShadowDusk's pipeline drives the same core compilers (DXC, vkd3d) the references use.
  • RID — Runtime Identifier, .NET's name for a platform (for example win-x64, linux-x64, osx-arm64, android-arm64). Native binaries ship per RID.
  • Reach / HiDef — MonoGame/KNI GraphicsProfile settings (a runtime feature level, not a compile target). An MGFX .mgfx serves both. A KNIFX .knifx records each shader's model and KNI refuses one above the profile's ceiling (Reach 2.0, HiDef 3.0), so a KNIFX effect built at ps_3_0 or *_4_0_level_9_3 loads on HiDef but not on Reach; ps_2_0 or *_4_0_level_9_1 loads on both.
Edit this page