effect-motion
Guides

Depth of field

Give the camera a lens — a sharp focus plane, and blur that grows with depth

The default camera is a pinhole: everything is sharp at every depth. Give it an aperture and it becomes a lens. One plane in front of it stays sharp, and everything nearer or farther blurs, more the farther it sits from that plane. Both settings are ordinary numeric camera fields, so the animators you already use drive them, and a rack focus is just a tween.

The two fields

  • focusDistance: how far in front of the lens the sharp plane sits, measured along the view. It defaults to the camera's resting distance, so for an untouched camera the z: 0 plane is in focus.
  • aperture: the lens radius, in world units. 0 (the default) is a pinhole, and the renderer skips depth of field entirely. Bigger values give a shallower depth of field: less of the scene stays sharp.

Set them like any other field:

const camera = yield* Scene.camera;
yield* Scene.update(camera, (props) => ({ ...props, aperture: 40 }));

How much blur

The blur follows the thin-lens model. A point at view distance d blurs to a disc of radius

aperture · |d − focusDistance| / d

in world units on the focus plane. At the camera's resting distance one world unit on the focus plane is one pixel, so for a resting camera this is the blur radius in pixels.

As an example, take a 1920-wide scene. Its camera rests about 2667 units back, so the focus plane is at z: 0. With aperture: 40, a shape at z: -1000 sits at d ≈ 3667 and blurs by about 40 · 1000 / 3667 ≈ 11 px. A shape 1000 units in front of the plane (d ≈ 1667) blurs by about 24 px: blur grows faster in front of the focus plane than behind it, just like a real lens. In the browser the blur radius is capped at 30 px of scene size (at most 48 rendered pixels, so above a pixel ratio of 1.6 the cap is a little lower). Video export caps it at 30 rendered pixels.

Blur is worked out per pixel from depth, not per shape. A plane tilted away from the camera is sharp along one band and softens smoothly on either side, with no steps. See the tilted plane example.

Focusing on something

focusDistance is a distance from the lens, not a z coordinate. For a camera that isn't rotated, focusing on a layer at depth z means focusDistance = camera.z - z:

const { position } = yield* Scene.data(camera);
const focusOn = (z: number) => ({ focusDistance: position.z - z });

For a camera aimed with Camera.lookAt, the distance to the point of interest is the one that keeps the subject sharp. Camera.orbitTo keeps that distance the same, so the focus holds while the camera orbits. Camera.dollyTo changes it, so pull focus along with the dolly, using the same duration and easing:

yield* Scene.all([
	Camera.dollyTo(camera, 1900, "2 seconds", "easeInOutCubic"),
	Motion.tweenTo(camera, { focusDistance: 1900 }, "2 seconds", "easeInOutCubic"),
]);

Rack focus

A rack focus moves the sharp plane from one subject to another while the camera holds still. That's a focusDistance tween:

yield* camera.pipe(
	Motion.tweenTo(focusOn(FRONT), "1200 millis", "easeInOutCubic"),
	Motion.wait("700 millis"),
	Motion.tweenTo(focusOn(BACK), "1200 millis", "easeInOutCubic"),
);
0:00
import * as Color from "effect-motion/Color";import * as Entity from "effect-motion/Entity";import * as Motion from "effect-motion/Motion";import * as Scene from "effect-motion/Scene";// A rack focus is a tween. Three layers of flat shapes sit at three depths;// the camera never moves — only `focusDistance` travels, and the sharp plane// slides from the foreground to the back and home again.// flat colour (shapes draw no outline unless a strokeColor is set)const flat = (hex: string) => ({ fillColor: Color.hex(hex) });const FRONT = 1500;const MID = 0;const BACK = -2600;export const scene = Scene.make(	"rack focus",	function* () {		// back: a wall of tall slabs, far behind everything		const slabs = ["#2d6a4f", "#40916c", "#52b788", "#74c69d", "#40916c"];		for (const [i, hex] of slabs.entries()) {			yield* Scene.instantiate("Rect", {				position: Entity.vec3({ x: (i - 2) * 900, y: 250, z: BACK }),				width: 560,				height: 2400,				...flat(hex),			});		}		// mid: the subject, on the resting focus plane		yield* Scene.instantiate("Rect", {			position: Entity.vec3({ x: -160, y: -20, z: MID }),			width: 620,			height: 380,			...flat("#ffd166"),		});		yield* Scene.instantiate("Circle", {			position: Entity.vec3({ x: 250, y: 90, z: MID + 60 }),			radius: 150,			...flat("#ef476f"),		});		// front: big shapes crowding the lens, half out of frame		yield* Scene.instantiate("Circle", {			position: Entity.vec3({ x: -330, y: -200, z: FRONT }),			radius: 120,			...flat("#118ab2"),		});		yield* Scene.instantiate("Rect", {			position: Entity.vec3({ x: 330, y: 90, z: FRONT }),			width: 110,			height: 520,			...flat("#073b4c"),		});		// a HUD caption: pinned to the screen and exempt from the blur		const caption = yield* Scene.instantiate("Text", {			position: Entity.vec3({ y: 440 }),			text: "rack focus",			fontSize: 56,			fillColor: Color.hex("#073b4c"),			textAnchor: "middle",			baseline: "middle",		});		yield* Scene.instantiate("Hud", { children: [caption] });		// focusDistance is a VIEW distance, so each layer's is the camera's		// resting z minus the layer's z		const camera = yield* Scene.camera;		const { position } = yield* Scene.data(camera);		const focusOn = (z: number) => ({ focusDistance: position.z - z });		// open the lens, hold on the subject, then pull focus layer to layer		yield* Scene.update(camera, (props) => ({ ...props, aperture: 45 }));		yield* Motion.wait("700 millis");		for (const z of [FRONT, BACK, MID]) {			yield* camera.pipe(				Motion.tweenTo(focusOn(z), "1200 millis", "easeInOutCubic"),				Motion.wait("900 millis"),			);		}		yield* Motion.wait("600 millis");	},	{		compositing: "depth",		width: 1920,		height: 1080,		backgroundColor: Color.hex("#f4ecd8"),	},);

The HUD stays sharp

Hud content is drawn after, and on top of, the depth-of-field pass. Titles and labels on the HUD stay crisp whatever the camera's aperture.

Limits

  • Opaque shapes only. Blur comes from the depth buffer, which holds one depth per pixel. A semi-transparent shape blurs at its own depth, not at the depth of whatever shows through it, so a fade on the focus plane stays sharp but the content seen through it takes the fading shape's blur.
  • Precomps render sharp inside. A scene mounted with Scene.play ignores its own camera's aperture; its plane blurs as one layer by the parent camera's lens, at the plane's depth.
  • Perspective cameras only.
  • Cost. With aperture > 0 the scene is drawn twice per frame and every pixel gathers dozens of blur samples. The sampling cost grows with the pixel count; the second draw adds a draw call per shape. The tilted plane, with a few hundred shapes, holds 60 fps in the browser. At aperture: 0 there is no extra cost.
  • Real time vs export. The browser renderer (and so the Player) takes half the blur samples by default, which halves the blur's GPU cost; the blur shape is the same, with a little more fine grain. Video export always uses full quality. For full quality in the browser, for example when recording the canvas, pass dofQuality: "full" to Renderer.make.

For a camera orbiting a sharp subject through a field of blurred shapes, see focus orbit.

On this page