MobileGL/docs/archive/notes/p5e/scout-S2.md

S2 — textures and samplers under run-ahead (P5e scouting report)

Head 2fde7034. Paths under MobileGL/. "The record arm" = MOBILEGL_PIPE_PUSH + TextureResourceSubsystemEnabled() / SamplerSubsystemEnabled(). Headline. The SAMPLER half is already run-ahead-clean on its record arm, and SamplerImpl::ResolveSamplerCsoTwin (Managers.cpp:13457-13486) is the exact shape the TEXTURE half needs: handle in, record first, GetOrCreateByHandle, serial-gated sync, no frontend touch, no allocator probe. The texture half is one step behind — its three sync bodies already read the record and the staged store, but every one re-enters through g_backendTextureObjects.HandleOf(frontendObject) and the per-draw work list borrows frontend binding slots. No new record and no new wire field on the draw path; one signature, four line-level substitutions, one ruling.

1. The live reads at 2fde7034

live = frontend dereference; id = GetLifetimeId() + client allocator probe; mint = Acquire, a WRITE into it; rec = reads nothing frontend; hit = runs on every steady draw.

1.1 The per-draw keys — already server-owned, nothing to do

CaptureDrawTextureSyncKeys DirectGLES.cpp:2188-2211 reads GetTextureContextId :2189, GetMaxTouchedTextureUnit :2203, GetSamplingResolutionGeneration :2204 — rec, hit: the two generations are APPLIER_DERIVED (FieldOwnership.def:126-131), answered from MGPipeApplierTextureShutterSerial()/ContextSerial() under a server stamp (PipeInputs.h:490-527); the mark is RECORD_SUPPLIED via set_context_values (Coverage.def:260, MGPipeTypes.h:1694). CurrentUnitBindingsEpoch's record arm :2044-2071 -> UnitBindingsEpochFromRecords :2003-2042 reads the two counts and the two serials — rec, hit.

1.2 SyncNeccessaryTextures, unit half (:2321-2391)

site	read	kind
:2346 PairingsIntact(g_unitTextureSyncList)	per entry entry.slot->get(), a const SharedPtr<ITextureObject>* borrowed INTO the frontend unit's slot (:2127-2131, borrowed at :2381)	live, hit
:2356 IsDrawSyncClean(entry.slot->get(),...) -> Managers.h:1641-1658	GetTextureParamsVersion, GetContentVersion, GetSamplerObject()->GetVersion(), GetStorageType(); then :2358-2361 hands *entry.slot to the three syncs	live, hit
:2374-2382 memo MISS	GetTextureUnitObject(index)/unit, every GetAllBindingSlots() slot's GetBoundObject(), IsUndefinedDefaultTexture, SyncTextureObjectToBackend(obj)	live, id, mint

1.3 SyncTextureObjectToBackend (:1723-1806) and the three sync bodies

site	read	kind
:1734 scope, :1736 Find(obj), :1737 GetOrCreate(obj), and the re-resolve :1781,:1797	HandleOf -> GetLifetimeId + MGPipeSlots().FindByLifetimeId (SlotTables.h:430-450); miss mints (:244-250)	id, mint
:1757-1758 RequireImageBindableStorage(obj) -> Managers.cpp:5816-5975	HandleOf :5884, GetTarget :5888, GetUploadTargets/GetMipmapTexelSize/GetMipmapByteSize/MarkStorageDirty :5931-5940 — the last is ALREADY Fatal{RoleViolation,"texture-legacy-arm"} from the apply thread (MipmapStorage.cpp:39-51)	id, live
:1760 -> SyncTextureParamsToBackend Managers.cpp:8803+	prologue ResolvePushedTextureParams :8712-8743 = scope :8717 + HandleOf :8719; body :8876-8877 GetTarget() on both arms; :8841,:8874 GetExternalIndex (logs)	id, live
:1761 -> SyncBuiltinSamplerToBackend :8554+	prologue ResolvePushedBuiltinSampler :8472-8551 = scope :8481 + HandleOf :8483; body :8620-8621 GetTarget() on both arms	id, live
:1762 -> SyncMipmapsToBackend :7049+	:7060 IsTextureView() BEFORE the record is resolved; :7087 scope + :7089 HandleOf; :8223-8231 the Buffer arm's GetBufferBindingSlot().GetBoundObject(); GetExternalIndex in ~14 log lines. Everything else on the staged arm is the record + ServerStagedTexture() (:6902-6985)	id, live (4 sites)

