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

package/src/styles/text/text_settings.ts

@@ -0,0 +1,228 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import Utils from '../../utils/utils';
+import StyleParser from '../style_parser';
+
+type TextColorValue = unknown;
+
+interface TextFontStroke {
+    color?: TextColorValue;
+    alpha?: TextColorValue;
+    width?: TextColorValue;
+}
+
+interface TextFontBackground {
+    color?: TextColorValue;
+    alpha?: TextColorValue;
+    width?: TextColorValue;
+    stroke?: TextFontStroke;
+}
+
+interface TextFont {
+    fill?: TextColorValue;
+    alpha?: TextColorValue;
+    stroke?: TextFontStroke;
+    underline?: boolean;
+    background?: TextFontBackground;
+    weight?: TextColorValue;
+    family?: string;
+    style?: string;
+    transform?: string;
+    px_size?: TextColorValue;
+    size?: TextColorValue;
+}
+
+export interface TextDraw {
+    font?: TextFont;
+    supersample_text?: boolean;
+    can_articulate?: boolean;
+    text_wrap?: boolean | number;
+    max_lines?: number;
+}
+
+export interface TextSettingsResult {
+    style?: string;
+    weight?: string | number;
+    px_size?: number;
+    family?: string;
+    fill?: string;
+    stroke?: string;
+    stroke_width?: number;
+    underline_width?: number;
+    background_color?: string;
+    background_width?: number;
+    background_stroke_color?: string;
+    background_stroke_width?: number;
+    transform?: string;
+    text_wrap?: boolean | number;
+    max_lines?: number;
+    supersample: number;
+    can_articulate?: boolean;
+    font_css?: string;
+}
+
+interface TextSettingsContext {
+    [key: string]: unknown;
+}
+
+interface StyleParserApi {
+    zeroPair: readonly [number, number];
+    evalCachedProperty(value: unknown, context: unknown): unknown;
+    evalCachedColorPropertyWithAlpha(value: unknown, alpha: unknown, context: unknown): number[] | false | null | undefined;
+}
+
+const typedStyleParser = StyleParser as unknown as StyleParserApi;
+
+function toCssColor(value: number[] | false | null | undefined): string | undefined {
+    return Array.isArray(value) ? Utils.toCSSColor(value) : undefined;
+}
+
+const TextSettings = {
+
+    // A key for grouping all labels of the same text style (e.g. same Canvas state, to minimize state changes)
+    key (settings: TextSettingsResult): string {
+        return [
+            settings.style,
+            settings.weight,
+            settings.family,
+            settings.px_size,
+            settings.fill,
+            settings.stroke,
+            settings.stroke_width,
+            settings.underline_width,
+            settings.background_color,
+            settings.background_width,
+            settings.background_stroke_color,
+            settings.background_stroke_width,
+            settings.transform,
+            settings.text_wrap,
+            settings.max_lines,
+            settings.supersample,
+            Utils.device_pixel_ratio
+        ].join('/');
+    },
+
+    defaults: {
+        style: 'normal',
+        weight: 'normal',
+        size: '12px',
+        px_size: 12,
+        family: 'Helvetica',
+        fill: [1, 1, 1, 1],
+        text_wrap: 15,
+        max_lines: 5,
+        align: 'center'
+    },
+
+    compute (draw: TextDraw, context: TextSettingsContext): TextSettingsResult {
+        const style: TextSettingsResult = {supersample: 1};
+
+        draw.font = draw.font || this.defaults;
+
+        style.supersample = draw.supersample_text ? 1.5 : 1; // optionally render text at 150% to improve clarity
+
+        // LineString labels can articulate while point labels cannot. Needed for future texture coordinate calculations.
+        style.can_articulate = draw.can_articulate;
+
+        // Text fill
+        const fillColor = typedStyleParser.evalCachedColorPropertyWithAlpha(draw.font.fill, draw.font.alpha, context);
+        style.fill = toCssColor(fillColor); // convert to CSS for Canvas
+
+        // Text stroke
+        if (draw.font.stroke && draw.font.stroke.color) {
+            style.stroke = toCssColor(typedStyleParser.evalCachedColorPropertyWithAlpha(draw.font.stroke.color, draw.font.stroke.alpha, context)); // convert to CSS for Canvas
+            style.stroke_width = typedStyleParser.evalCachedProperty(draw.font.stroke.width, context) as number;
+        }
+
+        // Text underline
+        if (draw.font.underline === true && !style.can_articulate) {
+            style.underline_width = 1.5 * style.supersample;
+        }
+
+        // Background box
+        if (draw.font.background && !style.can_articulate) { // supported for point labels only
+            // Background fill
+            style.background_color = toCssColor(typedStyleParser.evalCachedColorPropertyWithAlpha(draw.font.background.color, draw.font.background.alpha, context)); // convert to CSS for Canvas
+            if (style.background_color) {
+                style.background_width = typedStyleParser.evalCachedProperty(draw.font.background.width, context) as number;
+            }
+
+            // Background stroke
+            const backgroundStroke = draw.font.background.stroke;
+            const backgroundStrokeColor = backgroundStroke?.color != null ?
+                typedStyleParser.evalCachedColorPropertyWithAlpha(backgroundStroke.color, backgroundStroke.alpha, context) :
+                undefined;
+            style.background_stroke_color = toCssColor(backgroundStrokeColor);
+            if (style.background_stroke_color) {
+                // default background stroke to 1px when stroke color but no stroke width specified
+                style.background_stroke_width = backgroundStroke?.width != null ?
+                    typedStyleParser.evalCachedProperty(backgroundStroke.width, context) as number : 1;
+            }
+        }
+
+        // Font properties are modeled after CSS names:
+        // - family: Helvetica, Futura, etc.
+        // - size: in pt, px, or em
+        // - style: normal, italic, oblique
+        // - weight: normal, bold, etc.
+        // - transform: capitalize, uppercase, lowercase
+
+        // clamp weight to 1-1000 (see https://drafts.csswg.org/css-fonts-4/#valdef-font-weight-number)
+        style.weight = typedStyleParser.evalCachedProperty(draw.font.weight, context) as string | number || this.defaults.weight;
+        if (typeof style.weight === 'number') {
+            style.weight = Math.min(Math.max(style.weight, 1), 1000);
+        }
+
+        if (draw.font.family) {
+            style.family = draw.font.family;
+            if (style.family !== this.defaults.family) {
+                style.family += ', ' + this.defaults.family;
+            }
+        }
+        else {
+            style.family = this.defaults.family;
+        }
+
+        style.style = draw.font.style || this.defaults.style;
+        style.transform = draw.font.transform;
+
+        // calculated pixel size
+        style.px_size = (typedStyleParser.evalCachedProperty(draw.font.px_size, context) as number) * style.supersample;
+
+        style.font_css = this.fontCSS(style);
+
+        // Word wrap and text alignment
+        // Not a font properties, but affect atlas of unique text textures
+        let text_wrap = draw.text_wrap; // use explicitly set value
+
+        if (text_wrap == null && !style.can_articulate) {
+            // point labels (for point and polygon features) have word wrap on w/default max length,
+            // line labels default off
+            text_wrap = true;
+        }
+
+        // setting to 'true' causes default wrap value to be used
+        if (text_wrap === true) {
+            text_wrap = this.defaults.text_wrap;
+        }
+        style.text_wrap = text_wrap;
+
+        // max_lines setting to truncate very long labels with an ellipsis
+        style.max_lines = draw.max_lines || this.defaults.max_lines;
+
+        return style;
+    },
+
+    // Build CSS-style font string (to set Canvas draw state)
+    fontCSS ({style, weight, px_size, family}: TextSettingsResult): string {
+        return [style, weight, px_size + 'px', family]
+            .filter(x => x) // remove null props
+            .join(' ');
+    }
+
+};
+
+export default TextSettings;

