Ambient occlusion (SSAO)

Corners get darker. Where a wall meets the floor, where crates are stacked, under a ledge: real light does not reach in there, and a renderer without ambient occlusion lights those creases exactly like the open ground beside them. That is most of why a scene of plain boxes looks pasted together. One attribute on <tosi-b3d> fixes it: ssao="auto".

Demo

import { b3d, b3dSun, b3dSkybox, b3dLight, b3dBox, b3dSphere, b3dGround, b3dProp, assetUrl, select3d, slider3d } from 'tosijs-3d'
import { tosi } from 'tosijs'

const { ssaoDemo } = tosi({ ssaoDemo: { mode: 'on', method: 'projected', strength: 1, radius: 2 } })

// A bust in faux alabaster: pale and semi-gloss, so occlusion is easy to see.
const bust = b3dProp({
  libraryUrl: assetUrl('tosijs-3d/ariosto-bust.glb'),
  meshName: 'Ariosto',
  scale: 0.8,
  x: 0.6, y: 1.4, z: -2.6, ry: 100,
})
function alabaster(babylon) {
  const mesh = bust.mesh ? bust.mesh.getChildMeshes()[0] : null
  if (mesh == null) return setTimeout(alabaster, 250, babylon)
  const material = new babylon.PBRMaterial('alabaster', mesh.getScene())
  material.albedoColor = new babylon.Color3(0.93, 0.9, 0.84)
  material.metallic = 0
  material.roughness = 0.4
  material.bumpTexture = mesh.material.bumpTexture
  mesh.material = material
}

const stone = '#b9b2a4'
const crate = '#a0764a'
preview.append(
  b3d(
    {
      ssao: ssaoDemo.mode,
      ssaoMethod: ssaoDemo.method,
      ssaoStrength: ssaoDemo.strength,
      ssaoRadius: ssaoDemo.radius,
      scenePanel: () => [
        select3d({ label: 'ssao', value: ssaoDemo.mode, options: ['off', 'auto', 'on'] }),
        select3d({ label: 'method', value: ssaoDemo.method, options: ['projected', 'screen'] }),
        slider3d({ label: 'strength', value: ssaoDemo.strength, min: 0, max: 3, step: 0.05 }),
        slider3d({ label: 'radius (m)', value: ssaoDemo.radius, min: 0.25, max: 6, step: 0.05 }),
      ],
      sceneCreated(el, BABYLON) {
        alabaster(BABYLON)
        const cam = el.scene.activeCamera
        // Target first: an orbit camera re-derives its position from the target.
        if (cam && cam.setTarget) cam.setTarget(new BABYLON.Vector3(-0.5, 1, 0.5))
        if (cam && cam.setPosition) cam.setPosition(new BABYLON.Vector3(6, 5, -10))
      },
    },
    b3dLight({ intensity: 0.9 }),
    b3dSun({ shadowTextureSize: 2048 }),
    b3dSkybox({ timeOfDay: 15 }),
    b3dGround({ size: 40, color: '#8f9a7a' }),
    // A corner of two walls, a doorway with a lintel, steps, stacked crates.
    b3dBox({ meshName: 'wall-a', width: 8, height: 3, depth: 0.5, x: 0, y: 1.5, z: 3, color: stone }),
    b3dBox({ meshName: 'wall-b', width: 0.5, height: 3, depth: 6, x: -4.25, y: 1.5, z: 0.25, color: stone }),
    b3dBox({ meshName: 'post-l', width: 0.5, height: 2.4, depth: 0.5, x: 2, y: 1.2, z: -1, color: stone }),
    b3dBox({ meshName: 'post-r', width: 0.5, height: 2.4, depth: 0.5, x: 4, y: 1.2, z: -1, color: stone }),
    b3dBox({ meshName: 'lintel', width: 3, height: 0.5, depth: 0.7, x: 3, y: 2.65, z: -1, color: stone }),
    b3dBox({ meshName: 'step-1', width: 3, height: 0.25, depth: 1.5, x: -1.5, y: 0.125, z: 1.5, color: stone }),
    b3dBox({ meshName: 'step-2', width: 3, height: 0.5, depth: 1, x: -1.5, y: 0.25, z: 2.1, color: stone }),
    b3dBox({ meshName: 'crate-1', size: 1, x: -3.2, y: 0.5, z: -0.5, color: crate }),
    b3dBox({ meshName: 'crate-2', size: 1, x: -2.1, y: 0.5, z: -0.3, ry: 12, color: crate }),
    b3dBox({ meshName: 'crate-3', size: 1, x: -2.7, y: 1.5, z: -0.4, ry: -8, color: crate }),
    b3dSphere({ meshName: 'ball', diameter: 1.2, x: 1, y: 0.6, z: 1.6, color: '#c8553d' }),
    b3dBox({ meshName: 'plinth', width: 0.6, height: 1, depth: 0.6, x: 0.6, y: 0.5, z: -2.6, color: stone }),
    bust
  )
)

