From 9ec83307fc66b9bad22d2eab5f6a39d6b7a8db1d Mon Sep 17 00:00:00 2001 From: Erik Date: Fri, 29 May 2026 11:57:30 +0200 Subject: [PATCH] =?UTF-8?q?docs(render):=20Phase=20A8.F=20=E2=80=94=20corr?= =?UTF-8?q?ect=20PortalProjection=20near-clip=20comments?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The clip predicate (w+z>=0) is convention-agnostic, not GL-specific: Matrix4x4.CreatePerspectiveFieldOfView (which all acdream cameras use) is NDC z in [0,1], not [-1,1]. Comment said "GL near plane / z_ndc>=-1" which is misleading though the code is correct (eye w=0 always excluded; divide safe under both conventions). Also soften the ProjectToNdc CCW claim: it preserves projected winding; the caller must feed camera-facing portals. No behavior change. (Opus code-review I-1/M-1.) Co-Authored-By: Claude Opus 4.7 --- src/AcDream.App/Rendering/PortalProjection.cs | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/src/AcDream.App/Rendering/PortalProjection.cs b/src/AcDream.App/Rendering/PortalProjection.cs index 852d9a1..e34b5f6 100644 --- a/src/AcDream.App/Rendering/PortalProjection.cs +++ b/src/AcDream.App/Rendering/PortalProjection.cs @@ -1,9 +1,13 @@ // PortalProjection.cs // // Phase A8.F: project a cell-local portal polygon to NDC screen space, clipping -// against the GL near plane (w + z >= 0, i.e. z_ndc >= -1) so a portal straddling -// the camera does not invert under the perspective divide. At the near plane w is -// bounded away from zero, so the divide is safe — no eye-singularity blow-up. +// against the in-front-of-camera half-space (keep where w + z >= 0) so a portal +// straddling the camera does not invert under the perspective divide. This crossing +// excludes the eye (w = 0) and lands just in front of the near plane, so every kept +// vertex has w bounded away from zero and the divide is safe — no eye-singularity +// blow-up. The predicate is convention-agnostic: acdream's cameras build projection +// with Matrix4x4.CreatePerspectiveFieldOfView (NDC z in [0,1]); under a true GL +// [-1,1] matrix w + z = 0 is exactly the near plane. Either way the eye is excluded. // Homogeneous form of the near-plane sidedness in retail PView::GetClip / // ConstructView(CBldPortal) (decomp:432344 / 433832). using System.Collections.Generic; @@ -13,8 +17,11 @@ namespace AcDream.App.Rendering; public static class PortalProjection { - /// Project a cell-local polygon to NDC. Returns CCW NDC xy verts, or - /// fewer than 3 verts when the polygon is entirely behind the camera / degenerate. + /// Project a cell-local polygon to NDC, preserving the projected winding of + /// the input (NOT normalized to CCW). The caller (PortalVisibilityBuilder) is responsible + /// for feeding camera-facing portal polygons (via the portal-side test) so the result is + /// CCW for the CCW-only . Returns fewer than 3 verts when + /// the polygon is entirely behind the camera / degenerate. public static Vector2[] ProjectToNdc(IReadOnlyList localPoly, Matrix4x4 cellToWorld, Matrix4x4 viewProj) { if (localPoly == null || localPoly.Count < 3) return System.Array.Empty(); @@ -26,7 +33,7 @@ public static class PortalProjection foreach (var lp in localPoly) clip.Add(Vector4.Transform(new Vector4(lp, 1f), m)); - // Clip against the GL near plane (keep where w + z >= 0). + // Clip against the in-front-of-camera half-space (keep where w + z >= 0). clip = ClipAgainstNearPlane(clip); if (clip.Count < 3) return System.Array.Empty(); @@ -40,7 +47,7 @@ public static class PortalProjection return ndc; } - // Sutherland-Hodgman against the GL near plane: keep where (w + z) >= 0 (z >= -w, i.e. z_ndc >= -1). + // Sutherland-Hodgman against the in-front-of-camera half-space: keep where (w + z) >= 0. private static List ClipAgainstNearPlane(List poly) { var result = new List(poly.Count + 1);