From 89c72554c5fb5cd469bdd8ba06ff4b03a1a67ff9 Mon Sep 17 00:00:00 2001 From: OpenAI Codex Date: Fri, 11 Sep 2026 07:05:46 +0800 Subject: [PATCH] docs: close STEP-067 scalar GPU renderer --- ...larGPU与GenericFieldRenderer_Codex任务_v1.md | 169 ++++++++++++++++++ ..._V3-03_ScalarGPU与GenericFieldRenderer_v1.md | 7 +- ...PU与GenericFieldRenderer_Codex完成报告_v1.md | 8 +- 粒子开发记录.md | 5 + 4 files changed, 183 insertions(+), 6 deletions(-) create mode 100644 docs/40_任务/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex任务_v1.md diff --git a/docs/40_任务/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex任务_v1.md b/docs/40_任务/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex任务_v1.md new file mode 100644 index 000000000..248f3be89 --- /dev/null +++ b/docs/40_任务/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex任务_v1.md @@ -0,0 +1,169 @@ +# STEP-067 MapLibreParticleLab V3-03 Scalar GPU + Generic Field Renderer — Codex任务 v1 + +## 0. 任务定位 + +本任务承接已关闭的 STEP-066，只实施 **GPU field bundle / WeatherColor generic value source**。 + +目标：让 V3 scalar snapshot 首次可由 WeatherColorLayer 真正渲染，并保留 vector magnitude 色场；不实现 DIRECTION 粒子推进，不做 JNI/RN v2 ingress，不做 Android 编译。 + +## 1. 当前基线 + +仓库：`/mnt/sda1/MapLibreParticleLab` + +分支：`particle/main` + +任务书创建时： + +`HEAD == origin/particle/main == 9dabb95e4425ffbcb863c520923f5d4b537a3feb` + +执行时重新确认 HEAD、origin、`git status --short`，不得 reset/clean/stash。 + +STEP-062 用户修改、历史 untracked、build/cache/tgz 均视为无关内容，禁止 `git add .` / `git add -A`。 +## 2. 开工前必须完整阅读 + +- `AGENTS.md` +- `PARTICLE_BASELINE.md` +- `docs/00_项目规范/` +- `docs/20_调查/STEP-065_MapLibreParticleLab_V3通用ScalarVectorField现状调查_v1.md` +- `docs/30_设计/MapLibreParticleLab_V3通用ScalarVectorField运行时架构设计_v1.md` +- `docs/50_Step记录/STEP-066_MapLibreParticleLab_V3-02_CoreContract与ScalarSnapshotAdapter_v1.md` +- `docs/报告/STEP-066_MapLibreParticleLab_V3-02_CoreContract与ScalarSnapshotAdapter_Codex完成报告_v1.md` +- 当前 `field_data_adapter.*` +- 当前 `render_weather_color_layer.*` +- 当前 `render_particle_validation_layer.*` 中 field texture / upload / reuse 路径 +- `weather_color_layer.*`、`weather_color_stop.hpp`、相关 shader/UBO/generator 与 tests + +不得按任务书猜源码；先以当前 HEAD 为准。 + +## 3. 冻结语义 + +1. `FieldValueSource = SCALAR | VECTOR_MAGNITUDE`，必须显式选择，不能根据 channel presence 猜。 +2. `SCALAR` 要求 scalar present；`VECTOR_MAGNITUDE` 要求 vector present；不满足则 WeatherColor renderer fail-closed/unavailable。 +3. Wind/Tide 使用 `VECTOR_MAGNITUDE`；Rain/Wave color 使用 `SCALAR`。 +4. Particle renderer 本任务仍只接受 `VectorSemantics::Velocity`；DIRECTION 留 V3-04。 +5. T0/T1/MIX、Pause、Timeline ownership、OLD_T1→NEW_T0 reuse、only NEW_T1 upload 的架构不变。 +6. WeatherColorLayer 与 RasterParticleLayer 继续分离，但消费同一 Source-owned snapshots。 +7. `FieldColorStop.value` 是 generic 值。C++ 内部 `speedMps` 命名必须在本 Step 收敛为 generic `value`/`fieldValue`；Android/JNI/RN 旧 ABI 本 Step 不修改。 +## 4. 必做实现 + +### A. Generic FieldValueSource + +在 C++ style/render 层新增最小 enum/config，推荐：`enum class FieldValueSource { Scalar, VectorMagnitude };`。 + +放在与 WeatherColorLayer 最贴近且不引入业务域的位置。WeatherColorLayer 必须持有明确 value source；默认值必须保持现有 Wind 行为，即 `VECTOR_MAGNITUDE`，保证旧路径兼容。 + +### B. WeatherColor scalar/vector GPU 输入 + +扩展现有 WeatherColor field texture 生成/上传，使： + +- `VECTOR_MAGNITUDE`：继续从 vector U/V 得到 magnitude 语义；不得改变现有 Wind 可视结果。 +- `SCALAR`：真正上传/编码 scalar 值，shader 根据 T0/T1 MIX 对 scalar 做时间插值后进入相同 generic color ramp。 +- shared validity 必须进入 alpha/有效性判断；T0/T1 任一无效时按现有 fail-closed 策略不可显示错误值。 +- 不允许 scalar 伪装成 U/V。 + +可继续复用现有 texture/UBO/shader 基础设施，但要让 field texture 的数据语义显式，不要复制第二套 WeatherColor renderer。 + +### C. Generic color ramp 命名 + +把 C++ Core/style/render/shader 中与 WeatherColor 色阶相关的 `speedMps` / 固定 speed 语义改成 generic value。至少： + +- `WeatherColorStop.speedMps` → generic `value` +- 校验逻辑变成 finite、严格递增 generic value +- shader/UBO 注释和日志不再声称单位固定 m/s +- 删除/替换 `scale=0..30mps` 这类 Wind-only 日志 + +不得改变 RN `.2` 公共 API，也不得修改 Android/JNI/Kotlin/TS。 +### D. Particle renderer 保护 + +本任务不得实现 DIRECTION advection。现有 RasterParticleLayer 必须显式要求： + +- vector present +- `VectorSemantics::Velocity` + +scalar-only 或 DIRECTION vector 必须 fail-closed，不创建/继续使用错误粒子资源。 + +### E. GPU reuse/content identity + +复核 WeatherColor 的 T0/T1 resource reuse： + +- normal boundary OLD_T1→NEW_T0 可复用相同 decoded plane bundle +- 新 T1 只上传新需要的 texture +- scalar/vector/validity 变化必须触发正确 content change +- 正常 playback 不允许因为 generic value source 改造而重建 Particle simulation 或 clear trail + +如果当前 `sameFieldGpuContent()` 已满足，无需再改 Core Contract。 + +## 5. Shader 约束 + +允许修改 WeatherColor 实际使用的 shader/UBO/generator，只限完成 generic field value。必须保持： + +- T0/T1 GPU 时间插值 +- spatial sampling/bounds +- current vector particle shader physics 不变 +- 不把 provider、WeatherV2、Rain/Wave/Tide 业务名写进 shader +- 不增加第二套专用 rain/wave shader + +如果同一 shader 当前同时承载 particle/weather pass，可做最小 pass/value-source 分支，但不能借此重构整个粒子 shader 架构。 +## 6. 最小验证 + +不加入 Jest。使用现有 C++/OpenGL 测试体系，至少覆盖： + +- WeatherColor default `VECTOR_MAGNITUDE` 保持旧 Wind 行为 +- scalar-only + `SCALAR` 可建立 field texture/render resources +- vector-only + `VECTOR_MAGNITUDE` 可建立资源 +- scalar+vector 可由 value source 明确选择对应 channel +- scalar-only + `VECTOR_MAGNITUDE` fail-closed +- vector-only + `SCALAR` fail-closed +- T0/T1 channel/valueSource compatibility 错误不被渲染 +- scalar T0/T1 MIX 数值路径正确 +- vector magnitude T0/T1 MIX 不回归 +- validity mask 对 scalar/vector 都生效 +- DIRECTION vector 在 Particle renderer fail-closed +- existing v1 Wind fixture/source tests 回归通过 +- `git diff --check` PASS + +执行规定的 Linux OpenGL 精确编译/测试，遵循全局 `$build-output-throttle`。 + +不得执行 Android Gradle、AAR、APK、ADB。 + +## 7. 硬边界 + +本任务禁止修改 Android/JNI/Java/Kotlin、RN package/API/version、Test Host JS/TS、WeatherV2、NavSea；禁止实现 DIRECTION particle movement / wave physics；禁止解析 NSFT/PMTiles；禁止新增 provider/network/cache；禁止重构 Timeline/Playback/Runtime Window；禁止新建 RainRenderer/WaveRenderer/TideRenderer；禁止 Jest 与 Android build/install/ADB。 +## 8. 文档输出 + +必须新增/更新： + +- `docs/50_Step记录/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_v1.md` +- `docs/报告/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex完成报告_v1.md` +- 追加 `粒子开发记录.md` + +所有文档中文。报告逐项列出生产代码修改文件、Renderer/shader 语义变化、精确编译/测试结果、未执行 Android/Jest、未触碰无关工作区。 + +## 9. 必做清单 + +- [ ] 复读规范、STEP-065/066 与当前源码 +- [ ] 引入显式 `FieldValueSource::Scalar / VectorMagnitude` +- [ ] 默认保持 VectorMagnitude 旧 Wind 行为 +- [ ] WeatherColor scalar GPU path 可用 +- [ ] WeatherColor vector magnitude path 回归 +- [ ] shared validity 同时保护 scalar/vector +- [ ] C++ WeatherColor `speedMps` 语义改为 generic value +- [ ] Particle renderer 拒绝 scalar-only 和 DIRECTION +- [ ] T0/T1/MIX 与 resource reuse 不回归 +- [ ] 最小精确 Linux/OpenGL tests PASS +- [ ] `git diff --check` PASS +- [ ] Step/报告/开发记录完成 +- [ ] scoped Git commit + push `origin/particle/main` +## 10. Git 收尾 + +完成后只显式 `git add` 本任务文件与实际修改文件，严禁把 STEP-062 用户修改、历史 untracked、build/cache/tgz 带入提交。 + +创建合理 scoped commit；更新完成报告记录全部 commit hash/message、push 结果与最终远端分支。 + +必须 push 到 `origin/particle/main`，最终复核： + +`HEAD == origin/particle/main` + +push 失败不得声称完成。 + +完成后直接按必做清单报告“已完成 / 未完成 / 无法验证”，不要输出实施计划。 \ No newline at end of file diff --git a/docs/50_Step记录/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_v1.md b/docs/50_Step记录/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_v1.md index 48808366a..350d63bcb 100644 --- a/docs/50_Step记录/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_v1.md +++ b/docs/50_Step记录/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_v1.md @@ -1,6 +1,6 @@ # STEP-067 MapLibreParticleLab V3-03 Scalar GPU 与 Generic Field Renderer -状态：完成（Linux 全量重链受执行环境时限限制，见验证） +状态：完成（CLOSED / PASS） ## 目标与基线 @@ -29,8 +29,9 @@ WeatherColor style/render、Particle renderer guard、实际 GLSL/生成的 Open - 精确受影响对象：`render_weather_color_layer.cpp.o`、`render_particle_validation_layer.cpp.o`、`style_layer.test.cpp.o`：PASS（经 build-output-throttle；ccache 临时目录使用 `/tmp/maplibre-particle-ccache-tmp`）。 - `build-linux-opengl/mbgl-test-runner --gtest_filter='Source.ParticleFieldV3*:Layer.WeatherColorUsesIndependentFixedOpacity'`：PASS，退出码 0。 - `git diff --check`：PASS。 -- 尝试 `ninja -C build-linux-opengl -j3 mbgl-test mbgl-test-runner`：未在单次受限终端时限内完成全量 shader 依赖重链；首轮唯一错误为 sandbox 的 `/root/.cache/ccache/tmp` 只读，改用 `/tmp` 后受影响对象均已通过。不得将此记为全量链接 PASS。 +- 用户于当前 `HEAD`（`06fcbef9ccb820e595f06acbd356950de7e3a73f`）手工执行 `ninja -C build-linux-opengl -j3 mbgl-test mbgl-test-runner`，输出为 `ninja: no work to do.`。确认 `mbgl-test` 与 `mbgl-test-runner` 两个完整目标及其依赖均已是最新，没有待处理的构建或重链接工作。 +- 上述结果仅确认目标构建/重链接状态；本次没有重新执行全量测试用例，不能将其表述为全量测试用例重跑 PASS。 ## 阻塞与下一步 -无功能阻塞。需要具备持续 Linux 构建会话的环境在同一 commit 补跑全量 `mbgl-test` / `mbgl-test-runner` 链接；Android 验收按 V3-08 的单独周期执行。 +无功能阻塞。本 Step 的 Linux 全量目标重链收尾已确认；Android 验收按 V3-08 的单独周期执行，且不属于本 Step 的关闭条件。 diff --git a/docs/报告/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex完成报告_v1.md b/docs/报告/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex完成报告_v1.md index 70070594b..f07a8dd76 100644 --- a/docs/报告/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex完成报告_v1.md +++ b/docs/报告/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex完成报告_v1.md @@ -1,6 +1,6 @@ # STEP-067 MapLibreParticleLab V3-03 Scalar GPU 与 Generic Field Renderer Codex 完成报告 -状态：IMPLEMENTED / Linux 全量重链待持续构建环境复验 +状态：CLOSED / PASS ## 生产代码修改 @@ -11,10 +11,12 @@ ## 验证结果 -shader generator、三个受影响 C++ 编译对象、`Source.ParticleFieldV3*` 与 WeatherColor layer 过滤测试、`git diff --check` 均 PASS，命令输出均经 build-output-throttle 限流。全量 `ninja -C build-linux-opengl -j3 mbgl-test mbgl-test-runner` 因受限终端的 30 秒上限未完成；初始 ccache 临时目录只读已通过 `/tmp` 规避，不能据此虚报全量链接 PASS。 +shader generator、三个受影响 C++ 编译对象、`Source.ParticleFieldV3*` 与 WeatherColor layer 过滤测试、`git diff --check` 均 PASS，命令输出均经 build-output-throttle 限流。此前受限终端未完成的全量重链，已由用户在当前 `HEAD`（`06fcbef9ccb820e595f06acbd356950de7e3a73f`）手工执行 `ninja -C build-linux-opengl -j3 mbgl-test mbgl-test-runner` 收尾，输出为 `ninja: no work to do.`；因此确认 `mbgl-test`、`mbgl-test-runner` 的完整目标和依赖已最新，没有待处理的构建或重链接工作。 + +该手工 Ninja 结果不等于重新执行全量测试用例：本次未重跑完整测试套件，只确认构建/重链接目标无待处理工作。 未执行 Android Gradle、AAR、APK、ADB 或 Jest；未触碰 STEP-062 用户修改、历史 untracked、build/cache/tgz。 ## Git 收尾 -本报告随 scoped 文档提交交付；实现提交 hash、文档提交 hash、push 输出与 `HEAD == origin/particle/main` 的最终复核会在本次 Git 收尾后记录于终端回执。仅显式暂存本 Step 的生产代码、测试与文档文件。 +实现基线提交为 `06fcbef9ccb820e595f06acbd356950de7e3a73f`（`docs: record STEP-067 scalar GPU renderer`）。本次关闭仅提交 STEP-067 任务归档、Step 记录、完成报告和开发记录；不会暂存 STEP-062 用户修改、历史未跟踪文件、build/cache 或 tgz。关闭提交 hash、push 结果与最终 `HEAD == origin/particle/main` 复核见本次交付终端回执。 diff --git a/粒子开发记录.md b/粒子开发记录.md index 3e88d8389..caca6d93b 100644 --- a/粒子开发记录.md +++ b/粒子开发记录.md @@ -641,3 +641,8 @@ WeatherColorLayer 的 `ParticleGpuValidationUBO` designated initializer 补齐 ` - `WeatherColorStop` 的 C++ 字段从 `speedMps` 收敛为 generic `value`；shader/UBO/log 不再声称固定 m/s。切换 value source 会重新编码资源，正常 OLD_T1→NEW_T0 rollover 仍复用同一 decoded bundle。 - RasterParticleLayer 继续只接受 `Velocity` U/V；scalar-only 或 `Direction` 立即不可绘制并释放粒子资源，未实现 DIRECTION advection。 - shader generator、受影响 C++ 对象和 Core/layer 过滤测试均通过；全量 OpenGL `mbgl-test` 链接受当前单次终端时限限制未完成，未虚报 PASS。未运行 Gradle/AAR/APK/ADB/Jest，未触碰 STEP-062 或历史未跟踪内容。 + +## 2026-09-11 — STEP-067 Linux 全量目标验证收尾 + +- 用户在当前 `HEAD` `06fcbef9ccb820e595f06acbd356950de7e3a73f` 手工执行 `ninja -C build-linux-opengl -j3 mbgl-test mbgl-test-runner`，Ninja 返回 `no work to do.`；确认 `mbgl-test` 与 `mbgl-test-runner` 完整目标及其依赖已经最新，没有待处理构建或重链接工作。 +- 此结果只关闭此前 Linux 全量目标重链复验，不代表重新执行全量测试用例；本轮未执行 Android Gradle/AAR/APK/ADB/Jest，未修改生产代码、STEP-062 用户修改或其他历史未跟踪内容。STEP-067 正式 `CLOSED / PASS`。