docs pass

docs/DECKLINK_OPENGL_LESSONS_LEARNED.md

@@ -282,6 +282,24 @@ Lesson:
 - test policies such as `one_before_output` or `skip_before_output`
 - prefer latest-input semantics over draining every pending upload
 
+### CPU Input Conversion Can Be Worse Than Input Copy
+
+When DeckLink input only exposed UYVY8 on the test machine, an initial CPU UYVY-to-BGRA conversion in the input callback measured around a full-frame budget on sampled runs and reduced input cadence dramatically.
+
+Moving the input edge to raw UYVY8 capture changed the ownership:
+
+- DeckLink callback copies raw supported input bytes into `InputFrameMailbox`
+- the mailbox keeps latest-frame semantics and uses a contiguous copy when row strides match
+- the render thread uploads/decodes UYVY8 into the shader-visible `gVideoInput` texture
+- runtime shaders continue to see decoded input, not packed capture bytes
+
+Lesson:
+
+- keep input callbacks as capture/copy edges
+- keep GL decode/upload in the render-owned path
+- measure input copy, upload, and decode separately
+- do not hide expensive format conversion inside the DeckLink callback
+
 ### Preview And Screenshot Must Stay Secondary
 
 Preview is useful, but DeckLink output is the real-time path.

docs/RENDER_CADENCE_GOLDEN_RULES.md

@@ -58,6 +58,8 @@ It must not:
 
 If no completed frame is available, record the miss and keep the ownership boundary intact.
 
+DeckLink input is also an edge, not a renderer. It may capture/copy the latest supported CPU frame into an input mailbox and update input telemetry, but it must not call GL, schedule output, compile shaders, or drive render cadence. Format decode that requires GL belongs to the render-owned input upload path.
+
 ## 4. Runtime Build Work Produces Artifacts
 
 Runtime shader work is split into two phases:
@@ -112,6 +114,10 @@ Good examples:
 - `completedPollMisses`
 - `scheduleFailures`
 - `decklinkBuffered`
+- `inputCaptureFps`
+- `inputSubmitMs`
+- `inputUploadMs`
+- `inputConvertMs`
 - `shaderCommitted`
 - `shaderFailures`