chore: freeze MapLibreParticleLab step 0 baseline
Some checks failed
validate-scripts / validate-scripts (push) Has been cancelled

This commit is contained in:
OpenAI Codex
2026-08-28 16:38:16 +08:00
parent 18545ca10d
commit ea5b8f9d7f
32 changed files with 398 additions and 0 deletions

View File

@@ -0,0 +1,3 @@
# 文档目录与命名规范 v1
正式目录:`00_项目规范/10_架构/20_调查/30_设计/40_任务/50_Step记录/60_测试/70_发布/报告`。正式说明文档文件名和正文使用中文;代码/API/命令保留英文。同主题只用 `_v1/_v2/_v3` 递增,不得用“最新版/修正版/final”制造近义文件。调查=`<主题>调查_vN.md`,设计=`<主题>设计_vN.md`,任务=`STEP-xxx_<主题>_Codex任务_vN.md`,Step=`STEP-xxx_<主题>_vN.md`,完成报告=`STEP-xxx_<主题>_Codex完成报告_vN.md`。完成报告只放 `docs/报告/`。

View File

@@ -0,0 +1,3 @@
# Codex 协作规范 v1
标准流程:只读调查 → 设计 → Step → 实现 → 构建/测试 → 完成报告 → Step 更新。没有调查结论不得凭猜测大改 Core。每个任务明确目标、必做项、允许/禁止范围、构建测试、必做输出、停止条件。无法完成必须明确阻塞,不伪造 PASS。默认禁止 force push、push upstream、改写官方 tag、删除历史 Step/报告、无授权扩大重构。

View File

@@ -0,0 +1,3 @@
# 构建与验证规范 v1
主环境 Ubuntu 24.04 x86_64,默认并行度 3。Linux 优先官方 CMake/Make 路线,至少保证 OpenGL build、mbgl-render、mbgl-render-test-runner。Android 官方路线:Java17、.nvmrc Node、npm install --ignore-scripts;`cd platform/android && RENDERER=opengl BUILDTYPE=Debug make apackage` 与 `RENDERER=vulkan BUILDTYPE=Debug make apackage`。涉及 renderer/backend 必须双 backend 验证。Linux 不得宣称 iOS/Metal PASS,必须 Mac 同 commit 验证。基础回归只用离线 fixture。GPU 阶段记录粒子数、FPS/frame time、backend 与 pan/zoom/rotate/pitch。

View File

@@ -0,0 +1,3 @@
# Step 阶段记录规范 v1
Step 连续编号 STEP-000/001/002,不跳号。状态只用:计划/进行中/阻塞/完成/冻结。每个 Step 至少有:状态、目标、基线、必做项勾选、允许修改、禁止修改、构建测试、必做输出、当前结果、阻塞、下一步。执行结束必须更新 Step、追加粒子开发记录、生成 docs/报告 完成报告;未完成项不得勾选。

View File

@@ -0,0 +1,3 @@
# Git 与上游同步规范 v1
upstream=MapLibre GitHub,仅 fetch,push=DISABLED;origin=用户 Gitea。日常分支 particle/main。提交小而单一。上游升级使用 upgrade/<release> 基于官方新 release 重放 Particle commits,完整回归后更新 PARTICLE_BASELINE.md;不得直接把 upstream/main 混进 particle/main。必须启用 git rerere。

View File

@@ -0,0 +1,3 @@
# 粒子架构原则 v1
目标链:RasterArraySource → RasterArrayTile/Velocity Field → WeatherColorLayer + RasterParticleLayer → RenderRasterParticleLayer → Particle State A/B + GPU Update/Draw/Trail → MapLibre gfx/backend → OpenGL/Vulkan/Metal。WeatherColor 表达定量颜色,Particle 表达方向/运动,默认不得靠降低 WeatherColor opacity 才看导航信息。Wind=GLOBAL;Wave/Tide/Current=OCEAN_ONLY 共用 Land/Ocean Mask。Particle State 格式/坐标系/生命周期/跨 tile 必须单独设计后冻结。

View File

@@ -0,0 +1,18 @@
# 官方基线来源 v1
本项目初始化版本依据 MapLibre 官方资料固定:
- MapLibre Native releases:`https://github.com/maplibre/maplibre-native/releases`
- Linux 开发文档:`https://maplibre.org/maplibre-native/docs/book/platforms/linux/`
- Render Tests:`https://maplibre.org/maplibre-native/docs/book/render-tests.html`
- Android release CI:MapLibre Native `.github/workflows/android-release.yml`
- Android `Versions.kt`:当前 core `18545ca` 的 `ndkVersion = 28.2.13676358`,`cmakeVersion = 3.24.0+`。
当前冻结:
- Android `android-v13.4.1` → core `18545ca`
- iOS `ios-v6.28.0` → core `18545ca`
- Android compileSdk = 34
- Java = 17
初始化脚本仍会运行时验证 Android/iOS tag 是否继续指向同一 core,避免只依赖本文档。

View File

@@ -0,0 +1,3 @@
# MapLibre 粒子总体架构 v1
Layer:Base Map → WeatherColorLayer → RasterParticleLayer → Navigation Reference → AIS/Route/Ownship/Alarm。GPU 核心候选:Velocity Texture、Particle State A/B、Update、Draw、Trail Render Target、Color Ramp。

3
docs/20_调查/README.md Normal file
View File

