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

package/src/labels/projected-pass.ts

@@ -0,0 +1,259 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Matrix4} from '@math.gl/core';
+import type HostFrame from '../scene/host_frame';
+import type {LabelMesh, LabelTile, MeshLabel} from './main-pass-types';
+import {getGeographicProjectionProcedure, PROJECTION_CONSTANTS, projectGeographicPosition} from '../scene/projection_math';
+import {resolveLabelPlacement} from '../map-logic/label-placement';
+import type {ScreenLabelCandidate} from '../map-logic/label-placement';
+import {areGeographicLabelCopies} from '../map-logic/label-identity';
+import type {GeographicLabelAnchor} from '../map-logic/label-identity';
+import {unionScreenBounds as unionBounds} from '../map-logic/screen-bounds';
+import type {ScreenBounds} from '../map-logic/screen-bounds';
+import type {TerrainSurfaceCollection} from '../selection/terrain_surface';
+
+/** Settled surfaces retain only one eye signature and a bounded set of exact anchor results. */
+const terrainVisibility = new WeakMap<TerrainSurfaceCollection, {eyes: string; results: Map<string, boolean>}>();
+
+type Bounds = ScreenBounds;
+/** One worker identity may have multiple atlas/outline mesh ranges. */
+interface Candidate extends ScreenLabelCandidate, GeographicLabelAnchor {
+    id: string;
+    label: MeshLabel;
+    tile: LabelTile;
+    parts: {mesh: LabelMesh; label: MeshLabel}[];
+    boxes: Map<string, Bounds>;
+    anchor: [number, number];
+    height: number;
+}
+/** Immutable domain eligibility must survive later hide/show writes. */
+const eligible = new WeakMap<LabelMesh, Map<MeshLabel, boolean>>();
+
+/**
+ * Lay out projected billboard candidates in CSS pixels before either eye draws.
+ * One shared mask is collision-free in every eye, avoiding GPU buffer mutations
+ * between queued stereo draws. Worker snapshots and source geometry stay immutable.
+ * @returns Whether masks changed or pending label meshes were activated.
+ */
+export function layoutProjectedAnnotations(tiles: readonly LabelTile[], frame: HostFrame,
+    {clockwiseRotation = false, terrainExaggeration = 1, terrainTransitionDuration = 0, terrainTime = performance.now(), terrainSurface}: {
+        clockwiseRotation?: boolean;
+        /** Same visual relief multiplier used by the terrain vertex shaders. */
+        terrainExaggeration?: number;
+        /** Per-mesh transition duration in milliseconds, matching the renderer. */
+        terrainTransitionDuration?: number;
+        /** Shared monotonic frame time, so both eyes and color agree during morphing. */
+        terrainTime?: number;
+        /** Exact ground generation about to draw; missing triangles never certify occlusion. */
+        terrainSurface?: TerrainSurfaceCollection;
+    } = {}): boolean {
+    let terrainCache = terrainSurface && terrainVisibility.get(terrainSurface);
+    const eyeSignature = frame.renderViews.map(view => `${view.id}/${view.camera.position.join(',')}/${Array.from(view.camera.view).join(',')}/${Array.from(view.camera.projection).join(',')}`).join(';');
+    if (terrainSurface && terrainCache?.eyes !== eyeSignature) {
+        terrainCache = {eyes: eyeSignature, results: new Map()}; terrainVisibility.set(terrainSurface, terrainCache);
+    }
+    const cameras = frame.renderViews.map(eye => {
+        const matrix = frame.projection.type === 'globe' ? new Matrix4(Array.from(eye.camera.projection)) :
+            new Matrix4(Array.from(eye.camera.projection)).multiplyRight(Array.from(eye.camera.view));
+        return {eye, matrix, inverse: terrainSurface ? invertFrameMatrix(matrix) : undefined};
+    });
+    const candidates = new Map<string, Candidate>();
+    for (const tile of tiles) {
+        const meshes = {...tile.meshes, ...tile.pending_label_meshes};
+        for (const [style, parts] of Object.entries(meshes)) {
+            // A resident proxy may no longer draw this style once its child labels are ready.
+            if (tile.isProxy() && tile.shouldProxyForStyle?.(style) === false) continue;
+            for (const mesh of parts) {
+                if (!mesh.valid || !mesh.labels || !mesh.vertex_data || !mesh.vertex_layout.offset || mesh.vertex_layout.offset.a_shape === undefined ||
+                    (mesh.vertex_layout.offset.a_projected_position === undefined && mesh.vertex_layout.offset.a_position === undefined)) continue;
+                for (const label of Object.values(mesh.labels)) {
+                    const id = String(label.container.label.id);
+                    let candidate = candidates.get(id);
+                    if (!candidate) {
+                        const position = label.container.label.position;
+                        const unitsPerMeter = 4096 * 2 ** tile.coords.z / (2 * Math.PI * 6378137);
+                        const first = label.ranges[0]?.[0];
+                        const data = new DataView(mesh.vertex_data.buffer, mesh.vertex_data.byteOffset, mesh.vertex_data.byteLength);
+                        const height = label.container.label.layout.projected_height ?? (first === undefined ||
+                            mesh.vertex_layout.offset.a_position === undefined ? 0 : (mesh.vertex_layout.offset.a_terrain === undefined ? data.getInt16(first + mesh.vertex_layout.offset.a_position + 4, true) : data.getFloat32(first + mesh.vertex_layout.offset.a_position + 8, true)));
+                        const layout = label.container.label.layout;
+                        candidate = {id, label, tile, parts: [], boxes: new Map(), height,
+                            linkedId: String(label.container.linked), collide: layout.projected_collide,
+                            identity: layout.projected_identity, repeatGroup: layout.repeat_group, repeatDistance: layout.repeat_distance,
+                            sourceTileIdentity: tile, sourceZoom: tile.coords.z, anchor: [
+                            tile.min.x + position[0] / unitsPerMeter, tile.min.y + position[1] / unitsPerMeter]};
+                        candidates.set(id, candidate);
+                    }
+                    candidate.parts.push({mesh, label});
+                    for (const {eye, matrix, inverse} of cameras) {
+                        const box = getScreenBounds(mesh, label, tile, frame, eye.camera.position, matrix,
+                            eye.viewport.width, eye.viewport.height, clockwiseRotation, terrainExaggeration, terrainTransitionDuration, terrainTime, terrainSurface, terrainCache?.results, inverse, eye.id);
+                        if (box) candidate.boxes.set(eye.id, unionBounds(candidate.boxes.get(eye.id), box));
+                    }
+                }
+            }
+        }
+    }
+    const sorted = [...candidates.values()].sort((left, right) =>
+        left.label.container.label.layout.priority - right.label.container.label.layout.priority ||
+        left.tile.build_id - right.tile.build_id || Number(left.id) - Number(right.id));
+    const visibility = resolveLabelPlacement(sorted, {
+        viewports: new Map(frame.renderViews.map(eye => [eye.id, eye.viewport])),
+        isDuplicate: (candidate, previous) => areGeographicLabelCopies(candidate, previous, {
+            worldWidth: 2 * Math.PI * PROJECTION_CONSTANTS.mercatorRadius,
+            wrapHorizontal: frame.projection.type === 'globe'
+        })
+    });
+    const uploads = new Set<LabelMesh>();
+    for (const candidate of sorted) for (const {mesh, label} of candidate.parts) {
+        if (!mesh.vertex_data || !mesh.vertex_layout.offset) continue;
+        const view = new DataView(mesh.vertex_data.buffer, mesh.vertex_data.byteOffset, mesh.vertex_data.byteLength);
+        for (const [start, count] of label.ranges) for (let index = 0; index < count; index++) {
+            const offset = start + index * mesh.vertex_layout.stride + mesh.vertex_layout.offset.a_shape + 6;
+            const shown = visibility.get(candidate) && eligible.get(mesh)?.get(label) ? 1 : 0;
+            if (view.getInt16(offset, true) !== shown) {
+                view.setInt16(offset, shown, true);
+                uploads.add(mesh);
+            }
+        }
+    }
+    uploads.forEach(mesh => mesh.upload());
+    const pending = tiles.some(tile => tile.pending_label_meshes !== null);
+    tiles.forEach(tile => tile.swapPendingLabels());
+    return uploads.size > 0 || pending;
+}
+
+/** Reconstruct the shader's rotated pixel quad from retained packed geometry, including atlas ranges. */
+function getScreenBounds(mesh: LabelMesh, label: MeshLabel, tile: LabelTile, frame: HostFrame,
+    eye: readonly number[], matrix: Matrix4, width: number, height: number,
+    clockwiseRotation: boolean, terrainExaggeration: number, transitionDuration: number, terrainTime: number,
+    terrainSurface?: TerrainSurfaceCollection, terrainCache?: Map<string, boolean>, inverse?: Matrix4, eyeId?: string): Bounds | null {
+    let eligibility = eligible.get(mesh);
+    if (!eligibility) eligible.set(mesh, eligibility = new Map());
+    if (!mesh.vertex_data || !mesh.vertex_layout.offset) return null;
+    const data = new DataView(mesh.vertex_data.buffer, mesh.vertex_data.byteOffset, mesh.vertex_data.byteLength);
+    const {stride, offset} = mesh.vertex_layout;
+    const first = label.ranges[0]?.[0];
+    if (first === undefined) return null;
+    if (!eligibility.has(label)) eligibility.set(label, data.getInt16(first + offset.a_shape + 6, true) !== 0);
+    if (!eligibility.get(label)) return null;
+    let bounds: Bounds | undefined;
+    /** A billboard has constant clip depth; probe its rectangle, not only its geographic anchor. */
+    let clipDepth: number | undefined;
+    let anchorScreen: [number, number] | undefined;
+    for (const [start, count] of label.ranges) for (let index = 0; index < count; index++) {
+        const base = start + index * stride;
+        let anchor: [number, number, number];
+        if (offset.a_projected_position !== undefined) {
+            anchor = [data.getFloat32(base + offset.a_projected_position, true),
+                data.getFloat32(base + offset.a_projected_position + 4, true),
+                data.getFloat32(base + offset.a_projected_position + 8, true)];
+        } else {
+            const scale = 2 * Math.PI * PROJECTION_CONSTANTS.mercatorRadius / (4096 * 2 ** tile.coords.z);
+            anchor = offset.a_terrain === undefined ? [tile.min.x + data.getInt16(base + offset.a_position, true) * scale,
+                tile.min.y + data.getInt16(base + offset.a_position + 2, true) * scale,
+                data.getInt16(base + offset.a_position + 4, true)] : [
+                tile.min.x + data.getFloat32(base + offset.a_position, true) * scale,
+                tile.min.y + data.getFloat32(base + offset.a_position + 4, true) * scale,
+                data.getFloat32(base + offset.a_position + 8, true)];
+            if (offset.a_terrain !== undefined) {
+                if (data.getFloat32(base + offset.a_terrain + 12, true) < 0.5) return null;
+                mesh.terrainVisibleAt ??= terrainTime;
+                const duration = mesh.variant?.terrainTransitionDuration ?? transitionDuration;
+                const blend = duration ? Math.max(0, Math.min(1, (terrainTime - mesh.terrainVisibleAt) / duration)) : 1;
+                const current = data.getFloat32(base + offset.a_terrain, true);
+                const previous = data.getFloat32(base + offset.a_terrain_previous, true);
+                anchor[2] += (previous + (current - previous) * blend) * terrainExaggeration;
+            }
+            if (frame.projection.type === 'globe') {
+                anchor = projectGeographicPosition(getGeographicProjectionProcedure('web-mercator').unproject(anchor), 'globe');
+                if (isGlobeOccluded(anchor, eye)) return null;
+            }
+        }
+        const position = matrix.transform([...anchor, 1]);
+        if (position[3] <= 0 || position[2] < -position[3] || position[2] > position[3]) return null;
+        const depth = position[2] / position[3];
+        // Curved labels may have different anchors/depths. Unknown shared depth
+        // keeps them collision-eligible rather than pretending this is a quad.
+        clipDepth = clipDepth === undefined ? depth : clipDepth === depth ? depth : NaN;
+        anchorScreen = [(position[0] / position[3] + 1) * width / 2, (1 - position[1] / position[3]) * height / 2];
+        const shape = base + offset.a_shape;
+        // Retain the existing GLSL clockwise and WGSL counter-clockwise sprite conventions.
+        const angle = data.getInt16(shape + 4, true) / 4096 * (clockwiseRotation ? -1 : 1);
+        let point: [number, number] = [data.getInt16(shape, true) / 256, data.getInt16(shape + 2, true) / 256];
+        const displacement: [number, number] = offset.a_offset === undefined ? [0, 0] :
+            [data.getInt16(base + offset.a_offset, true), -data.getInt16(base + offset.a_offset + 2, true)];
+        if (offset.a_offsets !== undefined && data.getUint16(base + offset.a_offsets, true) !== 0) {
+            const zoom = Math.max(0, Math.min(1, frame.geographicAnchor.zoom - tile.style_z));
+            const preAngle = mixCurve(Array.from({length: 4}, (_, index) =>
+                data.getInt8(base + offset.a_pre_angles + index) * Math.PI / 128), zoom);
+            const curveAngle = mixCurve(Array.from({length: 4}, (_, index) =>
+                data.getInt16(base + offset.a_angles + index * 2, true) * Math.PI / 16384), zoom);
+            point = rotate(point, preAngle * (clockwiseRotation ? -1 : 1));
+            point[0] += mixCurve(Array.from({length: 4}, (_, index) => data.getUint16(base + offset.a_offsets + index * 2, true) / 64), zoom);
+            point = rotate(point, curveAngle * (clockwiseRotation ? -1 : 1));
+            const rotatedOffset = rotate(displacement, angle);
+            point = [point[0] + rotatedOffset[0], point[1] + rotatedOffset[1]];
+        } else point = rotate([point[0] + displacement[0], point[1] + displacement[1]], angle);
+        const screenX = (position[0] / position[3] + 1) * width / 2 + point[0];
+        const screenY = (1 - position[1] / position[3]) * height / 2 - point[1];
+        bounds = unionBounds(bounds, [screenX, screenY, screenX, screenY]);
+    }
+    if (!bounds) return null;
+    if (terrainSurface && terrainCache && inverse && anchorScreen && typeof clipDepth === 'number' && Number.isFinite(clipDepth)) {
+        const depth = clipDepth;
+        const probes = [[bounds[0], bounds[1]], [bounds[0], bounds[3]], [bounds[2], bounds[1]], [bounds[2], bounds[3]],
+            [(bounds[0] + bounds[2]) / 2, (bounds[1] + bounds[3]) / 2]];
+        const isBlocked = (x: number, y: number): boolean => {
+            const key = `${eyeId}/${width},${height}/${x},${y},${depth}`;
+            const cached = terrainCache.get(key);
+            if (cached !== undefined) return cached;
+            const horizontal = x / width * 2 - 1, vertical = 1 - y / height * 2;
+            const near = inverse.transform([horizontal, vertical, -1, 1]), target = inverse.transform([horizontal, vertical, depth, 1]);
+            const start: [number, number, number] = [near[0] / near[3], near[1] / near[3], near[2] / near[3]];
+            const end: [number, number, number] = [target[0] / target[3], target[1] / target[3], target[2] / target[3]];
+            const inset = terrainSurface.projection === 'globe' ? 0.25 * PROJECTION_CONSTANTS.globeRadius / PROJECTION_CONSTANTS.earthRadius : 0.25;
+            const hidden = [...start, ...end].every(Number.isFinite) && terrainSurface.intersectSegment(start, end, {startInset: inset, endInset: inset}) !== null;
+            if (terrainCache.size >= 10000) terrainCache.clear();
+            terrainCache.set(key, hidden); return hidden;
+        };
+        // This refinement may restore an anchor-hidden label, never hide one
+        // whose original anchor test was clear (including offset billboards).
+        const blocked = isBlocked(...anchorScreen) && probes.every(([x, y]) => isBlocked(x, y));
+        if (blocked) return null;
+    }
+    const buffer = label.container.label.layout.buffer ?? [0, 0];
+    bounds = [bounds[0] - buffer[0] - 1, bounds[1] - buffer[1] - 1,
+        bounds[2] + buffer[0] + 1, bounds[3] + buffer[1] + 1];
+    return bounds[2] < 0 || bounds[0] > width || bounds[3] < 0 || bounds[1] > height ? null : bounds;
+}
+
+/** Singular host matrices leave terrain visibility unknown rather than hiding annotations. */
+function invertFrameMatrix(matrix: Matrix4): Matrix4 | undefined {
+    try {return new Matrix4(matrix).invert();}
+    catch {return undefined;}
+}
+
+/** Mirror the production shader's finite eye-to-anchor sphere segment and f32 tolerance. */
+function isGlobeOccluded(position: readonly number[], eye: readonly number[]): boolean {
+    const radius = PROJECTION_CONSTANTS.globeRadius;
+    if (Math.hypot(...eye) <= radius) return false;
+    const segment = position.map((value, index) => value - eye[index]);
+    const squaredLength = segment.reduce((sum, value) => sum + value * value, 0);
+    if (squaredLength === 0) return false;
+    const amount = Math.max(0, Math.min(1, -eye.reduce((sum, value, index) => sum + value * segment[index], 0) / squaredLength));
+    const closest = eye.map((value, index) => value * (1 - amount) + position[index] * amount);
+    return closest.reduce((sum, value) => sum + value * value, 0) / radius ** 2 < 1 - 1e-6;
+}
+/** Apply the same clockwise GLSL or counterclockwise WGSL billboard convention. */
+function rotate(point: readonly [number, number], angle: number): [number, number] {
+    return [point[0] * Math.cos(angle) - point[1] * Math.sin(angle), point[0] * Math.sin(angle) + point[1] * Math.cos(angle)];
+}
+/** Preserve the shader's 0/.33/.66/.99 piecewise interpolation, including its last interval. */
+function mixCurve(values: readonly number[], zoom: number): number {
+    const mix = (left: number, right: number, amount: number) => left * (1 - amount) + right * amount;
+    return zoom < 0.33 ? mix(values[0], values[1], 3 * zoom) : mix(values[1],
+        mix(values[2], values[3], 3 * (Math.max(zoom, 0.66) - 0.66)), 3 * (Math.max(0.33, Math.min(0.66, zoom)) - 0.33));
+}

