acdream/docs/research/2026-06-11-polyclipfinish-w0-clip-pseudocode.md

ACRender::polyClipFinish — W=0 eye-plane clip pseudocode (the knife-edge port)

Source: ACRender::polyClipFinish at 0x006b6d00, docs/research/named-retail/acclient_2013_pseudo_c.txt:702749-702988. Read 2026-06-11 for the knife-edge in-plane portal clip port (handoff docs/research/2026-06-11-tower-stairs-fundamental-handoff.md §5).

Signature (reconstructed)

polyClipFinish(view_vertex** inVerts,   // arg1 — homogeneous clip-space verts (x,y,z,w)
               int           inCount,   // arg2
               Vec2Dscreen** outVerts,  // arg3 — output vertex pointers
               int*          outCount,  // arg4
               int           planeMask) // arg5 — per-edge skip mask (bit set = poly already
                                        //        fully inside that portal_view edge)

Part 1 — the W=0 eye-plane pass (0x006b6d5d–0x006b6f12)

scan = inCount - 1
while scan >= 0:                         # walk verts from the END
    if inVerts[scan].w < 0: break        # found a vertex BEHIND the eye plane → must clip
    scan -= 1
if scan < 0: goto edge_clips             # all w >= 0 → skip the W pass entirely

# homogeneous Sutherland-Hodgman against w = 0, intersections EMITTED:
out = []
prev = inVerts[0]; prevIn = (prev.w >= 0)
for cur in inVerts[last..0]:             # retail iterates indices descending
    curIn = (cur.w >= 0)
    if curIn != prevIn:
        t = prev.w / (prev.w - cur.w)    # 0x006b6ea0: w0 / (w0 - w1)
        emit(prev + t*(cur - prev))      # interpolates x, y, z, w → lands at w == 0 exactly
    if curIn: emit(cur)
    prev, prevIn = cur, curIn

if len(out) < 3: return                  # 0x006b6f00: reject — fewer than 3 survivors
inVerts = out                            # ping-pong to tempPtBuf

x87 flag-decode note (the BN polarity trap, feedback_bn_decomp_field_names): the scan loop's test ah, 0x5 (C0|C2) breaks on w < 0, NOT w ≥ 0. Decoded by case analysis: the all-behind polygon must reach the W pass and clip to empty (reject), and the common all-in-front polygon must skip the pass — only the break-on-negative decode yields both. The inside predicate in the clip pass (test ah, 0x41, C0|C3) is inside ⇔ w ≥ 0 (emit-on-sign-change with t = w0/(w0−w1) confirms: t∈[0,1] requires opposite signs).

Part 2 — portal_view edge clips (0x006b6d82–0x006b7030)

for each portal_view edge (vertex pair), mask-gated (planeMask bit set → skip):
    # homogeneous 2D edge function for vertex P against edge (a → b):
    #   side(P) = (P.x − a.x·P.w)·(b.y − a.y) − (P.y − a.y·P.w)·(b.x − a.x)
    # (0x006b6e05) — linear in (x, y, w): valid for w = 0 verts (directions).
    Sutherland-Hodgman with intersection emission (t = s0/(s0 − s1), all 4 comps)
    if survivors < 3: return             # 0x006b6fe1
*outCount = survivors                    # 0x006b7006

The load-bearing semantics for acdream

1. Clip at w ≥ 0 EXACTLY — boundary intersections land at w == 0. A w=0 vertex is a homogeneous DIRECTION; the polygon containing it represents the unbounded screen region extending toward that direction. This is what makes an eye-crossing portal (climbing through a stair opening) produce the correct large half-region instead of a bounded sliver:
   • At w ≥ ε (our old EyePlaneW = 1e-4), boundary verts are finite NDC points ~1e4 units out along the portal-plane horizon line; the polygon's screen intersection still APPROXIMATES the half-region, but the divide and the dedup/merge operate on degenerate near-collinear coordinates.
   • At w = 0, the edge functions stay exact (linear in homogeneous coords) and no divide ever touches a w=0 vertex (see invariant below).
2. A w=0 vertex can never survive the region clip into the divide when the clip region is BOUNDED: for a bounded convex CCW region the edge directions wrap 360°, so a nonzero direction fails at least one edge's inside test. Our regions are always bounded (FullScreenQuad and its descendants), so the post-clip divide is safe by construction. The measure-zero exception (direction exactly on a region corner) is guarded by a non-finite check that returns empty — identical net behavior to retail's degenerate sliver.
3. Empty is a verdict, not an error. < 3 survivors → reject at every stage; retail has NO eye-in-opening rescue anywhere in this path. The acdream EyeInsidePortalOpening rescue was the documented compensation for the EyePlaneW = 1e-4 divergence (T2 ledger) and is deleted with this port.

What is NOT ported here

• cdstW = 0.000199999995 (pinned at 0x007247d5) — consumed elsewhere (its consumer is still unmapped; landPolysDraw 0x006b7040 uses the same 0.0002 inline for plane side tests). PortalSideEpsilon = 0.01 stays as the documented root-lag tolerance (T2 refutation: retail's 0.0002 needs eye-exact viewer-cell tracking first).
• The planeMask per-edge skip — a perf short-circuit; our ClipToRegion clips against every region edge unconditionally.
• Retail's descending vertex iteration order — Sutherland-Hodgman output is order-invariant up to rotation; we keep ascending.