@tangram.gl/tangram-renderer 0.0.0-stage → 0.0.0

package/src/styles/text/font_manager.ts

@@ -0,0 +1,180 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+
+import log from '../../utils/log';
+import Utils from '../../utils/utils';
+import FontFaceObserver from 'fontfaceobserver';
+
+interface FontFaceDefinition {
+    url?: string;
+    weight?: string | number;
+    style?: string;
+    [key: string]: unknown;
+}
+
+type FontDefinition = FontFaceDefinition | FontFaceDefinition[] | 'external';
+type FontCollection = Record<string, FontDefinition>;
+
+interface FontFaceOptions {
+    family: string;
+    weight?: string | number;
+    style?: string;
+    [key: string]: unknown;
+}
+
+interface FontManagerApi {
+    fonts_loaded: Promise<void>;
+    last_loaded: string | null;
+    supports_native_font_loading?: boolean;
+    loadFonts(fonts?: FontCollection | null): Promise<void>;
+    loadFontFace(family: string, face: FontDefinition): Promise<void>;
+    injectFontFace(options: FontFaceOptions & {url?: string}): Promise<void>;
+}
+
+const FontManager: FontManagerApi = {
+
+    // Font detection
+    fonts_loaded: Promise.resolve(), // resolves when all requested fonts have been detected
+    last_loaded: null,               // tracks last set of fonts loaded
+
+    // Load set of custom font faces
+    // `fonts` is an object where the key is a font family name, and the value is one or more font face
+    // definitions. The value can be either a single object, or an array of such objects.
+    // If the special string value 'external' is used, it indicates the the font will be loaded via external CSS.
+    loadFonts (fonts?: FontCollection | null): Promise<void> {
+        const same = (JSON.stringify(fonts) === this.last_loaded);
+        if (fonts && !same) {
+            const queue = [];
+            for (const family in fonts) {
+                if (Array.isArray(fonts[family])) {
+                    fonts[family].forEach(face => queue.push(this.loadFontFace(family, face)));
+                }
+                else {
+                    queue.push(this.loadFontFace(family, fonts[family]));
+                }
+            }
+
+            this.last_loaded = JSON.stringify(fonts);
+            this.fonts_loaded = Promise.all(queue.filter(x => x)).then(() => undefined);
+        }
+        return this.fonts_loaded;
+    },
+
+    // Load a single font face
+    // `face` contains the font face definition, with optional parameters for `weight`, `style`, and `url`.
+    // If the `url` is defined, the font is injected into the document as a CSS font-face.
+    // If the object's value is the special string 'external', or if no `url` is defined, then the font face
+    // is assumed is assumed to been loaded via external CSS. In either case, the function returns a promise
+    // that resolves when the font face has loaded, or times out.
+    async loadFontFace (family: string, face: FontDefinition): Promise<void> {
+        if (face == null || (typeof face !== 'object' && face !== 'external')) {
+            return;
+        }
+
+        const options: FontFaceOptions = {family};
+
+        if (typeof face === 'object' && !Array.isArray(face)) {
+            Object.assign(options, face);
+
+            // If URL is defined, inject font into document
+            if (typeof face.url === 'string') {
+                await this.injectFontFace(options);
+            }
+        }
+
+        // Wait for font to load
+        try {
+            // FontFaceObserver does not directly support variable fonts syntax, which allows for ranges,
+            // e.g. `font-weight: 100 800`. FontFaceObserver will insert the entire string value into a
+            // CSS `font` shorthand property, causing an error. To get around this, we simply take the first
+            // value, because as soon as one variant of the variable font is available, they all should be.
+            // See https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide
+            options.weight = typeof options.weight === 'string' ? options.weight.split(' ')[0] : options.weight;
+            const observer = new FontFaceObserver(family, options);
+            await observer.load();
+            // Promise resolves, font is available
+            log('debug', `Font face '${family}' is available`, options);
+        }
+        catch (e) {
+            // Promise rejects, font is not available
+            log('warn', `Font face '${family}' is NOT available`, options, e);
+        }
+    },
+
+    // Loads a font face via either the native FontFace API, or CSS injection
+    // TODO: consider support for multiple format URLs per face, unicode ranges
+    async injectFontFace ({family, url, weight, style}: FontFaceOptions & {url?: string}): Promise<void> {
+        if (!url) {
+            return;
+        }
+
+        if (this.supports_native_font_loading === undefined) {
+            this.supports_native_font_loading = (window.FontFace !== undefined);
+        }
+
+        // Convert blob URLs, depending on whether the native FontFace API will be used or not.
+        //
+        // When the FontFace API *is* supported, the blob URL is read into a raw data array.
+        // NB: it's inefficient to be converting blob URLs into typed arrays here, since they originated
+        // as raw data *before* they were converted into blob URLs. However, this process should be fast since
+        // these are native browser functions and all data is local (no network request), and it keeps the
+        // logic streamlined by allowing us to continue to use a URL-based interface for all scene resources.
+        //
+        // When the FontFace API is *not* supported, the blob URL data is converted to a base64 data URL.
+        // This avoids security restricions in some browsers.
+        // Also see https://github.com/bramstein/fontloader/blob/598e9399117bdc946ff786fa2c5007a6bd7d3b9e/src/fontface.js#L145-L153
+        let data: string | Uint8Array = url;
+        if (url.slice(0, 5) === 'blob:') {
+            const body = (await Utils.io(url, 60000, 'arraybuffer')).body as ArrayBuffer;
+            let bytes = new Uint8Array(body);
+            if (this.supports_native_font_loading) {
+                data = bytes; // use raw binary data
+            }
+            else {
+                let str = '';
+                for (let i = 0; i < bytes.length; i++) {
+                    str += String.fromCharCode(bytes[i]);
+                }
+                data = 'data:font/opentype;base64,' + btoa(str); // base64 encode as data URL
+            }
+        }
+
+        if (this.supports_native_font_loading) {
+            // Use native FontFace API
+            let face;
+            if (typeof data === 'string') { // add as URL
+                face = new FontFace(family, `url(${encodeURI(data)})`, {weight: weight == null ? undefined : String(weight), style});
+            }
+            else if (data instanceof Uint8Array) { // add as binary data
+                face = new FontFace(family, data.buffer as ArrayBuffer, {weight: weight == null ? undefined : String(weight), style});
+            }
+            if (!face) {
+                return;
+            }
+            document.fonts.add(face);
+            log('trace', 'Adding FontFace to document.fonts:', face);
+        }
+        else {
+            // Use CSS injection
+            if (typeof data !== 'string') {
+                return;
+            }
+            let css = `
+                @font-face {
+                    font-family: '${family}';
+                    font-weight: ${weight || 'normal'};
+                    font-style: ${style || 'normal'};
+                    src: url(${encodeURI(data)});
+                }`;
+            let style_el = document.createElement('style');
+            style_el.appendChild(document.createTextNode(''));
+            document.head.appendChild(style_el);
+            style_el.sheet?.insertRule(css, 0);
+            log('trace', 'Injecting CSS font face:', css);
+        }
+    }
+
+};
+
+export default FontManager;

