@solidrt/flux-types 0.0.67 → 0.0.68

package/README.md

@@ -48,7 +48,8 @@ rely on must be named.
 - `flux:*` modules: `flux:http`, `flux:fs`, `flux:sqlite`, `flux:subprocess`,
   `flux:p2p`, `flux:net`, `flux:mdns`, `flux:process`, `flux:tty`, `flux:path`, `flux:wasm`,
   and (on a gui-enabled runtime)
-  `flux:camera`, `flux:microphone`, `flux:audio`, `flux:gpu`, `flux:spatial`.
+  `flux:camera`, `flux:microphone`, `flux:audio`, `flux:gpu`, `flux:spatial`,
+  `flux:font`.
 - Web-standard globals: `console`, `fetch` + `Headers`/`Request`/`Response`,
   `setTimeout`/`setInterval`/`queueMicrotask`, `performance`, `WebSocket`,
   `TextEncoder`/`TextDecoder`, `crypto.subtle.digest`. These are deliberate subsets matching exactly what

package/gui/font.d.ts

@@ -0,0 +1,137 @@
+// The glyph engine (gui-enabled runtime only): a registered font shaped on
+// the runtime's own shaper, its glyphs rasterized into an atlas texture a
+// consumer samples itself - the sprite layer's world-space text, a terminal
+// grid, anything that draws glyph quads. `<text>` does not draw through
+// this; it is the primitive beneath that for text the tree cannot carry.
+//
+// A font handle is one face (family, weight, style) with one atlas of one
+// cell kind. Prepare text over it to get units whose glyphs are named and
+// placed, ask for the cells of the glyphs you draw, then draw each glyph as
+// a quad at its placement sampling the atlas rect. Cells are made on a
+// worker thread and land at a later frame: draw a glyph whose cell has not
+// arrived as nothing at its advance, and re-read the cells when the promise
+// resolves.
+
+declare module "flux:font" {
+  import type { TextureId } from "flux:gpu"
+  import type { PreparedText } from "flux:rendertree"
+
+  /** A created font, valid until {@link destroyFont}. */
+  type FontId = number
+
+  /**
+   * The face a font shapes and rasterizes with: the same vocabulary as a
+   * `<text>`'s font props, resolved the same way (a role alias such as
+   * "sans", "serif" or "mono", or a registered family name; an unknown
+   * family falls back to sans). `fontSize` is the size a "mask" atlas is
+   * made at and the default size {@link prepareText} shapes at; an "msdf"
+   * atlas is size-independent.
+   */
+  type FontFace = {
+    fontFamily?: "sans" | "serif" | "mono" | (string & {})
+    fontSize?: number
+    fontStyle?: "normal" | "italic"
+    fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+    /** Width as a percentage of normal (CSS font-stretch), on the font's width axis; default 100. */
+    fontStretch?: number
+    /** Line height as a multiplier of the size, 0 for the font's own line. */
+    lineHeight?: number
+  }
+
+  /** Options for {@link createFont}. */
+  type FontAtlasOptions = {
+    /**
+     * What the atlas holds. "msdf" (default): multi-channel signed distance
+     * fields at `size` texels per em, one cell for every zoom; the consumer
+     * decodes the field in its shader (the sprite layer's text does).
+     * "mask": coverage masks at the face's pixel size, premultiplied white,
+     * drawn 1:1 as a plain texture - a terminal, a HUD at a fixed size.
+     */
+    cells?: "mask" | "msdf"
+    /** Texels per em of the cells: the face's `fontSize` for a mask atlas, 48 for an msdf one. */
+    size?: number
+    /** msdf only: the distance range in texels (default 8), the room an outline has. */
+    range?: number
+    /** Keep a mip chain on the atlas texture: default true for msdf (sampled at every zoom), false for mask. */
+    mipmap?: boolean
+    /** Debug label of the atlas texture. */
+    label?: string
+  }
+
+  /** The atlas of a font: its texture, its current size and what its cells are. */
+  type FontAtlas = {
+    texture: TextureId
+    /** Current size in texels. The atlas grows as glyphs arrive; a change of size means EVERY cell moved, so re-read placements with {@link glyphCells}. */
+    width: number
+    height: number
+    cells: "mask" | "msdf"
+    /** Texels per em the cells were made at. */
+    size: number
+    /** The face's size: what {@link prepareText} shapes at by default (the runtime's text default when the face named none). */
+    fontSize: number
+    /** msdf: the distance range in texels; 0 for a mask atlas. */
+    range: number
+  }
+
+  /**
+   * Where a glyph's cell sits in the atlas (`x`, `y`, `width`, `height`,
+   * texels) and how the cell sits on the glyph: `left` texels right of the
+   * glyph origin, `top` texels above the baseline. To draw a glyph placed
+   * at pen (px, py) in a text prepared at `fontSize`, scale by
+   * `fontSize / atlas.size` and put the cell's top-left at
+   * `(px + left * s, py + ascent - top * s)`.
+   */
+  type GlyphCell = {
+    glyph: number
+    x: number
+    y: number
+    width: number
+    height: number
+    left: number
+    top: number
+  }
+
+  /** Options for {@link prepareText} over a font. */
+  type FontPrepareOptions = {
+    /** Pixels per em to shape at; default the face's `fontSize`. */
+    fontSize?: number
+    /** Line height multiplier; default the face's. */
+    lineHeight?: number
+    /** Also report each unit's caret stops (one pass over the cluster map). */
+    carets?: boolean
+  }
+
+  /**
+   * Create a font: one face with an empty atlas. Throws on an unknown cells
+   * kind or a non-positive size. The atlas texture exists from here, so a
+   * layer can declare it at creation and draw from it as cells arrive.
+   */
+  function createFont(face?: FontFace, options?: FontAtlasOptions): FontId
+  /** Free the font and its atlas texture. Requests still pending on it reject. */
+  function destroyFont(font: FontId): void
+  /** The font's atlas as it is now. */
+  function fontAtlas(font: FontId): FontAtlas
+  /**
+   * Shape `text` on the font (the runtime's own shaper): the same
+   * `PreparedText` as `flux:rendertree`'s, every unit also carrying its
+   * `glyphs` - ids and pen positions, kerned, in pixels at `fontSize` -
+   * for app-side line breaking with `layoutNextLine` and glyph placement.
+   * The font is one face and its atlas holds that face's cells only, so a
+   * character the face lacks shapes to its missing glyph (id 0) with no
+   * fallback to another font, where a `<text>` would borrow the glyph;
+   * whitespace and control characters the face lacks take the space's
+   * advance.
+   */
+  function prepareText(font: FontId, text: string, options?: FontPrepareOptions): PreparedText
+  /**
+   * Make the cells of `glyphs` (ids from prepared units) that the atlas
+   * does not hold yet, on the worker thread. Resolves once every glyph is
+   * placed or has failed (a glyph the font cannot rasterize, or an atlas
+   * at the device's texture size cap), with one {@link GlyphCell} per
+   * requested glyph, null for a failed one. Work in flight: `settle`
+   * waits for it. Rejects if the font is destroyed first.
+   */
+  function requestGlyphs(font: FontId, glyphs: number[]): Promise<(GlyphCell | null)[]>
+  /** The cells of `glyphs` as the atlas holds them now, null for a glyph not (yet) in it. */
+  function glyphCells(font: FontId, glyphs: number[]): (GlyphCell | null)[]
+}

