STEP-092 Continuous Range 可退化分段 Retained Cache v1

状态

进行中：Codex 实现完成，等待 RDC 独立编译与运行验证

目标与基线

分支：particle/main
起始 HEAD：b29e564944197072a0effaec36ca95c48fe0649b
起始 origin/particle/main：b29e564944197072a0effaec36ca95c48fe0649b
Implementation commit：a9eaec6b65cc26aa70e03002bdc1326c46cad245（feat: add continuous retained render ranges），已 push 至 origin/particle/main。
Style Layer 顺序是唯一 Z-order；App 只提交现有 startLayerId / endLayerId 闭区间。
保留未配置 explicit range 时的 startsRetainedDynamicRange() legacy underlay 行为。

实现结构

RetainedUnderlayRuntimeState 是 map-scoped range config 所有者；使用 mutex 保护 ID/config/resolution，config revision 单调递增。
RenderOrchestrator::createRenderTree() 基于完整 orderedLayers（包含 hidden layer）把 ID 解析为 Style index；不存在、倒序或 Style 未 ready 均 fail closed，不保留旧 index。
内部统一使用 [continuousBegin, continuousEndExclusive)：Bottom、Continuous、Top 均由 Style index 自然退化。
现有 cache 泛化为带 begin/endExclusive 与 Bottom/Top role 的 retained range cache；两个 cache 对象不等于两个 GPU cache，texture/render target/compositor 只在对应 range 实际存在时 lazy 创建。
explicit valid 时完全忽略 legacy boundary；explicit invalid 时不用 legacy 猜测，走完整 Renderer。

四种结构

Style 结构	Render Range	Retained GPU cache
Bottom + Continuous + Top	3	2
Bottom + Continuous	2	1（Bottom）
Continuous + Top	2	1（Top）
Continuous only	1	0

startLayerId == endLayerId 是合法 single-layer Continuous。hidden endpoint 仍决定 topology；range 是否存在只看 Style index 区间，不看当前 drawable/group 是否为空。

绘制与 global index

cache build 的 opaque 使用区间 reverse traversal，translucent 使用 forward traversal。
callback ordinal 来自完整 layerGroupsByLayerIndex，parameters.currentLayer 与 depthRangeSize 沿用全 Style 语义，不对子区间重新编号。
main 顺序固定为：Bottom composite（若有）→ Continuous opaque/translucent → Top composite（若有）。
Top 与 Bottom 均使用透明 RGBA offscreen、现有 direct sample compositor 和 premultiplied alpha blend；未新增 land-mask 或业务判断。

Invalidation 与 fallback

camera/viewport/pixel ratio/style/layer/source/tile/image/glyph/placement/context/debug/3D 等继续进入 STEP-089 的 content/topology/static revision 模型。
range config revision、continuous begin/end、Bottom/Top topology 纳入 revision；配置变化会释放实际存在 cache 并使 prepared tree/fast gate 失配。
endpoint 删除、missing、倒序与 Style 未 ready：diagnostics 给出原因，cache key 变空并释放资源，full renderer 安全 fallback；后续 Style 恢复会重新解析。
correctness-first：无法只归因 Bottom 或 Top 时，两侧实际存在 cache 可同时失效。

Particle-only CPU Fast Path

gate 只要求实际存在的 retained cache valid；Bottom/Top 不存在时为 vacuous success，不产生 cache-missing miss。
fast frame 仅遍历 Continuous 区间，仍使用全局 ordinal。
explicit Continuous 中只允许 Renderer 已知的 WeatherColor/RasterParticle dynamic candidate；出现未知 Layer 时 fail closed 到 full CPU frame，但 range cache/Z-order 仍保持。
Continuous-only 可进入 0-cache fast gate；是否最终命中仍需满足 Particle、revision、placement、scene 等既有条件。

API 与 diagnostics

C++/Android/iOS/RN 增加 setContinuousLayerRange(..., startLayerId, endLayerId)；空 ID 拒绝，相同 ID 接受。
保留 setRetainedUnderlayEnabled() 与 getRetainedUnderlayDiagnostics()。
pull diagnostics 增加 configured/valid、IDs/index、Bottom/Top present/build/reuse/invalidation；保留 aggregate fallback 与 lastReason，无 per-frame Release 日志。

Directed tests

已新增源码覆盖：single/multi layer、missing/reversed、hidden endpoint、reorder/delete、四种 topology、0/1/2 cache decision、无 cache 的 fast gate、config revision 与 explicit/legacy 排他。

待 RDC 执行

cmake --build build-step088-opengl --target mbgl-test-runner -j3
build-step088-opengl/mbgl-test-runner \
  --gtest_filter='ContinuousLayerRange.*:RetainedDynamicBoundary.*:RetainedLayerGroupRange.*:RetainedUnderlayCache.*:RetainedUnderlayRevision.*:ParticleFastPath.*'
cmake --build build-ios --target ios-sdk-static -- -quiet
git diff --check

RDC 还需独立核验 OpenGL/Metal 透明 Top composite、0/1/2 texture/FBO 生命周期和 stable frame 复用。Android Gradle/APK/ADB/设备项未由 Codex 执行。

当前结论

源码与 directed test 已实现并完成 scoped implementation push；在 RDC 返回 OpenGL、Metal、Native test 实际结果前，本 Step 不判 PASS。

5.0 KiB Raw Permalink Blame History Unescape Escape