MapLibreParticleLab/粒子开发记录.md

粒子开发记录

2026-08-27 — STEP-000

• 建立正式 Ubuntu MapLibreParticleLab 工作目录。
• MapLibre core：18545ca10d296704b2cba675b182ff2c8da24588

2026-08-28 — STEP-000 环境基线冻结

• Ubuntu 24.04 x86_64 MapLibreParticleLab 主开发环境建立完成。
• Linux OpenGL Native 构建通过。
• mbgl-render 构建通过。
• mbgl-render-test-runner 构建通过。
• Android OpenGL Debug apackage 构建通过。
• Android Vulkan Debug apackage 构建通过。
• OpenGL/Vulkan AAR 均包含 arm64-v8a、armeabi-v7a、x86、x86_64 的 libmaplibre.so。
• Vulkan Debug AAR 同时包含 Khronos Validation Layer。
• Android SDK 路径已通过 ANDROID_HOME 与 local.properties 固化。
• 下一步进入 STEP-001：MapLibre Native 粒子接入点只读调查。

2026-08-29 — 10_架构调查

• 按 docs/40_任务/10_架构调查指令书_v1.md 完成只读架构调查。
• 确认当前仓库是 MapLibre Native monorepo，不是 React Native 应用；确认 Android 13.4.1、iOS 6.28.0 和共用 Core 渲染链。
• 确认 Android OpenGL/Vulkan、iOS OpenGL/Metal、Core CustomLayer/gfx、Camera/Matrix、帧驱动和线程边界；粒子 fixture 目前只有空目录占位，暂无粒子运行时代码。
• 生成 docs/20_调查/10_架构调查报告_v1.md 和 docs/报告/10_架构调查_Codex完成报告_v1.md。
• 本次未修改生产代码、原生工程、依赖或项目总则；遵循用户要求未自行创建或修改 Step 文件。

2026-08-29 — 20_架构设计

• 按 docs/40_任务/20_架构设计指令书_v1.md 完成第一版正式粒子系统总体架构设计。
• 生成 docs/10_架构/20_粒子系统总体架构设计_v1.md 和 docs/报告/20_架构设计_Codex完成报告_v1.md。
• 正式主路线冻结为独立 Core RasterParticleLayer/RenderRasterParticleLayer + RasterArraySource + 隔离 mbgl::particle 模块，进入 Style/RenderTree 并使用 MapLibre gfx；CustomLayer/CustomDrawable 不作为产品主宿主。
• 冻结 WeatherColor/Particle 分层、Field/fixture contract、Wind GLOBAL、海洋场 OCEAN_ONLY 共用 Mask、MapLibre frame driver、同帧 Camera Matrix、GPU resource/context-loss 和平台薄接入原则。
• 下一阶段选择 30_最小技术验证，集中验证独立 RenderLayer、OpenGL/Vulkan ping-pong/trail/context、Camera/wrap/Mask 和 iOS 薄接入。
• 最终 FPS、最大粒子数、最佳 texture format、生产 Mask 来源、真实天气协议和生产 Host API 仍未确认。
• 本次未修改生产代码、依赖、构建配置、项目总则或 Step，未运行构建/测试。

2026-08-29 — 30-01 Core RenderLayer 接入验证（阶段 A）

• 按 docs/40_任务/30_01_CoreRenderLayer接入验证指令书_v1.md 完成最小验证代码准备。
• 新增 source-less ParticleValidationLayer/RenderParticleValidationLayer，经正式 Style/LayerManager/RenderTree/LayerGroup/translucent pass 链接入；代码明确标记 VALIDATION ONLY。
• 新增默认 false 的 RenderLayer repaint hook；ACTIVE 通过 MapLibre 自身 needsRepaint → Map::onUpdate → Android requestRender 链持续帧，STATIC 停止验证层额外请求。
• 验证 Drawable 在真实 pass 内读取当前 PaintParameters/TransformParameters/TransformState 的 viewport、zoom、bearing、pitch 和 projection matrix 摘要。
• Android Test App 新增 Particle Core Layer Validation 页面，提供 ACTIVE/STATIC 切换和蓝/黄普通 Style Layer 顺序参照。
• Linux OpenGL 重新配置通过；本任务新增/直接修改的 5 个 Core 对象精确编译通过。全量增量因公共头触发 321 个对象重编译，在 41/321 无错误时主动停止，未宣称全量 PASS。
• 遵循指令书未运行 Android/Gradle/npm/ADB；等待用户手工 Android OpenGL 编译、运行、手势、resize 与日志证据。
• 当前结论为 WAITING_MANUAL_VALIDATION；不得进入下一项 GPU ping-pong/Trail 验证。

2026-08-29 — 30-01 Core RenderLayer 接入验证（阶段 B 修复轮次 1）

• 用户 Android OpenGL 实机日志暴露 RenderParticleValidationLayer::update() 的 DrawableBuilder 生命周期错误：当前 Drawable 未完成就调用 clearDrawables()，RenderThread 随后触发 SIGSEGV。
• 对照 DrawableBuilder::flush(context) 与仓库既有 Drawable 使用方式，在 clearDrawables() 前补充 builder->flush(context)，使 custom validation Drawable 完成后再转移给 LayerGroup。
• 未以空指针判断跳过 Drawable；Tweaker 仍必须进入真实 translucent render pass 并读取同帧 Transform。
• Linux OpenGL 对应目标对象编译通过；C++ 格式和 git diff --check 通过。
• 未运行 Android/Gradle/npm/ADB，等待用户在新提交上重新手工编译和实机运行。
• 当前结论仍为 WAITING_MANUAL_VALIDATION；未扩大到粒子、GPU ping-pong、Trail、Mask、Vulkan 或 iOS。

2026-08-29 — 30-01 Android Test App APK 版本标识

• 在 Test App 主菜单列表顶部增加当前 APK 构建身份显示。
• 显示 versionName/versionCode、renderer flavor、build type 和构建时 Git revision 前 10 位，均来自 BuildConfig，不写死版本。
• 版本条用于人工验证时区分旧 APK 与当前源码构建，避免只凭安装时间或文件名判断。
• git diff --check 与 Android XML 标准库解析通过；按用户要求未执行任何编译。
• 等待用户手工构建、安装后确认设备端显示。

2026-08-29 — 30-02 GPU Ping-Pong 与 Context Recreation（前置阻塞）

• 开始执行 docs/40_任务/30_02_GPU_PingPong与ContextRecreation验证指令书_v1.md 并首先检查硬前置门槛。
• 30-01 最新技术报告与完成报告均仍为 WAITING_MANUAL_VALIDATION，不存在正式 PASS 记录或 PASS commit。
• 按 30-02 指令书第 2 节停止：未创建 State A/B、Trail A/B、RenderTarget、Shader、ping-pong、generation 或 context recreation 验证代码。
• State A/B、Trail A/B、gfx 同步、resize、disable/enable 和 context recreation 均未验证，无 PASS/FAIL 技术结论。
• 当前 30-02 状态为 BLOCKED；不允许进入 30-03。
• 阻塞报告：docs/60_测试/30_02_GPU_PingPong与ContextRecreation最小技术验证报告_v1.md。
• Codex 完成报告：docs/报告/30_02_GPU_PingPong与ContextRecreation验证_Codex完成报告_v1.md。

2026-08-29 — 30-01 Core RenderLayer 接入验证（用户验收 PASS 回填）

• 用户已完成 Android OpenGL 构建和 Particle Core Layer Validation 实际运行验收，明确确认结果为 OK/PASS。
• 30-01 正式状态由 WAITING_MANUAL_VALIDATION 更新为 PASS；Core RenderLayer 接入、ACTIVE/STATIC repaint、同帧 Transform 及 pan/zoom/bearing/pitch/resize 验证范围均由用户确认满足要求。
• 本次只回填验收状态：未重新修改 30-01 代码、未重新编译、未重新运行 Android、未执行 ADB。
• 30-01 正式完成，允许重新开始 30-02。
• 30-02 v1 的 BLOCKED 历史记录继续保留；它反映当时 30-01 正式 PASS 尚未回填，不代表 GPU/gfx 架构验证失败。

2026-08-29 — 30-02 GPU Ping-Pong 与 Context Recreation（阶段 A）

• 30-01 正式状态为 PASS，此前 30-02 v1 的历史 BLOCKED 前置原因已解除；开始重新执行 30-02 指令书。
• validation-only State A/B 已使用两套固定尺寸独立 GPU RenderTarget 实现；每帧 read/write 反向选择，无 CPU 完整状态复制。
• Trail A/B 已使用两套 viewport 尺寸真实 RenderTarget 实现 previous fade/marker → next，并把 next 合成到 MapLibre 主 translucent pass。
• 静态确认只注册当帧 write target，read target 不作为当帧附件；RenderTarget 顺序为 State → Trail，主 pass 后续 composite，slot 在 composite Tweaker 到达时提交。
• resize 只重建 Trail A/B 并保留 State A/B；disable/remove 会停止并释放或重置资源；context lost 记录旧 generation discard，新资源使用递增 generation。
• 复用 Particle Core Layer Validation，保留 ACTIVE/STATIC 并增加 DISABLE/ENABLE；没有修改通用 gfx API、正式粒子、Mask、Vulkan 或 iOS。
• 静态格式、JSON、shader 注册链与 diff 检查通过；遵守用户要求未编译，未运行 Gradle/Android/ADB。
• 当前状态为 WAITING_MANUAL_VALIDATION：State/Trail 实际 GPU 交替、OpenGL 同步、resize、disable/enable 和真实 context recreation 均等待用户手工运行证据。
• 不允许进入 30-03；若无法确认真实 context recreation，最终应按指令书标记 BLOCKED。
• 技术报告：docs/60_测试/30_02_GPU_PingPong与ContextRecreation最小技术验证报告_v2.md。
• Codex 完成报告：docs/报告/30_02_GPU_PingPong与ContextRecreation验证_Codex完成报告_v2.md。

2026-08-30 — 30-02 T3 STATIC freeze 实机缺陷修复

• 用户 Android OpenGL 手工验证确认：STATIC 静止时 State/Trail 停止，但 STATIC 拖动地图触发 MapLibre redraw 时仍继续推进，停止拖动后再停止；原 T3 正式判定为 FAIL。
• 原因是 needsRepaint=false 只停止 validation 主动请求帧，而原 update() 在地图手势帧中仍无条件注册 State/Trail RenderTarget、设置 pending，并由 composite Tweaker提交 slot/frame。
• 最小修复在 RenderParticleValidationLayer 增加 STATIC frozen-composite 路径：地图主 pass 仍正常 redraw 并显示最后 commit 的 Trail，但不注册离屏 target、不执行 State/Trail update、不 fade/加 marker、不 swap、不增加 simulation frame/index。
• STATIC 下不因 resize 重建/清空 Trail；恢复 ACTIVE 后才继续原 ping-pong 与 resize 生命周期。
• 仅修改 validation RenderLayer .cpp/.hpp 和本轮文档；未修改 Test App、shader、通用 gfx、正式粒子、Mask、Vulkan 或 iOS。
• C++ 格式、diff 与 GPU scheduling/commit 静态控制流检查通过；按用户要求未编译，未运行 Android/Gradle/ADB。
• 修复后的 T3 等待用户在 commit 364b8f381e27eee36c4895084b2f0578a023fa61 上重新手工验证；30-02 总体状态仍为 WAITING_MANUAL_VALIDATION，不允许进入 30-03。
• 技术报告：docs/60_测试/30_02_GPU_PingPong与ContextRecreation最小技术验证报告_v3.md。
• Codex 完成报告：docs/报告/30_02_GPU_PingPong与ContextRecreation验证_Codex完成报告_v3.md。

2026-08-30 — 30-02 Android Rotation 状态恢复定向修复

• 用户确认此前 STATIC 的 pan/zoom/bearing/pitch 手势回归已经通过，DISABLE / ENABLE 正常；但旋转导致 Activity recreation 后 STATIC 错误恢复为 ACTIVE。
• 根因是 Test App 没有将 active/enabled 写入 Bundle，且 onCreate() 无条件恢复 ACTIVE + ENABLED 并重置 camera。
• 仅在 ParticleCoreLayerValidationActivity.kt 新增 Bundle key、保存/恢复 validation control mode；recreation 复用恢复后的统一 loadValidationStyle()，且只在首次进入设置默认 camera。
• 未修改 Manifest、C++、gfx、RenderLayer、shader、GPU ping-pong、GPU 状态、Gradle 或依赖；未使用 configChanges、方向锁定、SharedPreferences、全局变量或 GPU 序列化。
• git diff --check 与状态控制静态检查通过；按要求未运行 Gradle、Android 编译或 ADB。
• R1 STATIC、R2 ACTIVE、R3 DISABLED rotation 与 R4 STATIC gesture 回归等待用户实机验证；30-02 保持 WAITING_MANUAL_VALIDATION，不允许进入 30-03。
• 技术报告：docs/60_测试/30_02_GPU_PingPong与ContextRecreation最小技术验证报告_v4.md。
• Codex 完成报告：docs/报告/30_02_GPU_PingPong与ContextRecreation验证_Codex完成报告_v4.md。

2026-08-30 — 30-02 正式关闭（EGL Context Recreation Accepted Risk）

• 用户已完成并确认 30-02 的 Android OpenGL 实机结果；ACTIVE/STATIC、GPU ping-pong、STATIC 手势冻结、DISABLE/ENABLE 与 rotation control-mode 恢复纳入正式结论。
• 30-02 正式状态为 PASS，并正式关闭；允许进入 30-03。
• 真实 EGL Context recreation 没有独立实机验证证据，明确标记为 Accepted Risk / 未验证项；用户已明确决定该风险不阻塞后续阶段。
• 未伪造 context-loss PASS，也未重写 v1 BLOCKED、v2、v3 或 v4 历史报告。
• 本次只回填报告与开发记录；未修改代码，未重新编译，未运行 Gradle、Android 或 ADB。
• 技术报告：docs/60_测试/30_02_GPU_PingPong与ContextRecreation最小技术验证报告_v5.md。
• Codex 完成报告：docs/报告/30_02_GPU_PingPong与ContextRecreation验证_Codex完成报告_v5.md。

2026-08-30 — 30-03 Camera / World Wrap 与 Land/Ocean Mask（阶段 A）

• 30-02 已正式 PASS，EGL Context recreation 作为用户接受的未验证风险不阻塞，故开始 30-03。
• validation composite 改为使用当前 PaintParameters::matrixForTile() 的 canonical z0 world quad；ACTIVE/STATIC 继续区分 simulation update 与 Camera redraw。
• 通过 UnwrappedTileID.wrap 绘制中心和相邻 MapLibre world copy；仅中心 copy commit，避免 world copy 额外推进 30-02 GPU simulation。
• 增加反经线两侧 deterministic anchors C/D，并以全球 canonical mask UV 复用 MapLibre wrap，不建立第二套 world 状态机。
• 增加 validation-only shared 16×16 synthetic coastal mask，GLOBAL、OCEAN_ONLY_A/B 复用同一 GPU texture；Camera/consumer 切换不重建，context-destroy 通知后按新 generation 重建。
• Android Test App 复用既有入口，增加 GLOBAL/OCEAN A/OCEAN B/DATELINE/WORLD WRAP 最小控制；未运行 Android 编译、Gradle 或 ADB。
• Linux OpenGL 受影响 Core 对象精确编译、C++ 格式与 diff 检查通过；用户 T1–T13 实机验证仍待执行。
• 当前状态：WAITING_MANUAL_VALIDATION；不允许进入 iOS 最小验证。
• 技术报告：docs/60_测试/30_03_Camera_WorldWrap与LandOceanMask最小技术验证报告_v1.md。
• Codex 完成报告：docs/报告/30_03_Camera_WorldWrap与LandOceanMask验证_Codex完成报告_v1.md。

2026-08-31 — 30-03 Camera / World Wrap 与 Land/Ocean Mask（最终 PASS）

• 用户已完成 Android OpenGL 手工验收，T1–T13 全部记录为 PASS；30-03 正式状态更新为 PASS。
• 已确认本最小验证范围内的 Camera 同帧地理锁定、ACTIVE/STATIC camera redraw 分离、world wrap、双向反经线连续性，以及 shared Land/Ocean Mask 的 GLOBAL / OCEAN_ONLY_A / OCEAN_ONLY_B 语义。
• Rotation/Viewport 自动恢复问题 为已知问题；用户接受延期，明确在下一个任务修复。本轮不声称该问题已修复，也不将其伪造为已验证功能。
• 真实 EGL context recreation 的独立设备证据、正式 fixture adapter、正式 NoData fail-closed 和生产 coastline 数据仍未完成；EGL 风险沿用 30-02 的 Accepted Risk / 未验证 边界。
• 30-03 已允许进入下一阶段；下一任务优先处理 Rotation/Viewport 自动恢复延期项。

2026-08-31 — 40-01 Android 离线 Fixture 到正式粒子渲染最小闭环（Stage A）

• 30-03 后进入 Android 第一条离线 fixture 粒子闭环；Rotation/Viewport 自动恢复技术债已纳入本任务。
• 新增 backend-neutral OfflineFixtureParticleAdapter 和 ParticleFieldSnapshot，以 v1 metadata、binary length 与 SHA-256 把 uniform-east、uniform-north、vortex 解码为正式 Field；不使用在线数据或 Android UI 依赖。
• GPU field texture 接入既有 State A/B；Trail A/B 改为读取 State write texture，fixture 切换递增 field/gpu field generation 并清理旧 trail；Mask 继续走既有 shared GLOBAL/OCEAN_ONLY 路线。
• STATIC 不再阻止 resource bootstrap：Activity/context recreation 后会建立 field/mask/trail/state 并做零步 first composite，simulationFrame 不增加；Activity 保存 active/enabled/mask/fixture 选择。
• Linux OpenGL 受影响 Core 对象、C++ format、diff、fixture checksum 和 adapter smoke test 均通过；未运行 Gradle/ADB/实机验证。
• 当前结论：WAITING_MANUAL_VALIDATION。用户仍需完成 Android OpenGL T1-T12，尤其 T1 rotation 无按钮恢复；iOS、Vulkan、真实数据、生产 mask 和性能均未覆盖，尚不建议进入下一 Android 子任务。
• Stage A 实现提交 0b076c6d52fffb2ee4411cac64f06d43cea260c8 已成功 push 到 origin/particle/main。