tei/MapLibreParticleLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2c6f673e5411419cf722aa1bb875e50994bc4c71
MapLibreParticleLab/docs/40_任务/STEP-081_iOS_Metal_Renderer与真机Smoke入口_Codex任务_v1.md
tei 79c0ff89f1
Some checks failed
validate-scripts / validate-scripts (push) Has been cancelled
Details
feat: bring up particle renderer on ios metal
2026-09-17 09:27:35 +09:00

11 KiB
Raw Blame History

STEP-081 — iOS Metal Renderer 与真机 Smoke 入口 Codex 任务 v1

状态：计划 日期：2026-09-17

1. 任务性质与执行机器

本任务在 Mac-mini-tei.lan 的 /Users/tei/dev/MapLibreParticleLab 执行，是 Android 粒子系统完成后的第一张 iOS/Metal 实现任务。

当前代码事实：

  • branch：particle/main
  • 起点 HEAD：f23f4143b9642de0e8d6661dd567e791494a0a0b
  • origin/particle/main：同一 commit
  • 当前 Android/RN 代码版本：13.4.1-particle.5
  • iOS 官方基线：ios-v6.28.0，与 Android 共用 core 18545ca10d296704b2cba675b182ff2c8da24588
  • iOS 当前 renderer：Metal
  • ParticleGpuValidationShader 目前只有 OpenGL ShaderSource，Metal 尚未实现/注册。

Codex 是本任务的大规模代码实现者；Codex 禁止执行任何 iOS/Xcode/CMake 编译、链接、安装、Simulator 或真机操作。Codex 完成后停止，由 RDC 把结果交给 GPT 审查；审查通过后，实际编译和真机验证由 GPT + RDC 完成。

2. 前置必读

开始修改前必须读取并遵守：

  1. AGENTS.md
  2. PARTICLE_BASELINE.md
  3. docs/00_项目规范/ 全部当前文件
  4. docs/00_项目总则/README.md 及其列出的当前有效总则
  5. docs/00_项目总则/当前基线与开发路线_v2.md
  6. packages/maplibre-particle-rn/CHANGELOG.md 与 README.md
  7. 当前 RasterParticleLayer、WeatherColorLayer、QBIN V4 Projection/Materialization 代码
  8. Metal backend、Metal shader group/program、iOS app CMake 与 MLNMapView private Core seam

若旧总则中出现“Simulator 验收”或“Codex 负责构建”的描述，以本任务和用户最新规则为准：iOS 不做 Simulator 测试；Codex 不编译；RDC 编译；运行验收只用真机。

3. 本 Step 目标

实现第一条可被 iOS 真机触发的 Metal 粒子渲染路径：

QBIN V4 / canonical field
→ RasterArraySource V4 renderer projection
→ WeatherColorLayer + RasterParticleLayer
→ ParticleGpuValidationShader (Metal)
→ MapLibre Metal gfx backend
→ iOS 原生 Test App 真机 Smoke 入口

本 Step 不接 React Native iOS bridge。

4. 固定架构边界

必须保持 Android 已冻结的核心语义不变：

  • 不改变 QBIN V4 文件格式、Decoder、FieldProfile/Binding 语义。
  • 不改变 RasterArraySource 对 T0/T1/MIX、Forecast Clock、boundary reuse 的所有权。
  • 不改变 WeatherColorLayer 与 RasterParticleLayer 分离原则。
  • 不新增 iOS 专用 Field 数据模型，不复制一套 Particle Runtime。
  • 不把 provider、HTTP、manifest、下载、缓存或 NavSea 业务逻辑放进 Native/iOS。
  • 粒子颜色继续独立于 WeatherColor ramp；不得为了 Metal 顺手改变视觉产品语义。
  • iOS/Metal 应消费与 Android/OpenGL 相同的 C++ RenderLayer、UBO、field snapshot 和 renderer-facing V4 projection。

后端差异只允许落在 Metal Shader/资源绑定/必要的 backend thin-hook 与 iOS Test App smoke seam。

5. 必做项 A — Metal Particle Shader

新增 ParticleGpuValidationShader 的 Metal ShaderSource，语义必须与当前 OpenGL 版本逐 pass 对齐，至少覆盖：

  • State A/B update
  • Trail fade
  • Trail particle line draw
  • Composite / FrozenComposite
  • WeatherColor pass（当前 u_pass.x > 4.5）
  • T0/T1 timeMix
  • field bounds / respawn bounds
  • VELOCITY 与 DIRECTION 两种 advection semantics
  • particleColor / trailColor / speed-color optional path
  • WeatherColor stops/ramp
  • invalid alpha / invalid sample 的 fail-closed 行为
  • world/map matrix projection Metal 实现必须复用现有 ParticleGpuValidationUBO，不得另建 iOS 专用 UBO。必须核对 Metal alignas(16)/buffer layout 与当前 sizeof(ParticleGpuValidationUBO) == 31 * 16 契约。

