Phase 4

docs/PHASE_4_RENDER_THREAD_OWNERSHIP_DESIGN.md

@@ -7,16 +7,16 @@ Phase 1 named the subsystems. Phase 2 added the typed event substrate. Phase 3 m
 ## Status
 
 - Phase 4 design package: proposed.
-- Phase 4 implementation: Step 3 started. The existing synchronous `RenderEngine` entrypoints delegate their GL bodies to named `...OnRenderThread(...)` helpers, preview/screenshot/render-reset/input-upload/output-render requests pass through a small `RenderCommandQueue` compatibility mailbox, and `RenderEngine` now starts a dedicated render thread for normal runtime GL work.
+- Phase 4 implementation: Step 7 started. The existing synchronous `RenderEngine` entrypoints delegate their GL bodies to named `...OnRenderThread(...)` helpers, preview/screenshot/render-reset/input-upload/output-render requests pass through a small `RenderCommandQueue` compatibility mailbox, and `RenderEngine` now starts a dedicated render thread for normal runtime GL work.
 - Current alignment: the repo has a named frame-state contract and cleaner render-state preparation. Normal runtime GL work is routed through the render thread after startup, while startup initialization still runs before the render thread is started.
 
 Current GL ownership footholds:
 
-- `RenderEngine` owns GL resources, a dedicated render thread, the current synchronous compatibility shims, a small render command mailbox, and named render-thread helper methods.
+- `RenderEngine` owns GL resources, a dedicated render thread, the current synchronous compatibility shims, a small render command mailbox, named render-thread helper methods, and wrong-thread diagnostics for those helpers.
 - `RenderFrameInput` / `RenderFrameState` provide the frame-state contract that a render thread can consume.
 - `RenderFrameStateResolver` prepares the render-facing layer state before drawing.
-- `OpenGLVideoIOBridge` still calls `RenderEngine::TryUploadInputFrame(...)` from the input path and `RenderEngine::RenderOutputFrame(...)` from the output path.
-- `OpenGLComposite::paintGL(...)`, screenshot capture, input upload, and output rendering still call synchronous `RenderEngine` methods, but those methods now invoke render-thread work once `OpenGLComposite::Start()` has started the render thread.
+- `OpenGLVideoIOBridge` calls `RenderEngine::QueueInputFrame(...)` from the input path and `RenderEngine::RequestOutputFrame(...)` from the output path.
+- `OpenGLComposite::paintGL(...)`, screenshot capture, input upload, and output rendering enter render work through explicit `RenderEngine` requests. After `OpenGLComposite::Start()` starts the render thread, those requests do not bind the GL context on the caller thread.
 
 ## Why Phase 4 Exists
 
@@ -65,11 +65,11 @@ The current code paths that matter most are:
 | Entry point | Current behavior | Phase 4 direction |
 | --- | --- | --- |
 | `RenderEngine::TryUploadInputFrame(...)` | synchronous compatibility shim; after render-thread startup it queues input upload work and waits for render-thread completion | enqueue latest input frame; render thread uploads without callback-owned GL |
-| `RenderEngine::RenderOutputFrame(...)` | synchronous compatibility shim; after render-thread startup it queues output render work and waits for render-thread completion | render thread executes output frame production |
-| `RenderEngine::TryPresentPreview(...)` | synchronous compatibility shim; after render-thread startup it queues preview presentation and waits for render-thread completion | render thread or preview presenter consumes latest completed frame |
+| `RenderEngine::RequestOutputFrame(...)` | synchronous output request; after render-thread startup it queues output render work and waits for render-thread completion with timeout/failure reporting | render thread executes output frame production |
+| `RenderEngine::TryPresentPreview(...)` | best-effort compatibility shim; after render-thread startup non-render callers queue preview presentation and return | render thread or preview presenter consumes latest completed frame |
 | `RenderEngine::CaptureOutputFrameRgbaTopDown(...)` | synchronous compatibility shim; after render-thread startup it queues screenshot readback and waits for render-thread completion | screenshot request becomes render-thread command |
-| `OpenGLVideoIOBridge::UploadInputFrame(...)` | calls render upload directly | push input frame into render queue/mailbox |
-| `OpenGLVideoIOBridge::RenderScheduledFrame(...)` | calls render output directly from backend path | request/consume render-produced output without callback-owned GL |
+| `OpenGLVideoIOBridge::UploadInputFrame(...)` | copies the latest input frame into the render mailbox and returns without waiting for GL | render thread uploads the latest queued input frame |
+| `OpenGLVideoIOBridge::RenderScheduledFrame(...)` | requests render-thread output production and reports success/failure to the backend | consume render-produced output without callback-owned GL |
 
 ## Target Ownership Model
 
