Slug Text

The @three-flatland/slug package renders crisp, resolution-independent text on the GPU using the Slug algorithm . Font outlines are rasterized per-pixel from quadratic Bezier curves — no texture atlases, no SDF approximations, no blurry edges at any zoom level.

Experimental

The @three-flatland/slug API isn't settled yet. We're dogfooding it and folding in community feedback to stabilize it, so it can shift between releases. Pin an exact version for now.

Three.js

import { WebGPURenderer } from 'three/webgpu';
import { SlugFontLoader, SlugText } from '@three-flatland/slug';

const font = await SlugFontLoader.load('/fonts/Inter-Regular.ttf');
const text = new SlugText({
  font,
  text: 'Hello, Slug!',
  fontSize: 48,
  color: 0xffffff,
  align: 'center',
});

scene.add(text);

// Per-frame update (required for dilation + dirty rebuild)
function animate() {
  requestAnimationFrame(animate);
  text.update(camera);
  renderer.render(scene, camera);
}

React

import { Canvas, extend, useFrame, useLoader, useThree } from '@react-three/fiber/webgpu';
import { SlugText, SlugFontLoader } from '@three-flatland/slug/react';

extend({ SlugText });

function TextScene() {
  const font = useLoader(SlugFontLoader, '/fonts/Inter-Regular.ttf');
  const ref = useRef<SlugText>(null);
  const { camera, size } = useThree();

  useEffect(() => {
    ref.current?.setViewportSize(size.width, size.height);
  }, [size]);

  useFrame(() => {
    ref.current?.update(camera);
  });

  return (
    <slugText
      ref={ref}
      font={font}
      text="Hello, Slug!"
      fontSize={48}
      color={0xffffff}
      align="center"
    />
  );
}

WebGPU & WebGL2

Slug text works with both the WebGPU renderer and its WebGL2 fallback. The TSL shaders compile to WGSL or GLSL ES 3.0 automatically.

Loading Fonts

SlugFontLoader is the single entry point for loading fonts. It automatically tries pre-baked data first (a single .slug.glb), and falls back to runtime parsing from the .ttf if baked data isn't available.

SlugFontLoader resolution — a baked .slug.glb loads directly and skips opentype.js; a miss falls back to fetching and parsing the .ttf at runtime.

Three.js

import { SlugFontLoader } from '@three-flatland/slug';

const font = await SlugFontLoader.load('/fonts/MyFont.ttf');

React

import { useLoader } from '@react-three/fiber/webgpu';
import { SlugFontLoader } from '@three-flatland/slug/react';

// Inside a component within <Canvas>, with <Suspense> boundary
const font = useLoader(SlugFontLoader, '/fonts/MyFont.ttf');

After loading, the font provides:

• font.glyphs — parsed glyph data (Map<number, SlugGlyphData>)
• font.curveTexture — GPU texture with Bezier control points
• font.bandTexture — GPU texture with spatial acceleration data
• font.unitsPerEm, font.ascender, font.descender, font.capHeight — font metrics
• font.measureText(text, fontSize), font.measureParagraph(text, fontSize, opts), font.wrapText(text, fontSize, maxWidth) — measurement helpers

SlugText Properties

SlugText extends InstancedMesh — each glyph is an instanced quad evaluated per-pixel by the Slug fragment shader.

| Property | Type | Default | Description | | ------------ | ------------------------------- | ----------- | ------------------------------------------------ | | font | SlugFont \| null | null | Font to render with | | text | string | '' | Text content | | fontSize | number | 16 | Font size in scene units | | color | Color \| number | 0xffffff | Text color | | opacity | number | 1.0 | Fill opacity | | align | 'left' \| 'center' \| 'right' | 'left' | Horizontal alignment | | lineHeight | number | 1.2 | Line height multiplier | | maxWidth | number \| undefined | undefined | Max width for word wrapping | | styles | StyleSpan[] | [] | Underline / strike / super-sub spans (see below) | | outline | SlugOutlineOptions \| null | null | Optional stroke outline (see below) |

All properties can be set after construction. Changes are applied on the next update() call.