Open the settings panel (the owl) and switch ssao between off and on. Watch the foot of the walls, the gaps between the crates and the underside of the lintel, then orbit in on the bust: a beard, a laurel and a collar are the kind of creased, organic shape occlusion does most for. It works in VR too, with the default projected method; screen is Babylon's own and switches itself off in a headset. See "Two methods" below.

Two methods

ssaoMethod chooses how the occlusion is worked out. The default is projected.

ssaoMethod Where it runs
projected (default) flat and in a headset ours: see below
screen flat only Babylon's SSAO2RenderingPipeline, a post-process

And ssao chooses whether it runs at all:

ssao
off (default) off
auto on if the device tier affords it (top tier only), and never in a headset
on on, including in a headset when the method is projected

Projected

Occlusion is computed once, from a camera between the eyes, into a texture. Every lit material then looks its own pixel up in that texture by world position, the way cloud shadows and caustics do.

What it costs is one extra pass over the opaque scene per redraw (depth only: the materials skip their lighting), two small full-screen passes, and two texture reads per lit pixel. On a Quest, in this demo, frame rate and CPU time were the same with it on as off. That is a small scene. It has not been measured on a heavy one, which is why auto stays off in a headset.

It concentrates its darkening in contacts and corners, where screen spreads it more thinly. It is softer than screen on fine surface detail, because it works from depth alone at reduced resolution and screen also reads each material's normal map. A surface the middle camera could not see gets no occlusion until the next redraw.

Screen, and why it is flat only

ssaoMethod="screen" is Babylon's pipeline: it draws the opaque scene a second time into a depth-and-normals buffer, samples that for every pixel, blurs the result and composites it over the frame.

It never runs in a headset. A post-process chain on a WebXR camera does not render per eye: it draws ONE image across both, on a Quest and in an emulated headset alike, whether the chain is carried into the session or built inside it. With this method occlusion is switched off before a session starts and back on when it ends.

ssao="always" is a deprecated alias of on: it is accepted and warns once.

Sample count and resolution come from the device budget (PerfBudgets.ssaoSamples, ssaoRatio), so you tune the LOOK and the tier tunes the COST.

Attributes (on <tosi-b3d>)

Attribute Default Description
ssao 'off' off, auto or on: see the tables above. LIVE
ssaoStrength 1 How dark a fully occluded crease gets. 0 is none. LIVE
ssaoRadius 2 How far, in metres, a surface looks for something occluding it. Small radii darken only tight creases; large ones shade whole alcoves. LIVE
ssaoMethod 'projected' projected (flat and headset) or screen (Babylon's post-process, flat only). LIVE
ssaoRate 30 Projected only: redraws per second. 0 is every frame. LIVE

What is and is not occluded

Transparent meshes are left out of the depth-and-normals pass, so glass, water seen through its alpha, particles and the cloud deck neither receive nor cast occlusion. With screen, a mesh whose vertex shader moves its vertices (the vertex-animated crowd) is occluded as if standing in its rest pose; projected occludes it in the pose you see.