docs: record STEP-091 zoom out reseed

2026-09-23 10:08:47 +09:00
parent 4286c16a53
commit a2642bbedf
4 changed files with 381 additions and 0 deletions
--- a/docs/40_任务/STEP-091_ZoomOut_Viewport_Particle_Reseed_Codex任务_v1.md
+++ b/docs/40_任务/STEP-091_ZoomOut_Viewport_Particle_Reseed_Codex任务_v1.md
@@ -0,0 +1,225 @@
+# STEP-091 Zoom Out 后粒子 Viewport 一次性重播种 Codex 任务 v1
+
+## 目标
+
+修复正式 RasterParticleLayer 在“大 Zoom → 小 Zoom（Zoom Out）”后，旧粒子短时间聚集在原视野小区域，必须等待粒子生命周期/运动逐渐扩散后才恢复正常密度的问题。
+
+用户实机现象：
+- Zoom Out 完成后，粒子集中成一小团/小矩形；
+- 风场和粒子仍继续运动；
+- 等旧粒子跑远或寿命到期后，整个新视野才逐渐恢复正常铺开；
+- Zoom In 暂未观察到同类问题。
+
+本任务必须以当前实际源码为准修复，不改 Field/T0/T1/Timeline 数据契约，不引入第二套粒子系统。
+
+## 基线
+
+- repo: MapLibreParticleLab
+- branch baseline: `origin/particle/main`
+- baseline HEAD: `297b9126200cea3da3bdef2faacedcd9845f6d08`
+- 实施工作树: `/Users/tei/dev/MapLibreParticleLab-step091`
+- 实施分支: `step091-zoom-out-reseed`
+- STEP-090 已 CLOSED / PASS，retained underlay + Particle-only CPU fast path 必须保持。
+## 已确认根因
+
+重点读取：
+- `src/mbgl/renderer/layers/render_particle_validation_layer.cpp`
+- OpenGL / Metal particle shader
+- 当前 camera invalidation、respawnBounds、State/Trail seed 逻辑。
+
+当前正式路径已经存在：
+- `TrailCameraStableDelay = 150ms`
+- camera 变化时 `trailCameraInvalidated=true`
+- camera stable 后重新启用 viewport density
+- `viewportRespawnDomain(...)`
+- `respawnBounds`
+- shader 的 `outsideRespawnBounds(position)`
+- `stateSeeded / trailSeeded`
+- initial seed 时由 shader 使用 `respawnSeed(...)` 在 `respawnBounds` 内播种。
+
+问题是 Zoom Out 后新的 respawnBounds 变大，旧粒子仍位于扩大后的 bounds 内，因此不会命中 outsideRespawnBounds，只能等待 age/invalid/运动触发 respawn。
+
+## 修复原则
+
+Camera 稳定后，如果本次手势/连续 camera 变化的最终结果是明确 Zoom Out，则执行一次 viewport density reseed：
+- 下一次 State pass 把全部粒子重新播种到“新的、已经计算完成的 respawnBounds”；
+- 同时清理/重新 seed Trail，避免旧小视野 trail 与新粒子叠加；
+- 之后立即恢复正常连续 simulation。
+这不是完整 Simulation reset。禁止为了 Zoom Out：
+- 调用 `resetSequence("ZOOM_OUT")`；
+- 重建 State/Trail GPU resource；
+- 重新上传 Field texture；
+- reset Timeline / T0 / T1 / MIX；
+- style reload；
+- source reload；
+- Host/RN 手工 reset API。
+
+优先复用现有 `stateSeeded=false` / `trailSeeded=false` 和 shader initial-seed 机制；若实际代码证明还需一个极小内部状态，可最小新增。
+
+## Camera 手势状态
+
+需要记录“一次 camera invalidation 开始前”的稳定 Zoom，不能每帧覆盖。
+
+建议最小状态语义：
+- camera gesture / invalidation 开始时保存 `startZoom`；
+- camera 变化期间仍沿用现有 invalidated 行为；
+- 150ms stable 时比较最终 `endZoom`；
+- 仅当 `endZoom < startZoom - epsilon` 才请求 viewport reseed；
+- epsilon 仅防浮点/微小抖动，建议约 0.05，实际值可按现有 double/zoom 语义选择并写明理由；
+- Zoom In、纯 Pan、Rotate、Pitch 不触发 full reseed；
+- 新一轮 camera invalidation 必须重新建立 startZoom，不得复用上一轮。
+## 执行顺序要求
+
+必须保证 reseed 使用新的 viewport domain：
+
+1. camera 变化 → invalidated；
+2. camera 连续变化期间不触发 reseed；
+3. stable debounce 到期；
+4. 计算当前 `viewportRespawnDomain(transformState, viewport, field)`；
+5. 得到当前 `viewportDensityActive` 和新的 `respawnBounds`；
+6. 仅在本轮最终为 Zoom Out 且 viewport respawn domain 有效时执行一次：
+   - `stateSeeded = false`
+   - `trailSeeded = false`
+   - 清除 pending 标记；
+7. 下一次 State/Trail pass 使用现有 initial seed 流程；
+8. 后续帧继续正常 simulation。
+
+若 stable 时 respawn domain fallback/无效：
+- 不允许留下会在未来无关 Pan 时突然触发的 pending reseed；
+- 必须安全消费/取消本轮请求并记录原因；
+- 不得伪造 viewport domain。
+
+## Trail
+
+Zoom Out viewport reseed 必须同时让 Trail 重新 seed/清理。
+不得保留旧小视野 trail 作为新 viewport 的历史。
+不得改变正常连续播放时的 trail fade、T0/T1 overlap、simulationRebuild=false 语义。
+## Shader / UBO 边界
+
+当前 GL/Metal shader 已有：
+- initial seed；
+- respawnSeed；
+- respawnBounds；
+- alpha/validity 防止 respawn jump 连线。
+
+本任务默认不修改 shader、UBO layout 或公共 Layer API。
+只有实际源码证明现有 initial-seed 无法正确完成 viewport reseed 时，才允许最小修改，并在完成报告说明原因。
+
+绝对禁止：
+- partial reseed ratio 新协议；
+- per-particle CPU readback；
+- JS/RN 粒子重播种；
+- 新增 Host camera callback 驱动粒子；
+- 将 provider/network/vendor 逻辑放入 Renderer。
+
+## STEP-089 / STEP-090 保护
+
+Camera 变化期间原本就应使 fast path miss/full；稳定后应恢复 fast hit。
+本次修复不得破坏：
+- retained underlay cache；
+- Particle-only static CPU fast path；
+- staticRevision/buildRevision 语义；
+- camera/style/tile mutation fail-closed；
+- normal continuous particle cadence；
+- WeatherColor 与 RasterParticle 分层；
+- Runtime Field Window/T0/T1/MIX。
+## 诊断日志
+
+新增或扩展最小 Debug 日志，至少能确认一次 Zoom Out reseed：
+
+建议稳定前缀：
+`ParticleDensity: event=VIEWPORT_RESEED reason=ZOOM_OUT ...`
+
+字段至少包含：
+- startZoom
+- endZoom
+- respawnBounds
+- stateReseed=true
+- trailReseed=true
+- fieldResubmit=false
+- timelineReset=false
+- gpuResourceRebuild=false
+
+fallback/无效 domain 时输出一次 skip/cancel 原因即可。
+禁止 per-frame spam。
+
+## 定向测试
+
+不得加入 Jest。
+
+至少验证：
+1. Zoom Out 超过 epsilon → stable 后请求一次 reseed；
+2. Zoom In → 不请求；
+3. 纯 Pan → 不请求；
+4. Rotate/Pitch 且 Zoom 未下降 → 不请求；
+5. Zoom Out 后 fallback domain → 不留下延迟 pending；
+6. 一次 gesture 只 reseed 一次；
+7. 下一轮 gesture startZoom 正确刷新；
+8. 现有 respawn/State/Trail 生命周期测试继续通过（如已有可复用测试）。
+测试实现优先使用小型 C++ helper / directed native test；不要为了测试扩大公共 API。
+若当前测试结构无法直接覆盖 private renderer 状态，允许测试提取出的纯判定 helper，但不得引入复杂新模块。
+
+## Mac 验证
+
+Codex 需要：
+- 读取根目录 `AGENTS.md` 与相关 STEP-055、STEP-089、STEP-090 记录/报告；
+- 执行与修改直接相关的 Mac 原生精确编译/定向 C++ 测试；
+- noisy build 遵循全局 `$build-output-throttle`；
+- `git diff --check` PASS；
+- 不运行 Android Gradle/APK/ADB；
+- 不运行 Jest。
+
+## Android Test App
+
+本任务默认不新增 UI 控件。
+现有 Particle Core Layer Validation / 正式 RasterParticleLayer 场景应足以通过 ADB 手势验证。
+如果现有 Test App 无法可靠触发正式 viewport respawn path，才允许最小增加 debug-only validation 入口，禁止改产品 Host API。
+
+## 实机验收预期（由 RDC 在 Codex 完成后执行）
+
+- 编译 OpenGL Debug Test APK；
+- 安装到当前可用 Android 测试设备；
+- 启动 `ParticleCoreLayerValidationActivity`；
+- 使用正式 RasterParticleLayer 场景与较高粒子数；
+- 做明显 Zoom In 后再快速 Zoom Out；
+- 日志出现一次 VIEWPORT_RESEED；
+- Zoom Out 后不再等待 10 秒级生命周期才铺满新视野；
+- 无 crash / ANR / GL/EGL error；
+- camera stable 后 ParticleFastPath fast hit 恢复增长。
+## 文档与 Git
+
+Codex 完成后必须：
+- 更新 `粒子开发记录.md`；
+- 生成 `docs/50_Step记录/STEP-091_ZoomOut_Viewport_Particle_Reseed_v1.md`；
+- 生成 `docs/报告/STEP-091_ZoomOut_Viewport_Particle_Reseed_Codex完成报告_v1.md`；
+- 完成报告逐项写“已完成 / 未完成 / 无法验证”，不要写实施计划；
+- 记录实际修改文件、实际测试命令与结果；
+- 记录是否改 shader/UBO/API；
+- 记录 STEP-090 fast path 是否保持。
+
+提交本任务相关变更到当前工作分支，并 push：
+`git push origin HEAD:particle/main`
+
+不得提交任何与本任务无关的改动。
+push 失败不得声称任务完成。
+
+完成报告必须记录：
+- implementation commit hash
+- commit message
+- push result
+- remote branch
+- Final HEAD / origin/particle/main
+
+## 完成标准
+
+只有同时满足以下条件才可判定 Codex 阶段 PASS：
+- 根因按当前代码被修复；
+- Zoom Out stable 后只做一次 viewport State/Trail reseed；
+- 不做 full simulation reset / field resubmit / timeline reset / GPU resource rebuild；
+- Zoom In/Pan/Rotate/Pitch 不误触发；
+- 定向 C++ 测试与 Mac 精确编译通过；
+- git diff --check 通过；
+- 文档完成；
+- commit + push 到 `origin/particle/main` 成功。
+
+Android APK 构建、安装与设备手势验收由后续 RDC 串行执行，不属于 Codex 自己的完成条件。
--- a/docs/50_Step记录/STEP-091_ZoomOut_Viewport_Particle_Reseed_v1.md
+++ b/docs/50_Step记录/STEP-091_ZoomOut_Viewport_Particle_Reseed_v1.md
@@ -0,0 +1,53 @@
+# STEP-091 Zoom Out Viewport Particle Reseed v1
+
+## 状态
+
+**完成（Codex）/ 等待 RDC Android 实机验收**
+
+## 基线
+
+- 分支：`step091-zoom-out-reseed`
+- Starting HEAD：`297b9126200cea3da3bdef2faacedcd9845f6d08`
+- Implementation commit：`4286c16a53d4f49001f3b41ed4638d3c6edc95b3`
+- STEP-090：`CLOSED / PASS`，retained underlay 与 Particle-only CPU fast path 未修改。
+
+## 实现结果
+
+- camera invalidation 首帧保存一次稳定 `startZoom`，连续 camera 变化不覆盖。
+- 延用 150 ms camera stable debounce；稳定后先计算当前 `viewportRespawnDomain`、`viewportDensityActive` 与新 `respawnBounds`。
+- 当且仅当 `endZoom < startZoom - 0.05` 且 viewport domain 有效时，一次性设置 `stateSeeded=false`、`trailSeeded=false`。下一次既有 State/Trail pass 使用新的 `respawnBounds` 完成全体 State initial seed 与 Trail 清理。
+- `0.05` 仅过滤 sub-step 浮点/相机抖动，明显小于一次有意 pinch 或 zoom level 变化。
+- Zoom In、Pan、Rotate、Pitch 以及 epsilon 内抖动不触发 State reseed。
+- Zoom Out 后 domain fallback 时，本轮请求立即消费并记录 `INVALID_RESPAWN_DOMAIN`，不会留到后续 Pan。
+- `resetSequence()` 会取消尚未稳定消费的 gesture 状态，避免真实 simulation reset 后残留请求。
+
+## 边界保持
+
+- 未调用 Zoom Out `resetSequence()`。
+- 未重建 State/Trail GPU resource，未重新上传 Field，未 reset Timeline/T0/T1/MIX。
+- 未修改 shader、UBO layout、公共 Layer/Host/RN API。
+- 未修改 WeatherColor/RasterParticle 分层、Runtime Field Window 或 continuous cadence。
+- 未修改 STEP-089 revision/invalidation 与 STEP-090 fast-path gate；camera 变化期间既有 full-path、稳定后 fast-hit 恢复语义保持。
+
+## 诊断
+
+成功时单次输出：
+
+`ParticleDensity: event=VIEWPORT_RESEED reason=ZOOM_OUT ... stateReseed=true trailReseed=true fieldResubmit=false timelineReset=false gpuResourceRebuild=false`
+
+fallback 时单次输出 `action=SKIP skipReason=INVALID_RESPAWN_DOMAIN`，并明确 State/Trail 未 reseed。
+
+## 测试与构建
+
+- Mac mini / Darwin x86_64，OpenGL Debug CMake/Ninja 配置：PASS。
+- 精确编译 `render_particle_validation_layer.cpp.o`：PASS。
+- 精确编译 `particle_viewport_reseed.test.cpp.o`：PASS。
+- 独立原生 C++ directed executable：8/8 PASS，覆盖 Zoom Out、Zoom In、Pan、Rotate/Pitch、epsilon、fallback 消费、一次 gesture 一次触发、下一 gesture 刷新 startZoom。
+- `git diff --check`：PASS。
+- 全量 `mbgl-test-runner` 冷链接不是本 Step 必需验证；首次新 build tree 在受影响 objects 已通过后停止于 182/659，未据此声称全量 runner PASS。
+- Android Gradle/APK/ADB/设备：未执行，交由 RDC 串行验收。
+- Jest：未运行、未新增。
+
+## 当前结果与下一步
+
+Codex 阶段满足一次性 viewport State/Trail reseed 的实现与 Mac 定向验证要求。下一步由 RDC 构建 OpenGL Debug Test APK，在正式 RasterParticleLayer 场景验证 Zoom Out 立即铺开、单次日志、无 GL/EGL/crash，以及 camera stable 后 ParticleFastPath fast hit 恢复。
--- a/docs/报告/STEP-091_ZoomOut_Viewport_Particle_Reseed_Codex完成报告_v1.md
+++ b/docs/报告/STEP-091_ZoomOut_Viewport_Particle_Reseed_Codex完成报告_v1.md
@@ -0,0 +1,96 @@
+# STEP-091 Zoom Out Viewport Particle Reseed Codex 完成报告 v1
+
+## 1. 执行结论
+
+**PASS（Codex 阶段）/ Android 实机验收待 RDC 执行**
+
+根因已按当前正式 Renderer 修复：Zoom Out 的 camera gesture 稳定后，在新的有效 viewport respawn domain 已计算完成的同一帧，一次性把 State/Trail seed 状态置为未播种；下一次既有 State/Trail pass 完成全粒子新 viewport 播种与旧 Trail 清理。没有执行完整 simulation reset。
+
+## 2. Git 基线
+
+- 已完成：branch `step091-zoom-out-reseed`。
+- 已完成：Starting HEAD `297b9126200cea3da3bdef2faacedcd9845f6d08`，对应任务指定 `origin/particle/main` 基线。
+- 已完成：implementation commit `4286c16a53d4f49001f3b41ed4638d3c6edc95b3`。
+- 已完成：implementation commit message `fix: reseed particles after zoom out`。
+- 已完成：implementation push 至 `origin/particle/main` 成功，远端由 `297b9126200cea3da3bdef2faacedcd9845f6d08` 前进到 `4286c16a53d4f49001f3b41ed4638d3c6edc95b3`。
+- final documentation closeout push / Final HEAD / `origin/particle/main`：见 Git 收尾章节与最终交付回读。
+
+## 3. 实际修改文件
+
+- 已完成：`src/mbgl/renderer/layers/render_particle_validation_layer.cpp`。
+- 已完成：`test/CMakeLists.txt`。
+- 已完成：`粒子开发记录.md`。
+- 已完成：用户提供的 `docs/40_任务/STEP-091_ZoomOut_Viewport_Particle_Reseed_Codex任务_v1.md` 保留并纳入本 Step 文档提交。
+
+## 4. 新增文件
+
+- 已完成：`src/mbgl/renderer/particle_viewport_reseed.hpp`。
+- 已完成：`test/renderer/particle_viewport_reseed.test.cpp`。
+- 已完成：`docs/50_Step记录/STEP-091_ZoomOut_Viewport_Particle_Reseed_v1.md`。
+- 已完成：本报告。
+
+## 5. 实际实现
+
+- 已完成：`ParticleViewportReseedGesture` 只在一轮 invalidation 开始时保存 `startZoom`，连续帧不覆盖。
+- 已完成：沿用既有 150 ms debounce；stable 后先计算新 domain/bounds，再消费 gesture 判定。
+- 已完成：采用 `0.05` epsilon。只有 `endZoom < startZoom - 0.05` 才属于明确 Zoom Out。
+- 已完成：有效 viewport domain 下仅设置 `stateSeeded=false` 与 `trailSeeded=false`，复用现有 shader initial-seed、State/Trail target clear 与 pass 顺序。
+- 已完成：fallback/无效 domain 返回 `SkipInvalidDomain` 并清除 active gesture，不留延迟 pending。
+- 已完成：一次 gesture 只消费一次；下一轮重新捕获新的 startZoom；真实 `resetSequence()` 会取消内部 gesture。
+- 已完成：新增成功与 skip 单次诊断日志，包含任务要求字段。
+- 已完成：Zoom In、Pan、Rotate、Pitch 和 epsilon 抖动不触发 reseed。
+
+## 6. 禁止项与接口边界
+
+- 已完成：未为 Zoom Out 调用 `resetSequence()`。
+- 已完成：未重建 State/Trail GPU resource。
+- 已完成：未重新上传 Field；未 reset Timeline/T0/T1/MIX；未 reload style/source。
+- 已完成：未修改 OpenGL/Metal shader。
+- 已完成：未修改 UBO layout。
+- 已完成：未修改公共 Layer、Host、RN API。
+- 已完成：未引入 partial ratio、CPU readback、第二套粒子系统或 Host camera callback。
+
+## 7. STEP-089 / STEP-090 保护
+
+- 已完成：未修改 retained underlay、staticRevision/buildRevision、topology/invalidation 或 ParticleFastPath 文件。
+- 已完成：camera invalidation 与 stable debounce 主路径保持；本次只在动态粒子层 stable domain 判定后改变一次 seed flags。
+- 已完成：continuous simulation cadence、WeatherColor 分层、Runtime Field Window/T0/T1/MIX 保持。
+- 无法验证：Android 实机上的 `fastHit` 增长恢复由 RDC 后续串行确认；Codex 未运行 APK/ADB。
+
+## 8. 构建记录
+
+- 已完成：Mac OpenGL Debug 配置：`cmake -S . -B build-step091-opengl -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DMLN_WITH_OPENGL=ON -DMLN_WITH_GLFW=OFF -DMLN_WITH_WERROR=OFF`，PASS。sandbox module/ccache temp 指向 `/private/tmp`。
+- 已完成：`ninja -C build-step091-opengl -j3 CMakeFiles/mbgl-core.dir/src/mbgl/renderer/layers/render_particle_validation_layer.cpp.o test/CMakeFiles/mbgl-test.dir/renderer/particle_viewport_reseed.test.cpp.o`，2/2 PASS。
+- 未完成且不作为本 Step PASS 声明：新 build tree 的全量 `mbgl-test-runner` 冷链接；在受影响 objects 已独立 PASS 后，于 182/659 主动停止，避免把精确验证扩大成无关全仓冷构建。
+
+## 9. 测试记录
+
+- 已完成：仓库内 gtest source/object 编译 PASS。
+- 已完成：`clang++ -std=c++17 -Wall -Wextra -Werror -Isrc /private/tmp/step091_particle_viewport_reseed_directed.cpp ...` 后运行原生 directed executable，8/8 PASS。
+- 已完成：覆盖明确 Zoom Out、Zoom In、Pan、Rotate/Pitch、epsilon 边界、fallback 消费、单 gesture 单次、下一 gesture startZoom 刷新。
+- 已完成：`git diff --check` PASS。
+- 未运行：Jest。
+- 未运行：Android Gradle/APK/ADB/设备。
+
+## 10. 生成产物
+
+- 无：本任务不生成 AAR/APK/发布 artifact。
+
+## 11. 已知问题与未完成事项
+
+- 无已知 Codex 实现阻塞。
+- 无法验证：Android 正式 RasterParticleLayer 视觉效果、单次 `VIEWPORT_RESEED` 日志、GL/EGL、crash/ANR 与 ParticleFastPath stable 恢复，按任务边界交由 RDC。
+
+## 12. 与任务书差异
+
+- 无生产实现范围差异。
+- 验证方式说明：仓库内定向 gtest 已编译；因本 worktree 是全新 build tree，未完成非必要的 659-object 全 runner 冷链接，改以同一 production helper 的独立原生 C++ executable 实际运行 8/8，满足定向 native test 要求，未宣称全量 runner PASS。
+
+## 13. Git 收尾
+
+- implementation commit hash：`4286c16a53d4f49001f3b41ed4638d3c6edc95b3`。
+- commit message：`fix: reseed particles after zoom out`。
+- implementation push result：SUCCESS，`297b91262..4286c16a5  HEAD -> particle/main`。
+- remote branch：`origin/particle/main`。
+- documentation closeout push result：在本报告纳入 closeout commit 后执行，结果由最终交付回读记录。
+- Final HEAD / `origin/particle/main`：由最终 push 后的 `git rev-parse HEAD`、`git ls-remote` 回读记录在最终交付；Git commit 无法在其自身内容中自指尚未生成的 closeout hash。