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

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

日期：2026-08-30

当前状态：WAITING_MANUAL_VALIDATION

1. 已确认实机状态与本轮问题

用户已确认此前 C++ STATIC freeze 修复有效：在 STATIC 下 pan、zoom、bearing、pitch 触发的普通 MapLibre redraw 不再推进 GPU simulation。DISABLE / ENABLE 也已由用户确认正常。

本轮 Android OpenGL 实机发现是另一层问题：屏幕旋转触发 Activity recreation 后，旋转前的 STATIC + ENABLED 被恢复成 ACTIVE + ENABLED。

该现象不改变已确认的 C++ STATIC freeze 结论；它是 Test App validation control mode 未在标准 Android Bundle 中恢复的问题。

2. 根因

ParticleCoreLayerValidationActivity 在 Activity 存活期间已经由 loadValidationStyle(active, enabled) 维护两个成员状态。但旧代码：

• 没有在 onSaveInstanceState() 保存 active、enabled；
• 在 onCreate() 的 Map callback 中无条件调用 loadValidationStyle(active = true, enabled = true)；
• 同时无条件重置相机到 (0, 0), zoom=2。

因此标准旋转 recreation 无论此前为 STATIC、ACTIVE 或 DISABLED，都会退回 ACTIVE + ENABLED。

3. 定向修复

仅修改：

• platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt

具体调整：

• 新增稳定 Bundle key：particle_validation.active、particle_validation.enabled；
• onCreate() 在 Map 初始化前恢复两个成员变量，首次进入默认 ACTIVE + ENABLED；
• getMapAsync 只在首次进入时设置默认 camera；recreation 时保持 MapView 的已保存状态；
• 恢复后的 active/enabled 仍只通过既有 loadValidationStyle() 应用 style 与页面状态；
• onSaveInstanceState() 写入两个 validation control 值，同时保留原有 MapView state 保存顺序；
• 新增低频日志：Activity state restored active=<...> enabled=<...> recreated=<...>。

未修改 AndroidManifest、layout、strings、C++ Core、gfx、RenderLayer、shader、GPU state、Gradle 或依赖。没有使用 configChanges、方向锁定、static/global、SharedPreferences、ViewModel 或 GPU 状态序列化。

4. 静态检查

• S1：Activity 中已不存在 recreation 后无条件 loadValidationStyle(active = true, enabled = true)：PASS。
• S2：savedInstanceState == null 时默认 ACTIVE + ENABLED 且设置初始 camera：PASS。
• S3：ACTIVE、STATIC、DISABLE、ENABLE 按钮仍调用唯一 loadValidationStyle()：PASS。
• S4：loadValidationStyle() 继续统一更新成员状态、style 和状态文字：PASS。
• S5：没有 Manifest workaround、持久化、全局状态或 GPU 资源状态：PASS。
• git diff --check：PASS。
• Kotlin/Android 编译、Gradle、ADB、安装与实机运行：未执行，遵守任务限制。

5. Rotation 重新验证

使用包含代码提交 503f1c66958798ef7294165c3ddeaffbd4908ee9 的新 APK。日志过滤：

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

1. R1 STATIC rotation：ACTIVE 运行几秒 → STATIC → 确认停止 → 竖屏/横屏互转两次。每次日志应为 active=false enabled=true recreated=true，页面保持 STATIC，不能自动 ACTIVE。
2. R2 ACTIVE rotation：ACTIVE 下旋转，日志应为 active=true enabled=true recreated=true，页面保持 ACTIVE。
3. R3 DISABLED rotation：DISABLE 后旋转，日志应为 active=<切换前值> enabled=false recreated=true，页面保持 DISABLED，不能自动 ENABLE。
4. R4 STATIC gesture regression：STATIC 下 pan、zoom、bearing、pitch；地图正常 redraw，但 GPU simulation 仍不得推进，验证本轮没有破坏 v3 的 C++ freeze。

6. 判定边界

Rotation 通过只能证明 validation control mode 在 Activity recreation 后恢复正确；它不能单独判定 T4 viewport resize 或 T6/T7 context/resource recreation PASS。旋转路径可能同时重建 Activity、MapView、RenderLayer 和 GPU resources，旧 Trail 不要求跨 Activity 保存。

30-02 总体状态仍为 WAITING_MANUAL_VALIDATION，等待 R1–R4 人工证据；不得写 PASS，也不允许进入 30-03。