package/gui/gpu.d.ts

@@ -358,13 +358,20 @@ declare module "flux:gpu" {
    * for byte formats, Float32Array for float formats).
    */
   export function createMutableTexture(data: Uint8Array | Float32Array | Uint32Array, width: number, height: number, opts?: SamplerOptions & TextureFormatOption & LabelOption): TextureId
+  /** A rect of a texture, in texels from its top-left: the third argument of {@link uploadTexture}. */
+  export type TextureRect = { x: number, y: number, width: number, height: number }
   /**
    * Replace a mutable texture's pixels; the frame size and required view
    * type (Uint8Array for byte formats, Float32Array for float formats)
    * follow the format the id was created with. `data` may hold several
-   * frames; `offset` (default 0) selects which frame to upload.
+   * frames; a numeric `at` (default 0) selects which frame to upload. A
+   * rect `at` uploads `data` as exactly that rect of the texture instead -
+   * `data` then holds `width * height` pixels - and the rect must lie
+   * inside the texture (GL's texSubImage2D with an offset): how a runtime
+   * atlas writes one cell without re-sending the sheet. A mip chain
+   * regenerates after either form.
    */
-  export function uploadTexture(id: TextureId, data: Uint8Array | Float32Array | Uint32Array, offset?: number): void
+  export function uploadTexture(id: TextureId, data: Uint8Array | Float32Array | Uint32Array, at?: number | TextureRect): void
   /**
    * Replace a texture's storage with a new size at the same id (an id-stable
    * resize): `<texture src>` references and shader sampler bindings keep

package/gui/rendertree.d.ts

@@ -12,6 +12,10 @@ declare module "flux:rendertree" {
     fontSize?: number
     fontStyle?: "normal" | "italic"
     fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+    /** Width as a percentage of normal (CSS font-stretch), on the font's width axis; default 100. */
