118 lines
3.2 KiB
Markdown
118 lines
3.2 KiB
Markdown
# 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。
|
||
|
||
最终版本：
|
||
|
||
```text
|
||
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；
|
||
|
||
随后稳定：
|
||
|
||
```text
|
||
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。
|