STEP-094 通用 RenderSegment 分段渲染与 Style 分类诊断 v1

状态

PASS / CLOSED（RDC 代码与构建验收完成）

Codex 完成实现后，RDC 已独立完成 OpenGL Native 编译与定向 tests、Metal-only iPhoneOS 编译、RN TypeScript/codegen、Android Validation APK 构建与产物自检。规定的代码/编译验收门槛全部通过；Android/iOS 实体机运行与视觉验证本 STEP 未执行，明确保留为 NOT RUN。

起始基线

机器：Mac-mini-tei.lan
仓库：/Users/tei/dev/MapLibreParticleLab
分支：particle/main
起始 HEAD：8fbb892a1236a55329ed9ef5a612640c9363d3f1
起始 origin/particle/main：同上
V12 tag：maplibre-particle/rn/13.4.1-particle.12（7eaff6e12）
起始工作树：clean

实现结果

新增 typed Core RenderSegmentPlan / resolved plan / diagnostics model。
explicit plan、V12 Continuous Range 与 legacy boundary 统一进入一个 resolver。
Style boundary ID 在 RenderOrchestrator 按完整 orderedLayers 解析；hidden Layer 仍参与。
Renderer 改为 topology-sized cache vector；每个 Retained Segment 独立 lazy GPU cache，Continuous 无 retained resource。
Segment 按 Style 顺序执行，global layerIndex/original ordinal/currentLayer/depthRangeSize 保持。
Layer Impl fingerprint 支持明确 retained Segment 内的 layer-local invalidation；Source/Tile 等仍保守全 retained invalidation。
单 Continuous 保留既有 Particle Fast Path；多 Continuous fail closed 到 full CPU frame。
pull diagnostics 返回完整 Style→Segment→Layer、config/topology revision、coverage 与每个 retained cache 统计。
Android/iOS/RN 沿既有 WeatherRuntimeBridge 增加 plan 与 diagnostics JSON ABI；RN public API 为 typed object/discriminated union。
RN Test Host 增加 Apply C-R plan 与 Fetch Segment Diagnostics，只在用户操作时拉取一次。

定向测试源码

在既有 retained_underlay_cache.test.cpp 增加 RenderSegmentPlan/Diagnostics tests，覆盖：全 Retained、全 Continuous、C-R-R、R-R-C、R-C-R-C-R、相邻 R 不合并、missing/duplicate/reversed、hidden boundary、插入 Layer membership、boundary 删除/恢复、compat R-C-R/Continuous-only、visibility 不推进 topology revision、Cache OFF diagnostics、完整 coverage/flatten、Continuous cache=null、严格 JSON strategy/schema。

RDC 已执行过滤集：8 个 suite、43/43 tests PASS；其中 RenderSegmentPlan 9、RenderSegmentDiagnostics 4，并同时覆盖 V12 Continuous/Retained/Fast Path 回归。

RDC 验证结果

OpenGL：mbgl-test-runner 编译 PASS（exit 0）；定向过滤集 43/43 PASS。
Metal/iPhoneOS：确认 MLN_WITH_METAL=ON、MLN_WITH_OPENGL=OFF；ios-sdk-static 编译 PASS（exit 0）。
RN package TypeScript：PASS；RN Test Host 使用本工作树 package typecheck PASS。
RN codegen：顶层 npx react-native codegen 因工程未安装 @react-native-community/cli 无法作为入口；未修改依赖，改用当前已安装 RN 0.85 的 @react-native/codegen combine/generate-all 正式底层入口 PASS，并确认 Android Java/JNI、C++ JSI 与 iOS ObjC++ 生成物均含 setRenderSegmentPlanJson / getRenderSegmentDiagnosticsJson。
Android Validation APK：标准脚本 PASS；OpenglDebug / x86_64 / strip=true；APK 60,294,298 bytes；libmaplibre.so 39,421,736 bytes；SHA-256 848c3196c64cee6dfb1e9627f4af32b6e235fdd82afd1cfb8474c7fc5d591c71。
Android/iOS 实体机 runtime 与视觉：NOT RUN。
Jest：明确不加入、不执行。

RDC 验证重点

Core 编译：重点检查 rapidjson header、RenderLayer Impl metadata、JNI String ABI 与 ObjC++ selector。
Tests：验证 resolver/diagnostics 新 suites 及 V12 原有 Continuous/Retained/Fast Path suites。
OpenGL/Metal：确认 N retained resource、相邻 retained 不合并、稳定帧不重复创建。
RN codegen：确认新增两个 primitive JSON methods 在 Android/iOS generated Spec 与实现 selector 对齐。
Runtime：拉取 snapshot，核对 styleLayers 与 flatten(segment.layers) 完全一致；Cache OFF 仍保留 topology。

当前限制

多 Continuous Fast Path 未优化，按任务边界明确 fail closed。
Source/Tile mutation 无安全通用 dependency graph，仍全 retained invalidation。
旧 diagnostics 仅兼容摘要；新 API 才是多 Segment 权威事实。
多 Continuous Fast Path 仍按设计 fail closed，不是本 STEP 缺陷。
Android/iOS 真机运行和视觉结果不在本次 PASS 证据内。

下一步

实现代码已以 016fd1fff（feat: add generic render segment model）提交并 push。完成报告与本 Step 记录作为独立文档收尾 commit 提交；后续如需产品级 runtime/视觉确认，应另做 Android/iOS 运行态验收，不反向改变本 STEP 的代码验收结论。

4.8 KiB Raw Blame History Unescape Escape