1.4 BindCurrentTextures / ResolveAndBindUnitTextures

• :5277-5284 memo key: currentProgram->GetLifetimeId/GetBackendStateVersion/GetLinkStatus — live, hit (S4's rows; this memo is the consumer). :5290's memcmp vs g_boundTexturesCache is server memory — rec.
• :4861-4948 ResolveAndBindUnitTextures (memo MISS) — live, id: GetTextureUnitObject(unit) :4860, two passes over GetAllBindingSlots() :4876, GetBoundObject, IsUndefinedDefaultTexture :4884, GetExternalIndex :4886, GetTarget :4890, the alias arbiter sampledTargetForUnit :4845-4857 (GetMaxUniformLocation/GetUniformSamplerOrImageUnitIndex/GetUniformType), GetSamplerObject :4914-4916, SamplesAsIncompleteTexture :4918, scope :4926 + Find(obj) :4928, unbind walk :4945-4947 (GetTarget per slot).

1.5 The samplers

• BindCurrentUnitSamplers gate :5051-5059 (keys + g_boundSamplersCache) and record arm :5106-5151 (st.SamplerStateStart/Count/BoundSamplerStates[], UnbindSampler, ResolveSamplerCsoTwin) — rec, hit; already clean.
• decline arm :5152-5169: GetTextureUnitObject(unit).GetSamplerObject() :5157 -> ResolveUnitSamplerBackend :4988-5026 = scope :4993 + HandleOf :4999 — live, id.
• sampler pass in BindCurrentProgramWithResources :5562-5596 — live: GetTextureUnitObject(unit) :5562, GetSamplerObject :5563, GetBindingSlot(Texture2D).GetBoundObject() :5564-5565, samplerObject->GetLodBias() :5573, boundTexture->GetSamplerObject()->GetLodBias() :5580, texture2D->GetSamplerObject() :5591, texture2D->GetFormat() :5595.
• :5609-5620 CSO-twin arm — rec. :5624-5632 else arm: ResolveUnitSamplerBackend (id) then g_backendSamplerObjects.GetOrCreate(samplerObject) :5626 — mint, the only one left here.
• Off the steady draw path (waited ops under P5e-2): SyncTextureObjectToBackend from CopyImageSubData :8294-8295, GenerateMipmap :9575,:9578, the copy-endpoint resolve :9735, the texture ops :10046+, readbacks :11695,:11866; Find(texture.get()) at :8512,:8839,:9305,:9419,:11886.

2. What the records and applier state ALREADY carry

need	carrier	citation
which texture each unit samples, PROGRAM-RESOLVED, one per unit, no alias contest, with IsUndefinedDefaultTexture + SamplesAsIncompleteTexture already applied (entry -> null)	st.BoundSamplerViews[unit]={View,Texture,Unit}, SamplerViewStart/Count/Serial	PipeApply.h:673-676, MGPipeTypes.h:856-862, emitter SamplerEmit.h:733-789, the two drops :760-765
the frontend TARGET to bind, aliasing format, view restrictions, samples	SamplerViewCsos[View].View.{Target,InternalFormat,MinLevel..NumLayers,Samples,FixedSampleLocations}	MGPipeTypes.h:524-535, SamplerEmit.h:899-916
which sampler CSO each unit carries, and its 15 values (lodBias, filters, mipmapMode, compareMode, border) with a server-owned Serial	st.BoundSamplerStates[] + SamplerCsos[h].Params	PipeApply.h:335-341, :678-681, MGPipeValueTypes.h:462-486
a texture's params, built-in sampler CSO, the two resync bits; and its storage shape, target, format, levels, immutability, ImageBindableHint, ViewOf, texbuffer backing	TextureResources[h].Params+ParamsSerial, .Desc	PipeApply.h:265-281, MGPipeTypes.h:295-356, :548-566
"did storage/texels move", and the twin's own "what did I last sync"	.Serial + PendingUploads + ServerStagedTexture() defined/GPU-dirty; m_syncedResourceSerial, m_syncedParamsSerial, m_syncedBuiltinSamplerSerial+m_syncedBuiltinSampler	PipeApply.h:240-318, Managers.cpp:6902-6985, Managers.h:1785-1812
texture death by handle on the apply thread, no allocator; the handle-keyed adopt/recycle rule	object_death -> ReleaseTwinsForWireObjectDeath -> ReleaseByHandle; GetOrCreate(MGPipeHandle)/FindByHandle	Managers.cpp:328-337, SlotTables.h:278-341, :420-425, :488-506

The brief's two questions: yes, object_death covers textures since P5c ct (Managers.cpp:331-332); and the default texture (name 0) DOES have a record — TextureEmit.h:806-833 self-heals a create+respecify when its first set_texture_params is refused, written for exactly that case.

3. The gap

• G-S2-1 (a signature, not a field). No SyncTextureToBackendByHandle(MGPipeHandle); every entry takes const SharedPtr<ITextureObject>& and re-derives the handle with HandleOf. Needed: one handle-taking entry point + handle-taking prologues (ResolvePushedTextureParams(MGPipeHandle), ResolvePushedBuiltinSampler(MGPipeHandle)).
• G-S2-2 (four live reads inside the handle arm, all with an existing carrier). Managers.cpp:8876-8877 and :8620-8621 GetTarget() -> Desc.Target (via StagedTextureTargetForPipeTarget, :6905); :7060 IsTextureView() -> Desc.ViewOf (MGPipeTypes.h:356), record resolved first; :8223-8231 -> Desc.BufferForTexBuffer (already read at :8240). Plus G-S2-4: ~20 log lines print GetExternalIndex(); Desc.GlNameForDiag (MGPipeTypes.h:349) is the declared diagnostics carrier. Mechanical.
• G-S2-3 (no handle-arm clean gate). IsDrawSyncClean(const ITextureObject*,...) (Managers.h:1641-1658) has no record-keyed sibling, so the memo-HIT path is frontend-bound every draw. Needs no new state — see §4.
• G-S2-5 (RULING). RequireImageBindableStorage's re-dirty (Managers.cpp:5930-5962) reaches back into the client's storage model and already aborts under split; ImageBindableHint is the prevention and P9 owns the pull, so P5e should delete the frontend argument and leave the split arm a NAMED refusal at the entry, not build half a terminator.
• G-S2-6 (narrowing, needs the integrator's word). Driving the unit list off BoundSamplerViews syncs only the program-resolved texture per unit, where today the walk syncs every slot of every touched unit. The union of (views + image units + the FBO attachment lists + the waited texture ops) still covers every texture anything reads, so this narrows WORK, not coverage — but it is a behaviour delta against the monolith arm and must be named under G1.

4. The retirement design

Twin key. g_backendTextureObjects stays one table; every draw-path resolution becomes GetOrCreateByHandle(view.Texture) / FindByHandle(view.Texture). HandleOf, Find(StateObject*) and GetOrCreate(const StatePtr&) become unreachable from the apply thread, so the existing MGPipeRefuseAllocatorFromApplyThread guards (SlotTables.h:255-266, :436-441) stop being scope-exempted here, and this family's MGPipeFrontendKeyedRegistryScope sites — DirectGLES.cpp:1734, :4926, :4993, Managers.cpp:5882, :7087, :8481, :8717 — are deleted, not moved. Sync shape (the ResolveSamplerCsoTwin template, Managers.cpp:13457-13486):

BackendTextureObject* SyncTextureToBackendByHandle(MGPipeHandle res, Bool imageBindable) {
    const auto* rec = PipeTextureRecordForHandle(res);       // record FIRST; null -> named decline
    auto* slot = rec ? g_backendTextureObjects.GetOrCreateByHandle(res) : nullptr; // adopt/recycle by Gen
    if (!slot) return nullptr;                               // backward Gen -> named decline
    if (!*slot) *slot = MakeShared<BackendTextureObject>();
    (*slot)->SyncTextureParamsToBackend(res, *rec); (*slot)->SyncBuiltinSamplerToBackend(res, *rec);
    (*slot)->SyncMipmapsToBackend(res, *rec);
    if ((*slot)->NeedsParameterResync()) { /* params; builtin */ }
    return slot->get();
}

The by-value twin copy + second Find (:1745-1755, :1781-1805) go with the map arm: a slot entry is an array element, so the nested-glTextureView relocation hazard is answered by re-indexing, not by a refcount. "Is it clean" from server-owned serials. IsDrawSyncCleanByRecord(res, rec) is EXACTLY the conjunction of the three handle-arm prologues' own early-outs — the relation Managers.h:1626-1640 already states for the frontend version:

m_isInitialized && m_syncedResourceSerial != 0 && m_syncedResourceSerial == rec->Serial   // :7133-7139
&& rec->PendingUploads.empty()
&& m_syncedParamsSerial == rec->ParamsSerial && rec->Params.ForceResync == 0 && !m_forceTextureParamsResync
&& m_syncedBuiltinSampler == rec->Params.BuiltinSampler                                   // :8735-8741
&& m_syncedBuiltinSamplerSerial == PipeSamplerCsoRecordForHandle(rec->Params.BuiltinSampler)->Serial
&& rec->Params.SamplerResync == 0 && !m_forceSamplerResync                                // :8539-8548
&& (TextureStorageType)rec->Desc.StorageKind == TextureStorageType::Mipmap

No new member, no new field. The contextId/samplingGeneration arguments disappear: the applier's ContextSerial and TextureShutterSerial (PipeApply.h:697-717) are what the keys already carry.

The unit work list and the bind. UnitTextureSyncEntry (:2127-2132) becomes {MGPipeHandle Res, BackendTextureObject* backend}; the memo key becomes (ContextSerial, SamplerViewsSerial, SamplerViewStart, SamplerViewCount, g_backendContextGeneration) — SamplerViewsSerial moves iff the resolved set moved, which the emitter's content-hash suppressor (SamplerEmit.h:692-697) makes sound — and PairingsIntact is deleted: no borrowed slot is left to go stale. The rebuild walks st.BoundSamplerViews[Start..Start+Count) calling SyncTextureToBackendByHandle. ResolveAndBindUnitTextures collapses to one pass over the same window: FindByHandle(entry.Texture), target from SamplerViewCsos[entry.View].View.Target, bind; then unbind every backend target the window did not claim, driven by the fixed TextureTarget enum plus g_boundTexturesCache (server memory) instead of GetAllBindingSlots(). The alias arbiter sampledTargetForUnit :4845-4857 DIES — the client already arbitrated (SamplerEmit.h:751-757).

The sampler pass :5562-5596. The unit's effective sampler becomes st.BoundSamplerStates[unit] if non-null, else TextureResources[view.Texture].Params.BuiltinSampler; its values come from the CSO record (lodBias, minFilter, magFilter, mipmapMode, compareMode all present, MGPipeValueTypes.h:462-486), and texture2D->GetFormat() becomes SamplerViewCsos[view.View].View.InternalFormat. The raw-depth-fetch substitution itself STAYS on the server (docs/Disaggregated/ARCHITECTURE.md §5.5 assigns it there by name). :5624-5632's GetOrCreate(samplerObject) is deleted; the CSO-twin arm :5609-5620 is the only arm left. Finally the two decline arms — BindCurrentUnitSamplers :5152-5169 and CurrentUnitBindingsEpoch :2073-2098 — become named refusals under a live wire instead of falls-back to GetTextureUnitObject, and with them gone CaptureUnitBindings/UnitBindingsUnchanged/g_observedUnitBindings (:1867-1957) are monolith/legacy-only text.

5. Monolith / G1

Every edit sits inside #if MOBILEGL_PIPE_PUSH and, for the run-ahead arms, behind MG_Config::Transport != MG_Config::TransportMode::Monolith — the idiom already at DirectGLES.cpp:3226, :4725, :6534. The pull build keeps :1936-1957, :2073-2098, :2340-2391, :4861-4948, :5152-5169, :5624-5632 token for token, the D-P rule this family already follows (Managers.cpp:8613-8618, :8791-8800 spell the #if/#else arm split and why a shared prologue is a G1 failure). Three obligations: (1) BackendTextureObject's pull-build layout must not move — every member the new gate needs is already inside #if MOBILEGL_PIPE_PUSH (Managers.h:1785-1812), so the admitted-resize set stays empty; (2) UnitTextureSyncEntry's re-shape is push-only, two structs under one name selected by #if, which g_fboTextureSyncListRecordKeyed (:2157-2171) already does; (3) the push build under Transport=monolith must KEEP the frontend walk — no server to answer from — so the run-ahead arm is a THIRD arm, like MGB_STAGED_TEXTURE_LIVE (:6902-6903). MOBILEGL_PIPE_VERIFY forces the lockstep, so the comparator keeps seeing both.

6. Red-once

1. Widen the pinned guard list. MG_Test/Wire/RemoteClientTest.cpp:1938-1941 deliberately EXEMPTS the shape reads — "GetMipmapTexelSize / GetMipmapByteSize / GetMipmapLevelCount / GetUploadTargets / GetTarget / IsComplete ... the per-draw binding walk reads them every draw". P5e adds those six plus GetSamplerObject/GetTextureParamsVersion/GetContentVersion to RefuseLegacyTextureArmFromApplyThread (MipmapStorage.cpp:39-51) and its MGL_TEXTURE_GUARD_TEST rows :1942-1978. Revert the handle arm -> each aborts by name.
2. Fatal{UnmigratedPipeInput,"GetTextureUnitObject@DrawVbo"} under MOBILEGL_IPC_STRICT_ERRORS=1 (PipeInputs.cpp:71-77, :191-224), where the row is BARRIER_PULLED and the read today only counts as rsp: revert ResolveAndBindUnitTextures' window arm -> strict lane red at the named field+verb. 3. And an integration assertion over PipeSlotPeek (MG_IntegrationTest/Harness/PipeSlotPeek.h) that MGPipeFrontendKeyedRegistryScope entries for this family are 0 over a frame; the mint is already Fatal{RoleViolation,"MGPipeSlots"} (SlotTables.h:255-266).
3. DirectGLESTextureSync.UnitMemoRefusesToDriveATwinFromAnotherTexture (MG_Test/SanityTest.cpp:3075-3144) is the PairingsIntact pin: keep it for monolith/pull, and give it a handle-arm sibling whose hazard is ABA — recycle the slot to {slot, gen+1} while the old entry is in the work list, assert the twin is re-minted (SlotTables.h:316-340's forward/backward rule answers it).
4. TextureParamsWithoutASamplerViewScenario stays green (the D10/G9 pin), i.e. the view window must not become the ONLY path into SyncTextureParamsToBackend; and SampledSetStalenessScenario — a texture that becomes complete with no rebind must re-enter the sampled set, which under the new key is SamplerViewsSerial moving; revert Tracker.h:605-610's textureParams mix -> red.

7. Risks and what I could not settle

• R1 — the window is not pinned (A8). Everything in §4 reads [SamplerViewStart, +SamplerViewCount). SamplerEmit.h:735-737 emits Start=0, Count=maxTouched+1, but PipeApply.h:666-669 says only "the last set as received" and does not require coverage; under run-ahead a too-narrow window silently drops a sync, and a decline is what run-ahead cannot take. P5e needs a contract sentence: the window MUST cover [0, MaxTouchedTextureUnit], narrower is Fatal{ProtocolCorruption,"SetSamplerViews.Count"} — not a server-side re-derivation.
• R2 — the program key (conflict with S4). BindCurrentTextures' memo :5277-5284 reads the frontend ProgramObject; my design deletes the alias arbiter but not that key. Ruling needed: key it on st.DrawProgram + ProgramBindingSerial (S4's rows), or on SamplerViewsSerial alone — which already mixes the program-resolved opaque units (Tracker.h:605-610)? I lean to the latter (one fewer cross-family key) but could not rule out that a relink with unchanged resolution must still re-bind.
• R3 — RequireImageBindableStorage under run-ahead. §3 G-S2-5. It aborts today, but three frames deep at a MarkStorageDirty guard rather than as a named refusal at the entry; run-ahead turns a decline into a hard stop. How often ImageBindableHint fails to prevent it is unmeasured.
• R4 — the twin's mutable flags. m_forceTextureParamsResync/m_forceSamplerResync are server-set and read-not-cleared from the wire (D-E2) — server memory, safe — but the new gate reads BOTH them and the wire bits, so "neither side clears the other's" becomes load-bearing for a gate, not just for a push. One contract sentence.
• R5 — buffer textures. Managers.cpp:8223-8231 still hands the frontend BufferObject to EnsureBufferResourceForHandle (D-A4's frontend argument). Desc.BufferForTexBuffer names the buffer; whether frontend may be nullptr under split is S1/S5's call — the E note says the transport arm reads nothing from the object (Managers.cpp:3199+), which suggests yes.
• R6 — unmeasured. This family's share of the apply thread at 2fde7034 is unknown; the E note's 3.0% HandleOf<ITextureObject> is at 85362a85, pre-round-3. Re-measure before sizing.