MapLibreParticleLab/docs/报告/STEP-088_静态底图缓存PoC与Renderer观测_Codex完成报告_v1.md

STEP-088 静态底图缓存 PoC 与 Renderer 观测 Codex 完成报告 v1

1. 执行结论

• 状态：IMPLEMENTED / WAITING FOR ANDROID VALIDATION
• 结论：Retained Static Underlay PoC、OpenGL/Metal compositor、Renderer counters 与 Native 定向测试代码已实现；RDC 已完成 Mac OpenGL/Metal 编译和 4/4 定向测试。Android/NavSea 尚未验证，因此不关闭 Step，也不进入 STEP-089/090。

2. Git 基线

• 机器：Mac mini，Darwin x86_64
• 仓库：/Users/tei/dev/MapLibreParticleLab
• 分支：particle/main
• 起始 HEAD：f47469d2ab77cdb959ecfe4081dc571fa1ab78f9
• STEP-088 实现 Final HEAD：8b9ab303228c307612c47f7f3379ad06206ea14e
• 实现提交信息：feat: add retained underlay render cache poc
• 当前版本坐标：13.4.1-particle.10
• 实现 push：成功，f47469d2a..8b9ab3032 particle/main -> particle/main
• 远端分支：origin/particle/main
• 既有 dirty/untracked：保留且未暂存，包括 AGENTS.md、两个 modified submodule、platform/ios/app/MBXAppDelegate.m 与用户既有任务文档。

3. 开工前只读确认

已按当前代码确认：

• RasterParticle 与 WeatherColor 的 needsRepaint() 经 RenderOrchestrator::hasTransitions() 驱动完整 MapLibre frame。
• Renderer::render() 每帧仍调用 createRenderTree()，随后进入 Renderer::Impl::render()。
• updateLayers/processChanges、LayerGroup tweaker/upload、visitRenderTargets 均位于 draw 分段之前，STEP-088 未跳过。
• main clear、opaque reverse、translucent forward、legacy items、debug、postRender、present 的原始顺序已核对。
• RenderTarget / OffscreenTexture 以及 Heatmap/Hillshade 的 offscreen + texture composite 模式已作为实现样板，未修改 Heatmap/Hillshade 自身语义。
• background layer optimized-as-color 继续通过 main framebuffer backgroundColor clear；underlay offscreen 使用透明 clear。

4. 实际实现

Boundary

• src/mbgl/renderer/render_layer.hpp：增加 Renderer-internal boundary 与 legacy-rendering virtual hooks。
• render_weather_color_layer.hpp、render_raster_particle_layer.hpp：声明为 boundary candidate。
• render_location_indicator_layer.hpp：标识 legacy rendering，供 boundary 以下 ordering fallback。
• render_orchestrator.cpp：在实际 ordered layers 上取最小 candidate index。

LayerGroup 分段

• render_orchestrator.hpp：增加 before/from、forward/reverse 四种 visitor，callback 获得完整 LayerGroup 序列 original ordinal。
• renderer_impl.cpp：currentLayer = totalGroups - 1 - originalOrdinal，depthRangeSize 仍按完整 group 数计算，避免子集从 0 编号改变 depth/transparency。

Cache 与 Renderer Flow

• 新增 retained_underlay_cache.hpp/.cpp：管理 key、valid、RGBA offscreen、compositor group、build/reuse/fallback counts 与 last invalidation reason。
• key 包含 viewport、boundary 与 projection/camera matrix。
• retained path 只改真正 draw 阶段；createRenderTree、source/layer update/prepare、tweaker/upload 全部保留。
• cache build 顺序为 independent targets → static opaque/translucent to offscreen → main clear → cached composite → dynamic opaque/translucent → legacy/debug/postRender/present。

Compositor 与 Backend

• 新增 RetainedUnderlayCompositeShader 的 OpenGL GLSL/generated header 与 Metal shader source/metadata。
• shader manifest、BuiltIn enum、shader info/defines、GL/Metal backend registration 与 CMake source lists 已接线。
• gfx Context 增加四参数 offscreen virtual；OpenGL 补齐 depth/stencil renderbuffer attachment，Metal/Vulkan/WebGPU 明确 override 已有实现。

Debug Counters

在 include/mbgl/particle/renderer_debug_counters.hpp 新增：

• FullRendererFrame
• RetainedUnderlayBuild
• RetainedUnderlayReuse
• RetainedUnderlayFallback
• RetainedUnderlayInvalidation
• RetainedUnderlayStaticGroupDraw
• RetainedDynamicGroupDraw

Release/NDEBUG 仍 no-op，不增加 Host API，不逐帧刷日志。

5. 修改文件

实现提交共 39 个文件：

• 构建：CMakeLists.txt、cmake/opengl.cmake、cmake/metal.cmake、test/CMakeLists.txt。
• Context/Offscreen：include/mbgl/gfx/context.hpp、include/mbgl/{mtl,vulkan,webgpu}/context.hpp、src/mbgl/gl/context.cpp/.hpp、src/mbgl/gl/offscreen_texture.cpp/.hpp。
• Renderer：src/mbgl/renderer/render_layer.hpp、render_orchestrator.cpp/.hpp、renderer_impl.cpp/.hpp、三个相关 RenderLayer headers、新增 retained_underlay_cache.cpp/.hpp。
• Shader：shaders/manifest.json、两个新增 GLSL、GL/Metal generated/handwritten headers、Metal source、shader source/manifest/defines/info 与 GL/Metal backend registration。
• 观测：include/mbgl/particle/renderer_debug_counters.hpp。
• 测试：新增 test/renderer/retained_underlay_cache.test.cpp；RDC 小修 test/gl/gl_functions.test.cpp 的 Apple/macOS 符号条件。