package/src/labels/repeat_group.ts

@@ -0,0 +1,72 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+type Position = [number, number];
+type RepeatObject = {position?: Position};
+type RepeatLayout = {repeat_distance?: number; repeat_group?: string; repeat_scale: number};
+export default class RepeatGroup {
+    static groups: Record<string, Record<string, RepeatGroup>> = {};
+    key: string;
+    repeat_dist: number;
+    repeat_dist_sq: number;
+    positions: Position[];
+
+    constructor (key: string, repeat_dist: number) {
+        this.key = key;
+        this.repeat_dist = repeat_dist;
+        this.repeat_dist_sq = this.repeat_dist * this.repeat_dist;
+        this.positions = [];
+    }
+
+    // Check an object to see if it's a repeat in this group
+    check (obj: RepeatObject): boolean | undefined {
+        // Check distance from new object to objects already in group
+        const p1 = obj.position!;
+        for (let i=0; i < this.positions.length; i++) {
+            let p2 = this.positions[i];
+            let dx = p1[0] - p2[0];
+            let dy = p1[1] - p2[1];
+            let dist_sq = dx * dx + dy * dy;
+
+            // Found an existing object within allowed distance
+            if (dist_sq < this.repeat_dist_sq) {
+                return true;
+            }
+        }
+    }
+
+    // Add object to this group
+    add (obj: RepeatObject): void {
+        // only store object's position, to save space / prevent unnecessary references
+        if (obj && obj.position) {
+            this.positions.push(obj.position);
+        }
+    }
+
+    // Static methods are used to manage repeat groups, within and across tiles
+
+    // Reset all groups for this tile
+    static clear (tile: string): void {
+        this.groups[tile] = {};
+    }
+
+    // Check an object to see if it's a repeat within its designated group
+    static check (obj: RepeatObject, layout: RepeatLayout, tile: string): boolean | undefined {
+        if (layout.repeat_distance && layout.repeat_group && this.groups[tile][layout.repeat_group]) {
+            return this.groups[tile][layout.repeat_group].check(obj);
+        }
+    }
+
+    // Add an object to its designated group
+    static add (obj: RepeatObject, layout: RepeatLayout, tile: string): void {
+        if (layout.repeat_distance && layout.repeat_group) {
+            if (this.groups[tile][layout.repeat_group] == null) {
+                this.groups[tile][layout.repeat_group] = new RepeatGroup(layout.repeat_group, layout.repeat_distance * layout.repeat_scale);
+            }
+            this.groups[tile][layout.repeat_group].add(obj);
+        }
+    }
+
+}

