# 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`:

```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.