MapLibreParticleLab/docs/报告/30_02_GPU_PingPong与ContextRecreation验证_Codex完成报告_v3.md

30-02 GPU Ping-Pong 与 Context Recreation 验证 Codex 完成报告 v3

日期：2026-08-30

执行结论：WAITING_MANUAL_VALIDATION

1. 输入与判定

用户提供了明确 Android OpenGL 运行现象：STATIC 静止时停止，STATIC 地图拖动时 State/Trail 随 redraw 继续推进，停止拖动后又停止。原 v2 实现的 T3 因此为 FAIL。

本轮授权范围仅是修复 30-02 STATIC freeze；未重新执行其他测试，也未扩大到正式粒子、Mask、Vulkan、iOS 或 30-03。

2. Git 基线

• 分支：particle/main。
• 本轮开始 HEAD：ba488f87027b3a53e7eb031e26c263c39a26bdc0。
• 开始时本地与 origin/particle/main 同步，工作区干净。
• 30-01 仍为正式 PASS。
• 30-02 v1 BLOCKED、v2 Stage A 文档与全部历史提交均保留。

3. 原因分析

needsRepaint() 正确地在 STATIC 返回 false，但它只决定 validation layer 是否主动请求 MapLibre 下一帧。地图手势产生的合法 redraw 仍会运行 RenderLayer update()。

原 update() 无条件建立 State/Trail write pass、注册 RenderTarget、设置 pending；主 composite Tweaker又无条件尝试 commit。因此每个由地图手势产生的帧都会推进 GPU ping-pong。缺陷不在 MapLibre redraw，而在 validation GPU scheduling 没有把 ACTIVE 状态作为执行 State/Trail pass 的硬门槛。

4. 修改文件

• src/mbgl/renderer/layers/render_particle_validation_layer.cpp
• src/mbgl/renderer/layers/render_particle_validation_layer.hpp
• docs/60_测试/30_02_GPU_PingPong与ContextRecreation最小技术验证报告_v3.md
• 本完成报告
• 粒子开发记录.md

没有修改 Test App、shader、通用 gfx、RenderTarget、Renderer 主循环或 style property。

5. 修复实现

• 新增 validation-only FrozenComposite pass mode。
• STATIC 有历史 Trail 时，主 pass 只采样当前已 commit 的 trailRead。
• STATIC 不注册 State/Trail RenderTarget，不运行 State update，不运行 Trail fade/marker update。
• STATIC 清除 pending；FrozenComposite Tweaker 在 commit() 前返回，不交换 slot、不增加 committedFrame。
• STATIC 仍在正常 MapLibre translucent render pass 内重绘 composite，并取得当前 viewport/zoom/bearing/pitch；没有阻止 pan/zoom/bearing/pitch redraw。
• STATIC resize 不重建 Trail，恢复 ACTIVE 后才由原 ACTIVE resize 路径处理。
• ACTIVE 恢复后沿用冻结时的 State/Trail read slot，继续既有 ping-pong。

6. 静态检查与未执行项

• clang-format --dry-run --Werror：PASS。
• git diff --check：PASS。
• GPU scheduling/commit 控制流检查：PASS。
• Android 编译、Gradle、ADB、安装、运行：未执行。
• C++ 编译：未执行。

严格遵守用户“不运行 Android 编译、Gradle 或 ADB”以及此前“不要编译”的要求。

7. 重新验证要求

技术报告 v3 第 6 节给出完整 T3 重测步骤。关键证据是：

• STATIC 日志显示固定 frame=N、固定 State/Trail read slot、offscreenPasses=0 swap=false；
• STATIC 地图手势正常，但 marker/fade、State/Trail pass、slot 与 simulation frame 不推进；
• ACTIVE 恢复后从 N 继续增长。

其他 T4–T7 项仍按 v2 执行。

8. Git 收尾

• STATIC 修复 commit：364b8f381e27eee36c4895084b2f0578a023fa61。
• commit message：fix: freeze particle gpu state in static mode。
• 修复 commit push：成功。
• 公开远端：origin（ssh://git@192.168.200.230:2222/tei/MapLibreParticleLab.git）。
• 远端分支：particle/main。
• 修复 push 后远端可见 HEAD：364b8f381e27eee36c4895084b2f0578a023fa61。
• v3 报告/开发记录收尾 commit 与最终远端 HEAD：按自引用规则在最终回复记录。
• 无未提交的无关修改。

9. 当前状态与范围

原 T3 实机结果已如实记为 FAIL；修复后的 T3 尚未由用户重测。因此 30-02 总体状态继续为 WAITING_MANUAL_VALIDATION，不得写 PASS，不允许进入 30-03。