// MobileGL - MobileGL/MG_Impl/Pipe/ClientFetchPlan.h // Copyright (c) 2025-2026 MobileGL-Dev // Licensed under the GNU Lesser General Public License v3.0 // SPDX-License-Identifier: LGPL-3.0-only // End of Source File Header // // Which elements of a client-memory vertex array a draw fetches. Only the draw can say: the // index bytes it reads, its instance count and base instance, and for indirect forms the // command block. The wire arm snapshots those elements into owned buffers // (MGPipeOwnedDrawInputs); the monolith arm sizes the backend's per-draw upload from the // application pointer. One copy of the arithmetic keeps the two from disagreeing about which // vertices a draw reads. The plan names element indices only; the caller's reader dereferences // memory. It is built in every configuration, since the monolith arm needs it too. #pragma once #include #include #include #include #include namespace MobileGL::MG_Pipe { // The indirect block as a role that reads GL state can state it: the byte geometry plus // whether the GL_PARAMETER_BUFFER of the *IndirectCount forms is bound. MGPDrawIndirect's // two handle fields are the wire's identity and are meaningless to the monolith arm, which // resolves the very same bytes out of the frontend binding slots. struct MGPipeClientIndirect { Uint64 Offset = 0; Uint64 ParameterOffset = 0; Uint32 Stride = 0; Uint32 DrawCount = 0; Bool HasParameterBuffer = false; }; // The draw's own shape, spelled the way the range record spells it: arrays carry Start = // first and no index size, indexed carries Start = the element offset into the element // buffer and IndexBias = base vertex. struct MGPipeClientDrawInputs { Uint8 IndexSize = 0; const MGPDrawRange* Ranges = nullptr; Uint32 RangeCount = 0; Uint32 InstanceCount = 1; Uint32 BaseInstance = 0; // True when primitive restart is live and RestartIndex is the value the index stream // restarts on. A restart index is a marker, not a vertex: it is what the mono arm's // restart substitution rewrites around, and counting it as a fetched element would // copy an element no primitive ever reads. Bool PrimitiveRestart = false; Uint32 RestartIndex = 0; // The application's own index array, when no element buffer is bound. Null with // IndexSize != 0 means "the indices come from the bound element buffer", i.e. through // the reader. const void* ClientIndices = nullptr; Uint64 ClientIndexBytes = 0; const MGPipeClientIndirect* Indirect = nullptr; // Whether a vertex-rate (divisor == 0) client array is present. A draw whose client // arrays are all instance-rate never has to read the index stream to answer "which // elements", so the element buffer is left alone (and the reader is never called with // BufferKind::Element). Bool WantVertices = false; }; // Where a byte request is aimed. Both kinds are buffers a GL context names; they are // distinguished because the two roles resolve them from different places and a reader // that answered one for the other would size an upload off the wrong bytes. enum class MGPipeClientBufferKind : Uint8 { Element, // the bound GL_ELEMENT_ARRAY_BUFFER, for the index stream IndirectCommand, // the bound GL_DRAW_INDIRECT_BUFFER, for the command block IndirectCount, // the bound GL_PARAMETER_BUFFER, for an *IndirectCount form's count }; // Reads `size` bytes at `offset` of the named buffer on the CPU. False when the bytes do // not exist on this side, which is a refusal rather than a guess. using MGPipeClientBufferReader = Bool (*)(void* user, MGPipeClientBufferKind kind, Uint64 offset, SizeT size, void* destination); // One sub-draw's fetch: the element range it reads, how many instances it runs, and the // raw base instance it shifts by. struct MGPipeClientFetch { MGPDrawRange Range; Uint32 Instances = 1; Uint32 BaseInstance = 0; }; // The reader for a buffer whose bytes this side owns - the wire client's staged shadow and // the monolith arm's frontend object are both read this way. Reconciles a pending GPU write // first, because a shader-written index or command block is exactly the case this plan // exists to handle. inline Bool MGPipeReadBufferShadow(const SharedPtr& buffer, Uint64 offset, SizeT size, void* destination) { if (!buffer || offset > buffer->GetSize() || size > buffer->GetSize() - offset) return false; buffer->SyncGpuWrites(); buffer->DownloadSubData(destination, static_cast(offset), size); return true; } class MGPipeClientFetchPlan { public: // False when the draw's fetched elements cannot be determined - an index or command // block this side cannot read, an index stream that leaves the client array, an index // that runs below the base vertex. A caller must then refuse the draw rather than // snapshot a guess: the elements it would leave out are the ones the draw reads. Bool Build(const MGPipeClientDrawInputs& inputs, MGPipeClientBufferReader reader, void* user) { m_inputs = inputs; m_fetches.clear(); m_vertices.clear(); if (inputs.Indirect != nullptr) { if (!ReadIndirectFetches(inputs, reader, user)) return false; } else { m_fetches.reserve(inputs.RangeCount); for (Uint32 i = 0; i < inputs.RangeCount; ++i) { m_fetches.push_back({inputs.Ranges[i], inputs.InstanceCount, inputs.BaseInstance}); } } if (!inputs.WantVertices) return true; return ReadVertices(inputs, reader, user); } // The vertex elements the draw fetches through a vertex-rate array, ascending and // unique. Only meaningful after a Build that wanted them. const Vector& Vertices() const { return m_vertices; } // The elements an attribute of `divisor` fetches: the vertex-rate set for divisor 0, // and one element per INSTANCE (baseInstance + instance / divisor) otherwise. Sorted // and unique, and `out` is left empty for a draw that fetches nothing. Bool Elements(Uint32 divisor, Vector& out) const { out.clear(); if (divisor == 0) { // Vertex rate: every instance reads the same vertices, and the collection above // already deduplicated them across the draw's sub-ranges. out = m_vertices; return true; } for (const auto& fetch : m_fetches) { if (!fetch.Range.Count || !fetch.Instances) continue; const Uint64 first = fetch.BaseInstance; const Uint64 last = first + (fetch.Instances - 1u) / divisor; for (Uint64 at = first; at <= last; ++at) out.push_back(at); } std::sort(out.begin(), out.end()); out.erase(std::unique(out.begin(), out.end()), out.end()); return true; } const Vector& Fetches() const { return m_fetches; } private: Bool ReadIndirectFetches(const MGPipeClientDrawInputs& inputs, MGPipeClientBufferReader reader, void* user) { const MGPipeClientIndirect& indirect = *inputs.Indirect; Uint32 count = indirect.DrawCount; if (indirect.HasParameterBuffer) { Uint32 actual = 0; if (reader == nullptr || !reader(user, MGPipeClientBufferKind::IndirectCount, indirect.ParameterOffset, sizeof(actual), &actual)) { return false; } count = std::min(count, actual); } const Uint64 commandBytes = inputs.IndexSize ? 5 * sizeof(Uint32) : 4 * sizeof(Uint32); const Uint64 stride = indirect.Stride ? indirect.Stride : commandBytes; m_fetches.reserve(count); for (Uint32 i = 0; i < count; ++i) { const Uint64 displacement = static_cast(i) * stride; if (displacement > std::numeric_limits::max() - indirect.Offset) return false; Uint32 words[5]{}; if (reader == nullptr || !reader(user, MGPipeClientBufferKind::IndirectCommand, indirect.Offset + displacement, commandBytes, words)) { return false; } Int32 bias = 0; if (inputs.IndexSize) std::memcpy(&bias, &words[3], sizeof(bias)); m_fetches.push_back({{words[2], words[0], bias}, words[1], words[inputs.IndexSize ? 4 : 3]}); } return true; } // The index stream's own answer. Arrays are contiguous by construction; an indexed // draw has to read the indices to learn which vertices it names, which is the whole // reason a GPU-written element buffer makes this a readback rather than arithmetic. Bool ReadVertices(const MGPipeClientDrawInputs& inputs, MGPipeClientBufferReader reader, void* user) { for (const auto& fetch : m_fetches) { if (!fetch.Range.Count || !fetch.Instances) continue; if (!inputs.IndexSize) { for (Uint64 n = 0; n < fetch.Range.Count; ++n) m_vertices.push_back(static_cast(fetch.Range.Start) + n); continue; } const Uint64 offset = static_cast(fetch.Range.Start) * inputs.IndexSize; const Uint64 size = static_cast(fetch.Range.Count) * inputs.IndexSize; if (size > std::numeric_limits::max()) return false; Vector indexBytes; const Uint8* data = nullptr; if (inputs.ClientIndices != nullptr) { if (offset > inputs.ClientIndexBytes || size > inputs.ClientIndexBytes - offset) return false; data = static_cast(inputs.ClientIndices) + static_cast(offset); } else { indexBytes.resize(static_cast(size)); if (reader == nullptr || !reader(user, MGPipeClientBufferKind::Element, offset, indexBytes.size(), indexBytes.data())) { return false; } data = indexBytes.data(); } for (Uint32 n = 0; n < fetch.Range.Count; ++n) { Uint32 index = 0; std::memcpy(&index, data + static_cast(n) * inputs.IndexSize, inputs.IndexSize); if (inputs.PrimitiveRestart && index == inputs.RestartIndex) continue; const Int64 vertex = static_cast(index) + fetch.Range.IndexBias; if (vertex < 0) return false; m_vertices.push_back(static_cast(vertex)); } } // An array draw's single range arrives ascending already; sorting it again was most of // the client's time on a client-array draw. if (!std::is_sorted(m_vertices.begin(), m_vertices.end())) std::sort(m_vertices.begin(), m_vertices.end()); m_vertices.erase(std::unique(m_vertices.begin(), m_vertices.end()), m_vertices.end()); return true; } MGPipeClientDrawInputs m_inputs{}; Vector m_fetches; Vector m_vertices; }; } // namespace MobileGL::MG_Pipe