Skip to content

fix(web,xr): inverted shadow-caster normal bias and <three-live section-plane> - #104

Merged
jbingham merged 1 commit into
mainfrom
fix/shadow-caster-bias-section-plane
Nov 16, 2026
Merged

jbingham merged 1 commit into
mainfrom
fix/shadow-caster-bias-section-plane

Conversation

@jbingham

@jbingham jbingham commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Bug 1: fake "overhang" shadow band on flush multi-story walls.
Both shadow depth vertex shaders (WebGL2 VS_SHADOW_DEPTH, WebGPU
vsShadowDepth) pushed casters outward along +N by ~1.75 shadow texels
(~5-6 cm on a house+lawn scene), while the receiver (shdEval / WGSL) also
offsets outward along +N. The inflated upper wall stuck out past a flush lower
wall and the light-facing faces self-shadowed.

  • Casters now shrink inward along -N (applyShadowCasterNormalBias is the CPU
    reference; GLSL and WGSL match it).
  • Receivers now carry the full normal bias
    (SHADOW_RECEIVER_NORMAL_BIAS_SCALE = 1.0, was 0.5) on WebGL2 and WebGPU.
    This keeps PCF taps across light-facing convex edges (a wall's top face
    meeting its front face at the floor joint) and grazing sloped/curved
    surfaces free of acne.

Bug 2: <three-live section-plane> did nothing to the mesh.

  • New src/section-plane.ts (resolveSectionPlane) is used by the
    WebGL2 color pass, WebGPU, and the shadow pass.
    resolveShadowSectionPlane now delegates to it.
  • ThreeView.render() binds uSectionEnabled/uSectionPlane on every
    primitive from the host's section-plane. It no longer hardcodes 0.
    Backdrop and plugin meshes are not clipped.
  • ThreeLiveElement observes section-plane, re-renders when it changes, and
    exposes a sectionPlane getter/setter. The duplicate entry in
    XRLiveElement.observedAttributes is removed.
  • exploded-view (xr-live) still overrides the uniforms when its gizmo or
    section is active. When inactive, it no longer zeroes the core binding.

Tests (written to fail first):

  • shadow_maps_test: CPU shadow-map rasterizer that mirrors the shader math
    (caster bias, polygonOffset(1.5, 4), bilinear LEQUAL compare, receiver
    normal offset, 8-tap Vogel PCF). Scene: 22x18 m lawn, flush stacked walls
    at y=0..3 and y=3..6, and an angled castShadow sun. Checks:
    • The legacy +N bias darkens the wall (min 0.92).
    • The fixed bias gives shadow == 1.0 below the joint and across both faces,
      for 4 sun directions and 1024/2048 maps.
    • The lawn behind the walls is still shadowed.
    • No acne on the sloped slab, sphere, or lawn.
      Also covers GLSL/WGSL inward-bias parity and toggling
      section-plane y:0.0 -> none in the shadow pass (uSecOn, plane, upper-half
      clip, digest invalidation).
  • three_view_test: <three-live section-plane="y:0.0"> clips the upper half
    in the WebGL2 color pass without xr-live, and "none" restores the full mesh.
  • three_webgpu_test: WebGPU receiver bias matches WebGL2, and section-plane
    toggles the scene uniforms.
  • three_live_element_test: observedAttributes, the sectionPlane property,
    and re-render on change.

Kit packaging: THREE.Architecture is not part of
compile_three_live_full_min (kits are opt-in). Use
three-live-kit-architecture.min.js
(compile_three_live_kit_architecture_min, loaded after the full bundle). Its
installArchitectureKit is registered as a worker extension installer, so it
reaches worker sandboxes with no shims (kit_architecture_test covers this).

xr-live golden tests: xr_plugins_test and xr_sim_test were already failing at
head in hermetic test runners. The bundled test is a CAS symlink, so __dirname resolves
outside the runfiles tree. Golden lookup now also resolves relative to the node
entry path (process.argv[1]), which keeps the symlinked location. All 38
three-live + xr-live tests pass.

Verified: npm test passes (all three-live + xr-live suites).

