[MG_Backend, docs] (P7): a wire decline's line says decline, not draw, because the texture rows count per sync

Fable review of the B3 rework, nit: MGL_WIRE_DECLINE_AT logged "Magma wire
draw declined [Site]" from every site, but the Tex*, Shape* and Upload*
rows are reached through SyncTextureResourceByHandle, whose callers are not
only the draw/dispatch texture preparation: the descriptor resolver,
framebuffer attachments, CopyTexSubImage, mipmap generation and
CopyImageSubData each Fatal right after a failed sync, and texture
readback falls back to the unbacked shadow. Those counters are per sync,
not per draw - a draw sampling three unsyncable textures counts three, a
failed attachment sync counts once and is then a Fatal.

- WireDeclineTally.h: the line is "Magma wire decline [Site]: ...", and
  the macro's comment says the texture rows are per sync and names the
  callers. Disaggregated-only header; no test or script matches the old
  text (git grep).
- magma-b3.md §1.5: says the counters are per sync and that the log lines
  quoted in §1.3 / §1.5 carry the old wording.
This commit is contained in:
2026-09-22 20:49:45 -04:00
parent 4196f0e902
commit 7e51860435
2 changed files with 16 additions and 1 deletions
@@ -150,11 +150,19 @@ private:
// Every decline goes through this: the tally moves ALWAYS, the log line is once per site.
// `return MGL_WIRE_DECLINE_FALSE(Site, "why", ...)` reads as the statement it replaces.
//
// A DECLINE IS NOT ALWAYS A SKIPPED DRAW, so the line does not say "draw". The Tex*, Shape* and
// Upload* rows are counted per texture SYNC: SyncTextureResourceByHandle is reached from the
// draw/dispatch texture preparation, but also from the descriptor resolver, framebuffer
// attachments, CopyTexSubImage, mipmap generation and CopyImageSubData - each of which Fatals
// right after a failed sync - and from texture readback, which falls back to the unbacked
// shadow. A draw that samples three unsyncable textures counts three; a failed attachment
// sync counts once and is then a Fatal, not a skipped draw.
#define MGL_WIRE_DECLINE_AT(site, fmt, ...) \
do { \
::MobileGL::MG_Backend::DirectVulkan::WireDeclineTally::Count( \
::MobileGL::MG_Backend::DirectVulkan::WireDeclineSite::site); \
MGLOG_E_ONCE("Magma wire draw declined [" #site "]: " fmt, ##__VA_ARGS__); \
MGLOG_E_ONCE("Magma wire decline [" #site "]: " fmt, ##__VA_ARGS__); \
} while (0)
} // namespace MobileGL::MG_Backend::DirectVulkan