erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs(render): Phase A8.F — correct PortalProjection near-clip comments

Browse source 
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 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-05-29 11:57:30 +02:00
parent a28a176ad6
commit 9ec83307fc
1 changed files with 14 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

21
src/AcDream.App/Rendering/PortalProjection.cs
View file

@ -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
{
/// <summary>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.</summary>
/// <summary>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 <see cref="ScreenPolygonClip"/>. Returns fewer than 3 verts when
/// the polygon is entirely behind the camera / degenerate.</summary>
public static Vector2[] ProjectToNdc(IReadOnlyList<Vector3> localPoly, Matrix4x4 cellToWorld, Matrix4x4 viewProj)
{
if (localPoly == null || localPoly.Count < 3) return System.Array.Empty<Vector2>();
@ -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<Vector2>();
@ -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<Vector4> ClipAgainstNearPlane(List<Vector4> poly)
{
var result = new List<Vector4>(poly.Count + 1);