mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-19 16:01:57 +09:00
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.
509 lines
37 KiB
Markdown
509 lines
37 KiB
Markdown
# P4a package E — `esprytdraw`. Result, v1
|
||
|
||
Branch `refs/heads/p4a/esprytdraw`, five commits on top of the tag `refs/tags/p4a/contract`
|
||
(`08192d72`). **Not pushed.** Working tree clean. One file touched:
|
||
`MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp`, **+893 / −38**. `Utils.{h,cpp}` and
|
||
`MultiDraw.cpp` are **untouched** (§5, DEV-10).
|
||
|
||
A safety ref `refs/heads/p4a/esprytdraw-backup` points at HEAD; the integrator may delete it after
|
||
the merge.
|
||
|
||
| step | sha | message (exactly as C.4 specifies, single line, no attribution) |
|
||
|---|---|---|
|
||
| `e1` | `98bdfa3e37d737c5131280d55829671dff4d4970` | `[Refactor] (Espryt): resolve the current framebuffers from the pushed records and keep the shadowed default bind and the missing fast path exactly as they are` |
|
||
| `e2` | `c0dc679ea3099d4ff04736adf55d3339927de6ca` | `[Refactor] (Espryt): drive the per-draw texture sync from the pushed sampler-view set and give a read-only attachment its texture parameters` |
|
||
| `e3` | `f23fec0ea652bc19543cd93dfa982cd8abcb4398` | `[Refactor] (Espryt): bind shader images from the pushed set and leave the format recast and the split view where they are` |
|
||
| `e4` | `45810af0903a6c23c7f8975e8a82dd00e991b55d` | `[Refactor] (Espryt): bind samplers and the program's resources from the applier's resolved sets and keep the raw-depth-fetch substitution on the server` |
|
||
| `e5` | `0b00f7f0baae89dba37af66896bc7fd0062623e7` | `[Refactor] (Espryt): name every emulation that cannot survive a split and take the format decisions from the descriptor` |
|
||
|
||
---
|
||
|
||
## 0. The one finding the other Espryt packages need before they write a line
|
||
|
||
**`MGPipeApplierReset()` ADVANCES every P4a working-state serial unconditionally**
|
||
(`PipeApply.cpp:686-690`, `:716-720`: `++FramebufferSerial; ++SamplerViewsSerial; …;
|
||
++ProgramBindingSerial`). It is a make-current, not a teardown, and the design's own argument for
|
||
advancing rather than zeroing is correct — but the consequence is that **a P4a working-state serial
|
||
is NEVER the test for "has the client ever emitted this set"**. It is non-zero after the first
|
||
make-current on a tree where nothing emits at all.
|
||
|
||
This was found the expensive way. `e1`'s first landing gated the framebuffer handle arm on
|
||
`FramebufferSerial != 0`, took that arm with two all-zero records, skipped every framebuffer sync
|
||
and turned **55 of 491** `integration-gpu` cases red on the default (`0x1fff`) arm — a failure that
|
||
looks exactly like "the applier is a stub, which the brief says to expect", and would have been
|
||
classified as expected rather than as mine. It is not: the same tree at the tag is **491/491 green
|
||
on the default arm**, which is the control that separated the two (§7 records that run).
|
||
|
||
The tests that hold instead, and that every handle arm in this package uses:
|
||
|
||
* a **record's own handle** (`MGPFramebufferState::Fbo`, `MGPBoundView::View`, `MGPImageView::Res`)
|
||
— null means "no record";
|
||
* a var-tail set's **`Count`** (`SamplerViewCount`, `SamplerStateCount`, `ShaderImageCount`) — 0
|
||
means "this set has never arrived".
|
||
|
||
Package D's `esprytobj` will meet the same trap in `d4`'s `FramebufferSerial` compare and in `d2`'s
|
||
per-record gates. **Recommend the integrator hand this paragraph to D before its rework round.**
|
||
|
||
---
|
||
|
||
## 1. The controlling invariant of this package
|
||
|
||
**Every handle arm DECLINES to the pre-handle arm when the records that arm needs have not arrived,
|
||
and a decline is a full fallback rather than a partial run.** That is P3a's
|
||
`SyncVaoAttributeBuffersByHandle` discipline ("no live record is a miss, never a hit") applied to
|
||
five more families, and it is what makes this package landable ahead of `wire`, `clientfb`,
|
||
`clientsp` and `esprytobj`:
|
||
|
||
* **the default (`0x1fff`) arm is green on this tree, 491/491**, with no expected-failure set to
|
||
argue about — because with an empty applier every arm declines and the tree runs exactly the code
|
||
it ran at the tag;
|
||
* when B/C/`wire` land, each arm engages on its own record's arrival, independently of the others;
|
||
* a **seam check** sits in front of the two arms that could otherwise drive the driver from a record
|
||
that describes something else (§4, e1 and e3), so a mis-keyed emission declines loudly instead of
|
||
producing wrong pixels.
|
||
|
||
---
|
||
|
||
## 2. Per-step summary: every memo re-keyed, and every frontend read replaced (Track H census input)
|
||
|
||
### `e1` — the framebuffer sync and bind path (+347 / −18)
|
||
|
||
**Memos re-keyed**
|
||
|
||
| before | after (handle arm) |
|
||
|---|---|
|
||
| `g_fboSyncedSlotVersions[t]`, `g_fboSyncedObjectVersions[t]`, `g_fboSyncedObjects[t]` — three answers to "has the state the client would describe moved" (`Managers.h:1690-1710`) | **one** `Uint64`: `FramebufferImpl::g_fboSyncedSerials[t].serial` vs `MGPipeApplier().FramebufferSerial` |
|
||
| `g_fboSyncedBackendIdGenerations[t]` | **kept, per D-B3/D-O**: `g_attachmentBackendIdGeneration` answers "did *I* re-mint a driver texture id", which no client version can answer. Joined by `g_backendContextGeneration`, because driver FBO names die with the ES context |
|
||
| `g_broadcastMemo{Fbo, SlotVersion, ObjectVersion}` (`DirectGLES.cpp:3037-3057`) | `g_broadcastMemoContentHash` vs `DrawFramebuffer.ContentHash` — a **complete** key by D-C4's construction: the hash covers `Fbo` (so a recycled framebuffer handle cannot be suppressed against its predecessor) and `DrawBuffers[8]` (so an unchanged hash provably means the broadcast count did not move) |
|
||
|
||
The memo stays **per target**, because `ForceBindCurrentFBO` syncs one binding and must be able to
|
||
say so; what collapsed is the three-value question into one serial, not the two targets into one.
|
||
|
||
**Frontend reads replaced**
|
||
|
||
| read | site | replaced by |
|
||
|---|---|---|
|
||
| `GetFramebufferBindingSlotChecked(t).GetVersion()` ×2 | `SyncCurrentFBO`'s memo | the record's serial |
|
||
| `currentFBO->GetObjectVersion()` ×2 | same | same |
|
||
| `currentFBO.get()` as identity ×2 | same | `record.Fbo` through `FindByHandle` |
|
||
| `currentFBO == pDefaultFramebufferInfo->defaultFBO` ×2 | `SyncCurrentFBO`, `BindCurrentFBO` | `record.IsDefault` — one of the four identity comparisons `MGPipeHandles.h:69-71` names. Retained **only** as the consistency guard's comparand (§4) |
|
||
| `currentFBO.get() == lastUpdatedFBO` ("same FBO as draw") | `SyncCurrentFBO:2286` | `record.Target == Both`, and the read buffer is then applied from the record's **own** `ReadSurface`. The hazard `Managers.cpp:7424-7426` describes becomes unrepresentable rather than merely fixed |
|
||
| **the whole of `GetFramebufferBindingSlotChecked(t)`** | `BindCurrentFBO` | the record. This is the one of the five call sites that is **entirely retired** on the handle arm |
|
||
| `drawFBO->GetDrawBuffers()` walk | `SyncCurrentProgram`'s fragColor derivation | `record.DrawBuffers[8]` (`>= 0` is "not None") |
|
||
|
||
**Kept exactly as they are, and each says so in a comment**: `BindCurrentFBO` has **no fast path on
|
||
any version** (`KHR-GL32.packed_pixels`, D-O); the **default framebuffer is bound through the
|
||
shadow**, never raw (`readback-state-guards`, D-O); the widened/integer draw-buffer masks are reset
|
||
on the default-FBO path for the DRAW target only; `SyncAndBindFramebufferObject`'s default-FBO early
|
||
return is untouched.
|
||
|
||
**New invalidation**: `FramebufferImpl::InvalidateFramebufferHandleArmMemos()` is called beside all
|
||
**six** `InvalidateFramebufferBindingCache()` call sites in this file, and `InvalidateBroadcastMemo()`
|
||
clears the handle-arm broadcast keys too.
|
||
|
||
### `e2` — the per-draw texture sync (+265 / −4)
|
||
|
||
**Memos re-keyed**
|
||
|
||
| before | after (handle arm) |
|
||
|---|---|
|
||
| `CurrentUnitBindingsEpoch`'s derivation: `CaptureUnitBindings` / `UnitBindingsUnchanged` — a per-unit walk over every binding slot **and** the unit's sampler object, re-run whenever `GetTextureBindGeneration()` moves (26.2 moves it around every texture-unit switch) | `Mix(SamplerViewsSerial, SamplerStatesSerial)` — **two `Uint64` reads, no walk, no accessor call**. Sound because both sets go out through a `ContentHash` suppressor over every tail entry, so a serial moves iff the resolved set moved |
|
||
| `g_fboTextureSyncListSlotVersion` + `…ObjectVersion` | `g_fboTextureSyncListContentHash` vs `DrawFramebuffer.ContentHash`. **The identity half stays a pointer compare** and deliberately so — the list borrows the attachment's own `SharedPtr` slots, and "is the object I borrowed from the one bound now" has no handle in it until D re-keys the twin tables |
|
||
|
||
**Transitively re-keyed with no edit of their own** — every consumer of `keys.unitBindingsEpoch`,
|
||
which is now the records' serials on the handle arm: `g_unitTextureSyncList*` (the unit texture sync
|
||
list), `ResolvedTextureBindingMemo` (the per-program resolved texture bindings), `g_unitSamplerWalk*`
|
||
(the sampler walk), and `BackendProgramObjectImpl::SamplerPassMemo`. **Four memos re-keyed by one
|
||
substitution** — this is the single largest item in the census and it costs no edit at any of the
|
||
four sites.
|
||
|
||
**Behaviour deliverable — D-E3, `ROADMAP.md:20`'s 落地前必须红 item.** A new push-only list,
|
||
`g_readFboTextureSyncList`, walks the **READ** framebuffer's texture attachments and gives each one
|
||
`SyncTextureParamsToBackend` + `SyncBuiltinSamplerToBackend` + `SyncMipmapsToBackend`. Today a
|
||
read-only attachment reaches `SyncAttachmentObject`, which calls `SyncMipmapsToBackend` **and
|
||
nothing else** (`Managers.cpp:7161`), because the list that pushes parameters for an attachment reads
|
||
the DRAW slot alone (`DirectGLES.cpp:1944`). One object bound to both bindings is walked once (a
|
||
pointer compare against the draw framebuffer). The list carries **both** key shapes, exactly like
|
||
the draw list.
|
||
|
||
**Memos retired**: none. `UnitBindingsSnapshot` / `CaptureUnitBindings` / `UnitBindingsUnchanged` /
|
||
`PairingsIntact` are all **kept**; their deletion is the ~175-line backend debounce removal that
|
||
`ROADMAP.md:23` gives to P3b/P4b, and `ARCHITECTURE.md:369` keeps the pre-handle arm compiling
|
||
through P4a.
|
||
|
||
### `e3` — the image units (+93 / −6)
|
||
|
||
* `SyncImageTextureBinding` takes **`Level`, `Layer`, `Layered` and `InternalFormat`** from
|
||
`MGPImageView` when `ResolveShaderImageRecord` says the record names the same texture the unit
|
||
holds. Substituted through four `#define`/`#undef` pairs in the `MGB_UNIT_BINDINGS_HANDLE_ARM`
|
||
shape this file already uses, so the **pull build's preprocessed text is unchanged** (D-P).
|
||
* `SyncImageTextureBindings`' sweep membership: `min(192, MaxImageUnits)` → `[ShaderImageStart,
|
||
ShaderImageStart + ShaderImageCount)`, clamped to what ES exposes. That is D-J2's rule — *the
|
||
var-tail window IS the bound and entries outside it are not cleared*.
|
||
* **`Access` is deliberately not taken from the record** — see DEV-6.
|
||
* **D-G4's two invariants are kept and now say so in the source**: the
|
||
`g_imageUnitHighWaterMark == 0` early-out is asked before anything reads a record, and the sweep's
|
||
gate stays the **frontend** sampling-resolution generation and is explicitly *not* re-keyed onto a
|
||
server-owned serial, because a texture bound only to an image unit is re-minted **inside** the
|
||
sweep. The bind-format recast and the buffer split view are untouched.
|
||
|
||
### `e4` — the sampler walk and the program's resources (+159 / −13)
|
||
|
||
* **`BindCurrentUnitSamplers`' walk reads `MGPipeApplier().BoundSamplerStates[unit]`** instead of
|
||
`MGB_CTX->GetTextureUnitObject(unit).GetSamplerObject()`, and binds through `FindByHandle` — so on
|
||
that path `UnitSamplerLookupMemo` is **bypassed entirely**: the handle *is* the lookup, and
|
||
`SlotTables.h:556-561`'s recorded single-entry-memo thrash does not happen. A null handle unbinds;
|
||
a handle whose twin does not exist yet is left alone and **never cached as a miss**, for the reason
|
||
`ResolveUnitSamplerBackend` gives (the program pass creates the twin later in the same draw).
|
||
* **`BindCurrentProgramWithResources`' global UBO takes its version and its block image from the
|
||
`ShaderCso` record** — `GlobalConstantsVersion` and `GlobalConstants` replace
|
||
`GetUBOContentVersion()` and `MapUBO()`. `ResolveGlobalConstantsRecord` requires four things
|
||
before it will answer: a live record at the program's handle, the record's own `Desc.Cso` naming
|
||
that same handle (the seam check), a version that is not the `~0u` never-uploaded sentinel, and a
|
||
block image at least `GetUBOSize()` long.
|
||
* `FindShaderCsoRecord` is the **one** reader that knows the composite band exists
|
||
(`MGPipeIsCompositeShaderSlot` → `CompositeShaderCsos[slot − base]`), so D-H7's "the server never
|
||
learns it is a composite" stays true of every other reader.
|
||
* **The UBO ring is untouched** — the `{contentVersion, ringGeneration, frameSerial, offset}`
|
||
allocation key, the `glBufferSubData` fallback and the `ByteClass::StageUboGlobal` accounting are
|
||
all exactly what they were. Named UBOs (P4b) are untouched.
|
||
* **The raw-depth-fetch substitution stays on the server** and now carries the D-F3 paragraph naming
|
||
it as *the largest surviving `MG_State`-type usage under `MG_Backend/DirectGLES`* with its owner
|
||
(P3b/P4b) written down, so P13's include-graph gate meets a known item.
|
||
|
||
### `e5` — the named emulations (+32)
|
||
|
||
Four `MGPipeUnmigratedEmulation` call sites, each planted where the emulation **commits to running**
|
||
(after the cheap declines), so the name means "this ran" rather than "this was considered". §6 lists
|
||
them.
|
||
|
||
---
|
||
|
||
## 3. What this package assumes of package D, and where the rebase will touch it
|
||
|
||
Every assumption below is written into the source at the site that makes it.
|
||
|
||
| # | assumption | what changes at the rebase |
|
||
|---|---|---|
|
||
| **A1** | `StateBackendObjectRegistry` (`Managers.h:303-540`) forwards `HandleOf` and `FindByHandle` but **not** `GetOrCreate(MGPipeHandle)`. `e1` resolves the FBO twin with `FindByHandle(record.Fbo)` and falls back to `GetOrCreate(currentFBO)` | after `d1`, the fallback becomes `GetOrCreate(record.Fbo)` — one line, marked "MONOLITH GLUE" in the source |
|
||
| **A2** | `BackendFramebufferObject::SyncToBackend(const SharedPtr<FramebufferObject>&, FramebufferTarget)` and `SyncReadBufferToBackend(const SharedPtr<FramebufferObject>&)` keep their signatures through `d4`; only their bodies re-key onto `MGPFramebufferState` | if `d4` changes the signature, `SyncCurrentFBOByRecord`'s two call sites take the record instead of the object, and the "resolve the bound object" block above them disappears with the consistency guard (§4) |
|
||
| **A3** | `BackendTextureObject::{SyncTextureParamsToBackend, SyncBuiltinSamplerToBackend, SyncMipmapsToBackend, IsDrawSyncClean}` keep their frontend-object signatures through `d2` | the three sync lists' entries become `{handle, twin}` instead of `{slot, texture, twin}`, and DEV-4 (the unit list's membership) can then move to the record |
|
||
| **A4** | D-K3's four `Resolve<Family>SubsystemArm()` latches do **not** exist at `c0`; contract-v1 §6 gives them to D | the four local latches in this file (`EsprytDraw{TextureResource,Framebuffer,Sampler,Program}HandlesEnabled`) become calls to D's, which add the `MGLOG_E` naming both bits and the `Fatal{PipeLegacyMemosDisabled}` stop. **The dependency directions are already copied here** (11→10, 9→10, 10→7, 12→nothing) so a half-running mask is refused in the meantime |
|
||
| **A5** | `SamplerPassMemo::rows` stays `Array<BackendSamplerObject*, 16>` and `g_boundSamplersCache` stays a raw-pointer shadow (`Managers.h`, D's) | nothing here; see DEV-5 for why no handle belongs in either |
|
||
| **A6** | `MGPImageView::Access` is a `Uint8` with **no documented encoding** at `c0` | `e3` starts reading it once package C writes the encoding down; one `#define` in this file |
|
||
| **A7** | `MGPipeApplierReset` advances all P4a working-state serials (§0) | nothing here — every arm already uses handles and counts |
|
||
|
||
---
|
||
|
||
## 4. The two seam checks, and why they exist
|
||
|
||
Both were added in a self-review pass and squashed into their step (DEV-12). Both exist because this
|
||
package can be *landed* but not *exercised* against real records on its own tree, and the failure
|
||
mode they guard is silent wrong pixels rather than a red test.
|
||
|
||
**Framebuffer (`e1`).** `FramebufferRecordMatchesBinding(target, record)` requires the record's
|
||
`IsDefault` to agree with the bound object's defaultness and, for a non-default record, the
|
||
record's `Fbo` to equal `HandleOf(bound)`. A disagreement **declines the whole arm** — both targets,
|
||
not one — because the two records are emitted together and one being wrong says nothing good about
|
||
the other, and it logs once. `g_fboRecordsTrusted` carries that verdict to `BindCurrentFBO` (whose
|
||
whole value is that it does **not** read the binding slot) and to the fragColor broadcast derivation;
|
||
both run immediately after `SyncCurrentFBO` in `PrepareForDraw`, so the latch is fresh, and it starts
|
||
false and is cleared by every decline and by every binding-cache invalidation, so an unpaired bind
|
||
takes the pre-handle arm.
|
||
|
||
**Image units (`e3`).** `ResolveShaderImageRecord` returns the record only when `view.Res` equals
|
||
`HandleOf(the unit's bound texture)`. This one is not optional: `SyncImageTextureBinding` is also the
|
||
**eager** funnel `glBindImageTexture` itself runs, and at that moment the newest record describes the
|
||
*previous* draw — driving the driver from it would bind one texture with another's level, layer and
|
||
format.
|
||
|
||
Both checks are monolith glue and both disappear when D's twin API takes the record instead of the
|
||
object: at that point there is no second answer left to disagree with.
|
||
|
||
---
|
||
|
||
## 5. Deviations, each with its reason
|
||
|
||
**DEV-1 — the READ-attachment parameter gap is closed from `SyncNeccessaryTextures`, not from
|
||
`SyncAttachmentObject`.** C.4's `e2` says *"`SyncAttachmentObject` gains the parameter sync for
|
||
READ-only attachments"*, but `SyncAttachmentObject` is in `Managers.cpp`, which C.7 gives to **D**
|
||
for the whole phase. The gap's actual cause is in this package's file — `SyncNeccessaryTextures`'
|
||
attachment list reads `GetFramebufferBindingSlotChecked(Draw)` alone
|
||
(`scout-espryt-framebuffer.md` §2.6) — so closing it here is both within ownership and closer to the
|
||
cause. Same observable behaviour: an attachment of either framebuffer now gets
|
||
`SyncTextureParamsToBackend` + `SyncBuiltinSamplerToBackend`.
|
||
|
||
**DEV-2 — the READ-attachment sync is NOT gated on the framebuffer subsystem bit.** It is a
|
||
*deliverable* of the phase (`ROADMAP.md:20`, `ARCHITECTURE.md:100`), not an *arm* of it. Gating it
|
||
would make the object A/B measure the arm **plus** a behaviour change and would leave G9's mandatory
|
||
case red on every legacy lane. It is inside `#if MOBILEGL_PIPE_PUSH`, so G1 and the pull build are
|
||
untouched, and G9 runs on `build-push`.
|
||
|
||
**DEV-3 — `keys.maxTouchedUnit` stays `MGB_CTX->GetMaxTouchedTextureUnit()`.** D-G2 makes
|
||
`SamplerViewCount` the client's spelling of exactly this number, and an earlier revision of `e2` did
|
||
take it off the record. It was **reverted in self-review** because the two failure directions are not
|
||
alike: a window larger than the frontend mark costs a walk over provably-empty units, while one that
|
||
is *smaller* silently drops the sync of a texture a draw is about to sample — and no gate on this
|
||
tree can see the difference, because this tree emits no windows. The design assigns the high-water
|
||
mark to the **client** as the `count` argument and says nothing about re-deriving it server-side.
|
||
One accessor read per draw; the integrator can move it in one line on a tree where the two can be
|
||
compared (§8).
|
||
|
||
**DEV-4 — the unit texture sync list's MEMBERSHIP stays the frontend binding walk; only its
|
||
VALIDITY is record-keyed.** C.4's `e2` asks for the list to be "rebuilt from the applier's
|
||
SamplerViews set". It cannot be, yet, and the reason is structural rather than a matter of effort:
|
||
an entry is `{const SharedPtr<ITextureObject>* slot, ITextureObject* texture, BackendTextureObject*
|
||
backend}` and the three twin calls it replays all take the **frontend object**. `MGPBoundView`
|
||
carries a texture *handle* and a unit index but not the binding target, and a handle cannot be turned
|
||
back into a frontend object (`Entry::stateRef` is empty by design on handle-keyed entries,
|
||
`SlotTables.h:266-269`). The membership move is unlocked by D's `d2`, at which point the entries
|
||
become `{handle, twin}`; A3 records it.
|
||
|
||
**DEV-5 — `SamplerPassMemo`'s rows stay `BackendSamplerObject*`.** C.4's `e4` says they become
|
||
handles. Two reasons not to, and the second is the real one: the struct is in `Managers.h`, which is
|
||
D's file; and the rows are not an *identity* question at all — they are the memo's proof that **the
|
||
driver still holds the bindings this pass left**, compared against `g_boundSamplersCache`, which is a
|
||
server-owned driver shadow. A client handle in that array would answer a question nobody asked. The
|
||
identity half of this memo family *is* already handle-keyed, by P2:
|
||
`UnitSamplerLookupMemo::frontendHandle` (`DirectGLES.cpp:3522-3535`). What `e4` adds is that the
|
||
record path does not consult that memo at all.
|
||
|
||
**DEV-6 — `MGPImageView::Access` is not consumed.** The field is a `Uint8` and a GL access token
|
||
(`GL_READ_ONLY` = 0x88B8) is not, so the record carries an **encoding** — and neither
|
||
`MGPipeTypes.h:659-668` nor `PipeFields.def:123-124` writes one down at `c0`. Reading it here would
|
||
be inventing it. The frontend value answers, and it is the same value by construction.
|
||
**Recommend the integrator have package C document the encoding in `ImageEmit.h`**, after which this
|
||
is one `#define` in `SyncImageTextureBinding`.
|
||
|
||
**DEV-7 — four local family arm latches instead of D's `Resolve<Family>SubsystemArm()`.** A4. They
|
||
carry the dependency directions verbatim; they do **not** carry the refusal `MGLOG_E` or the
|
||
`Fatal{PipeLegacyMemosDisabled}` stop, because two writers of one diagnostic is how the two drift.
|
||
|
||
**DEV-8 — `SyncTextureObjectToBackend` does not gain an explicit handle parameter.** C.4's `e2` asks
|
||
for it. It is already handle-keyed *internally* on the handle arm — `Find(obj)` on a
|
||
`BackendSlotTable` is `FindByHandle(HandleOf(obj))` (`SlotTables.h:364-368`) — so an explicit
|
||
parameter would only skip a memoised lifetime-id probe, and no caller has a handle to pass until
|
||
DEV-4 is unlocked. Adding the overload now would be ~60 duplicated lines with no caller.
|
||
|
||
**DEV-9 — two consistency guards on the handle arms.** §4. They add frontend reads that a fully
|
||
migrated path would not need, which is the opposite direction from the phase's goal; they are marked
|
||
in the source as monolith glue with the condition for their removal.
|
||
|
||
**DEV-10 — `Utils.{h,cpp}` and `MultiDraw.cpp` are untouched.** C.4's `e5` asks for "the
|
||
`Utils.{h,cpp}` readers that take a descriptor instead of a frontend object". A grep for `MG_State`,
|
||
`ITextureObject`, `FramebufferObject`, `SamplerObject` and `ProgramObject` across all three files
|
||
finds **no such reader**: `Utils.h`'s format decisions
|
||
(`ShouldUseCaveatTextureFormat`, `GetImageBindableStorageWidening`, `GetImageBindableBufferSplitFormat`,
|
||
`GenerateTextureFormatInfo`) already take `TextureInternalFormat` + `TextureTarget` **values**, and
|
||
`MultiDraw.cpp`'s only frontend reads are `BufferObject` (P3a's family, and the index host mirror is
|
||
P8's). The one Utils function D-N names, `ShouldUseCaveatTextureFormat`, is on the byte-identical
|
||
list and stays byte-identical. `e5`'s message therefore lands with only its first clause realised;
|
||
the second clause has no work behind it in these files.
|
||
|
||
**DEV-11 — D-N was checked by hand.** `scripts/p4a_untouched_regions.sh` is package F's and does not
|
||
exist yet. §6 gives the sha evidence for the two D-N functions that live in package E's files, taken
|
||
the same way the script takes them (an `awk` range for the namespace, a `git diff --stat` for the
|
||
file).
|
||
|
||
**DEV-13 — `~/w7/p4a-trees2.log` never said `REBUILT esprytdraw`, and this package built anyway.**
|
||
The task said to wait for that line before the first build. The file was created at 12:25 and was
|
||
**still zero bytes** when this round ended, with no `cmake`, `ninja`, `wsl_tree.sh` or
|
||
`wsl_integrate.sh` process running at any point. What was checked instead, before touching anything:
|
||
`HEAD == refs/tags/p4a/contract` (`08192d72`), a clean working tree, `build-linux` and `build-push`
|
||
present with libraries dated after the tree was created, and `ninja -n` in both reporting nothing to
|
||
do but a CMake re-run — i.e. the tree was already in the state the line would have announced. **If
|
||
the integrator's rebuild script is still pending, it must not be run against this worktree**: a
|
||
`wsl_tree.sh p4a esprytdraw p4a/contract` would reset `refs/heads/p4a/esprytdraw` and take the five
|
||
commits with it. `refs/heads/p4a/esprytdraw-backup` (`0b00f7f0`) exists for exactly that accident and
|
||
should be deleted after the merge.
|
||
|
||
**DEV-12 — the series was produced with one autosquashed fixup.** The self-review (§4, DEV-3) found
|
||
two issues after `e5` had landed; the fix was committed as `--fixup=<e2>` and folded in with
|
||
`git rebase --autosquash`, so `e2`..`e5` carry different shas than their first landing and the branch
|
||
is exactly the five commits C.4 asks for, with the five messages verbatim. Every commit was
|
||
re-verified afterwards (§7).
|
||
|
||
---
|
||
|
||
## 6. Emulations: dispositions and the `MGPipeUnmigratedEmulation` sites
|
||
|
||
Four of D-M's five names are planted in this package's file; the fifth (`texture-remint-pull`,
|
||
`Managers.cpp:4769`) is **package D's** — contract-v1 §6 splits the five between D and E, and
|
||
`PipeCatalogueTest.EveryUnmigratedEmulationIsNamedOnce` pins all five names.
|
||
`grep -rc 'MGPipeUnmigratedEmulation' MobileGL/MG_Backend/DirectGLES/` → `DirectGLES.cpp:4`.
|
||
|
||
| name | site (this file, at `0b00f7f0`) | planted where |
|
||
|---|---|---|
|
||
| `"generate-mipmap-storage"` | `EnsureGenerateMipmapStorageAllocated` | after the `existingLevelCount == 0` decline, before the level shadows are read |
|
||
| `"generate-mipmap-cpu-fallback"` | `GenerateThreeChannelFloatMipmapOnCpu` | after the format and mipmap-texture declines |
|
||
| `"copy-image-shadow-mirror"` | `MirrorCopyImageIntoDestinationShadow` (under `CanMirrorCopyImageShadow`) | after every shape decline, immediately before the shadow rows are copied |
|
||
| `"get-tex-image-shadow"` | `GetTexImageViaShadowConversion` | after the channel-mapping and zero-extent declines |
|
||
|
||
**Emulations that stay where they are, per D-M, and what changed about them:**
|
||
|
||
| emulation | owner | in this package |
|
||
|---|---|---|
|
||
| fragColor MRT broadcast (`BroadcastLegacyFragColor`) | server | unchanged as a rewrite; its **input** (`g_fragColorBroadcastCount`) is now derived from the framebuffer record's `DrawBuffers[8]`, keyed on its `ContentHash`, at the same point in the draw as before. Deleting the workaround and `g_broadcastMemo*` is P3b/P4b's |
|
||
| D24S8 dual-mode sampling (`DepthStencilSamplingReadImpl`) | server | **byte-identical**, §6.1 |
|
||
| blit LOD / layered blit, the multisample replicate path | server | untouched |
|
||
| draw-buffer `None` → `GL_NONE`, "apply draw buffers only for the DRAW target" | server (`Managers.cpp`, D's) | untouched here; the record's `Target` is what makes the second rule a field test rather than call-site discipline |
|
||
| layered attachment shapes, `SupportsLayeredImageBinding`'s rule | server | untouched; `e3` feeds it `record->Layered` / `record->Layer` and it still asks the **backend** target and still forces `layer` to 0 for a non-layerable one |
|
||
| image format bake / widen / split / array remap | server | untouched; `e3` feeds the recast the application's format from the record |
|
||
| texture LOD bias (`EmulateTextureLodBias` + the per-draw `glUniform1f`) | server | untouched |
|
||
| raw-depth-fetch sampler substitution | server, P3b/P4b to nativise | untouched, and now carries the D-F3 paragraph naming it as the largest surviving `MG_State`-type usage under `MG_Backend/DirectGLES` |
|
||
|
||
### 6.1 Byte-identical evidence
|
||
|
||
| item | evidence |
|
||
|---|---|
|
||
| **D-N, in package E's files**: `DepthStencilSamplingReadImpl` | it is a **namespace**, not a function (`DirectGLES.cpp:8437-8898`), so it is hashed the way P2's G5 hashes `RenderStateImpl`: `awk '/^ namespace DepthStencilSamplingReadImpl \{/,/^ \} \/\/ namespace DepthStencilSamplingReadImpl/' \| sha256sum` → `dfefc996…c9063f53` at `37da3c3a` **and** at HEAD. Package F's `p4a_untouched_regions.sh` will need the namespace shape for this one row |
|
||
| **D-N**: `ShouldUseCaveatTextureFormat` (`Utils.cpp:245`) | `git diff --stat 37da3c3a..HEAD -- Utils.cpp Utils.h MultiDraw.cpp` is **empty** — the whole file is untouched |
|
||
| **P3a's eleven** (G5) | `bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD` → **rc 0** at every one of the five commits |
|
||
| **P2's G5** (`RenderStateImpl` namespace) | `d8fd1c48716056c536752fde09db3a9e5aa8494b70404798bfc15d11220efe27` == `~/w7/p4a-before-syncrenderstate.sha`, at every one of the five commits |
|
||
|
||
Package E's other D-N obligations (`StageBlocksIntoUnpackRing`, `UnpackRingAvailable`,
|
||
`UnpackRingAllocate`, `RecomputeBackendColorSlots`) all live in `Managers.cpp`, which this package
|
||
never opens.
|
||
|
||
---
|
||
|
||
## 7. Verification transcript
|
||
|
||
All commands in `~/w7/p4a-esprytdraw` with `CCACHE_BASEDIR=/home/swung/w7`.
|
||
|
||
### 7.1 Per commit (all five)
|
||
|
||
```
|
||
$ for c in 98bdfa3e c0dc679e f23fec0e 45810af0 0b00f7f0; do git checkout --detach $c; ... done
|
||
|
||
98bdfa3e build-linux OK build-push OK unit(push) OK
|
||
### Removed (0) ### Added (0) ### Resized (0) ### Renamed only (0)
|
||
p3a-untouched rc=0 RenderStateImpl sha d8fd1c48716056c5
|
||
c0dc679e … identical …
|
||
f23fec0e … identical …
|
||
45810af0 … identical …
|
||
0b00f7f0 … identical …
|
||
```
|
||
|
||
### 7.2 On the finished branch (`0b00f7f0`)
|
||
|
||
```
|
||
$ python3 scripts/symbol_report.py --before ~/w7/p4a-before-libMobileGL.so \
|
||
--after build-linux/libMobileGL.so --threshold 0
|
||
| before | ~/w7/p4a-before-libMobileGL.so | 19114360 | 10806323 |
|
||
| after | build-linux/libMobileGL.so | 19114360 | 10806323 |
|
||
### Removed (0) ### Added (0) ### Resized (0) ### Renamed only (same size) (0) <- G1
|
||
|
||
$ bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD
|
||
[p3a-untouched] the 11 pool / deferred-release / ring / flush-drain functions are
|
||
[p3a-untouched] byte-identical between 37da3c3a and HEAD rc=0
|
||
|
||
$ awk '/^ namespace RenderStateImpl \{/,/^ \} \/\/ namespace RenderStateImpl/' \
|
||
MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp | sha256sum
|
||
d8fd1c48716056c536752fde09db3a9e5aa8494b70404798bfc15d11220efe27 == p4a-before-syncrenderstate.sha
|
||
|
||
$ cmake --build build-linux -j 12 && ctest --test-dir build-linux -L unit -j 12
|
||
100% tests passed, 0 tests failed out of 1635
|
||
$ cmake --build build-push -j 12 && ctest --test-dir build-push -L unit -j 12
|
||
100% tests passed, 0 tests failed out of 1635
|
||
|
||
# the legacy arms, and the default arm
|
||
$ MOBILEGL_PIPE_PUSH=0x1ff ctest --test-dir build-push -L integration-gpu -j 8 -R DirectGLES
|
||
100% tests passed, 0 tests failed out of 491 rc=0
|
||
$ MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu -j 8 -R DirectGLES
|
||
100% tests passed, 0 tests failed out of 491 rc=0
|
||
$ (default = 0x1fff) ctest --test-dir build-push -L integration-gpu -j 8 -R DirectGLES
|
||
100% tests passed, 0 tests failed out of 491 rc=0
|
||
|
||
# C.4's family subset, all three arms
|
||
$ ctest --test-dir build-push -L integration-gpu -j 4 -R '<C.4's 41-name regex>'
|
||
default 100% 497/497 | 0x1ff 100% 497/497 | 0 100% 497/497
|
||
|
||
$ grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$'
|
||
MobileGL/MG_Backend/MGPipe/PipeInputs.h:1 # pre-existing at $BASE, unchanged <- G13
|
||
|
||
$ grep -rc 'MGPipeUnmigratedEmulation' MobileGL/MG_Backend/DirectGLES/
|
||
MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:4 # + D's one in Managers.cpp = 5 <- G13b
|
||
|
||
# both compile-time arms, since none of the three standing build dirs has it off
|
||
$ cmake -S . -B build-nolegacy … -DMOBILEGL_PIPE_PUSH=ON -DMOBILEGL_PIPE_LEGACY_MEMOS=OFF
|
||
configure rc=0 ; ninja -C build-nolegacy MobileGL → rc=0 (dir removed afterwards)
|
||
```
|
||
|
||
**The default-arm control that made §0's finding attributable**: with the working tree stashed, the
|
||
same build dirs at the tag ran `default → 100% 491/491`. That is what says "55 red" was this
|
||
package's and not the stub applier's.
|
||
|
||
### 7.3 Not run here, and why
|
||
|
||
* **G3 / G3b / G4** (`retrace_gate.py`, the verify lane) — `build-verify` does not exist in this
|
||
worktree (`wsl_tree.sh p4a esprytdraw p4a/contract` was created without the `verify` argument, per
|
||
C's tree-creation list). They belong to the integrated tree.
|
||
* **G6 / G7** (`*EmitTest`, `p4a_descriptor_negative_control.sh`) — packages B/C/F.
|
||
* **G8 / G8b / G9 / G12** (`HandleRecycleScenario`, `TextureParamsWithoutASamplerViewScenario`,
|
||
`ObjectSubsystemControlScenario`) — package F's scenarios; none exists on this tree, so **D-E3's
|
||
closure is implemented but not yet demonstrated** (§8).
|
||
* **G5's script** — package F's (DEV-11).
|
||
|
||
---
|
||
|
||
## 8. Post-rebase verification list
|
||
|
||
For the integrator, after rebasing this branch onto `wire` + `clientfb` + `clientsp` + `esprytobj`.
|
||
The first three are the ones that can only be answered on the integrated tree.
|
||
|
||
0. **Re-read §3's assumptions against `contract-v2`.** This branch is based on the **tag**
|
||
`refs/tags/p4a/contract` (`08192d72`), as ID-2 requires, but `refs/heads/p4a/contract` has since
|
||
moved to `2cb44039` (the contract rework). Anything the rework settled that §3 lists as an
|
||
assumption — most likely **A6** (`MGPImageView::Access`'s encoding) and **A4**
|
||
(`Resolve<Family>SubsystemArm()`'s home) — is a one-line change here rather than a design
|
||
question, and should be taken before the rest of this list.
|
||
1. **The arms actually engage.** With the default mask, confirm each handle arm is taken rather than
|
||
declining: `SyncCurrentFBOByRecord` returns true, `UnitBindingsEpochFromRecords` answers,
|
||
`ResolveShaderImageRecord` returns non-null, `BindCurrentUnitSamplers` walks from records, and
|
||
`ResolveGlobalConstantsRecord` answers. A silent all-declining tree passes every gate below and
|
||
means this package did nothing. Recommend one temporary `MGLOG_D` per arm for the round, or the
|
||
`PipeStats` gate counters (`Gate::EsprytUnitBindingsEpoch` hit rate should go to 100%).
|
||
2. **Neither seam check fires.** `grep 'does not describe the binding it names'` in the itest and
|
||
retrace logs must be empty; a hit means a client emission is mis-keyed and is a **finding against
|
||
B/C**, not a reason to relax the check.
|
||
3. **G9** — `ctest --test-dir build-push -R 'TextureParamsWithoutASamplerView'`, and specifically
|
||
`AReadAttachmentOnlyTexturesDepthStencilModeReachesTheDriver` **green**, against package F's
|
||
recorded red-before log. This is the one deliverable of this package that has no gate on its own
|
||
tree.
|
||
4. **DEV-3, reconsidered with evidence**: on a tree that emits, compare
|
||
`MGB_CTX->GetMaxTouchedTextureUnit()` against `SamplerViewCount - 1` for a frame; if they agree
|
||
everywhere, `keys.maxTouchedUnit` can take the record in one line.
|
||
5. **DEV-6, reconsidered**: once package C documents `MGPImageView::Access`'s encoding, `e3` reads it
|
||
(one `#define`), and `ImageEmitTest.AnAccessModeChangeAloneStillEmitsTheSet` becomes the gate on
|
||
both sides.
|
||
6. **DEV-4 / A3**: once `d2` has re-keyed the twin's sync calls onto the record, move the unit
|
||
texture sync list's membership to `BoundSamplerViews` and drop the frontend binding walk.
|
||
7. **A1 / A2 / A4**: replace the `GetOrCreate(currentFBO)` fallback with `GetOrCreate(record.Fbo)`,
|
||
the four local arm latches with D's `Resolve<Family>SubsystemArm()`, and (if `d4` changed them)
|
||
the two `SyncToBackend` call signatures. Then re-run §7.2 whole.
|
||
8. **The full C.4 verification**: G1, `p3a_untouched_regions.sh`, **`p4a_untouched_regions.sh`**
|
||
(F's, including this file's two rows — note `DepthStencilSamplingReadImpl` is a **namespace**,
|
||
§6.1), `ctest -L unit` ×3, `-L integration-gpu` on all three arms, the C.4 family regex, G13's
|
||
greps, and `retrace_gate.py` on `build-push` and `build-verify`.
|
||
9. **Named traces**: `photon-v1.3b` on **llvmpipe desktop retrace** is G3b's canary for exactly the
|
||
image-binding semantics `e3` moves, and `improved-transparency-minecraft-26.3` is the draw-buffer
|
||
`None` net for `e1`. Neither can run here.
|
||
10. **The Track H census** (§2) is the input the phase owes `MEASUREMENTS.md`: **7 memos re-keyed**
|
||
(3 directly, 4 transitively through the epoch substitution), **0 retired** (the pre-handle arms
|
||
stay through P4a per `ARCHITECTURE.md:369`), **1 memo bypassed** on its record path
|
||
(`UnitSamplerLookupMemo`), **1 new** (`g_readFboTextureSyncList`, D-E3), and the frontend reads
|
||
listed per step.
|
||
|
||
---
|
||
|
||
## 9. Intermediate logs
|
||
|
||
Deleted, per ID-5 ("package logs `~/w7/p4a-<slug>-*.log` are deleted by their owner when the round
|
||
ends"): the five `~/w7/p4a-esprytdraw-*.log` tree-creation and first-build logs are gone, and so is
|
||
every `/tmp/p4ae-*` build, ctest and arm log this round produced. `~/w7/p4a-esprytdraw` itself holds
|
||
only `build-linux` and `build-push` (the `build-nolegacy` dir of §7.2 was removed after its one
|
||
compile). Nothing was written under `~/w7/notes/` except this file. The scratchpad's
|
||
`wsl/p4a-esprytdraw-*.sh` command scripts remain in the shared `wsl` directory, which ID-7 says
|
||
never to delete.
|