STEP-081 iOS Metal Renderer 与真机 Smoke 入口 v1

状态：CLOSED / PASS

目标

为既有 C++ RasterArray/QBIN V4 → WeatherColor + RasterParticle path 增加 Metal shader registry 接线，并在 iOS Test App 中提供 Wind Golden QBIN 的真机 smoke 入口。

本轮结果

新增 Metal ParticleGpuValidationShader source、属性/纹理表和 registry 注册。
保持 ParticleGpuValidationUBO 为唯一 shared UBO，MSL 静态契约为 31 * 16。
在 Test App Runtime Styling 菜单加入 T0/midpoint/T1/clear private smoke seam。
CMake 将既有 Wind Golden T0/T1 复制到 app bundle。
仅做静态检查；未执行 Jest。
iPhoneOS arm64 Test App 无签名编译通过，BUILD SUCCEEDED。
Pleiades（iPad mini 5 / iPadOS 26.5.2）完成签名安装、真实 Metal runtime 与视觉验收。
Deterministic Uniform East 向右、Uniform North 向上、Vortex 可见并具有连续轨迹。
QBIN T0 / MID / T1 / Clear / Clear 后重新 T0 均通过。

允许范围与限制

修改仅涉及 Metal thin-hook、iOS Test App、CMake Metal/app 资源接线以及本 Step 文档。未修改 QBIN V4/Decoder/Profile/Binding、Android/RN API、版本坐标或项目总则。现有 gfx 代码使用 gfx::RenderTarget、Texture2D、Lines 与 shader registry；静态审查未见 layer 内的直接 OpenGL 调用。

真机验收入口

在 iOS Test App 中，Particle Core Validation (Fixtures) 用 Uniform East / Uniform North / Vortex 验证正式 Host ingress → RasterParticleLayer → Metal 路径；Particle / QBIN V4 Smoke (T0) 用 T0 / midpoint / T1 / Clear 验证真实 Wind Golden QBIN。QBIN T0/MID/T1 对应 1789239600000 / 1789241400000 / 1789243200000。

构建与阻塞

Codex 未执行任何编译；GPT 审查后由 RDC 完成 CMake/Xcode iPhoneOS arm64 build。最终签名 device build BUILD SUCCEEDED，Bundle ID jp.eyaku.maplibreparticlelab.step081，Wind T0/T1 QBIN 均进入 ParticleSmokeFixtures/。随后在 Pleiades 真机完成安装、启动、Metal shader runtime 与视觉 smoke。

GPT / RDC 独立审查（2026-09-17）

Codex 结束后由 RDC 读取完整 diff、设计文档和完成报告，GPT 独立审查通过；编译仍未执行。审查中做了 3 个小范围、事实明确的修正：

State A/B RenderTarget 明确为 TextureChannelDataType::Float，Metal fragment 输出由 half4 改为 float4，避免 Web Mercator 粒子状态在 shader 输出阶段降为半精度。
Metal resolveAdvection() 的 VELOCITY 零向量行为与 OpenGL fragment fail-closed 对齐：长度 <= 0.00001 返回 false。
Smoke 选择器由 iPad 需要 popover anchor 的 ActionSheet 改为 Alert，保证 iPhone/iPad 真机都可直接进入。

git diff --check 通过；未发现 QBIN V4/Core contract、Android/RN API 或版本坐标越界修改。下一步允许 RDC 执行 iPhoneOS device build；仍禁止 Simulator。

RDC 编译验证（2026-09-17）

cmake --preset ios-metal 配置成功，Xcode 26.3 / iPhoneOS 26.2 / AppleClang 17。
Darwin style codegen 需要 Bazel；按仓库 .bazelversion 使用 Bazel 8.6.0 后通过。
首次签名构建被 org.maplibre.app provisioning 阻塞，因此改用 CODE_SIGNING_ALLOWED=NO 做 device-architecture 编译验证；未使用 Simulator。
编译中只对 Test App 做小范围修正：使用 ${CMAKE_SOURCE_DIR}/src 暴露 private smoke 所需内部头；weakSelf 改为显式 MBXViewController *；fixture path 使用 NSString *。
最终 app target BUILD SUCCEEDED；particle_gpu_validation.cpp 和 MBXViewController.mm 均通过 arm64 编译。
当前登记 iPhone/iPad 均为 unavailable，因此状态进入 WAITING_DEVICE_SMOKE，不能声明真机/Metal runtime PASS。

RDC 真机收口（2026-09-18）

设备：Pleiades，iPad mini (5th generation) / iPad11,2，iPadOS 26.5.2；使用 iPhoneOS device build，未使用 Simulator。
确认 Metal render-pipeline cache key 缺少 attachment pixel format：State RGBA32Float / Trail RGBA8Unorm / 主 renderable BGRA8Unorm 之间可能错误复用 pipeline。src/mbgl/shaders/mtl/shader_program.cpp 已把 color/depth/stencil format 合入 cache key。
Trail target 强制写测试在修复前全零、修复后 RGBA8 有效写入，证明 cache-key 根因。
State GPU 与 CPU/视觉验证确认 canonical U/V、T0/T1、State ping-pong、vertex-stage texture sampling 和 z0 matrix 投影正确。
实测正式 previous→current 线段平均约 0.065 px、最大约 0.24 px，全部 <0.5 px；Metal line primitive 无稳定覆盖。保留真实 line，同时增加 Metal-only 1 px current-endpoint quad coverage，不改变物理位移。
Deterministic：Uniform East 向东/右，Uniform North 向北/上，Vortex 粒子可见、移动连续、有轨迹感。
QBIN Golden fixture：grid 513×769，bounds=112.5E..157.5E / 0..55.776573N；Smoke 相机定位约 27.8883N / 135E、zoom 3 后，T0 / MID / T1 / Clear / Clear 后重进全部人工确认正常。
中间 STEP081_* GPU readback / fixed-line / point fallback 诊断均已删除；错误的 Point coverage 曾导致整屏绿色，最终未保留。
git diff --check 在最终清理后通过；无关 MBXAppDelegate.m 与 vendor/submodule dirty 不纳入 STEP-081 commit。
功能与真机验收实现已提交并成功推送：f1c0f92b2b（fix: close STEP-081 iOS Metal particle rendering），origin/particle/main 已同步。

5.4 KiB Raw Permalink Blame History Unescape Escape