package/src/styles/text/text_wgsl.ts

@@ -0,0 +1,159 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {GLOBE_PROJECTION_WGSL, TERRAIN_DRAPING_WGSL} from '../../scene/projection_shaders';
+import {GLOBE_VISIBILITY_WGSL} from '../globe_visibility_wgsl';
+
+const PI = Math.PI;
+
+/**
+ * Build the portable standalone-text shader used by the luma.gl WebGPU renderer.
+ *
+ * Text quads retain Tangram's CPU collision, atlas, and curved-label geometry.
+ * The shader applies the buffered screen-space shape and samples the luma-owned
+ * atlas texture without reading a backend texture handle.
+ *
+ * @param cpuProjection Use preprojected ground anchors for screen-laid-out annotations.
+ * @param selection Emit the worker selection key for visible atlas pixels.
+ * @param terrain Add physical terrain height/morph attributes to the anchor.
+ * @returns {string} Complete WGSL source for Tangram's text style.
+ */
+export function buildTextWGSL(cpuProjection = false, selection = false, terrain = false) {
+    return `
+@group(0) @binding(3) var u_texture: texture_2d<f32>;
+@group(0) @binding(4) var u_textureSampler: sampler;
+${GLOBE_PROJECTION_WGSL}
+${terrain ? TERRAIN_DRAPING_WGSL : ''}
+${GLOBE_VISIBILITY_WGSL}
+
+struct TextAttributes {
+    ${terrain ? '@location(14) a_terrain: vec4<f32>, @location(15) a_terrain_previous: vec4<f32>,' : ''}
+    @location(0) a_position: vec4<${terrain ? 'f32' : 'i32'}>,
+    @location(1) a_shape: vec4<i32>,
+    @location(2) a_texcoord: vec2<f32>,
+    @location(3) a_offset: vec2<i32>,
+    @location(4) a_color: vec4<f32>,
+    ${selection ? '@location(5) a_selection_color: vec4<f32>,' : ''}
+    @location(6) a_pre_angles: vec4<i32>,
+    @location(7) a_angles: vec4<i32>,
+    @location(8) a_offsets: vec4<u32>,
+    ${cpuProjection ? '@location(9) a_projected_position: vec3<f32>,' : ''}
+};
+
+struct TextVaryings {
+    @builtin(position) position: vec4<f32>,
+    @location(0) texcoord: vec2<f32>,
+    @location(1) color: vec4<f32>,
+    ${selection ? '@location(2) @interpolate(flat) selection_color: vec4<f32>,' : ''}
+};
+
+fn rotate2D(point: vec2<f32>, angle: f32) -> vec2<f32> {
+    let cosine = cos(angle);
+    let sine = sin(angle);
+    return vec2<f32>(
+        cosine * point.x - sine * point.y,
+        sine * point.x + cosine * point.y
+    );
+}
+
+fn mix4Linear(values: vec4<f32>, amount: f32) -> f32 {
+    let clamped_amount = clamp(amount, 0.0, 1.0);
+    let first_segment = mix(values.x, values.y, 3.0 * clamped_amount);
+    let last_segment = mix(
+        values.z,
+        values.w,
+        3.0 * (max(clamped_amount, 0.66) - 0.66)
+    );
+    let remaining_segments = mix(
+        values.y,
+        last_segment,
+        3.0 * (clamp(clamped_amount, 0.33, 0.66) - 0.33)
+    );
+    return select(first_segment, remaining_segments, clamped_amount >= 0.33);
+}
+
+@vertex
+fn vertexMain(attributes: TextAttributes) -> TextVaryings {
+    var output: TextVaryings;
+    ${selection ? 'output.selection_color = attributes.a_selection_color;' : ''}
+    output.texcoord = vec2<f32>(
+        attributes.a_texcoord.x,
+        1.0 - attributes.a_texcoord.y
+    );
+    output.color = attributes.a_color;
+
+    if (attributes.a_shape.w == 0) {
+        output.position = vec4<f32>(2.0, 2.0, 2.0, 1.0);
+        return output;
+    }
+
+    var shape = vec2<f32>(attributes.a_shape.xy) / 256.0;
+    let offset = vec2<f32>(
+        f32(attributes.a_offset.x),
+        -f32(attributes.a_offset.y)
+    );
+    let theta = f32(attributes.a_shape.z) / 4096.0;
+
+    if (attributes.a_offsets.x != 0u) {
+        let zoom = clamp(
+            TangramView.u_map_position.z - TangramTile.u_tile_origin.z,
+            0.0,
+            1.0
+        );
+        let pre_angle = mix4Linear(
+            vec4<f32>(attributes.a_pre_angles) * (${PI} / 128.0),
+            zoom
+        );
+        let curve_angle = mix4Linear(
+            vec4<f32>(attributes.a_angles) * (${PI} / 16384.0),
+            zoom
+        );
+        let curve_offset = mix4Linear(
+            vec4<f32>(attributes.a_offsets) / 64.0,
+            zoom
+        );
+        shape = rotate2D(shape, pre_angle);
+        shape = vec2<f32>(shape.x + curve_offset, shape.y);
+        shape = rotate2D(shape, curve_angle);
+        shape += rotate2D(offset, theta);
+    }
+    else {
+        shape = rotate2D(shape + offset, theta);
+    }
+
+    let local_position = vec4<f32>(
+        f32(attributes.a_position.x),
+        f32(attributes.a_position.y),
+        f32(attributes.a_position.z) ${terrain ? '+ tangramTerrainHeight(attributes.a_terrain, attributes.a_terrain_previous)' : ''},
+        1.0
+    );
+    let projected_position = ${cpuProjection ? 'vec4<f32>(attributes.a_projected_position, 1.0)' : 'tangramModelView(local_position)'};
+    if (TangramView.u_projection_mode == 1 && tangramGlobeOccluded(projected_position.xyz,
+        (TangramTile.u_model * local_position).z, TangramCamera.u_eye)) {
+        output.position = vec4<f32>(2.0, 2.0, 2.0, 1.0);
+        return output;
+    }
+    var clip_position = TangramCamera.u_projection * projected_position;
+    ${cpuProjection ? 'clip_position.z = (clip_position.z + clip_position.w) * 0.5;' : ''}
+    let screen_offset = shape * clip_position.w * 2.0 *
+        TangramView.u_device_pixel_ratio / TangramView.u_resolution;
+    clip_position = vec4<f32>(
+        clip_position.xy + screen_offset,
+        clip_position.zw
+    );
+
+    output.position = clip_position;
+    return output;
+}
+
+@fragment
+fn fragmentMain(input: TextVaryings) -> @location(0) vec4<f32> {
+    var atlas_color = textureSample(u_texture, u_textureSampler, input.texcoord);
+    ${selection ? 'if (atlas_color.a < 0.001) { discard; }\n    return input.selection_color;' : `return vec4<f32>(
+        atlas_color.rgb / max(atlas_color.a, 0.001),
+        atlas_color.a
+    );`}
+}
+`;
+}

