video-shader-toys/README.md

Video Shader

Native video shader host with an OpenGL/DeckLink render path, Slang shader packages, and a local React control UI.

The app loads shader packages from shaders/, compiles Slang to GLSL at runtime, renders a configurable layer stack, and exposes a browser-based control surface over a local HTTP/WebSocket server.

Repository Layout

• apps/LoopThroughWithOpenGLCompositing/: native C++ host app.
• shaders/: shader packages, each with shader.json and shader.slang.
• ui/: Vite/React control UI.
• config/runtime-host.json: runtime configuration.
• runtime/templates/: tracked shader wrapper templates.
• runtime/: ignored generated runtime cache/state output. See runtime/README.md.
• tests/: focused native tests for pure runtime logic.
• .gitea/workflows/ci.yml: Gitea Actions CI for Windows native tests and Ubuntu UI build.

Requirements

• Windows with Visual Studio 2022 C++ tooling.
• CMake 3.24 or newer.
• Node.js and npm for the control UI.
• Blackmagic DeckLink SDK 16.0 with the NVIDIA GPUDirect sample files available locally.
• Slang compiler available under the repo/tooling paths expected by the runtime, or otherwise discoverable by the existing app setup.

The Blackmagic/GPUDirect SDK should not be committed to this repository. CMakeLists.txt exposes GPUDIRECT_DIR as a cache path so local machines and CI runners can point at their installed SDK location.

Default expected SDK path:

3rdParty/Blackmagic DeckLink SDK 16.0/Win/Samples/NVIDIA_GPUDirect

Override example:

cmake --preset vs2022-x64-debug -DGPUDIRECT_DIR="D:/SDKs/Blackmagic DeckLink SDK 16.0/Win/Samples/NVIDIA_GPUDirect"

Build

Configure and build the native app:

cmake --preset vs2022-x64-debug
cmake --build --preset build-debug

Build the React control UI:

cd ui
npm ci
npm run build

The native app serves ui/dist when it exists, otherwise it falls back to the source UI directory during development.

Tests

Run native tests:

cmake --build --preset build-debug --target RUN_TESTS

Run the UI production build check:

cd ui
npm run build

Current native test coverage includes:

• JSON parsing and serialization.
• Parameter normalization and preset filename safety.
• Shader manifest parsing and package registry scanning.

Runtime Configuration

config/runtime-host.json controls host behavior:

{
  "shaderLibrary": "shaders",
  "serverPort": 8080,
  "autoReload": true,
  "maxTemporalHistoryFrames": 12,
  "enableExternalKeying": true
}

The control UI is available at:

http://127.0.0.1:<serverPort>

Shader Packages

Each shader package lives under:

shaders/<id>/
  shader.json
  shader.slang

See SHADER_CONTRACT.md for the manifest schema, parameter types, texture assets, temporal history support, and the Slang entry point contract.

Generated Files

Runtime-generated files are intentionally ignored:

• runtime/shader_cache/active_shader_wrapper.slang
• runtime/shader_cache/active_shader.raw.frag
• runtime/shader_cache/active_shader.frag
• runtime/runtime_state.json
• runtime/stack_presets/*.json

Only runtime/templates/ and runtime/README.md are tracked.

CI

The Gitea workflow expects two act runners:

• windows-latest: builds the native app and runs native tests.
• nubuntu-latest: installs UI dependencies and runs the Vite build.

If your Windows runner stores the Blackmagic SDK outside the repo, configure GPUDIRECT_DIR in the runner environment or adjust the workflow configure command to pass -DGPUDIRECT_DIR=....