Fix OHOS deferred rendering across seeks

Author: YangHYue

modern/ARCHITECTURE.md

@@ -195,6 +195,20 @@ newer snapshot is already current. A presentation-generation boundary clears
 all retained retries and invokes each renderer's non-blocking pending-frame
 invalidation hook. That hook may cancel a producer/image association which has
 not entered submission; it may not wait for already submitted GPU work.
+The playback worker does not join native render calls before a hardware-decoder
+flush: a codec present/release IPC may itself need that flush to make progress.
+The decoder flush becomes the cancellation authority for native producers
+which never published a consumer callback. Player publishes that completed
+generation and invokes the renderer's second-phase completion hook. A retired
+render call which overlaps the first pass repeats invalidation and completion
+when it returns. This two-phase discontinuity protocol has no caller, UI, or
+render-thread wait, no per-frame cost, and no wait for submitted GPU work.
+Native producer callbacks are a separate synchronization domain from renderer
+state. A redraw callback may run synchronously before the platform producer
+call returns, so forwarding it must not acquire a renderer/selector state lock
+which the graphics thread holds across that producer call. The active renderer
+identity is published independently, and one producer decision emits at most
+one redraw even when its consumer callback arrives before the decision returns.
 Timer-backoff busy results remain eligible for a high-level output's existing
 latest-frame supersession policy and are not pinned by Player.
 
@@ -458,7 +472,19 @@ invalidates it before import, the callback path acquires and immediately returns
 its consumer buffer, then clears the exact frame key before admitting another
 OHCodec output. Player repeats invalidation after an overlapping backend call,
 closing the race where an old render attempt queues its producer after seek was
-published. This path adds no per-frame GPU wait or decoded-source CPU copy.
+published. Player flushes the decoder without joining that native render call,
+then invokes a second completion phase. If OHCodec cancelled the invalidated
+producer without a callback, that phase clears the exact association. An
+overlapping retired call repeats both phases after it returns; any later orphan
+callback is drained instead of being matched to a newer frame. This path adds
+no render-thread or per-frame GPU wait and no decoded-source CPU copy.
+OHOS Surface notification can run before the native output-present call
+returns. The adapter and mobile selector therefore forward redraw through an
+event-only lock and atomically published active renderer identity, never their
+render-state locks. Interop records an early callback while the producer call
+is in flight and hands off exactly one redraw after it returns. This avoids both
+a callback/producer lock cycle and a second present of the same exactly-once
+OHCodec token.
 
 The Vulkan interop has three explicitly reported format routes:
 

modern/DECISIONS.md

@@ -771,6 +771,10 @@ remain unchanged.
   make statistics optional
 - Amended: 2026-08-12 to make exact retry-frame retention and pending-producer
   invalidation a Player/backend responsibility
+- Amended: 2026-08-12 to make decoder-flush cancellation a two-phase
+  discontinuity contract
+- Amended: 2026-08-12 to isolate synchronous native callbacks from renderer
+  state locks and coalesce one redraw per producer decision
 - Status: Accepted
 - Scope: Core render snapshots and cross-platform deferred-producer
   invalidation, plus Windows D3D11 context scheduling, composition output retry
@@ -794,6 +798,25 @@ removed that collision, then reason-level diagnostics exposed the remaining
 owner: FFmpeg's reservation-aware D3D11VA work could release and immediately
 reacquire the recursive immediate-context lock before a timer-only retry.
 
+The later OHOS seek stress matrix exposed a second lifecycle boundary. A
+non-blocking generation invalidation can mark an asynchronous producer stale,
+but some codec outputs never publish their native consumer callback because
+`avcodec_flush_buffers()` synchronously cancels them. Waiting for that callback
+before flushing is circular and produced a one-second seek timeout. Clearing
+the association before all old CPU render calls return is also unsafe because
+one of those calls can republish the retired producer after the clear.
+Joining those calls before flush is equally circular on OHCodec: a native
+`ReleaseOutputBuffer`/producer operation can itself wait for decoder flush and
+caused the foreground process to exceed the six-second thread-block watchdog.
+The consumer callback may also arrive before that producer operation returns.
+The OHOS adapter and mobile selector previously forwarded the callback through
+their recursive renderer-state locks while the render thread held those locks
+around the producer call. The callback then waited for the render thread, while
+the render thread's next native producer operation waited for callback return.
+Forwarding both the callback edge and the producer-return edge could also
+schedule two redraws for one exactly-once OHCodec token; the second present was
+a successful no-op and could not generate another consumer callback.
+
 ### Decision
 
 1. Add `Player::renderVideoDetailed()` and `VideoRenderResult`. Each attempt
