Appearance
@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
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
read
(doc, path) => Promise<ArrayBuffer | Uint8Array<ArrayBufferLike>>
Returns
Promise<{ data: Uint8Array; height: number; width: number; }>
buildTextMesh()
ts
function buildTextMesh(
value,
library,
options?
): TextMeshData;Proportional advances, pair kerning, fallback fonts, multiline alignment and uniform fitting.
Parameters
value
string
library
options?
Returns
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
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<unknown>
Returns
Promise<FontLibrary>
parseGlyphAtlas()
ts
function parseGlyphAtlas(doc): GlyphAtlasDoc;Validate a molen/glyph-atlas@1 document.
Parameters
doc
unknown