Skip to content

fix(android): wait for a fresh PAG frame after FlutterView resume - #110

Open
EverMPChat wants to merge 3 commits into
libpag:feature/fix_surfacefrom
EverMPChat:fix/android-first-frame-ready
Open

fix(android): wait for a fresh PAG frame after FlutterView resume#110
EverMPChat wants to merge 3 commits into
libpag:feature/fix_surfacefrom
EverMPChat:fix/android-first-frame-ready

Conversation

@EverMPChat

Copy link
Copy Markdown

Summary

Fix the Android black frame that can appear when a FlutterView containing a PAG Texture is detached by a native tab and later resumed.

The branch is intentionally based on feature/fix_surface at ab78a6a4fcbfca99064bfc3fe498111f10023095 so it retains the newer Flutter SurfaceProducer lifecycle support.

Fixes #108

Changes

  • track a frame generation for each composition and Surface lifecycle;
  • emit onFrameReady only after a successful flush for the current generation;
  • emit onFrameUnavailable when the Surface or lifecycle becomes invalid;
  • keep the Android Texture mounted under defaultBuilder and wait one Flutter compositor frame before revealing it;
  • add PAGViewState.pauseForLifecycle() for native-tab detach paths where no Surface-destroyed callback arrives;
  • make Android start() flush the current progress before starting the animator;
  • preserve existing non-Android Texture timing.

Why a lifecycle-specific pause

A normal animation pause must preserve existing display semantics. Native tab switching additionally needs to invalidate the previous ready state, because the underlying FlutterView can be detached without a matching SurfaceProducer.Callback.onSurfaceDestroyed callback.

Keeping this behavior in the shared adapter avoids requiring every Flutter page to add its own overlay or host-specific lifecycle handler.

Verification

  • flutter test --coverage test/pag_view_frame_state_test.dart: 6/6 passed
  • package analyze: no new errors; existing upstream/example warnings only
  • example Android debug APK build: passed
  • host Flutter PAG/card focused tests: 47/47 passed
  • host Android lint and assemble: passed
  • Android manual verification: repeated native tab switching no longer shows the black frame

The host app keeps libpag 4.5.85 through Gradle conflict resolution; this PR does not change the plugin dependency declaration.

Ever added 3 commits August 19, 2026 14:46
原因:PAG flush 成功早于 Flutter 首次合成 Texture,直接切换仍会短暂暴露黑色初始缓冲。

影响:Android 首帧和 Surface 恢复时先在遮罩下合成 Texture 一帧;iOS 与其他平台时序保持不变。
原因:FlutterView 重挂载时 PAG Surface 未必触发销毁,旧 ready 状态会暴露黑色 Texture。

影响:Android 生命周期恢复时可由共享组件重新武装首帧门控;其他平台和普通暂停语义不变。
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant