Files
MapLibreParticleLab/docs/50_Step记录/STEP-044_Android_OpenGL粒子数量容量基线_v1.md
OpenAI Codex c0d1ad43c4
Some checks failed
validate-scripts / validate-scripts (push) Has been cancelled
feat: add Android particle capacity baseline
2026-09-03 14:22:16 +08:00

3.3 KiB
Raw Permalink Blame History

STEP-044 Android OpenGL 粒子数量容量基线

  • 状态:IMPLEMENTED / WAITING FOR ANDROID VALIDATION
  • 前置:STEP-041(40-02)已 CLOSED / PASS。
  • 目标:在唯一正式链路 RasterArraySource -> RasterParticleLayer -> GPU State A/B -> Trail A/B -> Composite 上,为 Android OpenGL 提供可重复的 State 粒子容量档位;本 Step 不宣称任何容量实测结果。

实现

  • 正式 RasterParticleLayer 新增常量 paint property raster-particle-particle-count,默认 256。Core 只接受 256..1048576 的平方数,保证 Renderer 总能将其映射为合法的正方形 State texture。
  • 数量的实际承载点是正式 GPU State A/B render target:默认 16x16=256,可切换为 32x32=1024、64x64=4096、128x128=16384、256x256=65536、512x512=262144(Core 支持的中间平方值)和页面最高 1024x1024=1048576。每个 State texel 继续运行既有 State shader,故 effective count 即该网格面积。
  • Trail 仍只读取四个确定性 State texel 作为低开销视觉健康指示;这不是第二个 simulation,也不会改变 State A/B、Trail A/B、Composite 或 40-02 Field/MIX 语义。
  • Android 验证页提供 256 / 1K / 4K / 16K / 64K / 1M 档位。请求通过既有 MapLibreMap -> NativeMapView -> JNI -> Style::getLayer() 薄桥,并经强类型 RasterParticleLayer::setParticleCount(uint32_t) 生效;没有 Java raster-particle Layer peer。
  • 切换数量只替换 State A/B,并执行一次 SIMULATION_RESET reason=PARTICLE_COUNT_CHANGE 以 seed 新网格、清理旧 Trail。Field T0/T1、GPU content reuse、MIX、interpolation、mask、viewport 逻辑和 layer instance/resource generation 均不因该属性本身改变。

观测契约

  • Android host:PARTICLE_COUNT_REQUEST、PARTICLE_COUNT_APPLIED、拒绝原因;状态行显示当前 count。
  • Core/JNI:STYLE_PROPERTY_SET result=SUCCESS|INVALID_PARTICLE_COUNT。
  • Renderer:PARTICLE_RESOURCES_CREATE|REBUILD|RELEASE,每条含 requested/effective count、State grid 和 resource generation;现有低频 schedule/pass/commit 继续证明 simulation、trail 与 composite 持续工作。
  • State target 创建失败时记录 PARTICLE_COUNT_REJECTED reason=STATE_RESOURCE_CREATE_FAILED,旧资源/旧 effective count 保持。

Android 待验收矩阵

粒子数量 是否持续运行 画面/帧表现 内存趋势 GL/GPU 错误 生命周期异常 结论
256 待测 待测 待测 待测 待测 待测
1,024 待测 待测 待测 待测 待测 待测
4,096 待测 待测 待测 待测 待测 待测
16,384 待测 待测 待测 待测 待测 待测
65,536 待测 待测 待测 待测 待测 待测
1,048,576 待测 待测 待测 待测 待测 待测

本地验证边界

  • Linux/OpenGL:raster_particle_layer.cpp.o、render_particle_validation_layer.cpp.o、style_layer.test.cpp.o 精确编译通过;新增 Layer 测试覆盖默认、合法及非法 count 的 Core guard。
  • clang-format 与 git diff --check 通过。
  • 未运行 Android Gradle、ADB、APK 安装或设备测试;未加入/执行 Jest。

Android 用户完成各档长时间测试、GL/GPU 日志和矩阵后,才可判定稳定区间、性能下降区间和压力边界。