package/src/styles/text/fontfaceobserver.d.ts

@@ -0,0 +1,10 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+declare module 'fontfaceobserver' {
+    export default class FontFaceObserver {
+        constructor (family: string, options?: Record<string, unknown>);
+        load (): Promise<void>;
+    }
+}

package/src/styles/text/text-types.ts

@@ -0,0 +1,220 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {CollisionObject} from '../../labels/collision-types';
+import type {LabelLayout, LabelPointCoordinate} from '../../labels/label-types';
+import type LabelPoint from '../../labels/label_point';
+import type LabelLine from '../../labels/label_line';
+import type TextCanvas from './text_canvas';
+import type {TextDraw, TextSettingsResult} from './text_settings';
+import type {TaskRecord} from '../../utils/task';
+import type {PropertyCache} from '../property-types';
+
+/** Labels submitted by standalone text and attached point text. */
+export type TextRenderLabel = LabelPoint | Exclude<ReturnType<typeof LabelLine.create>, false>;
+
+/** Tile metadata needed for text placement and cancellation. */
+export interface TextTile {
+    id: string;
+    key: string;
+    generation: number;
+    canceled?: boolean;
+    overzoom2: number;
+    units_per_pixel?: number;
+}
+
+/** Supported tile-local feature geometry. */
+export type TextGeometry =
+    | {type: 'Point'; coordinates: LabelPointCoordinate}
+    | {type: 'MultiPoint' | 'LineString'; coordinates: LabelPointCoordinate[]}
+    | {type: 'MultiLineString' | 'Polygon'; coordinates: LabelPointCoordinate[][]}
+    | {type: 'MultiPolygon'; coordinates: LabelPointCoordinate[][][]};
+
+/** Feature passed to text-source callbacks and label placement. */
+export interface TextFeature {
+    /** Stable optional source identity, shared by buffered tile copies. */
+    id?: string | number;
+    geometry: TextGeometry;
+    properties: Record<string, TextValue>;
+}
+
+/** Legacy text sources may return numeric/falsy values as well as strings. */
+export type TextValue = string | number | boolean | null | undefined;
+
+/** Evaluation context supplied to dynamic style properties. */
+export interface TextContext {
+    tile: TextTile;
+    geometry: string;
+    layer?: string;
+    [property: string]: unknown;
+}
+
+/** Property lookup or dynamic text callback, with optional fallbacks. */
+export type TextSourceValue = string | ((context: TextContext) => TextValue);
+/** Single source, ordered fallbacks, or named boundary-label sources. */
+export type TextSource = TextSourceValue | TextSourceValue[] | Record<string, TextSourceValue | TextSourceValue[]>;
+
+/** Text draw properties before/after property-cache preprocessing. */
+export interface TextLabelDraw extends TextDraw {
+    /** Standalone projected text altitude, cached in physical meters after preprocessing. */
+    z?: PropertyCache;
+    /** Internal scene draw-group identity, used to keep independent annotations separate. */
+    key?: string;
+    /** Enable collision placement; projected annotations resolve it in screen space. */
+    collide?: boolean | ((context: TextContext) => boolean);
+    text_source?: TextSource;
+    offset?: unknown;
+    buffer?: unknown;
+    repeat_distance?: unknown;
+    repeat_group?: string | ((context: TextContext) => string);
+    align?: string;
+    blend_order?: number;
+}
+
+/** Parsed text candidate, before its feature and geometry are queued. */
+export interface ParsedTextFeature {
+    draw: TextLabelDraw;
+    text: string;
+    text_settings_key: string;
+    layout: LabelLayout;
+    feature?: TextFeature;
+    context?: TextContext;
+}
+
+/** Complete feature queue entry supplied by a rendering style. */
+export interface TextFeatureQueue extends ParsedTextFeature {
+    feature: TextFeature;
+    context: TextContext;
+}
+
+/** Collision container retaining text/style/feature information. */
+export interface TextLabelCandidate extends TextFeatureQueue, CollisionObject {
+    label: TextRenderLabel;
+}
+
+/** Measured canvas line; structural to avoid exposing the private wrapper class. */
+export interface TextLine {
+    text: string;
+    width: number;
+    height: number;
+}
+
+/** Logical/collision sizes and device-pixel atlas dimensions. */
+export interface TextSize {
+    collision_size: LabelPointCoordinate;
+    texture_size: LabelPointCoordinate;
+    logical_size: LabelPointCoordinate;
+    horizontal_buffer: number;
+    vertical_buffer: number;
+    dpr: number;
+    line_height: number;
+    background_size: number;
+}
+
+/** Cached measurement, including wrapped lines. */
+export interface TextMeasurement {
+    lines: TextLine[];
+    size: TextSize;
+}
+
+/** Packed sprite coordinates and owning atlas index. */
+export interface TextSprite {
+    texture_id: number;
+    texcoord: number[];
+}
+
+/** Point alignment populated during packing, then rasterization. */
+export interface TextAlignment {
+    texture_id?: number;
+    texture_position?: LabelPointCoordinate;
+    texcoords?: number[];
+}
+
+/** One unique text/style record, progressively measured and rasterized. */
+export interface TextInfo {
+    text_settings: TextSettingsResult;
+    ref: number;
+    size?: TextSize;
+    segment_sizes?: TextSize[];
+    segments?: string[];
+    isRTL?: boolean;
+    no_curving?: boolean;
+    vertical_buffer?: number;
+    align?: Record<string, TextAlignment>;
+    type?: string[];
+    textures?: (number | number[])[];
+    texcoords?: {straight?: TextSprite; curved?: TextSprite[]};
+    texcoords_stroke?: number[][];
+}
+
+/** Unique strings indexed first by style key and then by original text. */
+export type TextTable = Record<string, Record<string, TextInfo>>;
+
+/** Per-word atlas cache shared by straight and curved rasterization. */
+export interface TextSpriteCache {
+    texture_id: number;
+    texture_position: LabelPointCoordinate;
+    texcoord?: number[];
+    texcoord_stroke?: number[];
+}
+
+/** Single atlas produced by the packing pass. */
+export interface TextAtlas {
+    texture_size: LabelPointCoordinate;
+    texcoord_cache: Record<string, Record<string, TextSpriteCache>>;
+}
+
+/** Mutable column-packing cursor. */
+export interface TextAtlasCursor {
+    cx: number;
+    cy: number;
+    width: number;
+    height: number;
+    column_width: number;
+    texture_id: number;
+    texcoord_cache: TextAtlas['texcoord_cache'];
+}
+
+/** Cooperative text measurement/rasterization progress. */
+export interface TextTaskCursor {
+    styles: string[];
+    texts: string[] | null;
+    style_idx: number | null;
+    text_idx: number | null;
+}
+
+/** Measurement task payload carried by the generic scheduler. */
+export interface TextSizesTask extends TaskRecord<TextTable> {
+    texts: TextTable;
+    cursor: TextTaskCursor;
+}
+
+/** Raster task payload, retaining names for cancellation cleanup. */
+export interface TextRasterTask extends TaskRecord<string[]> {
+    texts: TextTable;
+    textures: TextAtlas[];
+    texture_prefix: string;
+    resource_context: unknown;
+    cursor: TextTaskCursor & {
+        texture_idx: number;
+        texture_resize: boolean;
+        texture_names: string[];
+    };
+}
+
+/** Shared style state required by the text-label mixin. */
+export interface TextLabelState {
+    /** Host-driven billboard candidates remain available until every eye is known. */
+    screen_space_labels?: boolean;
+    /** Projected candidates must bypass worker-local Mercator repeat culling. */
+    cpu_projection?: import('../../procedures/mesh-projector').ProjectedBasemapOptions;
+    name: string;
+    main_thread_target: string;
+    max_texture_size: number;
+    resource_context: unknown;
+    canvas: TextCanvas;
+    texts: Record<string, TextTable>;
+    computeLayout(target: Partial<LabelLayout>, feature: TextFeature, draw: TextLabelDraw, context: TextContext, tile: TextTile): LabelLayout;
+    buildTextLabels(tile: TextTile, queue: TextFeatureQueue[]): TextLabelCandidate[];
+}