threejs-ambient-contact-shading

Ambient Contact Shading

AO is visibility of indirect illumination. It may attenuate indirect diffuse and environment/specular response. Do not multiply direct light, emission, UI, or an already tone-mapped frame by AO. The final image changes through indirect lighting; test direct/emissive invariance in separate scene-linear terms at fixed exposure, not by requiring unchanged final RGB.

$threejs-choose-skills is an optional multi-system coordinator. Use $threejs-image-pipeline when AO shares depth, normals, velocity, history, or final-output ownership.

1. Choose the ambient-visibility branch

Use the first branch whose gate passes:

Gate	Branch	Consequence
Required occlusion is static/local and can be authored in assets	material aoMap / aoNode	One forward render; no dynamic inter-object contact.
Dynamic screen contact is required and the renderer exposes indirect lighting separately	apply GTAO visibility to that term	One geometry pass can remain possible.
Stock forward NodeMaterial needs dynamic contact and the complete marginal cost passes	depth/normal pass -> GTAO -> optional reconstruction -> second lit pass with builtinAOContext()	Correct placement costs two scene traversals.
No previous branch meets its quality and cost gates	omit screen AO	Preserve materials, direct shadows, and silhouette readability.

r185 GTAONode needs current depth/normal before AO exists, while builtinAOContext() must be present during material lighting. Treat the first pass as a full material/deformation/alpha-tested scene pass unless a parity- proven depth/normal-only pass replaces it.

Complete when: the chosen branch names the indirect-light owner and either charges every added pass/attachment or records screen AO as omitted.

2. Fix the input contract

• Initialize the renderer and require a WebGPU backend before graph creation. The default r185 graph requires perspective, non-logarithmic standard depth. Orthographic, logarithmic, reversed-depth, and subviewport adapters must prove every depth/normal reconstruction, view direction, sky, and ordering rule.
• Define opaque occluders, opaque receivers, alpha coverage, and one transparent policy: no screen AO, authored material AO, or a validated custom lighting model. Stock builtinAOContext() skips transparent materials.
• Bind AO to the active view's screenUV, drawing-buffer dimensions, and projection. Use a separate stateful node per independent view. Keep width and height independent, admit positive rounded target dimensions, and suspend zero-sized views rather than publishing invalid AO.
• Choose depth-reconstructed normals for reduced raw AO only when edge fixtures and target timing pass. Choose an MRT normal when it is shared, reconstruction is materialized, smooth/thin geometry fails, or its measured attachment delta is cheaper.
• Express physical contact radii in world units: radiusRender = radiusMeters * renderUnitsPerMeter, with the same conversion for dimensioned thickness and bias. An authored-look branch instead declares scene-unit-only controls and revalidates them after asset/world scaling.

When another system supplies scale, motion, or resources, bind units, coordinate frame, current/previous presentation times, authority, version, resource generation, validity, and reset conditions before using those inputs.

Complete when: depth convention, screen coordinates, normal source, transparency, scale meaning, and every external producer are explicit and dimensionally compatible.

3. Materialize scalar visibility

Build the selected screen-space branch in this order:

shared-or-AO-owned depth + optional normal/velocity
  -> GTAO scalar visibility
  -> optional materialized edge-aware reconstruction
  -> indirect-light application
  -> optional temporal resolve over the matching admitted layers
  -> excluded-layer composition only when those layers were separated
  -> one tone-map/output-transform owner

• Reuse a shared scene pass; do not create a second G-buffer for AO.
• Raw reduced-resolution AO receives ordinary texture filtering, not bilateral reconstruction. When edges fail, use a validated, materialized reconstruction once, then sample it with screenUV. The installed denoiser needs the index/rotation correction in the reference; stock construction alone is not admission. Raw/full-resolution AO or omission remain alternatives.
• Inside a mesh material graph, sample both raw and reconstructed visibility explicitly with screenUV; implicit texture coordinates resolve to mesh UVs.
• Keep stock transparent/transmission rendering in the non-temporal lit pass; builtinAOContext() already skips transparent materials. Use an opaque-only lit pass plus separate layer composition only for a temporal resolve or an already-owned external compositor. Account for its full cost; charge AO only the marginal delta when that compositor is shared.
• Keep scalar visibility single-channel. Replace the output graph and mark the RenderPipeline dirty when AO is disabled so inactive work is unreachable. Retain all owned noise, reconstruction-target, and material handles; base node disposal is not recursive and stock AO disposal leaves its noise alive.

When implementing GTAO or choosing reconstruction, read the r185 GTAO pipeline and its reconstruction tradeoff.

Complete when: the active graph has one depth/normal owner, visibility is sampled in screen space, AO reaches only indirect lighting, and AO-off removes every AO pass and dependency.

4. Admit temporal filtering only with valid history

GTAONode.useTemporalFiltering rotates samples; it does not create or reproject history. Enable it only with a live TRAA/custom resolve, valid camera and object motion (including deformation/instancing/alpha coverage), matching beauty/depth/ velocity dimensions and layer membership, rejection, and reset behavior. Resolve only layers represented by those depth and velocity signals. Composite excluded transparent or refractive layers afterward; admit them to the resolve only when their matching depth, motion, coverage, and rejection behavior are proven.

Reset or reseed on camera/projection cuts, uncompensated rebases, geometry or coverage discontinuities, AO parameter/scale/resolution changes, and quality migration. r185 TRAANode has no public camera-cut reset: rebuild and dispose the node, replace the output graph, and mark the pipeline dirty.

When temporal AO is selected, read the temporal contract before constructing history.

Complete when: beauty, depth, and velocity cover the same admitted layers; any excluded transparent/refractive layers are composed after the resolve; and moving-occluder, disocclusion, camera-cut, resize, and AO-parameter-change fixtures either pass with explicit rejection/reset or temporal AO is disabled.

5. Add bent normals only after scalar AO passes

A bent normal is the visibility-weighted mean unoccluded direction. Add this branch only when scalar AO already passes, directional environment response is visible and required, and the one-wall fixture proves the direction points away from the blocked hemisphere.

When bent normals are selected, read the bent-normal contract for basis, filtering, normalization, storage, and sign checks.

Complete when: scalar visibility remains independently available, the direction is transformed exactly once, and the one-wall fixture passes; otherwise directional use stays disabled.

6. Verify the finished graph

For an active screen-space branch, capture raw depth, the selected normal input, raw/reconstructed AO when admitted, indirect contribution, direct/emissive residuals, velocity/history rejection when temporal filtering is present, and AO off. Exercise UV-invariance, thin silhouettes, transparent crossings, smooth curves, screen edges, asymmetric projections, motion when present, resize, and disposal/recreation.

For authored material AO, validate the authored UV set, asset/world scaling, and indirect-only placement instead. For omitted screen AO, record that no screen-AO pass, attachment, history, or dependency is reachable.

Complete when: direct light and emission are invariant; every fixture for the selected branch passes; an active screen-space branch has no unintended UV-following, cross-edge halo, crawl, or trail; AO-off or omission shows zero screen-AO work; target-device marginal time and resource use pass; and recreation returns resource counters to baseline.

Ownership

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