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

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

日期：2026-08-29

执行结论：WAITING_MANUAL_VALIDATION

1. 前置状态与 Git 基线

• 30-01 正式状态：PASS。
• 30-01 PASS 回填 commit：b34b0a3e22f91a0101b0bbd02190e3384f6ef2ae。
• 本任务开始分支：particle/main。
• 本任务开始 HEAD：b34b0a3e22f91a0101b0bbd02190e3384f6ef2ae。
• 开始时本地与 origin/particle/main 同步，工作区干净。
• 历史阻塞 commit 25072cff1b3a538af361b572cd7e79cd4a471b07 与 30-02 v1 BLOCKED 报告均完整保留。

2. 前置材料读取

已读取 AGENTS.md、PARTICLE_BASELINE.md、docs/00_项目总则/、docs/00_项目规范/、当前 STEP-000、30-02 指令书、架构调查/设计、30-01 最新 PASS 技术报告与完成报告、30-02 v1 历史阻塞报告及 粒子开发记录.md。按指令书未创建或修改 Step。

3. 实际修改文件

Core validation 与 shader：

• src/mbgl/renderer/layers/render_particle_validation_layer.cpp/.hpp
• shaders/particle_gpu_validation.vertex.glsl
• shaders/particle_gpu_validation.fragment.glsl
• shaders/manifest.json
• include/mbgl/shaders/gl/particle_gpu_validation.hpp
• include/mbgl/shaders/particle_gpu_validation_ubo.hpp
• include/mbgl/shaders/gl/shader_info.hpp
• include/mbgl/shaders/shader_defines.hpp
• include/mbgl/shaders/shader_manifest.hpp
• include/mbgl/shaders/shader_source.hpp
• src/mbgl/shaders/gl/shader_info.cpp
• src/mbgl/shaders/shader_source.cpp
• src/mbgl/gl/renderer_backend.cpp

Android Test App：

• platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt
• platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_particle_core_layer_validation.xml
• platform/android/MapLibreAndroidTestApp/src/main/res/values/strings.xml

文档：本 v2 完成报告、对应 v2 技术报告，并追加 粒子开发记录.md。

4. State A/B 实现与创建链

ParticleGpuValidationResources 持有两套固定 16x16、RGBA unsigned-byte RenderTarget。创建链为 gfx::Context::createRenderTarget → 现有 RenderTarget/OffscreenTexture → 独立 texture；每个 target 各有一个 validation-only LayerGroup。State shader 从 read slot 采样并将确定性演进结果写到相反 slot，没有 CPU full-state copy。

5. Trail A/B 与 composite

Trail A/B 是两套 viewport 尺寸的真实 RenderTarget。Trail pass 采样 previous trail，执行 fade 加移动 marker，写 next trail。主 RenderLayer 的 translucent Drawable 随后采样本帧 next trail并以预乘 alpha 合成到 MapLibre 主 pass；没有 MapView 外部 Overlay。

6. ping-pong swap、pass 顺序与 hazard

• 正常帧只注册 State write 和 Trail write；对应 read target 不进入当帧 render-target list。
• 初次创建/resize 时，新的 read target 以空 LayerGroup 先清屏。
• RenderOrchestrator 按添加顺序访问 RenderTarget；本层添加顺序保证 State 在 Trail 前，主 LayerGroup composite 在所有 offscreen target 后。
• Drawable Tweaker 在主 translucent pass 到达时提交 A/B slot 交换，因此下一帧才把本帧输出作为 read。
• Tweaker 同时比较 source/target texture identity，异常时输出 HAZARD；正常节流日志输出 distinct=true。
• 该结论目前是源码/调度顺序确认；Android OpenGL driver 的实际同步语义仍待用户实机日志与画面确认。

7. Android OpenGL backend 事实

新增 shader 只加入 OpenGL RendererBackend::initShaders、GL ShaderInfo 与生成的 GL source。没有添加 Vulkan/Metal/WebGPU shader，也没有把 raw OpenGL 调用写入 Core validation 逻辑。

8. resize、disable/enable、context lifecycle 与 generation

• resize：仅销毁并重建 Trail A/B；State A/B 不重建，日志标记 StatePreserved=true。
• disable：renderability 关闭时移除 target、清空验证 Drawable、重置 frame/slot；当前 Test App 的 DISABLE 通过移除 validation layer 强制完整 resource destroy。
• enable：Test App 重新加入 validation layer，新 resource generation 从初始 slot/frame 创建。
• context/surface：Android OpenGL 现有 surface lifecycle 会通知 renderer context lost；本 RenderLayer 的 markContextDestroyed() 记录旧 generation discard，RenderLayer 重建时进程内 atomic generation 递增。
• generation 机制只服务验证日志，不是正式粒子资源管理 API。

9. Test App 入口

继续复用 Custom Layer → Particle Core Layer Validation，保留 30-01 ACTIVE/STATIC，并增加 DISABLE/ENABLE。主菜单既有 APK version/renderer/build type/Git revision 标识保持不变。没有创建第二套 Test App 或产品 UI。

10. 手工编译与运行

手工编译命令：

cd /mnt/sda1/MapLibreParticleLab
source /root/.maplibre-particle-env
cd platform/android
RENDERER=opengl BUILDTYPE=Debug JOBS=3 make android-x86-64

APK 预期路径：platform/android/MapLibreAndroidTestApp/build/outputs/apk/opengl/debug/MapLibreAndroidTestApp-opengl-debug.apk。

完整 T1–T7 手工运行步骤、带 adb -s 192.168.1.146 的安装/启动/logcat 示例见技术报告 v2 第 6–7 节。

11. 检查与未执行项

• shader manifest JSON：PASS。
• shader 生成/注册链静态一致性：PASS。
• C++ clang-format：PASS。
• git diff --check：PASS。
• Android XML：人工结构检查；环境无 XML parser，未宣称工具 PASS。
• Android/Gradle/ADB/APK 构建安装：未执行。
• 任何 C++/Android 编译：未执行，遵守用户“不要编译”。
• 用户实机日志、画面、resize、context recreation：尚未提供。

12. 修改边界

• 通用 gfx API：未修改；现有 API 足以表达本验证。
• 正式生产 Particle/Field/Mask：未实现。
• 依赖、SDK、NDK、Gradle、MapLibre baseline：未修改。
• Vulkan/iOS/Metal、30-03：未开始。
• Shader/OpenGL backend 的修改仅是注册 validation-only shader，不是通用 renderer 重构。

13. 当前判定与 30-03

Stage A 代码已准备并推送，但所有关键 GPU/context 门槛仍缺用户实际运行证据，因此状态必须为 WAITING_MANUAL_VALIDATION，不是 PASS/FAIL。30-03 不允许开始；若用户环境最终无法用日志确认真实 context recreation，则 30-02 应判定 BLOCKED。

14. Git 收尾

• 主要变更 commit：2f1506747b1dad8e89e526058a2951e9734ba99b。
• commit message：test: add particle gpu ping-pong validation。
• 主要变更 push：成功。
• 公开远端：origin（ssh://git@192.168.200.230:2222/tei/MapLibreParticleLab.git）。
• 远端分支：particle/main。
• 主要变更远端可见 HEAD：2f1506747b1dad8e89e526058a2951e9734ba99b。
• 本文档与开发记录的收尾 commit 及最终远端 HEAD：按指令书的自引用处理规则，在最终回复中记录。
• 未提交的无关本地改动：无。