package/src/lights/ambient_light.glsl

@@ -0,0 +1,18 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+
+/*
+
+Expected globals:
+light_accumulator_*
+
+*/
+
+struct AmbientLight {
+    vec3 ambient;
+};
+
+void calculateLight(in AmbientLight _light, in vec3 _eyeToPoint, in vec3 _normal) {
+    light_accumulator_ambient.rgb += _light.ambient;
+}

package/src/lights/directional_light.glsl

@@ -0,0 +1,39 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+
+/*
+
+Expected globals:
+material
+light_accumulator_*
+
+*/
+
+struct DirectionalLight {
+    vec3 ambient;
+    vec3 diffuse;
+    vec3 specular;
+    vec3 direction;
+};
+
+void calculateLight(in DirectionalLight _light, in vec3 _eyeToPoint, in vec3 _normal) {
+
+    light_accumulator_ambient.rgb += _light.ambient;
+
+    float nDotVP = clamp(dot(_normal, -_light.direction), 0.0, 1.0);
+
+    #ifdef TANGRAM_MATERIAL_DIFFUSE
+        light_accumulator_diffuse.rgb += _light.diffuse * nDotVP;
+    #endif
+
+    #ifdef TANGRAM_MATERIAL_SPECULAR
+        float pf = 0.0;
+        if (nDotVP > 0.0) {
+            vec3 reflectVector = reflect(_light.direction, _normal);
+            float eyeDotR = max(dot(normalize(_eyeToPoint), reflectVector), 0.0);
+            pf = pow(eyeDotR, material.shininess);
+        }
+        light_accumulator_specular.rgb += _light.specular * pf;
+    #endif
+}

package/src/lights/geographic-lights.ts

@@ -0,0 +1,21 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Geographic longitude/latitude in degrees and altitude in meters. */
+type GeographicPosition = readonly [number, number, number];
+
+import {getGeographicProjectionProcedure} from '../scene/projection_math';
+
+/** Project a lamp into Tangram's geometry space, choosing the nearest planar world copy. */
+export function projectGeographicLight(position: GeographicPosition, globe: boolean, anchorLongitude?: number): [number, number, number] {
+    if (!position.every(Number.isFinite) || Math.abs(position[1]) > 90) {
+        throw new Error('Geographic lights require finite longitude/latitude/altitude and latitude within +/-90 degrees');
+    }
+    return getGeographicProjectionProcedure(globe ? 'globe' : 'web-mercator').project(position, anchorLongitude);
+}
+
+/** Rotate a geographic spotlight's east/north/up direction into globe common space. */
+export function projectGeographicDirection(position: GeographicPosition, direction: readonly [number, number, number], globe: boolean): [number, number, number] {
+    return getGeographicProjectionProcedure(globe ? 'globe' : 'web-mercator').projectVector(position, direction);
+}