MapLibreParticleLab/docs/60_测试/30_02_GPU_PingPong与ContextRecreation最小技术验证报告_v3.md

30-02 GPU Ping-Pong 与 Context Recreation 最小技术验证报告 v3

日期：2026-08-30

当前状态：WAITING_MANUAL_VALIDATION

1. 本轮实机发现

用户在 30-02 v2 对应 Android OpenGL APK 上完成 T3 检查并明确报告：

• STATIC 静止时，粒子/Trail 正常停止；
• STATIC 下拖动地图时，MapLibre redraw 会使 State/Trail 继续推进；
• 停止拖动后，State/Trail 再次停止。

因此原实现的 T3 判定为 FAIL。这是明确的设备运行事实；本报告不补写用户未提供的 frame 数值或日志数值。

2. 原因

原实现只在 needsRepaint() 中用 ACTIVE/STATIC 控制验证层是否主动请求下一帧，但 RenderParticleValidationLayer::update() 没有按 ACTIVE/STATIC 区分 GPU 工作。

地图 pan/zoom/bearing/pitch 会合法触发 MapLibre redraw；每次 redraw 都会再次执行原 update()，继而：

1. 注册 State write RenderTarget；
2. 注册 Trail write RenderTarget；
3. 设置 pending=true；
4. composite Tweaker 调用 commit()；
5. State/Trail slot 与 committedFrame 前进。

所以 needsRepaint=false 只能停止 validation 自己制造的连续帧，不能保证在其他合法地图帧中冻结 GPU simulation。

3. 最小修复

仅修改：

• src/mbgl/renderer/layers/render_particle_validation_layer.cpp
• src/mbgl/renderer/layers/render_particle_validation_layer.hpp（说明性注释）

修复内容：

• update() 在已有资源上先撤销上一帧注册的 RenderTarget，然后读取当前 evaluated ACTIVE 状态。
• STATIC 分支不注册任何 State/Trail RenderTarget，不创建 State/Trail update Drawable，并清除任何 pending swap。
• STATIC 只为主 LayerGroup 建立 FrozenComposite Drawable，采样最后一次已经 commit 的 trailRead texture。
• FrozenComposite Tweaker可以在当前 MapLibre translucent pass 更新 composite UBO/texture 并读取当前 viewport、zoom、bearing、pitch，但在调用 commit() 前明确返回。
• STATIC 的 shader frame 值使用当前 committedFrame，不预先计算为下一 simulation frame。
• STATIC 下即使 viewport 改变也不重建、清空或推进 Trail；冻结 texture 由主 pass 重新显示。恢复 ACTIVE 后，既有 ACTIVE resize 路径才重建 Trail。
• 如果 layer 从未有过 ACTIVE/已 commit Trail 就直接处于 STATIC，不创建或清屏离屏资源，也不显示未初始化 texture。
• ACTIVE 路径的 State A/B、Trail A/B、pass 顺序、hazard 约束和 slot commit 保持不变。

4. 静态控制流确认

以下事实已经从修复后源码确认：

• AddRenderTargetRequest 只存在于 STATIC 提前返回之后的 ACTIVE 路径。
• State/Trail buildQuad() 只存在于 ACTIVE 路径。
• resources->pending = true 只存在于 ACTIVE 路径。
• STATIC 进入时强制 resources->pending = false。
• FrozenComposite 在 Tweaker 内先返回，不可能落入 resources->commit()。
• STATIC composite 绑定 trailTargets[trailRead]，read/write slot 参数相同且没有 target attachment。
• MapLibre redraw 没有被阻止；主 LayerGroup composite 仍会在当前地图 render pass 中执行。

5. 静态检查

• C++ clang-format --dry-run --Werror：PASS。
• git diff --check：PASS。
• ACTIVE/STATIC、RenderTarget 注册、pending、commit 与 committedFrame 控制流检索：PASS。
• 编译、Android、Gradle、ADB、安装与运行：未执行，遵守用户要求。

静态检查只能证明代码路径，不替代 Android OpenGL 重测。

6. T3 重新验证

使用包含修复提交 364b8f381e27eee36c4895084b2f0578a023fa61 的新 APK：

1. 进入 Particle Core Layer Validation，保持 ACTIVE，确认 State/Trail 正常交替并记下最近一次 commit frame=N、State read slot 与 Trail read slot。
2. 点击 STATIC，确认日志出现：STATIC frozen composite ... frame=N ... offscreenPasses=0 swap=false。
3. STATIC 静止至少 3 秒，确认粒子/Trail 不推进。
4. STATIC 下连续执行 pan、zoom、bearing、pitch；地图必须正常移动和 redraw，冻结 Trail 可以随主 pass 重新显示。
5. 操作期间确认画面中的 marker/fade 不推进；不得出现新的 State pass、Trail pass、slot swap 或 simulation commit frame 增长。
6. 停止操作后仍保持冻结。
7. 点击 ACTIVE，确认 GPU ping-pong 从冻结的 State/Trail slot 继续，而不是在 STATIC 操作期间跳过 frame/index；继续运行到下一次节流日志，确认 frame 恢复增长。
8. 再执行一次 ACTIVE → STATIC → 地图手势 → ACTIVE，排除只在首次切换正确。

用户手工日志命令：

adb -s 192.168.1.146 logcat | grep -E 'ParticleValidation30_02|ParticleValidation'

7. 仍需完成的 30-02 验证

本轮只修复 T3。以下仍沿用 v2 的待验证状态：

• 修复后 T3 Android OpenGL 重测；
• T4 resize；
• T5 disable/enable；
• T6/T7 真实 context/surface recreation 与恢复；
• 无 stale resource/framebuffer corruption/crash；
• 最终完整 PASS 证据。

当前最终状态仍为 WAITING_MANUAL_VALIDATION，不得写 PASS，也不允许进入 30-03。