MapLibreParticleLab/docs/报告/STEP-056_RN天气渲染桥接现状调查_Codex完成报告_v1.md

STEP-056 React Native 天气渲染桥接现状调查 — Codex 完成报告

调查状态

PASS（只读调查完成）。本阶段没有实现 React Native bridge。

• Starting HEAD：44a50e6e4a4e79fae7ddf36af007b5e35e969a92
• 分支/远端：particle/main / origin/particle/main
• 调查文档提交：f37f6eea1f7720c64b2cc949938f29539422b480
• 提交信息：docs: investigate React Native weather rendering bridge
• Push：成功，44a50e6e4..f37f6eea1 particle/main -> particle/main
• 本报告生成时的已推送调查 Final HEAD：f37f6eea1f7720c64b2cc949938f29539422b480

范围与实际检查

检查了 canonical field Adapter/Snapshot、RasterArraySource Host submission 与 Timeline、RasterParticle/WeatherColor style 与 renderer、shader 固定色表、Android MapLibreMap/NativeMapView/JNI、Android Test App REAL WEATHER 调用、Map render request/FPS 以及 layer/source resource destruction。

没有修改功能代码；没有执行 Android Gradle、APK build/install、ADB、App/设备测试或 Jest。

RN bridge 结论

没有可直接复用的 RN binding：仓库无 tracked React Native、TurboModule、Fabric、JSI 或 NativeModule。已有并可复用的是 Android Host Field path：

MapLibreMap.submitRasterArraySourceHostField(String, String, byte[]) → NativeMapView.nativeSubmitRasterArraySourceHostField → NativeMapView::submitRasterArraySourceHostField → RasterArraySource::submitHostField → ParticleFieldDataAdapter → ParticleFieldSnapshot/Core Timeline/Runtime Window。

Test App 的 ParticleCoreLayerValidationActivity::submitRealWeatherDataset() 只是使用 Android asset 模拟未来外部 Host，不是 RN bridge。

推荐 binary 路径

513×769 canonical U/V 单帧为 3,155,976 bytes（约 3.01 MiB）。当前 payload 经 asset/ByteArray、JNI GetArrayRegion 到 vector<char>、Adapter 到 Snapshot vector<float>，存在多次 CPU materialization/copy。

RN v1 推荐 ArrayBuffer/Uint8Array → Android module byte[] → 现有 JNI，优先稳定正确的 canonical contract；不走巨大 JSON。zero-copy 不是现有能力，只有 profiling 证明 copy/GC 是瓶颈时才增加 direct ByteBuffer JNI overload 或 JSI native-buffer seam。

Runtime unload、颜色与性能

• visibility=none 可隐藏 layer，粒子层也停止自身持续 repaint，但不会释放已持有 GPU/Native Snapshot。
• 完整 setWeatherEnabled(false) 可行，但需新低频 lifecycle/clear bridge：停止 playback，remove Particle/WeatherColor layers 以触发 GPU release，clear source timeline/pending fields 或 remove RasterArraySource 以释放 Snapshot。当前没有 clearWindFields() 或一条正式 runtime unload API。
• WeatherColor 仅有 opacity；0–30 m/s palette 硬编码在 particle_gpu_validation.fragment.glsl::weatherSpeedColor。dynamic color stops 应新增到 WeatherColorLayer style property/model，并以 uniform/texture 交给 shader 插值。
• RasterParticle 当前仅有 speed-color-enabled 与多项数值属性；没有 particleColor/trailColor。应新增独立 typed properties，令 speedColor 仅为可选模式，不能由 WeatherColor ramp 隐式决定粒子色。
• 当前约 60 FPS 是 RenderRasterParticleLayer::needsRepaint()、RenderWeatherColorLayer::needsRepaint() 经 Map onUpdate() 与 Android requestRender() 的连续链。MapView#setMaximumFps() 是全图 cap，不能作为天气专属 targetFps。weather-local gate 应独立性能批次，并以累计 wall elapsed 保持 lifecycle/motion/Timeline 语义。

推荐下一阶段

建议进入 STEP-057 Android Host Weather Runtime Bridge Foundation，先实现可由未来 RN module 薄包裹的 Android/Native typed facade：runtime lifecycle/clear、binary submit、timestamp playback controls、visibility/style、低频 structured result/error events、dynamic color stops 与独立 particle/trail color。仓库缺少 RN dependency/host app topology，故不应在此仓库凭空建立可编译 RN package。

weather-local targetFps/repaint gate 建议独立为下一性能批次，避免把 render scheduling 风险混入接口开发。

最大风险为：3 MiB payload 多拷贝带来的内存/GC 峰值；hide/suspend/unload 生命周期混同；以及错误 FPS gate 改变当前 State/Timeline 的 wall-time 行为。

完整证据、文件路径、API mapping 与实施拆分见 STEP-056 调查报告。

无关未跟踪文件（包括 STEP-046-e48fa087-review.diff 与既有 docs/40_任务/ 文件）未修改、未 stage、未提交。