@@ -834,6 +857,20 @@ reacquire the recursive immediate-context lock before a timer-only retry.
    retries and invoke a non-blocking renderer invalidation hook for producer
    work which has not entered GPU submission. Recheck and invalidate again
    after an overlapping backend call closes the old-render/new-seek race.
+8. A hardware-decoder seek uses a two-phase discontinuity protocol. First,
+   publish generation invalidation, then flush the decoder without joining
+   native render calls and publish the completed cancellation generation.
+   `completePendingFrameInvalidation()` may retire an invalidated association
+   whose callback the decoder flush cancelled; it may not wait for submitted
+   GPU work. An old render call which returns after that generation repeats
+   invalidation and completion, closing the late-republish race without a
+   render-thread barrier. Both public hooks default to no-op.
+9. Backend redraw callbacks use synchronization independent of renderer state
+   held across a native producer/present call. The mobile selector validates a
+   redraw against atomically published active API/generation identity without
+   entering its render-state mutex. When a native consumer callback arrives
+   before its producer call returns, interop records that edge and publishes
+   exactly one redraw after producer completion.
 
 ### Consequences
 
@@ -852,6 +889,13 @@ reacquire the recursive immediate-context lock before a timer-only retry.
 - The new public result and Windows statistics are additive API. Existing code
   using `renderVideo()` and `skippedRenders` continues to compile, with the
   clarified terminal-drop meaning for the latter.
+- Applications do not wait for, flush, or track backend producer state around
+  Player controls. Decoder cancellation and the repeated completion pass add
+  no steady-state frame cost and preserve the lifetime of GPU work already
+  submitted.
+- Callback delivery cannot form a renderer-state/native-producer lock cycle,
+  and one exactly-once decoder output cannot leave a duplicate redraw waiting
+  for a callback which will never exist.
 - D3D11 statistics use `Off`, `Counters`, or `Timing`. The high-level output no
   longer reads, clears, and re-aggregates renderer atomics after every frame;
   retry behavior remains identical when statistics are off.

modern/MIGRATION.md

@@ -868,8 +868,14 @@ implementation.
   call `VideoRenderAPI::invalidatePendingFrames()` automatically. The default
   implementation is a non-blocking no-op; asynchronous native-buffer backends
   cancel only producer associations which have not entered GPU submission.
-  Existing custom renderer source does not need an override, but consumers
-  must rebuild for the appended public virtual;
+  A hardware-decoder seek then flushes the decoder without joining native
+  render calls, publishes that cancellation generation, and calls
+  `completePendingFrameInvalidation()`. Backends use that second phase to
+  retire a producer callback synchronously cancelled by the flush. A retired
+  render call which overlaps the first pass repeats both hooks when it returns.
+  Both appended virtuals default to no-op, so custom renderer source remains
+  compatible after consumers rebuild; no application-side interop flush,
+  render-thread wait, or per-frame wait is required;
 - `OpenGLPresentCallback` runs on that same graphics-owner thread after
   framebuffer submission and before hardware-source release; it is intended
   for the adapter's bounded window-present call, not general application work;
@@ -885,7 +891,10 @@ implementation.
   wrapper). Its default implementation calls the legacy boolean `render()`;
   backend event callbacks may request another player state;
 - audio-sink and video-render backend event callbacks run on the thread chosen
-  by the backend and may request another player state;
+  by the backend and may request another player state. A native producer may
+  invoke its redraw callback before the producer call returns; renderer
+  adapters therefore forward redraw through synchronization independent of
+  render-state locks and coalesce that producer decision to one redraw;
 - compressed audio packets cross a bounded queue to their decode worker, then
   decoded audio crosses a second bounded queue to the dedicated audio-output worker;
   ordinary conversion, time stretching, sink writes, and primary device-clock

