What it does. 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. Part of scottstts/Threejs-Awesome-Graphics-Agent-Skills (scottstts/Threejs-Awesome-Graphics-Agent-Skills).


Upstream	scottstts/Threejs-Awesome-Graphics-Agent-Skills
Skill file	skills/threejs-screen-space-ambient-occlusion/SKILL.md
License	MIT
Author	Scott Sun (scottstts)
Fetched	2026-09-10

Install

npx skills add scottstts/Threejs-Awesome-Graphics-Agent-Skills --skill threejs-screen-space-ambient-occlusion, or copy the skill folder into ~/.claude/skills/threejs-screen-space-ambient-occlusion/.
Raw file: curl -sL https://raw.githubusercontent.com/scottstts/Threejs-Awesome-Graphics-Agent-Skills/HEAD/skills/threejs-screen-space-ambient-occlusion/SKILL.md

SKILL.md (verbatim)

name: threejs-screen-space-ambient-occlusion
description: 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.

Screen-Space Ambient Occlusion

AO estimates missing ambient visibility. It must modulate indirect lighting, not repaint all scene color with a dark multiply.

Workflow

Verify linear depth and view-space normals.
Reconstruct view position consistently.
Sample horizon visibility in a controlled radius.
Estimate AO and optional bent normal.
Denoise with depth/normal-aware filters.
Apply to indirect diffuse and environment response.

Read references/gtao-bent-normal-pipeline.md.

Failure conditions

direct light and emission are darkened;
radius is specified only in pixels;
foreground silhouettes cast thick screen-space halos;
depth discontinuities are blurred together;
AO remains strong at distances where its world radius is subpixel;
bent normals are treated as ordinary geometric normals;
the implementation claims temporal accumulation even though this path has none.

Routing boundary

This skill owns GTAO gathering, bent normals, denoising, and AO application. Use $threejs-image-pipeline only when its depth/normal buffers or pass order must be coordinated with other image-space systems.

Other files in this skill

references/gtao-bent-normal-pipeline.md (verbatim)

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.

Preserve the actual budget
Preserve the depth convention
Preserve world-radius projection
Rotate two horizon slices per pixel
Keep horizon angle and distance falloff separate
Treat the bent direction as an observed heuristic
Own gather rendering state
Upsample with the exact kernel
Apply AO only to reconstructed indirect light
Verify view/world transform semantics
Temporal behavior
Required diagnostics

1. Preserve the actual budget

The gather uses:

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:

sky threshold          0.000001
maximum reconstruction 0.999999

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

Gather:

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:

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:

camera.projectionMatrix.elements[0]

and refreshed every frame.

World radius becomes UV reach:

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:

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:

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:

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

Accept the sample only when:

abs(delta.z) < thickness

Raw horizon cosine:

cosine = dot(delta, viewDirection) / distance

Apply distance falloff by mixing toward fully open:

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:

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

Final scalar:

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:

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

Then:

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:

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():

saves/reset renderer state through RendererUtils;
reads drawing-buffer dimensions;
resizes the half-resolution target;
refreshes projection scale;
renders one fullscreen QuadMesh;
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:

left, right, up, down
four diagonals
center omitted

Each weight is depth-only:

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:

1 / screenWidth

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

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:

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:

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:

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:

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:

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:

preserve raw half-resolution visibility and bent direction;
add representative depth/normal validity;
reproject with velocity;
clamp scalar visibility to the current neighborhood;
constrain bent history by angular deviation;
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:

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:

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

Back to scottstts/Threejs-Awesome-Graphics-Agent-Skills or Agent skills.

threejs-screen-space-ambient-occlusion skill (Threejs-Awesome-Graphics-Agent-Skills)