docs: record STEP-067 scalar GPU renderer

docs/50_Step记录/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_v1.md

@@ -0,0 +1,36 @@
+# STEP-067 MapLibreParticleLab V3-03 Scalar GPU 与 Generic Field Renderer
+
+状态：完成（Linux 全量重链受执行环境时限限制，见验证）
+
+## 目标与基线
+
+在 `particle/main` 的 `9dabb95e4425ffbcb863c520923f5d4b537a3feb` 上实现 V3 scalar GPU field bundle 的 WeatherColor 消费，保持 vector magnitude 的 Wind 色场和既有粒子 Velocity 语义。
+
+## 完成内容
+
+- [x] `WeatherColorLayer` 新增显式 `FieldValueSource::Scalar|VectorMagnitude`，默认 `VectorMagnitude`。
+- [x] WeatherColor 单一 GPU renderer 根据明确 source 编码 scalar 或 U/V，shared validity 始终写入 alpha；T0/T1 均无效或缺少所选 channel 时清理 drawable 并 fail-closed。
+- [x] shader 对 scalar 或 vector magnitude 分别先作 T0/T1 时间插值，再进入同一 generic color ramp；没有 scalar 伪装为 U/V。
+- [x] `WeatherColorStop.speedMps` 收敛为 generic `value`，校验为 finite 且严格递增；日志、UBO 注释和 shader 去除固定 m/s 语义。
+- [x] Particle renderer 明确仅接受 vector present 且 `VectorSemantics::Velocity`；scalar-only 与 `Direction` 立即清理其 GPU resource 并 fail-closed。
+- [x] WeatherColor rollover 仍以 decoded bundle content identity 复用 OLD_T1→NEW_T0；切换 value source 时不误复用不同 GPU 编码，只有新内容上传。
+
+## 允许修改
+
+WeatherColor style/render、Particle renderer guard、实际 GLSL/生成的 OpenGL shader header、对应 UBO 注释和 C++ layer test。
+
+## 禁止修改确认
+
+未修改 Android/JNI/Java/Kotlin、RN package/API/version、Test Host、WeatherV2、NavSea、Timeline/Playback/Runtime Window；未实现 DIRECTION advection、Wave physics、v2 JNI/RN ingress；未运行 Gradle、AAR、APK、ADB 或 Jest。
+
+## 验证
+
+- `node shaders/generate_shader_code.mjs`：PASS（经 build-output-throttle）。
+- 精确受影响对象：`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。
+
+## 阻塞与下一步
+
+无功能阻塞。需要具备持续 Linux 构建会话的环境在同一 commit 补跑全量 `mbgl-test` / `mbgl-test-runner` 链接；Android 验收按 V3-08 的单独周期执行。

docs/报告/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex完成报告_v1.md

@@ -0,0 +1,20 @@
+# STEP-067 MapLibreParticleLab V3-03 Scalar GPU 与 Generic Field Renderer Codex 完成报告
+
+状态：IMPLEMENTED / Linux 全量重链待持续构建环境复验
+
+## 生产代码修改
+
+- `weather_color_layer.*` 与 `weather_color_stop.hpp`：增加明确 `FieldValueSource`（默认 `VectorMagnitude`），将 color stop 的 C++ 内部字段改为 generic `value`。
+- `render_weather_color_layer.cpp`：同一 renderer 按 source 显式上传 scalar 或 vector bundle，A 写 shared validity；source 不匹配时 unavailable。切换 source 不复用旧的不同编码，正常同 source rollover 继续重用 immutable decoded bundle。
+- `particle_gpu_validation.fragment.glsl` 与生成的 OpenGL header：Weather pass 用 UBO flag 选择 scalar 或 vector magnitude，分别对 T0/T1 做数值插值后进入通用 ramp；默认 ramp 保留旧 Wind 的 0..30 数值外观，但不再声明固定 m/s 单位。
+- `render_particle_validation_layer.cpp`：Particle 仅接受 vector + `Velocity`；scalar 或 `Direction` 清理粒子资源、不可绘制。粒子 shader 的物理 U/V 计算未改变。
+
+## 验证结果
+
+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。
+
+未执行 Android Gradle、AAR、APK、ADB 或 Jest；未触碰 STEP-062 用户修改、历史 untracked、build/cache/tgz。
+
+## Git 收尾
+
+本报告随 scoped 文档提交交付；实现提交 hash、文档提交 hash、push 输出与 `HEAD == origin/particle/main` 的最终复核会在本次 Git 收尾后记录于终端回执。仅显式暂存本 Step 的生产代码、测试与文档文件。

粒子开发记录.md

@@ -634,3 +634,10 @@ WeatherColorLayer 的 `ParticleGpuValidationUBO` designated initializer 补齐 `
 - 旧 v1 单 payload 未扩展：adapter 从 U/V noData 派生 shared validity，并归一为 `VELOCITY` vector snapshot；Core 不再以 `WIND/GLOBAL` 判断 capability 或 compatibility。
 - Timeline T0/T1/MIX/pause/rollover ownership 未改；compatibility 收紧为 grid/bounds、channel presence 与 vector semantics；content identity 覆盖 scalar/vector/validity 的逐值变化。
 - 既有 GPU renderer 尚不消费 scalar：本轮只让 scalar-only 不可用，未改 shader 或渲染计算。Linux OpenGL Core/source test 精确编译和 `Source.ParticleFieldV3*` 过滤测试通过；未运行 Gradle/AAR/APK/ADB/Jest。
+
+# 2026-09-10 — STEP-067 V3-03 Scalar GPU 与 Generic Field Renderer
+
+- WeatherColor 现以显式 `FieldValueSource::Scalar|VectorMagnitude` 决定使用 canonical scalar 或 U/V magnitude；默认仍是 `VectorMagnitude`，保持现有 Wind 色场。两个时间片均按 selected channel + shared validity fail-closed，scalar 在 GPU 作 T0/T1 数值插值后走同一 generic color ramp。
+- `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 或历史未跟踪内容。