// MobileGL - MobileGL/MG_Impl/Pipe/SetHashSuppressor.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 #include // Set-hash suppression (ARCHITECTURE.md §5.4): every kVarTail set_* hashes the resolved set on // the client and is not emitted while the hash is unchanged, in place of the backends' own // "same set as last time" debounce. A slot's hash must cover every input its record carries, // not only the set: MGPipeVertexBufferSetContentHash mixes in BaseInstance, which is draw state // that moves without the buffer set, or a changed fetch shift would be suppressed. A latched 0 // means "never emitted", so the first emission always goes out; a computed 0 is latched as 1, // costing at worst one extra emission, never a missed one. #include namespace MobileGL::MG_Pipe { // One slot per kVarTail set_* (ARCHITECTURE.md 5.1's call list), PLUS // SetFramebufferState, which is not kVarTail at all: MGPFramebufferState carries a // ContentHash for TWO jobs - the server's render-pass memo key and the client's emission // suppressor - and the second one needs a slot here like any other, PLUS // SetContextValues (P5c rv), also not kVarTail: one fixed-width POD whose whole-record // hash is the "did any covered value move" answer. The enum is // CLIENT-ONLY and is not a wire opcode, so appending before Count is safe. enum class MGPipeSuppressorSlot : Uint32 { SetVertexBuffers = 0, // P3a - wired, and its hash includes BaseInstance // P4a - WIRED. The three unit sets' suppressors are not optional and were never a // later phase's: MGPipeTypes.h makes the pattern mandatory for every kVarTail set_*, // because GetTextureBindGeneration() bumps on a REDUNDANT rebind - MC 26.2 rebinds the // same sampler at every texture-unit switch - so an unsuppressed set is a // several-hundred-byte variable-length record per batch, which is the exact regression // the design names. What P3b/P4b owns is the ~175-line BACKEND debounce these replace // (UnitBindingsSnapshot / CaptureUnitBindings / UnitBindingsUnchanged and the two // g_*SyncList tables); P4a wires the carrier, P3b/P4b deletes the backend copy. SetSamplerViews, // P4a - wired (backend debounce deletion: P3b/P4b) BindSamplerStates, // P4a - wired (backend debounce deletion: P3b/P4b) SetShaderImages, // P4a - wired (backend debounce deletion: P3b/P4b) // P5e (docs/archive/contracts/CONTRACT-P5E.md §1, ruling 11): THREE SLOTS, ONE PER CLASS, not one // for the call. set_shader_buffers is emitted per Class (Uniform / ShaderStorage / // AtomicCounter) because the record's own Class field says which binding-point array // it describes - so a single slot would make every emission of one class cancel the // previous emission of another, and the shader-storage set would be suppressed as // "unchanged" by a uniform set that happened to hash the same way. Three slots also // keep the per-family fire tally and the A/B meaningful, which one keyed on // (slot, Class) would not. SetShaderBuffersUniform, // P5e (sb) SetShaderBuffersShaderStorage, // P5e (sb) SetShaderBuffersAtomicCounter, // P5e (sb) SetStreamOutputTargets, // P4b // P5e (CONTRACT-P5E.md §1): set_program_bindings, the post-link binding record. Not // kVarTail-only - it has three tails - but the same rule applies: the emitter latches // on (Cso, backendStateVersion, blockBindingVersion) and the whole-record hash is what // says "nothing moved". SetProgramBindings, // P5e (pg) SetVertexAttribDefaults, // P2 - the one consumer that is wired SetFramebufferState, // P4a - wired // P5c rv (CONTRACT-P5C.md §5.3). NOT kVarTail either - the same shape as // SetFramebufferState's note: MGPContextValues is one fixed-width POD, and the // whole-record hash IS its "did any covered value move" answer (there is deliberately // no dirty mask in the payload - a suppressed record means "nothing moved", never // "field invalid"). SetContextValues, // P5c rv - wired, split+transport only (PipeFill.cpp gates) Count, }; inline constexpr SizeT kMGPipeSuppressorSlotCount = static_cast(MGPipeSuppressorSlot::Count); class MGPipeSetHashSuppressor { public: // True when `contentHash` differs from what this slot last emitted, and LATCHES it. // False means the resolved set has not moved and the call must not go out. Bool ShouldEmit(MGPipeSuppressorSlot slot, Uint64 contentHash) { const Uint64 latched = contentHash == 0 ? 1 : contentHash; const SizeT index = static_cast(slot); if (m_lastEmitted[index] == latched) return false; m_lastEmitted[index] = latched; return true; } // The server now holds the set `contentHash` names without this slot having emitted it // (P14: bind_vertex_elements re-applies the array's kept set). Same 0 -> 1 remap as // ShouldEmit, so the next ShouldEmit of the same hash answers false. void Latch(MGPipeSuppressorSlot slot, Uint64 contentHash) { m_lastEmitted[static_cast(slot)] = contentHash == 0 ? 1 : contentHash; } // A context change or a server reset: what the server has is no longer what this // slot last emitted, so the next resolved set must go out whatever it hashes to. void Invalidate(MGPipeSuppressorSlot slot) { m_lastEmitted[static_cast(slot)] = 0; } void InvalidateAll() { for (SizeT i = 0; i < kMGPipeSuppressorSlotCount; ++i) m_lastEmitted[i] = 0; } // 0 == "never emitted". Exposed for the unit test, which is what pins that the // reserved value really is reserved. Uint64 LastEmitted(MGPipeSuppressorSlot slot) const { return m_lastEmitted[static_cast(slot)]; } private: Array m_lastEmitted{}; }; // The monolith's one suppressor, beside the tracker and the CSO cache. inline MGPipeSetHashSuppressor& MGPipeSetHashSuppressorInstance() { // NEVER DESTROYED, for MGPipeTrackerInstance()' reason (MG_Impl/Pipe/Tracker.h): the // rule covers every MGPipe process singleton, not only the ones on today's death // paths. static MGPipeSetHashSuppressor* suppressor = new MGPipeSetHashSuppressor(); return *suppressor; } } // namespace MobileGL::MG_Pipe