package/src/styles/text/text_wrap.ts

@@ -0,0 +1,194 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+
+// Word wrapping
+
+import { isTextRTL, isTextNeutral, RTL_MARKER } from './text_segments';
+
+interface TextMeasurementContext {
+    measureText(text: string): {width: number};
+}
+
+// Private class to arrange text labels into multiple lines based on
+// "text wrap" and "max line" values
+export default class MultiLine {
+    static ellipsis: string;
+    width: number;
+    height: number;
+    lines: Line[];
+    max_lines: number;
+    text_wrap: number | boolean;
+    context: TextMeasurementContext;
+
+    constructor (context: TextMeasurementContext, max_lines = Infinity, text_wrap: number | boolean = Infinity) {
+        this.width = 0;
+        this.height = 0;
+        this.lines = [];
+
+        this.max_lines = max_lines;
+        this.text_wrap = text_wrap;
+        this.context = context;
+    }
+
+    createLine (line_height: number): Line | false {
+        if (this.lines.length < this.max_lines){
+            return new Line(line_height, this.text_wrap);
+        }
+        else {
+            return false;
+        }
+    }
+
+    push (line: Line): boolean {
+        if (this.lines.length < this.max_lines){
+            // measure line width
+            let line_width = this.context.measureText(line.text).width;
+            line.width = line_width;
+
+            if (line_width > this.width){
+                this.width = Math.ceil(line_width);
+            }
+
+            // add to lines and increment height
+            this.lines.push(line);
+            this.height += line.height;
+            return true;
+        }
+        else {
+            this.addEllipsis();
+            return false;
+        }
+    }
+
+    // pushes to the lines array and returns a new line if possible (false otherwise)
+    advance (line: Line, line_height: number): Line | false {
+        let can_push = this.push(line);
+        if (can_push){
+            return this.createLine(line_height);
+        }
+        else {
+            return false;
+        }
+    }
+
+    addEllipsis (): void {
+        let last_line = this.lines[this.lines.length - 1];
+        let ellipsis_width = Math.ceil(this.context.measureText(MultiLine.ellipsis).width);
+
+        last_line.append(MultiLine.ellipsis);
+        last_line.width += ellipsis_width;
+
+        if (last_line.width > this.width) {
+            this.width = last_line.width;
+        }
+    }
+
+    finish (line: Line | false): void {
+        if (line){
+            this.push(line);
+        }
+        else {
+            this.addEllipsis();
+        }
+    }
+
+    static parse (
+        str: string,
+        text_wrap: boolean | number,
+        max_lines: number,
+        line_height: number,
+        ctx: TextMeasurementContext
+    ): MultiLine {
+        // Word wrapping
+        // Line breaks can be caused by:
+        //  - implicit line break when a maximum character threshold is exceeded per line (text_wrap)
+        //  - explicit line break in the label text (\n)
+        let words;
+        if (typeof text_wrap === 'number') {
+            words = str.split(' '); // split words on spaces
+        }
+        else {
+            words = [str]; // no max line word wrapping (but new lines will still be in effect)
+        }
+
+        let multiline = new MultiLine(ctx, max_lines, text_wrap);
+        let line = multiline.createLine(line_height);
+
+        // First iterate on space-break groups (will be one if max line length off), then iterate on line-break groups
+        for (let i = 0; i < words.length; i++) {
+            let breaks = words[i].split('\n'); // split on line breaks
+            let new_line = (i === 0) ? true : false;
+
+            for (let n=0; n < breaks.length; n++) {
+                if (!line){
+                    break;
+                }
+
+                let word = breaks[n];
+
+                // force punctuation (neutral chars) at the end of a RTL line, so they stay attached to original word
+                if (isTextRTL(word) && isTextNeutral(word[word.length - 1])) {
+                    word += RTL_MARKER;
+                }
+
+                let spaced_word = (new_line) ? word : ' ' + word;
+
+                // if adding current word would overflow, add a new line instead
+                // first word (i === 0) always appends
+                if (text_wrap && i > 0 && line.exceedsTextwrap(spaced_word)) {
+                    line = multiline.advance(line, line_height);
+                    if (!line){
+                        break;
+                    }
+                    line.append(word);
+                    new_line = true;
+                }
+                else {
+                    line.append(spaced_word);
+                }
+
+                // if line breaks present, add new line (unless on last line)
+                if (n < breaks.length - 1) {
+                    line = multiline.advance(line, line_height);
+                    new_line = true;
+                }
+            }
+
+            if (i === words.length - 1){
+                multiline.finish(line);
+            }
+        }
+        return multiline;
+    }
+}
+
+MultiLine.ellipsis = '...';
+
+// A Private class used by MultiLine to contain the logic for a single line
+// including character count, width, height and text
+class Line {
+    chars: number;
+    text: string;
+    width: number;
+    height: number;
+    text_wrap: number | boolean;
+
+    constructor (height = 0, text_wrap: number | boolean = 0){
+        this.chars = 0;
+        this.text = '';
+        this.width = 0;
+
+        this.height = Math.ceil(height);
+        this.text_wrap = text_wrap;
+    }
+
+    append (text: string): void {
+        this.chars += text.length;
+        this.text += text;
+    }
+
+    exceedsTextwrap (text: string): boolean {
+        return typeof this.text_wrap === 'number' && text.length + this.chars > this.text_wrap;
+    }
+}

