[Docs, Chore] (docs, tools, MobileGL, scripts, CONTRIBUTING.md, .gitignore): translate the documentation and use US spelling

This commit is contained in:
BZLZHH
2026-10-31 19:58:19 +08:00
parent 47892afddc
commit 4f50bedde0
512 changed files with 2955 additions and 2945 deletions
+21 -21
View File
@@ -1,39 +1,39 @@
# 构建、运行与测试
# Build, run and test
> 上手说明。文档导航见 [`../README.md`](../README.md);全部开关见 [`../design/09-build-switches-counters.md`](../design/09-build-switches-counters.md) 附 A。
> Getting started. For the documentation index see [`../README.md`](../README.md); for every switch see [`../design/09-build-switches-counters.md`](../design/09-build-switches-counters.md) appendix A.
## 三种构建
## Three builds
P13 起只有一种单进程形态:后端只从前端推来的记录取状态(记录臂),旧的「后端直接读前端」路径与 pull / push 两套构建一起删掉了(`MOBILEGL_PIPE_PUSH` 不再是 CMake 选项)。
Since P13 there is only one single-process shape: the backend takes its state solely from the records the frontend pushes (the record arm); the old "backend reads the frontend directly" path went away together with the pull / push builds (`MOBILEGL_PIPE_PUSH` is no longer a CMake option).
| 构建目录 | CMake | 用途 |
| Build directory | CMake | Purpose |
|---|---|---|
| `build-linux` | 默认 | 出货形态(FCL 内嵌库就是它):单进程,记录臂,不编 `MG_Remote` |
| `build-verify` | `-DMOBILEGL_PIPE_VERIFY=ON` | 每个 draw 把推来的状态与前端实际状态逐字段比对;慢,永不出货 |
| `build-split` | `-DMOBILEGL_BUILD_DISAGGREGATED=ON -DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ON` | 可以拆成两线程 / 两进程 / 两台机器;不设 `MOBILEGL_TRANSPORT` 时是同一记录臂的单进程对照 |
| `build-linux` | default | The shipped shape (the FCL embedded library is this one): single process, record arm, `MG_Remote` not built |
| `build-verify` | `-DMOBILEGL_PIPE_VERIFY=ON` | Every draw compares the pushed state field by field with the frontend's actual state; slow, never shipped |
| `build-split` | `-DMOBILEGL_BUILD_DISAGGREGATED=ON -DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ON` | Can split into two threads / two processes / two machines; with `MOBILEGL_TRANSPORT` unset it is the single-process control on the same record arm |
库由七个 OBJECT 模块拼成(`mg_util` / `mg_pipe` / `mg_backend` / `mg_frontend` / `mg_remote_transport` / `mg_remote_client` / `mg_remote_server`,按 `scripts/link_ratchet.py` 的 PARTITION 划分);split 构建另有 `MobileGL_server_linkcheck`,证明 server 那一半不带前端模块也能链接(剩下的前端引用是 link ratchet 基线里具名的债务)。
The library is assembled from seven OBJECT modules (`mg_util` / `mg_pipe` / `mg_backend` / `mg_frontend` / `mg_remote_transport` / `mg_remote_client` / `mg_remote_server`, partitioned by `scripts/link_ratchet.py`); the split build also has `MobileGL_server_linkcheck`, which proves the server half links without the frontend modules (the remaining frontend references are named debts in the link-ratchet baseline).
## 选拓扑
## Choosing a topology
split 构建在运行时用 `MOBILEGL_TRANSPORT` 选拓扑;**不设就是单进程(monolith)对照**:
The split build selects the topology at run time with `MOBILEGL_TRANSPORT`; **unset means the single-process (monolith) control**:
| `MOBILEGL_TRANSPORT` | 形态 |
| `MOBILEGL_TRANSPORT` | Shape |
|---|---|
| 不设 / `monolith` | 单线程直调 |
| `inproc` | 同一进程两个线程(CI 的主验收形态) |
| `spawn` | 两个进程;再用 `MOBILEGL_IPC_CONTROL`(`fork` / `unix:<path>` / `tcp://host:port`)与 `MOBILEGL_IPC_DATA`(`auto` / `shm` / `stream`)选控制面与数据面,跨机时还要 `MOBILEGL_IPC_TOKEN`(≥16 字节) |
| unset / `monolith` | Single thread, direct calls |
| `inproc` | Two threads in one process (the main CI acceptance shape) |
| `spawn` | Two processes; `MOBILEGL_IPC_CONTROL` (`fork` / `unix:<path>` / `tcp://host:port`) and `MOBILEGL_IPC_DATA` (`auto` / `shm` / `stream`) then choose the control and data planes; across machines also set `MOBILEGL_IPC_TOKEN` (at least 16 bytes) |
```text
MOBILEGL_TRANSPORT=inproc MOBILEGL_ITEST_REQUIRE_GPU=1 ctest --test-dir build-split -L integration-split --output-on-failure
ctest --test-dir build-split -L 'integration-(spawn|tcp)' --output-on-failure # 条目自带 spawn / tcp 环境与私有日志
ctest --test-dir build-split -L 'integration-(spawn|tcp)' --output-on-failure # the entries carry their own spawn / tcp environment and private logs
```
其他常用旋钮:`MOBILEGL_IPC_RUN_AHEAD`(默认 1,client 发完就走)、`MOBILEGL_IPC_STAGE_MB`(默认 32,其 1/4 是大块上传的分块预算)、`MOBILEGL_IPC_SURFACE=server`(使用 Android server 自己的窗口)、`MOBILEGL_PIPE_STATS=1`(边界计数器,日志里的 `MGPipe stats:` 行)。
Other common knobs: `MOBILEGL_IPC_RUN_AHEAD` (default 1, the client sends and moves on), `MOBILEGL_IPC_STAGE_MB` (default 32; a quarter of it is the chunk budget for large uploads), `MOBILEGL_IPC_SURFACE=server` (use the Android server's own window), `MOBILEGL_PIPE_STATS=1` (boundary counters, the `MGPipe stats:` lines in the log).
## Android
- 两份 APK flavour:单进程 / split(Gradle 属性 `mobilegl.buildDisaggregated`、`mobilegl.buildDisaggregatedInproc`;独立 plugin 构建默认 split,FCL 内嵌默认单进程)。split APK 同样要设 `MOBILEGL_TRANSPORT`,不设就是单进程对照。
- 设备侧 server 有两种形态:离屏的前台 Service(`MobileGLServerService`)与上屏的 `MobileGLDisplayActivity`;同一时刻只有一个。plugin 与 trace 两个 flavour 的 APK 都带(standalone 构建默认开 `mobilegl.buildDisaggregated`),入口是 APK 底部导航栏的 “Render Server” 页;plugin flavour 的这三个组件不导出,只有 trace 允许 adb 直接按组件名拉起。
- 电脑当 client、手机当 server 的跨机配置(起 server、设令牌、`adb forward` 备用路线)见 git 历史中的"两边怎么配"。
- 性能对比只用 Redmi `2f7cbe2e`,按 [`pin-verification-2026-09-07.md`](pin-verification-2026-09-07.md) 定频,reboot-clean、同热窗口、配对 A/B。P13 之后的性能工作以 `dev` 分支构建为「之前」基线(用户 2026-10-07)。
- Two APK flavors: single-process / split (Gradle properties `mobilegl.buildDisaggregated`, `mobilegl.buildDisaggregatedInproc`; a standalone plugin build defaults to split, the FCL embedding defaults to single-process). The split APK also needs `MOBILEGL_TRANSPORT`; unset means the single-process control.
- The on-device server has two shapes: an off-screen foreground Service (`MobileGLServerService`) and the on-screen `MobileGLDisplayActivity`; only one at a time. Both the plugin and trace flavor APKs carry them (standalone builds enable `mobilegl.buildDisaggregated` by default); the entry point is the "Render Server" page in the APK's bottom navigation. In the plugin flavor these three components are not exported; only the trace build allows adb to start them directly by component name.
- For the cross-machine setup with the computer as client and the phone as server (starting the server, setting the token, the `adb forward` fallback), see "configuring the two sides" in the phase notes (in git history).
- Performance comparisons use only the Redmi `2f7cbe2e`, pinned as described in the pin-verification record (in git history): reboot-clean, same thermal window, paired A/B. Performance work after P13 uses the `dev` build as its "before" baseline (user, 2026-10-07).
+11 -11
View File
@@ -1,14 +1,14 @@
# 代码地图
# Code map
> 参考。文档导航见 [`../README.md`](../README.md);目录布局与构建选项见 [`../design/09-build-switches-counters.md`](../design/09-build-switches-counters.md) §16。
> Reference. For the documentation index see [`../README.md`](../README.md); for the directory layout and build options see [`../design/09-build-switches-counters.md`](../design/09-build-switches-counters.md) §16.
| 路径 | 作用 |
| Path | Role |
|---|---|
| `MobileGL/MG_Pipe/` | 接口本身:调用目录 `PipeCalls.def` 与其他 `.def` 表、payload / 句柄 / 回调头、`PipeApply`、`PipeRoute`、`generated/*.inc`(生成物,提交进树) |
| `MobileGL/MG_Impl/Pipe/` | 前端:Tracker、`PipeFill`、`SlotAllocator`、`CsoCache`、`CompositeResolver`、`ResourceTracker`、各族 `*Emit.h` |
| `MobileGL/MG_Backend/MGPipe/` | `PipeInputs`:后端读的、被前端推来的状态块 |
| `MobileGL/MG_Remote/` | 拆分专用(仅 `MOBILEGL_BUILD_DISAGGREGATED`):`Protocol/`(控制面 schema)、`Transport/`(控制面 `ITransport` × 数据面 `ILink`)、`Wire/`(记录编解码)、`Client/`、`Server/`;各阶段的 wire 契约 `CONTRACT-*.md` |
| `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}` | 边界计数器(`MOBILEGL_PIPE_STATS=1`) |
| `MobileGL/MG_Test/Pipe/`、`MG_Test/Wire/`、`MG_IntegrationTest/Harness/*Peek` | 目录 / tracker / 发射器单元测试、wire 与 remote 单元测试、白盒断言 |
| `scripts/` | 生成器(`gen_pipe.py`、`gen_pipe_field_ownership.py`、`gen_pipe_dirty_surface.py`、`gen_protocol.py`)、门脚本(`symbol_report.py`、`check_include_closure.py`、`link_ratchet.py`、G5 保护区脚本、`check_doc_citations.py`)、`ci/` |
| `tools/trace_replay/`、`tools/device_bench/` | trace 回放(含 TCP 矩阵跑器)、设备定频与配对 A/B 工具 |
| `MobileGL/MG_Pipe/` | The interface itself: the call catalog `PipeCalls.def` and the other `.def` tables, the payload / handle / callback headers, `PipeApply`, `PipeRoute`, `generated/*.inc` (generated, committed to the tree) |
| `MobileGL/MG_Impl/Pipe/` | Frontend: Tracker, `PipeFill`, `SlotAllocator`, `CsoCache`, `CompositeResolver`, `ResourceTracker`, the per-family `*Emit.h` |
| `MobileGL/MG_Backend/MGPipe/` | `PipeInputs`: the state block the backend reads and the frontend pushes |
| `MobileGL/MG_Remote/` | Split-only (`MOBILEGL_BUILD_DISAGGREGATED`): `Protocol/` (control-plane schema), `Transport/` (control plane `ITransport` × data plane `ILink`), `Wire/` (record encoding and decoding), `Client/`, `Server/`; the per-phase wire contracts `CONTRACT-*.md` |
| `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}` | Boundary counters (`MOBILEGL_PIPE_STATS=1`) |
| `MobileGL/MG_Test/Pipe/`, `MG_Test/Wire/`, `MG_IntegrationTest/Harness/*Peek` | Catalog / tracker / emitter unit tests, wire and remote unit tests, white-box assertions |
| `scripts/` | Generators (`gen_pipe.py`, `gen_pipe_field_ownership.py`, `gen_pipe_dirty_surface.py`, `gen_protocol.py`), gate scripts (`symbol_report.py`, `check_include_closure.py`, `link_ratchet.py`, the G5 protected-region scripts, `check_doc_citations.py`), `ci/` |
| `tools/trace_replay/`, `tools/device_bench/` | Trace replay (including the TCP matrix runner), device clock pinning and paired A/B tooling |
+13 -13
View File
@@ -1,21 +1,21 @@
# 工程纪律与验证门
# Engineering discipline and verification gates
> 参考。验证门的设计见 [`../design/07-memory-readback-verification.md`](../design/07-memory-readback-verification.md) §13.2;各阶段实际跑门的结果在 `../notes/<阶段>/README.md`。
> Reference. The design of the verification gates is in [`../design/07-memory-readback-verification.md`](../design/07-memory-readback-verification.md) §13.2; the per-phase gate results are in the phase notes (in git history).
## 每个提交
## Every commit
- 默认 ALL target 必须完整构建;禁止提交热路径插桩(CI grep 门)。
- **每个门必须能因它存在的理由变红**:带阴性对照并真跑过一次红(R-16);公共 GL 看不见的改用白盒断言。
- 正确性门是硬门;**性能只记录、不设门**(用户 2026-09-08),但数字必须真的采到。专门的优化阶段排在路线图推完之后;P13 之后的性能轮以 `dev` 构建为基线(用户 2026-10-07)。
- **拆分不顺手修 `dev` 的 bug**:发现的 `dev` 侧缺陷记成独立条目、独立 PR。
- The default ALL target must build completely; instrumenting hot paths is not allowed in commits (a CI grep gate).
- **Every gate must be able to turn red for the reason it exists**: it has a negative control and has really run red once (R-16); what public GL cannot see is asserted white-box instead.
- Correctness gates are hard gates; **performance is recorded, not gated** (user, 2026-09-08), but the numbers must actually be measured. Dedicated optimization phases come after the roadmap; performance rounds after P13 use the `dev` build as the baseline (user, 2026-10-07).
- **Do not fix `dev` bugs along the way**: a defect found on the `dev` side becomes its own entry and its own PR.
## 每个阶段出口
## Every phase exit
- 跑一次五部分门:接口纯度、语义影子比对、行为 A/B、性能记录、覆盖与句柄纪律。
- 字节 / 名字级等式:**G5** 受保护区域逐字节一致;**G14** 测试名只增不删。**G1**(pull 构建的符号集与 `.text` 对基线恒等)与 **G2**(pull 与 push 的测试名集合相同)随 pull 构建在 P13 退役;接班的是:出货库零 `MG_Remote` 符号检查、skip 普查(新出现的跳过与消失的名字都要在基线里具名)、recorder 金标(`MG_Test/Pipe/RecorderGoldenTest.cpp`:固定 GL 调用序列的记录流逐条比对,改金标要在提交里说为什么),以及 link ratchet(server 一半对前端的引用只减不增,不允许 `# P13` 注解)。
- 性能判据是**逐线程 CPU 时间**;设备对比走 reboot-clean + 同热窗口配对 A/B,只用 Redmi `2f7cbe2e`([`pin-verification-2026-09-07.md`](pin-verification-2026-09-07.md));Windows 机器不是正确性门。
- 收官由异模型族审查一次,发现进入下一阶段首轮;实现方与审查方错开模型族;不过度验证(用户 2026-09-16,ID-66)。
- Run the five-part gate once: interface purity, semantic shadow comparison, behavioral A/B, performance record, coverage and handle discipline.
- Byte and name level equalities: **G5** protected regions are byte-identical; **G14** test names only grow. **G1** (the pull build's symbol set and `.text` identical to the baseline) and **G2** (the pull and push builds have the same set of test names) retired with the pull build in P13; their successors are: the zero-`MG_Remote`-symbol check on the shipped library, the skip census (newly appearing skips and disappearing names must be named in the baseline), the recorder golden (`MG_Test/Pipe/RecorderGoldenTest.cpp`: record streams from a fixed GL call sequence compared one by one; changing the golden requires saying why in the commit), and the link ratchet (the server half's references to the frontend only fall, and `# P13` annotations are not allowed).
- The performance criterion is **per-thread CPU time**; device comparisons use reboot-clean + same-thermal-window paired A/B, on the Redmi `2f7cbe2e` only (pin-verification record, in git history); a Windows machine is not a correctness gate.
- The close-out is reviewed once by a different model family; findings enter the first round of the next phase; implementers and reviewers use different model families; do not over-verify (user, 2026-09-16, ID-66).
## CTS
`gl44to46` 约 56,271 例,单独计价:逐阶段只跑该阶段可能影响的具名块;完整 caselist 只在架构边界与合并 `dev` 之前跑,放 CI 不放关键路径。
`gl44to46` has about 56,271 cases and is priced separately: each phase runs only the named blocks it can affect; the full caselist runs only at architecture boundaries and before merging into `dev`, in CI rather than on the critical path.
+46 -36
View File
@@ -1,49 +1,59 @@
# 在宿主 APK 中嵌入 split server
# Embedding the split server in a host APK
宿主应用可直接加载 `libMobileGL.so`,把自己持有的 `ANativeWindow` 交给 server。
窗口、输入和 Android Service 的生命周期由宿主 APK 管理;不需要安装 MobileGL plugin APK。
公共接口是 [`EmbeddedServer.h`](../../../MobileGL/MG_Remote/Server/EmbeddedServer.h),
只使用 C 类型,也可通过 `dlsym` 调用。构建必须开启 `MOBILEGL_BUILD_DISAGGREGATED`。
A host application can load `libMobileGL.so` directly and hand the server an `ANativeWindow` it owns.
The window, input and the Android Service lifecycle stay with the host APK; no MobileGL plugin APK is
needed. The public interface is
[`EmbeddedServer.h`](../../../MobileGL/MG_Remote/Server/EmbeddedServer.h), uses only C types, and can
also be called through `dlsym`. The build must enable `MOBILEGL_BUILD_DISAGGREGATED`.
## 有窗口的合成器服务
## Compositor service with a window
在加载库前设置 `MOBILEGL_IPC_ROLE=server`、`MOBILEGL_IPC_DIAL=no`,清除
`MOBILEGL_TRANSPORT`、`MOBILEGL_IPC_SERVER_PATH`、`MOBILEGL_IPC_RING_MB` 和
`MOBILEGL_IPC_STAGE_MB`。建议放在宿主 APK 的独立服务进程中,以免渲染故障结束 UI 进程。
Before loading the library, set `MOBILEGL_IPC_ROLE=server` and `MOBILEGL_IPC_DIAL=no`, and clear
`MOBILEGL_TRANSPORT`, `MOBILEGL_IPC_SERVER_PATH`, `MOBILEGL_IPC_RING_MB` and
`MOBILEGL_IPC_STAGE_MB`. Running in a separate service process of the host APK is recommended, so that
a rendering fault does not take down the UI process.
1. 调用 `mobilegl_server_display_install_android(request_geometry, user)`。
回调可为空;有回调时,它在 apply 线程运行,必须快速返回,把尺寸变更交给宿主线程。
2. 从宿主的 `Surface` 获取 `ANativeWindow`,调用
`mobilegl_server_display_attach_android(window, width, height)`。
server 独立持有引用,调用者随后释放自己的引用。同一窗口再次 attach 只更新尺寸。
3. 在服务线程调用 `mobilegl_server_serve_inprocess("@anland-mobilegl-compositor")`。
这会在当前进程接受一个 client 会话。AF_UNIX 控制连接用 `SCM_RIGHTS` 传递共享内存段,
数据通过 SHM 环传输。客户端设置 `MOBILEGL_TRANSPORT=spawn`、
`MOBILEGL_IPC_CONTROL=unix:@anland-mobilegl-compositor`、`MOBILEGL_IPC_DATA=shm` 和
`MOBILEGL_IPC_SURFACE=server`。
4. Surface 销毁时调用 `mobilegl_server_display_detach(3000)`。
返回值 `0/1/2/3` 分别为无窗口、直接释放、会话释放后完成、超时。
超时会保留引用,直到 apply 线程停止使用窗口;当前失窗会结束活动会话。
5. 服务停止时调用 `mobilegl_server_stop_inprocess()`,等待 serve 线程返回,再调用
`mobilegl_server_display_uninstall(3000)`。几何回调的 user 对象应至少活到此时。
1. Call `mobilegl_server_display_install_android(request_geometry, user)`.
The callback may be null; when present it runs on the apply thread, must return quickly, and hands
size changes to the host thread.
2. Take an `ANativeWindow` from the host's `Surface` and call
`mobilegl_server_display_attach_android(window, width, height)`.
The server holds its own reference; the caller then releases its own. Attaching the same window
again only updates the size.
3. On the service thread, call `mobilegl_server_serve_inprocess("@anland-mobilegl-compositor")`.
This accepts one client session in the current process. The AF_UNIX control connection passes the
shared-memory segment with `SCM_RIGHTS`, and data travels over a SHM ring. The client sets
`MOBILEGL_TRANSPORT=spawn`, `MOBILEGL_IPC_CONTROL=unix:@anland-mobilegl-compositor`,
`MOBILEGL_IPC_DATA=shm` and `MOBILEGL_IPC_SURFACE=server`.
4. When the Surface is destroyed, call `mobilegl_server_display_detach(3000)`.
The return values `0/1/2/3` mean no window, released directly, completed after the session
released it, and timed out. On timeout the reference is kept until the apply thread stops using the
window; losing the window currently ends the active session.
5. When the service stops, call `mobilegl_server_stop_inprocess()`, wait for the serve thread to
return, then call `mobilegl_server_display_uninstall(3000)`. The geometry callback's user object
must live at least until then.
`width/height` 为零时,Android attach 从 `ANativeWindow` 查询尺寸。几何回调收到正尺寸表示
请求固定缓冲尺寸,收到 `0/0` 表示恢复宿主布局尺寸;宿主应通过后续 attach 报告实际结果。
安装、attach、detach 和 uninstall 由宿主串行调用。库拒绝替换已安装的 display 或尚未结束
的旧窗口租约,避免晚到的释放使用另一组引用回调。
When `width/height` are zero, the Android attach queries the size from the `ANativeWindow`. A positive
size in the geometry callback requests fixed buffer dimensions; `0/0` means restore the host's layout
size, and the host reports the actual result through a later attach. Install, attach, detach and
uninstall are serialized by the host. The library refuses to replace an installed display or an old
window lease that has not ended, so that a late release cannot use another set of reference callbacks.
## 并发的离屏应用服务
## Concurrent off-screen application service
一个进程仍只有一套 backend/GL 状态。有窗口的服务只接一个合成器;其他 EGL client 可连接
宿主 APK 打包的 `libMobileGLServer.so` 可执行文件,由另一个服务进程负责启动和结束:
A process still has only one set of backend / GL state. A service with a window accepts a single
compositor; other EGL clients can connect to the `libMobileGLServer.so` executable packaged by the
host APK, which another service process starts and stops:
```text
<nativeLibraryDir>/libMobileGLServer.so @anland-mobilegl --serve --max-sessions 16
```
`--max-sessions` 是活动会话上限,接受 `1..64`,默认仍为 `1`。大于 `1` 只适用于
AF_UNIX 的 `--serve` 离屏 supervisor。每个 client 单独 fork worker,拥有独立 backend,
共享内存与其他会话隔离;worker 退出后归还名额,supervisor 结束时所有 worker 一起结束。
这些 worker 没有 display,客户端应清除 `MOBILEGL_IPC_SURFACE`,由客户端 WSI 提交窗口图像。
`--max-sessions` is the limit on active sessions; it accepts `1..64` and still defaults to `1`. Values
above `1` apply only to the AF_UNIX `--serve` off-screen supervisor. Each client forks its own worker
with an independent backend, isolated from other sessions in shared memory; a worker returning frees
its slot, and all workers end when the supervisor ends. These workers have no display; the client
should clear `MOBILEGL_IPC_SURFACE` and submit window images through its own WSI.
进程隔离解决多个应用同时连接的问题;同一应用中的真正多 context/share-group 支持仍需另行实现。
Process isolation solves multiple applications connecting at the same time; true multi-context /
share-group support inside one application still needs separate work.
+20 -20
View File
@@ -1,23 +1,23 @@
# 术语
# Terms
> 参考。文档导航见 [`../README.md`](../README.md)。
> Reference. For the documentation index see [`../README.md`](../README.md).
| 术语 | 意思 |
| Term | Meaning |
|---|---|
| 前端 / 后端 | 前端 = `MG_State` + `MG_Impl`,处理应用的 GL 调用;后端 = `MG_Backend`,真正调用驱动 |
| Espryt / Magma | 两个后端:Espryt 走 OpenGL ES(DirectGLES),Magma 走 Vulkan(DirectVulkan) |
| client / server | 拆分后的前端角色 / 后端角色;可以是两个线程、两个进程或两台机器 |
| monolith / inproc / spawn | 三种拓扑:单线程直调 / 同进程两线程 / 两个进程(可跨机) |
| pull / push | 后端自己去读前端状态(旧做法)/ 前端把状态推给后端(MGPipe) |
| verb | 会让后端真正做事的命令:draw、dispatch、clear、blit、回读、XFB、query、纹理操作。状态只在 verb 之前推送 |
| 句柄 `{slot, gen}` | 对象的身份:client 分配的槽号 + 复用代数,server 从不回传 |
| CSO | 常量状态对象(渲染状态、顶点格式、sampler、sampler view、shader):client 按内容去重,server 按句柄缓存 |
| 控制面 / 数据面 | 握手与罕见控制消息走的连接 / 命令记录与批量数据走的通道;两者可分别选(共享内存或字节流、本机或 TCP) |
| lockstep / run-ahead | client 每条命令都等 server 做完 / client 发完就走,只有需要答案的命令才等 |
| barrier tax | 拆成两线程后多出来的逐线程 CPU 代价(split − push) |
| device-lost | server 崩溃或断线后 client 进入的状态:GL 调用变空操作、交换缓冲返回"上下文丢失",而不是崩溃或卡死 |
| class A / B / C | 后端函数表的槽:A 本地回答,B 发成记录,C 还没迁移、按名拒绝 |
| Track V / Track H | 值类读点的迁移(整块数据过线)/ 对象类读点的迁移(对象指针换成句柄) |
| G1 / G2 / G5 / G14 | 验证门:单进程构建二进制逐字节不变 / pull 与 push 测试名集合相同 / 受保护的后端函数逐字节不变 / 测试名只增不删 |
| red-once(R-16) | 每个门都必须真的跑红过一次,证明它能因为它要抓的问题而失败 |
| `MGGen` | server 私有的"我重建了驱动对象"纪元,永不过线;与句柄代数严格分开 |
| frontend / backend | frontend = `MG_State` + `MG_Impl`, handling the application's GL calls; backend = `MG_Backend`, calling the driver for real |
| Espryt / Magma | The two backends: Espryt goes through OpenGL ES (DirectGLES), Magma through Vulkan (DirectVulkan) |
| client / server | The frontend role / backend role after the split; they can be two threads, two processes or two machines |
| monolith / inproc / spawn | The three topologies: single thread direct calls / two threads in one process / two processes (optionally across machines) |
| pull / push | The backend reads the frontend's state itself (the old way) / the frontend pushes state to the backend (MGPipe) |
| verb | A command that makes the backend actually do work: draw, dispatch, clear, blit, readback, XFB, query, texture operations. State is pushed only before a verb |
| handle `{slot, gen}` | An object's identity: a client-allocated slot plus the reuse generation; the server never sends it back |
| CSO | Constant state object (render state, vertex format, sampler, sampler view, shader): the client deduplicates by content, the server caches by handle |
| control plane / data plane | The connection carrying the handshake and rare control messages / the channel carrying command records and bulk data; each can choose shared memory or a byte stream, local or TCP |
| lockstep / run-ahead | The client waits for the server after every command / the client sends and moves on, waiting only for commands that need an answer |
| barrier tax | The extra per-thread CPU cost of splitting into two threads (split − push) |
| device-lost | The state the client enters after the server crashes or disconnects: GL calls become no-ops and swap buffers returns "context lost" instead of crashing or hanging |
| class A / B / C | Slots in the backend function table: A answers locally, B becomes a record, C is not migrated yet and is refused by name |
| Track V / Track H | Migration of value-class read points (a whole block crosses the wire) / migration of object-class read points (object pointers become handles) |
| G1 / G2 / G5 / G14 | Verification gates: single-process build binary byte-identical / pull and push have the same test-name set / protected backend functions byte-identical / test names only grow |
| red-once (R-16) | Every gate must really have run red once, proving it can fail for the problem it is meant to catch |
| `MGGen` | The server's private "I rebuilt the driver object" epoch; it never crosses the wire and is kept strictly separate from the handle generation |