…on-plane>

Bug 1: fake "overhang" shadow band on flush multi-story walls.
Both shadow depth vertex shaders (WebGL2 `VS_SHADOW_DEPTH`, WebGPU
`vsShadowDepth`) pushed casters *outward* along +N by ~1.75 shadow texels
(~5-6 cm on a house+lawn scene), while the receiver (`shdEval` / WGSL) also
offsets outward along +N. The inflated upper wall stuck out past a flush lower
wall and the light-facing faces self-shadowed.
- Casters now shrink inward along -N (`applyShadowCasterNormalBias` is the CPU
  reference; GLSL and WGSL match it).
- Receivers now carry the full normal bias
  (`SHADOW_RECEIVER_NORMAL_BIAS_SCALE = 1.0`, was 0.5) on WebGL2 and WebGPU.
  This keeps PCF taps across light-facing convex edges (a wall's top face
  meeting its front face at the floor joint) and grazing sloped/curved
  surfaces free of acne.

Bug 2: `<three-live section-plane>` did nothing to the mesh.
- New `src/section-plane.ts` (`resolveSectionPlane`) is used by the
  WebGL2 color pass, WebGPU, and the shadow pass.
  `resolveShadowSectionPlane` now delegates to it.
- `ThreeView.render()` binds `uSectionEnabled`/`uSectionPlane` on every
  primitive from the host's `section-plane`. It no longer hardcodes 0.
  Backdrop and plugin meshes are not clipped.
- `ThreeLiveElement` observes `section-plane`, re-renders when it changes, and
  exposes a `sectionPlane` getter/setter. The duplicate entry in
  `XRLiveElement.observedAttributes` is removed.
- `exploded-view` (xr-live) still overrides the uniforms when its gizmo or
  section is active. When inactive, it no longer zeroes the core binding.

Tests (written to fail first):
- shadow_maps_test: CPU shadow-map rasterizer that mirrors the shader math
  (caster bias, polygonOffset(1.5, 4), bilinear LEQUAL compare, receiver
  normal offset, 8-tap Vogel PCF). Scene: 22x18 m lawn, flush stacked walls
  at y=0..3 and y=3..6, and an angled castShadow sun. Checks:
  - The legacy +N bias darkens the wall (min 0.92).
  - The fixed bias gives shadow == 1.0 below the joint and across both faces,
    for 4 sun directions and 1024/2048 maps.
  - The lawn behind the walls is still shadowed.
  - No acne on the sloped slab, sphere, or lawn.
  Also covers GLSL/WGSL inward-bias parity and toggling
  section-plane y:0.0 -> none in the shadow pass (uSecOn, plane, upper-half
  clip, digest invalidation).
- three_view_test: `<three-live section-plane="y:0.0">` clips the upper half
  in the WebGL2 color pass without xr-live, and "none" restores the full mesh.
- three_webgpu_test: WebGPU receiver bias matches WebGL2, and section-plane
  toggles the scene uniforms.
- three_live_element_test: observedAttributes, the `sectionPlane` property,
  and re-render on change.

Kit packaging: `THREE.Architecture` is not part of
`compile_three_live_full_min` (kits are opt-in). Use
`three-live-kit-architecture.min.js`
(`compile_three_live_kit_architecture_min`, loaded after the full bundle). Its
`installArchitectureKit` is registered as a worker extension installer, so it
reaches worker sandboxes with no shims (kit_architecture_test covers this).

xr-live golden tests: xr_plugins_test and xr_sim_test were already failing at
head in hermetic test runners. The bundled test is a CAS symlink, so `__dirname` resolves
outside the runfiles tree. Golden lookup now also resolves relative to the node
entry path (`process.argv[1]`), which keeps the symlinked location. All 38
three-live + xr-live tests pass.

Verified: `npm test` passes (all three-live + xr-live suites).
@jbingham
jbingham force-pushed the fix/shadow-caster-bias-section-plane branch from 7030b6c to 1311e9b Compare November 16, 2026 16:14
@jbingham
jbingham merged commit 9ba8d67 into main Nov 16, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant