Skip to content

LumosLab-Innovation/3D-lab-skills / plugins/threejs-lab/skills/threejs-screen-space-ambient-occlusion

threejs-screen-space-ambient-occlusion

Verified

Implement a production GTAO path in Three.js. Use for half-resolution horizon sampling, reversed-depth reconstruction, bent-normal encoding, full-resolution bilateral reconstruction, environment-light application, contact grounding, and halo diagnosis.

FileKindSize
LICENSEother1.0 KB
SKILL.mdskill md1.6 KB
agents/openai.yamlconfig357 B
references/gtao-bent-normal-pipeline.mdmarkdown10.6 KB

references/gtao-bent-normal-pipeline.md

View on GitHub
# GTAO and bent-normal pipeline

Use this reference for a bounded-cost WebGPU/TSL ambient-visibility pass with half-resolution horizon integration, bent normals, bilateral reconstruction, and directional ambient tint.

## Contents

1. Gather budget and depth convention
2. World-radius projection and horizon integration
3. Bent-normal encoding
4. Bilateral reconstruction
5. Indirect-light composite
6. Implementation defects, adaptation, and diagnostics

## 1. Preserve the actual budget

The gather uses:

```text
resolution scale     0.5 × 0.5
slices               2
steps per side       4
sides per slice      2
depth taps           16 per half-resolution pixel
target               RGBA16F
RGB                   bent direction encoded to [0, 1]
A                     scalar visibility, 1 = open
```

Half linear resolution means one quarter of full-resolution fragments.

The implementation targets an approximately `2 ms` budget by combining:

- half-resolution gather;
- few slices;
- interleaved-gradient-noise rotation;
- direct UV marching;
- one view-position reconstruction per tap;
- sky early-outs in gather and composite.

Do not increase slices first. Validate whether the bilateral pass and stable
rotation already remove directional structure.

## 2. Preserve the depth convention

The implementation uses reversed depth:

```text
sky threshold          0.000001
maximum reconstruction 0.999999
```

Sky is cleared to zero. Far terrain remains above the sky threshold.

Gather:

```text
if rawDepth <= 1e-6:
  output visibility = 1
  output encoded bent = encoded view normal
  skip all 16 taps
```

Composite clamps depth to `[0, 0.999999]` before linearization so sky
neighbours do not create extreme view-Z values.

Do not port these thresholds to a forward-depth target unchanged.

## 3. Preserve world-radius projection

Default controls:

```text
radius              0.5 m
intensity           1.0
power               1.6
thickness           0.35 m in view Z
bentNormalStrength  0.6
```

The horizontal projection scale is cached from:

```text
camera.projectionMatrix.elements[0]
```

and refreshed every frame.

World radius becomes UV reach:

```text
radiusUv =
  radius
  * projectionScaleX
  / max(-viewPosition.z, 0.0001)
  * 0.5

radiusUv = clamp(radiusUv, 0.004, 0.08)
```

This clamp prevents near surfaces searching half the screen and stops far
surfaces collapsing to a useless footprint.

Observed adaptation issue: only the X projection term is used, then one scalar
radius is applied to both UV axes. At unusual aspect ratios or asymmetric
projections, derive a `vec2` reach from both projection axes.

## 4. Rotate two horizon slices per pixel

For slice `i`:

```text
noise = interleavedGradientNoise(screenCoordinate)
angle = (i / 2 + noise) * PI
sliceDirection = (cos(angle), sin(angle))
```

The axis covers both positive and negative directions, so angles only span
`PI`, not `2 * PI`.

Step spacing:

```text
t = (stepIndex + noise + 0.5) / 4
stepUv = sliceDirection * radiusUv * t
```

The shared noise rotates slices and jitters their radial positions.

The pass has no temporal accumulation. Its stability depends on the
noise being screen-stable and the full-resolution spatial composite.

## 5. Keep horizon angle and distance falloff separate

For each positive and negative sample:

```text
delta = sampleViewPosition - centerViewPosition
distance = max(length(delta), 0.0001)
falloff = saturate(1 - distance / max(radius, 0.0001))
```

Accept the sample only when:

```text
abs(delta.z) < thickness
```

Raw horizon cosine:

```text
cosine = dot(delta, viewDirection) / distance
```

Apply distance falloff by mixing toward fully open:

```text
horizon = mix(-1, cosine, falloff)
maxHorizon = max(maxHorizon, horizon)
```

Do not multiply the cosine directly by falloff. Mixing toward `-1` weakens a
distant occluder without changing the angle of a nearby one.

Per slice:

```text
positiveAngle = acos(clamp(positiveHorizon, -1, 1))
negativeAngle = acos(clamp(negativeHorizon, -1, 1))
visibility += saturate((positiveAngle + negativeAngle) / PI)
```

Final scalar:

```text
visibility = visibility / 2
visibility = visibility ^ power
visibility = saturate(mix(1, visibility, intensity))
```

Disabling the pass sets intensity to zero; the gather still runs unless the
owner removes or bypasses the node. If disabled cost matters, bypass the pass
at pipeline construction or add an update/render gate.

## 6. Treat the bent direction as an observed heuristic

For accepted samples, the gather accumulates:

```text
bentDirection +=
  normalize(delta)
  * saturate(cosine * falloff)
```

Then:

```text
bent = normalize(
  mix(
    viewNormal,
    normalize(viewDirection + bentDirection),
    bentNormalStrength
  )
)
```

The output stores `bent * 0.5 + 0.5`.

