Continues the V2a mesh-path conversion onto TerrainModernRenderer: its two
per-pass bindless texture handles (the terrain atlas and the alpha-mask
atlas) now travel as table indices instead of raw 64-bit
ARB_bindless_texture handles, with zero pixel change.
Terrain differs structurally from the mesh path: it has no per-batch SSBO at
all, just two handles set once per draw as plain uniforms
(terrain_modern.frag's uTerrainHandle/uAlphaHandle, reconstructed via the
sampler2DArray(handle) macros uTerrain/uAlpha). So instead of a BatchData
struct field, the two uniforms became uTextureIndexA/uTextureIndexB - named
to match the pinned GpuPushConstants.TextureIndexA/B fields (campaign doc
section 3.4) so V4d's eventual move to push constants is a rename, not a
redesign. There is no push-constant plumbing yet, so these stay plain
uniforms for now, set via ProgramUniform1 instead of ProgramUniform2.
TerrainModernRenderer owns its own GlBindlessHandleTable and binding=9 SSBO
(the same GL-only handle-table emulation V2a introduced), independent of
WbDrawDispatcher's and EnvCellRenderer's - nothing requires index agreement
between renderers, and terrain only ever registers two handles per draw
(the atlas's terrain/alpha textures), so its table is dirty only once, on
first draw. Unlike WbDrawDispatcher/EnvCellRenderer, TerrainModernRenderer
already eagerly creates its other GL resources in the constructor with a
ResourceCleanupGroup rollback, so the texture-table SSBO is created there
too rather than lazily.
TerrainAtlas needed no change: GetBindlessHandles() keeps returning the raw
(ulong terrain, ulong alpha) pair unchanged - the table lookup is entirely a
TerrainModernRenderer-side concern, added at the one draw-call site that
already converts those handles into shader state.
Shader-side: terrain_modern.frag's uTerrain/uAlpha macros now expand through
common.glsl's ACDREAM_TEXTURE_HANDLE(idx) lookup; both terrain_modern.vert
and .frag opted into the common.glsl preamble (Shader's
includeCommonPreamble, introduced at V2a) so their SceneLighting UBO
declarations could also pick up the ACDREAM_UBO_SET scaffolding macro -
terrain_modern.vert doesn't touch the texture table itself, but sharing the
same preamble across both stages of a technique is simpler to reason about
than deciding per-stage.
Gate: dotnet build -c Release green, dotnet test tests/AcDream.App.Tests
-c Release green (3843 passed / 3 skipped, matching V2a), and
tools/run-offline-pixel-gate.ps1 passed against the V2a commit's build with
a 2.49e-05 differing-pixel fraction - within the documented ~33x same-commit
noise margin. No divergence-register row: this introduces no retail
behavior deviation.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds the GPU mechanism to clip drawing to a per-cell screen-space convex
region via gl_ClipDistance, consumed by the mesh + terrain vertex shaders.
This is the MECHANISM only — every instance defaults to slot 0 (no-clip /
pass-all) and terrain to count 0, so the running game renders IDENTICALLY to
pre-U.3 (verified: offline launch compiles both shaders and reaches steady
state; no GL errors). U.4 populates real clip data from portal visibility.
Binding contract (define once, both sides obey):
- mesh_modern.vert: SSBO binding=2 CellClip[] (shared per-frame regions, slot 0
reserved no-clip) + SSBO binding=3 uint[] per-instance slot, indexed by the
IDENTICAL gl_BaseInstanceARB+gl_InstanceID used for binding=0. binding=0/1
untouched.
- terrain_modern.vert: UBO binding=2 TerrainClip { int count; vec4 planes[8]; }
for the single OutsideView region (UBO namespace; SceneLighting is UBO
binding=1, so binding=2 is free and does not collide with the mesh SSBO
binding=2). count 0 = ungated.
- Both redeclare out gl_PerVertex { vec4 gl_Position; float gl_ClipDistance[8]; }
and set unused planes (i >= count) to +1.0 so they pass everything.
CellClip std430 layout (144 bytes/slot): count@0, 3 pad uints@4/8/12,
planes[8]@16 (vec4 stride 16). Terrain UBO std140: count@0 (padded to 16),
planes[8]@16 → 144 bytes. Verified by ClipFrameLayoutTests (8 new tests).
Pieces:
- ClipFrame: per-frame container + uploader for the SHARED clip data (binding=2
SSBO + terrain UBO). NoClip() = slot 0 + terrain count 0. AppendSlot /
SetTerrainClip pack std430/std140 bytes for U.4. UploadShared binds both.
- WbDrawDispatcher + EnvCellRenderer: each owns its binding=3 zero buffer
(all-zeros sized to its instance count → slot 0), re-binds binding=2 from the
shared ClipFrame id (or an internal no-clip fallback if unwired) before MDI.
gl_ClipDistance is per-vertex, so the single glMultiDrawElementsIndirect per
group is preserved — no draw splitting.
- TerrainModernRenderer: binds the terrain clip UBO (shared or no-clip fallback)
before its draw.
- GameWindow: glEnable(GL_CLIP_DISTANCE0..7) once at init (unused planes pass-all
so always-on avoids per-draw thrash); per frame builds ClipFrame.NoClip(),
UploadShared, and hands the buffer ids to the three renderers (tiny diff; U.4
swaps NoClip() for the real portal-visibility frame).
Gate: dotnet build green; App suite 134/134; offline launch confirms both
shaders compile + link with no GL errors.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Subtract 0.01 from every terrain vertex Z in the modern terrain vertex
shader, matching retail's per-draw nudge applied inside
ACRender::landPolysDraw(arg2=2). Coplanar building floors now always win
the depth test against the rendered terrain, so the visual "ground at
the building floor" reads as the building's floor, not as Z-fighting.
Constant 0.01f bit-equals retail's float literal 0.00999999978 when
rounded to single precision.
Render-only — physics reads the un-nudged heightmap via
TerrainSurface.SampleZ / SampleZFromHeightmap. The same render-vs-
physics split is already established for EnvCell render lift
(+0.02m at GameWindow.cs around the cell-mesh draw).
Retail anchors:
docs/research/named-retail/acclient_2013_pseudo_c.txt:1120769
docs/research/named-retail/acclient_2013_pseudo_c.txt:702254
Cross-ref:
docs/research/2026-05-25-issue-100-terrain-cutout-handoff.md
docs/superpowers/plans/2026-05-25-issue-100-terrain-cutout.md
Followed by Task 2 (delete the hiddenTerrainCells / BuildingTerrainCells
plumbing). Visible result of this commit alone: building floors stop
Z-fighting, but the 24m x 24m transparent rectangles persist until the
plumbing is removed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Deletes:
- TerrainChunkRenderer.cs (454 lines, replaced by TerrainModernRenderer)
- TerrainRenderer.cs (247 lines, older sibling, no production users)
- terrain.vert / terrain.frag (replaced by terrain_modern.{vert,frag})
Removes the temporary Task 8 perf-benchmark toggle (ACDREAM_LEGACY_TERRAIN
env var, _useLegacyTerrain field, parallel _terrainLegacy renderer
instance, [TERRAIN-DIAG/modern|legacy] label suffix). The modern path
is now the only path. Mirror N.5's mandatory-modern amendment: missing
GL_ARB_bindless_texture throws NotSupportedException at startup
(already in place via the BindlessSupport.TryCreate gate).
Three load-bearing research comments preserved verbatim from terrain.vert
into terrain_modern.vert before deletion: the MIN_FACTOR = 0.0 N-dot-L
floor block (cross-ref Lambert brightness split), the aPacked3 bit
layout, the gl_VertexID corner-table 2026-04-21 ConstructPolygons fix.
Also retires the now-orphaned _shader field (legacy terrain pipeline
was its only user).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Vertex shader for the modern terrain dispatcher. Bit-identical math
to today's terrain.vert (Phase 3c per-cell mesh + Phase G AdjustPlanes
lighting). The only structural change is the version + bindless
extension preamble — sampler access stays a regular sampler2DArray
uniform; bindless-ness is invisible at the GLSL level.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
