MapLibreParticleLab/docs/50_Step记录/STEP-088_静态底图缓存PoC与Renderer观测_v3.md

STEP-088 静态底图缓存 PoC 与 Renderer 观测 v3

状态

ANDROID / NATIVE VALIDATION PASS；STEP-088 收尾。

STEP-088 已验证 retained underlay 能停止静态 LayerGroup 的重复 GPU draw，并补充了 Release 可用的运行时 Cache ON/OFF、最小诊断接口、Android/iOS Native API、React Native RendererRuntime，以及 Android Test App 的真实 NavSea PBF 性能基线工具。

本轮新增能力

• Retained Underlay 默认开启，可按 Map 实例运行时开启/关闭。
• 关闭时立即失效缓存并恢复原始 full-render；重新开启后在满足条件时重新 build/reuse。
• Release 保留最小 pull-based diagnostics：enabled/build/reuse/fallback/invalidation/lastReason。
• Debug 继续保留详细 ParticleRetained 周期日志。
• RN 新增 RendererRuntime：
  • setRetainedUnderlayEnabled(reactTag, enabled)
  • getRetainedUnderlayDiagnostics(reactTag)
• Android Test App 新增：
  • NavSea 正式 63 层 PBF Style；
  • Particle 位置 BOTTOM / AFTER_SEA / AFTER_CLIP / BEFORE_SYMBOL_CLUSTER / TOP；
  • runtime Cache ON/OFF；
  • PBF ON/OFF；
  • PURE PARTICLE；
  • PURE PBF；
  • CUSTOM PARTICLE COUNT，范围 1..10000。

关键 Android 性能证据

测试设备：Android 13 / x86_64 / FZG1-2，固定唐津 Camera，Particle target FPS 30。

• PURE PARTICLE，2048 粒子，无 PBF：
  • RenderThread ≈ 10.2%
  • Process ≈ 13.7%
  • Main ≈ 2.5%
• PURE PBF，63 层正式 Style，无 Particle：
  • RenderThread ≈ 0%
  • Process ≈ 0%
• NavSea Style 保留、60 个 navsea_delivery layer 全隐藏、Particle 2048：
  • RenderThread ≈ 25.5%
  • Process ≈ 29.1%
• PBF + Particle，AFTER_CLIP：
  • Cache ON RenderThread ≈ 96.5%，Process ≈ 102.2%
  • Cache OFF RenderThread ≈ 99.5%，Process ≈ 111.8%
• PBF + Particle，BEFORE_SYMBOL_CLUSTER：
  • Cache ON RenderThread ≈ 96.5%，Process ≈ 102.8%
  • Cache OFF RenderThread ≈ 100.2%，Process ≈ 114.2%
• TOP 因 static-placement/static-transition 持续 fallback，不能作为稳定 retained 场景。

结论：STEP-088 能消除静态 GPU draw，但主要 CPU 成本仍来自 Particle continuous repaint 下 PBF/vector/static renderer pipeline 被反复处理。该证据支持下一阶段先做 STEP-089 invalidation/revision 基础，再进入 STEP-090 Static CPU Fast Path。

验证结果

• Android x86_64 stripped Debug Validation APK：BUILD SUCCESSFUL，约 57 MB，实机通过。
• Mac OpenGL mbgl-test-runner：PASS。
• STEP-088 directed tests：5/5 PASS。
• iOS Metal mbgl-core：BUILD SUCCEEDED。
• iOS ios-sdk-static：BUILD SUCCEEDED。
• RN package TypeScript：PASS。
• RN Test Host TypeScript：PASS。
• RN iOS bridge 单独编译：被 Test Host 仍引用旧 STEP-083 本地 SwiftPM 包阻塞；旧包缺少本轮新增 MLNMapView retained-underlay API。当前源码 iOS SDK 已通过编译，因此该项记录为测试宿主产物过期，不阻塞 STEP-089。
• git diff --check：PASS。

下一步

进入 STEP-089：建立静态内容 invalidation/revision 可靠判据，只做 fast-path 前置安全基础，不提前实现 STEP-090 的 CPU fast path。