40-01 Android 离线 Fixture 到正式粒子渲染最小闭环验证报告 v1

状态

PASS。用户已完成 40-01 Stage B Android OpenGL x86_64 手工验收。本文保留 Stage A 静态检查及失败/修复历史，并以 Stage B 验收作为最终结论。

基线与范围

分支：particle/main
开始 HEAD：1ec44701146925dec9a87618e3f90bee9a12073f
本次 PASS 范围：Android OpenGL x86_64 离线 fixture 正式粒子闭环；不扩大为 iOS、Metal、Android Vulkan、真实在线数据或生产 coastline/mask 的 PASS。

最终正式链路

APK asset://integration/particle-fixtures/{uniform-east,uniform-north}/
  -> RasterArraySource -> RenderRasterArraySource
  -> ParticleFieldSnapshot -> GPU field texture
  -> RasterParticleLayer (Source::Required) -> RenderRasterParticleLayer
  -> State A/B -> Trail A/B -> formal Trail composite / shared coastal mask

fixture 使用 metadata.json + field.f32，Core 仅接收 FileSource bytes；metadata、binary length 与 SHA-256 经过校验。
State pass 采样 GPU field，Trail 从 State write texture 读取；不使用 Kotlin/CPU 每帧粒子循环。NoData cell 以 field alpha=0 表示，确定性 respawn，绝不把 -9999 当速度。
STATIC 首帧可以 zero-step bootstrap，之后使用 frozen composite；Activity Bundle 恢复 active、enabled、mask mode 与 fixture mode。

Codex 静态验证

检查	结果
Linux OpenGL 受影响 Core 与 `source.test.cpp.o` 精确编译	PASS（`-Werror`）
`clang-format --dry-run --Werror`	PASS
`git diff --check`	PASS
fixture metadata / SHA-256、adapter smoke、APK asset parity	PASS
shader source/header parity 与 generator 二次运行幂等	PASS
RasterArray runtime generation / field identity 定向 C++ 测试对象	PASS

完整 mbgl-test 不是本任务的精确验证范围，未将未执行测试伪造为 PASS。

Android OpenGL x86_64 手工验收（Stage B）

用户已确认下列项目全部 PASS：

项目	结果
GLOBAL + ACTIVE + UNIFORM EAST	PASS
ACTIVE → STATIC → ACTIVE	PASS
UNIFORM EAST → UNIFORM NORTH → UNIFORM EAST	PASS
STATIC + OCEAN A/B Rotation 自动恢复	PASS
ACTIVE Rotation	PASS
Pan / Zoom / Bearing / Pitch	PASS
World Wrap	PASS
Antimeridian 双向跨越	PASS
GLOBAL / OCEAN A / OCEAN B	PASS
Shared Mask reuse	PASS
DISABLE / ENABLE	PASS
快速 Fixture 切换	PASS
最终重复 Rotation 回归	PASS

Shared Mask 日志事实：同一 RenderThread / GPU resource generation 内，GLOBAL、OCEAN_ONLY_A、OCEAN_ONLY_B 均复用同一 maskGeneration，并记录 reuse=true。graphics resource 重建后 maskGeneration 可以递增；这是新 GPU resource generation 的重建，不是同 generation 内重复创建。

40-01 调试与修复历史

以下失败过程保留为调试与验证记录，不影响最终 PASS：

SourceType::RasterArray 首次 Android C++ 编译遗漏 OfflineDownload 两个 exhaustive switch；按 APK asset:// fixture 的 no-op contract 补齐，未用 default: 掩盖遗漏。
enabled RenderRasterArraySource 曾返回空 RenderItem，RenderTree 无条件解引用导致首次启动 SIGSEGV；source 内补合法 no-op RenderItem，未弱化 orchestrator contract。
Android 出现旧 APK / .cxx native 缓存造成的观察偏差；以当前源码重新生成 native artifact 后继续验收。
source-scoped transient markLayerRenderable(false) 曾每帧 reset State/Trail；移除错误生命周期边界后 ACTIVE frame/slot 连续推进，STATIC 仅在必要时 zero-step bootstrap。
formal Composite 曾只让 Trail RGB 影响 alpha、主体仍为 legacy stripe；FORMAL_PARTICLE 改为显示 Trail RGB，legacy validation display 保留。
shader 逻辑曾与 generated OpenGL header 不同步；已回写 GLSL source、由项目 generator 生成 header，并完成 parity/幂等检查。
opaque RenderTarget clear 使 previous.a 不能表达未 seed；改用 stateSeeded 经 UBO 显式 State seed，初始 marker 分散于 world。
Style source recreation 时 instance-local field generation 碰撞，north 复用 east GPU texture；generation 改为 process-wide revision，renderer 同时比较 generation、fixtureID、dataVersion。
Rotation / Viewport 的 STATIC 自动恢复纳入本任务，已由 STATIC OCEAN A/B 与最终重复 Rotation 回归验证。

范围外事项

40-01 的 Android OpenGL x86_64 范围已 PASS。iOS/Metal、Android Vulkan、真实数据、生产 coastline/mask、性能和独立 EGL context-loss 设备证据不在本次 PASS 声明范围。NoData 有确定性 fixture/static smoke 覆盖，本轮未单独形成 NoData 视觉结论。

最终结论

40-01 Android 离线 Fixture 到正式粒子渲染最小闭环正式判定为 PASS。

4.8 KiB Raw Permalink Blame History Unescape Escape