STEP-089 静态渲染 Revision 与 Invalidation 基础层 v1

状态

CLOSED / PASS

STEP-089 已完成 retained underlay 的静态状态 revision / invalidation 基础层，为 STEP-090 Static CPU Fast Path 提供可靠的安全门控。

核心实现

新增单调递增的静态 revision / generation。
retained cache build 时记录 buildRevision。
reuse 前要求 buildRevision 与当前 staticRevision 一致。
新增稳定 topology snapshot：
- dynamic boundary；
- static prefix 中每个 LayerGroup 的 layerIndex；
- groupName；
- groupType。
真正的 LayerGroup 增删、排序、index 变化会推进 topologyRevision。
Renderer 内部 transient drawable churn 不再直接推进 static revision。
等价的 stencil tile set 不因 shared_ptr identity 变化而误失效。
支持并记录以下语义失效来源：
- camera / viewport / pixel ratio；
- style / layer / source mutation；
- tile content change；
- image / sprite / glyph；
- placement / fade；
- context reset；
- debug options；
- 3D / unsupported custom/static layer。
unsupported / uncertain 场景继续 fail-closed。
STEP-088 runtime Cache ON/OFF 行为保持不变。
未实现 STEP-090 CPU fast path。

Android 实机关键验证

测试场景：

Android 13 / x86_64；
NavSea 正式 63 层 PBF Style；
Particle = AFTER_CLIP；
固定 Camera：Karatsu；
Cache ON。

稳态

修复前曾出现：

drawable-mutation 每帧失效；
layer-group-mutation 每帧失效；
staticRevision 每帧递增；
build 每帧递增；
reuse=0。

最终版本：

frame=480  build=2  reuse=302  staticRevision=21  buildRevision=21
frame=600  build=2  reuse=422  staticRevision=21  buildRevision=21
frame=720  build=2  reuse=542  staticRevision=21  buildRevision=21

确认：

staticRevision 稳定；
buildRevision == staticRevision；
build 不再增长；
reuse 持续增长。

Camera 变化

相机变化后：

staticRevision: 41 -> 44；
build: 18 -> 19；
buildRevision = 44；

随后稳定：

build=19
reuse=3519 -> 3639 -> 3759 -> 3879
staticRevision=44
buildRevision=44

确认真实变化会使 revision 前进并重建一次，稳定后恢复 reuse。

Native 测试

Retained directed tests：12/12 PASS。

覆盖：

dynamic boundary；
layer group range；
cache build/reuse/invalidation；
runtime Cache ON/OFF；
revision 单调；
无语义变化时 revision 不前进；
等价 intra-frame remove/add 不推进 topology；
持久 topology 变化只推进一次；
ordering/index 变化推进 topology；
buildRevision 匹配才允许 reuse；
placement/fade 活跃时拒绝 stale cache。

构建验证

Mac OpenGL mbgl-test-runner：PASS。
Metal/iOS mbgl-core：BUILD SUCCEEDED。
Android x86_64 stripped Debug Validation APK：BUILD SUCCESSFUL，约 57 MB。
Android 实机稳态 reuse：PASS。
Android Camera invalidation -> rebuild -> reuse：PASS。
git diff --check：PASS。

结论

STEP-089 已建立可信的 static revision gate。后续 STEP-090 可以在该 gate 为稳定状态时尝试跳过静态 PBF/vector CPU processing；089 本身不做 CPU fast path。

下一步

进入 STEP-090：Static CPU Fast Path。

3.2 KiB Raw Permalink Blame History Unescape Escape