acdream/src/AcDream.App/Rendering/ClipPlaneSet.cs

// ClipPlaneSet.cs
//
// Phase U.2c: turn a CellView (a cell's accumulated screen-space clip region,
// in NDC) into a small set of clip-space half-space planes for the GPU's
// gl_ClipDistance, OR a scissor AABB when the region can't be expressed as one
// convex plane set.
//
// This is the bridge between PortalVisibilityBuilder's 2D NDC view polygons and
// the per-vertex clip the mesh/terrain shaders will perform (Phase U.2c → U.2e).
// Pure System.Numerics math; NO GL. The shader consumes each plane as
//     d = nx*clip.x + ny*clip.y + 0*clip.z + dw*clip.w   (>= 0 ⇒ keep)
// where (nx, ny, dw) = the plane's (normal.xy, offset). z is always 0 because a
// screen-space (NDC) edge is a vertical slab in clip space — independent of depth.
//
// === The convexity rule (read before touching this file) =====================
// gl_ClipDistance planes are a CONJUNCTION of half-spaces, i.e. exactly ONE
// convex region (their intersection). A CellView with MORE THAN ONE polygon is a
// UNION of convex regions, which is in general NOT convex and CANNOT be
// represented by one plane set. Emitting just the first/largest polygon's planes
// would clip away the others → a real visibility bug (under-inclusion).
//
// Therefore From() NEVER emits a single polygon's planes when the CellView holds
// several. Multi-polygon (and >8-edge) regions degrade to the UNION AABB scissor:
// the scissor is a superset of the true region, so it OVER-includes (draws a few
// extra pixels) but never hides anything. Over-inclusion is safe; under-inclusion
// is the bug class.
//
// === The three Count==0 states (how a consumer tells them apart) =============
// Count == 0 can mean three different things; the consumer MUST distinguish:
//   (a) Empty  — IsNothingVisible == true, UseScissorFallback == false.
//                The cell/region isn't visible at all → DRAW NOTHING. The
//                ScissorNdcAabb is a degenerate inverted box (min > max) so that a
//                consumer which naively scissors on it still draws nothing.
//   (b) Scissor — UseScissorFallback == true, IsNothingVisible == false.
//                The convex-plane budget was exceeded (multi-polygon or >8 edges)
//                → DRAW the ScissorNdcAabb box (a valid min<=max NDC rectangle).
//   There is no third Count==0 state produced by From(). (A separate "no-clip,
//   pass-all" slot 0 is constructed by the consumer directly, not via From().)
// When Count > 0, Planes carries the convex gate and the scissor fields are unused.
using System;
using System.Buffers;
using System.Collections.Generic;
using System.Numerics;

namespace AcDream.App.Rendering;

