Skip to content

@bendyline/molen-materials/text ​

Molen materials: pixel grids, SVG and procedural material graphs (rungs 2-4). No three.js.

ts
import { /* … */ } from '@bendyline/molen-materials/text';

Interfaces ​

AtlasTextLayout ​

Properties ​

capHeight ​
ts
capHeight: number;

Cap height in output units: what decides when the letters are worth drawing.

face ​
ts
face: string;

The face the text was set in: the first candidate holding every character.

height ​
ts
height: number;
lines ​
ts
lines: string[];
quads ​
ts
quads: Float32Array;

Per glyph x0, y0, x1, y1, u0, v0, u1, v1: the quad's lower-left and upper-right corners in output units, Y up and centered on the fitted block, and the combined texture's coordinates at those same corners.

scale ​
ts
scale: number;

Output units per em.

width ​
ts
width: number;

Fitted ink extent, output units.


AtlasTextOptions ​

Properties ​

font? ​
ts
optional font?: string;

A face id or role; default the first document's default face.

letterSpacing? ​
ts
optional letterSpacing?: number;

Extra advance between letters, in em (default 0).

maxHeight ​
ts
maxHeight: number;
maxLines? ​
ts
optional maxLines?: number;

1 or 2 (default 1): with 2, a line break is used where it sets the letters larger.

maxWidth ​
ts
maxWidth: number;

Box the ink is fitted into, in output units.

size? ​
ts
optional size?: number;

Largest em size in output units (default no limit beyond the box).


FontLibrary ​

Properties ​

defaultFont ​
ts
defaultFont: string;
fonts ​
ts
fonts: Readonly<Record<string, VectorFont>>;
roles? ​
ts
optional roles?: Readonly<Record<string, string>>;

Semantic roles, e.g. highway, sans, serif and mono. Values are font ids.


GlyphAtlasDoc ​

Properties ​

defaultFace ​
ts
defaultFace: string;
distanceRange ​
ts
distanceRange: number;

Texels of signed distance across the byte range: 128 is the outline, 255 that far inside.

emSize ​
ts
emSize: number;

Texels per em at which the glyphs were rasterized.

faces ​
ts
faces: Record<string, GlyphAtlasFace>;
format ​
ts
format: "molen/glyph-atlas@1";
id ​
ts
id: string;
padding ​
ts
padding: number;

Texels of distance field kept around each glyph's ink.

pages ​
ts
pages: GlyphAtlasPage[];
roles? ​
ts
optional roles?: Record<string, string>;

Semantic names (sans, bold, serif) for face ids.


GlyphAtlasFace ​

Properties ​

ascent ​
ts
ascent: number;

Font-wide metrics in em.

capHeight ​
ts
capHeight: number;
descent ​
ts
descent: number;
family ​
ts
family: string;
glyphs ​
ts
glyphs: Record<string, GlyphAtlasGlyph>;
kerning? ​
ts
optional kerning?: Record<string, number>;

Pair adjustments in em; keys are two characters.

lineHeight ​
ts
lineHeight: number;
style ​
ts
style: "normal" | "italic";
weight ​
ts
weight: number;

GlyphAtlasPage ​

Properties ​

height ​
ts
height: number;
path ​
ts
path: string;

Raw 8-bit distance values, width * height bytes, relative to the document's own path.

width ​
ts
width: number;

GlyphAtlasSet ​

Properties ​

distanceRange ​
ts
readonly distanceRange: number;
docs ​
ts
readonly docs: readonly GlyphAtlasDoc[];
hash ​
ts
readonly hash: string;

Content hash of the documents, for cache keys.

height ​
ts
readonly height: number;
pages ​
ts
readonly pages: readonly GlyphAtlasSetPage[];
width ​
ts
readonly width: number;

Combined texture size: the widest page, and every page's height stacked.

Methods ​

faceFor() ​
ts
faceFor(text, font?): string | undefined;

The face that would set text, or undefined when no face holds every character.

Parameters ​
text ​

string

font? ​

string

Returns ​

string | undefined

layout() ​
ts
layout(text, options): AtlasTextLayout | undefined;

Lay out text; undefined when no face holds every character.

Parameters ​
text ​

string

options ​

AtlasTextOptions

Returns ​

AtlasTextLayout | undefined


GlyphAtlasSetPage ​

Where one document page sits in a set's combined texture.

Properties ​

doc ​
ts
doc: number;

Index of the document in the list the set was made from.

height ​
ts
height: number;
page ​
ts
page: number;

The document's page index and path.

path ​
ts
path: string;
top ​
ts
top: number;

First row of the page in the combined texture; pages start at column 0.

width ​
ts
width: number;

TextLayoutOptions ​

Properties ​

