Ambient Contact Shading

Ambient Contact Shading

AO is visibility of indirect illumination. It may attenuate indirect diffuse and environment/specular response; it must not multiply direct light, emission, UI, or a tone-mapped frame.

Use $threejs-choose-skills for renderer and budget preflight. Use $threejs-image-pipeline when depth, normal, velocity, history, tone mapping, or adaptive resolution are shared.

Numeric provenance

Every quantitative claim is tagged:

• [Derived] follows from r185 source or an explicit formula.
• [Gated] is a branch condition that must pass on the target scene/device.
• [Measured] is recorded target-device evidence, never a portable promise.
• [Authored] is a starting value or planning ceiling, not a fact of hardware.

Release numbers and list ordering are identifiers, not tuning claims.

Decide whether screen AO is the right algorithm

Use the first row whose gate passes:

The second lit pass is not an implementation detail. r185 GTAONode needs current depth/normal before AO exists, while builtinAOContext() must be present when materials are lit. A single stock forward pass cannot satisfy both dependencies. If the first pass exists only for AO, count its color attachment, material evaluation, deformation, alpha testing, draw submission, and depth/ normal writes; calling it a cheap prepass is incorrect.

r185 API proof and non-negotiable constraints

Verified against installed three@0.185.1 [Measured]:

Initialize and hard-gate WebGPU before graph construction:

await renderer.init();

if ( renderer.backend.isWebGPUBackend !== true ) {
  throw new Error( 'threejs-ambient-contact-shading requires WebGPU.' );
}

if ( renderer.reversedDepthBuffer === true ) {
  throw new Error( 'r185 GTAONode baseline is not validated for reversed depth.' );
}

There is no non-WebGPU implementation in this skill.

Production graph

shared-or-AO-owned scene pass: depth + optional normal/velocity
  -> GTAONode scalar visibility
  -> optional materialized depth+normal-aware reconstruction
  -> second forward scene pass with builtinAOContext(visibility)
  -> optional TRAANode over final HDR beauty
  -> single tone-map/output-transform owner

Rules:

• Share an existing depth/normal/velocity pass when it is already required. Do not create duplicate G-buffers.
• A half-scale raw AO texture receives only ordinary texture filtering when sampled at full resolution; that is not bilateral reconstruction.
• Use rtt(denoise(...)) to materialize reconstruction once before the second scene pass. Directly embedding denoise(...) in builtinAOContext() repeats its taps over scene overdraw.
• Sample the materialized texture with screenUV before passing it to builtinAOContext(). Pass textures default to fullscreen uv() only while evaluated by a fullscreen quad; material evaluation otherwise resolves ordinary mesh UV attributes.
• Use the full-resolution normal MRT when reconstruction is enabled or when another effect already owns normals. For raw reduced-resolution GTAO alone, benchmark a normal attachment against depth reconstruction.
• Keep scalar visibility in a single channel. Use RGBA16F only when a custom bent direction and scalar visibility must coexist.
• Bypass inactive AO nodes. Zeroing strength while keeping dependencies in the output graph still executes work.

Read references/gtao-bent-normal-pipeline.md for the exact graph, tap model, memory equations, temporal contract, and bent- normal validation.

Physics Scale And Presentation Contract

When the route declares physical metre-scale contact, resolve AO distances through PhysicsContext and the current presentation transform in the physics domain and interaction contract. Let sRender be CameraViewPublication.globalToRenderCurrent.renderUnitsPerMeter:

radiusRender    = radiusMeters    * sRender                  [Derived]
thicknessRender = thicknessMeters * sRender                  [Derived]
biasRender      = biasMeters      * sRender                  [Derived]

For the ordinary authored-world mapping, gate sRender = 1 / PhysicsContext.metersPerWorldUnit; a deliberate visualization rescale declares a new RenderSimilarityTransform.transformRevision and uses its exact dimensioned transform. biasRender applies only to a custom AO bias that is dimensionally a world distance; normalized-depth or angular biases retain their own declared units. If the route intentionally uses perceptual scene units, label radius, thickness, and bias as scene-unit-only and do not compare them across scaled assets, physics contexts, or rebases as metres. A static/stylistic route may use this mode without instantiating the physics ABI.

