MapLibreParticleLab/docs/报告/40-04_Runtime_Field动态更新接口_Codex完成报告_v1.md

40-04 Runtime Field 动态更新接口 Codex 完成报告

状态

40-04：IMPLEMENTED / WAITING FOR ANDROID VALIDATION

40-03 的 CLOSED / PASS 不变。本轮只交付运行中 Field 窗口推进接口；没有执行 Android 构建或实机验收。

完成结果

1. 正式 Runtime Field API 位于 RasterArraySource：updateRuntimeFieldWindow(particle::ParticleFieldSnapshot newT1)；验证辅助入口为 advanceRuntimeFieldWindow()。
2. 参数是新的 immutable ParticleFieldSnapshot；它包含 fixture/content identity、dataVersion、runtime generation、grid、bounds、NoData、velocity 和 validity。
3. 权威 T0/T1 是 RasterArraySource::Impl::field/nextField。
4. Android/Kotlin 不持有 T0/T1；仅触发 source id 的 advance action，状态行也不复述具体 T0/T1。
5. JNI 是薄桥：MapLibreMap -> NativeMapView -> JNI -> Style::getSource() -> RasterArraySource，不保存窗口、不做 Field 业务计算、不碰 GPU。
6. A/B→B/C 时 Source 输出 old T1(B) 为 new T0；renderer 的 SHA-256/content identity 命中旧 T1，复用其 texture。
7. B/C→C/D 同理，旧 T1(C) 成为 new T0。
8. 正常推进只上传一个新 Field；旧 T1 的 GPU resource 被复用。
9. 正常推进不 Layer recreate。
10. 正常推进不 Style reload。
11. 重叠窗口不 reset simulation，renderer 日志为 simulationRebuild=false。
12. 重叠窗口不 clear trail，renderer 日志为 trailCleared=false。
13. MIX 保持既有 property-only Core setter/UBO 路径，与 Runtime Field update 解耦。
14. 重复当前 T1 内容为 NOOP；重复队列推进耗尽为明确 NO_PRELOADED_FIELD reject，均不产生 upload/reset。
15. 无效、未加载、不兼容或 non-monotonic Snapshot fail closed，记录 FIELD_WINDOW_UPDATE_REJECTED reason=...，不替换当前窗口。
16. 不存在每 frame Field copy/hash/upload；候选仅在 source asset 加载后缓存，runtime generation 仅在候选真正进入 T1 时分配。
17. 未修改 full particle draw；仍是 40-03 已验收的 State N -> draw N -> Trail -> Composite。
18. 本地检查：受影响 Linux/OpenGL Core、conversion 与 source.test.cpp.o 精确 -Werror 编译；新增定向 Source test 对象覆盖窗口两次推进、NOOP、invalid fail-closed。当前 build tree 缺少大量无关测试依赖，完整 mbgl-test 会触发全量重建，故未将其二进制执行误报为通过；clang-format --dry-run --Werror 与 git diff --check 通过。
19. 等待 Android 手工验证：A/B、B/C、C/D 的 reuse/upload/no-reset/no-clear、C/D MIX、候选耗尽拒绝，以及 Android toolchain 编译。
20. 实现 commit hash：45502a53f4fc486bd24cb0008d1ab0ff221e7e63。
21. commit message：feat: add runtime particle field updates。
22. push 结果：待文档收尾 commit 后推送至 origin/particle/main。
23. origin/particle/main 最终 HEAD：待 push 后在交付记录中确认。

Android 验证入口与日志

TIME WINDOW 加载 A=uniform-east / B=uniform-north 并由 Source 预加载 C=vortex、D=nodata。每次 ADVANCE 不调用 setStyle()：Core 记录 FIELD_WINDOW_UPDATE_REQUEST 和 FIELD_WINDOW_UPDATE_APPLIED，renderer 记录 FIELD_REUSE from=OLD_T1 to=NEW_T0、新内容的 FIELD_UPLOAD reason=NEW_CONTENT 以及 simulationRebuild=false trailCleared=false。第三次 advance 应只见 reject，不影响当前 C/D。

Windows 11 手工验证

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 ParticleField:I ParticleGPU:I "*:S"

依次点击 TIME WINDOW、MIX 0/50/100、ADVANCE、ADVANCE，然后在 C/D 再点击 MIX 0/50/100。记录两次 FIELD_REUSE from=OLD_T1 to=NEW_T0、每次恰一条新内容 upload、无 Style reload/layer recreate/reset/trail clear；第三次 ADVANCE 应为 NO_PRELOADED_FIELD 拒绝且 C/D 继续运行。

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

Android Gradle、ADB、实体机和 Jest 均未由 Codex 执行。