+    fontStretch?: number
+    /** Extra advance after every character in pixels (CSS letter-spacing); default 0. */
+    letterSpacing?: number
     lineHeight?: number
     /** measureText only. */
     maxLines?: number
@@ -35,6 +39,8 @@ declare module "flux:rendertree" {
     fontSize?: number
     fontStyle?: "normal" | "italic"
     fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+    fontStretch?: number
+    letterSpacing?: number
     lineHeight?: number
   }
 
@@ -66,12 +72,20 @@ declare module "flux:rendertree" {
      * cluster boundary from its start (`offset` = start, x 0) to the end of
      * its shaped text (before any break characters), in order. `offset` is
      * into the prepared text, `x` from the unit's pen position. These are
-     * the per-glyph x positions of the shaping that is drawn, kerning
-     * included: for placing or animating single glyphs, use them rather
+     * the runtime's own shaper's glyph positions for the unit, kerning
+     * included, within a texel of what is drawn and ending on the unit's
+     * drawn advance: for placing or animating single glyphs, use them rather
      * than measuring characters one at a time with measureText, which sees
      * no neighbors and drifts on every kerning pair.
      */
     carets?: { offset: number, x: number }[]
+    /**
+     * The unit's glyphs, from `flux:font`'s prepareText only (its ids name
+     * cells of that font's atlas): the font's glyph `id`, the glyph origin
+     * `x`/`y` from the unit's pen position (kerned, y down) and the pen
+     * `advance` it contributes.
+     */
+    glyphs?: { id: number, x: number, y: number, advance: number }[]
   }
 
   /** The wrap units of a text in one font, shaped once. Plain data; layout is arithmetic over `units`. */
@@ -200,10 +214,20 @@ declare module "flux:rendertree" {
    * the shared word cache, so a text already drawn or prepared costs no
    * shaping), for app-side line breaking - text into a shape, around an
    * obstacle, across columns, fitted by size, per glyph; see layoutNextLine
-   * in @solidrt/core. `runs` restyle ranges, `carets` adds glyph positions;
+   * in @solidrt/core. `runs` restyle ranges, `carets` adds caret stops;
    * `maxLines` is ignored.
    */
   export function prepareText(text: string, options?: MeasureTextOptions): PreparedText
+  /**
+   * Make the glyph cells of printable ASCII for these font styles ahead of
+   * their first use, on the engine's worker thread: the type scale an app
+   * draws its screens in, called at startup under the splash, so a first
+   * paint in any of them never waits for cells. Each entry names a font
+   * (family, size, weight, style) as a `<text>` would; `lineHeight`,
+   * `maxLines`, `carets` and `runs` are ignored. Glyphs outside ASCII are
+   * made at first use.
+   */
+  export function warmText(styles: MeasureTextOptions[]): void
   /**
    * The node's bounding box from the most recent layout, relative to its
    * nearest positioning context (an ancestor with an explicit

package/index.d.ts

@@ -38,6 +38,7 @@
 /// <reference path="./gui/audio.d.ts" />
 /// <reference path="./gui/gpu.d.ts" />
 /// <reference path="./gui/spatial.d.ts" />
+/// <reference path="./gui/font.d.ts" />
 /// <reference path="./gui/video.d.ts" />
 /// <reference path="./gui/raf.d.ts" />
 /// <reference path="./gui/test.d.ts" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",