Latch the immutable central PhysicsPresentationSnapshot and resolve its exact Candidate, CameraViewPublication, and ViewPreparationPublication; do not define an AO-local subset. AO, depth, velocity, camera, and downstream history consume candidate pair refs/signal descriptors, camera transforms/matrices, and the preparation reactive/reset plan from the same chain. Temporal velocity uses adjacent presented poses, never fixed-step endpoints. A compensated origin rebase keeps AO radius, depth, and motion invariant only when previous/current uniform scales are equal. A scale change converts AO parameters and resets/reseeds history; it is not an origin rebase.

The Candidate supplies pose/deformation pairs, the camera publication supplies complete render transforms/matrices, and the Snapshot references both plus the preparation publication. Depth, normal, and velocity are target/view render-pass resources produced after sealing and carry their image-pipeline resource versions; never misclassify those attachments as physics provider signals.

Reset/reject AO history for changed geometry/deformation/coverage, camera or projection discontinuity, uncompensated rebase, AO scale/parameter change, or quality/resolution migration. A shadow or emissive-only radiance change does not change scalar ambient visibility; preserve AO history, but propagate its radiance-reactive mask to a downstream color history only when that temporal implementation supports it. Stock r185 TRAANode does not; use evidenced rebuild/bypass/reseed or a conservative full reset. When no local mask can bound a geometry discontinuity, reset the affected history conservatively. ViewPreparationPublication.resetDependencies is immutable; append executed actions to FrameExecutionRecord. Device loss appends a FrameExecutionRecord with overallStatus: device-lost, affected target execution statuses device-lost, cancelled dependent actions, and lost-generation entries in leaseDispositionById; it invalidates AO/history resources and timing proof without mutating the sealed snapshot. Rebuild under the new backend/resource generation.

Quality gates

samples is not the number of depth taps. In r185:

D = samples < 30 ? 3 : 5                         [Derived]
S = floor((samples + D - 1) / D)                [Derived]
horizon depth taps per GTAO pixel = 2 * D * S    [Derived]
samples = 16 -> 36 depth taps                    [Derived]
samples = 8  -> 18 depth taps                    [Derived]

Increase samples only after scale, radius, reconstruction, and temporal policy have been validated.

Composable marginal budget

Measure toggles with the same camera path and warmed pipelines:

deltaAO = time(complete AO graph) - time(no-screen-AO graph)       [Measured]
deltaNormal = time(scene pass with normal) - time(without normal)  [Measured]
deltaVelocity = analogous velocity attachment delta               [Measured]
deltaSecondScene = time(second lit pass)                           [Measured]
route valid iff deltaAO <= declaredMarginalAOBudget                [Gated]

Do not add the shared scene pass twice in a composed budget. Charge only its measured attachment delta to AO when another selected system already owns that pass; charge the entire first pass when AO created it.

For the stock half-float PassNode MRT, each extra full-resolution normal or velocity attachment is 8 * width * height bytes [Derived] before MSAA, backend padding, and tile scratch. The built-in scalar GTAO target is approximately scale^2 * width * height bytes for R8 [Derived]. On a tile GPU, an extra MRT attachment can reduce tile residency or force stores; this is a measured architecture decision, not a desktop assumption.

Do not seed the search with adapter-class millisecond tables. They hide scene complexity, DPR, attachment traffic, browser state, and thermal drift. Start from the cheapest representation that can meet the declared contact-radius and edge-error gates, then measure deltaAO, deltaNormal, deltaVelocity, and any deltaSecondScene separately on each named target. The product's marginal AO budget is [Gated]; only matched, warmed A/B traces are [Measured].

Visual wrongness signatures

Ownership boundary

This skill owns scalar GTAO, reconstruction choice, ambient-light placement, temporal eligibility, optional bent normals, and AO diagnostics. The image- pipeline owner controls shared MRTs, global pass order, history, tone mapping, output conversion, and adaptive resolution.