Text

insomni ships two text paths that share one rendering shader and one authoring surface (Layer.pushText and friends). They differ only in how glyphs are rasterized into the atlas:

1. Raster (default) — system fonts via Canvas 2D + a CPU-computed SDF. Zero font bytes, no opentype.js. This is what insomni gives you out of the box.
2. MSDF / TTF (opt-in) — true multi-channel SDF from TTF/OTF outlines, with kerning and cross-platform-consistent shapes. Imported from insomni/text-ttf, which pulls in insomni-msdf-text.

Both produce a GlyphAtlas you attach to a layer; the layer’s text methods shape strings against that atlas.

WebGPU SVG Fullscreen Exit Debug

MSDF text Three lines at different sizes, rendered from a system font with zero font downloads via RasterFont + SdfGlyphAtlas.

Choosing a path

	Raster (default)	MSDF / TTF (insomni/text-ttf)
Import	insomni	insomni/text-ttf (+ insomni-msdf-text)
Font source	Any CSS family the browser resolves	A specific .ttf / .otf you load
Bundle cost	Zero font bytes	opentype.js + MSDF generator
Kerning	No (always 0)	Yes
Extreme-zoom corners	SDF rounds sharp corners	Stays crisp (MSDF)
Best for	UI / dataviz labels at typical sizes	Display typography, brand fonts, exact cross-OS layout

Tip

Most apps need only the raster path. Reach for insomni/text-ttf when you need a specific font file, kerning, or pixel-identical text across platforms.

The shared font/atlas interfaces

Both paths satisfy two interfaces so the shaper and renderer don’t care which kind you use:

• TextFont — family, unitsPerEm, ascender, descender, lineGap, and getKerning(left, right). Metrics are em-relative and normalized.
• GlyphAtlas — owns the GPU atlas texture and lazily rasterizes glyphs on first request. Key members: texture, font, pxRange, atlasFontSize, atlasSize, getGlyph(codepoint), measureText(text, options), preload(text), and version (bumped on each new glyph allocation).

GlyphAtlasOptions configures an atlas: atlasSize (default 2048), atlasFontSize (em size in atlas texels, default 64), pxRange (SDF distance range in texels, default 8), and label.

measureText(text, options) takes MeasureTextOptions (fontSize, optional maxWidth, lineHeight, fontFamily, fontWeight, fontStyle, simple) and returns TextMetrics (width, height). The simple flag mirrors the same flag on the shape so a measured width matches what the layout will produce.

Raster path (default)

Build a RasterFont from a CSS family, then an SdfGlyphAtlas over it:

import { createLayer, loadSystemFont, SdfGlyphAtlas, rgba } from "insomni";

const font = await loadSystemFont("system-ui");
const atlas = new SdfGlyphAtlas(renderer, font, { atlasFontSize: 64 });

const labels = createLayer({ space: "ui", atlas });
labels.pushText({
  text: "Hello, insomni",
  x: 24,
  y: 24,
  fontSize: 16,
  color: rgba(0.1, 0.1, 0.1, 1),
});

renderer.render([labels]);

• RasterFont implements TextFont over a system font. loadSystemFont(family, options?) returns one (resolves immediately — Canvas metrics are synchronous). family is any CSS font-family ("sans-serif", "system-ui", "monospace", …). RasterFontOptions: family (label override), samplePx (metric sampling size, default 64), weight, style. Kerning always returns 0.
• SdfGlyphAtlas is the GlyphAtlas for raster fonts: it renders each glyph onto an OffscreenCanvas, runs a CPU distance transform, and splats the single-channel SDF into all four atlas channels so the MSDF shader works unchanged. Construct with new SdfGlyphAtlas(owner, rasterFont, options?).

MSDF / TTF path (opt-in)

Import the loaders from insomni/text-ttf. This entry point re-exports insomni-msdf-text’s Font / loadFont plus insomni’s MsdfGlyphAtlas adapter, and pulls opentype.js + the MSDF generator into your bundle:

import { createLayer } from "insomni";
import { loadFont, MsdfGlyphAtlas } from "insomni/text-ttf";

const inter = await loadFont("/fonts/inter.ttf");
const atlas = new MsdfGlyphAtlas(renderer, inter);

const labels = createLayer({ space: "ui", atlas });
labels.pushText({ text: "Crisp at any zoom", x: 24, y: 24, fontSize: 18 });

loadFont accepts a URL or an ArrayBuffer (FontSource) and takes FontOptions. The resulting Font is a TextFont with real kerning; MsdfGlyphAtlas is its GlyphAtlas.

Standalone MSDF shaping

For non-layer consumers (custom pipelines, SVG export, measurement), the MSDF shaper is exported from the core barrel under prefixed names:

• shapeMsdfText(text, font, atlas, x, y, options) → an MsdfShapedBlock (glyphs, bbox, height, lineCount, maxLineWidth).
• MsdfShapeOptions — fontSize, align, maxWidth, lineHeight, simple.
• MsdfShapedGlyph — one positioned glyph (glyph, worldX/Y, worldW/H).
• MsdfGlyph — an atlas glyph entry.

The TextPack class (with TextBlockMetrics and the MsdfTextShape alias of its TextShape) is the GPU-backed per-layer text buffer used internally; it owns the glyph instance buffer and a style table. Most callers never touch it directly — Layer.pushText manages packing for you.

Pushing text onto a layer

A layer created with { atlas } exposes the text methods (they throw without an atlas):

• pushText(shape, flags?) — full shaper: kerning, multi-line (\n), and word wrap (maxWidth). Returns layout metrics (glyph count + world bbox).
• pushString(shape) — fast single-line, no-kerning append (equivalent to pushText with shaping off).
• pushAnchoredString(shape, flags?) — world-anchored, screen-sized text: the anchor stays in world coordinates and the shader projects it per-frame, so panning never repacks the glyphs. Em size and offsets are CSS px.
• pushStringsBulkInto(batch) — structure-of-arrays fast path for many short single-line labels with no per-string allocation.

pushText / pushString consume a text shape with these fields:

Field	Type	Default	Notes
text	string	—	The string.
x, y	number	—	Anchor; y is the top of the first line (Y-up).
fontSize	number	16	World units per em.
color	Color	black	Fill color.
align	string	"left"	"left" | "center" | "right".
maxWidth	number	— (no wrap)	Hard wrap width in world units.
lineHeight	number	fontSize*1.2	Line spacing.
simple	boolean	false	Skip kerning / multi-line / wrap for speed.

Text styling

Outline, shadow, and gradient are described per-block by these exported types (stored per text block, looked up per-glyph in the fragment shader):

• TextStyle — { fill, outline?, shadow?, gradient? }.
• TextOutline — { color, width, softness? } (width/softness in screen px).
• TextShadow — { color, dx, dy, softness? } (offset/softness in screen px).
• TextGradient — { from, to, angle? } (angle radians; 0 = left→right).
• BlockGeometry — { originX, originY, width, height }, the block’s world-space content box that a gradient samples within.

Note

Effects are fully supported on the GPU TextPack (MSDF) style table. The default core glyph packer accepts outline / shadow / gradient fields for call-site compatibility but currently ignores them — effect support there is a future milestone. For guaranteed effects, use the MSDF TextPack path.

See also

• Drawing primitives — shapes and sprites.
• Layers & groups — attaching an atlas and the text methods.
• insomni-msdf-text — the standalone TTF/MSDF package behind insomni/text-ttf.