docs(render): S3 hygiene lens closeout — the clip-distance doc names every writer; AppendSlot's doc drops the U.4 AABB promise

The hygiene lens's one blocking finding was a sentence the lead's own
§10.6 prescribed: 'only portal_depth.vert writes gl_ClipDistance in the
world pass'. Five mesh/particle vertex shaders still write it from the
per-cell clip-region table PrepareClipFrame publishes (dormant in the walk
path, which feeds slot 0; live for the flat path). The doc now says so.
ClipFrame.AppendSlot's doc still promised a U.4 AABB box that no longer
exists after H1. Comments only; no behavior change.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-09-03 18:25:53 +02:00
parent 99d9c6d564
commit d0c9812122
2 changed files with 20 additions and 13 deletions

View file

@ -155,12 +155,13 @@ public sealed class ClipFrame : IDisposable
/// <summary>
/// Append one clip region (becomes the next slot index) from a
/// <see cref="ClipPlaneSet"/>. Only the convex-plane case is supported in
/// U.3 — <c>Count &gt; 0</c> packs that many planes; <c>Count == 0</c> packs a
/// no-clip region (pass-all). The scissor / nothing-visible fallbacks that
/// <see cref="ClipPlaneSet"/> can carry are deferred to U.4 (which will draw
/// the AABB box or skip the cell on the CPU side, not via this slot). Returns
/// the new slot's index.
/// <see cref="ClipPlaneSet"/>: <c>Count &gt; 0</c> packs that many planes;
/// <c>Count == 0</c> packs a no-clip region (pass-all) — that is the
/// whole contract for both of <see cref="ClipPlaneSet"/>'s empty states
/// (nothing visible is decided by the caller before it appends; a plane
/// overflow draws unclipped, over-include). There is no scissor and no
/// AABB anywhere on this path (S3 landing hygiene, H1). Returns the new
/// slot's index.
/// </summary>
public int AppendSlot(ClipPlaneSet set)
{

View file

@ -56,13 +56,19 @@ internal interface IWorldPassSurface
///
/// <para>Vulkan activates every element the shader declares and has no
/// enable, so this is a no-op there — and that is safe rather than a
/// divergence: only <c>portal_depth.vert</c> writes <c>gl_ClipDistance</c>
/// in the world pass now (S3 landing hygiene, H4 — S3 chunk 4 fix round 2
/// (L3) deleted the sky and terrain shaders' own declaration of the block
/// this contract used to also publish; see <see cref="PrepareClipFrame"/>'s
/// doc). It still writes <c>1.0</c> ("keep everything") into every slot
/// past its active count, so a frame with no clip planes clips nothing on
/// either backend (plan §5.5.14 item 4).</para>
/// divergence. Two shader families still write <c>gl_ClipDistance</c> in
/// the world pass: <c>portal_depth.vert</c> (the exit seals and punch fans,
/// planes handed per draw) and the mesh/particle vertex shaders
/// (<c>mesh_modern</c>, <c>mesh_atmospheric</c>, <c>mesh_detail</c>,
/// <c>particle</c>, <c>particle_mesh</c>), which read the per-cell
/// clip-region table this contract publishes through
/// <see cref="PrepareClipFrame"/>. The walk feeds every ordinary part and
/// every particle slot 0 (no clip), so in the walk path that table is
/// dormant; the sky and terrain shaders no longer declare any clip block
/// at all (S3 chunk 4 fix round 2, L3). Every writer sets <c>1.0</c>
/// ("keep everything") in each slot past its active count, so a frame
/// with no clip planes clips nothing on either backend (plan §5.5.14
/// item 4).</para>
/// </summary>
void EnableClipDistances();