package/src/tile/globe_tile_preload.ts

@@ -0,0 +1,40 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {TileID, type TileCoordinate, type TileCoordinates, type TileSource} from './tile_id';
+import Geo from '../utils/geo';
+
+/** Enumerate one bounded global level, independent of camera or hemisphere. */
+export function createGlobePreloadCoordinates(zoom: number): TileCoordinate[] {
+    if (!Number.isInteger(zoom) || zoom < 0 || zoom > 3) {
+        throw new Error('Globe preload zoom must be an integer from 0 to 3');
+    }
+    const coordinates: TileCoordinate[] = [];
+    for (let x = 0; x < 2 ** zoom; x++) {
+        for (let y = 0; y < 2 ** zoom; y++) coordinates.push(TileID.coord({x, y, z: zoom}));
+    }
+    return coordinates;
+}
+
+/** Resolve a coarse ancestor without expanding a source's minimum zoom into global high-detail requests. */
+export function getGlobePreloadKey(coordinates: TileCoordinates, source: TileSource, styleZoom: number, zoom: number): string | undefined {
+    const normalized = TileID.normalizedCoord(TileID.coordAtZoom(coordinates, zoom), source);
+    if (normalized.z > zoom) return undefined;
+    return TileID.key(normalized, source, styleZoom);
+}
+
+/** Clip a fallback mesh in its local packed tile units to one missing detail tile. */
+export function getGlobeFallbackClipBounds(parent: TileCoordinates, child: TileCoordinates): [number, number, number, number] {
+    const scale = 2 ** (child.z - parent.z);
+    const width = Geo.tile_scale / scale;
+    const horizontal = child.x - parent.x * scale;
+    const vertical = child.y - parent.y * scale;
+    return [horizontal * width, -(vertical + 1) * width, (horizontal + 1) * width, vertical === 0 ? 0 : -vertical * width];
+}
+
+/** Only surface geometry can be drawn as a clipped loading placeholder. */
+export function isGlobeFallbackStyle(name: string, base?: string | null): boolean {
+    const style = base || name;
+    return style === 'polygons' || style === 'lines' || style === 'raster';
+}