MapLibreParticleLab/docs/40_任务/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex任务_v1.md

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 失败不得声称完成。

完成后直接按必做清单报告“已完成 / 未完成 / 无法验证”，不要输出实施计划。