/// <summary>
/// An NDC convex view region reduced to ≤8 clip-space gl_ClipDistance planes, or a
/// scissor AABB fallback. See the file header for the convexity rule and the three
/// Count==0 states.
/// </summary>
public readonly struct ClipPlaneSet
{
    // Max simultaneous hardware clip planes we target (GL guarantees >= 8).
    private const int MaxPlanes = 8;

    // Collinear-edge merge threshold. Two consecutive edge directions are treated as
    // the same edge when the turn between them is below ~0.5° (retail copy_view does a
    // ~1px screen-space dedup). |sin θ| for unit dirs = |cross|; sin(0.5°) ≈ 0.0087265.
    private const float CollinearSinEps = 0.0087265f;

    // Drop a vertex whose two incident edges are shorter than this (NDC) — a duplicate
    // or near-duplicate point that would otherwise yield a garbage normalized normal.
    private const float DegenerateEdgeLen = 1e-6f;

    // A polygon whose absolute signed area (full area, not 2x) falls below this is a line
    // or point — zero screen coverage ⇒ nothing visible. A real portal opening has area far
    // above this (e.g. the sliver-clip test region is 0.4); only an edge-on projection gets here.
    private const float MinPolygonArea = 1e-7f;
    private readonly Vector4[] _planes;

    private ClipPlaneSet(Vector4[] planes, bool useScissorFallback, bool isNothingVisible, Vector4 scissorNdcAabb)
    {
        _planes = planes ?? Array.Empty<Vector4>();
        UseScissorFallback = useScissorFallback;
        IsNothingVisible = isNothingVisible;
        ScissorNdcAabb = scissorNdcAabb;
    }

    /// <summary>Number of active clip planes, 0..8. 0 ⇒ inspect <see cref="UseScissorFallback"/>
    /// and <see cref="IsNothingVisible"/> to decide between "draw the AABB" and "draw nothing".</summary>
    public int Count => _planes?.Length ?? 0;

    /// <summary>The active clip-space planes (nx, ny, 0, d). Empty when <see cref="Count"/> is 0.
    /// A clip-space point <c>clip</c> is inside iff <c>Vector4.Dot(plane, clip) &gt;= 0</c> for every plane.</summary>
    public IReadOnlyList<Vector4> Planes => _planes ?? (IReadOnlyList<Vector4>)Array.Empty<Vector4>();

    // The set is immutable after construction. ClipFrameAssembler transfers this exact array into
    // its frame-scoped slice instead of cloning every plane payload a second time.
    internal Vector4[] PlaneArray => _planes ?? Array.Empty<Vector4>();

    /// <summary>True ⇒ the convex-plane budget was exceeded; gate on <see cref="ScissorNdcAabb"/>
    /// instead (draw the box). Always false when <see cref="Count"/> &gt; 0 or when the region is empty.</summary>
    public bool UseScissorFallback { get; }

    /// <summary>True ⇒ the region is not visible at all; the consumer draws NOTHING.
    /// Mutually exclusive with <see cref="UseScissorFallback"/>, and only meaningful when Count == 0.</summary>
    public bool IsNothingVisible { get; }

    /// <summary>NDC axis-aligned scissor box (minX, minY, maxX, maxY). Valid (min &lt;= max) only when
    /// <see cref="UseScissorFallback"/> is true. For the empty/nothing-visible case it is a degenerate
    /// inverted box so naive scissoring still draws nothing.</summary>
    public Vector4 ScissorNdcAabb { get; }

    /// <summary>The "nothing is visible" sentinel: Count == 0, not a scissor fallback, draw nothing.</summary>
    public static ClipPlaneSet Empty { get; } =
        new(Array.Empty<Vector4>(), useScissorFallback: false, isNothingVisible: true, scissorNdcAabb: DegenerateAabb);

    // Inverted box (min > max) — any sane AABB intersection against it is empty.
    private static Vector4 DegenerateAabb => new(1f, 1f, -1f, -1f);

    /// <summary>
    /// Reduce a CellView's NDC clip region to a ClipPlaneSet. One convex polygon (≤8 edges
    /// after collinear-merge) → per-edge planes; multi-polygon or >8 edges → union-AABB scissor;
    /// empty/degenerate → <see cref="Empty"/>. See the file header for the full rule.
    /// </summary>
    public static ClipPlaneSet From(CellView region)
    {
        if (region is null || region.IsEmpty || region.Polygons.Count == 0)
            return Empty;

        // MORE THAN ONE polygon ⇒ union, not convex ⇒ never emit one polygon's planes.
        // Over-include via the union AABB (safe). region.Min/Max already track the union.
        if (region.Polygons.Count > 1)
            return Scissor(region.MinX, region.MinY, region.MaxX, region.MaxY);

        return From(region.Polygons[0]);
    }

    /// <summary>
    /// Reduce one convex view polygon without wrapping it in a temporary <see cref="CellView"/>.
    /// The clip-frame assembler already iterates individual retail <c>view_poly</c> slices, so
    /// constructing a CellView there needlessly ran the flood's canonical-key/dedup machinery for
    /// every slice on every frame. This overload is behavior-identical to the one-polygon branch
    /// of <see cref="From(CellView)"/> and avoids that unrelated allocation path.
    /// </summary>
    public static ClipPlaneSet From(in ViewPolygon polygon)
    {
        if (polygon.IsEmpty)
            return Empty;

        // Exactly one polygon: normalize winding to CCW and merge collinear edges in reusable
        // scratch. The surviving vertices are consumed immediately to build the actual plane
        // payload; there is no reason to allocate a second exact-sized polygon array per slice.
        Vector2[] input = polygon.Vertices;
        Vector2[]? rented = null;
        Span<Vector2> verts = input.Length <= 32
            ? stackalloc Vector2[input.Length]
            : (rented = ArrayPool<Vector2>.Shared.Rent(input.Length)).AsSpan(0, input.Length);

        try
        {
            int count = NormalizeAndMerge(input, verts);

            // Fewer than 3 distinct edges survive ⇒ a sliver/line with no area. There is no
            // meaningful AABB to over-include (a zero-area region), so treat it as nothing visible.
            if (count < 3)
                return Empty;

            ReadOnlySpan<Vector2> normalized = verts[..count];

            // A single convex polygon with too many edges to fit the hardware budget ⇒ scissor
            // on ITS own AABB (still a superset of the polygon → over-include, safe).
            if (count > MaxPlanes)
                return Scissor(normalized);

            // 3..8 edges: emit one inward half-space plane per edge (CCW formula). This array is
            // the retained GPU-routing payload and therefore the one necessary allocation.
            var planes = new Vector4[count];
            for (int i = 0; i < count; i++)
            {
                Vector2 p = normalized[i];
                Vector2 q = normalized[(i + 1) % count];
                Vector2 dir = q - p;
                // Inward normal for CCW winding: perp(dir) = (-dir.y, dir.x) points to the polygon's
                // interior (the "left" side of the directed edge p→q).
                Vector2 n = Vector2.Normalize(new Vector2(-dir.Y, dir.X));
                // Plane: n·x + d >= 0 inside, with d = -(n·p). In clip space with NDC x = clip.x/clip.w:
                //   dist = n.x*clip.x + n.y*clip.y + 0*clip.z + (-(n·p))*clip.w   (>= 0 ⇒ keep)
                planes[i] = new Vector4(n.X, n.Y, 0f, -Vector2.Dot(n, p));
            }
            return new ClipPlaneSet(planes, useScissorFallback: false, isNothingVisible: false, scissorNdcAabb: DegenerateAabb);
        }
        finally
        {
            if (rented is not null)
                ArrayPool<Vector2>.Shared.Return(rented);
        }
    }

    private static ClipPlaneSet Scissor(float minX, float minY, float maxX, float maxY) =>
        new(Array.Empty<Vector4>(), useScissorFallback: true, isNothingVisible: false,
            scissorNdcAabb: new Vector4(minX, minY, maxX, maxY));

    private static ClipPlaneSet Scissor(ReadOnlySpan<Vector2> verts)
    {
        float minX = float.MaxValue, minY = float.MaxValue, maxX = float.MinValue, maxY = float.MinValue;
        foreach (var v in verts)
        {
            if (v.X < minX) minX = v.X;
            if (v.X > maxX) maxX = v.X;
            if (v.Y < minY) minY = v.Y;
            if (v.Y > maxY) maxY = v.Y;
        }
        return Scissor(minX, minY, maxX, maxY);
    }

    /// <summary>
    /// Return the polygon wound CCW with collinear vertices removed. The PortalVisibilityBuilder
    /// already EnsureCcw's its output, but From() is a public entry point that must be robust to
    /// either winding (e.g. a hand-built CellView), so we normalize here too.
    /// </summary>
    private static int NormalizeAndMerge(ReadOnlySpan<Vector2> input, Span<Vector2> points)
    {
        if (input.Length < 3)
            return 0;

        // 1) Drop exact/near-duplicate consecutive points first so edge directions are well-defined.
        int count = 0;
        foreach (Vector2 vertex in input)
        {
            if (count == 0 || (vertex - points[count - 1]).LengthSquared() > DegenerateEdgeLen * DegenerateEdgeLen)
                points[count++] = vertex;
        }
        // Wrap-around duplicate (last == first).
        if (count >= 2 && (points[count - 1] - points[0]).LengthSquared() <= DegenerateEdgeLen * DegenerateEdgeLen)
            count--;
        if (count < 3)
            return 0;

        // 2) Force CCW winding (positive signed area). perp(dir)=(-y,x) is the inward normal only
        //    for CCW; if the caller handed us CW, reverse so the plane signs come out inside-positive.
        if (SignedArea2(points[..count]) < 0f)
            points[..count].Reverse();

        // 3) Merge collinear edges: drop vertex i when edge (i-1→i) and edge (i→i+1) point the same
        //    way (turn angle < ~0.5°). Iterate until stable — removing one vertex can expose a new
        //    collinear triple. |cross(a,b)| of unit dirs = |sin θ|; dot>0 rules out a 180° reversal.
        bool changed = true;
        while (changed && count >= 3)
        {
            changed = false;
            for (int i = 0; i < count; i++)
            {
                Vector2 prev = points[(i - 1 + count) % count];
                Vector2 cur = points[i];
                Vector2 next = points[(i + 1) % count];

                Vector2 d0 = cur - prev;
                Vector2 d1 = next - cur;
                float l0 = d0.Length();
                float l1 = d1.Length();
                if (l0 < DegenerateEdgeLen || l1 < DegenerateEdgeLen)
                {
                    points[(i + 1)..count].CopyTo(points[i..]);
                    count--;
                    changed = true;
                    break;
                }

                d0 /= l0;
                d1 /= l1;
                float cross = d0.X * d1.Y - d0.Y * d1.X; // sin θ
                float dot = d0.X * d1.X + d0.Y * d1.Y;   // cos θ
                if (dot > 0f && MathF.Abs(cross) < CollinearSinEps)
                {
                    points[(i + 1)..count].CopyTo(points[i..]);
                    count--; // cur lies on the straight line prev→next
                    changed = true;
                    break;
                }
            }
        }

        if (count < 3)
            return 0;

        // Final degeneracy gate: a polygon with negligible area is a line/point even if it still
        // has >= 3 distinct vertices (e.g. an edge-on portal, or a near-collinear triple the 0.5°
        // merge didn't quite collapse). Emitting its planes would yield an empty half-space
        // intersection that silently gates out everything; report it honestly as nothing-visible.
        if (MathF.Abs(SignedArea2(points[..count])) * 0.5f < MinPolygonArea)
            return 0;

        return count;
    }

    // Twice the signed area (the "shoelace" sum). > 0 ⇒ CCW, < 0 ⇒ CW.
    private static float SignedArea2(ReadOnlySpan<Vector2> poly)
    {
        float a = 0f;
        for (int i = 0; i < poly.Length; i++)
        {
            Vector2 p = poly[i];
            Vector2 q = poly[(i + 1) % poly.Length];
            a += p.X * q.Y - q.X * p.Y;
        }
        return a;
    }
}