align? ​
ts
optional align?: "left" | "center" | "right";
fallbackFonts? ​
ts
optional fallbackFonts?: readonly string[];
font? ​
ts
optional font?: string;

A font id or semantic role in the library.

letterSpacing? ​
ts
optional letterSpacing?: number;

Additional advance in em units.

lineHeight? ​
ts
optional lineHeight?: number;

Baseline spacing in em units, default the face's lineHeight.

maxCharacters? ​
ts
optional maxCharacters?: number;

Bounds CPU/geometry work; default 256, maximum 4096 Unicode characters.

maxHeight? ​
ts
optional maxHeight?: number;
maxWidth? ​
ts
optional maxWidth?: number;
overflow? ​
ts
optional overflow?: "shrink" | "ellipsis";
size? ​
ts
optional size?: number;

Maximum em size in world units (default 1). Fitting never stretches glyphs.

verticalAlign? ​
ts
optional verticalAlign?: "center" | "baseline" | "top";

TextMeshData ​

Properties ​

height ​
ts
height: number;
indices ​
ts
indices: Uint32Array;
missingGlyphs ​
ts
missingGlyphs: string[];
positions ​
ts
positions: Float32Array;
text ​
ts
text: string;

The rendered text after normalization/length limiting/ellipsis.

truncated ​
ts
truncated: boolean;
width ​
ts
width: number;

VectorFont ​

Compiled outlines: fonts remain content supplied by the host, never embedded in library code.

Properties ​

ascent ​
ts
ascent: number;
descent ​
ts
descent: number;
family ​
ts
family: string;
format ​
ts
format: "molen/vector-font@1";
glyphs ​
ts
glyphs: Record<string, VectorGlyph>;
id ​
ts
id: string;
kerning ​
ts
kerning: Record<string, number>;

Keys are pairs of Unicode characters, including supplementary code points.

lineHeight ​
ts
lineHeight: number;
style ​
ts
style: "normal" | "italic";
weight ​
ts
weight: number;

VectorGlyph ​

Glyph coordinates and advance are in em units, Y up. Triangles face +Z.

Properties ​

advance ​
ts
advance: number;
indices ​
ts
indices: number[];
positions ​
ts
positions: number[];

Type Aliases ​

GlyphAtlasGlyph ​

ts
type GlyphAtlasGlyph = number[];

One glyph: [advance] for a glyph with no ink (a space), otherwise [advance, left, bottom, right, top, page, x0, y0, x1, y1]. Advance and the plane box are in em, from the pen on the baseline with Y up; the box is exactly the texel rectangle [x0, x1) × [y0, y1) on page (row 0 is the page's first row, the glyph's top at y0), including the distance field's padding around the ink.

Variables ​

vectorFontSchema ​

ts
const vectorFontSchema: z.ZodType<VectorFont>;

Functions ​

assembleGlyphAtlasPixels() ​

ts
function assembleGlyphAtlasPixels(set, read): Promise<{
  data: Uint8Array;
  height: number;
  width: number;
}>;

Assemble a set's pages into one combined 8-bit texture image (row 0 first), reading each page through the host's loader. read(doc, path) resolves a page path against document doc.

Parameters ​

set ​

GlyphAtlasSet

read ​

(doc, path) => Promise&lt;ArrayBuffer | Uint8Array&lt;ArrayBufferLike&gt;&gt;

Returns ​

Promise&lt;{ data: Uint8Array; height: number; width: number; }&gt;


buildTextMesh() ​

ts
function buildTextMesh(
   value, 
   library, 
   options?
): TextMeshData;

Proportional advances, pair kerning, fallback fonts, multiline alignment and uniform fitting.

Parameters ​

value ​

string

library ​

FontLibrary

options? ​

TextLayoutOptions

Returns ​

TextMeshData


createGlyphAtlasSet() ​

ts
function createGlyphAtlasSet(input): GlyphAtlasSet;

Combine glyph atlas documents (metrics only; pixels stay with the renderer). Every document must share one distance range, so a single material reads them all. Later documents add faces; the first document's default face is the set's default.

Parameters ​

input ​

readonly unknown[]

Returns ​

GlyphAtlasSet


loadFontLibrary() ​

ts
function loadFontLibrary(catalog, read): Promise<FontLibrary>;

Read catalog-relative font documents through the host's file/pack loader; never fetches URLs.

Parameters ​

catalog ​

unknown

read ​

(path) => Promise&lt;unknown&gt;

Returns ​

Promise&lt;FontLibrary&gt;


parseGlyphAtlas() ​

ts
function parseGlyphAtlas(doc): GlyphAtlasDoc;

Validate a molen/glyph-atlas@1 document.

Parameters ​

doc ​

unknown

Returns ​

GlyphAtlasDoc

50 guides · 44 schema formats · 51 API entry points · 11 samples. API, CLI and schema pages are generated from the shipped build.