# Three.js & TSL Reference (`ultra-text` and `ultra-text/slug`) Target runtime: ESM with `three` (`>=0.187.0 <0.188.0`), `WebGPURenderer` from `three/webgpu`, and nodes from `three/tsl`. ## Core options (`DomTextOptions` / `DomSdfOptions`) | Option | Default | Notes | | ---------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `textBackend` | `'sdf'` | `'sdf'` (atlas), `'slug'` (dual-ray curves), or `'windfoil'` (row-band curves). | | `atlasMode` | `'auto'` | SDF only: `'auto'` (GPU JFA with CPU fallback), `'gpu'`, or `'cpu'`. | | `quality` | `'standard'` | SDF only: `'standard'` (1 tap, smallest) or `'high'` (4-tap sampling + mipmaps + up to 4× anisotropy). | | `bakeSize / padding` | `96 / 12` | SDF texel size and field range (`maxAtlasSize` defaults to `2048`; enable `adaptiveBakeSize` near overflow). | | `layoutEngine` | `'range'` | Browser `Range` fidelity, or lazy `'pretext'` Canvas layout. | | `tone` | on | Matches browser ink weight; pass `{ backdrop: '#0b0b0d' }` when light text sits over a dark 3D scene, or `false` for exact coverage. | | `extraGlyphs` | `—` | Pre-bake dynamic digits/symbols/emoji sequences so live edits repack instances without rebuilding the atlas. | | `outline / dropShadow` | `—` | Local-unit outline (`width`, `color`, `opacity`) and hard shadow (`offsetX`, `offsetY`, `color`, `opacity`). Supported on all backends (uses an SDF underlay under Windfoil/Slug). | | `motion` | `'slide-up'` | `{ enabled, mode, strength, speed, stagger }`. `mode: 'none'` omits the motion shader graph until upgraded via `setMotion()`. | | `fill / vertex` | `—` | Build-time TSL callbacks (`TextFill`, `TextVertex`) evaluated only while constructing materials. | | `observe / reflowable` | `true / false` | Automatic DOM/Resize observation; `reflowable: true` retains metrics for width-only `reflow(width)` without reading the DOM. | | `pixelsPerUnit` | `1` | Scales captured X/Y coordinates (`textDepth: 1`, `rectDepth: 0`, `panelDepth: -1` are unscaled). | | `pixelSnap` | `false` | Snaps lines/glyph origins to browser pixel grids for crisp flat 1:1 overlays. | | `castShadow / side` | `true / FrontSide` | Set `castShadow: false` to skip shadow-map draws; `DoubleSide` for two-sided text. | | `signal / onError` | `—` | Abort builds cleanly; handle errors from observer-triggered async rebuilds. | ## TSL custom `fill` and `vertex` hooks ```ts import { mix, sin, time, vec3, vec4 } from 'three/tsl' import { DomText } from 'ultra-text' const copy = await DomText.create(renderer, source, { padding: 24, outline: { width: 1.2, color: '#cafae2', opacity: 0.8 }, dropShadow: { offsetX: 5, offsetY: -6, color: '#030c09', opacity: 1 }, fill: ({ position }) => { const wave = sin(position.x.mul(0.02).add(time)).mul(0.5).add(0.5) return vec4(mix(vec3(0.1, 0.8, 0.5), vec3(1, 0.25, 0.08), wave), 1) }, vertex: ({ position, center, sequence }) => { const bob = sin(time.mul(2).add(sequence.mul(0.35))).mul(2) return position.add(vec3(0, bob, sin(center.x.mul(0.015).add(time)).mul(4))) }, }) ``` - `fill` receives `{ uv, position, color, colorWeight, glyphIndex }` and returns linear RGBA `Node<'vec4'>`; coverage, `tone`, DOM opacity, and scene shadows still apply. - `vertex` receives `{ position, center, uv, glyphIndex, sequence, rect, clip }` after built-in motion and returns displaced local `Node<'vec3'>` (runs on both beauty and shadow passes; block `clip` is computed beforehand so Z waves do not clip). ## Analytic Slug & Windfoil outlines - **Pure Slug bundle (`ultra-text/slug`)**: exports `DomSlug` (aliased `DomText`), `SlugText` (aliased `Text`), `SlugMaterial`, `createTrueTypeOutlineProvider`, `parseTrueTypeFont`, `createTracedOutlineProvider`, `createSvgEmojiOutlineProvider`, and omits all SDF rasterizer/JFA/worker code. - **No `.ttf` file needed by default**: if `outlineProvider` is omitted, `DomSlug` / `textBackend: 'slug'` / `'windfoil'` traces the browser's rendered glyphs on Canvas 2D (`traceSize: 256`, `traceTolerance: 0.25`). Colour glyphs use an SDF companion on `ultra-text` (`fallback: 'sdf-glyphs'`) or `missingGlyphs: 'skip' | 'error'` on `ultra-text/slug`. - **Exact TTF curves**: when bundling an uncompressed `.ttf` font, parse it once and reuse the provider: ```ts import { DomSlug, createTrueTypeOutlineProvider } from 'ultra-text/slug' const ttfBytes = await fetch('/fonts/inter.ttf').then((r) => r.arrayBuffer()) const outlineProvider = createTrueTypeOutlineProvider(ttfBytes) const copy = await DomSlug.create(renderer, source, { outlineProvider }) ``` - Note on Windfoil: `textBackend: 'windfoil'` adapts upstream Windfoil (Apache-2.0); upstream notes patent considerations to evaluate for commercial use. ## SVG capture, standalone shapes, and vector emoji - `svg: true` (or `{ render: 'bitmap', images: true, unsupported: 'error', maxPathData }`) captures inline `` elements using Range layout; shapes count in `stats.shapes`. - For scene-authored shapes, import `svgToWindfoilOutlines`, `windfoilOutlineFromSvgPaths`, and `createWindfoilShapes` from `ultra-text`. - For vector emoji on analytic backends, wrap your font provider with `createSvgEmojiOutlineProvider({ text, resolve, em })` and supply app-owned SVG artwork. ## Runtime updates & shared atlases - Motion uniforms update without rebuilding shaders or DOM: `copy.setMotion({ mode: 'offset', speed: 0.8 })`. - Width-only re-wrap: create with `{ reflowable: true }`, then call `copy.reflow(widthPx)` (`1.51 ms` median on 1,000 glyphs vs full DOM `rebuild()`). - Force rebuild: `await copy.rebuild()` (re-reads DOM, reuses retained atlas if glyph signature matches) or `await copy.rebuild({ atlas: true })`. - Lower-level SDF stages (`collectDomSnapshot`, `rasterizeGlyphAtlas`, `buildSdfAtlas`, `createGlyphGeometry`, `SdfTextMaterial`, `createRectGeometry`, `createRectMaterial`, `reflowSnapshot`) let multiple meshes share one `SdfAtlas`; pass `sharedAtlas` (matching `quality` and `colorGlyphs` mode) and dispose `sharedAtlas` only after every consumer has been disposed.