using System; using System.Numerics; using AcDream.App.Rendering; using Xunit; namespace AcDream.App.Tests.Rendering; public class PortalProjectionTests { // A simple GL-style perspective looking down -Z, camera at origin. private static Matrix4x4 ViewProj() { var view = Matrix4x4.CreateLookAt(Vector3.Zero, new Vector3(0, 0, -1), Vector3.UnitY); var proj = Matrix4x4.CreatePerspectiveFieldOfView(1.0f, 1.0f, 0.1f, 1000f); return view * proj; } [Fact] public void Project_QuadInFront_ProducesNdcInsideViewport() { // A 2x2 quad at z=-5 (in front), cell-local == world (identity transform). var poly = new[] { new Vector3(-1, -1, -5), new Vector3(1, -1, -5), new Vector3(1, 1, -5), new Vector3(-1, 1, -5), }; var r = PortalProjection.ProjectToNdc(poly, Matrix4x4.Identity, ViewProj()); Assert.True(r.Length >= 3); foreach (var v in r) { Assert.InRange(v.X, -1.001f, 1.001f); Assert.InRange(v.Y, -1.001f, 1.001f); } } [Fact] public void Project_QuadFullyBehind_ReturnsEmpty() { var poly = new[] { new Vector3(-1, -1, 5), new Vector3(1, -1, 5), new Vector3(1, 1, 5), new Vector3(-1, 1, 5), }; var r = PortalProjection.ProjectToNdc(poly, Matrix4x4.Identity, ViewProj()); Assert.True(r.Length < 3); } [Fact] public void Project_QuadStraddlingCamera_ClipsWithoutInversion() { // Spans from behind (z=+2) to in front (z=-5). Must clip to the in-front part, // never produce a wildly out-of-range inverted vertex. var poly = new[] { new Vector3(-1, -1, 2), new Vector3(1, -1, -5), new Vector3(1, 1, -5), new Vector3(-1, 1, 2), }; var r = PortalProjection.ProjectToNdc(poly, Matrix4x4.Identity, ViewProj()); Assert.True(r.Length >= 3); foreach (var v in r) { // A corner a few cm in front of the eye and ~1 m to the side genuinely // projects large (~±37 NDC) but finite. ±50 still catches the ±7852 // perspective-inversion blow-up the old w-clip produced. Assert.InRange(v.X, -50f, 50f); // bounded — no inversion blow-up Assert.InRange(v.Y, -50f, 50f); } } [Fact] public void Project_QuadStraddlingCamera_DownstreamIntersectionIsValidOnScreen() { var poly = new[] { new Vector3(-1, -1, 2), new Vector3(1, -1, -5), new Vector3(1, 1, -5), new Vector3(-1, 1, 2), }; var projected = PortalProjection.ProjectToNdc(poly, Matrix4x4.Identity, ViewProj()); Assert.True(projected.Length >= 3); // The viewport region (NDC [-1,1]^2), same as CellView.FullScreen()'s single polygon. var viewport = CellView.FullScreen().Polygons[0].Vertices; var onScreen = ScreenPolygonClip.Intersect(projected, viewport); Assert.True(onScreen.Length >= 3); // a non-empty visible region survives foreach (var v in onScreen) { Assert.InRange(v.X, -1.001f, 1.001f); Assert.InRange(v.Y, -1.001f, 1.001f); } } [Fact] public void Project_QuadStraddlingCamera_NdcStaysWithinScreen() { // R1 void-flap fix (2026-06-05): the eye-plane-only clip (w>MinW) let small-w verts // explode under the perspective divide (~±37 NDC). Those off-screen NDC then corrupted // the downstream 2D ScreenPolygonClip, which at glancing/close angles collapsed to EMPTY // -> OutsideView empty -> terrain Skip -> the bluish "void" at the cottage doorway. // Clipping the 4 frustum SIDE planes in clip space (homogeneous, before the divide) // bounds every projected vertex to the screen [-1,1] by construction. RED before the fix. var poly = new[] { new Vector3(-1, -1, 2), new Vector3(1, -1, -5), new Vector3(1, 1, -5), new Vector3(-1, 1, 2), }; var r = PortalProjection.ProjectToNdc(poly, Matrix4x4.Identity, ViewProj()); Assert.True(r.Length >= 3); foreach (var v in r) { Assert.InRange(v.X, -1.001f, 1.001f); // bounded to the screen — no off-screen explosion Assert.InRange(v.Y, -1.001f, 1.001f); } } [Fact] public void Project_CloseDoorway_NdcStaysWithinScreen_AndCoversScreen() { // The probe-confirmed void frame (2026-06-05): the chase eye is ~0.28 m from the front-door // EXIT portal — well inside RetailChaseCamera's 1.0 m near plane — and looking through it. // The door subtends the whole screen, but the old clip produced NDC like (10.2,-67.4) and // ScreenPolygonClip reduced it to clip=0 (the void). After the homogeneous side-plane clip // the NDC stays on-screen AND the door still covers the viewport (non-empty), not the void. var view = Matrix4x4.CreateLookAt(Vector3.Zero, new Vector3(0, 0, -1), Vector3.UnitY); var proj = Matrix4x4.CreatePerspectiveFieldOfView(MathF.PI / 3f, 16f / 9f, 1.0f, 5000f); // RetailChaseCamera var viewProj = view * proj; // A 2 m x 2 m doorway 0.28 m in front of the eye, facing it. var doorway = new[] { new Vector3(-1f, -1f, -0.28f), new Vector3(1f, -1f, -0.28f), new Vector3(1f, 1f, -0.28f), new Vector3(-1f, 1f, -0.28f), }; var projected = PortalProjection.ProjectToNdc(doorway, Matrix4x4.Identity, viewProj); Assert.True(projected.Length >= 3); foreach (var v in projected) { Assert.InRange(v.X, -1.001f, 1.001f); Assert.InRange(v.Y, -1.001f, 1.001f); } var viewport = CellView.FullScreen().Polygons[0].Vertices; var onScreen = ScreenPolygonClip.Intersect(projected, viewport); Assert.True(onScreen.Length >= 3, "a doorway the eye looks through must cover the screen, not collapse to the void"); } [Fact] public void Project_PortalEyeIsAlmostTouching_StaysVisibleOnScreen() { // Regression (2026-06-03 doorway "void"): the chase camera orbits to ~0.1 m from a // doorway portal. With RetailChaseCamera's 1.0 m near plane and the old w+z>=0 GL // near-clip — which, for a D3D CreatePerspectiveFieldOfView matrix, discards everything // within ~0.5 m of the eye — the whole doorway was clipped to empty, so the room behind // it was culled and rendered as a dark void (camera-orientation dependent; rotating away // fixed it). The eye-clip must be near-INDEPENDENT: a portal you're standing in must // still project (covering the screen) so the cell behind stays visible. var view = Matrix4x4.CreateLookAt(Vector3.Zero, new Vector3(0, 0, -1), Vector3.UnitY); var proj = Matrix4x4.CreatePerspectiveFieldOfView(MathF.PI / 3f, 16f / 9f, 1.0f, 5000f); // RetailChaseCamera var viewProj = view * proj; // A 2 m x 2 m doorway 0.1 m in front of the eye, facing it. var doorway = new[] { new Vector3(-1f, -1f, -0.1f), new Vector3(1f, -1f, -0.1f), new Vector3(1f, 1f, -0.1f), new Vector3(-1f, 1f, -0.1f), }; var projected = PortalProjection.ProjectToNdc(doorway, Matrix4x4.Identity, viewProj); Assert.True(projected.Length >= 3, "a doorway 0.1 m from the eye must still project (was clipped to empty -> void)"); var viewport = CellView.FullScreen().Polygons[0].Vertices; var onScreen = ScreenPolygonClip.Intersect(projected, viewport); Assert.True(onScreen.Length >= 3, "the cell behind a doorway you're standing in must stay visible (the void bug)"); } // --------------------------------------------------------------------------- // Faithful homogeneous (w-space) portal clip — port of retail PView::GetClip + // PrimD3DRender::xformStart + ACRender::polyClipFinish (decomp 432344 / 424310 / // 702749). The early divide + fixed side-plane clamp (ProjectToNdc) collapsed // grazing/near portals to zero-area edge slivers (-> the flap) and near doorways // to empty (-> the void/fallback). The faithful pipeline keeps homogeneous clip // coords (ProjectToClip — eye-plane clip only, no divide) and runs Sutherland- // Hodgman against the view region with w-aware edge tests, dividing the survivors // only after they are bounded to the region (ClipToRegion). 2026-06-06. // --------------------------------------------------------------------------- private static Vector2[] FullScreenCcw() => new[] { new Vector2(-1f, -1f), new Vector2(1f, -1f), new Vector2(1f, 1f), new Vector2(-1f, 1f), }; [Fact] public void ProjectToClip_QuadInFront_KeepsVertsWithPositiveW() { var poly = new[] { new Vector3(-1, -1, -5), new Vector3(1, -1, -5), new Vector3(1, 1, -5), new Vector3(-1, 1, -5), }; var clip = PortalProjection.ProjectToClip(poly, Matrix4x4.Identity, ViewProj()); Assert.True(clip.Length >= 3); foreach (var v in clip) Assert.True(v.W > 0f, $"an in-front portal vertex must keep w>0 (homogeneous), got w={v.W}"); } [Fact] public void ProjectToClip_QuadFullyBehind_ReturnsEmpty() { var poly = new[] { new Vector3(-1, -1, 5), new Vector3(1, -1, 5), new Vector3(1, 1, 5), new Vector3(-1, 1, 5), }; Assert.True(PortalProjection.ProjectToClip(poly, Matrix4x4.Identity, ViewProj()).Length < 3); } [Fact] public void ClipToRegion_OnScreenQuad_ReturnsBoundedNdc() { // A small 2x2 quad at z=-5 is fully on-screen; clipping against the full screen // returns it bounded to [-1,1]. var poly = new[] { new Vector3(-1, -1, -5), new Vector3(1, -1, -5), new Vector3(1, 1, -5), new Vector3(-1, 1, -5), }; var clip = PortalProjection.ProjectToClip(poly, Matrix4x4.Identity, ViewProj()); var ndc = PortalProjection.ClipToRegion(clip, FullScreenCcw()); Assert.True(ndc.Length >= 3); foreach (var v in ndc) { Assert.InRange(v.X, -1.001f, 1.001f); Assert.InRange(v.Y, -1.001f, 1.001f); } } [Fact] public void ClipToRegion_FullyOffScreen_ReturnsEmpty_NotSliver() { // The flap's root: a portal entirely off one screen edge. The old early-divide + // side-plane clamp collapsed it to a zero-area sliver pinned to x=1.0 (proj=3) that // propagated a degenerate region one hop and then died; the faithful clip returns // EMPTY so the flood stops cleanly. Quad at z=-5, x in [3,5] -> ndc x ~[1.1,1.8], off right. var poly = new[] { new Vector3(3, -1, -5), new Vector3(5, -1, -5), new Vector3(5, 1, -5), new Vector3(3, 1, -5), }; var clip = PortalProjection.ProjectToClip(poly, Matrix4x4.Identity, ViewProj()); var ndc = PortalProjection.ClipToRegion(clip, FullScreenCcw()); Assert.True(ndc.Length < 3, $"fully off-screen portal must clip to empty, got {ndc.Length} verts (sliver)"); } [Fact] public void ClipToRegion_PartlyOffScreen_ClipsToBoundedNonEmpty() { // A quad straddling the right edge -> clipped to the on-screen part, bounded, non-empty. var poly = new[] { new Vector3(0, -1, -5), new Vector3(4, -1, -5), new Vector3(4, 1, -5), new Vector3(0, 1, -5), }; var clip = PortalProjection.ProjectToClip(poly, Matrix4x4.Identity, ViewProj()); var ndc = PortalProjection.ClipToRegion(clip, FullScreenCcw()); Assert.True(ndc.Length >= 3, "a partly-on-screen portal must produce a non-empty clipped region"); foreach (var v in ndc) { Assert.InRange(v.X, -1.001f, 1.001f); Assert.InRange(v.Y, -1.001f, 1.001f); } } [Fact] public void ClipToRegion_DoorwayEyeLooksThrough_CoversScreen_WithoutFallback() { // The void frame: chase eye 0.28 m from a 2x2 m doorway, looking through it. The doorway // subtends the whole screen. The faithful clip keeps the homogeneous verts (no early-divide // blow-up) and clips to the screen quad -> covers the screen (non-empty). This is what makes // the EyeInsidePortalOpening *fallback* unnecessary for an in-front doorway. var view = Matrix4x4.CreateLookAt(Vector3.Zero, new Vector3(0, 0, -1), Vector3.UnitY); var proj = Matrix4x4.CreatePerspectiveFieldOfView(MathF.PI / 3f, 16f / 9f, 1.0f, 5000f); var viewProj = view * proj; var doorway = new[] { new Vector3(-1f, -1f, -0.28f), new Vector3(1f, -1f, -0.28f), new Vector3(1f, 1f, -0.28f), new Vector3(-1f, 1f, -0.28f), }; var clip = PortalProjection.ProjectToClip(doorway, Matrix4x4.Identity, viewProj); var ndc = PortalProjection.ClipToRegion(clip, FullScreenCcw()); Assert.True(ndc.Length >= 3, "a doorway the eye looks through must cover the screen, not collapse to the void"); foreach (var v in ndc) { Assert.InRange(v.X, -1.001f, 1.001f); Assert.InRange(v.Y, -1.001f, 1.001f); } } [Fact] public void ClipToRegion_StraddlingEye_OnScreenBounded_NoBlowup() { // A portal spanning from behind (z=+2) to in front (z=-5). The faithful clip keeps the // in-front part and bounds it to the screen — no perspective-inversion blow-up, non-empty. var poly = new[] { new Vector3(-1, -1, 2), new Vector3(1, -1, -5), new Vector3(1, 1, -5), new Vector3(-1, 1, 2), }; var clip = PortalProjection.ProjectToClip(poly, Matrix4x4.Identity, ViewProj()); var ndc = PortalProjection.ClipToRegion(clip, FullScreenCcw()); Assert.True(ndc.Length >= 3); foreach (var v in ndc) { Assert.InRange(v.X, -1.001f, 1.001f); Assert.InRange(v.Y, -1.001f, 1.001f); } } private static float AbsArea(Vector2[] p) { if (p == null || p.Length < 3) return 0f; float a2 = 0f; for (int i = 0; i < p.Length; i++) { var u = p[i]; var w = p[(i + 1) % p.Length]; a2 += u.X * w.Y - w.X * u.Y; } return MathF.Abs(a2) * 0.5f; } [Fact] public void ClipToRegion_SubjectFullyInsideRegion_ReturnsSubjectNotRegion() { // Regression for Build_AppliesReciprocalOtherPortalClip: a NARROW subject fully inside a WIDE // region must return the narrow (subject ∩ region = subject), NOT the wide region. The builder's // reciprocal clip is exactly this shape (reciprocal opening ∩ near-side region). var view = Matrix4x4.CreateLookAt(Vector3.Zero, new Vector3(0, 0, -1), Vector3.UnitY); var proj = Matrix4x4.CreatePerspectiveFieldOfView(1.2f, 1.0f, 0.1f, 1000f); var vp = view * proj; var narrow = new[] { new Vector3(-0.3f, -0.9f, -3f), new Vector3(0.3f, -0.9f, -3f), new Vector3(0.3f, 0.9f, -3f), new Vector3(-0.3f, 0.9f, -3f) }; var wide = new[] { new Vector3(-0.9f, -0.9f, -3f), new Vector3(0.9f, -0.9f, -3f), new Vector3(0.9f, 0.9f, -3f), new Vector3(-0.9f, 0.9f, -3f) }; var narrowClip = PortalProjection.ProjectToClip(narrow, Matrix4x4.Identity, vp); // Build the region exactly as the builder does (clip wide against the full screen → CCW region). var wideRegion = PortalProjection.ClipToRegion(PortalProjection.ProjectToClip(wide, Matrix4x4.Identity, vp), FullScreenCcw()); var clipped = PortalProjection.ClipToRegion(narrowClip, wideRegion); float narrowArea = AbsArea(PortalProjection.ClipToRegion(narrowClip, FullScreenCcw())); float wideArea = AbsArea(wideRegion); float clippedArea = AbsArea(clipped); Assert.True(clippedArea <= narrowArea + 1e-3f, $"subject∩region must be the narrow subject (area {narrowArea}), not the wide region (area {wideArea}); got {clippedArea}"); } [Fact] public void ClipToRegion_AgainstSubRegion_TightensToIntersection() { // The region clip is the propagation step: clipping a wide on-screen portal against a // narrower view region must yield the intersection (the narrow region), not the wide portal. var wide = new[] { new Vector3(-2, -2, -5), new Vector3(2, -2, -5), new Vector3(2, 2, -5), new Vector3(-2, 2, -5), }; var clip = PortalProjection.ProjectToClip(wide, Matrix4x4.Identity, ViewProj()); var narrow = new[] { new Vector2(-0.3f, -0.3f), new Vector2(0.3f, -0.3f), new Vector2(0.3f, 0.3f), new Vector2(-0.3f, 0.3f), }; var ndc = PortalProjection.ClipToRegion(clip, narrow); Assert.True(ndc.Length >= 3); foreach (var v in ndc) { Assert.InRange(v.X, -0.301f, 0.301f); Assert.InRange(v.Y, -0.301f, 0.301f); } } // --------------------------------------------------------------------------- // The W=0 knife-edge port (2026-06-11) — retail ACRender::polyClipFinish part 1 // (0x006b6d00, pc:702749; pseudocode at docs/research/2026-06-11-polyclipfinish- // w0-clip-pseudocode.md). The eye-plane clip is at w >= 0 EXACTLY: boundary // intersections land at w == 0 (homogeneous directions), so a portal the eye is // CROSSING (stair openings on a spiral climb, the tower deck) yields the correct // unbounded half-region that the bounded view-region clip then cuts to the // screen. The previous EyePlaneW = 1e-4 made the boundary verts finite ~1e4-NDC // points and the resulting regions sat at the merge/dedup degeneracy threshold — // the climb-strobe class that the (now deleted) EyeInsidePortalOpening rescue // compensated for. // --------------------------------------------------------------------------- [Fact] public void ProjectToClip_EyeCrossingPortal_BoundaryVertsLandAtWZero() { // A horizontal floor opening 5 mm BELOW the eye, spanning from 1.5 m ahead to // 0.5 m behind — the spiral-climb crossing frame. The two edges crossing the // eye plane must emit intersections at exactly w == 0 (retail polyClipFinish // t = w0/(w0-w1)), not at an epsilon offset. var opening = new[] { new Vector3(-1f, -0.005f, -1.5f), new Vector3(1f, -0.005f, -1.5f), new Vector3(1f, -0.005f, 0.5f), new Vector3(-1f, -0.005f, 0.5f), }; var clip = PortalProjection.ProjectToClip(opening, Matrix4x4.Identity, ViewProj()); Assert.True(clip.Length >= 3, "an eye-crossing portal must keep its forward half"); int atZero = 0; foreach (var v in clip) { Assert.True(v.W >= 0f, $"no survivor may sit behind the eye plane, got w={v.W}"); if (v.W == 0f) atZero++; } Assert.True(atZero >= 2, $"the two eye-plane crossings must land at exactly w==0, got {atZero}"); } [Fact] public void ClipToRegion_EyeCrossingFloorOpening_YieldsHalfRegionNotSliver() { // Same crossing frame: the visible set through an opening the eye is inside is // the half-screen below the opening's plane horizon — NOT the degenerate sliver // the epsilon clip produced. Full screen area is 4.0; the half-region must hold // a substantial part of it. var opening = new[] { new Vector3(-1f, -0.005f, -1.5f), new Vector3(1f, -0.005f, -1.5f), new Vector3(1f, -0.005f, 0.5f), new Vector3(-1f, -0.005f, 0.5f), }; var clip = PortalProjection.ProjectToClip(opening, Matrix4x4.Identity, ViewProj()); var ndc = PortalProjection.ClipToRegion(clip, FullScreenCcw()); Assert.True(ndc.Length >= 3, "the crossing frame must produce a region, not empty (the climb strobe)"); foreach (var v in ndc) { Assert.True(float.IsFinite(v.X) && float.IsFinite(v.Y), $"region verts must be finite, got ({v.X},{v.Y})"); Assert.InRange(v.X, -1.001f, 1.001f); Assert.InRange(v.Y, -1.001f, 1.001f); } float area = AbsArea(ndc); Assert.True(area > 1.5f, $"the region must approximate the lower half-screen (area ~2.0 of 4.0), got {area} (sliver = the strobe bug)"); } [Fact] public void EyeInPortalPlane_GazeAlongPlane_DegenerateViewPropagates() { // The spiral-climb knife edge: the eye sits IN a horizontal portal's plane with // the gaze ALONG the plane (climbing stairs through the opening). The opening is // visibly edge-on ON screen: ProjectToClip + ClipToRegion yield a zero-area // collinear region — and retail PROPAGATES it (ClipPortals forwards any count!=0 // clip; no area gate), keeping the cell behind in the draw list. CellView.Add // must therefore ACCEPT the collinear polygon (the "L:" segment key) instead of // rejecting it as degenerate — rejection dropped the whole chain for the frame. var view = Matrix4x4.CreateLookAt(Vector3.Zero, new Vector3(0, 0, -1), Vector3.UnitY); var proj = Matrix4x4.CreatePerspectiveFieldOfView(MathF.PI / 3f, 16f / 9f, 1.0f, 5000f); var vp = view * proj; // Horizontal opening in the y=0 plane (contains the eye), ahead of the camera. var opening = new[] { new Vector3(-1f, 0f, -1f), new Vector3(1f, 0f, -1f), new Vector3(1f, 0f, -4f), new Vector3(-1f, 0f, -4f), }; var clip = PortalProjection.ProjectToClip(opening, Matrix4x4.Identity, vp); Assert.True(clip.Length >= 3, "the in-plane opening's forward part must survive the W clip"); var ndc = PortalProjection.ClipToRegion(clip, FullScreenCcw()); Assert.True(ndc.Length >= 3, "the edge-on opening must yield its (zero-area) collinear region"); var cellView = new CellView(); Assert.True(cellView.Add(new ViewPolygon(ndc)), "a zero-area collinear view must be ACCEPTED (retail propagates degenerate views; " + "rejecting it drops the cell chain at the knife edge)"); // Re-emission of the same degenerate view dedups (finite segment-key space = convergence). Assert.False(cellView.Add(new ViewPolygon(ndc)), "a re-emitted degenerate view must dedup via its segment key"); } [Fact] public void ClipToRegion_NeverReturnsNonFiniteVerts() { // The measure-zero guard: whatever survives the bounded region clip must divide // to finite NDC. Exercise with a portal whose vertices sit ON the eye plane // (w == 0 inputs) plus one in front — degenerate input, must yield empty or finite. var degenerate = new[] { new Vector3(-1f, 0f, 0f), new Vector3(1f, 0f, 0f), new Vector3(0f, 1f, -2f), }; var clip = PortalProjection.ProjectToClip(degenerate, Matrix4x4.Identity, ViewProj()); if (clip.Length >= 3) { var ndc = PortalProjection.ClipToRegion(clip, FullScreenCcw()); foreach (var v in ndc) Assert.True(float.IsFinite(v.X) && float.IsFinite(v.Y), $"non-finite NDC vert leaked from the divide: ({v.X},{v.Y})"); } } }