Files
MobileGL/MobileGL/MG_Impl/Pipe/Verb/VerbPort.h
T
swung0x48 1e9f8bb0ff [Refactor] (docs/ci, MG_Impl/Pipe, MG_Remote/Client, MG_Test/Wire, scripts/data): drop the E2 drop knobs
- MOBILEGL_IPC_E2_DROP_DRAW and MOBILEGL_IPC_E2_DROP_CLEAR leave the shipped emitter with their per-draw and per-clear branches, setters, counters and per-frame evidence line; nothing sets them since the dropped-draws control left CI
- the wire-volume assertion on the OpenRA split legs replaces the control (758 DrawVbo records and 758/788 server draws locally, both backends, inproc and spawn)
- retire the unit case RemoteEmitTable.TheE2DropSwitchStartsDisarmed, which only toggled the clear setter; skip census: removed from junit-integration-split-strict/unit-strict (test/unit and unit-split borrow that list)
2026-10-17 15:59:52 -04:00

219 lines
14 KiB
C++

// MobileGL - MobileGL/MG_Impl/Pipe/Verb/VerbPort.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
// P13 W5: THE RECORD ARM'S VERB EMITTERS, WITHOUT A TRANSPORT. The draws, clears, blits, readbacks,
// compute, copies, image binds, XFB and mipmaps are planned here once. Under a transport a planned
// record goes to the session, which MG_Remote hands over as a VerbSession (EmitTables.cpp installs
// the resolver at static init); on monolith's record arm it goes to an in-process RecordVerbSink
// bound to the one backend object (InstallMonolithVerbPort). Nothing here names MG_Remote.
#pragma once
#include <Includes.h>
#include <MG_Backend/BackendFunctions.h>
#include <MG_Pipe/MGPipeTypes.h>
#include <MG_Pipe/MGPipeValueTypes.h>
#include <MG_Pipe/PipeVerbSink.h>
namespace MobileGL::MG_Record {
// Where a split emitter's record goes: the transport's session, spelled as the emitters call
// it. Only MG_Remote implements it; a library without a transport never resolves one.
class VerbSession {
public:
virtual Uint64 EmitAndWait(MG_Pipe::MGPWireOp op, const void* payload, Uint64 payloadBytes, const void* varTail,
Uint64 varTailBytes, void* replyOut, Uint64 replyBytes, Int32* statusOut,
Uint64* replySizeOut) = 0;
virtual Uint64 EmitAndWaitTails(MG_Pipe::MGPWireOp op, const void* payload, Uint64 payloadBytes,
const MG_Pipe::MGPipeVerbTail* tails, Uint32 tailCount, void* replyOut,
Uint64 replyBytes, Int32* statusOut, Uint64* replySizeOut) = 0;
virtual Uint32 MaxReplyBytes() const = 0;
virtual void RequireReadPixelsReplyFits(Uint32 width, Uint32 height, Uint32 format, Uint32 type,
Uint64 bytes) const = 0;
// A blob the record names by reference, staged where the record's reader can find it.
virtual MG_Pipe::MGPBlobRef StageBytes(const void* bytes, Uint64 size) = 0;
protected:
~VerbSession() = default;
};
// The session for `slot`, or a named death when there is none (the resolver's own refusal).
using VerbSessionResolver = VerbSession& (*)(const char* slot);
void SetVerbSessionResolver(VerbSessionResolver resolver);
// Every slot a verb emitter serves, written into `table` (the remote table's class-B verbs).
void AssignVerbEmitters(MG_Backend::GlobalBackendFunctionsTable& table);
// A verb that reads buffers but starts no shader (clear, blit, readback, present, fences): the
// persistent-map push and the deferred destroys, before its record.
void BeforeReadOnlyVerb();
#if MOBILEGL_PIPE_VERIFY
// True while the monolith verb port applies a record on this thread. The verify read hook
// answers a pack-state read inside that window from the applied pack payload, as it does for a
// server-stamped verb: the record verb sink forces the neutral pack around its readback, so
// the live context is not the oracle there (PipeFill.cpp MGPipeVerifyReadHook).
Bool MonolithPortApplyingForVerify();
#endif
// Called by the Fatal slots. Named separately so a death test can filter on it and so
// that the message wording lives in exactly one place.
[[noreturn]] void UnmigratedVerbFatal(const char* slot);
// P13 W4: monolith's record arm. Overwrites the ported verb slots of the backend's own
// table with this file's emitters, which hand their planned record to an in-process
// RecordVerbSink instead of a session (VerbPort.cpp, "THE MONOLITH VERB PORT"). Installed
// by the library's bring-up when MG_Config::RecordArmAliasesFrontend() holds.
void InstallMonolithVerbPort(MG_Backend::GlobalBackendFunctionsTable& table);
Bool MonolithVerbPortInstalled();
// Tests only (MG_Test/Pipe/RecorderGoldenTest.cpp): send the ported slots to the verb session
// resolver instead of the in-process sink, so a recorder sees the records the port would apply.
// Returns the previous routing.
Bool SetMonolithVerbPortRoutingForTesting(Bool viaPort);
// ID-47. The CLIENT refuses a readback whose answer would not fit a reply slot, BEFORE it
// emits the record, and names the read. THE REFUSAL ITSELF IS s1's -
// ClientSession::RequireReadPixelsReplyFits, forwarding to
// ReplySlotPool::RequireReadPixelsFits - and this package does not own a second copy of the
// message: two spellings of one refusal is how the two sides come to disagree about which
// reads are legal. What c1 owns is the CALL SITE and the number it passes, which is ID-49's
// tight extent; the control below is over that, and s1-v3.md §1's cases are over the
// helper.
// ID-49. `MGPReadbackInfo::DstSize` is the TIGHT w*h*bytesPerPixel extent - the reply
// payload - and nothing about the application's pack state crosses the wire. The server
// reads with a NEUTRAL pack state into that run; this is the number both sides derive.
Uint64 TightReadbackByteCount(GLsizei width, GLsizei height, GLenum format, GLenum type);
// ID-49. Scatters the tight rows into the application's pointer per the application's own
// pack state (ROW_LENGTH, SKIP_*, ALIGNMENT), which only the client holds. Exposed for the
// same reason as the refusal above: the control drives the function the emitter calls
// rather than a second copy of GL 4.6 8.4.4's arithmetic. THE GAPS ARE NEVER WRITTEN -
// they belong to the application - and that is what the control checks with a sentinel.
void ScatterTightReadbackIntoPackState(const void* tight, void* destination, GLsizei width, GLsizei height,
Uint64 bytesPerPixel, const PixelStoreParameters& pack);
// A glReadPixels whose tight answer exceeds one reply slot is split into bands, each an
// ordinary read_pixels record with its own box and tight DstSize, scattered under the
// application's pack state (ARCHITECTURE.md §13.1.2). Bands are whole-width row runs when a
// row fits a reply, else column pieces of one row; they go in row-major order and cover the
// rectangle once. No plan means not even one pixel fits, and the emitter refuses by name
// (Fatal{ReplyTooLarge}). The plan is two numbers and bands are walked, not listed, so a
// read allocates nothing and the emitter and its unit test share one walk.
struct ReadbackBand {
Uint64 FirstRow = 0;
Uint64 Rows = 0;
Uint64 FirstColumn = 0;
Uint64 Columns = 0;
};
struct ReadbackBandPlan {
Uint64 RowsPerBand = 0; // 1 when a single row does not fit a reply
Uint64 ColumnsPerBand = 0; // the whole width when it does
};
// False (and `plan` untouched) exactly when not even one pixel fits a reply.
Bool PlanReadbackBands(Uint64 width, Uint64 height, Uint64 bytesPerPixel, Uint64 maxReplyBytes,
ReadbackBandPlan& plan);
template <typename Visit>
void ForEachReadbackBand(Uint64 width, Uint64 height, const ReadbackBandPlan& plan, Visit&& visit) {
if (plan.RowsPerBand == 0 || plan.ColumnsPerBand == 0) return;
for (Uint64 row = 0; row < height; row += plan.RowsPerBand) {
const Uint64 rows = plan.RowsPerBand < height - row ? plan.RowsPerBand : height - row;
for (Uint64 column = 0; column < width; column += plan.ColumnsPerBand) {
const Uint64 columns = plan.ColumnsPerBand < width - column ? plan.ColumnsPerBand : width - column;
visit(ReadbackBand{row, rows, column, columns});
}
}
}
// The scatter for ONE band: `band` holds band.Rows x band.Columns tight pixels, and they land
// where ScatterTightReadbackIntoPackState would have put those pixels of the whole
// `width`-wide read. ScatterTightReadbackIntoPackState is this function over the single band
// {0, height, 0, width}, so the whole-read arithmetic and the banded one cannot drift.
void ScatterReadbackBandIntoPackState(const void* band, void* destination, GLsizei width, const ReadbackBand& where,
Uint64 bytesPerPixel, const PixelStoreParameters& pack);
// ID-49. True when the destination layout IS the tight layout, which is the only condition
// under which EmitReadPixels may read the reply straight into the application pointer and
// skip the bounce. Exported because the FAST PATH and the SCATTER have to agree, and the
// only honest way to state that is to drive both and compare - a case that tested either
// alone would pass a predicate that said yes to a layout the scatter would have rearranged.
Bool ReadbackPackStateIsTightForTest(GLsizei width, Uint64 bytesPerPixel, const PixelStoreParameters& pack);
// M2 / codex 11. True exactly when the readback reply is OK and carries the read's own exact
// extent (CONTRACT-P5 row 23). EmitReadPixels calls this and Fatals by name when it is false
// - a short OK reply, or a DECLINE/ERROR with a zero payload, is refused rather than scattered
// as pixels. Exposed so the control drives the production predicate (R-16), not a copy: pass
// 0=OK / 1=DECLINED / 2=ERROR as `status`.
Bool ReadbackReplyIsComplete(Int32 status, Uint64 replySize, Uint64 expected);
// =============================================================================
// P5b d1 - the draw family's record plan (docs/archive/contracts/CONTRACT-P5B.md §2 d1)
// =============================================================================
//
// The nineteen indexed / instanced / multi-draw / indirect entry points all ride draw_vbo
// (59), and the ONLY thing that differs per entry point is how the GL arguments become the
// record's fields. That derivation is split out of the emitters as three pure functions
// over a snapshot of the bindings the emitter read from the GL context, so a unit case can
// drive the PRODUCTION derivation with synthetic bindings (R-16) while the integration lane
// proves the bindings are read from the right slots. The emitters compose these and add
// nothing but the hooks and the staging of a client index array.
// What the emitter reads from the GL context before it plans a draw.
struct RemoteDrawBindings {
// The VAO's GL_ELEMENT_ARRAY_BUFFER: bound or not, and its handle when bound (the same
// handle set_index_buffer carried at validate). Not bound means `indices` is a client
// pointer and the emitter stages the bytes (kDrawHasUserIndices).
Bool ElementBufferBound = false;
MG_Pipe::MGPipeHandle ElementBuffer = MG_Pipe::kMGPipeNullHandle;
// The bound GL_DRAW_INDIRECT_BUFFER and GL_PARAMETER_BUFFER, null when unbound.
MG_Pipe::MGPipeHandle DrawIndirectBuffer = MG_Pipe::kMGPipeNullHandle;
MG_Pipe::MGPipeHandle ParameterBuffer = MG_Pipe::kMGPipeNullHandle;
// GL_PRIMITIVE_RESTART / GL_PRIMITIVE_RESTART_FIXED_INDEX and the application's index,
// carried verbatim (informational in P5b: the backend reads its own barrier-pulled copy).
Bool PrimitiveRestart = false;
Uint32 RestartIndex = 0;
// P5e (vi), ID-82 / CONTRACT-P5E §5.1: TRUE when the bound VAO has at least one ENABLED
// attribute with no buffer object behind it, i.e. an array whose vertices live in the
// application's own memory. The server has no such memory: today it dereferences
// `attrib.Offset` as a raw client pointer from the apply thread
// (Managers.cpp's SyncClientSideAttributesForDrawArrays), which is legal only while the
// client is parked behind the record. It rides in MGPDrawInfo::Flags as kDrawClientArrays
// so BOTH roles can decide from the wire - the client refuses such a draw under
// run-ahead, and MGPipeBarriered's escalation (ii) keeps it barriered if one ever
// arrives anyway. Staging the bytes is P8's.
Bool ClientVertexArrays = false;
};
// 1 / 2 / 4 for the three GL index types, 0 for anything else (the frontend has already
// refused those with INVALID_ENUM before the slot is reached).
Uint8 RemoteIndexSizeFor(GLenum indexType);
// The fixed head. `indexSize` 0 = arrays. `instanceCount` is the call's own (1 for a
// non-instanced entry point) and `baseInstance` its gl_BaseInstance value; the sink reads
// "instanced" as InstanceCount != 1 || StartInstance != 0, so an instanced call with a
// count of 1 and no base instance is dispatched as the plain draw it is equivalent to.
MG_Pipe::MGPDrawInfo PlanDrawInfo(GLenum mode, Uint8 indexSize, GLsizei instanceCount, GLuint baseInstance,
Uint32 numDraws, const RemoteDrawBindings& bindings);
// One MGPDrawRange from one (first | indices, count, basevertex). Arrays: Start = first.
// Indexed with an element buffer bound: Start = offset / IndexSize, and FALSE when the byte
// offset is not a whole number of indices or does not fit the record's Uint32 Start - the
// caller refuses by name rather than round. Indexed with no element buffer: Start = 0 and
// the bytes are the client's (the emitter stages `count * IndexSize` of them).
Bool PlanDrawRange(const RemoteDrawBindings& bindings, Uint8 indexSize, const void* indicesOrFirst, GLsizei count,
GLint baseVertex, MG_Pipe::MGPDrawRange& out);
// The kDrawIsIndirect second tail: the bound GL_DRAW_INDIRECT_BUFFER handle, the call's
// `indirect` byte offset, the stride and the draw count; for the *IndirectCount forms the
// bound GL_PARAMETER_BUFFER handle and the byte offset the call spells as `drawcount`.
MG_Pipe::MGPDrawIndirect PlanDrawIndirect(const RemoteDrawBindings& bindings, const void* indirect,
GLsizei drawCount, GLsizei stride, GLintptr parameterOffset,
Bool hasParameterBuffer);
} // namespace MobileGL::MG_Record