@@ -0,0 +1,3 @@
# 调查目录
第一份建议 `MapLibre粒子接入点调查_v1.md`,只读调查 Style/Source/Tile/RenderLayer/gfx/ShaderRegistry/OpenGL/Vulkan/Metal。

3
docs/30_设计/README.md Normal file
View File

@@ -0,0 +1,3 @@
# 设计目录
调查后再写设计:ParticleState、VelocityField、Trail、RasterParticleLayer接口、LandOceanMask。

3
docs/40_任务/README.md Normal file
View File

@@ -0,0 +1,3 @@
# Codex 任务目录
文件名 `STEP-xxx_<主题>_Codex任务_vN.md`;完成报告固定 `docs/报告/`。

View File

@@ -0,0 +1,3 @@
# Step 记录目录
保存阶段权威状态,初始化脚本生成 STEP-000。

View File

@@ -0,0 +1,27 @@
# STEP-000 完整环境初始化 v1
## 状态
进行中
## 目标
建立 MapLibreParticleLab 完整 Linux/Android 开发环境与 Codex 中文工程规范。
## 必做项
- [x] MapLibre 正式 release 基线
- [x] 全 submodule
- [x] upstream / origin
- [x] particle/main
- [x] 中文文档目录和命名规范
- [x] Codex 协作规范
- [x] 构建规范
- [x] Step 规范
- [x] Node/npm 环境
- [x] Android SDK/NDK
- [x] Linux Native 构建
- [x] Android OpenGL 构建
- [x] Android Vulkan 构建
- [x] 初始化完成报告
## 必做输出
- PARTICLE_BASELINE.md
- 环境初始化报告.txt

View File

@@ -0,0 +1,9 @@
# 固定测试场景 v1
- uniform-east:恒定向东
- uniform-north:恒定向北
- vortex:旋涡
- shear:剪切
- coastal-mask:Coverage/Mask
全部离线固定可重复。

3
docs/70_发布/README.md Normal file
View File

@@ -0,0 +1,3 @@
# 发布目录
保存 Particle release、MapLibre upstream 升级、冻结 commit 和双平台回归结果。

3
docs/报告/README.md Normal file
View File

@@ -0,0 +1,3 @@
# Codex 完成报告目录
统一 `STEP-xxx_<主题>_Codex完成报告_vN.md`,不得覆盖旧版本。

View File

@@ -0,0 +1,118 @@
# STEP-000 环境初始化完成报告 v1
## 结论
MapLibreParticleLab Linux / Android 主开发环境已完成建立,可以进入粒子系统开发阶段。
## 主开发环境
- Ubuntu 24.04 LTS
- x86_64
- 4 CPU 线程
- 约 8 GB RAM
- 默认编译并行度:3
## Git
- 正式开发分支:`particle/main`
- `upstream`:MapLibre 官方 GitHub
- `origin`:用户 Gitea
- `upstream` 只用于读取官方更新
- `git rerere` 用于长期 Fork 冲突复用
## MapLibre 基线
- Android:`android-v13.4.1`
- iOS:`ios-v6.28.0`
- Android/iOS 使用共同 MapLibre Native core 基线
- 实际 commit 以根目录 `PARTICLE_BASELINE.md` 为准
## Linux Native 验证
已通过:
- CMake `linux-opengl` configure
- Linux OpenGL backend
- `mbgl-render`
- `mbgl-render-test-runner`
## Android OpenGL
已成功生成:
`platform/android/MapLibreAndroid/build/outputs/aar/MapLibreAndroid-opengl-debug.aar`
包含:
- `arm64-v8a/libmaplibre.so`
- `armeabi-v7a/libmaplibre.so`
- `x86/libmaplibre.so`
- `x86_64/libmaplibre.so`
结论:PASS。
## Android Vulkan
已成功生成:
`platform/android/MapLibreAndroid/build/outputs/aar/MapLibreAndroid-vulkan-debug.aar`
包含:
- arm64-v8a
- armeabi-v7a
- x86
- x86_64
四种 ABI 的 `libmaplibre.so`。
Debug AAR 同时包含对应的 Khronos Vulkan Validation Layer。
结论:PASS。
## Android SDK
已确认:
- `ANDROID_HOME=/root/Android/Sdk`
- Android Platform Tools 可用
- NDK `28.2.13676358` 可用
- `platform/android/local.properties` 已配置
- `render-test/android/local.properties` 已配置
## 已修正的问题
### Linux preset 构建目录
实际 CMake preset 输出:
`build-linux-opengl`
构建工具已统一使用该目录,不再错误引用 `build`。
### Android SDK 定位
Gradle 工程同时使用 `ANDROID_HOME` 和本机 `local.properties`,避免新 shell 或 Codex 环境找不到 SDK。
## Codex 开发规范
已建立:
- `AGENTS.md`
- 中文构建规范
- 中文 Codex 协作规范
- Step 阶段记录规范
- 文档目录与命名规范
- Git/upstream 同步规范
- 粒子总体架构原则
- `docs/报告/` 固定完成报告目录
## STEP-000 状态
**完成并冻结。**
下一阶段:
**STEP-001:MapLibre Native 粒子接入点只读调查。**
STEP-001 暂不实现正式 RasterParticleLayer,先调查 Style / Source / Tile / RenderLayer / gfx / Shader / OpenGL / Vulkan / Metal 的最小接入点。