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 main replacement point is the render-content adapter in src/render/RuntimeShaderRenderContent.*, where the current shader-package renderer decides what to draw into the framebuffer handed to it by RenderThread.

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.

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.
• 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 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.
• Align remaining runtime third-party discovery with CMake. Font atlas generation now checks MSDF_ATLAS_GEN_ROOT, THIRD_PARTY_ROOT, 3rdParty, and video-io-3rdParty; shader compiler lookup still needs the same treatment for Slang.
• 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, retire or clearly isolate shaders/SHADER_CONTRACT.md, shader package UI, and shader manifest tests.
• 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 font-builder lookup fix:

• Worktree was clean before documentation changes.
• UI production build passed with npm.cmd run build.
• Native debug build passed with cmake --build --preset build-debug --parallel.
• Native tests passed 24 of 24 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.

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 IRenderContent as the boundary behind the RenderThread draw call.
3. Keep RuntimeShaderRenderContent as the baseline implementation until the fork's renderer exists.
4. Add the new renderer beside it or replace the default adapter.
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.