40-01 Android 正式粒子 State Seed 修复 Codex 完成报告 v1

1. 结论

已修复正式粒子的 State 初始化契约。40-01 保持 WAITING_MANUAL_VALIDATION；未运行 Android Gradle、ADB 或实体机。

2. 根因

RenderTarget::render() 按 MapLibre 既有 contract 将每个 offscreen pass clear 为 (0,0,0,1)。State shader 原本把 previous.a < 0.5 当作“尚未 seed”，但新的 State A/B target 因此是 opaque black，条件恒为 false。所有 16×16 State texel 都从 (0,0) 开始；uniform-east 仅移动 x，四个 deterministic marker 聚在 canonical world 顶缘，当前视口通常不可见。

没有修改 src/mbgl/renderer/render_target.cpp。

3. Seed contract

ParticleGpuResources::stateSeeded 是唯一生命周期权威。
State pass 使用已有 UBO 的 u_mask.w：1.0 = SEED_STATE，0.0 = CONTINUE_STATE。
shader 在 SEED_STATE 时让每个 texel 从自身 v_uv 初始化，再采样 field；在 CONTINUE_STATE 时从 State read texture 的 previous.rg 继续。field.a 仍仅表示 Field/NoData validity。
Composite commit 后既有 commit() 将 stateSeeded=true。新 resource、context recreation 和 fixture/field reset 令其恢复 false；普通 ACTIVE、Camera、STATIC 与 transient markLayerRenderable(false) 不会重 seed。
STATIC zero-step bootstrap 使用相同 seed flag，但 simulationStep=0，因此建立分散的 deterministic state 而不推进 simulation。

Trail/Composite 的 State write → Trail write wiring、slot swap、hazard=SAFE、formal display、legacy validation display、fixture、mask、world wrap、antimeridian、rotation resource lifecycle 均未改变。

4. 诊断与静态验证

新增低频 ParticleRender: stateSeed=INITIALIZE|CONTINUE，含 generation、State A/B 和 fixture。
shader source：shaders/particle_gpu_validation.fragment.glsl；由 node shaders/generate_shader_code.mjs 生成 OpenGL header，未手改 generated header。
generator 二次运行幂等：PASS；GLSL source 与 generated fragment parity：PASS。
Linux OpenGL render_particle_validation_layer.cpp.o、相关 test/style/source.test.cpp.o 精确编译：PASS。
clang-format --dry-run --Werror 与 git diff --check：PASS。

5. 下一步

用户下一次只验收 GLOBAL + ACTIVE + uniform-east：四个 deterministic marker/trail 应分散在 world 内，且连续向 east 移动。通过前不声明 40-01 PASS。

6. Git 收尾

最终代码修复 commit：087d80d0527c33743a6c59a5c7cce5eeb836dfb5（fix: seed particle state explicitly）。push 成功后 remote branch 与 origin/particle/main HEAD 在交付结果中记录。

2.6 KiB Raw Permalink Blame History Unescape Escape