docs(render): record V4t at the committed tree, and correct one stale comment

Marks V4t done in the slice table with its two commits and per-commit gate
numbers, adds §5.5.11, and ticks off step 3 of §5.5.9's corrected sequence.

§5.5.11 records four things the world arm needs and one it should not
re-derive: why §5.2's "the device's table is unreachable" argument expired
rather than being worked around (its premise was that V4c would move the world
renderers onto the encoder; §5.5.6 closed that, so the block became
indefinite); that V4t landed narrower than §5.3 sized it, keeping texture
creation and residency with the caches and moving only the table entry, with
`IGpuTexture` creation deferred to the world arm that actually cannot use a GL
handle; why `GroupKey`'s ordering survives a retype of one of its fields; and
the pixel-gate control measurement, because one capture read 5.50e-05 against a
documented 15–23 px band and the honest response to that is a control, not a
paragraph. The decisive number is the 9-px difference between captures at the
two V4t commits — two different commits, fewer differing pixels than the
same-commit control.

`GlBindlessHandleTable`'s own doc comment claimed four renderers own instances.
Three of them no longer do. It now names its one remaining owner, `SkyRenderer`,
says why that one is different (its textures come from the raw GL-name path V4t
did not retype), and names V4f as the slice that deletes both the table and the
class.

`common.glsl`'s binding-9 comment carries the same stale list. It is left alone
deliberately: the file is a shader source with compiled `.spv` artifacts and a
V9 freshness gate, so a comment-only edit there is not free, and what the
comment says about what binding 9 IS remains correct.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-07-28 12:45:55 +02:00
parent 565c351f93
commit b9ab5890af
2 changed files with 117 additions and 11 deletions

View file

@ -18,16 +18,20 @@ namespace AcDream.App.Rendering;
/// accumulate for the renderer's lifetime, exactly like the world atlas and
/// composite-texture caches it draws handles from.
///
/// This class, plus the per-renderer SSBO it backs, is deleted at
/// V4c/V4d/V4e when each renderer moves onto <c>IGpuDevice</c>'s own
/// retirement-gated table — see the campaign doc's §5.2 for why V2 cannot
/// reach that table yet.
/// <b>Campaign V slice V4t retired every instance but one.</b> The world
/// texture stack now produces <c>GpuTextureSlot</c> directly, so
/// WbDrawDispatcher, EnvCellRenderer, TerrainModernRenderer and
/// ParticleRenderer share <c>GlGpuDevice</c>'s single retirement-gated table
/// instead of interning handles themselves — see that class's
/// <c>RegisterWorldTextureHandle</c> and the campaign doc's §5.5.11.
///
/// Each renderer that needs the indirection (WbDrawDispatcher,
/// EnvCellRenderer, TerrainModernRenderer, ParticleRenderer) owns its own
/// instance. Nothing requires index agreement between renderers: each rebinds
/// its own buffer to binding=9 immediately before its own draw call, so two
/// renderers may legitimately assign different slots to the same handle.
/// <b>The remaining owner is <c>SkyRenderer</c></b>, whose textures are minted
/// from <c>TextureCache.GetOrUpload</c>'s raw GL texture names — the one world
/// path V4t did not retype — so it is the sole consumer interning handles it
/// produced itself. Slice V4f retires that table, and this class with it.
/// Nothing requires index agreement between the sky's table and the device's:
/// each rebinds its own buffer to binding=9 immediately before its own draw
/// call, so the same handle may legitimately hold different slots in the two.
/// </summary>
internal sealed class GlBindlessHandleTable
{