必须从当前 shader IDs / texture IDs / attribute IDs 推导 Metal binding，不得凭 OpenGL location 猜测。

建议文件形态遵循现有 Metal shader 规范，例如：

include/mbgl/shaders/mtl/particle_gpu_validation.hpp
src/mbgl/shaders/mtl/particle_gpu_validation.cpp

具体文件名可按仓库现有命名契约调整，但不得把 MSL 字符串塞进 renderer layer 源文件。

6. 必做项 B — Metal backend 注册与构建图接线

必须完成：

  • 在 Metal renderer backend include 新 shader。
  • 将 BuiltIn::ParticleGpuValidationShader 注册进 Metal shader registry。
  • 补齐 Metal shader attributes、textures 与 UBO/buffer binding。
  • 如当前 CMake/Bazel/source list 不是自动 glob，补齐最小构建图接线。
  • 不修改 OpenGL shader 语义来“迁就”Metal；若共享 ID 定义确有缺口，只做 backend-neutral 最小修正并在报告中单列原因。

必须静态检查当前 RenderRasterParticleLayer / RenderWeatherColorLayer 使用的 gfx API 是否存在明显 OpenGL-only 假设。能通过现有 gfx 抽象工作的代码保持不动；只有明确阻断 Metal 的点才允许最小修改。

7. 必做项 C — iOS 原生真机 Smoke 入口

在现有 platform/ios/app 内增加一个最小、隔离、可明确触发的 Particle/QBIN V4 Smoke 场景，用于后续 RDC 编译安装后在真实 iPhone/iPad 上触发 Metal shader runtime compilation。

要求：

  • 使用现有 iOS Test App，不新建第二个产品工程。
  • 场景应能从 App 内明确进入，名称应能识别为 Particle / QBIN V4 Smoke。
  • 使用仓库现有 Wind Golden QBIN T0/T1 作为本地 fixture；不得联网下载。
  • fixture 可通过 CMake resource copy 或其他现有 iOS app 资源机制进入 bundle；不得复制出新的数据格式。
  • 通过 iOS Objective-C++ / private test seam 取得当前 mbgl::Map / Style，并调用现有 C++ Host API；不得新增另一套 runtime。
  • 建立 raster-array source、weather-color layer、raster-particle layer，并提交 Wind T0/T1。
  • Smoke 默认应同时显示 WeatherColor 与 Particle，便于真机确认 Metal 两种 pass 都被实际触发。
  • 至少提供 T0 / midpoint / T1 三个固定时间状态或等价的可操作入口，使后续真机能验证 mix。
  • 提供 clear/reload 最小入口或可重复进入场景的方式，以便观察资源释放/重建。

Smoke 代码只能存在于测试 App/测试 seam，不得进入公开 iOS SDK API，也不得成为 NavSea 正式接口。

8. 非目标

本 Step 明确不做：

  • React Native iOS bridge / TurboModule
  • Expo plugin iOS 接线
  • NavSea iOS 接入
  • npm/iOS artifact 发布
  • Android AAR/RN package 版本升级
  • Vulkan 实现
  • 新粒子算法、视觉重设计、性能调优

9. 允许修改范围

优先限制在：

include/mbgl/shaders/mtl/
src/mbgl/shaders/mtl/
src/mbgl/mtl/renderer_backend.cpp
必要的 CMake/Bazel/source list
src/mbgl/renderer/layers/（仅 Metal 阻断的 backend-neutral 最小修正）
platform/ios/app/
integration/react-native/MapLibreParticleRNTestHost/assets/qbin-golden/wind/（只读 fixture 来源）
docs/30_设计/
docs/50_Step记录/
docs/报告/
粒子开发记录.md

若必须超出以上 production 范围，先判断是否仍属于明确的 Metal thin-hook；若需要改 QBIN/Core contract、RasterArraySource API 或 Android bridge，立即停止并在报告标为 BLOCKED，不得自行扩大任务。

10. 禁止修改范围

