tecs.gfx.fonts

newTTFconstructor#

function newTTF(options: TTFOptions): Font?, string?

Reads a font's bytes and its metrics.

Loading a name a font already holds replaces what that name resolves to. A Text already carrying the earlier font keeps it, so a reload changes what new text picks up rather than what old text draws.

Arguments

Returns

Raises

• when neither source nor bytes is given, when the size is not greater than zero, or when the raster is not one of its declared values

Fontrecord#

record Font
    name: string
    source: string
    size: number
    raster: Raster
    ascent: number
    descent: number
    lineGap: number
    lineHeight: number
end

A loaded font and the atlas its glyphs live in.

Immutable in everything a game reads. The atlas behind it grows as glyphs are asked for, which is why imageOf rather than a stored id is what extraction reads.

Fields

name: string

source: string

size: number

raster: Raster

ascent: number

descent: number

lineGap: number

lineHeight: number

Glyphrecord#

record Glyph
    index: integer
    advance: number
    left: number
    top: number
    right: number
    bottom: number
    u0: number
    v0: number
    u1: number
    v1: number
    width: integer
    height: integer
end

One glyph's place in the atlas and its box relative to the pen.

The four plane edges are in em units with y increasing downward from the baseline, so a glyph drawn at em size s with its pen at x, y covers x + left * s to x + right * s horizontally. A glyph with no ink, which is what a space is, reports four zeroes and no atlas region.

Fields

index: integer

advance: number

left: number

top: number

right: number

bottom: number

u0: number

v0: number

u1: number

v1: number

width: integer

height: integer

Rastertype#

type Raster = "sdf" | "alpha"

Selects how a font's glyph images are stored.

These identifiers reach a game's font configuration and are a compatibility surface.

TTFOptionstype#

type TTFOptions = {
    source: string?,
    bytes: string?,
    name: string?,
    size: number?,
    raster: Raster?
}

The options newTTF accepts.

advanceOffunction#

function advanceOf(font: Font, codepoint: integer): number

Returns one codepoint's horizontal advance in em units.

Reads the horizontal metrics directly, so it costs nothing and makes no glyph resident. Measuring a string that will never be drawn goes through here rather than through glyph.

Arguments

Returns

atlasNameOffunction#

function atlasNameOf(name: string): string

The name the atlas is uploaded under.

A glyph entity stores this through its Sprite, and a snapshot stores a sprite's image by name, so the prefix is a compatibility surface.

Arguments

Returns

atlasSizefunction#

function atlasSize(font: Font): integer, integer

Returns the atlas dimensions in texels.

Arguments

Returns

epochfunction#

function epoch(): integer

Returns how many times any atlas has been laid out again.

Growing an atlas moves every region in it, so anything holding a texture coordinate read from a Glyph compares this against what it last saw and reads the regions again when the two differ.

Returns

findfunction#

function find(name: string): Font?

Returns the font one name resolves to.

Arguments

Returns

glyphfunction#

function glyph(font: Font, codepoint: integer): Glyph

Returns the glyph one codepoint selects, making it resident on first use.

A codepoint the font does not carry answers with the face's .notdef glyph, which is the box a font draws for a missing character, rather than with nil. A codepoint with no ink, which is what a space is, answers with a glyph whose advance is set and whose region is empty.

The returned record is the font's own and is updated in place when the atlas grows. Read what you need from it rather than keeping it across frames.

Arguments

Returns

glyphIndexOffunction#

function glyphIndexOf(font: Font, codepoint: integer): integer

Returns the glyph index one codepoint selects.

Arguments

Returns

hasGlyphfunction#

function hasGlyph(font: Font, codepoint: integer): boolean

Reports whether the font carries a glyph for one codepoint.

Arguments

Returns

imageOffunction#

function imageOf(font: Font): integer

Returns the atlas image id, queuing whatever the atlas gained.

The id is permanent, so a caller may store it. Residency is not: call this once per frame that might have added a glyph and let tecs.gfx.images.stateOf report where the upload stands.

Arguments

Returns

kerningOffunction#

function kerningOf(font: Font, left: integer, right: integer): number

Returns the kerning between two codepoints in em units.

Only a format-zero kern table is read. A font that carries its kerning in GPOS alone reports zero for every pair, which lays the text out on its advance widths.

Arguments

Returns

releasefunction#

function release(font: Font): boolean, string?

Drops the atlas from the backend.

The glyphs stay packed and the id survives, so the next imageOf makes the same atlas resident again under the same id. Text drawn in between samples the backend's white fallback.

Arguments

Returns

residentGlyphsfunction#

function residentGlyphs(font: Font): integer

Returns how many glyphs the atlas holds.

Counts every glyph asked for, including the inkless ones that occupy no region, because each of those cost a lookup and a metric.

Arguments

Returns

DEFAULT_SIZEvariable#

const DEFAULT_SIZE: number

The point size a font rasterizes at when the caller names none.

SDF_SPREADvariable#

const SDF_SPREAD: integer

The texels a distance field reaches on each side of an outline.

The same number is the padding around every glyph, because the field has to have somewhere to run before the region ends. A wider spread costs atlas room and buys a thicker outline or glow; four texels carry an ordinary antialiased edge at any size the atlas is used at.