Files
MobileGL/docs/Disaggregated/notes/p3a/scout-espryt-vao.md
T
swung0x48 aba329cc53 [Docs] (Disaggregated): P6's plan and contract draft; the working notes move from a local directory into the repository
Two things land together: the plan and contract draft P6 needs before it starts, and the
working notes that until now existed on exactly one machine.

1. P6's plan and contract draft (neither started; not one line of code)

     docs/Disaggregated/P6-SPAWN-PLAN.md      the package plan
     docs/Disaggregated/P6-CONTRACT-DRAFT.md  the contract draft (moves to
                                              MG_Remote/CONTRACT-P6.md when c6 lands)

   The three findings that mattered, all written into the documents:

   a. P6 is SMALLER than its roadmap cell suggests. The transport primitives are already in
      the tree and already tested: SocketDoorbell including hangup detection and the two
      lost-wakeup fences (Doorbell.cpp:211-360, four cases in FdPassingTest), SCM_RIGHTS fd
      passing, ShmSegment::Adopt, and the SurfaceOp / WindowKind schema already defined in
      protocol.fbs. inproc uses a real second shm mapping rather than an alias, and
      SessionRings.h:22-28 says that was done so today is not the first time it runs. P6 is
      assembly plus a control plane plus a process, not "write a socket transport".

   b. The evidence for "P6 is only a transport swap" has EXPIRED. It was bought by P5c, whose
      audit found 59 direct memory accesses in a tree that already looked clean. P5e changed
      the tree again. So the first package, a6, is a read-only audit that writes no code, and
      every contract row that depends on it is marked PENDING a6 rather than decided in
      advance.

   c. P6 does not get a game running on the phone. ANativeWindow* is meaningless in the child,
      and protocol.fbs:186-196's own comment says Android transfers the window out of band -
      that band is P12. P6 lands pbuffer / surfaceless / offscreen, which is what HeadlessGL,
      the split-equivalent lane and trace replay need, and which is exactly what P6's own exit
      gate measures. A real window reaching the server is a named refusal. This gets its own
      section because "P6 is done" would otherwise read as "the game runs now".

   The contract adds rule G: a role may not name a process-local handle. It extends P5c's
   rule E (a role may not name the other role's memory) from memory to identity - EGLDisplay /
   EGLSurface / EGLContext / ANativeWindow* / fd number / pid / mapped address either cross as
   a token this contract defines or they do not cross, and a descriptor crosses only through
   SCM_RIGHTS, where the kernel renumbers it.

   What P5e left for P6 gets its own section. The latch semantics are already designed
   (ARCHITECTURE.md:504) and are copied unchanged. What is new is that after run-ahead the
   client no longer waits while the peer process can DIE: the client holds records that were
   published and will never be applied, and Android's freezer suspends the child without
   closing anything. So slow and dead must be distinguishable WITHOUT a timeout threshold.
   That is P6's only new design; everything else is carriage. It shares a predicate with E1's
   outstanding re-specification (ID-122), and the two should be designed together.

   Two gates carried over from P5e's lessons: G2 requires integration-spawn's test-name set to
   match integration-split's name for name, because a differing set means the lane is quietly
   running less; and the arm-proof gate requires every entry to record the child pid and
   transport=spawn in its OWN private log - ID-124 established that this kind of false green
   really happens, and a spawn lane that actually ran monolith would pass every other gate.
   S2's shape must be settled before it is written, and the document says why: E1 is the
   cautionary case.

2. The working notes move into the repository (docs/Disaggregated/notes/, 415 .md files)

   ROADMAP / CURRENT_STAGE_PROGRESS / MEASUREMENTS cite ruling numbers, audit line numbers and
   the provenance of gate figures from ~/w7/notes/, a directory that exists on one machine and
   is under no version control. A record cited hundreds of times that lives only locally is not
   a record, so it moves in whole, with its directory structure intact.

   Only .md moves. Scripts, run logs, census and gate result JSON, patches, APKs and nm dumps
   stay where they are: they are evidence DATA rather than documents - large, regenerated per
   run, and mostly carrying absolute paths and device serials that mean something only on the
   machine that produced them. The mapping and this split are written in
   docs/Disaggregated/notes/README.md.

   Two exceptions are recorded there too: P6's BRIEF has been promoted to a first-class
   document and keeps no copy under notes/, so the two cannot drift apart; and recovered/ holds
   material salvaged from failed workflow runs, which may duplicate the like-named phase
   directories and is kept because a few of those were the only complete version at the time.

   CI's citation lint takes docs/Disaggregated/*.md only (non-recursive), and notes/ is
   deliberately outside it: those notes' file:line citations were written against their own
   code heads, and resolving them against today's HEAD would fail wholesale - which is not an
   error, it is their correct state as a historical record. To check one, use the revision it
   declares (--rev).

3. Inconsistencies fixed in passing

   - README.md's status line still said P5e was in progress while the stage table already said
     closed.
   - CURRENT_STAGE_PROGRESS's next-step item 1 still listed the exit gate as pending, though
     (a) and (b) were run in the previous commit; rewritten to closed plus the one item that
     actually remains (E1).
   - ROADMAP's P6 row still had the pre-phase plan in three of its cells; it now carries the
     package order, the scope boundary and the two new gates.

Checked with check_doc_citations.py: 125 citations across docs/Disaggregated/*.md, 0 problems.
2026-09-18 23:31:39 -04:00

596 lines
42 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# P3a scout — Espryt's vertex-array surface
Worktree: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`, branch `feat/disaggregated`.
Every line number below was opened. Paths are repo-relative to `MobileGL/` unless they start with `docs/`.
---
## 0. One-paragraph shape
Espryt has **no vertex-elements CSO**. It has a **per-VAO twin object** (`BackendVertexArrayObject`) that owns
one driver VAO name plus per-attribute scratch buffers, and that twin re-emits `glVertexAttribPointer` /
`glEnable|DisableVertexAttribArray` / `glVertexAttribDivisor` / `glBindBuffer(GL_ELEMENT_ARRAY_BUFFER)`
**into the driver VAO** whenever a version compare says the frontend moved. So the three things P3a wants to
separate — vertex *elements* (format), vertex *buffers* (which store + offset + stride), and the *index* buffer —
are today one fused emit inside `BackendVertexArrayObject::SyncToBackend`, gated by one `Uint32` config version
plus one `Uint16` index-slot version plus one global buffer-id generation. That fusion is the P3a work.
---
## 1. How a draw resolves its vertex input today
### 1.1 The draw prologue
`PrepareForDraw` — `MG_Backend/DirectGLES/DirectGLES.cpp:3163-3231` (decl `Managers.h:105`).
Order of the vertex-relevant steps:
| line | step |
|---|---|
| `DirectGLES.cpp:3169` | `const auto& currentVAO = MGB_CTX->GetBoundVertexArray();` |
| `DirectGLES.cpp:3170-3171` | `vaoTwin = VertexArrayImpl::ResolveVaoTwin(currentVAO)` — **one** twin resolve serves the whole draw |
| `DirectGLES.cpp:3176` | early `vaoConfigVersion = currentVAO->GetConfigVersion()` (deliberate cold-line prefetch) |
| `DirectGLES.cpp:3193-3195` | `BufferImpl::SyncNeccessaryBuffers(currentVAO, vaoTwin, vaoConfigVersion, syncBit & IndexBuffer, syncBit & IndirectBuffer)` |
| `DirectGLES.cpp:3196` | `VertexArrayImpl::SyncCurrentVAO(currentVAO, vaoTwin)` → `vaoTwin->SyncToBackend(...)` |
| `DirectGLES.cpp:3212-3220` | `vaoTwin->Bind()`, else `BindBackendVAOId(0)` |
| `DirectGLES.cpp:3222` | `VertexArrayImpl::SyncCurrentVertexAttributeValues(vaoTwin, currentProgram)` |
`DrawSyncBit` (`Managers.h:74-83`): `None / IndexBuffer(1) / IndirectBuffer(2) / Instancing(4)`.
Note the client-array upload is **not** here — it runs *after* `PrepareForDraw` at the draw entry point (§1.6).
### 1.2 `ResolveVaoTwin` — `DirectGLES.cpp:1236-1268`
Two arms:
* `MOBILEGL_PIPE_PUSH` + `EsprytSlotTablesEnabled()` (`DirectGLES.cpp:1240-1252`): `g_backendVertexArrayObjects.Find(vao.get())`
→ `GetOrCreate(vao)` → `MakeShared<BackendVertexArrayObject>()`. **No lookup memo on this arm.**
* legacy (`DirectGLES.cpp:1254-1266`): `g_vaoTwinLookupMemo.Lookup(vao)` (a 4096-slot Fibonacci-hashed direct-map,
declared `DirectGLES.cpp:128-129`, class at `DirectGLES.cpp:~80-121`) then the address-keyed registry.
`SyncCurrentVAO` — `DirectGLES.cpp:1270-1283`; it still calls `g_backendVertexArrayObjects.CollectGarbageIfNeeded()`
at `1275` (legacy arm only — the slot arm has no GC, see `SlotTables.h:37-48`).
### 1.3 `SyncNeccessaryBuffers` — `DirectGLES.cpp:572-707`
Resolves the *stores* the draw fetches through. It is the `ResolvedDrawBuffers` memo host.
* `DirectGLES.cpp:601` `const Uint64 bufferEpoch = CurrentBufferMutationEpoch();` (decl `Managers.h:588`, doc `Managers.h:548-587`)
* `DirectGLES.cpp:602-603` `auto* memo = vaoTwin ? &vaoTwin->GetResolvedDrawBuffersMemo() : nullptr;`
* **hit path** `605-621`: memo valid && `configVersion` matches → if `vboCleanEpoch != bufferEpoch`, re-probe each
distinct entry with `IsBufferDrawClean(entry.frontend, entry.resource)` (`Managers.h:675`), and repair only the dirty
ones via `EnsureBufferResource(currentVAOObject->GetAttribute(entry.attribIndex).Buffer)` (`DirectGLES.cpp:613-614`).
Stamp `vboCleanEpoch = allClean ? bufferEpoch : 0` (`619`).
* **miss path** `622-664`: full walk over `GetAllAttributes()` (`629`), skip `!Enabled` / null `Buffer`, dedupe by
frontend `BufferObject*` into a `MAX_VERTEX_ATTRIBS` scratch (`626-627, 634-642`), `EnsureBufferResource` each
(`644`), rebuild memo entries (`645-651`), `memo->configVersion = configVersion; memo->valid = true; vboCleanEpoch = 0` (`654-660`).
* **IBO** `666-694`: `currentVAOObject->GetIndexBufferBindingSlot().GetBoundObject()` (`669`), matched on
**bound-object identity** `memo->iboFrontend == possibleIBO.get()` plus `iboCleanEpoch` (`673-687`) — explicitly not
covered by the config version.
* **indirect** `696-703`: binds `GL_DRAW_INDIRECT_BUFFER` from `MGB_CTX->GetBufferBindingSlot(BufferTarget::DrawIndirect)`.
* tail `705-706`: `SyncBufferBindingPoints(ShaderStorage, GL_SHADER_STORAGE_BUFFER)` + `MarkShaderStorageBuffersGpuWritten()`.
UBO binding points are deliberately **not** synced here (comment `696-704`) — the program rebind does it.
### 1.4 `ResolvedDrawBuffers` — `Managers.h:833-869`
```
struct Entry { BufferObject* frontend; GLESBufferResource* resource; Uint8 attribIndex; } // Managers.h:849-853
Bool valid; Uint32 configVersion; Uint count; Array<Entry, MAX_VERTEX_ATTRIBS> entries; // 854-857
BufferObject* iboFrontend; GLESBufferResource* iboResource; // 858-859
Uint64 vboCleanEpoch; Uint64 iboCleanEpoch; // 866-867
```
Accessor `GetResolvedDrawBuffersMemo()` `Managers.h:870`; member `m_resolvedDrawBuffers` `Managers.h:911`.
Key: **VAO config version** for the VBO half, **bound-object identity + epoch** for the IBO half.
`PendingAttribValueMask` — `Managers.h:872-887` (`{valid, configVersion, activeMask, pendingMask}`), accessor
`Managers.h:884`, member `Managers.h:912`; consumed by `SyncCurrentVertexAttributeValues`.
### 1.5 `BackendVertexArrayObject::SyncToBackend` — `Managers.cpp:2419-2647`
This is the function P3a converts into `create/bind_vertex_elements_state` + `set_vertex_buffers` + `set_index_buffer`.
Gate (`Managers.cpp:2437-2470`):
```
currentConfigVersion = stateVAOObject->GetConfigVersion(); // 2437
currentIndexBufferVersion = ...GetIndexBufferBindingSlot().GetVersion(); // Uint16 // 2438
currentBufferIdGeneration = BufferImpl::g_bufferBackendIdGeneration; // 2446
bufferIdsRemitted = m_syncedBufferIdGeneration != currentBufferIdGeneration; // 2447
attributesDirty = bufferIdsRemitted || !m_hasSyncedConfigVersion || version mismatch // 2448-2449
indexBufferDirty = bufferIdsRemitted || version mismatch || OBJECT-IDENTITY mismatch // 2452-2456
baseInstanceDirty= m_syncedFetchBaseInstance != g_pendingFetchBaseInstance // 2462-2463
emitAttributes = attributesDirty || baseInstanceDirty || m_hasConvertedFloat64Attribute// 2467
if (!emitAttributes && !indexBufferDirty) return; // 2468-2470
```
Per-attribute walk `2477-2617` over `GetAllAttributeVersions()` / `GetAllAttributes()`:
* `SwitchVersion` → `glEnable/DisableVertexAttribArray` (`2489-2496`)
* `FormatVersion` / `BufferVersion` → format + buffer (`2498-2502`)
* **fp64 narrowing** `2521-2542`: `attrib.IsLong || attrib.Type == Float64` → `SyncFloat64AttributeAsFloat32`; on
failure the array is **disabled** (Adreno SIGSEGV note `2495-2520`, `KHR-GL43.vertex_attrib_binding.basic-input-case4`)
* **zero-stride** `2545-2560`: `attrib.Stride == 0 && HasVertexBindingApi()` → `SyncZeroStrideAttribute` (binding-point API)
* `BindAttributeBuffer` (`Managers.cpp:2330-2346`) then `glVertexAttribPointer` / `glVertexAttribIPointer` at
`fetchOffset = attrib.Offset + BaseInstanceByteShift(attrib, fetchBaseInstance)` (`2586-2600`)
* **BGRA refusal probe** `2568-2582` + `2602-2611`: `glGetError` drain, attempt, re-check, disable on refusal
(`basic-input-case5`). Deliberately the only format that pays a `glGetError` round trip.
* `glVertexAttribDivisor` on `needsSyncFormat` (`2613-2615`)
Index half `2618-2638`: `EnsureBufferResource(indexBufferBinding)` → `BufferImpl::BindBufferId(GL_ELEMENT_ARRAY_BUFFER, id)`,
else `glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, 0)`; stamps `m_syncedIndexBufferVersion` + `m_syncedIndexBufferObject` (`2634-2637`).
Stamps at `2640-2646`.
Twin private state — `Managers.h:906-953`:
```
m_resolvedDrawBuffers, m_pendingAttribValueMask // 911-912
Uint m_backendVAOId // 913
Array<Uint,32> m_clientAttributeBufferIds // 914
Array<Uint,32> m_convertedAttributeBufferIds // 918
Array<ConvertedFloat64Stream,32> m_convertedAttributeStreams // 919-920
Bool m_hasConvertedFloat64Attribute // 924
Uint16 m_syncedIndexBufferVersion // 927
const BufferObject* m_syncedIndexBufferObject (raw, never dereferenced) // 931
Bool m_hasSyncedConfigVersion; Uint32 m_syncedConfigVersion // 937-938
Array<VertexAttributeVersion,32> m_syncedAttributeVersions // 939-940
Uint32 m_syncedFetchBaseInstance // 946
Uint64 m_syncedBufferIdGeneration // 952
```
ctor/dtor `Managers.cpp:2259-2296` (`glGenVertexArrays`; dtor deletes the VAO name and both scratch-buffer arrays,
early-returns under `InProcessTeardown()`).
`Bind()` `Managers.cpp:2323-2327` → `BindBackendVAOId` shadow (`Managers.cpp:2303-2312`), `InvalidateVAOBindingCache`
`2314-2316`, `NoteVAOIdDeleted` `2318-2321`.
### 1.6 Client-array upload path
`BackendVertexArrayObject::SyncClientSideAttributesForDrawArrays(vao, first, count)` — `Managers.cpp:2651-2755`
(decl `Managers.h:831-832`). Selects `attrib.Enabled && !attrib.Buffer` (`2662-2664`), then:
* fp64 client array `2670-2715`: `NarrowDoubleStreamToFloat32` → `glBufferData(GL_STREAM_DRAW)` into
`m_clientAttributeBufferIds[attribIndex]`, counts `PipeStats::ByteClass::StageVertexClient` (`2701-2704`)
* ordinary `2717-2752`: `uploadSize = (first + count - 1) * stride + elementSize` (`2726`) — this is the exact
formula ARCHITECTURE.md 5.7 assigns to the client; `glBufferData` then `glVertexAttribPointer(..., nullptr)`;
bytes counted at `2740-2743`.
Call sites (both **after** `PrepareForDraw`, both re-`Find` the twin instead of reusing the resolve):
* `DrawArrays` — `DirectGLES.cpp:4805-4821` (`Find` at `4814`, call at `4817`)
* `MultiDrawArrays` — `DirectGLES.cpp:4837-4866`, per sub-draw range (`Find` at `4855`, call at `4857`)
There is **no** client-array upload on any `DrawElements*` path — `SyncClientSideAttributesForDrawArrays` is the only
uploader and only `DrawArrays`/`MultiDrawArrays` call it.
### 1.7 fp64 vertex narrowing
`SyncFloat64AttributeAsFloat32` — `Managers.cpp:2757-2874` (decl `Managers.h:889-892`).
* `bufferObject->SyncGpuWrites()` before reading the shadow (`2776`); `MappedData()` / `GetSize()` (`2777-2778`)
* stride-0 = "never advances" → exactly one element converted (`2793-2796`)
* baseInstance folds into `firstElement` (`2800-2806`)
* memo `ConvertedFloat64Stream` keyed on `{sourceLifetimeId, sourceChangeSerial, sourceOffset, sourceStride,
componentCount, elementCount}` and **never trusted for a persistently mapped buffer** (`2812-2820`)
* emits `StageVertexClient` bytes (`2839-2845`)
* stride-0 output requires the binding API (`2857-2866`), else `glVertexAttribPointer` with `normalized = GL_FALSE`
deliberately (`2869-2873`, `basic-input-case5`)
### 1.8 `SyncCurrentVertexAttributeValues` — `DirectGLES.cpp:1291-1348`
Feeds `glVertexAttrib4fv / I4iv / I4uiv` for program-active locations with **no enabled array**, from
`MGB_CTX->GetCurrentVertexAttribute(location)` (`1329`). Memo keyed on `{VAO config version, program active-attrib mask}`
(`1311-1323`). This is the read that `set_vertex_attrib_defaults` (already landed at P2) supplies.
### 1.9 Complete list of Espryt reads of frontend vertex state
Every `MG_Backend/DirectGLES` read of `VertexArrayObject` / `VertexAttribute` / `VertexBufferBindingPoint`:
| file:line | read |
|---|---|
| `DirectGLES.cpp:128-129` | `TwinLookupMemo<VertexArrayObject, BackendVertexArrayObject, 12>` (legacy arm) |
| `DirectGLES.cpp:572-573` | `SyncNeccessaryBuffers(SharedPtr<VertexArrayObject>&, BackendVertexArrayObject*, ...)` |
| `DirectGLES.cpp:613-614` | `GetAttribute(entry.attribIndex).Buffer` |
| `DirectGLES.cpp:626-627` | `MAX_VERTEX_ATTRIBS` dedupe scratch |
| `DirectGLES.cpp:629` | `GetAllAttributes()` |
| `DirectGLES.cpp:669` | `GetIndexBufferBindingSlot().GetBoundObject()` |
| `DirectGLES.cpp:1236-1266` | `ResolveVaoTwin` |
| `DirectGLES.cpp:1270-1283` | `SyncCurrentVAO` |
| `DirectGLES.cpp:1291-1348` | `SyncCurrentVertexAttributeValues` (`1312` config version, `1317` `GetAttribute(location).Enabled`) |
| `DirectGLES.cpp:3169-3176` | `GetBoundVertexArray()`, `GetConfigVersion()` |
| `DirectGLES.cpp:4624` | `BoundElementArrayBuffer()` → `GetIndexBufferBindingSlot().GetBoundObject()` (restart path) |
| `DirectGLES.cpp:4814`, `4855` | `g_backendVertexArrayObjects.Find(currentVAO.get())` (client arrays) |
| `Managers.cpp:210` | death-notice case `MGPipeKind::VertexElementsCso` |
| `Managers.cpp:2330` | `BindAttributeBuffer(const VertexAttribute&)` |
| `Managers.cpp:2377` | `BaseInstanceByteShift(const VertexAttribute&, Uint32)` |
| `Managers.cpp:2387` | `SyncZeroStrideAttribute(Uint, const VertexAttribute&)` |
| `Managers.cpp:2437-2438`, `2453` | config version, index-slot version, index bound object |
| `Managers.cpp:2477-2478` | `GetAllAttributeVersions()`, `GetAllAttributes()` |
| `Managers.cpp:2619` | index bound object (emit) |
| `Managers.cpp:2659` | `GetAllAttributes()` (client arrays) |
| `Managers.cpp:2758` | `SyncFloat64AttributeAsFloat32(..., const VertexAttribute&, ...)` |
| `Managers.cpp:2877-2878` | `TwinRegistry<VertexArrayObject, BackendVertexArrayObject, MGPipeKind::VertexElementsCso> g_backendVertexArrayObjects` |
| `Managers.h:826-955` | class + registry decl |
| `BackendObject_DirectGLES.cpp:1391` | `VertexArrayObject::MAX_VERTEX_ATTRIBS` clamp for the advertised limit |
| `MultiDraw.cpp:98` | `GetIndexBufferBindingSlot().GetBoundObject()` |
**Finding.** Neither Espryt nor Magma reads `VertexBufferBindingPoint`, `GetAttributeBindingIndex` or
`GetAttributeRelativeOffset` — grep over `MG_Backend/DirectGLES` and `MG_Backend/DirectVulkan` returns nothing.
The frontend resolves the binding model eagerly into the flat `VertexAttribute` view
(`VertexArrayObject.cpp:229-260` `ResolveAttributeFromBinding`, `262-269` `ResolveAttributesForBinding`,
`146-181` `MirrorPointerIntoBinding`). See §4.2 for why this matters to the "two views" requirement.
---
## 2. After P2's Espryt 0b slot tables
### 2.1 Which kind holds the VAO twin
`MG_Backend/DirectGLES/Managers.cpp:2877-2878`:
```
TwinRegistry<MG_State::GLState::VertexArrayObject, BackendVertexArrayObject,
MG_Pipe::MGPipeKind::VertexElementsCso> g_backendVertexArrayObjects;
```
decl `Managers.h:954-955`. So **`MGPipeKind::VertexElementsCso` (`MG_Pipe/MGPipeHandles.h:31`) is today the slot
space of the per-VAO twin**, one slot per live frontend `VertexArrayObject`, minted off `GetLifetimeId()`.
`TwinRegistry` is an alias that swallows the kind in a pull build: `Managers.h:543-549`; the class carries
`BackendSlotTable<StateObject, BackendObject, kKind> m_slotTable` only under `MOBILEGL_PIPE_PUSH`
(`Managers.h:299-305`, macro `MGB_TWIN_KIND_PARAM` `Managers.h:293-297`).
`BackendSlotTable` — `MG_Backend/DirectGLES/SlotTables.h:139-...`:
`GetOrCreate` `SlotTables.h:207-243` (`MGPipeSlots().Acquire(kKind, stateObj->GetLifetimeId())` at `225-226`, gen
mismatch resets the twin at `229-233`); `Find` `246-253`; `FindByHandle` `255-262`; `HandleOf` `272-281`;
`OnFrontendObjectDestroyed` (static, per-kind, walks every holder) `295-310`; `ForEachLive` `326-345`;
`ReleaseTwinAt` `352-374`; one-entry lifetimeId→handle memo `m_memoLifetimeId/m_memoHandle` `429-431`
(the comment at `407-428` names `ResolveVaoTwin` as one of the two callers the single-entry memo *does* help).
Arm selection: `ClassifyEsprytSlotArm` (`SlotTables.h:86-98`, impl `Managers.cpp:224-...`),
`EsprytSlotTablesEnabled()` inline latch `SlotTables.h:131-134`,
subsystem bit `kMGPipeSubsystemEsprytSlots = 1ull << 5` (`MG_Pipe/MGPipe.h:77`).
### 2.2 Death announcement
`VertexArrayObject::~VertexArrayObject()` — `MG_State/GLState/VertexArrayState/VertexArrayObject.cpp:42-54`,
raising `NotifyStateObjectDestroyed(MG_Pipe::MGPipeKind::VertexElementsCso, m_lifetimeId)` (`53`).
Declared only under push (`VertexArrayObject.h:26-31`, so the pull build keeps its implicit destructor for G1).
Consumer: `OnFrontendStateObjectDestroyed` — `Managers.cpp:191-217`, VAO case at `209-211`
(`g_backendVertexArrayObjects.DestroyByLifetimeId(lifetimeId)`); ops table `Managers.cpp:219-221`.
### 2.3 Recorded debt P3a inherits
`SlotTables.h:68-78` — the header is under `MG_Backend/` yet it **mints** handles off a frontend
`SharedPtr`'s `GetLifetimeId()`, which `MGPipeHandles.h:13-16` forbids ("minted by the CLIENT"). Its own comment says
the minting and the lifetimeId→handle resolution belong on the client and the backend should receive the handle in
the verb payload — i.e. exactly what P3a is supposed to do for the VAO kind. `check_include_closure.py` does not
probe `MG_Backend` headers, so nothing catches this automatically.
---
## 3. Index-buffer handling (and the P8 host-mirror hooks)
### 3.1 The element-array binding
Owned by the VAO twin (§1.5, `Managers.cpp:2618-2638`). Its freshness key is
`{ BindingSlot::GetVersion() (Uint16, wrapping), bound-object raw pointer identity }` —
`Managers.h:922-931` explains why identity joins the version (`BindingSlot` lives at `MG_Util/Types.h:181-204`,
`m_version` is a `Uint16` bumped only on a real change, `Bind()` at `189-195`, `GetVersion()` at `198`).
`SetIndexBuffer` being independent of the VAO config version (D5, `docs/Disaggregated/ARCHITECTURE.md:99`) matches
what the code already does — the index slot is explicitly *not* covered by `m_configVersion`.
**Trap that any P3a re-emit must preserve:** two paths temporarily swap the element-array binding and must restore
the *exact* previous GL name, because the twin memoised that it already synced it:
* `ScopedRestartIndexSubstitution::~ScopedRestartIndexSubstitution` — `DirectGLES.cpp:4788-4791`
(previous name captured at `4776` via `BoundElementArrayBufferId()`, `DirectGLES.cpp:4629-4634`)
* `MultiDrawImpl` — `MultiDraw.cpp:101-109` (`BoundIndexBufferId`, comment states the memo hazard verbatim)
and `MultiDraw.cpp:929-937` (flattened-stream draw restores `previousIndexBinding`).
### 3.2 Primitive-restart rewrite (server-owned at P8, client today)
`docs/Disaggregated/ARCHITECTURE.md:222` assigns restart rewrite to the **server**, reading through the index host
mirror (`ARCHITECTURE.md:383-391`), with `kCapNeedsHostIndexBytes` as the switch (`ARCHITECTURE.md:106`) and
`kMGHostSpanSegFromServerIndexMirror = 0xFFFFFFFF` (`MG_Pipe/MGPipeHostSpan.h:26`) as the "bytes are already yours"
sentinel.
Today, in Espryt:
* `RestartSubstitutionKind ResolveRestartSubstitution(GLenum)` — `DirectGLES.cpp:4636-4653`
(`None` / `SuppressRestart` when `restartIndex > fixedMax` / `RewriteIndices`)
* `ScopedSuppressedPrimitiveRestart` — `Managers.h:~130-145`, impl `DirectGLES.cpp:4657-4673`
(toggles `GL_PRIMITIVE_RESTART_FIXED_INDEX` *around* the render-state shadow)
* `ScopedRestartIndexSubstitution` — decl `Managers.h:157-194`, ctor `DirectGLES.cpp:4675-4786`, dtor `4788-4791`
* `kMaxRestartRewriteBytes = 1<<26` (64 MiB) — `DirectGLES.cpp:4510`
* EBO source: **whole buffer** is rewritten, never just the draw range (`4691-4721`), so a GPU-resident
`firstIndex` still addresses the right element
* **the two reconcile calls P8 must reproduce**: `indexBuffer->SyncPersistentMappedRange();`
`indexBuffer->SyncGpuWrites();` then `MappedData()` — `DirectGLES.cpp:4709-4713`
* client-pointer source: only the draw's own range (`4722-4741`)
* widening `UBYTE→USHORT→UINT` when the source already contains the all-ones index
(`ContainsFixedRestartIndex` `4553-4560`, `WiderIndexType` `4515-4521`, decision `4746-4764`)
* `RewriteRestartIndices` `4562-4578`; `UploadRestartScratch` `4580-4617` (whole-buffer `glBufferData` orphan into
`g_restartIndices`, staged through `BufferImpl::TempBufferTarget`), byte counter
`PipeStats::ByteClass::StageIndexClient` at `4610-4614`
* `OnRestartSubstitutionContextDestroyed` `4655-4659`
* Call sites: `DirectGLES.cpp:4174` (indirect, `count=0` → whole-EBO form), `4799`, `4830`, `5099`, `5112`, `5137`,
`5159`, `5174`, `5191`.
### 3.3 Multi-draw flattening (server-owned at P8, client today)
`MG_Backend/DirectGLES/MultiDraw.{h,cpp}`. Tier ladder documented `MultiDraw.h:15-31`:
`Ext / MultiIndirect / Indirect / BaseVertex / DrawElements / Compute`.
* `DrawElementsBatch` — `MultiDraw.cpp:897-992` (the whole entry point, owns `PrepareForDraw` at `927`)
* `ResolveTierForBatch(programReadsDrawID, perSubDrawBaseVertex, hasIndexBuffer, arbitraryRestart)` —
`MultiDraw.cpp:294-347`; arbitrary restart forces the rewriting tier (`303-307`); batched tiers demote when the
program reads `gl_DrawID` / per-sub-draw base vertex (`316-324`)
* `RunRebasedDrawElements` — `MultiDraw.cpp:492-...`; **the CPU index read**:
`indexBuffer->SyncPersistentMappedRange(); indexBuffer->SyncGpuWrites(); MappedData(); GetSize();`
— `MultiDraw.cpp:508-514`. `RebaseIndices` `MultiDraw.cpp:353-380` (always widens to `GL_UNSIGNED_INT`).
* `FlattenWithCompute` — `MultiDraw.cpp:690-...`; declines on non-list modes (`701-704`), on active restart
(`706-717`), and with no real index buffer (`719-722`)
* Ceilings: `kMaxFlattenedIndices = 1<<24` (`MultiDraw.cpp:74`), `kComputeWorkGroupSize = 64` /
`kMaxComputeWorkGroups = 65535` (`MultiDraw.cpp:81-84`)
* `BoundIndexBuffer` / `BoundIndexBufferId` `MultiDraw.cpp:94-109`, `BoundDrawIndirectBufferId` `86-92`
### 3.4 baseInstance emulation (the thing `set_vertex_buffers`' explicit field retires)
* `g_pendingFetchBaseInstance` — `Managers.cpp:2358`; `SetPendingFetchBaseInstance` / `GetPendingFetchBaseInstance`
`Managers.cpp:2360-2366`; decl + doc `Managers.h:970-983` (`ScopedFetchBaseInstance` at `976-982`)
* `BaseInstanceByteShift` — `Managers.cpp:2377-2383`: `baseInstance * attrib.Stride`, only for `Divisor != 0`,
zero for a stride-0 array
* applied at `Managers.cpp:2586` (`fetchOffset`) and inside the fp64 path at `Managers.cpp:2800-2806`
* `EmulatedFetchBaseInstance` — `DirectGLES.cpp:5128-5130` (returns 0 when `GL_EXT_base_instance` exists,
`UseNativeBaseInstance` `5122-5124`); scopes at `DirectGLES.cpp:5135`, `5172`, `5224`
* **The shift is baked into the driver VAO's attribute offsets**, is draw state, and is deliberately *not* covered by
any frontend version (`Managers.h:941-946`). Un-shifting on the next non-baseInstance draw is why
`baseInstanceDirty` exists (`Managers.cpp:2462-2463`).
---
## 4. The MGPipe side as it exists
### 4.1 Catalogue entries (all present, none implemented)
`MG_Pipe/PipeCalls.def`:
```
95: X(CreateVertexElements, MGPVertexElements, kCtxCso, kHasBlob)
96: X(BindVertexElements, MGPHandleOnly, kCtxCso, kNone)
97: X(DeleteVertexElements, MGPHandleOnly, kCtxCso, kNone)
108: X(SetVertexBuffers, MGPVertexBuffers, kCtxState, kVarTail)
109: X(SetIndexBuffer, MGPIndexBuffer, kCtxState, kNone)
117: X(SetVertexAttribDefaults, MGPVertexAttribDefaults, kCtxState, kVarTail) // landed at P2
```
Generated: dispatch-table members `generated/PipeTables.inc:43-45, 55-56`; thunks
`generated/PipeThunks.inc:96-105, 144-149`; wire opcodes `generated/PipeWire.inc:66-68` (20/21/22) and `78-79` (32/33),
wire record `PipeWire.inc:273-279`; field verifier `generated/PipeVerify.inc:62, 148, 376-378`.
`gMGPipeContext` (`MG_Pipe/MGPipe.h:97`) is **never populated** anywhere outside
`MG_Test/Pipe/PipeCatalogueTest.cpp:102`. P2 does not emit through the table — it calls the applier directly
(`MG_Pipe/PipeApply.h:100-121`: `MGPipeApplyCreateRenderState`, `…BindRenderState`, `…DeleteRenderState`,
`…SetDynamicState`, `…SetPixelPackState`, `…SetPatchState`, `…SetVertexAttribDefaults`, `…SetResidualValueState`).
**P3a's applier entry points follow that same shape**, with `MGPipeApplierState` at `PipeApply.h:47-86`.
### 4.2 Payloads
`MG_Pipe/MGPipeTypes.h`:
```
253-259 MGPVertexElements { MGPipeHandle Cso; Uint32 AttributeCount; Uint32 BindingPointCount; MGPBlobRef Blob; } // 40 B
356-364 MGPVertexBuffer { MGPipeHandle Res; Uint64 Offset; Uint32 Stride, Divisor, BindingIndex, Pad0; } // 32 B
367-371 MGPVertexBuffers { Uint32 Start, Count; Uint64 ContentHash; } // 16 B
374-380 MGPIndexBuffer { MGPipeHandle Res; Uint64 Offset; Uint32 IndexSize, Pad0; } // 24 B
484-488 MGPVertexAttribDefaults { Uint32 Mask, Count; } // 8 B
714-728 MGPDrawInfo (56 B), 731-735 MGPDrawRange (12 B)
```
Draw flags `MGPipeTypes.h:701-707`: `kDrawHasUserIndices / kDrawPrimitiveRestart / kDrawIndicesAreClient /
kDrawHasIndexRange / kDrawHasXfbCount`.
**The two views** the roadmap means (`docs/Disaggregated/ROADMAP.md:19` "vertex elements 三件(两个视图都带)",
`ARCHITECTURE.md:130`) are the two arrays concatenated in `MGPVertexElements::Blob`:
1. the resolved flat `MG_State::GLState::VertexAttribute[]` — `MG_Pipe/MGPipeValueTypes.h:491-527`
(`Enabled, Size, Type, Normalized, Stride, Offset, IsInteger, IsLong, IsBgra, Divisor, Buffer`,
plus query-only `LegacyStride`/`LegacyPointer` at `524-526` which the doc says stay client-side)
2. `VertexBufferBindingPoint[]` — `MGPipeValueTypes.h:530-538` (`Buffer, Offset, Stride = 16 initial, Divisor`)
`VertexAttributeVersion` (3× `Uint16`, size-asserted 6) — `MGPipeValueTypes.h:540-544`, assert `561-562`.
> **Flag for the implementer.** The stated reason both views must travel (pointer stride 0 = element size vs binding
> stride 0 = same element) is *already resolved in the frontend*: `VertexAttribute::Stride` is documented as the
> RESOLVED distance and a surviving 0 can only have come from the binding model (`MGPipeValueTypes.h:496-507`), and
> Espryt consumes exactly that (`Managers.cpp:2545-2560`). Today **no backend reads the binding-point array at all**
> (§1.9). So the second view is either (a) for the `glGetVertexArrayIndexed*` query path, which
> `VertexArrayObject.h:88-104` keeps client-side anyway, or (b) forward-looking. Decide and record it before shipping
> a 2× blob for every VAO in a chunked-renderer workload.
> **Flag: `baseInstance` explicit field.** `ROADMAP.md:19` says "`set_vertex_buffers`(`baseInstance` 显式字段)",
> but `MGPVertexBuffer` (`MGPipeTypes.h:356-364`) has **no** baseInstance member. The only explicit field in the
> current catalogue is `MGPDrawInfo::StartInstance` (`MGPipeTypes.h:719`, `PipeFields.def:189`), which is on the draw
> verb, not on `set_vertex_buffers`. Either the roadmap line means "the fetch shift stops being folded into the
> vertex-buffer offsets and travels as `MGPDrawInfo::StartInstance`" — which is what the payloads support — or
> `MGPVertexBuffer` needs a field, which changes an already-size-asserted POD. Resolve explicitly; `MGPVertexBuffer`
> at 32 B has a `Pad0` at `MGPipeTypes.h:362` that could take it without moving the assert.
### 4.3 CSO caching
`ARCHITECTURE.md:57` sets the client-side content-addressed CSO capacities (render-state 64 / **vertex-elements 1024** /
sampler 256 / sampler-view 4096). `MG_Impl/Pipe/CsoCache.h` implements **only** the render-state cache
(`kMGPipeCsoCacheCapacity = 64`, `CsoCache.h:53`; eviction at `140`). There is no vertex-elements cache yet, and the
negative control bit is `kMGPipeBehaviourNoCsoContentAddressing` (`CsoCache.h:30-37`).
Slot minting: `MG_Impl/Pipe/SlotAllocator.h:39-99` — `FindByLifetimeId` `53`, `Acquire` `55`, `Free` `60`,
`FreeCount` `71`, singleton `MGPipeSlots()` `99`.
---
## 5. What the tracker already pushes for VAOs (P2)
`MG_Impl/Pipe/Tracker.h`:
* dirty enum — `Tracker.h:56-84`; the vertex rows: `NewVertexAttribDefaults` `63`, `NewVertexElements` `65`,
`NewVertexBuffers` `70`, `NewIndexBuffer` `71`
* names — `Tracker.h:96-114` (`"NEW_VERTEX_ATTRIB_DEFAULTS"` `100`, `"NEW_VERTEX_ELEMENTS"` `101`,
`"NEW_VERTEX_BUFFERS"` `105`, `"NEW_INDEX_BUFFER"` `106`)
* `kMGPipeDirtyEmittedAtP2` — `Tracker.h:91-97`: only the five value bits, **vertex elements / buffers / index are
computed and counted but not emitted**; `MGPipeSubsystemForDirty` returns 0 for them (`Tracker.h:122-136`,
default arm `132-135`)
* the shutters, `MGPipeTracker::Update` — `Tracker.h:178-...`:
```
Tracker.h:210-213 vaoIdentity = vao ? MGPipeMixShutter(vao->GetLifetimeId(), vao->GetConfigVersion()) : 0;
now[NewVertexElements] = vaoIdentity;
Tracker.h:243-244 now[NewVertexBuffers] = MGPipeMixShutter(ctx.GetAnyVaoAttributeGeneration(), vaoIdentity);
Tracker.h:245-248 now[NewIndexBuffer] = MGPipeMixShutter(buffers, vaoIdentity); // over-fires on ANY buffer write
Tracker.h:208 now[NewVertexAttribDefaults] = ctx.GetAnyVertexAttribDefaultGeneration();
```
`MGPipeMixShutter` `Tracker.h:143-146`; `MGPipeWidenedCounter` `Tracker.h:158-176`.
The over-fire policy is stated at `Tracker.h:27-33` — a rarely-firing bit renders stale and P1's verify
comparator cannot see it for object-class state.
`FillPoints.def` kDraw rows relevant to vertex state — `MG_Pipe/FillPoints.def:152-199`:
`GetBoundVertexArray` `154`, `GetProgramForDraw` `155`, `GetBufferBindingSlot` `156`,
`GetCurrentVertexAttribute` `165`, `GetPrimitiveRestartIndex` `193`.
(`kDispatch, GetBufferBindingSlot` `204`; `kReadback, GetBufferBindingSlot` `289`.)
`Coverage.def` — accessor→call map: `GetBoundVertexArray → BindVertexElements` (`Coverage.def:36`);
`GetBufferBindingSlot → SetIndirectBuffers` with the note at `37-41` that its rows **split across
set_vertex_buffers / set_index_buffer / set_indirect_buffers / set_shader_buffers** once the inventory is
re-vendored with the target argument (deferred out of P1 — P3a is where that split lands);
`GetCurrentVertexAttribute → SetVertexAttribDefaults` `52`; `GetPrimitiveRestartIndex → DrawVbo` `70`.
Emitted list `Coverage.def:158-192` contains **no** vertex-elements/buffers/index row yet
(`GetCurrentVertexAttribute → SetVertexAttribDefaults` `164` and `GetPrimitiveRestartIndex → SetDynamicState` `178`
are the only vertex-adjacent ones).
`PipeInputs` side — `MG_Backend/MGPipe/PipeInputs.h`: field list rows `79` (`GetBoundVertexArray → m_boundVertexArray`),
`80` (`GetBufferBindingSlot`), `89` (`GetCurrentVertexAttribute`), `107` (`GetPrimitiveRestartIndex`);
accessors `477-481`, `487-493`, `274-283`, `369-372`; storage `641`, `658`, `678-679`;
`kMaxVertexAttribs` `175`. Fill: `MG_Impl/Pipe/PipeFill.cpp:80-82` (bound VAO), `83-91` (buffer binding slots),
`126-129` (current attribs); aggregate note dispatch `PipeFill.cpp:537-538`.
---
## 6. The P2 aggregate generations that cover vertex state
| generation | owner | declaration | bumped from |
|---|---|---|---|
| `VertexArrayObject::m_configVersion` (`Uint32`, per object) | frontend | `VertexArrayObject.h:107` (getter), `:214` (member) | the three `Bump*Version` — `VertexArrayObject.cpp:313-332` |
| per-attribute `VertexAttributeVersion{Format,Buffer,Switch}` (`Uint16`×3) | frontend | `MGPipeValueTypes.h:540-544`; array member `VertexArrayObject.h:207` | same three bumpers |
| `VertexArrayState::m_anyVaoAttributeGeneration` (`Uint64`) | frontend | `VertexArrayState.h:36-42` (`NoteAttributeChanged` / `GetAnyAttributeGeneration`), member `:44` | `MGP_NOTE_AGGREGATE(VaoAttribute)` inside all three bumpers (`VertexArrayObject.cpp:317, 324, 331`) |
| `BufferState::m_anyBufferChangeGeneration` (`Uint64`) | frontend | `BufferState.h:72-78` | every buffer mutator |
| index slot `BindingSlot::m_version` (`Uint16`, **wraps**) | frontend | `MG_Util/Types.h:198, 202` | `BindingSlot::Bind` `Types.h:189-195` |
| `BufferImpl::g_bufferBackendIdGeneration` (`Uint64`) | backend | `Managers.h:701-707` | driver-id re-mint (persistent-map adoption, immutable-store retire) |
| buffer-mutation epoch (`CurrentBufferMutationEpoch()`) | backend | `Managers.h:548-588` | any path that can dirty any buffer |
| `VertexArrayObject::m_lifetimeId` (`Uint64`, never reused) | frontend | `VertexArrayObject.h:70` (`GetLifetimeId`), member `:205`; allocator `:203` | ctor |
### How a server-side VAO object table would be keyed
* Handle: `MGPipeHandle{Slot, Gen}` of kind `VertexElementsCso`, minted client-side off `GetLifetimeId()`
(`SlotTables.h:225-226`), freed on the destructor notice (`VertexArrayObject.cpp:53`), so the server table is a
dense array indexed by `Slot` with a `Gen` compare — exactly `BackendSlotTable::Entry` (`SlotTables.h:145-158`)
and `MGPipeApplierState::RenderStateCsos` (`PipeApply.h:47-51`) already do this shape for render state.
* Freshness inside a slot: today the twin's own `{m_syncedConfigVersion, m_syncedAttributeVersions[32],
m_syncedIndexBufferVersion + m_syncedIndexBufferObject, m_syncedFetchBaseInstance, m_syncedBufferIdGeneration}`
(`Managers.h:906-952`). Under P3a the elements half becomes a **content hash** on the client (`CsoCache`-shaped)
and the buffers/index halves become `MGPVertexBuffers::ContentHash` (`MGPipeTypes.h:370`) + a plain
`set_index_buffer`, so `m_syncedConfigVersion` / `m_syncedAttributeVersions` / `m_syncedIndexBufferObject` all
disappear — but `g_bufferBackendIdGeneration` **does not**: it answers "did *I* re-mint the driver id", which is a
server-side `MGGen` and must never cross the wire (`ARCHITECTURE.md:73-79`).
* `ARCHITECTURE.md:363` records that `SetBackendStateMemo` (the frontend VAO holding a backend heap pointer) is
deleted outright; the three legacy memos on the frontend object are `VertexArrayObject.h:110-175`
(`GetBackendHashMemo`/`SetBackendHashMemo` `121-129`, `GetBackendStateMemo`/`Set…` `137-149`,
`GetBackendAuxMemo`/`Set…` `160-172`, storage `216-225`), all under `MOBILEGL_PIPE_LEGACY_MEMOS`.
---
## 7. Tests
### 7.1 Integration scenarios (`MG_IntegrationTest/Scenarios/`) — gtest `TEST_F`
`VertexAttribBindingScenario.cpp` (758 lines; every case captures the vertex shader's inputs with XFB under
`GL_RASTERIZER_DISCARD`, poison-prefilled buffer — header note `:8-17`):
`FormatAndBindingFeedTheDraw` `241`, `FormatBeforeBufferStillResolves` `269`,
`BindingStrideZeroRepeatsOneElement` `297`, `PointerStrideZeroStaysTightlyPacked` `324`,
`BindingDivisorAppliesToEveryAttributeOnThePoint` `349`,
**`BaseInstanceMovesTheInstancedArraysStartElement` `406`**,
**`BaseInstanceLeavesPerVertexArraysWhereTheyWere` `451`**,
`RelativeOffsetComposesWithBindingOffset` `496`, `InputArrayCaptureProgramFeedsTheDraw` `532`,
`EveryInputArrayElementGetsItsOwnCurrentValue` `617`, `DoubleArrayIsFetchedAtFloat32Precision` `681`,
`NormalizedIsIgnoredForDoubleArrays` `708`, `LongDoubleArrayIsFetchedAtFloat32Precision` `734`.
`VertexArrayEnableDisableScenario.cpp`: `EitherHalfOfTheAttributesInTurn` `231`, `TheEvenHalfAlone` `245`,
`TheOddHalfAlone` `255`.
`MultiDrawScenario.cpp`: `BaseVertexBatchMatchesUnrolledDraws` `225`, `PlainBatchMatchesUnrolledDraws` `253`,
`UnsignedShortBatchMatchesUnrolledDraws` `288`, `UnsignedByteBatchMatchesUnrolledDraws` `317`,
`BaseVertexBeyondIndexTypeRangeMatchesUnrolledDraws` `357`, `ClientSideIndicesBatchMatchesUnrolledDraws` `391`,
`PrimitiveRestartStripBatchMatchesUnrolledDraws` `423`, `PrimitiveRestartUnsignedShortBatchMatchesUnrolledDraws` `456`,
`ZeroCountSubDrawsMatchUnrolledDraws` `493`, `BaseVertexDrawsRejectMalformedArguments` `526`.
`PrimitiveRestartScenario.cpp`: `AnArbitraryRestartIndexDrawsInsteadOfKillingTheProcess` `215`,
`TheFixedIndexValueTakesTheForwardingPath` `236`, `WithoutTheCapTheStripWeldsAcrossTheGap` `263`,
`ChangingTheRestartIndexBetweenDrawsIsHonoured` `281`, `ANonIndexedListTopologyDrawIsUnaffectedByTheCap` `306`,
`ARestartIndexTooLargeForTheIndexTypeRestartsNowhere` `332`, `AnAllOnesVertexIndexSurvivesTheSubstitution` `368`.
`DrawParametersScenario.cpp` (the `gl_BaseInstance`/`gl_DrawID`/`gl_BaseVertex` side of the same emulation):
`DrawArraysReportsAZeroBaseVertexDespiteItsFirst` `213`,
`DrawArraysInstancedBaseInstanceReportsItsBaseInstance` `221`, `APlainDrawAfterABaseInstancedOneSeesZeroAgain` `233`,
`DrawElementsBaseVertexReportsItsBaseVertex` `245`, `DrawElementsAfterABaseVertexDrawReportsZeroAgain` `266`,
`MultiDrawArraysNumbersItsSubDraws` `286`, `MultiDrawElementsIndirectCarriesEveryCommandsParameters` `301`,
`MultiDrawArraysIndirectCountObeysItsParameterBuffer` `327`.
`ResidentIndexScenario.cpp` (element-array + persistent map — the closest thing to a P8 index-mirror gate):
`PersistentCoherentEboWrittenEveryFrame` `186`, `EboAlsoBoundAsVertexBufferLater` `225`,
`EboDeletedAndRecreatedAtTheSameName` `271`, `OneEboTwoVaosMutatedAcrossFrames` `311`, `PromotedDynamicEbo` `351`.
`HandleRecycleScenario.cpp`: `TheReproducerRecyclesEveryName` `440`,
**`AVertexArrayAtARecycledAddressDoesNotInheritItsPredecessorsVertexInput` `483`** (the P2 re-key gate for this kind),
`ATextureAtARecycledAddress…` `573`, `AFramebufferAtARecycledAddress…` `624`.
`DoublePrecisionScenario.cpp` vertex-array cases: `A64BitVertexFormatIsRecordedAndItsArrayIsDroppedAtDraw` `863`,
`AnEnabledLongArrayDoesNotBreakADrawThatIgnoresIt` `916`.
Buffer-family scenarios the roadmap names for P3a: `LargeArenaAdoptionScenario.cpp`
(`SubDataAfterAnInFlightDrawReachesTheNextDraw` `204`, `ReadbackSeesTheLatestCpuWrite` `227`,
`GpuWriteIntoTheArenaIsReadBack` `245`), `StorageBufferRegrowScenario.cpp`
(`AGrownStoreIsVisibleThroughItsExistingIndexedBinding` `124`).
### 7.2 Unit tests
* `MG_Test/VertexArray/VertexArrayTest.cpp` (1366 lines, 46 cases) — frontend state. Cases most load-bearing for
P3a: `VertexAttributeSetup` `124`, `IndexBufferBinding` `156`, `MultipleAttributes` `221`,
`BoundVAOPreservesState` `266`, `VertexBindingIndexIsBoundedByTheAdvertisedAttribLimit` `322`,
`DefaultAttributeBindingIsIdentityAcrossFullCapacity` `338`,
`General_ElementArrayBufferBindingIsVaoLocalAndZeroUnbinds` `557`,
`General_ClientSideVertexAttribPointerIsAccepted` `602`, `General_ElementBufferBindingPoint` `750`,
`ArrayFormat_PackedStored` `1207`, `ArrayFormat_BgraStored` `1228`,
`ArrayFormat_BindingAndRelativeOffsetAreQueryable` `1324`.
* `MG_Test/VertexArray/VertexAttribBindingStateTest.cpp` (430 lines) — the two-view invariant:
`DefaultsMatchTheSpecInitialState` `198`,
**`SeparateFormatSequenceKeepsLegacyStrideAndPointerAtZero` `209`**, `DivisorGoesThroughTheBindingPoint` `318`,
`BindingApiRejectsTheDefaultVertexArrayInCoreProfile` `370`, `…StillAcceptsTheDefaultVertexArrayWhenRelaxed` `395`,
`RelaxedSemanticsOverrideReopensTheDefaultVertexArray` `415`.
* `MG_Test/SanityTest.cpp` `DirectGLESSlotTable` suite (20 cases, `3311`–`4044`). VAO-specific:
`EveryReKeyedObjectClassAnnouncesItsOwnDeath` `3706` (VAO at `3727-3734`),
`EverySwitchedOverKindResolvesItsTwinThroughTheHandleArm` `3857` (VAO at `3878-3879`),
plus `ARecycledSlotIsANewHandleAndTheStaleOneResolvesToNothing` `3311`,
`OneDeathNoticeDropsTheTwinInEveryHolderOfTheKind` `3532`, `AnAnnouncedDeathReturnsTheSlotWithoutASweep` `3657`,
`EglBringUpUnderTheArmlessKnobPairReturnsInsteadOfStopping` `4044`.
* `MG_Test/Pipe/TrackerTest.cpp`: `TrackerAggregates.AVertexArrayAttributeMovesOnlyTheVaoAggregate` `153`
(skip-list row `55`), `AVertexAttribDefaultMovesOnlyItsOwnAggregate` `213`,
`TrackerWalk.WrapAroundRePushesButNeverMisses` `384`, `TrackerAttribPayload.*` `490-524`.
* `MG_Test/Backend/DirectGLES/BaseInstanceInjectionTest.cpp` — the *shader-side* baseInstance gate (`77-155`),
not the fetch shift; `MG_Test/SanityTest.cpp:469-609` covers the SPIR-V rewrites.
* `MG_Test/Pipe/SlotAllocatorTest.cpp`, `CsoCacheTest.cpp`, `PipeCatalogueTest.cpp` (pins
`MGP_CALL_LIST_DOCUMENTED_COUNT = 71`, `PipeCalls.def:69`) — the catalogue/allocator gates P3a must keep green.
---
## 8. Traps an implementer will hit
1. **The twin bakes driver ids into the driver VAO, keyed on FRONTEND versions.** `g_bufferBackendIdGeneration`
(`Managers.h:701-707`, read `Managers.cpp:2446`) exists solely because a backend-side re-mint moves no frontend
version. A `set_vertex_buffers` keyed on client-side content hash alone reintroduces the bug commit `d7655247`
fixed. The generation must stay server-local.
2. **Element-array binding restore.** `ScopedRestartIndexSubstitution` (`DirectGLES.cpp:4788-4791`) and
`MultiDrawImpl` (`MultiDraw.cpp:101-109`, `929-937`) restore the exact previous GL name *because the twin
memoised it*. Whatever replaces the memo must keep an equivalent invariant, or the next draw silently draws
through the scratch buffer.
3. **fp64 streams are content-derived and covered by no version.** `m_hasConvertedFloat64Attribute`
(`Managers.h:919-924`, set `Managers.cpp:2530`, cleared `2471`) forces a full re-walk each draw while any such
array is live. A pure content-hash CSO would go stale here.
4. **The zero-stride and BGRA paths are the two Adreno SIGSEGV corners** (`Managers.cpp:2495-2520`, `2568-2611`);
both must survive the split, and the BGRA probe is the one `glGetError` on the draw path.
5. **Client arrays are resolved after `PrepareForDraw`**, per draw range, and only for `DrawArrays` /
`MultiDrawArrays` (`DirectGLES.cpp:4805-4821`, `4837-4866`). The push ordering contract (`ARCHITECTURE.md:194`)
allows this, but the emitted `set_vertex_buffers` for a client-array attribute names a store that does not exist
until the draw entry point runs.
6. **`SyncNeccessaryBuffers` also does SSBO binding points and `MarkShaderStorageBuffersGpuWritten()`**
(`DirectGLES.cpp:705-706`) — unrelated to vertex input, and it must not be dragged into `set_vertex_buffers`.
7. **`ResolveVaoTwin`'s single-entry handle memo.** `SlotTables.h:407-428` names `ResolveVaoTwin` as one of the two
callers a one-entry memo helps, *because* `PrepareForDraw` resolves the same VAO once per draw. Two resolves per
draw (e.g. adding a second lookup for the elements CSO) would thrash it.
8. **`CollectGarbageIfNeeded` at `DirectGLES.cpp:1275`** is legacy-arm-only; do not add a matching tick on the slot
arm (`SlotTables.h:37-48`).