STEP-085 V4 Renderer 性能修复 Codex 完成报告 v1

1. 执行结论

IMPLEMENTED / STATIC_CHECKS_PASS / BUILD_NOT_RUN_BY_CODEX — WAITING_FOR_RDC

Codex model：gpt-5.6-terra。推理强度：high。机器：Mac-mini-tei.lan。仓库：/Users/tei/dev/MapLibreParticleLab-step085。

2. Git 基线

branch：step/085-v4-render-efficiency
STEP-084 Final / STEP-085 Start HEAD：bc6b8dd84b4c10e5263d61832661508c02d84d88
End HEAD、commit、push 与 remote HEAD：本报告随最终 scoped commit 回填，以最终 Git 事实为准。
STEP-084 已由 fix: disable particle speed color by default 推入 origin/particle/main，本 Step 从该更新后的 remote HEAD 创建独立 worktree。

3. 实际实现

RasterArrayRendererCadence 是 Source-owned shared internal state。它以 monotonic deadline gate V4 Particle simulation，不推进 forecast。Particle active/visible/field-ready 时才请求 repaint；未到 deadline 的 camera frame 只重合成已有 trail。
WeatherColor 不再把 sourceTimeline == nullptr 解释为动画。V4 静态 PAUSE 返回 false；legacy playback 仍沿用 timeline cadence。
V4 materialized projection 与 RenderLayer source endpoint 改为 immutable shared pointer。materialization 只在 binding/window refresh 时产生，prepare 不复制完整 scalar、vector、valid。
WeatherColor 只在 wrap 集合变化时重建 drawable；texture/UBO 参数由 persistent Resource/Tweaker 读取，正常 MIX、opacity、stops 和 field endpoint 更新不重建 LayerGroup drawable。
Android WeatherRuntime 和 iOS MLNParticleFieldRuntime 仅补下一帧 wake：已绑定 particle fieldKey 且该 key 已收到 accepted V4 submit、可见且 target 为 30/60 时才请求 repaint；hidden/clear/disable/dispose 停止，disable 后 re-enable 可恢复既有 V4 field 的 wake。公共 RN/ObjC/Java API 未新增。
新 debug counters 为 non-spam atomic 累计值；release no-op。覆盖 repaint/update/simulation/drawable/texture/GPU/trail/materialize/window revision。

4. 根因与语义

根因是 V4 具有独立 projection，却被 renderer 的 sourceTimeline sentinel 当作“持续动画”；同时 prepare 直接给 value snapshot 赋值。修复后 Forecast PAUSE 只暂停自动 forecast time，Particle visual simulation 仍在 active cadence 下运行。V4 PLAY 自动推进没有 production owner：advanceForecastClock 只定义未被生产 Runtime/bridge 调用，本 Step 明确保留为后续设计项。

5. 静态检查与测试

已执行：git diff --check，通过。
已执行：对 V4 projection/cadence/repaint/materialization/drawable code path 的 rg 定向静态审计，确认 no-timeline WeatherColor 不再 permanent repaint，V4 Particle 调用 consumeIfDue()。
已执行：平台 wake 静态审计；wake 只使用 Host command bookkeeping，Core RasterArrayRendererCadence 仍是 deadline 和 simulation advance 的唯一裁决者。
新增：RasterArrayV4RendererCadenceGatesVisualSimulationWithoutForecastPlayback C++ test；V4 materializer tests 调整为 shared snapshot lifetime 断言。
未运行测试二进制：任务书不允许以未编译的 native test 冒充验证，且 Native 编译/链接由 RDC 负责。

6. 未执行的编译与运行

未执行 Bazel、CMake/Ninja/Make、clang/clang++ Native compile、Xcode、Metal/iOS build、Gradle、AAR/APK、artifact、ADB、设备安装、真机或 CPU/GPU/heap 采样。状态为 BUILD_NOT_RUN_BY_CODEX — WAITING_FOR_RDC，不代表 Android/iOS/Metal/AAR/性能 PASS。

7. RDC 后续入口

在本 Final HEAD 上执行受影响 C++ renderer/source/test 精确编译和相关 test filter；确认 shader/codegen/build graph。
执行 bazel build --//:renderer=metal //platform/ios:MapLibre.dynamic，并使用当前 iOS Test Host 的 Metal XCFramework 消费链完成 device build。
按 docs/50_Step记录/STEP-080_Android_AAR与RNTestHost标准构建流水线_v2.md 构建新的 Android OpenGL AAR、发布新版本坐标、从公网 Maven/npm 消费并构建 Test Host；不得覆盖现有版本。
统一执行任务书 22/23：A/B/C/D、30/60/AUTO、PAUSE、speed-color OFF/ON/OFF，以及 pan/zoom/bearing/pitch/resize；采集 RenderThread/GPU/jank 与 debug counters。确认静态 WeatherColor idle、camera frame 不误推进、field upload/GPU/trail/drawable 不异常增长。

8. 已知问题、未完成项

V4 ForecastClock PLAY 自动推进的 production owner 缺失，未在本 Step 引入第二时钟。
Native Heap/detach/destroy 未归因或修改。
所有 Native 编译、artifact 和设备验收待 RDC；本次 Android Java / iOS Objective-C++ wake 收紧也待目标平台编译。如发现跨 backend 架构问题，应停止 RDC 扩改并重新进入 Codex 任务。

4.8 KiB Raw Permalink Blame History Unescape Escape