@@ -260,10 +260,12 @@ Change `OpenGLVideoIOBridge::UploadInputFrame(...)` so it enqueues or replaces t
 
 Policy targets:
 
-- bounded memory
-- latest-frame wins under load
-- input upload skip count is observable
-- input callback never waits for GL
+- [x] bounded memory
+- [x] latest-frame wins under load
+- [x] input upload skip count is observable through render command coalescing metrics
+- [x] input callback never waits for GL
+
+Current implementation: `OpenGLVideoIOBridge::UploadInputFrame(...)` calls `RenderEngine::QueueInputFrame(...)`, which copies the input bytes into the latest-value render mailbox and schedules one bounded render-thread wakeup to upload the newest pending frame.
 
 ### Step 5. Move Output Rendering To The Render Thread
 
@@ -271,32 +273,38 @@ Change `OpenGLVideoIOBridge::RenderScheduledFrame(...)` so it requests render-th
 
 Transitional option:
 
-- synchronous request/response through the render thread
+- [x] synchronous request/response through the render thread
 
 Better follow-up:
 
 - render ahead into a bounded output queue and let backend callbacks consume ready frames
 
+Current implementation: `OpenGLVideoIOBridge::RenderScheduledFrame(...)` calls `RenderEngine::RequestOutputFrame(...)` and returns whether the render-thread request produced an output frame. `VideoBackend` skips scheduling that frame when render production fails or times out.
+
 ### Step 6. Decouple Preview And Screenshot Requests
 
 Preview should become best-effort:
 
-- request preview presentation from the render thread
-- skip when render is busy or output deadline pressure is high
-- record preview skips
+- [x] request preview presentation from the render thread
+- [x] skip/coalesce when render is busy or output deadline pressure is high
+- [x] record preview skips through render command coalescing metrics
 
 Screenshot should become:
 
-- queued render-thread capture request
-- async disk write remains outside render thread
+- [x] queued render-thread capture request
+- [x] async disk write remains outside render thread
+
+Current implementation: `OpenGLComposite::RequestScreenshot(...)` builds the output path, queues `RenderEngine::RequestScreenshotCapture(...)`, and the render thread captures pixels before handing them to the existing async PNG writer. Preview presentation is a latest-value best-effort render command; non-render callers enqueue and return, while render-thread callers drain the latest preview command inline.
 
 ### Step 7. Remove Shared GL Lock From Normal Paths
 
 Once all GL entrypoints are render-thread-owned:
 
-- remove normal dependence on `pMutex` for render correctness
-- keep assertions or diagnostics that detect wrong-thread GL calls
-- leave only lifecycle synchronization where needed
+- [x] remove normal dependence on `pMutex` for render correctness
+- [x] keep diagnostics that detect wrong-thread render-thread helper calls
+- [x] leave only lifecycle context binding where needed
+
+Current implementation: `OpenGLComposite` no longer owns or passes a shared `CRITICAL_SECTION`, and `RenderEngine` no longer has caller-thread GL fallback paths for preview, input upload, output render, or screenshot capture. Runtime callers must go through the render thread; pre-start direct GL fallback is limited to startup initialization while the app explicitly owns the context.
 
 ## Testing Strategy
 
@@ -366,12 +374,12 @@ Preview can remain a hidden budget consumer if it stays in the output frame path
 
 Phase 4 can be considered complete once the project can say:
 
-- [ ] one render thread owns the GL context during normal operation
-- [ ] input callbacks do not bind GL or wait on GL upload
-- [ ] output callbacks do not bind GL directly
-- [ ] preview and screenshot requests enter render through explicit render-thread requests
+- [x] one render thread owns the GL context during normal operation
+- [x] input callbacks do not bind GL or wait on GL upload
+- [x] output callbacks do not bind GL directly
+- [x] preview and screenshot requests enter render through explicit render-thread requests
 - [ ] `RenderFrameInput` / `RenderFrameState` remain the frame-state contract
-- [ ] normal frame production no longer depends on a shared GL `CRITICAL_SECTION`
+- [x] normal frame production no longer depends on a shared GL `CRITICAL_SECTION`
 - [ ] render-thread queue/mailbox behavior has non-GL tests
 - [ ] shutdown order is explicit and tested or manually verified