Clock updates

apps/RenderCadenceCompositor/README.md

@@ -19,7 +19,8 @@ RenderThread
 
 InputFrameMailbox
   owns latest disposable CPU input slots
-  drops older unsampled input frames when newer frames arrive
+  keeps a bounded three-ready-frame input buffer for render
+  trims frames beyond that bound to avoid runaway input latency
   protects the one frame currently being uploaded by render
   uses a single contiguous copy when capture row stride matches mailbox row stride
 
@@ -34,7 +35,7 @@ DeckLinkOutputThread
   never renders
 ```
 
-Startup warms up real rendered frames before DeckLink scheduled playback starts. When DeckLink input is available, startup also waits briefly for two ready input frames before the render thread starts so the first render ticks are deliberate rather than lucky.
+Startup warms up real rendered frames before DeckLink scheduled playback starts. When DeckLink input is available, startup also waits briefly for three ready input frames before the render thread starts so the first render ticks are deliberate rather than lucky.
 
 ## Current Scope
 
@@ -46,9 +47,9 @@ Included now:
 - hidden render-thread-owned OpenGL context
 - simple smooth-motion renderer
 - BGRA8-only output
-- non-blocking latest-frame input mailbox
+- non-blocking three-frame FIFO input mailbox for render
 - fast contiguous mailbox copy path for matching input row strides
-- bounded two-frame input warmup before render cadence starts
+- bounded three-frame input warmup before render cadence starts
 - render-thread-owned input texture upload
 - async PBO readback
 - latest-N system-memory frame exchange
@@ -122,9 +123,9 @@ This tracks parity with `apps/LoopThroughWithOpenGLCompositing`.
 - [x] Trigger parameter pulse count/time for latest trigger events
 - [x] Optional DeckLink input capture
 - [x] UYVY8 input capture with render-thread GPU decode to shader input texture
-- [x] Latest-frame CPU input mailbox
+- [x] Three-frame FIFO CPU input mailbox for render
 - [x] Fast contiguous input mailbox copy when source/destination stride matches
-- [x] Bounded two-frame input warmup before render cadence starts
+- [x] Bounded three-frame input warmup before render cadence starts
 - [x] Render-owned input texture upload
 - [x] Runtime shaders receive input through `gVideoInput`
 - [x] Live DeckLink input bound to `gVideoInput`
@@ -254,10 +255,10 @@ Startup order is:
 2. try to attach DeckLink input for the configured input mode
 3. prefer BGRA8 capture, otherwise accept raw UYVY8 capture and configure the mailbox for UYVY8 bytes
 4. start `DeckLinkInputThread`
-5. wait briefly for two ready input warmup frames before starting render cadence
+5. wait briefly for three ready input warmup frames before starting render cadence
 6. leave input absent if discovery, setup, format support, or stream startup fails
 
-`DeckLinkInput` and `DeckLinkInputThread` are deliberately narrow. They capture BGRA8 frames directly or raw UYVY8 frames into `InputFrameMailbox`; they do not call GL, render, preview, screenshot, shader, or output scheduling code. UYVY8-to-RGBA decode happens later inside the render-thread-owned input texture upload path, so the DeckLink callback stays a capture/copy edge only. The mailbox uses one contiguous copy when the capture row stride matches the configured mailbox row stride, and falls back to row-by-row copy only for padded or mismatched frames. Unsupported input modes or formats outside BGRA8/UYVY8 are reported explicitly and treated as an unavailable edge rather than silently converted.
+`DeckLinkInput` and `DeckLinkInputThread` are deliberately narrow. They capture BGRA8 frames directly or raw UYVY8 frames into `InputFrameMailbox`; they do not call GL, render, preview, screenshot, shader, or output scheduling code. UYVY8-to-RGBA decode happens later inside the render-thread-owned input texture upload path, so the DeckLink callback stays a capture/copy edge only. The render upload path consumes the oldest ready input frame from a bounded three-ready-frame queue, so the input behaves like a small jitter buffer instead of a latest-frame preview mailbox. The mailbox trims older frames beyond that bound to avoid runaway latency, uses one contiguous copy when the capture row stride matches the configured mailbox row stride, and falls back to row-by-row copy only for padded or mismatched frames. Unsupported input modes or formats outside BGRA8/UYVY8 are reported explicitly and treated as an unavailable edge rather than silently converted.
 
 Input warmup is startup-only and bounded. It may delay render-thread startup for a short window, but it does not add waits to the steady-state render cadence loop.
 
@@ -269,6 +270,12 @@ Normal cadence samples are available through `GET /api/state` and are not printe
 - warning when schedule failures increase
 - error when the app/DeckLink output buffer is starved
 
+Render cadence telemetry:
+
+- `clockOverruns`: render cadence overruns where missed time was detected
+- `clockSkippedFrames`: selected-cadence frame intervals skipped instead of catch-up rendering
+- `clockOveruns` / `clockSkipped`: compatibility aliases for quick polling scripts
+
 Input telemetry:
 
 - `inputFramesReceived`: frames accepted into `InputFrameMailbox`
@@ -391,7 +398,7 @@ This app keeps the same core behavior but splits it into modules that can grow:
 - `frames/`: system-memory handoff
 - `platform/`: COM/Win32/hidden GL context support
 - `render/`: cadence thread, clock, and simple renderer
-- `frames/InputFrameMailbox`: non-blocking latest-frame CPU input handoff with contiguous-copy fast path for matching row strides
+- `frames/InputFrameMailbox`: non-blocking bounded FIFO CPU input handoff with contiguous-copy fast path for matching row strides
 - `render/InputFrameTexture`: render-thread-owned upload of the latest CPU input frame into GL, including raw UYVY8 decode into the shader-visible input texture
 - `render/readback/`: PBO-backed BGRA8 readback and completed-frame publication
 - `render/runtime/RuntimeRenderScene`: render-thread-owned GL scene for ready runtime shader layers