video-shader-toys/docs/FORKING_RENDER_CADENCE_BASE.md

Forking The Render Cadence Base

This note captures the fork-readiness review for using this repository as a base where the render cadence and video I/O work are kept, but the GPU content being rendered is replaced in a separate repository.

Verdict

The repository is clean enough for an internal fork, but it needs a small hygiene pass before it becomes a comfortable long-lived base repo.

The important architecture is already in place: render cadence, video input/output, frame exchange, readback, preview, control, and shader build work are mostly separated by role. The app-side replacement point is now IRuntimeContentController in src/app/RuntimeContentController.h. The current shader package stack is plugged in by ShaderRuntimeContentController, while a fork can provide a D3D-engine controller without making the host app own Slang, shader catalogs, or shader layer state.

The current render-thread implementation still uses OpenGL for its context and readback path. If the fork's renderer is truly D3D rather than GL content, keep the app/video/frame-exchange boundary and replace the render-thread/content implementation that publishes completed system-memory frames.

For a new repo, keep the cadence and frame handoff machinery, then replace or narrow the runtime shader rendering layer.

Keep

These parts are the useful base for the fork:

• src/frames: CPU frame handoff, input mailbox, and completed-frame exchange.
• src/video/core: backend-neutral input/output contracts.
• src/video/decklink, src/video/ndi, and src/video/playout: concrete video I/O edges and scheduling support.
• src/render/thread: render cadence ownership, readback pumping, runtime render-layer commit point, and metrics.
• src/render/readback: BGRA8/UYVY8 PBO readback and completed-frame publication.
• src/platform: hidden GL window/context support.
• src/app: startup, config, video backend factory, runtime layer orchestration, preview, telemetry, and HTTP server hookup.
• src/control/http, src/control/osc, src/telemetry, src/logging, and ui: useful if the new repo still wants a local control surface. control/osc is currently a status/lifecycle stub, not a UDP listener.
• src/app/RenderCadenceHttpRoutes.*: useful only if the new repo keeps this app's current /api/... control surface.
• src/app/RuntimeContentController.h: the app-side runtime-content boundary. Keep the interface shape and provide a fork-owned implementation for D3D engine control/state.

Replace Or Rework

These are most likely to change when the fork renders something other than shader packages:

• src/render/runtime: current runtime shader scene, renderer, text texture cache, and shared-context shader preparation.
• src/runtime/shader: background Slang package build bridge.
• src/shader: shader package manifest parsing and Slang wrapper generation, unless the new renderer keeps the same shader package contract.
• src/app/ShaderRuntimeContentController.*: current Slang shader-stack implementation of the app runtime-content boundary.
• shaders/: bundled shader package library.
• runtime/templates/shader_wrapper.slang.in: only needed for the current Slang package pipeline.
• src/app/RenderCadenceHttpRoutes.*: replace this with a fork-owned route module if the new renderer has different controls, while keeping src/control/http/HttpControlServer.* as the socket/static/WebSocket shell.
• Shader-specific UI affordances in ui, if the new renderer has a different control model.

The first fork step is now in place: RenderThread preserves the cadence/readback shell and calls a narrow render-content interface behind the draw call. A new repo can swap that implementation without touching video I/O scheduling.

The shader stack is also separated from RenderCadenceApp now. The app owns only an IRuntimeContentController; RenderCadenceCompositor.cpp wires the current ShaderRuntimeContentController into that slot. A D3D fork should wire a D3D runtime-content controller there and then replace the render-thread content/readback implementation as needed.

The HTTP control boundary is also split now. HttpControlServer owns transport, static-file helpers, OpenAPI helper serving, and WebSocket state transport; RenderCadenceHttpRoutes owns this app's REST endpoint map. A fork that wants the same browser/server plumbing can provide its own route callback and leave the Render Cadence-specific endpoints behind.

Current Swap Point

The render cadence loop now calls IRenderContent inside the readback queue call in src/render/thread/RenderThread.cpp:

renderContent.RenderFrame(RenderContentFrame{
	index,
	mConfig.width,
	mConfig.height,
	videoInputTexture
});

The default implementation is RuntimeShaderRenderContent, which owns the existing runtime shader scene plus simple fallback renderer. That is the practical boundary for a fork:

• keep the tick clock, input upload, readback queueing, and SystemFrameExchange publication around it
• replace what draws into the current GL framebuffer
• keep video output consuming already completed system-memory frames

Do not move DeckLink, NDI, file I/O, shader compilation, or control handling into the cadence path while doing the replacement.

Fork Hygiene Checklist

Before cutting a long-lived fork, fix or decide these items:

• Keep runtimeShaderId empty in checked-in config unless this repo intentionally wants a default startup shader again.
• Keep runtime third-party discovery aligned with CMake. Font atlas generation and Slang compilation now both check explicit tool roots, THIRD_PARTY_ROOT, the private video-io-3rdParty bundle, and legacy or packaged 3rdParty layouts.
• Make config/runtime-host.json portable. Current checked-in defaults include a local NDI source name and DeckLink output.
• Decide whether the fork keeps the Slang shader package contract. If not, replace ShaderRuntimeContentController, retire or clearly isolate shaders/SHADER_CONTRACT.md, shader package UI, and shader manifest tests.
• For a D3D engine fork, decide whether to bridge D3D output into the existing GL/readback path temporarily or replace RenderThread/readback with a D3D-native publisher that still writes completed SystemFrameExchange frames.
• Mark older docs that reference apps/LoopThroughWithOpenGLCompositing as historical, or update them to point at the current src/ implementation.
• Keep runtime/ generated output ignored, and keep only runtime/templates/ plus runtime/README.md tracked.
• Keep the private SDK bundle as a submodule only if the new repo is intended for the same org/build environment. External forks should use ignored 3rdParty/ or explicit CMake SDK paths.

Verification Snapshot

Last checked locally on 2026-05-30 after the runtime-content controller split:

• UI production build passed with npm.cmd run build.
• Native debug build passed for RenderCadenceCompositor.
• Native tests passed 26 of 26 with ctest --test-dir build\vs2022-x64-debug -C Debug --output-on-failure.
• FontAtlasBuilderTests now passes with msdf-atlas-gen.exe supplied by the private video-io-3rdParty/msdf-atlas-gen bundle.
• ShaderCompilerLookupTests covers SLANG_ROOT, THIRD_PARTY_ROOT, repo video-io-3rdParty, legacy 3rdParty, and packaged 3rdParty/slang Slang layouts.

The generated Visual Studio RUN_TESTS target did not build missing test executables by itself during the first local run; building the debug preset first produced the test binaries.

Recommended Fork Sequence

1. Make the hygiene fixes above in this repo or immediately after the fork.
2. Keep IRuntimeContentController as the app-side boundary and replace ShaderRuntimeContentController with the fork's D3D engine control/state implementation.
3. Keep IRenderContent as the render-thread draw-call boundary only if the fork remains GL-backed or uses a GL/D3D bridge.
4. If the fork is D3D-native, replace the render-thread/readback implementation while preserving completed-frame publication into SystemFrameExchange.
5. Verify that video output still consumes completed frames and never requests rendering directly.
6. Only then remove shader package pieces that the new repo no longer needs.

That sequence preserves the hard-won cadence/video I/O behavior while giving the fork a clean place to become its own renderer.