40-02 Android 双时间片 GPU 时间插值 Codex 完成报告 v1

结论

代码阶段完成，状态为 IMPLEMENTED / WAITING FOR ANDROID VALIDATION，不是 PASS。

实际开始 HEAD：b0f855eb094c21eda9471088537a79f493f12dca（docs: record 40-01 closeout push）
实际完成实现 HEAD：4675a8a29dd6fc7b684bfb64913a8c9075ad8583（feat: add GPU particle time interpolation）；本报告作为紧随其后的文档收尾提交。

实现内容

双时间片数据结构：ParticleFieldTimeWindow 包含 immutable T0/T1 ParticleFieldSnapshot。兼容性检查比较 grid width/height、bounds、NoData、fieldType 和 displayDomain；fixture identity/dataVersion 不作为兼容性条件，但仍作为 GPU slot identity。
Source：RasterArraySource 保持原 fixture/metadata/field，并可接收 next-fixture/next-metadata/next-field。T0/T1 均经 FileSource byte boundary 与 adapter 校验；不兼容窗口报 source error。
GPU T0/T1：同一 ParticleGpuResources 现在持有 fieldTexture 与 nextFieldTexture；未创建第二套 Layer、State、Trail、Mask 或 simulation。
Shader：唯一源 shaders/particle_gpu_validation.fragment.glsl 采样两个 field texture，分别 decode 后执行 mix(velocity0, velocity1, u_marker.x)。u_marker.x 来自 raster-particle-time-mix，不是 CPU 中间 Field。
生命周期：初次 resource create 上传 T0、T1。仅 timeMix 更新时只写 UBO；Camera/transform 不走 Field source-change 分支。A/B -> B/C 如能匹配 B，则移动/复用其 GPU texture，只上传 C，且保留 simulation/trail；没有重叠的真实新窗口保留 40-01 的安全 reset/reseed 行为。
Mask/ACTIVE/STATIC：共享 mask 未复制且 timeMix 不参与 mask upload。ACTIVE 仍是既有连续 simulation；STATIC 不因双 Field 请求连续 repaint。World wrap、antimeridian、rotation/viewport 与既有 State/Trail ping-pong 路径未改。

修改文件及目的

src/mbgl/particle/field/offline_fixture_particle_adapter.*：time-window 兼容性模型。
include/mbgl/style/sources/raster_array_source.hpp、src/mbgl/style/sources/raster_array_source*、src/mbgl/style/conversion/source.cpp：T0/T1 source contract 与加载。
include/mbgl/style/layers/raster_particle_layer.hpp、src/mbgl/style/layers/raster_particle_layer*、particle_render_layer_properties.hpp：timeMix 常量 Layer property。
render_raster_particle_layer.hpp、render_particle_validation_layer.cpp：双 Field texture slot、复用/advance 与低频资源日志。
shaders/particle_gpu_validation.fragment.glsl、生成的 OpenGL header、shader defines/info：实际 GPU dual-field sampling。
Android validation Activity/layout/strings：T0/T1、mix、advance 手工入口。
test/style/source.test.cpp：compatible/incompatible time-window snapshot 定向测试。

日志与资源证明

ParticleGPU 日志记录 T0/T1 fixture/dataVersion、upload count、timeMix、窗口 advance、reuse、simulationRebuild 和 trailCleared。正常 timeMix 更新输出 simulationRebuild=0 trailRebuild=0；不在每帧输出。资源销毁沿用 ParticleGpuResources 既有析构路径。

静态/本地检查

node shaders/generate_shader_code.mjs：通过；随后再次生成应无语义改动。
Linux OpenGL 精确 object compile：raster_array_source.cpp、raster_particle_layer.cpp、render_particle_validation_layer.cpp、shader_info.cpp、adapter 及 test/style/source.test.cpp：通过。
clang-format --dry-run --Werror：通过。
git diff --check：通过。
未运行完整 test binary、Android Gradle、ADB 或设备；遵守任务限制。

用户手工 Android 验证

在仓库根目录执行：

./gradlew :MapLibreAndroidTestApp:assembleOpenglDebug --console=plain
adb -s 192.168.1.146 install -r platform/android/MapLibreAndroidTestApp/build/outputs/apk/opengl/debug/MapLibreAndroidTestApp-opengl-debug.apk
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 -s ParticleValidation mbgl

APK 输出路径为 platform/android/MapLibreAndroidTestApp/build/outputs/apk/opengl/debug/MapLibreAndroidTestApp-opengl-debug.apk。先点 T0 EAST / T1 NORTH，再依次点 MIX 0% / MIX 50% / MIX 100%；随后在 ACTIVE 下反复调 mix、点 ADVANCE B→C，并回归 Camera、GLOBAL/OCEAN、STATIC、Rotation/Viewport、World Wrap 与 Antimeridian。

T1--T10 验收状态

T1 east、T2 50% northeast、T3 north、T4 连续 mix 无 upload、T5 B/C 复用、T6 Camera 无 upload、T7 ACTIVE/STATIC、T8 mask、T9 Rotation/Viewport、T10 World Wrap/Antimeridian：均为用户手工执行，尚未验证。

未完成、风险与下一步

本轮不包含 Android 设备证据，因此不能确认实际 OpenGL sampler binding、视觉方向或 APK UI 资源。时间窗口 advance 的 GPU slot 复用已由 identity 实现与日志覆盖，但必须以 T5 Android 日志确认。若 T1--T10 无阻塞失败，建议进入 40-03 Android OpenGL 性能与资源压力基线；否则先按失败日志做最小修复。

5.1 KiB Raw Permalink Blame History Unescape Escape