6. Fallback 与安全边界

• 无 boundary：原 Renderer。
• static prefix 为空、style 未 loaded、has3D、debug options：full render。
• static prefix 存在 transition/repaint、symbol placement/fade 或 source fading tile：full render。
• boundary 以下存在 legacy renderer item：full render。
• viewport、camera fingerprint、boundary 改变：cache invalid 后 build。
• offscreen texture/compositor 创建或 renderable 检查失败：计数并 full-render fallback。

STEP-088 的成立前提是固定 Camera 且 Style/Tile 稳定。production 级 style/tile/drawable/context invalidation 明确留给 STEP-089，未在本次越界实现。

7. 新增文件

• include/mbgl/shaders/gl/retained_underlay_composite.hpp
• include/mbgl/shaders/mtl/retained_underlay_composite.hpp
• shaders/retained_underlay_composite.vertex.glsl
• shaders/retained_underlay_composite.fragment.glsl
• src/mbgl/renderer/retained_underlay_cache.hpp
• src/mbgl/renderer/retained_underlay_cache.cpp
• src/mbgl/shaders/mtl/retained_underlay_composite.cpp
• test/renderer/retained_underlay_cache.test.cpp

8. 与任务书差异

• 功能范围无扩大：未进入 STEP-089/090。
• 按新 AGENTS.md，长时间 Mac 编译/测试由 RDC 执行，Codex 只负责实现、静态审计、文档与 Git 收尾。
• RDC 为完成 Mac OpenGL test-runner 链接，增加了任务范围内必要的 test/gl/gl_functions.test.cpp Apple/macOS 平台条件小修。
• 没有提交用户对 AGENTS.md 的全局流程修改，也没有提交既有无关 dirty/untracked。

9. RDC 构建与测试记录

• OpenGL：cmake --build build-step088-opengl --target mbgl-test-runner -j3，结果成功。
• 定向测试：4/4 成功：
  • RetainedDynamicBoundary.SelectsFirstCandidate
  • RetainedLayerGroupRange.PreservesForwardReverseOriginalOrdinals
  • RetainedUnderlayCache.BuildReuseAndInvalidation
  • RetainedUnderlayCache.UnsupportedAndResourceFailureFallBackSafely
• iOS/Metal device arm64：cmake --build build-ios --config Debug --target mbgl-core -j3，结果 BUILD SUCCEEDED。
• git diff --check：成功。
• RDC 小修说明：Darwin 的 gl functions 实现仅在 iPhone/Simulator 定义 glInvalidateFramebuffer / glInvalidateSubFramebuffer；macOS test-runner 不应无条件引用，故增加 Apple target 条件。该修复仅影响测试平台链接，不改变 Renderer 业务语义。

按最新 AGENTS.md 分工，以上长时间编译/测试由 RDC / 普通 Terminal 执行并回传；Codex 最终收尾没有再次启动 build/test。

10. Android 未执行与无法验证

以下均未执行：Android Gradle、AAR/APK、ADB、Android 真机/模拟器、NavSea 实机、Jest。因此无法验证复杂 NavSea Style 下的实际视觉、缓存 counters、draw-call 降幅、RenderThread/main/JS CPU 收益以及所有交互 invalidation。

11. PoC 限制、已知问题与未完成事项

• 未实现 STEP-089 的 production 全量 invalidation。
• 未实现 STEP-090 的 Map/update/createRenderTree/source/prepare CPU fast path。
• 未修改 NavSea、React、Host API 或 C-001。
• Android/NavSea 手工验证待用户执行；结果回传前不得把本 Step 标记为关闭。

12. 生成产物

本 Step 不生成 AAR/APK/XCFramework/npm artifact；没有发布物、ABI、大小或 SHA-256。Mac 输出仅用于编译/测试验证，不作为发行 artifact。

13. 是否满足进入 STEP-089 条件与下一步建议

当前不满足。进入 STEP-089 的前置条件是用户/RDC 在 Android/NavSea 复杂真实 Style 上确认：画面与 ordering 正确、fixed Camera 下 build 约一次且 reuse/Particle advance 持续、static group draw 不随 Particle FPS 增长、camera/resize/fallback 不出现 stale cache。STEP-088 未取得这些证据前不得进入 STEP-089；STEP-090 同样未执行。

下一步只建议执行 STEP-088 Android/NavSea 手工验证，不创建或执行新的 Step。

14. Git 收尾

• Final implementation commit hash：8b9ab303228c307612c47f7f3379ad06206ea14e
• Commit message：feat: add retained underlay render cache poc
• Push result：成功
• Remote branch：origin/particle/main
• STEP-088 implementation Final HEAD：8b9ab303228c307612c47f7f3379ad06206ea14e
• 本报告与 Step/开发记录由后续独立 docs closeout commit 承载；该提交的精确 hash 因 Git commit 不能自引用，记录在最终响应和远端 HEAD 核验中。