MapLibreParticleLab/docs/报告/40-03_Android_OpenGL粒子数量容量基线_Codex完成报告_v1.md

40-03 Android OpenGL 粒子数量容量基线 Codex 完成报告

状态

40-03：IMPLEMENTED / WAITING FOR ANDROID VALIDATION

40-02 的已关闭结论未改变。本报告只交付正式 GPU 链的容量测试入口；Android x86_64 实机矩阵尚无结果，不能写 PASS 或声称存在稳定容量区间。

已完成

1. 当前正式粒子数的最终控制点是 RenderRasterParticleLayer 的 State A/B render target。原固定 16x16 即 256 个 State shader texel；每个 texel保存并推进一粒子的 RG position、B age、A validity。
2. 新增 RasterParticleLayer::setParticleCount(uint32_t) 与 raster-particle-particle-count。默认仍为 256，Core 接受 256 到 1,048,576 的平方数，实际生效 count 为 State grid 面积。
3. Android 验证页增加 256 / 1K / 4K / 16K / 64K / 1M。请求经既有 JNI float-property 薄桥进入强类型 Core setter，成功后才更新 host count；没有 CPU simulation、第二 Layer 或 Java Layer peer。
4. 切换 count 会释放并替换 State A/B，记录一次有理由的 SIMULATION_RESET reason=PARTICLE_COUNT_CHANGE，随后重新 seed State/Trail。它不会执行 Style reload、Field upload、MIX 更新或时间窗推进；Field T0/T1、SHA-256 reuse、interpolation、mask 和 40-02 生命周期语义保持。
5. 新增低频资源诊断：PARTICLE_COUNT_REQUEST/APPLIED/REJECTED、PARTICLE_RESOURCES_CREATE/REBUILD/RELEASE、STYLE_PROPERTY_SET。它们含 requested/effective count、State grid、resource generation 或失败原因；原有采样 schedule/pass/commit 日志继续用于确认 simulation、trail 与 composite。

Trail 仍将四个确定性 State texel投射为可视 marker/trail。这是正式 State simulation 的低开销可视健康指示，不改变实际 State texel 并行数，也没有复制任何 simulation。

本地检查

• clang-format：受影响 C++ 文件已格式化。
• Linux/OpenGL 精确编译：raster_particle_layer.cpp.o、render_particle_validation_layer.cpp.o、style_layer.test.cpp.o 均通过。
• 新增 Layer.RasterParticleCountProperties 测试对象已成功编译，覆盖默认 256、合法 65,536、非平方与越界拒绝；完整测试二进制在当前 build tree 不存在，因此未将其运行误报为通过。
• git diff --check：通过。
• Android Gradle：未执行。ADB / APK 安装 / 设备测试：未执行。Jest：未加入、未执行。

未完成／等待用户验证

• 六个档位的持续运行、帧表现、内存趋势、GL/GPU 错误与 crash 结果。
• 稳定运行区间、性能明显下降区间和当前压力边界。
• Android Kotlin/JNI 的最终 Android toolchain 编译和 x86_64 OpenGL 实测。

Windows 11 手工验证

在 PowerShell 或 CMD 中依次执行：

cd /mnt/sda1/MapLibreParticleLab/platform/android
./gradlew :MapLibreAndroidTestApp:assembleOpenglDebug -Pandroid.injected.build.abi=x86_64 --console=plain
adb -s 192.168.1.146 install -r .\MapLibreAndroidTestApp\build\intermediates\apk\opengl\debug\MapLibreAndroidTestApp-opengl-debug.apk
adb -s 192.168.1.146 logcat -c
adb -s 192.168.1.146 shell am start -n org.maplibre.android.testapp/.activity.particle.ParticleCoreLayerValidationActivity
adb -s 192.168.1.146 logcat -v time ParticleValidation:I ParticleGPU:I "*:S"

页面默认 256；依次点击 1K、4K、16K、64K、1M，每档至少观察持续推进、四个代表性 trail、交互、内存和日志。每次切换应见 PARTICLE_COUNT_REQUEST、JNI STYLE_PROPERTY_SET result=SUCCESS、PARTICLE_RESOURCES_RELEASE、SIMULATION_RESET reason=PARTICLE_COUNT_CHANGE 与 PARTICLE_RESOURCES_REBUILD；不应见 FIELD_UPLOAD、Style reload 或无理由 reset。若高档创建失败，应记录 PARTICLE_COUNT_REJECTED 而保持旧档稳定运行。

APK 路径：./MapLibreAndroidTestApp/build/intermediates/apk/opengl/debug/MapLibreAndroidTestApp-opengl-debug.apk。