Important objective finding: the accumulated vectors point toward accepted
sample positions. A physically derived bent normal normally points toward
unoccluded directions, so do not assume this sign convention is correct in an
adaptation.

Required validation:

```text
place a flat receiver beside one vertical wall
show geometric normal
show decoded bent direction
show environment sample direction
verify the direction turns away from the blocked hemisphere
```

If it turns toward the wall, negate/rederive the directional accumulator
before using it for environment lighting.

## 7. Own gather rendering state

`GtaoNode.updateBefore()`:

1. saves/reset renderer state through `RendererUtils`;
2. reads drawing-buffer dimensions;
3. resizes the half-resolution target;
4. refreshes projection scale;
5. renders one fullscreen `QuadMesh`;
6. restores renderer state.

Dispose both the target and node material.

Do not let a post node leak render target, viewport, or material state into the
main pipeline.

## 8. Upsample with the exact kernel

The full-resolution composite gathers eight neighbours:

```text
left, right, up, down
four diagonals
center omitted
```

Each weight is depth-only:

```text
weight = exp(-abs(sampleViewZ - centerViewZ) / 0.5)
```

If total weight is above `0.01`, normalize the eight-sample sum. Otherwise use
the center AO texel.

This is an eight-neighbour `3×3` ring with the center skipped, not a cross.

The rationale is to cover the four-pixel interleaved-gradient-noise repeat
while sampling across half-resolution AO texels.

Observed limitation: `screenTexelHint()` returns only:

```text
1 / screenWidth
```

and uses that scalar for both X and Y offsets. At non-square viewports the
vertical step is wrong. Adapt as:

```text
texel = vec2(1 / width, 1 / height)
```

Observed limitation: the filter has no normal-similarity weight despite having
the normal buffer available later in the composite. Thin foreground/background
contacts may need:

```text
weight *= pow(saturate(dot(centerNormal, sampleNormal)), normalPower)
```

Add this only after confirming the depth-only kernel causes cross-edge leakage;
normal buffers can be noisy at hard edges.

## 9. Apply AO only to reconstructed indirect light

Do not multiply final scene color by AO.

It approximates indirect light:

```text
irradiance =
  PMREM sampled along bent direction at texture level 1
  or fallback cavity color (0.55, 0.62, 0.78)

indirectEstimate =
  albedo
  * environmentIntensity
  * irradiance

indirect = min(indirectEstimate, sceneColor)
direct = sceneColor - indirect
```

The clamp ensures direct light never becomes negative.

Then:

```text
occludedIndirect = indirect * visibility

deviation =
  saturate(1 - dot(decodedBentView, geometricViewNormal))

tintAmount =
  deviation
  * (1 - visibility)
  * bentTintStrength

bentTintStrength default = 0.35

tintedIndirect =
  mix(
    occludedIndirect,
    occludedIndirect * irradiance,
    saturate(tintAmount)
  )

output = direct + tintedIndirect
```

This keeps direct sun and most specular response out of the AO multiply.

The indirect reconstruction is still approximate because it works from a
forward-shaded scene color and an albedo MRT. Specular energy can leak into
the `direct` residual. Prefer a renderer-provided indirect-diffuse signal when
available.

## 10. Verify view/world transform semantics

The composite decodes the bent direction in view space and calls:

```text
transformDirection(bentView, cameraViewMatrix)
```

while describing the result as view-to-world.

Matrix-direction semantics in TSL are version-sensitive. Verify the installed
Three.js behavior with axis probes:

```text
camera facing -Z:
  view (0, 0, 1) maps to expected world direction

camera rotated 90 degrees:
  decoded bent direction rotates with the camera exactly once
```

Do not copy the matrix expression solely from the comment.

## 11. Temporal behavior

This pipeline has no motion vectors, history target, reprojection,
neighborhood clamp, or disocclusion rejection.

Do not describe it as temporally accumulated GTAO.

If adding temporal accumulation:

1. preserve raw half-resolution visibility and bent direction;
2. add representative depth/normal validity;
3. reproject with velocity;
4. clamp scalar visibility to the current neighborhood;
5. constrain bent history by angular deviation;
6. reset on camera cuts and resolution changes.

First verify whether the current stable-noise plus bilateral pass already meets
the target. Temporal history adds ghosting risk to moving procedural geometry.

## 12. Required diagnostics

Expose:

```text
raw reversed depth and linear view Z
sky classification
view normal
projected radius UV/pixels
slice angle and jitter
positive/negative horizon cosine
thickness acceptance
distance falloff
visibility before power/intensity
raw encoded and decoded bent direction
one-sided-wall bent-direction test
eight bilateral sample depths and weights
X/Y texel offsets
upsampled visibility
albedo and environment irradiance
indirect estimate before/after scene-color clamp
direct residual
tint deviation and amount
final direct versus indirect contribution
GPU time for gather and composite
```

Failure diagnosis:

```text
AO radius changes with distance incorrectly:
  world radius was replaced by a fixed pixel radius

far surfaces lose all contact:
  projected radius was not clamped to a minimum

thick silhouette halos:
  thickness or depth-only bilateral weights cross discontinuities

vertical blur differs from horizontal blur:
  width-derived scalar texel size was used for Y

bent tint points into walls:
  the observed accumulator sign was accepted without a one-sided-wall test

sunlit surfaces become gray:
  visibility multiplied final scene color instead of reconstructed indirect

disabled AO still costs the full pass:
  intensity was set to zero without bypassing gather rendering

camera rotation changes tint incorrectly:
  view-to-world direction transform semantics were not verified
```
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall