ShaderLab

HDR / WCG / SDR shader effect development & debugging tool

A WinUI 3 desktop application (C++/WinRT) for developing, testing, and debugging Direct2D shader effects with full HDR and wide color gamut support.

---

Installing a Release Build

Release builds ship as unsigned MSIX packages — no signing certificate needed, but Developer Mode must be on.

1. Enable Developer Mode: Settings → Privacy & security → For developers → Developer Mode.
2. Download the architecture-matched zip from the GitHub Releases page:
   • ShaderLab-<version>-x64.zip for AMD64 / Intel
   • ShaderLab-<version>-arm64.zip for ARM64 (Snapdragon X / Surface Pro)
3. Extract and run Install.ps1 from an elevated PowerShell (see the limitation below):

   .\Install.ps1

4. Launch ShaderLab from the Start menu.

Install.ps1 calls Add-AppxPackage -AllowUnsigned, which installs unsigned MSIX packages on systems with Developer Mode enabled. ShaderLab requires Windows 11 22H2 (build 22621) or later — the display pipeline uses WinRT AdvancedColorInfo via desktop interop, which first shipped there. The script installs the bundled dependency packages (Microsoft VCLibs, Windows App Runtime) for the host architecture first, then ShaderLab itself.

⚠️ Known limitation — admin is required (unsigned + full-trust). ShaderLab is a full-trust packaged app: its main app and the background MCP Hub both declare Windows.FullTrustApplication (executable activations). Per Microsoft's unsigned-package rules, an unsigned package containing executable content can only be installed for all users, which requires elevation — a per-user, non-elevated Add-AppxPackage -AllowUnsigned fails with 0x80073D2B ("an unsigned package cannot include Executable activations"). Run Install.ps1 from an elevated PowerShell. A signed release would install per-user with no admin; signing the release with a real code-signing certificate is the cleaner long-term fix (tracked as a release-process gap).

The release manifest carries the special OID 2.25.311729368913984317654407730594956997722=1 (Windows' "unsigned namespace") that allows -AllowUnsigned. The OID is injected by the release workflow only — the in-repo manifest stays plain CN=ShaderLab so signed F5 deploys keep working locally.

---

Local Development

Clone recursively — the two native dependencies (exprtk, miniz, both MIT) are git submodules under third_party/:

git clone --recurse-submodules https://github.com/<owner>/ShaderLab.git

On an existing clone: git submodule update --init --recursive.

Then open ShaderLab.slnx and F5 (Debug | x64, startup project = ShaderLab) to deploy and launch the packaged app. NuGet restores automatically, and MSBuild auto-runs scripts/EnsureDevCert.ps1 on first build to generate a self-signed CN=ShaderLab cert and import it into TrustedPeople for F5 deploy — the project ships without a code-signing certificate.

If the submodules are missing, the build stops with an actionable error rather than a cascade of missing-header failures.

See docs/development/build.md for full prerequisites, configurations, and the dependency map.

---

Documentation

The deep technical reference lives under docs/, organized by audience.

Area	Highlights
Architecture	System overview, threading model (UI thread + render worker), pipeline format, effect graph model, D2D/D3D11 hybrid compute, engine/host split
Effects	Built-in catalog, Effect Designer, parameter / numeric / property-binding mechanics, working space
UI / UX	Graph editor, multi-output windows, animation, conditional parameter visibility
Hosts	ShaderLabHeadless console host, MCP server for AI agent integration
Development	Build instructions, project structure
History	Decision log (architectural choices with rationale)

CHANGELOG.md tracks every release. The decision log tracks architectural choices independently of release boundaries.

---

Project Identity

ShaderLab is a testbed for HDR / WCG / SDR pixel-effect development. The pipeline is always scRGB FP16 linear light (DXGI_FORMAT_R16G16B16A16_FLOAT, DXGI_COLOR_SPACE_RGB_FULL_G10_NONE_P709) — no pipeline format switching; DWM/ACM handles the final display conversion.

Core capabilities:

• Live effect graph with D2D + D3D11 compute custom effects, dirty-gated re-evaluation, JSON serialization (Windows.Data.Json).
• Effect Designer for authoring custom pixel & compute shaders with live HLSL compile + reflection-driven property generation.
• Analysis viewers (Luminance / Channel / Chromaticity Statistics, CIE Histogram + Plot, Gamut Coverage, Luminance Heatmap, etc.) — all share the same compute-bridge architecture and route their outputs as SRVs to downstream consumers when possible.
• Tone-mapping suite (D2D HDR Tone Map, ICtCp Tone Map, ICtCp Inverse Tone Map, ICtCp Gamut Map, etc.) operating in scRGB FP16 with PQ / HLG / sRGB transfer functions.
• HDR / WCG aware — event-driven display tracking (WinRT AdvancedColorInfoChanged: HDR toggles, the Windows SDR-brightness slider, monitor moves), ICC profile parsing, monitor primaries piped into Custom-gamut analysis effects via the Working Space node.
• MCP integration (stdio, via a broker: shim → hub → per-window sessions) + headless host for AI-agent and CI use; the MCP route layer lives in ShaderLabEngine.dll so headless and GUI hosts share the route implementations.

Build: Visual Studio 2022 17.8+, Windows 10 SDK 10.0.26100+, C++/WinRT only (no C#). Runtime: Windows 11 22H2 (10.0.22621)+.

---

License & Contact

See LICENSE for the project license and the GitHub repository for issues / PRs.