@react-x11/components 0.8.0 → 0.10.0

package/dist/maps/gl/text.d.ts

@@ -0,0 +1,283 @@
+import type { MapIcon } from '../icons.js';
+/** A set string's box, in device pixels. */
+export interface TextBox {
+    width: number;
+    height: number;
+}
+/** Which of an icon's two single-colour rasters. */
+export type IconPart = 'plate' | 'glyph';
+/** One string to set, at `size` device pixels — or, with `icon`, one piece
+ *  of an icon `size` pixels across, and `text` empty. */
+export interface TextItem {
+    text: string;
+    size: number;
+    icon?: {
+        name: MapIcon;
+        part: IconPart;
+    };
+}
+/** A rasterized string, `pad` pixels of clear margin included: RGBA as
+ *  read back, coverage in alpha — or, with `stride` 1, the text engine's own
+ *  coverage, one byte a pixel. */
+export interface TextRaster {
+    width: number;
+    height: number;
+    pixels: Uint8Array;
+    /** Bytes a pixel: 4 (the default) for a readback, 1 for coverage. */
+    stride?: 1 | 4;
+}
+/** What the atlas asks of a text engine. */
+export interface TextEngine {
+    /** The box `text` sets in, synchronously — placement needs it now. */
+    measure(text: string, size: number): TextBox;
+    /**
+     * Rasterize as many of `items` as fit one batch. Answers per item: a
+     * raster; `null` for one that can never be drawn (wider than the engine
+     * can set); `undefined` for one left for the next batch.
+     */
+    rasterize(items: readonly TextItem[], pad: number): Promise<(TextRaster | null | undefined)[]>;
+    /**
+     * One item set now, synchronously, where the engine can: a raster;
+     * `null` for one that can never be drawn; `undefined` for one it can only
+     * set through {@link rasterize} (an icon's paths, or an engine whose
+     * layouts answer no coverage of their own). Optional.
+     */
+    rasterizeNow?(item: TextItem, pad: number): TextRaster | null | undefined;
+    dispose(): void;
+}
+/** ntk's font cache, structurally — `../labels.ts`' `FontsLike`. */
+interface FontsLike {
+    layout(content: string, style: Record<string, unknown>): {
+        width: number;
+        height: number;
+        draw(ctx: unknown, x: number, y: number): void;
+        /** The engine's own coverage of the layout, one byte a pixel, with
+         *  `pad` round its box — where the engine answers it
+         *  (sidorares/react-x11#673). */
+        coverage?(options?: {
+            pad?: number;
+        }): {
+            width: number;
+            height: number;
+            data: Uint8Array;
+        } | null;
+    };
+}
+/** The text engine over an app's fonts and an offscreen surface. */
+export declare class SurfaceTextEngine implements TextEngine {
+    private readonly _app;
+    private readonly _fonts;
+    private readonly _family;
+    private readonly _layouts;
+    private _surface;
+    private _ctx;
+    /** Whether the layouts answer their own coverage: unknown until a string
+     *  asks, and false for good once one does not. */
+    private _coverage;
+    constructor(app: unknown, fonts: FontsLike, family: string);
+    /** The engine for the app a node belongs to, or null where there is
+     *  nothing to set text with. */
+    static forApp(app: unknown, family: string): SurfaceTextEngine | null;
+    private _layout;
+    measure(text: string, size: number): TextBox;
+    /**
+     * Strings the layouts set themselves, where the engine answers a layout's
+     * coverage (react-x11#673): no staging surface and no readback. The rest —
+     * icons, which are paths, and every string on an engine that cannot — go
+     * through the surface.
+     */
+    /**
+     * A string the layout sets itself, synchronously, where the engine
+     * answers a layout's coverage — no surface, no readback, nothing to wait
+     * for. `undefined` for an icon, and for every string once the engine has
+     * shown it cannot.
+     */
+    rasterizeNow(item: TextItem, pad: number): TextRaster | null | undefined;
+    rasterize(items: readonly TextItem[], pad: number): Promise<(TextRaster | null | undefined)[]>;
+    private _stage;
+    dispose(): void;
+}
+/** A rasterized label's place in the atlas: its whole padded raster. */
+export interface AtlasEntry {
+    key: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** The distance field, one byte a texel — kept to upload again, after a
+     *  compaction moves it or into the texture of a new context. */
+    pixels: Uint8Array;
+    /** In the texture where it is now; only then is it drawn. Set by the
+     *  renderer that uploads it. */
+    ready: boolean;
+    /** The frame it was last asked for — what a compaction keeps. */
+    used: number;
+}
+/**
+ * Texels the drawn quad leaves off each side of a field: bilinear samples
+ * at its edge then stay inside the field's own margin, never reaching the
+ * shelf's unwritten rows or a neighbour.
+ */
+export declare const QUAD_INSET = 1;
+/**
+ * How far past the glyphs' edge a field can see, in its own texels — the
+ * widest halo it holds, and the reach of its distances before they
+ * saturate — for a field set with `pad` texels of margin and `pad` of
+ * spread. Scale by the drawn size over the base for screen pixels.
+ */
+export declare const fieldReach: (pad: number) => number;
+/** The base size a display scale sets fields at, in device pixels: 16 at
+ *  1x, 32 at 2x — the size most map labels are drawn at or just under, so
+ *  a field is mostly sampled down, where it is sharpest. */
+export declare const fieldBase: (scale: number) => number;
+/** A field's margin and spread at a base size: room for a halo of a
+ *  quarter of the type's height. */
+export declare const fieldPad: (base: number) => number;
+/**
+ * Every label raster, packed into one texture's worth of shelves, with the
+ * uploads the renderer owes it.
+ *
+ * The atlas is CPU-side and outlives any one GL context: it keeps each
+ * entry's raster, so a renderer that is new — the surface was recreated —
+ * uploads it again from here ({@link restart}), and asks nothing of the text
+ * engine. What it holds is bounded by the texture it packs into: 16 MB for
+ * the default 2048², whatever is panned past.
+ *
+ * **Measuring is budgeted, drawing is asynchronous, uploading is metered.**
+ * Placement needs a label's box the frame it is considered, which is a
+ * synchronous shaping call — tens of microseconds on the Cocoa backend, but
+ * milliseconds each the first time on X11, where fonts load and glyphs
+ * rasterize in JS — so a frame measures until its deadline and leaves the
+ * rest for the next. A raster is asked for only once a label has won a
+ * place, and arrives a batch at a time, a readback later; the renderer
+ * takes a few dozen a frame into the texture, and a label fades in once its
+ * raster is there.
+ */
+export declare class LabelAtlas {
+    readonly size: number;
+    /** The device-pixel size every string and icon is set at: a label drawn
+     *  at `size` scales its field by `size / base`. */
+    readonly base: number;
+    /** The margin set around every field, in its texels, which is also the
+     *  distance its values span — what a halo grows into. */
+    readonly pad: number;
+    /** A frame's measuring ran out of budget: there is more to place. */
+    starved: boolean;
+    onChange: (() => void) | null;
+    private _engine;
+    private readonly _entries;
+    /** Entries the texture does not have where they are, oldest first. */
+    private _uploads;
+    /** Drawable entries a compaction moved: all of them go up in the next
+     *  frame, ahead of any cap, before it draws. */
+    private _moved;
+    private readonly _wanted;
+    private readonly _failed;
+    /** Rasters read back and waiting for their fields, oldest first — asked
+     *  for as much as anything in `_wanted`, so a frame never asks again. */
+    private _fieldQueue;
+    private readonly _queued;
+    private readonly _measured;
+    private _busy;
+    private _shelves;
+    private _top;
+    private _frame;
+    private _deadline;
+    private _measures;
+    constructor(engine: TextEngine | null, options?: {
+        size?: number;
+        base?: number;
+        pad?: number;
+    });
+    /** Strings asked for and not yet set: waiting, being read back, or
+     *  waiting for their fields. */
+    get pending(): boolean;
+    /** Rasters waiting for the texture. */
+    get uploading(): boolean;
+    get entries(): number;
+    /** A new frame, whose measuring stops at `deadline` (after one). */
+    beginFrame(deadline: number): void;
+    /** The box a string sets in at `size`, or null when this frame's budget
+     *  is spent. Measured once, at the base size, and scaled — the same
+     *  arithmetic that scales its field, so the box placement collides and
+     *  the quad the frame draws are one size. */
+    measure(text: string, size: number): TextBox | null;
+    /** The string's field, once the texture has it; null until then —
+     *  asking is what gets it set. One field whatever size it is drawn at. */
+    entry(text: string): AtlasEntry | null;
+    /** One piece of an icon, as {@link entry} answers for a string. */
+    icon(name: MapIcon, part: IconPart): AtlasEntry | null;
+    private _lookup;
+    /** Whether an icon can never be drawn — the engine has no path to fill
+     *  it with. A name set beside it is then set alone. */
+    iconFailed(name: MapIcon): boolean;
+    /** Start rasterizing what has been asked for, unless a batch is out. */
+    pump(): void;
+    /** Rasters for the texture: every one a compaction moved, then up to
+     *  `max` new ones, oldest first. The renderer marks each `ready` once it
+     *  is uploaded — a moved one already is, because the frame that takes it
+     *  draws after taking it. */
+    takeUploads(max: number): AtlasEntry[];
+    /** The texture is new, and has none of it: everything goes up again. */
+    restart(): void;
+    dispose(): void;
+    /** Read back and waiting for their fields: another frame is worth
+     *  drawing, to make them. */
+    get fielding(): boolean;
+    /**
+     * Make fields for what has been read back until `deadline` — at least
+     * one — in the frame, whose own draw then takes them into the texture.
+     *
+     * A field is about 0.2 ms. A batch of them made as it landed was 4-9 ms
+     * beside the frames, measured as event-loop stalls on a jump to a view
+     * whose every name was new; slices on timers of their own each waited
+     * behind a frame, and names arrived late. In the frame, on a budget,
+     * they are made at a known cost and drawn the frame after.
+     */
+    /**
+     * Set what placement asked for, in the frame, until `deadline` (at least
+     * one): what was read back already, then every string the engine can set
+     * synchronously. What is set here is drawable in this frame — it goes
+     * into the texture ahead of any cap, before this frame draws (the
+     * `labelsWhileMoving` path, `view.ts`). Icons, and an engine with no
+     * synchronous path, still go through {@link pump}.
+     */
+    setNow(deadline: number): void;
+    makeFields(deadline: number): void;
+    /** A raster's coverage as its distance field. The coverage is the
+     *  readback's alpha; the field spans `pad` texels either side of the
+     *  edge, which is the margin the engine set it with. */
+    private _field;
+    private _add;
+    /** A shelf packer: rows of one height class (rounded up to 8 pixels),
+     *  filled left to right, a new row below the last when none has room. */
+    private _allocate;
+    /**
+     * Room made in place: the shelf of this height whose rasters were drawn
+     * longest ago, emptied and filled again from its left.
+     *
+     * **Nothing that stays moves.** A compaction moves every raster it keeps,
+     * and a moved raster is not drawn until it is in the texture again — at
+     * {@link takeUploads}' pace, so every label on screen went out together
+     * and came back over the next few frames, at full opacity. A full atlas
+     * is the ordinary state of a session (a thousand strings at 1x, a quarter
+     * of that at 2x), so that was a flash of the whole label layer at the end
+     * of most settles. A shelf any label of the last two frames stands on is not
+     * taken: what is dropped is off screen, and asked for again if it
+     * returns.
+     */
+    private _reuseShelf;
+    /** Whether a compaction would free anything: something kept past its
+     *  last use. One that keeps everything only moves it — every label on
+     *  screen out of the texture for the frames its upload takes, for no
+     *  room at all. */
+    private _compactable;
+    /** Drop what has not been drawn for a while and pack the rest again,
+     *  tallest first — the last resort, when no shelf of the height wanted
+     *  can be taken in place. What was drawable stays drawable: it is
+     *  uploaded where it now is, all of it, by the next frame before that
+     *  frame draws ({@link takeUploads}); what was waiting still waits. */
+    private _compact;
+}
+export {};
+//# sourceMappingURL=text.d.ts.map

package/dist/maps/gl/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../../src/maps/gl/text.ts"],"names":[],"mappings":"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"}