STEP-081 iOS Metal Renderer 与真机 Smoke 入口 RDC 真机验收报告 v2

日期：2026-09-18 状态：CLOSED / PASS

验收环境

仓库：MapLibreParticleLab，分支 particle/main。
设备：Pleiades，iPad mini (5th generation) / iPad11,2，iPadOS 26.5.2。
Xcode 26.3，iPhoneOS SDK 26.2，arm64 device build。
Test App Bundle ID：jp.eyaku.maplibreparticlelab.step081。
未使用 Simulator。

最终通过项

签名 device build、安装、启动通过。
Deterministic Uniform East：粒子整体向右/东，PASS。
Deterministic Uniform North：粒子整体向上/北，PASS。
Deterministic Vortex：粒子可见、持续移动并形成连续轨迹，PASS。
QBIN Wind Golden：T0、MID、T1 均正常显示，PASS。
QBIN Clear：正常释放；Clear 后重新 T0 可恢复，PASS。

真机定位出的 Metal 问题与修复

1. Render pipeline cache attachment format 缺失

ShaderProgram::getRenderPipelineState() 原 cache key 未包含 color/depth/stencil attachment pixel format。粒子同一 shader 跨 State RGBA32Float、Trail RGBA8Unorm 与主 renderable 使用时，可能错误复用不兼容 Metal pipeline。修复为在 reuse hash 中合并 color/depth/stencil format。

物理 iPad 诊断中，修复前 Trail target 即使强制纯绿色 fragment 仍为全零；修复后同一路径 RGBA8 target 出现有效写入，因此该根因得到直接设备证据。

2. 亚像素 previous→current line 无稳定覆盖

State/Field/vertex texture sampling、矩阵与坐标范围均被分别证明正确。实际 previous→current 屏幕线段平均约 0.065 px、最大约 0.24 px，全部小于 0.5 px。Metal line primitive 对该长度没有稳定可见 coverage。

最终保留真实 previous→current line，并新增 Metal-only current-endpoint 1 px quad coverage。该 fallback 只补 raster coverage，不修改 State、U/V、advection、时间步、速度或物理线长。中间 Point fallback 会导致整屏绿色，已撤销且不进入最终代码。

3. QBIN smoke 相机不在 fixture 范围

Wind Golden QBIN 解码出的 grid 为 513×769，bounds 为 112.5E..157.5E、0..55.776573N。原 Smoke 入口 FIELD_READY 后不调整相机，世界中心视图看不到字段。Test App 现定位约 27.8883N / 135E、zoom 3；此修改只影响 private smoke 可观察性。

其他正式修复

Darwin layer manager 注册 ParticleValidation / RasterParticle / WeatherColor Core-only factories。
Metal OffscreenTexture 的 size 初始化与 isRenderable() 实现修正。
Metal RenderPass 增加 vertex texture / sampler binding；当前 Texture2D::bind() 为粒子正式路径同时绑定 vertex+fragment。
Metal MSL 恢复 raw short2 a_pos 语义，并修正 fullscreen State/Trail/Composite Y 方向。
Metal render pipeline cache key 现在包含 attachment formats。

清理与边界

所有 STEP081_* readback、固定绿线、matrix-only、State-range 等临时诊断均从最终源码删除。
Test App deterministic fixture 保留高对比显示参数，仅用于人工 smoke；不改变 Core 物理语义。
未修改 QBIN V4 decoder/profile/binding 协议、Android/RN 公共 API、NavSea 或 provider/network 责任边界。
MBXAppDelegate.m 的既有日志级别 dirty 与两个 vendor/submodule dirty 不属于 STEP-081，不纳入提交。

3.3 KiB Raw Blame History Unescape Escape