diff --git a/docs/30_设计/STEP-094_通用RenderSegment模型与Style分类Diagnostics设计_v1.md b/docs/30_设计/STEP-094_通用RenderSegment模型与Style分类Diagnostics设计_v1.md new file mode 100644 index 000000000..e724e9bd9 --- /dev/null +++ b/docs/30_设计/STEP-094_通用RenderSegment模型与Style分类Diagnostics设计_v1.md @@ -0,0 +1,141 @@ +# STEP-094 通用 Render Segment 模型与 Style 分类 Diagnostics 设计 v1 + +## 1. 目标与边界 + +Renderer 只接收 Style 顺序和一组连续 Segment 定义。每个 Segment 的执行策略只有 `RETAINED` 或 `CONTINUOUS`；不引入 LOW/MEDIUM/HIGH，不识别 AIS、Route、Weather 等业务语义，不改变 Style Z-order，也不增加 Anchor/Marker Layer。 + +V12 的 Bottom Retained / Continuous / Top Retained 是本模型的兼容特例。新实现只有一套 resolved topology；旧 `setContinuousLayerRange()` 先转换为通用 Segment Plan，再进入同一 Renderer 路径。 + +## 2. 公共数据模型 + +Core 公共类型位于 `include/mbgl/renderer/render_segment.hpp`： + +```text +RenderSegmentPlan + schemaVersion = 1 + segments[1..N] + strategy = RETAINED | CONTINUOUS + startLayerId = 第 1 段省略；后续段必填 +``` + +RN 公共类型位于 `packages/maplibre-particle-rn/src/types.ts`，`RendererRuntime.setRenderSegmentPlan(reactTag, plan)` 接收 typed object。TurboModule、Android/iOS package bridge 与 platform API 内部使用 schema-versioned JSON，JS 调用方不接触 raw JSON。 + +## 3. Config / Resolve 生命周期 + +1. map-scoped runtime state 保存 active config、`configSource` 和单调递增 `configRevision`。 +2. `setRenderSegmentPlan()` 将 active source 切到 `explicit-render-segment-plan`。 +3. `setContinuousLayerRange()` 将 active source 切到 `continuous-range-compat`，不会再并存第二套 Renderer topology。 +4. 没有显式配置时，既有 `startsRetainedDynamicRange()` 仅通过 `unconfigured/legacy` adapter 生成兼容 plan。 +5. RenderOrchestrator 只在 config、Style ready、Layer add/remove/change 时重新解析 boundary ID 和 diagnostics metadata；Particle 高频 Fast Path 不扫描/复制 Style 字符串，也不 stringify JSON。 +6. `topologyRevision` 只在 resolved strategy/begin/end 签名变化时递增。Visibility 变化更新 `visible`，不改变 topology revision。 + +显式 plan 合法条件：definitions 非空；第 0 段无 boundary；第 1..N-1 段 boundary 存在、非空且 index 严格递增；每段非空；完整覆盖 `[0, layerCount)`。失败时 segments 为空、`valid=false`、释放旧 cache 并走 full renderer；ordered `styleLayers` 仍可读取。 + +## 4. V12 Compatibility Mapping + +旧闭区间 `[startLayerId,endLayerId]` 解析为： + +```text +startIndex > 0 -> RETAINED [0,startIndex) + CONTINUOUS [startIndex,endIndex+1) +endIndex+1 < styleLayerCount -> RETAINED [endIndex+1,layerCount) +``` + +因此自然退化为 R-C-R、R-C、C-R 或 C。`configSource=continuous-range-compat`。旧 `getRetainedUnderlayDiagnostics()` 继续保留摘要；多段真实事实以新 API 为准。 + +## 5. Renderer 执行与 Cache Ownership + +Resolved Segment 保留 Style 全局 `layerIndex` 和 LayerGroup 原 ordinal。Retained 构建继续使用 opaque reverse / translucent forward；Continuous 直接绘制同一全局 index 范围。`parameters.currentLayer` 和 `depthRangeSize` 不按 Segment 重新编号。 + +Renderer 按 resolved topology 动态创建 `retainedSegmentCaches[segmentIndex]`： + +- RETAINED：独立 `RetainedUnderlayCache`、key、revision、texture、compositor 和 counters； +- CONTINUOUS：对应 slot 为空，不创建 retained texture/FBO/compositor； +- topology 改变：旧 cache 在 Renderer 线程释放，不能迁移或 composite stale resource； +- GPU resource 仍由 `prepareResources()` lazy 创建，稳定 viewport 复用。 + +主 buffer 按 Segment 顺序执行：Retained composite 或 Continuous direct render。相邻同策略不会合并。 + +## 6. Invalidation + +Layer immutable Impl identity 与全局 Style index 组成 retained Segment content fingerprint。Layer property/visibility 在某 retained Segment 内变化时，只推进该 Segment 的 content revision；其他 retained Segment 可继续 reuse。 + +以下仍保守 invalidate 全部 retained Segment：camera/viewport/pixel ratio、source/tile、image/sprite/glyph、placement/transition、context reset、debug/3D、style reload、resource/compositor failure。原因是当前 Core 没有足够稳定的通用 source-to-render-segment dependency graph；本 Step 不扩建该图。 + +## 7. Particle Fast Path + +恰好一个 Continuous Segment、其内容满足既有 Particle-only 支持条件、所有实际 Retained cache 有效时，沿用 V12 Fast Path。缺少某个不存在的 retained cache 不构成 miss。 + +多个 Continuous Segment 暂不做高级 Fast Path：gate 以 `unsupported-continuous-layer` fail closed，进入正常 full CPU frame；Segment topology、cache 与 Z-order 不变。 + +## 8. Android / iOS / RN API + +```text +RN RendererRuntime + setRenderSegmentPlan(reactTag, typedPlan) + getRenderSegmentDiagnostics(reactTag) + ↓ schemaVersion=1 JSON transport +WeatherRuntimeBridge（既有唯一 bridge） + ↓ +Android MapLibreMap / iOS MLNMapView + ↓ +mbgl::Map typed RenderSegmentPlan / RenderSegmentDiagnostics + ↓ +RetainedUnderlayRuntimeState + RenderOrchestrator + RendererImpl +``` + +Android platform 内部 API 为 `setRenderSegmentPlan(String)` / `getRenderSegmentDiagnostics()`；iOS 为 `setRenderSegmentPlanJSON:` / `renderSegmentDiagnosticsJSON`。Core API 保持 typed。JSON/schema/strategy 非法时返回 REJECTED，同时把 active topology 置 invalid，避免继续复用旧 cache。 + +## 9. Diagnostics Schema + +Snapshot 为 pull-based。顶层包含 enabled/configured/valid/configSource/configRevision/topologyRevision/counts/coverage/fallback/reason/Fast Path counters；`styleLayers[]` 始终按 Style 顺序；`segments[]` 包含 begin/end、实际 Layer 成员。Retained 的 `cache` 为 object；Continuous 的 `cache=null`，不会伪装为 disabled retained cache。 + +完整示例： + +```json +{ + "schemaVersion": 1, + "enabled": true, + "configured": true, + "valid": true, + "configSource": "explicit-render-segment-plan", + "configRevision": 7, + "topologyRevision": 4, + "styleLayerCount": 6, + "segmentCount": 4, + "retainedSegmentCount": 3, + "continuousSegmentCount": 1, + "coverageComplete": true, + "fallback": false, + "lastReason": "none", + "fastPathEligible": true, + "fastPathActive": true, + "fastPathFallbackReason": "none", + "fastPathHit": 120, + "fastPathMiss": 3, + "fullCpuFrame": 4, + "styleLayers": [ + {"layerIndex":0,"layerId":"background","layerType":"background","visible":true,"sourceId":null,"sourceLayer":null}, + {"layerIndex":1,"layerId":"water","layerType":"fill","visible":true,"sourceId":"chart","sourceLayer":"water"}, + {"layerIndex":2,"layerId":"rn-weather-color","layerType":"weather-color","visible":true,"sourceId":"rn-weather-fields","sourceLayer":null}, + {"layerIndex":3,"layerId":"rn-weather-particles","layerType":"raster-particle","visible":true,"sourceId":"rn-weather-fields","sourceLayer":null}, + {"layerIndex":4,"layerId":"land-area","layerType":"fill","visible":true,"sourceId":"chart","sourceLayer":"land"}, + {"layerIndex":5,"layerId":"ais-layer","layerType":"symbol","visible":true,"sourceId":"ais","sourceLayer":null} + ], + "segments": [ + {"segmentIndex":0,"strategy":"RETAINED","configuredStartLayerId":null,"beginIndex":0,"endExclusive":2,"resolvedStartLayerId":"background","resolvedEndLayerId":"water","layerCount":2,"layers":[{"layerIndex":0,"layerId":"background","layerType":"background","visible":true,"sourceId":null,"sourceLayer":null},{"layerIndex":1,"layerId":"water","layerType":"fill","visible":true,"sourceId":"chart","sourceLayer":"water"}],"cache":{"cacheState":"reuse","contentRevision":19,"build":1,"reuse":120,"invalidation":0,"lastInvalidationReason":"none","textureCreate":1,"compositeCreate":1,"resourceRelease":0}}, + {"segmentIndex":1,"strategy":"CONTINUOUS","configuredStartLayerId":"rn-weather-color","beginIndex":2,"endExclusive":4,"resolvedStartLayerId":"rn-weather-color","resolvedEndLayerId":"rn-weather-particles","layerCount":2,"layers":[{"layerIndex":2,"layerId":"rn-weather-color","layerType":"weather-color","visible":true,"sourceId":"rn-weather-fields","sourceLayer":null},{"layerIndex":3,"layerId":"rn-weather-particles","layerType":"raster-particle","visible":true,"sourceId":"rn-weather-fields","sourceLayer":null}],"cache":null}, + {"segmentIndex":2,"strategy":"RETAINED","configuredStartLayerId":"land-area","beginIndex":4,"endExclusive":5,"resolvedStartLayerId":"land-area","resolvedEndLayerId":"land-area","layerCount":1,"layers":[{"layerIndex":4,"layerId":"land-area","layerType":"fill","visible":true,"sourceId":"chart","sourceLayer":"land"}],"cache":{"cacheState":"ready","contentRevision":22,"build":2,"reuse":80,"invalidation":1,"lastInvalidationReason":"layer-mutation","textureCreate":2,"compositeCreate":2,"resourceRelease":1}}, + {"segmentIndex":3,"strategy":"RETAINED","configuredStartLayerId":"ais-layer","beginIndex":5,"endExclusive":6,"resolvedStartLayerId":"ais-layer","resolvedEndLayerId":"ais-layer","layerCount":1,"layers":[{"layerIndex":5,"layerId":"ais-layer","layerType":"symbol","visible":true,"sourceId":"ais","sourceLayer":null}],"cache":{"cacheState":"reuse","contentRevision":11,"build":1,"reuse":40,"invalidation":0,"lastInvalidationReason":"none","textureCreate":1,"compositeCreate":1,"resourceRelease":0}} + ] +} +``` + +有效 snapshot 保证 Segment layers 拼接等于 styleLayers，Layer 不重号、不遗漏、不重复。RN Test Host 的按钮只在用户操作时配置/拉取并显示一次完整 JSON，不轮询、不逐帧打印。 + +## 10. 当前限制 + +- 多 Continuous 只保证正确 full renderer，不提供高级 Particle Fast Path。 +- Source/Tile mutation 尚无通用 dependency graph，仍全 retained invalidation。 +- Legacy diagnostics 只是兼容摘要，不能表达任意 N Segment。 +- OpenGL/Metal 编译、Native tests、Android codegen/Gradle 与设备运行由 RDC 独立验证后才能形成 PASS 事实。 diff --git a/docs/50_Step记录/STEP-094_通用RenderSegment分段渲染与Style分类诊断_v1.md b/docs/50_Step记录/STEP-094_通用RenderSegment分段渲染与Style分类诊断_v1.md new file mode 100644 index 000000000..bf328a172 --- /dev/null +++ b/docs/50_Step记录/STEP-094_通用RenderSegment分段渲染与Style分类诊断_v1.md @@ -0,0 +1,66 @@ +# 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 验证重点 + +1. Core 编译：重点检查 rapidjson header、RenderLayer Impl metadata、JNI String ABI 与 ObjC++ selector。 +2. Tests：验证 resolver/diagnostics 新 suites 及 V12 原有 Continuous/Retained/Fast Path suites。 +3. OpenGL/Metal：确认 N retained resource、相邻 retained 不合并、稳定帧不重复创建。 +4. RN codegen：确认新增两个 primitive JSON methods 在 Android/iOS generated Spec 与实现 selector 对齐。 +5. 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 的代码验收结论。 diff --git a/docs/报告/STEP-094_通用RenderSegment分段渲染与Style分类诊断_Codex完成报告_v1.md b/docs/报告/STEP-094_通用RenderSegment分段渲染与Style分类诊断_Codex完成报告_v1.md new file mode 100644 index 000000000..2b4a12b1b --- /dev/null +++ b/docs/报告/STEP-094_通用RenderSegment分段渲染与Style分类诊断_Codex完成报告_v1.md @@ -0,0 +1,126 @@ +# STEP-094 通用 RenderSegment 分段渲染与 Style 分类诊断 Codex 完成报告 v1 + +## 1. 执行结论 + +**PASS / CLOSED（RDC 独立验证完成）** + +任务书范围的 Core、Renderer、Android/iOS/RN bridge、定向测试、diagnostics pull 入口和中文文档均已完成。Codex 负责实现，RDC 按 AGENTS.md 独立完成 OpenGL、Metal、RN codegen/typecheck 与 Android Validation APK 验证。规定的代码与构建 Gate 均通过；Android/iOS 实体机 runtime/视觉未执行，未将其虚报为 PASS。 + +## 2. Git 基线 + +- Branch：`particle/main` +- Starting HEAD：`8fbb892a1236a55329ed9ef5a612640c9363d3f1` +- Starting remote：`origin/particle/main` 同上 +- Implementation commit：`016fd1fff`（完整 SHA `016fd1fff6a33cf795c10d4f5c5413d308383677`，如最终 Git 回读一致则以 Git 为准） +- Commit message：`feat: add generic render segment model` +- Implementation push：PASS，已推送 `origin/particle/main` +- 文档收尾：本报告、Step 记录、设计文档与开发记录在实现 commit 后独立提交；包含本报告的 commit 无法在文件自身内自引用 SHA，最终远端 HEAD 由 RDC push 后回读确认。 + +## 3. 实际实现 + +- `RenderSegmentStrategy/Definition/Plan/Diagnostics` typed Core model。 +- schemaVersion=1 JSON parser/serializer，非法输入使 active plan invalid，不复用 stale topology。 +- boundary Layer ID → ordered Style layerIndex resolver，完整 coverage、严格递增、非空 Segment。 +- N Segment Renderer 遍历与 topology-sized retained cache ownership。 +- 每个 retained cache 独立 revision/build/reuse/invalidation/resource counters；Continuous 无 cache。 +- topology change 释放旧 cache；稳定 viewport lazy reuse。 +- LayerMutation 通过 immutable Impl fingerprint segment-local invalidation；无法可靠归属的 mutation 全 retained invalidation。 +- V12 `setContinuousLayerRange()` compatibility mapping 与旧 diagnostics API 保留。 +- 单 Continuous Particle Fast Path 保留；多 Continuous 明确 fallback。 +- diagnostics 返回 ordered styleLayers、ordered segments、每段 layers、sourceId/sourceLayer（可取得时）和 cache stats。 +- Android/iOS platform API、既有 RN TurboModule、typed TS API 和 RN Test Host pull 入口完成。 + +## 4. 修改文件类别 + +- Core public/private：Map API、RenderSegment model/resolver/JSON、runtime state、orchestrator、renderer、retained cache。 +- Build：CMake 与 Bazel core header/source lists。 +- Android：MapLibreMap/NativeMap/NativeMapView/JNI。 +- iOS：MLNMapView public API 与 ObjC++ bridge。 +- RN：types、Native Spec、RendererRuntime、Android/iOS bridge、Test Host。 +- Tests：`test/renderer/retained_underlay_cache.test.cpp`。 +- Docs：STEP-094 设计、Step 记录、本报告、开发记录。 + +准确逐文件列表以最终 `git status --short` 为准。 + +## 5. Diagnostics 与一致性 + +- valid 时 `segmentCount == segments.length`、`styleLayerCount == styleLayers.length`、Segment 连续覆盖 `[0,layerCount)`。 +- 每段 `layers` 从同一 ordered styleLayers slice 生成；flatten 后顺序与 styleLayers 完全一致。 +- 全局 layerIndex 不按 Segment 重编号。 +- Continuous `cache=null`；Retained cache object 包含 content revision 与生命周期 counters。 +- invalid plan 保留当前 ordered styleLayers，segments 为空且 `valid=false/fallback=true`。 +- snapshot 只在显式 pull 时 JSON stringify；Style 字符串 metadata 仅在 config/style layer metadata 变化时重建。 + +## 6. OpenGL / Metal / Tests + +- OpenGL build：PASS。命令 `cmake --build build-step088-opengl --target mbgl-test-runner -j3`，exit 0；仅既有 Boost/macOS deployment warnings。 +- Native directed tests：PASS。过滤集共 8 suites / 43 tests，43/43 PASS；其中 `RenderSegmentPlan` 9、`RenderSegmentDiagnostics` 4，并包含 V12 Continuous/Retained/Fast Path 回归。 +- Metal build：PASS。预先确认 `MLN_WITH_METAL=ON`、`MLN_WITH_OPENGL=OFF`；`cmake --build build-ios --target ios-sdk-static -- -quiet` exit 0。存在既有 EAGL/statusBar deprecation 与 bundle-id warning，无编译/链接错误。 +- RN package TypeScript：PASS。 +- RN Test Host TypeScript：PASS，验证时临时将 node_modules package 指向本工作树，结束后恢复旧依赖。 +- RN codegen：PASS。工程的 `npx react-native codegen` 因缺少 `@react-native-community/cli` 入口返回 1；未升级/修改依赖，改用同一已安装 RN 0.85 `@react-native/codegen` 的 combine-js-to-schema + generate-all，exit 0，并在 Android Java/JNI/C++ JSI 与 iOS ObjC++ generated Spec 中确认两个新方法。 +- Android Validation APK：PASS。标准脚本 `build_validation_apk.sh`，Gradle `BUILD SUCCESSFUL in 4m 45s`；x86_64-only、strip=true；APK 60,294,298 bytes，`libmaplibre.so` 39,421,736 bytes，SHA-256 `848c3196c64cee6dfb1e9627f4af32b6e235fdd82afd1cfb8474c7fc5d591c71`。 +- Android/iOS runtime/视觉：NOT RUN。 +- Jest：未加入、未执行。 + +## 7. RDC 精确验证命令 + +### OpenGL Native runner + +```bash +cd /Users/tei/dev/MapLibreParticleLab +cmake --build build-step088-opengl --target mbgl-test-runner -j3 +build-step088-opengl/mbgl-test-runner --gtest_filter='RenderSegmentPlan.*:RenderSegmentDiagnostics.*:ContinuousLayerRange.*:RetainedDynamicBoundary.*:RetainedLayerGroupRange.*:RetainedUnderlayCache.*:RetainedUnderlayRevision.*:ParticleFastPath.*' +``` + +### Metal / iPhoneOS arm64 compile + +```bash +cd /Users/tei/dev/MapLibreParticleLab +cmake --build build-ios --target ios-sdk-static -- -quiet +``` + +RDC 必须先确认 `build-ios/CMakeCache.txt` 的 `MLN_WITH_METAL=ON`、`MLN_WITH_OPENGL=OFF`，不能用 target 名称推断后端。 + +### RN TypeScript / Codegen + +在现有 RN Test Host 已安装依赖环境中执行： + +```bash +cd /Users/tei/dev/MapLibreParticleLab/integration/react-native/MapLibreParticleRNTestHost +npm run typecheck +npx react-native codegen +``` + +若当前工程的 RN 0.85 codegen 正式入口由 Expo prebuild/Pods 驱动，RDC 应使用现行 STEP-083 流程，并核对 generated Android/iOS Spec 确实含 `setRenderSegmentPlanJson`、`getRenderSegmentDiagnosticsJson`，不要只看 TS。 + +### Android compile / Validation APK + +```bash +cd /Users/tei/dev/MapLibreParticleLab +./tools/particle_android_validation/build_validation_apk.sh +``` + +若还需 RN Test Host Android compile，使用当前 STEP-080 v2 公网/本地 package handoff 流程生成包含本工作树 package 的测试依赖后再编译；不得误用远端 `.10` tgz 代替本轮源码。 + +## 8. 需要验证的 targets / tests + +- `mbgl-test-runner` +- `ios-sdk-static`（Metal-only iPhoneOS arm64） +- Android `MapLibreAndroid` JNI/Java 与 `MapLibreAndroidTestApp` OpenGL Debug x86_64 +- RN `WeatherRuntimeBridgeSpec` Android/iOS codegen +- RN Test Host TypeScript +- Native suites：`RenderSegmentPlan`、`RenderSegmentDiagnostics` 及全部 V12 Continuous/Retained/Fast Path 回归 +- 运行态重点：R-C-R、C-R-R、R-R-C、R-C-R-C-R、相邻 R-R 独立 counters、invalid/recovery、hidden boundary、Cache OFF、单 Continuous Fast Path、多 Continuous fallback、Style/segment layer flatten 一致性 + +## 9. Known limitations / 未完成 + +- 多 Continuous Fast Path 未优化，按任务边界明确 fail closed。 +- Source/Tile mutation 仍为保守全 retained invalidation。 +- RN Test Host package.json 仍指向历史远端 `.10` tgz；本次通过临时工作树 package + 直接 RN 0.85 codegen 验证新接口，没有把旧包结果冒充新实现。 +- Android/iOS 实体机 runtime、视觉与性能观察 NOT RUN；本报告的 PASS 仅表示 STEP-094 规定的代码、编译、测试、ABI/codegen Gate 已通过。 +- Android Validation build-info 中 commit 字段为构建时尚未提交的起始 HEAD，且 `git_dirty=true`；这是预提交验证事实，产物 SHA 与验证结果有效，但不是发布 artifact。 + +## 10. 最终状态 + +代码/构建验收：`PASS / CLOSED`。实现 commit `016fd1fff` 已 push；文档收尾 commit 完成后由 RDC 再次确认 `HEAD == origin/particle/main` 与工作树 clean。 diff --git a/粒子开发记录.md b/粒子开发记录.md index 0f70dd1ba..dfb70eb1b 100644 --- a/粒子开发记录.md +++ b/粒子开发记录.md @@ -916,3 +916,11 @@ Android V3-08 单次综合验收已完成并关闭。Native `13.4.1-particle.2` - 测试 Style 用普通 background/fill/line 构造清晰的 Bottom、Particle Continuous、Top opaque/semi-transparent/line 覆盖关系；资源与 Fast Path counter 通过屏幕低频 pull 展示，不产生逐帧日志风暴。 - 静态字段/场景接线审查、Android Manifest/layout `xmllint` 与 `git diff --check` PASS。依照职责分工，本轮未执行 Native/Gradle/Xcode 编译、tests、APK、ADB、安装或 Android/iOS runtime；两平台均为 `WAITING_RUNTIME_VALIDATION`，不得写 PASS。 - implementation commit：`b3ec8edc87ece404b5f7b3706f5acf2a70de6862`（`feat: add STEP-093 runtime validation tooling`）。完整 RDC 命令、操作步骤、证据要求与 18 项矩阵见 STEP-093 v1 记录。 + +### 2026-09-25 STEP-094 通用 RenderSegment 分段渲染与 Style 分类诊断 + +- 将 V12 固定 Bottom/Continuous/Top 收敛为 `RenderSegmentPlan`：Style 顺序仍是唯一 Z-order，1..N 个连续 Segment 只声明 RETAINED/CONTINUOUS，相邻同策略不合并。 +- Renderer 按 resolved topology 动态持有独立 retained cache；Continuous 不分配 retained target。Layer Impl fingerprint 支持明确 LayerMutation 的 segment-local invalidation，其余不安全依赖继续全 retained invalidation。 +- 旧 `setContinuousLayerRange` 转换为同一 topology；恰好一个 Continuous 时保留 Fast Path，多 Continuous fail closed 到 full CPU frame。 +- 新 pull diagnostics 端到端返回 ordered Style→Segment→Layer、config/topology revision、coverage、visibility/source metadata 与每个 retained cache counters；RN public API 为 typed object，TurboModule 内部用 schemaVersion=1 JSON。 +- 新增 Native directed tests 与 RN Test Host 一次性 Apply/Fetch 入口。RDC 独立验收：OpenGL runner 编译 PASS；8 suites / 43 tests 全 PASS；Metal-only iPhoneOS `ios-sdk-static` PASS；RN package/Test Host typecheck PASS；RN 0.85 codegen 直接入口生成 Android/iOS Spec PASS；Android Validation APK BUILD SUCCESS（60,294,298 bytes，x86_64，SHA-256 `848c3196c64cee6dfb1e9627f4af32b6e235fdd82afd1cfb8474c7fc5d591c71`）。实现 commit `016fd1fff` 已 push；Android/iOS 实体机 runtime/视觉 NOT RUN。STEP-094 代码/构建验收 `PASS / CLOSED`。