禁止：

  • docs/00_项目总则/
  • docs/00_项目规范/
  • QBIN V4 格式/Decoder/Profile/Binding contract
  • Android JNI/Kotlin/RN bridge
  • Android 版本号与公开 artifact coordinate
  • packages/maplibre-particle-rn 公共 API
  • upstream remote/tag/history
  • 与本 Step 无关的已有文件/未跟踪文件

11. Codex 验证规则 — 严禁编译

Codex 本任务只允许静态验证，例如：

git diff --check
git status --short
git grep / rg / find
必要的文本/结构一致性检查

禁止 Codex 执行任何可能进入 iOS/Native 构建、链接、shader runtime 编译、安装或运行的命令，包括但不限于：

xcodebuild
cmake / ninja / make / bazel build
clang / clang++ / metal / metallib 的编译调用
pod install / swift build
simctl
任何 iOS Simulator 命令
任何真机安装/启动命令

也不要用 Android/Linux build 代替 iOS 验证。本 Step 的编译状态在 Codex 报告中必须写为 NOT_RUN_BY_DESIGN。

不加入 Jest，不执行 Jest。

12. GPT/RDC 后续验收接口

Codex 必须在完成报告中明确列出，供 GPT/RDC 后续逐项执行：

  1. iPhoneOS device build 所需的推荐 CMake/Xcode 入口与 target 名称。
  2. Smoke 场景在 iOS Test App 中的进入方法。
  3. 真机预期出现的关键日志事件，至少覆盖 shader/layer creation、field ready、particle resource create。
  4. T0 / midpoint / T1 与 clear/reload 的人工操作步骤。
  5. 若 Metal shader runtime compile 失败，应优先检查的源文件/函数/绑定表。

13. 必做输出

Codex 必须实际生成/更新：

docs/30_设计/STEP-081_iOS_Metal_Renderer与真机Smoke入口设计_v1.md
docs/50_Step记录/STEP-081_iOS_Metal_Renderer与真机Smoke入口_v1.md
docs/报告/STEP-081_iOS_Metal_Renderer与真机Smoke入口_Codex完成报告_v1.md
粒子开发记录.md

设计文档必须记录 OpenGL → Metal pass 对照、Metal UBO/attribute/texture binding 表、Metal 注册位置、Smoke 场景数据链和后续 RN iOS bridge 的明确边界。

Step 状态在 Codex 结束时只能根据事实写：代码实现完成但未编译时，写“进行中 / WAITING_RDC_BUILD_REVIEW”或等价明确表述；不得写 iOS PASS、Metal PASS 或真机 PASS。

完成报告必须至少包含：

  • 执行结论：PASS/PARTIAL/BLOCKED/FAIL（仅针对 Codex 代码任务本身）
  • branch、Start HEAD、End HEAD、工作树状态
  • 实际修改/新增文件
  • Metal shader/pass/binding 实现摘要
  • iOS Smoke 入口说明
  • 与任务书差异
  • 构建记录：明确 NOT_RUN_BY_DESIGN — Codex prohibited from building
  • 静态检查记录
  • 已知风险/未完成项
  • 给 GPT/RDC 的编译与真机验收清单
  • commit hash、commit message、push result、remote branch、Final HEAD

14. Git 收尾

本任务会修改项目文件，因此 Codex 必须：

  1. 只提交本任务相关文件，不得夹带既有无关 dirty/untracked。
  2. 使用 scoped commit message，例如：feat: bring up particle renderer on ios metal。
  3. commit 后 push 到 origin/particle/main。
  4. push 失败不得声称完成。
  5. 完成后不得继续下一 Step，不得自行开始 RN iOS bridge。

15. 停止条件

出现以下任一情况必须停止扩大修改并在报告中写明 BLOCKED/PARTIAL：

  • Metal 实现需要改变 QBIN V4/Core contract 才能继续。
  • 需要建立 iOS 独立 Particle Runtime 或复制 Android Runtime 逻辑。
  • 必须修改 Android bridge/API 才能让 iOS smoke 工作。
  • 发现现有 gfx RenderTarget/Texture/Lines 在 Metal 根本不具备所需能力，且修复将变成大规模 gfx backend 重构。
  • 需要升级 Xcode、MapLibre baseline、CMake、SDK 或第三方依赖。
  • 无法以现有 iOS Test App/private test seam 触发 Core Host API，且需要新增公开 SDK API。

完成本任务后立即停止，等待 RDC 将 Codex 结果交给 GPT 审查。GPT 审查通过后，才由 RDC 执行 iPhoneOS device build，并只在真实 iPhone/iPad 上做运行验收。

Reference in New Issue View Git Blame Copy Permalink