modern/PLAN.md

@@ -100,13 +100,20 @@ The following accepted decisions constrain all remaining work:
 - The OHCodec/Vulkan deferred-frame freeze root cause is repaired in C++.
   Player now retains the exact backend-deferred frame per renderer key and
   automatically invalidates pending producer associations at every
-  presentation-generation boundary. The OHCodec consumer path drains an
-  invalidated one-buffer output before admitting a new frame, without a CPU
-  copy, renderer fallback, or GPU-wide wait. Deterministic Windows playback
-  tests, OHOS arm64/API 23 shared/static cross-builds, the player native link,
-  and signed HAP packaging pass. Replaying the forward/backward seek matrix on
-  `legend.mkv` and `wednesday.mp4` remains a connected-device gate requiring
-  explicit installation approval; see
+  presentation-generation boundary, then completes decoder-cancelled
+  associations after synchronous flush without joining native render calls.
+  The OHCodec consumer path drains invalidated/orphaned buffers before
+  admitting a new frame. Native redraw callbacks no longer enter renderer
+  state locks held across producer calls, and an early callback is coalesced to
+  exactly one redraw per OHCodec output. The repair adds no CPU copy, renderer
+  fallback, caller-side flush, per-frame wait, or GPU-wide wait. Deterministic
+  playback coverage, OHOS arm64/API 23 shared/static cross-builds, the player
+  native link, and signed HAP packaging pass. The overwrite-installed HAP then
+  passed cold-start, forward-seek, and backward-seek cells on both `legend.mkv`
+  and `wednesday.mp4` at 24--25 FPS with balanced native release/callback
+  counts; eight additional Wednesday forward/backward pairs continued decoding
+  and presenting without a seek timeout, thread-block watchdog, or crash. The
+  cold cells did not show `当前媒体不可定位`; see
   [`PLAN_HISTORY_2026-08-12_OHOS_DEFERRED_RENDER_SEEK.md`](PLAN_HISTORY_2026-08-12_OHOS_DEFERRED_RENDER_SEEK.md).
 - The OHOS software-decode follow-up now keeps FFmpeg LTO/NEON and the shared
   small-build policy while overriding the effective arm64 optimization from
@@ -314,6 +321,9 @@ all those frames still used an RGBA16F normalization image.
   still reported tone mapping. The 2026-08-12 follow-up then replaced the
   former Profile 5 Vulkan-to-OpenGL fallback with opaque identity Vulkan
   sampling and passed repeated `wednesday -> legend -> wednesday` switching.
+  The separate deferred-render regression now also passes cold-start plus
+  forward/backward seek on both local files and an eight-pair Wednesday seek
+  stress run without presentation freeze.
   Physical audio identity and the remaining broad manual cells stay open.
 
 The four-thread software-decode build, signed-device counters, temperatures,

modern/PLAN_HISTORY_2026-08-12_OHOS_DEFERRED_RENDER_SEEK.md

@@ -10,7 +10,7 @@ captured `legend.mkv` session advanced from roughly 2:52 to 3:25 and continued
 receiving OHCodec video outputs, while successful presentation FPS stayed at
 zero. Only the first few private-consumer callbacks/imports completed.
 
-The failure was not demux seekability, audio clocking, software decode
+The first failure was not demux seekability, audio clocking, software decode
 throughput, ArkTS slider state, or a Vulkan color path. The asynchronous
 OHCodec/Vulkan handshake queued frame A into its private one-buffer
 `OH_ConsumerSurface` and correctly returned `DeferredUntilRedraw`. Before the
@@ -40,6 +40,45 @@ invalidating Player's snapshot without canceling the interop's queued A.
 - Player invokes invalidation again when generation changes during a backend
   call, closing the race where an old render attempt queues its producer just
   after seek publishes the new generation.
