mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-20 08:21:56 +09:00
- CONTRACT-P5E §2.3. EmitAndWaitTails now switches on the generated WaitClass column
when RunAheadArmed(): kWaitNone and kWaitPresent return at the publish, kWaitApplied
waits and then releases the fill pins, and a reply row is unchanged. It REPLACES the
BatchWaits skip rather than layering on it - the batch rule reads the call CLASS and
this one reads what an apply READS, and the server's MGPipeBarriered reads the second,
so two rules layered is two halves of the wire disagreeing about whether the client is
parked.
- §1: RunAheadArmed() = barrierArmed && Ipc.RunAhead && Caps().HasCap(kCapRunAheadApply),
latched at the first caps adoption after Start and demotable but never promotable - a
record already published without a wait cannot be un-published. A knob set against a
server that does not publish the bit logs once and runs lockstep.
- §2.4: MGPPresent::FrameSerial is minted client-side, 1-based, by AcquirePresentCredit,
which pays the credit BEFORE the encode (a client that encoded first would hold a
SEG_CMD reservation across the park). ServerVerbSink::OnPresent returns one credit per
swap through ServerSession::ReturnPresentCredit, which has had no production caller
since v1 wrote it; serial 0 on a run-ahead server is Fatal{ProtocolCorruption,
"Present.FrameSerial"}. The stats line and the wire ledger gain credit-waits.
- §2.5, the drains and the forced waits: every wait exit drains SEG_EVENT (the applied
wait, the present-ack wait, the cmd-space wait and - through a hook the session lends
the encoder - the stage bell); glFinish becomes WaitForApplyToCatchUp, since "the
commands issued so far have completed" is a promise a queue nobody waits on can break;
every Server* EGL forwarder waits first, because the control mailbox is pumped BETWEEN
drain batches and a make-current landing between two run-ahead records is not a wrong
pixel but a wrong everything. ServerSwapEGLBuffers is not on that list: present is the
swap.
- §2.5 / ruling 15 (ID-93): resource_subdata's BUFFER half stops waiting. The row keeps
kReplySlot, the server still posts, and the slot is never read - which is what makes
the 64 KB persistent-map push fire-and-forget instead of a hidden round trip per block.
MGPipeSubDataWantsItsReply is the one predicate, read by the route and by the emit
table, so the two cannot disagree about whether a wait is owed. The texture half keeps
its reply: DrainTextureSubData clears a level's dirty flag on the accepted answer.
- §3: gPipeInputs becomes server-role memory for unbarriered records. The tracker walk
and the emitters still run - they produce records - but the serial bump, the verb
stamp, the server-stamp withdrawal and the whole of step 4 do not, and
MGPipeNoteFrontendMutation / MGPipeLeaveVerb return instead of writing. `fillOwed` is
a separate name from `barriered` on purpose: the red-once is that one line.
- §3.3: MGPipeInputUnfreshRead's counter becomes an UNCONDITIONAL abort under an
unbarriered record, knob or no knob, because the value is torn or stale by
construction and there is nothing for a counter to count. The marker gains its reason
so the lane's allowlist can tell the two apart.
- §3.5: RefusePipeInputsTouchWhileApplierOwnsIt is re-derived - under run-ahead the rule
is "not at all unless you are the barriered fill", and the BatchWaits early return
goes with the argument that justified it.
- §2.3's ReleaseFillPins drops the four O-class SharedPtr rows once a barriered apply
returns: under lockstep the next fill overwrote them within a verb, under run-ahead a
pinned VAO can make the apply thread its last owner a frame later.
- §2.7 / ruling 13 (ID-91): the deferred-destroy queue stays live, and an enqueue from
an UNBARRIERED apply is now a named finding - loud once, Fatal under strict.
- NAMED DEVIATION from §3.1: the identity/liveness pair is still written on every verb.
It is not a field of the residual model - no ownership row owns it, no record carries
it, no server stamp can answer it - it is "does this process still have a GL context",
which only this thread knows and every null-context guard reads.
- Inert until the integration commit: RunAheadArmed() is false while
kMGPipeP5eRunAheadReady is, so every branch above answers as it did before.
485 lines
33 KiB
C++
485 lines
33 KiB
C++
// MobileGL - MobileGL/MG_Pipe/PipeMutation.h
|
|
// Copyright (c) 2025-2026 MobileGL-Dev
|
|
// Licensed under the GNU Lesser General Public License v3.0:
|
|
// https://www.gnu.org/licenses/gpl-3.0.txt
|
|
// https://www.gnu.org/licenses/lgpl-3.0.txt
|
|
// SPDX-License-Identifier: LGPL-3.0-only
|
|
// End of Source File Header
|
|
|
|
#pragma once
|
|
#ifndef MOBILEGL_MG_PIPE_MUTATION_H // belt and braces: reachable as <MG_Pipe/..> and <..>
|
|
#define MOBILEGL_MG_PIPE_MUTATION_H
|
|
// Push-on-mutation (P1 lane finding F2). MGP_FILL copies a verb's may-read set out of the
|
|
// live GLContext at the verb boundary; the backend then reads that copy for the whole verb.
|
|
// A backend that WRITES a frontend object inside its own verb - Magma synthesising a
|
|
// fallback texture for an unbound sampler, materialising a queued clear, or overriding a
|
|
// sampler's filter - moves a value the boundary already copied, and every read after that
|
|
// point sees a block that no longer equals the live context. That is a real divergence, not
|
|
// a harness artefact: the pull build reads the moved value and the push build does not.
|
|
//
|
|
// The frontend mutator that moves such a value spells MGP_NOTE_MUTATION(Field) right where
|
|
// it moves it. The notice refreshes that ONE field in the pushed block when the field
|
|
// belongs to the verb currently in flight, so "the pushed block equals the live context at
|
|
// every read" stays literally true and the push build keeps pull semantics. It refreshes
|
|
// the value only and never the poison stamp, so a withheld stamp (MOBILEGL_PIPE_POISON_OMIT,
|
|
// negative control B) stays withheld.
|
|
//
|
|
// In the pull build the macro is ((void)0) and this header includes nothing, so the pull
|
|
// build is byte-identical to a tree without it.
|
|
#if MOBILEGL_PIPE_PUSH
|
|
#include <MG_Pipe/MGPipe.h>
|
|
namespace MobileGL::MG_Pipe {
|
|
// MG_Impl/Pipe/PipeFill.cpp (the client side, the only place that may spell pGLContext).
|
|
// A no-op unless a context is live, a verb has been filled, and `field` is in that verb
|
|
// class's may-read mask; a forwarded (sticky) field has no storage and is never copied.
|
|
void MGPipeNoteFrontendMutation(MGPipeInputField field);
|
|
|
|
// ---- the aggregate generations (P2 brief D4, ARCHITECTURE.md 5.2) ----
|
|
//
|
|
// MGP_NOTE_MUTATION answers "a backend moved a frontend value INSIDE its own verb".
|
|
// MGP_NOTE_AGGREGATE answers a different question, which is why it is a second macro
|
|
// and not an overload: "did ANY object of this class move since the last time the
|
|
// tracker looked", collapsed onto one monotonic Uint64 per class so a per-verb dirty
|
|
// walk is a handful of compares rather than a scan over 32 attributes, 16 attachments,
|
|
// 32 texture units and 84 binding points.
|
|
//
|
|
// The counters are members of the owning MG_State container, all guarded by
|
|
// MOBILEGL_PIPE_PUSH so the pull build's state objects do not change size (G1). The
|
|
// bump points sit on OBJECTS, which have no back-pointer to their state, so the macro
|
|
// goes through a free function that finds the live GLContext - the same shape, and for
|
|
// the same reason, as MGP_NOTE_MUTATION (MG_Impl/Pipe/PipeFill.cpp). It costs a global
|
|
// load on a path that has just written object state.
|
|
//
|
|
// Monotonic and never reset: the tracker widens and compares, it never subtracts.
|
|
// Over-firing is free (one extra re-push); under-firing renders stale, which is why
|
|
// every counter here is deliberately COARSER than the state it guards.
|
|
enum class MGPipeAggregate : Uint32 {
|
|
// VertexArrayState: any VAO attribute format / buffer / enable moved.
|
|
VaoAttribute = 0,
|
|
// FramebufferState: any FBO attachment or default-geometry write, or a bind - and, since
|
|
// P4a (fable seam F-3), any STORAGE DEFINITION of a texture or a renderbuffer, because
|
|
// set_framebuffer_state inlines an attachment's format, extent and samples and those
|
|
// setters are the only writers of what it inlines (TextureObject.cpp /
|
|
// RenderbufferObject.cpp, PipePublishDescriptor).
|
|
FramebufferAttachment,
|
|
// TextureState: any texture object CONTENT moved (an upload, a dirty region).
|
|
TextureContent,
|
|
// TextureState: any texture object or sampler object PARAMETER moved.
|
|
TextureParams,
|
|
// BufferState: any buffer object contents moved.
|
|
BufferChange,
|
|
// GLContext: a glVertexAttrib* default value moved. Not one of D4 five: the bit it
|
|
// shutters (NEW_VERTEX_ATTRIB_DEFAULTS) is specified there as a ContentHash over
|
|
// all 32 CurrentVertexAttributeValues, and hashing 768 bytes on EVERY draw does not
|
|
// fit inside the T1 ceiling. The hash still decides whether to EMIT (D11 set-hash
|
|
// suppressor); this decides whether to hash at all.
|
|
VertexAttribDefault,
|
|
Count,
|
|
};
|
|
|
|
// MG_Impl/Pipe/PipeFill.cpp. A no-op unless a context is live.
|
|
void MGPipeNoteAggregate(MGPipeAggregate aggregate);
|
|
|
|
// ---- P3a: the resource family's emission points (brief D-A1) ----
|
|
//
|
|
// The seven BufferBackendOps hooks already dispatch at the GL call that causes them
|
|
// (ARCHITECTURE.md 5.1 names them as the ONE exception to push-at-validate), so their
|
|
// pipe calls are emitted from the same BufferObject dispatchers rather than from the
|
|
// validate point. That puts the emission inside MG_State, which is why these are
|
|
// DECLARED here beside the two notices and DEFINED in MG_Impl/Pipe/PipeFill.cpp: this
|
|
// header is the one MG_State already includes for exactly this, and the closure gate
|
|
// (check_include_closure.py's mutation-header probe) keeps it a declaration - reaching
|
|
// MG_Impl/Pipe/ResourceTracker.h from BufferObject.cpp would pull the client's tracker
|
|
// into the state machine that calls it.
|
|
//
|
|
// The forward declaration is the whole coupling: none of these needs the definition of
|
|
// BufferObject, and this header must not gain it.
|
|
} // namespace MobileGL::MG_Pipe
|
|
|
|
namespace MobileGL::MG_State::GLState {
|
|
class BufferObject;
|
|
// P4a's five, for the BIRTH half at the tail of this header. Declarations only, exactly as
|
|
// BufferObject is: none of the hooks below needs a definition, and this header must not
|
|
// gain one - reaching a frontend class header from here would put the state machine's own
|
|
// types in front of every mutator that spells MGP_NOTE_MUTATION.
|
|
class ITextureObject;
|
|
class RenderbufferObject;
|
|
class FramebufferObject;
|
|
class SamplerObject;
|
|
class ProgramObject;
|
|
}
|
|
|
|
namespace MobileGL::MG_Pipe {
|
|
// (Features.PipePush & kMGPipeSubsystemResources) != 0 && MGPipeGetResourceOps() != nullptr.
|
|
//
|
|
// BOTH HALVES MATTER. The bit is the operator's per-subsystem A/B; the table is "has a
|
|
// backend taken this family over at all". Until one has, every dispatch below falls
|
|
// through to the BufferBackendOps table it replaces and the tree behaves exactly as it
|
|
// did - which is what lets the client half land on its own.
|
|
Bool MGPipeResourceSubsystemEnabled();
|
|
// The nullable member, asked the way the frontend asks g_bufferBackendOps->ResidentSubData
|
|
// today: one backend deliberately does not implement it and the caller has a different
|
|
// path when it is absent (BufferObject::FillSubData).
|
|
Bool MGPipeResourceOpsHaveSubDataResident();
|
|
|
|
// Minted from the constructor and released from the destructor, both unconditionally in
|
|
// a push build: a handle is CLIENT state and set_vertex_buffers names it whether or not
|
|
// the resource family is switched on. The CALLS are what the predicate above gates.
|
|
void MGPipeMintResourceHandle(MG_State::GLState::BufferObject& buffer);
|
|
// In this order, and it is not negotiable (D-L): the destroy resolves the handle, and
|
|
// MGPipeSlotAllocator::Free erases the lifetimeId -> slot mapping it resolves through.
|
|
//
|
|
// RETURNS whether resource_destroy was emitted, which is the LATCH taken at this buffer's
|
|
// create and not a second reading of MGPipeResourceSubsystemEnabled(). The destructor
|
|
// needs that answer to decide whether the legacy OnDestroy still owes a call: asking the
|
|
// predicate twice pairs a create emitted under one registration with a destroy gated on
|
|
// another, and either direction leaks - a live applier record on a slot about to be
|
|
// re-handed-out, or a backend object nobody releases.
|
|
Bool MGPipeEmitResourceDestroyAndFree(MG_State::GLState::BufferObject& buffer);
|
|
|
|
// THE VERTEX-ELEMENTS CSO's DEATH, and it is BACKEND-NEUTRAL - which is the whole point.
|
|
// Before this, the only thing that ever returned a VertexElementsCso slot was DirectGLES'
|
|
// StateObjectDeathOps table; under any backend that installs none - DirectVulkan/Magma,
|
|
// which keeps its own age-reclaimed identity table on purpose - every VAO ever created
|
|
// held its slot and its ~1.3 KB applier record for the life of the process, on the shipped
|
|
// 0x1ff mask, and past 65536 slots every create_vertex_elements became a permanent
|
|
// Fatal{ProtocolCorruption}. The client mints the slot, so the client is where the death
|
|
// has to be spoken from.
|
|
//
|
|
// Takes the lifetime id and not the object for StateObjectDeathNotice.h's reason: the last
|
|
// SharedPtr has already dropped by the time this runs, and the lifetime id is what the
|
|
// slot allocator resolves the handle from. Returns whether delete_vertex_elements went
|
|
// out, i.e. whether the applier actually held a record - see the definition for why that
|
|
// is asked rather than assumed.
|
|
Bool MGPipeEmitVertexElementsDestroyAndFree(Uint64 lifetimeId);
|
|
|
|
// ---- P4a: ONE CLIENT-SIDE DEATH HELPER PER KIND P4a MINTS (brief D-I1) ----
|
|
//
|
|
// BACKEND-NEUTRAL FROM DAY ONE, and this is the P3a final-review lesson taken forward
|
|
// rather than repeated. Before it, the only thing that ever returned a VertexElementsCso
|
|
// slot was DirectGLES' StateObjectDeathOps table; under a backend that installs none -
|
|
// DirectVulkan/Magma, which keeps its own age-reclaimed identity table on purpose - every
|
|
// VAO ever created held its slot and its applier record for the life of the process, and
|
|
// past 65536 slots every create became a permanent Fatal{ProtocolCorruption}. P4a mints
|
|
// SIX kinds, so the rule is stated once and obeyed six times: whatever mints a handle owns
|
|
// the death of that handle, the client mints all six, and a backend death notice is a
|
|
// redundant SECOND path that must be idempotent - which it is, because it resolves through
|
|
// the same lifetimeId -> slot map these free, and MGPipeSlotAllocator::Free refuses a slot
|
|
// that is not live at that generation.
|
|
//
|
|
// THE ORDER INSIDE EACH IS FIXED AND IS NOT A PACKAGE'S CHOICE:
|
|
// 1. emit the wire delete FIRST - it drops the applier's record while the record still
|
|
// exists, so a recycled slot cannot inherit a field;
|
|
// 2. raise NotifyStateObjectDestroyed SECOND - it resolves the handle through the
|
|
// allocator, and a backend told after the Free could no longer find its twin, which
|
|
// moves the leak from the client to the driver object;
|
|
// 3. free the slot LAST, and a double free on a stale generation is a proven no-op
|
|
// because Free bumps no generation (the bump rides the next handout).
|
|
//
|
|
// ALL SIX TAKE THE LIFETIME ID rather than the object, for MGPipeEmitVertexElementsDestroy
|
|
// AndFree's reason: they run from a destructor, where the last SharedPtr has already
|
|
// dropped, and the lifetime id is what the slot allocator resolves the handle from. It is
|
|
// also what keeps this header a declaration-only coupling - no frontend class needs
|
|
// forward-declaring for any of them.
|
|
//
|
|
// Each returns whether its wire delete actually went out, which is the LATCH taken at the
|
|
// object's create and not a second reading of the subsystem predicate: an object born
|
|
// while a subsystem bit was clear and destroyed after it was set would otherwise free its
|
|
// slot with the applier's record still Live, on a slot about to be handed out again. The
|
|
// legacy path runs only when the answer is false.
|
|
|
|
// ResourceDestroy, and then the SamplerViewCso minted off this same lifetime id (P4a
|
|
// D-F2: one sampler view per ITextureObject). Called from TextureObjectBase's VIRTUAL
|
|
// destructor, so 2D / 3D / cube / buffer / view all announce exactly once.
|
|
Bool MGPipeEmitTextureDestroyAndFree(Uint64 lifetimeId);
|
|
// ResourceDestroy.
|
|
Bool MGPipeEmitRenderbufferDestroyAndFree(Uint64 lifetimeId);
|
|
// NO WIRE CALL AT ALL (D-I2). PipeCalls.def has no framebuffer delete, because a
|
|
// framebuffer is not a resource and is not a CSO - it is STATE, and set_framebuffer_state
|
|
// is the only call that names one - and the catalogue is closed, so P4a does not invent a
|
|
// row. The handle is minted and freed entirely client-side and this helper does steps 2
|
|
// and 3 only. A recycled framebuffer handle is distinguished by Gen, which is inside the
|
|
// record's ContentHash, so it can never be suppressed against its predecessor's record.
|
|
Bool MGPipeEmitFramebufferDestroyAndFree(Uint64 lifetimeId);
|
|
// DeleteSamplerState. Also the path the content-addressed CSO cache's LRU eviction takes,
|
|
// which is why it is addressed by lifetime id and not by "the object that owns it".
|
|
Bool MGPipeEmitSamplerCsoDestroyAndFree(Uint64 lifetimeId);
|
|
// DeleteSamplerView. Called by the texture helper above; a sampler view has no frontend
|
|
// object of its own, so this is the only path there is.
|
|
Bool MGPipeEmitSamplerViewCsoDestroyAndFree(Uint64 lifetimeId);
|
|
// DeleteShaderState, for an ordinary program AND for a program-pipeline COMPOSITE, whose
|
|
// slot has two independent release paths - the pipeline cache's LRU eviction and the
|
|
// composite ProgramObject's own destructor. One helper for both, and the second call is a
|
|
// proven no-op.
|
|
Bool MGPipeEmitShaderCsoDestroyAndFree(Uint64 lifetimeId);
|
|
|
|
#if MOBILEGL_BUILD_DISAGGREGATED
|
|
// ---- THE DEFERRED DESTROY QUEUE (the MOBILEGL_IPC_BATCH_WAITS class) ----
|
|
//
|
|
// Every helper above speaks on the CLIENT's behalf: it resolves the handle through the
|
|
// client allocator, emits a client wire record and frees a client slot - so it may only
|
|
// ever run on the GL thread. The per-record barrier made that free: the client waited
|
|
// out every apply, so a server-side SharedPtr (an applier's endpoint local, a
|
|
// gPipeInputs entry) could never be an object's last owner. Batched waits remove the
|
|
// guarantee - the client races ahead, drops its own references at teardown, and the
|
|
// apply thread's local CopyImageEndpoint becomes a texture's last owner, whose
|
|
// destructor then touches the client allocator from the server role
|
|
// (Fatal{RoleViolation, "MGPipeSlots"}). The helpers therefore START with
|
|
// MGPipeDeferDestroyAndFreeIfOnApplyThread: on the apply thread it enqueues the
|
|
// (kind, lifetime id) pair - the only thing a death announcement needs - and the GL
|
|
// thread replays the helper at the next verb hook (EmitTables' BeforeDrawVerb /
|
|
// BeforeReadOnlyVerb) through MGPipeDrainDeferredDestroys. A delayed free is safe:
|
|
// slots are plentiful, reuse is delayed rather than corrupted, and the replay runs the
|
|
// helper itself, so every helper's own three-step order is untouched.
|
|
// P5e (ra), CONTRACT-P5E §2.7 / ruling 13 (ID-91): THE QUEUE STAYS LIVE, AND AN
|
|
// UNBARRIERED ENQUEUE IS A FINDING. After the family packages land, an unbarriered apply
|
|
// holds no frontend SharedPtr at all - every object is resolved from a handle - so the
|
|
// only apply thread that can still be a last owner is one inside a BARRIERED record (a
|
|
// fill's O-class rows, XFB's pinned targets). An enqueue from an unbarriered record
|
|
// therefore means some site still pins a frontend object across a record, which is a
|
|
// migration this phase believes it finished: it logs once with the kind, and is Fatal
|
|
// under MOBILEGL_IPC_STRICT_ERRORS so the strict lane owns the red. The queue itself is
|
|
// NOT removed - it is the belt that keeps the barriered case from corrupting the
|
|
// allocator while the finding is being read.
|
|
Bool MGPipeDeferDestroyAndFreeIfOnApplyThread(MGPipeKind kind, Uint64 lifetimeId);
|
|
void MGPipeDrainDeferredDestroys();
|
|
|
|
// P5e (ra), CONTRACT-P5E §2.3: drop the four O-class SharedPtr rows the residual fill left
|
|
// in gPipeInputs (the bound VAO and the three programs, PipeInputs.h's O block). Called by
|
|
// ClientSession on the GL thread once a BARRIERED apply has returned - the one instant
|
|
// under run-ahead at which the applier is provably idle and this block has no other
|
|
// reader. Under lockstep nothing calls it: the next verb's fill overwrites those rows
|
|
// within a verb, and dropping them early would only cost a re-pin.
|
|
//
|
|
// It is HERE rather than in ClientSession because the rows are PipeInputs' private storage
|
|
// and MGPipeFillAccess - the client-side door to it - lives in MG_Impl (PipeFill.cpp).
|
|
// MG_Remote says when; MG_Impl says what.
|
|
void MGPipeReleaseResidualFillPins();
|
|
|
|
// P5e (ra), CONTRACT-P5E §2.5: glFinish's whole body under a transport. Declared here
|
|
// rather than on ClientSession so that MG_Impl's GL entry points - which are BELOW
|
|
// MG_Remote - can reach it without learning that a session exists; the implementation in
|
|
// PipeFill.cpp is one forward to ClientSession::Finish. A no-op with no live session, on a
|
|
// monolith transport, and on a lockstep one (there the client waited out every command it
|
|
// issued before it could reach the call).
|
|
void MGPipeClientFinish();
|
|
#endif
|
|
|
|
void MGPipeEmitResourceCreate(MG_State::GLState::BufferObject& buffer);
|
|
void MGPipeEmitResourceRespecify(MG_State::GLState::BufferObject& buffer);
|
|
void MGPipeEmitResourceSubData(MG_State::GLState::BufferObject& buffer, SizeT offset, SizeT size);
|
|
void MGPipeEmitBufferSubDataResident(MG_State::GLState::BufferObject& buffer, SizeT offset,
|
|
const void* bytes, SizeT size);
|
|
void MGPipeEmitResourceFlushRange(MG_State::GLState::BufferObject& buffer, SizeT offset, SizeT size,
|
|
Uint32 accessFlags);
|
|
void MGPipeEmitResourceReadback(MG_State::GLState::BufferObject& buffer);
|
|
// The ranged form, for the split arm's sliced whole-buffer readback: the writeback's
|
|
// bytes travel INLINE in a SEG_EVENT record, so a buffer larger than the ring can hold
|
|
// is read back as [offset, offset+size) slices, each its own record. Monolith never
|
|
// calls it - the direct callback carries a pointer, not a copy.
|
|
void MGPipeEmitResourceReadbackRange(MG_State::GLState::BufferObject& buffer, SizeT offset, SizeT size);
|
|
// Returns the coherent host pointer the resource owner donated, or null for a DECLINE -
|
|
// which is a real answer. Every call, mint or decline, is one map-persistent roundtrip.
|
|
void* MGPipeEmitMapPersistent(MG_State::GLState::BufferObject& buffer);
|
|
|
|
// ================================================================================
|
|
// P4a: THE BIRTH HALF, one hook per client path MG_State owns (D-C .. D-I)
|
|
// ================================================================================
|
|
//
|
|
// The death helpers above are half a lifetime. The other half is emitted from MG_State
|
|
// too - a texture's create from its constructor, a renderbuffer's respecify from its
|
|
// storage mutators, a texture's params from glTexParameter*, a sampler CSO from the
|
|
// sampler object, a shader CSO from the program - because that is where the event
|
|
// happens, exactly as P3a's buffer family emits from BufferObject's own dispatchers
|
|
// (ARCHITECTURE.md 5.1 names those as the ONE exception to push-at-validate). Only the
|
|
// texture sub-data DRAIN runs at the validate point, and even it is fed from here: the
|
|
// drain list is appended on a level's first dirty mark.
|
|
//
|
|
// WHY THEY ARE DECLARED HERE. This header is the one door MG_State has into the client
|
|
// (check_include_closure.py's mutation-header probe pins it: reaching
|
|
// MG_Impl/Pipe/*Emit.h from a frontend mutator would pull the client's emitters into the
|
|
// state machine that calls them). So a hook a frontend mutator calls is DECLARED here and
|
|
// DEFINED in MG_Impl/Pipe/PipeFill.cpp, which is package A's for the whole phase - the
|
|
// same "declaration here, definition there" split MGPipeMintResourceHandle and
|
|
// MGPipeEmitResourceCreate use, and the reason no file is touched twice.
|
|
//
|
|
// WHAT EACH BODY DOES, and the division is fixed:
|
|
// * PipeFill.cpp owns the GATE - the subsystem bit in MOBILEGL_PIPE_PUSH *and* the
|
|
// family's own kMGPipeWired*Subsystem constant, the same pair the validate point's
|
|
// `wants()` applies to every emission - and the four MINTS, which are pure allocator
|
|
// work and need no family knowledge;
|
|
// * the FAMILY EMITTER (MG_Impl/Pipe/<Family>Emit.h, owned by package B or C) owns the
|
|
// payload build, the handle rule for its own kind and the PUBLICATION LATCH below.
|
|
// PipeFill.cpp forwards to it through an entry point that is compiled only while that
|
|
// family's wired constant is non-zero, so this tree links against the STUB emitters
|
|
// and against the finished ones with no edit to PipeFill.cpp - and a family that sets
|
|
// its constant without providing the entry point is a COMPILE ERROR in its own commit
|
|
// rather than a surprise at the merge. The entry point each hook forwards to is named
|
|
// beside it and spelled out in PipeFill.cpp's contract block.
|
|
//
|
|
// NOTHING CALLS ANY OF THEM AT THE CONTRACT COMMIT. B and C add the call sites in the
|
|
// five MG_State directories C.7 gives them, in the SAME commit that gives the emitter its
|
|
// body - by EDITING an existing constructor/mutator body, never by adding one (G1).
|
|
|
|
// ---- the publication latch (D-I1), and it is the ONE answer both halves read ----
|
|
//
|
|
// The create is gated at its call site and the destroy inside the death helper, so the
|
|
// two ask the same question at two different moments. An object born while its subsystem
|
|
// bit was clear and destroyed after it was set would otherwise free its slot with the
|
|
// applier's record still Live - on a slot the allocator is about to hand out again. A
|
|
// slot is NOT evidence of a record either: a backend twin table mints one through
|
|
// MGPipeSlots().Acquire whether or not the subsystem ever asked this client to emit a
|
|
// create, and a delete_* on such a handle is a refused call the applier asserts on.
|
|
//
|
|
// So the emitter latches the answer when its create actually goes out, the death helper
|
|
// reads the latch, and the latch is keyed by {kind, slot, gen} so a recycled slot cannot
|
|
// inherit its predecessor's answer. Defined in PipeFill.cpp beside the six death helpers,
|
|
// declared here because both the helpers and the five emit headers read it.
|
|
void MGPipeNoteHandlePublished(MGPipeKind kind, MGPipeHandle handle);
|
|
Bool MGPipeHandleIsPublished(MGPipeKind kind, MGPipeHandle handle);
|
|
void MGPipeNoteHandleUnpublished(MGPipeKind kind, MGPipeHandle handle);
|
|
|
|
// ---- the four mints (pure allocator work, no family knowledge) ----
|
|
//
|
|
// UNCONDITIONAL in a push build, for MGPipeMintResourceHandle's reason: a handle is CLIENT
|
|
// state and other subsystems name these objects by handle whether or not their own family
|
|
// is switched on - MGPSurface::Res names a Texture or a Renderbuffer out of the framebuffer
|
|
// subsystem, MGPBoundView::Texture and MGPImageView::Res name a Texture out of the sampler
|
|
// one. Gating the mint on the family bit would make those emit null handles in exactly the
|
|
// A/B arm that exists to isolate the families. Each costs one free-list pop and one map
|
|
// insert per object and emits nothing.
|
|
void MGPipeMintTextureHandle(MG_State::GLState::ITextureObject& texture);
|
|
void MGPipeMintRenderbufferHandle(MG_State::GLState::RenderbufferObject& renderbuffer);
|
|
// A framebuffer has a handle and NO wire lifetime (D-I2): set_framebuffer_state is the only
|
|
// call that names one, and there is no create or destroy for the kind. The mint is still
|
|
// the object's, so the identity exists before the first validate point that pushes it.
|
|
void MGPipeMintFramebufferHandle(MG_State::GLState::FramebufferObject& framebuffer);
|
|
// Ordinary programs only. A program-pipeline COMPOSITE is minted by the composite resolver
|
|
// out of the reserved band through MGPipeSlotAllocator::AllocateComposite, which is the one
|
|
// door into it, and it is not a frontend construction event.
|
|
void MGPipeMintShaderCsoHandle(MG_State::GLState::ProgramObject& program);
|
|
|
|
// ---- textures and renderbuffers: MG_Impl/Pipe/TextureEmit.h, package B ----
|
|
//
|
|
// resource_create from ITextureObject's constructor and RenderbufferObject's;
|
|
// resource_respecify from every storage-defining entry point, including
|
|
// RenderbufferObject::{SetInternalFormat, AllocateStorage, SetSamples}, which publish
|
|
// nothing at all today (D-D2); set_texture_params from the parameter mutators, which is
|
|
// where the READ-attachment-only gap D-E3 closes.
|
|
//
|
|
// Entry points MGPipeTextureEmitter must provide, all taking the frontend object by
|
|
// reference and returning void:
|
|
// EmitResourceCreate(ITextureObject&)
|
|
// EmitResourceRespecify(ITextureObject&, MGPipeTextureRespecifyScope, Uint32 uploadTarget,
|
|
// Uint32 level)
|
|
// EmitTextureParams(ITextureObject&)
|
|
// NoteLevelDirty(ITextureObject& storageOwner, Uint32 uploadTarget, Uint32 level)
|
|
// EmitRenderbufferCreate(RenderbufferObject&) / EmitRenderbufferRespecify(RenderbufferObject&)
|
|
void MGPipeEmitTextureResourceCreate(MG_State::GLState::ITextureObject& texture);
|
|
|
|
// WHICH STORAGE A TEXTURE RESPECIFY REPLACES (P4a final review C-1). The applier scopes
|
|
// its pending-upload clear on this answer and not on the descriptor, because the
|
|
// descriptor cannot give it: AllocateStorage is per (uploadTarget, level) and
|
|
// TruncateMipmapLevels removes every level at or above a cut, while MGPResourceDesc
|
|
// carries only the base extent and the level count. A level the applier had ACCEPTED at
|
|
// one verb (the client's dirty flag already clear, D-D5 step 1) and that a later per-level
|
|
// definition redefined AROUND was dropped by the whole-resource arm with nobody owing its
|
|
// texels - so every respecify states its scope, and "whole resource" is said, never
|
|
// defaulted. The emitter builds wire's MGPRespecifiedLevel from the pair, packed exactly
|
|
// as the drain packs a sub-data record's Target (MGPipePackSubDataTarget), so the key it
|
|
// drops is the key that level's emission made.
|
|
enum class MGPipeTextureRespecifyScope : Uint32 {
|
|
// The whole store is redefined or restated: a format, sample-count or
|
|
// fixed-sample-locations change, an immutable allocation completing
|
|
// (SetImmutableLevels), a texture view's creation. Every pending upload goes.
|
|
WholeResource = 0,
|
|
// ONE (uploadTarget, level) was (re)allocated: glTexImage*D, glCompressedTexImage*D,
|
|
// glCopyTexImage*D, one level of a glTexStorage* loop, one level of a generated-mipmap
|
|
// grow. That level's pending upload goes; every other level's stays. `uploadTarget` and
|
|
// `level` name it.
|
|
OneLevel = 1,
|
|
// The chain was cut: every level of `uploadTarget` at or above `level` is gone and the
|
|
// levels below it are untouched (glGenerateMipmap fitting the chain, a base-level
|
|
// redefinition discarding its tail, glTexStorage* fitting the chain to its level
|
|
// count). `level` is the first level removed; a cut at 0 is the whole resource.
|
|
LevelsFrom = 2,
|
|
};
|
|
void MGPipeEmitTextureResourceRespecify(MG_State::GLState::ITextureObject& texture,
|
|
MGPipeTextureRespecifyScope scope, Uint32 uploadTarget,
|
|
Uint32 level);
|
|
void MGPipeEmitTextureParams(MG_State::GLState::ITextureObject& texture);
|
|
// The DRAIN LIST's append, on a level's FIRST dirty mark, keyed on the STORAGE OWNER from
|
|
// day one (D-D4: a view and its owner already share one dirty state, so an upload through
|
|
// either lands on the same key). The record itself is emitted at the validate point by
|
|
// MGPipeTextureEmitter::DrainTextureSubData; this is only what puts the level on the list,
|
|
// and walking every live texture per verb is the cost it exists to avoid.
|
|
void MGPipeNoteTextureLevelDirty(MG_State::GLState::ITextureObject& storageOwner, Uint32 uploadTarget,
|
|
Uint32 level);
|
|
void MGPipeEmitRenderbufferResourceCreate(MG_State::GLState::RenderbufferObject& renderbuffer);
|
|
void MGPipeEmitRenderbufferResourceRespecify(MG_State::GLState::RenderbufferObject& renderbuffer);
|
|
|
|
// ---- D-A4's two sticky bind-mask producers (P4a final review M-A) ----
|
|
//
|
|
// kMGPipeBindSampler is "any texture the sampler-view resolution names in an emitted
|
|
// MGPBoundView" and kMGPipeBindShaderImage "any texture named in an emitted MGPImageView"
|
|
// - both the SAMPLER package's emitters (SamplerEmit.h, ImageEmit.h), which the texture
|
|
// emitter's header includes and which therefore cannot include it back - and, earliest of
|
|
// all, glBindImageTexture's state setter (TextureState.h, MG_State), which may include no
|
|
// emit header at all. So the note goes through this door, exactly as the birth hooks do.
|
|
// Nothing produced either bit before the fix round: ImageBindableHint was always 0, the
|
|
// metadata respecify (ID-18 M4) had no live trigger, and the remint pull the hint exists to
|
|
// prevent was neither prevented nor counted.
|
|
//
|
|
// UNCONDITIONAL IN A PUSH BUILD, like the mints: the mask is CLIENT state the framebuffer
|
|
// emitter ORs into whether or not the texture family is on, and the emission a mask move
|
|
// causes (the metadata respecify) is gated inside the emitter on the family's own pair.
|
|
void MGPipeNoteTextureBoundAs(MGPipeHandle texture, Uint32 bindBit);
|
|
// glBindImageTexture. The hint is the PREVENTION half of the texture-remint stall class -
|
|
// a texture the server knows may be image-bound is allocated image-bindable up front - so it
|
|
// has to reach the applier before the texture's first sync, i.e. at the bind itself, not at
|
|
// the validate point's image walk (which notes it as well, D-A4's letter).
|
|
void MGPipeNoteTextureImageBound(MG_State::GLState::ITextureObject& texture);
|
|
|
|
|
|
// ---- sampler CSOs and sampler views: MG_Impl/Pipe/SamplerEmit.h, package C ----
|
|
//
|
|
// Entry points MGPipeSamplerEmitter must provide, returning void:
|
|
// EmitSamplerCso(SamplerObject&) - D-F1's content-addressed mint-or-share at
|
|
// capacity 256, hashed field-wise over a canonical
|
|
// zero-initialised copy, behind the version-first
|
|
// skip. The HANDLE RULE FOR THIS KIND IS THE
|
|
// EMITTER'S, not this file's: two identical
|
|
// samplers share one CSO, so there is deliberately
|
|
// no per-object mint above, and it is the emitter
|
|
// that decides which lifetime id (if any) owns the
|
|
// slot the death helper will resolve.
|
|
// EmitSamplerView(ITextureObject&) - D-F2's ONE view per texture object, minted off
|
|
// the texture's own lifetime id and re-issued on
|
|
// the SAME handle when the restrictions move.
|
|
void MGPipeEmitSamplerCsoCreate(MG_State::GLState::SamplerObject& sampler);
|
|
void MGPipeEmitSamplerViewCreate(MG_State::GLState::ITextureObject& texture);
|
|
|
|
// ---- programs: MG_Impl/Pipe/ProgramEmit.h, package C ----
|
|
//
|
|
// Entry point MGPipeProgramEmitter must provide, returning void:
|
|
// EmitShaderCso(ProgramObject&)
|
|
//
|
|
// Re-issued on the SAME handle whenever the link version moves, exactly as
|
|
// create_vertex_elements is (Gen moves only on slot reuse). D-H4 keeps the TRACKER out of
|
|
// it - bit 6's shutter reads GetCurrentProgram() and deliberately not GetProgramForDraw(),
|
|
// because the tracker must not force a compile to answer "did the shader move" - so the
|
|
// ordinary emission is the validate point's, from the join the verb was going to make
|
|
// anyway. This hook exists for the paths that are NOT a draw: a link that completes off
|
|
// the draw path still owns its own publication.
|
|
void MGPipeEmitShaderCsoCreate(MG_State::GLState::ProgramObject& program);
|
|
} // namespace MobileGL::MG_Pipe
|
|
#define MGP_NOTE_MUTATION(Field) \
|
|
::MobileGL::MG_Pipe::MGPipeNoteFrontendMutation(::MobileGL::MG_Pipe::MGPipeInputField::Field)
|
|
#define MGP_NOTE_AGGREGATE(Aggregate) \
|
|
::MobileGL::MG_Pipe::MGPipeNoteAggregate(::MobileGL::MG_Pipe::MGPipeAggregate::Aggregate)
|
|
#else
|
|
#define MGP_NOTE_MUTATION(Field) ((void)0)
|
|
#define MGP_NOTE_AGGREGATE(Aggregate) ((void)0)
|
|
#endif
|
|
#endif
|