Builtin Library
README.md
ambientOcclusion
The render pass behind the AmbientOcclusion component and the ao module. It
stands in the lighting post stage and runs at afterDepthPrepass, where this
frame's opaque depth is complete and nothing has shaded yet:
- An estimator writes, per texel of a grid at the quality level's
scaleof the frame, the occlusion of the hemisphere above the surface and its bent normal (the mean open direction):ao_pass, the screen-space horizon integral over a visibility bitmask, orao_trace, rays traced against the scene acceleration structure whiletracedis set and the scene's ray tracing is on. ao_temporalcarries the estimate across the renders of each view, reprojecting the view's previous accumulation through its previous view-projection and taking it only where the depth says the surface is the same one. The accumulation is a history target (history = true), so the viewport, every render-to-texture camera and every capture read and write their own, and its state says when a view's previous image is there to read.ao_filterlifts the grid to the frame's resolution, weighing each tap by depth, and writes the scene's occlusion channel (@scene.ao): occlusion in r, the bent normal laid flat on the octahedron in g and b, and in a whether a bent normal was written.- With the
aomodule'sindirecton, the estimate isao_pass_indirect: the same walk (ao_walk), which also gathers, over each run of sectors a tap closes first, the light that occluder sent toward the camera in the view's previous render (@scene.colorHistory), where that render drew the same surface there and its face turns toward the surface.ao_light_temporalcarries the gathered light across the view's renders like step 2, andao_light_filterlifts it into the scene's indirect channel (@scene.indirect): the light in rgb and the share of the closed hemisphere it answers for in a. A traced estimate runs that walk beside it for the light. The light passes stay out of a reflection probe's cube faces, which continue no render of their own.
Every lit material reads the channel at its own pixel the same frame, on its
indirect light alone: FragmentData.ambient_visibility carries the open share,
and PBR shading (zero_pbr_shade) takes it on the diffuse lobe with the light
the surface's colour bounces back into a crease, and on the reflection lobe as
the share of that lobe the open cone around the bent normal holds
(zero_scene_bent_normal, zero_pbr_indirect_visibility). The gathered
light reaches the diffuse lobe in place of the surroundings' light the
occlusion took from the closed part (zero_scene_indirect_here), and the
crease-return estimate stands only for the share the gather did not answer.
Direct light, emissive surfaces and transparents keep the light they carry.
Both estimators reconstruct the surface normal from this frame's depth. Depth and camera come from the render target being drawn, so the pass is correct in offscreen captures and render-to-texture cameras at their own resolutions. Sky pixels have no surface to occlude and write none.
The ambientOcclusion capture view is drawn into a target the pass makes when
a capture of the view asks for it and releases once captures stop asking; its
passes run on that capture's channel alone.
Settings arrive through the ao_params buffer, packed by the ao module, which
also reports what the pass built through ao.stats().