+- Stressing consecutive forward/backward seeks exposed that invalidation alone
+  was insufficient: OHCodec can cancel a surface output during decoder flush
+  without publishing the callback which would normally drain it. A preliminary
+  callback-before-flush wait reproduced `seek.error: Operation timed out`,
+  proving that ordering circular.
+- A second diagnostic ordering which joined old native render calls before
+  flush was also rejected on-device. Wednesday's backward seek left
+  `ReleaseOutputBuffer` and `QueueInputBuffer` IPC calls blocked for five
+  seconds and triggered HarmonyOS `THREAD_BLOCK_6S`; the system killed the
+  foreground process. The codec flush must be allowed to break that native
+  dependency, not wait behind it.
+- The final C++ contract is a non-joining two-phase protocol. Player first
+  publishes non-blocking invalidation, flushes the hardware decoder, publishes
+  the completed cancellation generation, and calls
+  `completePendingFrameInvalidation()`. OHCodec acquires and releases an
+  available invalidated buffer, or clears the association known to have been
+  cancelled by the synchronous flush. A retired render call which returns
+  after the first pass repeats invalidation and completion, closing the
+  late-republish race. A later callback without an association is drained as
+  an orphan and cannot poison the next exact frame.
+- The remaining freeze was a callback lock cycle. OHOS can invoke the private
+  Surface callback before `OH_VideoDecoder_RenderOutputBuffer()` returns. The
+  adapter and mobile selector used to reacquire renderer-state locks which the
+  render thread still held around that native call; the callback waited for the
+  render thread while the next producer operation waited for callback return.
+  Redraw forwarding now uses a separate event lock and atomically published
+  active renderer API/generation, so it never enters those state locks.
+- An early callback and the producer-return path also used to schedule two
+  redraws for the same exactly-once OHCodec output. The second present was a
+  successful no-op and could never produce the callback needed to continue.
+  Interop now records callbacks while the producer call is in flight and emits
+  exactly one redraw after it returns. Orphan acquisition remains on the Vulkan
+  render thread because a callback may precede the buffer becoming acquirable.
+- `Player::seek()` now accepts the latest request during asynchronous input
+  opening without changing the interrupt epoch which protects that open. The
+  request is clamped and executed after metadata is available, and its callback
+  receives failure if opening cannot complete. The OHOS Demo forwards the
+  request to this core contract instead of rejecting it from a stale ArkTS
+  `seekable` snapshot.
 
 There is no per-frame GPU wait, decoded-source map, software transfer, staging
 copy, upload, decoder fallback, or ArkTS/caller-owned retry-frame state. GPU
@@ -59,6 +98,22 @@ submissions already in flight retain their existing timeline-based lifetime.
 - The OHOS player native library linked and the signed debug HAP packaged at
   `modern/examples/ohos/player-hap/entry/build/default/outputs/default/entry-default-signed.hap`.
 
-The HAP was not installed or launched in this repair turn. Connected-device
-replay with local `legend.mkv` and `wednesday.mp4` remains gated on explicit
-installation approval.
+The final signed HAP was overwrite-installed on the connected ALN-AL80. Both
+document-picker cold starts omitted the former `当前媒体不可定位` toast, and
+both processes survived the complete matrix:
+
+| Media / cell | Position | FPS | Hardware decoded | Presented | Native release/callback |
+|---|---:|---:|---:|---:|---:|
+| `legend.mkv` cold | 0:10 / 45:44 | 25.1 | 257 | 254 | 255/255 |
+| `legend.mkv` forward | 30:15 / 45:44 | 25.1 | 769 | 766 | 767/767 |
+| `legend.mkv` backward | 6:05 / 45:44 | 25.0 | 1,312 | 1,307 | 1,308/1,308 |
+| `wednesday.mp4` cold | 0:10 / 59:28 | 24.1 | 244 | 239 | 240/240 |
+| `wednesday.mp4` forward | 39:15 / 59:28 | 24.1 | 787 | 782 | 783/783 |
+| `wednesday.mp4` backward | 7:49 / 59:28 | 24.0 | 1,254 | 1,247 | 1,249/1,249 |
+
+An additional Wednesday stress run completed eight forward/backward pairs.
+After the last seek it remained Loaded at 24.1 FPS; hardware decode/presentation
+rose from 2,163/2,113 to 2,354/2,304 during the next five seconds, native
+release and callback stayed balanced at 2,311/2,311, and Player drops remained
+two. The final process emitted no seek timeout, media error, `THREAD_BLOCK`, or
+crash evidence.