Per-Frame Updates

SlugText.update(camera) does two things:

1. Rebuilds geometry if any property changed (dirty flag)
2. Updates the MVP matrix for vertex dilation — this must happen every frame since the camera or object may move

Three.js

function animate() {
  requestAnimationFrame(animate);
  text.update(camera);
  renderer.render(scene, camera);
}

React

useFrame(() => {
  ref.current?.update(camera);
});

Viewport Size

For correct edge dilation (half-pixel anti-aliasing at quad boundaries), call setViewportSize when the viewport changes:

Three.js

text.setViewportSize(window.innerWidth, window.innerHeight);

window.addEventListener('resize', () => {
  text.setViewportSize(window.innerWidth, window.innerHeight);
});

React

const { size } = useThree();

useEffect(() => {
  ref.current?.setViewportSize(size.width, size.height);
}, [size]);

Dynamic Text

Change any property and the text rebuilds on the next update():

text.text = 'New content'
text.fontSize = 96
text.align = 'right'
text.color = 0xff0000
// Geometry rebuilds automatically on next update() call

Multi-line & Word Wrap

Set maxWidth to enable automatic word wrapping. Line breaks (\n) are also supported:

const text = new SlugText({
  font,
  text: 'This is a long paragraph that will wrap automatically.',
  fontSize: 24,
  maxWidth: 400,
  lineHeight: 1.4,
})

Measurement

SlugFont exposes a measurement API mirroring CanvasRenderingContext2D.measureText for layouts that don't need GPU geometry — overlays, hit-testing, fitting text inside a box.

const m = font.measureText('Hello, Slug!', 48)
// m.width
// m.actualBoundingBoxLeft / .actualBoundingBoxRight
// m.actualBoundingBoxAscent / .actualBoundingBoxDescent
// m.fontBoundingBoxAscent / .fontBoundingBoxDescent

For wrapped paragraphs:

const para = font.measureParagraph(longText, 24, {
  maxWidth: 400,
  lineHeight: 1.4, // matches SlugText's default — measurements agree with rendering
})
// para.width (widest line), para.height (block height)
// para.lines: [{ text, width }, ...]

font.wrapText(text, fontSize, maxWidth) exposes the same wrap policy SlugText uses internally — useful when you need to compare line breaks against another renderer (Canvas2D, DOM).

Decorations (underline, strikethrough, super/sub)

Apply StyleSpan[] over half-open [start, end) UTF-16 ranges:

const text = new SlugText({
  font,
  text: 'Bold and underlined and ²',
  fontSize: 48,
  styles: [
    { start: 9, end: 21, underline: true }, // "underlined"
    { start: 24, end: 25, scriptLevel: 2 }, // superscript "2"
  ],
})

| Field | Type | Description | | -------------- | --------- | -------------------------------------------------------------------------------------------------- | | start, end | number | Half-open code-unit range. | | underline | boolean | Underline rect at the font's underlinePosition. | | strike | boolean | Strikethrough rect at the font's strikethroughPosition. | | scriptLevel | number | Slug script(n) level. Positive = superscript, negative = sub. Magnitude ∈ [1, 3] is the depth. |

Decoration rects render through the same instance pipeline as glyphs (no second draw call) — they short-circuit the fragment shader to solid coverage via a sentinel bit on the instance attributes.

Multi-font fallback (SlugFontStack / SlugStackText)

Render strings whose codepoints span multiple loaded fonts. The first font in the stack with a non-zero glyphId for a given codepoint wins (per-character, automatic — authors don't tag runs).

Three.js

import { SlugFontLoader, SlugFontStack, SlugStackText } from '@three-flatland/slug';

const [inter, fa] = await Promise.all([
  SlugFontLoader.load('/fonts/Inter-Regular.ttf'),
  SlugFontLoader.load('/fonts/FontAwesome-Regular.ttf'),
]);

const stack = new SlugFontStack([inter, fa]);

const text = new SlugStackText({
  fontStack: stack,
  text: 'Lorem  search',  // last char is an FA icon
  fontSize: 48,
});
scene.add(text);

React

import { extend } from '@react-three/fiber/webgpu';
import { SlugStackText, SlugFontStack } from '@three-flatland/slug/react';

extend({ SlugStackText });

function StackedText({ fonts }: { fonts: SlugFont[] }) {
  const stack = useMemo(() => new SlugFontStack(fonts), [fonts]);
  return <slugStackText fontStack={stack} text="Lorem  search" fontSize={48} />;
}

SlugStackText renders one InstancedMesh per backing font — one extra draw call per fallback font. It has full SlugText parity (styles, outline, setOpacity, dispose).

Color emoji not supported

COLR / CPAL / CBDT (color-glyph tables) are out of scope. Emoji glyphs render as their outline if present, otherwise notdef. A roadmap entry tracks this.

Outline

Add a stroked outline behind the fill:

const text = new SlugText({
  font,
  text: 'Hello, Slug!',
  fontSize: 96,
  color: 0xffffff,
  outline: {
    width: 0.025, // em-space half-width (~5% em total stroke width)
    color: 0x000000,
  },
})

Width and color update at runtime via uniforms — no rebuild:

text.setOutlineWidth(0.05)
text.setOutlineColor(0xff0000)

Outline-only text:

text.setOpacity(0) // hide fill, keep outline visible

The current dynamic shader uses min(distance) over the glyph's curves, producing a clean bevel at exterior corners. Interior corners stay crisp by construction. Miter / round joins, caps, dashing, and a 1× fill cost baked path are landing in Phase 5 (#37); the dynamic shader will stay as outline.mode = 'dynamic' for live width scrubbing.

Material Options

SlugText creates a SlugMaterial internally. Several shader-level options are available at construction time (some compile-time constants, some runtime uniforms):

| Option | Type | Default | Description | | ------------- | --------- | ------- | ---------------------------------------- | | evenOdd | boolean | false | Even-odd fill rule (compile-time). | | weightBoost | boolean | false | sqrt() coverage boost (compile-time). | | stemDarken | number | 0 | Stem darkening strength; ~0.4 is subtle. | | thicken | number | 0 | Coverage thickening at low ppem. | | pixelSnap | boolean | true | Snap glyph positions to pixel grid. | | supersample | boolean | false | 2×2 supersampling (expensive). |

Pre-baking Fonts

For production, use slug-bake to pre-process fonts offline. This eliminates opentype.js at runtime and lets you subset to only the glyphs you need:

# Install (or use npx)
npx slug-bake Inter-Regular.ttf

# Subset to ASCII only — 32 KB with Brotli
npx slug-bake Inter-Regular.ttf --range ascii

# Latin extended
npx slug-bake Inter-Regular.ttf --range latin

# Multiple ranges
npx slug-bake Inter-Regular.ttf -r latin -r 0x2000-0x206F

Place the .slug.glb file alongside the font. SlugFontLoader.load() detects it automatically — no code changes needed. The .ttf is never fetched when baked data is present, and opentype.js never enters the bundle.

| Range | Glyphs | Raw | Brotli | | ------- | ------ | -------- | ------ | | All | 2,849 | 12.78 MB | 724 KB | | latin | 523 | 2.15 MB | 208 KB | | ascii | 95 | 412 KB | 32 KB |

CDN Compression

Rely on your CDN's gzip/brotli — the browser decompresses automatically with zero JS cost. ASCII-only Inter with Brotli is 32 KB for resolution-independent text at any zoom level.

Missing glyphs render as a fallback rectangle. Named ranges: ascii, latin, latin+. Custom ranges use hex (0x20-0x7E) or decimal (32-126).

How It Works

The Slug algorithm renders each pixel by:

1. Casting dual rays (horizontal + vertical) from the pixel center
2. Solving quadratic equations to find Bezier curve intersections
3. Computing winding number from intersection results
4. Producing fractional coverage for anti-aliased edges

Spatial band structures accelerate the per-pixel curve lookup, and vertex dilation expands each glyph quad by half a pixel to ensure boundary fragments are evaluated.