# 3D

Live UI on panels in space, a real lens and light, from the @intentface-launch/three add-on.

`pnpm launch add three`, then `import { … } from "@intentface-launch/three"`.
Use 3D for transitions and moments of awe; go flat when the viewer has to read.

## Stage and camera

| Tool | What it does |
| --- | --- |
| `Stage3D` | A 3D stage rendered like a film camera: real depth of field, shutter motion blur and anti-aliasing, summed in 32-bit float. Each sample is smoothed by its depth before it is summed (`smoothBokeh`, on by default), so bokeh is a smooth disc, not separate copies. |
| `rig` | A camera move from keyframed framings: target, distance, elevation, azimuth, fov, blur. |
| `pushIn`, `pullBack`, `orbitMove`, `turntable`, `macroSlide`, `topDown`, `dollyThrough` | Named camera moves, two keys each. |
| `sequence` | Chains lens functions, each taking over at its frame. |
| `handheld` | Seeded operator sway on any lens. |
| `follow` | A lagging look-at. |
| `fillDistance` | The camera distance at which something fills the frame. |
| `samplesForBlur` | The samples a `Stage3D` needs for blur of a given size in pixels; `samples` also takes a function of the frame, to spend them only while the blur is there. |
| `apertureFor`, `cocPx` | The aperture for a blur size, and the blur size for an aperture. |
| `project`, `pixelsPerUnit`, `orbit` | Lens maths: where a world point lands on screen, and how large. |

## UI in space

| Tool | What it does |
| --- | --- |
| `Panel` | Live DOM on a slab, posed per frame. `region` shows one part, so a snapshot splits into layers. |
| `centerOf` | Places a region panel where it sits in the UI. |
| `stack`, `fan`, `grid`, `exploded` | Layouts that give the pose of panel `i` of `n`. |
| `mixPose`, `offsetPose` | Poses between two layouts, and relative to another. |
| `Phone`, `Tablet`, `Laptop` | Generic devices whose screens show their children live. |
| `Overlay3D` | DOM pinned to a point in the scene: sharp labels that follow a panel. |
| `surfaces` | Slab materials: `frosted`, `glass`, `aluminium`, `anodised`, `matte`, `plastic`, `gloss`. |
| `Floor` | An invisible ground plane that shows only reflections and soft shadows. |

## Light

| Tool | What it does |
| --- | --- |
| `Beam` | A soft or crisp ribbon of light, optionally split into a spectrum. |
| `Ring` | A ring of light: an echo on a surface, a rim. |
| `Wave` | A soft wave of light spreading over a surface. |
| `Glow` | A soft point of light. |
| `Cone` | A cone of light through haze: a spotlight's beam. |
| `Prism` | A glass prism that splits a beam into a spectrum by real refraction. |
| `Smear` | A rainbow where a spectrum lands on a surface. |
| `Light` | The lights above as components, for scenes with a few of them. |
| `useStageItem` | Puts your own three.js objects on the stage, posed per sample. |
| `spectrumBands`, `glasses`, `refractiveIndex`, `wavelengthToLinear` | Spectral colour and glass maths for your own light. |

## Lighting and finish

| Tool | What it does |
| --- | --- |
| `threePoint`, `keyLight`, `rimLight` | Soft boxes around a target. |
| `sweep` | A strip light that runs over glossy faces and edges. |
| `environment` (prop) | Reflections from a preset or an `.hdr`/`.exr`, animatable. |
| `post` (prop) | Bloom, vignette, aberration, a grade and a LUT, and `effects` from postprocessing. Off by default. |
| `grades` | Grade presets: `neutral`, `warm`, `cool`, `premium`. |
| `htmlInCanvas` | Whether the browser can draw DOM into WebGL (needed for panel textures). |

## Post effects

pmndrs' [postprocessing](https://github.com/pmndrs/postprocessing) (bloom, glitch, noise, chromatic aberration, pixelation and the rest) on the video's clock: every pass renders at the frame's time and each effect draws from a random stream seeded by the frame, so any frame renders alone, in any order, the same every time.

| Tool | What it does |
| --- | --- |
| `usePostEffect` | Builds a postprocessing effect once per mount, seeded, and disposes it with the shot. Set its values in the render from the frame. |
| `PostFX` | Applies effects to any DOM (a snapshot, type, a whole shot), drawn in through HTML-in-Canvas. With no effects it matches the DOM. |
| `post.effects` (prop) | Applies effects to a `Stage3D`'s averaged samples, before its own finishing. |
| `EffectChain` | The pass runner both use, for a texture of your own. |
| `Crt` | Any DOM (a terminal, a code editor) on a subtle CRT with a soft glow: a slight bulge, colour fringing, scanlines on lit pixels only, a slow roll bar, flicker and a vignette; no grain by default, since it compresses badly. Every option can change per frame. |
| `CrtEffect` | The same CRT pass as an effect, for `PostFX` or `post.effects`. |

Effects that need depth (depth of field, SSAO, god rays, selective bloom, SMAA) are refused: the stage's lens and samples already do that. `GlitchEffect`'s sporadic mode keeps its own clock: switch `mode` by frame instead.