52 lines
5.8 KiB
Markdown
52 lines
5.8 KiB
Markdown
# STEP-119 粒子独占 C 与 CPU 效率阶段验收报告 v1
|
||
|
||
日期：2026-10-11（JST）。阶段结果：**SOURCE_READY / CPU_BENCH_READY / ANDROID_NEW_APK_NOT_RUN / STEP119_PARTIAL**。
|
||
|
||
## 一、可行性结论
|
||
|
||
用户确认 RCRR 的正常使用原则是 C 只放粒子，后续必须以实际 CPU 效率衡量 FastPath 而非单看 Fast 计数。源码检查确认：Native `tryRenderParticleFastFrame()` 使用 `singleContinuousSegment(plan)`；Fast 执行仅访问当前唯一 C 段的 LayerGroup，R 需全部缓存有效、无版本/内容/Placement/Annotation 等 24 Gate 安全问题。原则**有条件可行**，不等于 WeatherColor 放入 R 后已经获得 Fast 资格。
|
||
|
||
**没有取得新 APK 的 Full/Fast CPU 性能对比数值**；本报告仅完成测试场景、测量器与验收准备。不能宣称 CPU 性能提升、GTest 或 iOS 完成。
|
||
|
||
## 二、实际基线和执行状态
|
||
|
||
- 设备 Mac.lan，通过 RDC 操作 `/Users/tei/dev/MapLibreParticleLab`；原有 `particle/main` 分支，起点 `1072816740fa69b7b23cd70602a402be19e5be2a`。
|
||
- Integration `/Users/tei/dev/navsea-particle-integration` 已 `fetch main`、`merge --ff-only origin/main`，本地/远端一致 `80667d6c343411d03a760425438e3d292f452118`。已依据当前规则确认 Android/iOS/Shared Core 边界及项目 AGENTS。
|
||
- 既有设备 APK 源 commit `3d989a00a822989339a6d7cb4d23acc04396670e`、SHA-256 `57d68800770d431a2ce9247406f636e7a01cc19fccaf4c59f5eb3a7c99128135`；**未重新编译或安装，不得对新场景使用旧 APK 验收**。
|
||
- 之前的原 `PARTIAL_RCRR` 80秒真机负例保留：R0 因缺 tide Build=0/Reuse=0、R2/R3 各 Build=1/Reuse=536、FastDelta=0/FullDelta=596、decisionMismatch=0。旧 `STATIC_RC_NO_TIDE` 正向 Fast=1819，数据/图层顺序不同，不当作新 CPU 对照数据。
|
||
|
||
## 三、新 Test App 结构
|
||
|
||
不改生产 PBF、原 63 层场景或 Shared Core 的 24 Gate。Test App 在唯一无 tide 测试副本中得到 62 个基础层，插入的 WeatherColor 索引31、Particle 索引32。正常性能候选只允许 Particle C[32,33)：
|
||
|
||
- `RCRR_C_NARROW_NO_TIDE`：R[0,32)、C[32,33)、R[33,63)、R[63,64)。
|
||
- `RCR_PARTICLE_ONLY_NO_TIDE`：R[0,32)、C[32,33)、R[33,64)。
|
||
- `RCRRR_PARTICLE_ONLY_NO_TIDE`：R[0,32)、C[32,33)、R[33,38)、R[38,63)、R[63,64)。
|
||
- `RCRR_FULL_CONTROL_NO_TIDE`：与第一组同源、同图层、同 RCRR Plan，但调用 `setRetainedUnderlayEnabled(false)`，目的是同屏 Full CPU 基线；预期原生 Fast=0，实际须设备证明。
|
||
|
||
老 `RCRR_C_WIDE_NO_TIDE`、`RCRR_R_DYNAMIC_NO_TIDE` 仍保留为错误划分安全负对照，不列为正常性能候选。原 `PARTIAL_RCRR` 和 `STATIC_RC` 及 v1 报告均保留历史事实。
|
||
|
||
Test App 菜单的操作 ID 从10/11/12迁移到100/101/102，避免新增 enum 场景 10/11 与 Snapshot、Mutate 冲突；Full 对照按钮显示 CACHE OFF。Native 摘要新增 `sampleElapsedMs` 与 benchmark 档 6 秒报告周期，仅用于关联 CPU 采样，不修改 Gate 或 Render 路径。
|
||
|
||
## 四、CPU 真实测量方案
|
||
|
||
新增 `tools/particle_android_validation/benchmark_step119_cpu.py`：在用户提供相同源码构建并正确安装的 APK 上，调用既有严格 `inspect()` 锁 commit、SHA、ABI/安装设备；启动目标 Activity，Warmup35秒，稳定观察90秒，按6秒读取 Android `/proc/PID/stat` 的 utime+stime 和 `/proc/uptime`。设备访问能力已只读检查：真实 `CLK_TCK=100`，`/proc/<PID>/stat` 可读取，但**CPU Benchmark 本身尚未对新 APK 运行**。
|
||
|
||
输出 `CPU Core Seconds`、`CPU Core Equivalent`（CPU%相对单核）、`Native FPS`、Fast/Full增量、FastFraction、估算 `CPU ms/完成帧` 和分段 Build/Reuse/Invalidation。CPU 为**整个 App 进程**的时间，并非 C++ renderer 独占的精准逐帧计时。Fast 稳定区间要求 FastFraction≥95%，Full 对照要求 Full>0、Fast=0，且 24 Gate mismatch=0；失败按原始事实保存 JSON 并返回非零。
|
||
|
||
新增 `tools/particle_android_validation/compare_step119_cpu.py`：读取 Full→Fast→Full A-B-A 实际结果与 RCR/RCRRR 结果，校验同设备/APK SHA/Style 指纹、场景生命周期和 CPU/Native 边界，将 Full 两轮作为 CPU/帧基线，计算各 Fast 组 CPU/帧变化比例及 CPU/秒和 FPS。若 Full 两端 CPU/秒漂移大于15%，结果标记需复测。此比较用于检验 CPU FastPath 收益，**不代表 GPU 时间、能耗或省电已经证明**；FPS 不同时必须同时呈报 CPU每秒与CPU每帧。
|
||
|
||
## 五、当前已执行验证与未执行项
|
||
|
||
- Python 非 Jest 结构/CPU 算法测试：12 项 PASS，运行退出码 0；涵盖4类有效性能结构与2类保守负例、错误分段/缺源/Annotation失败、原 STATIC_RC / 原 PBF63 边界、proc/stat解析与 CPU/fps 归一计算。
|
||
- CPU 工具 CLI 参数校验/AST：PASS；Android ADB 读设备时钟率：`100`（只读）。
|
||
- `git diff --check`：本阶段代码检查通过，最终 commit/push 信息以后续 RDC 实际状态补充。
|
||
- 新 Kotlin Test App 尚未经用户手工 Gradle 编译/打包；四种 CPU 场景 Native 真实 Full/Fast、CPU时间、帧率与图像仍为 **NOT VERIFIED**。
|
||
- Source/Style/Tile/Camera/Annotation 等失效及恢复、13项 STEP119 Native GTest、Metal/iOS 独立验证均未完成。Mac libuv 既有缺失不擅自装依赖/升级系统工具。
|
||
|
||
## 六、工程风险与下一步
|
||
|
||
只有在 C[32,33) 实际得到 Fast、视觉匹配及 CPU/帧或 CPU/秒的受控改善后，才考虑产品采用。多 R 可能提高 FBO/Composite 成本；WeatherColor 放 R 可能因当前 Core 类型/动态数据结果证书被保守拒绝；如果 Main CPU 指标改善但持续功耗/热度上升，也不等于总体有益。
|
||
|
||
详见 `docs/60_测试/STEP-119_RCRR多配置验收矩阵_v2.md`。本报告是阶段验收，不进入发行、不创建 Tag/SOURCE_LOCK，也不覆盖上轮或未跟踪的 STEP110/111。Git 以 RDC 实际新 commit/push/远端 SHA 返回为准。
|