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

package/src/lights/spot_light.glsl

@@ -0,0 +1,111 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+/*
+
+Expected globals:
+material
+light_accumulator_*
+
+*/
+
+struct SpotLight {
+    vec3 ambient;
+    vec3 diffuse;
+    vec3 specular;
+    vec4 position;
+    float useLumaAttenuation;
+    vec3 attenuationCoefficients;
+
+    float attenuationExponent;
+    float innerRadius;
+    float outerRadius;
+
+    vec3 direction;
+    float spotCosCutoff;
+    float spotExponent;
+    vec2 lumaConeCos;
+};
+
+void calculateLight(in SpotLight _light, in vec3 _eyeToPoint, in vec3 _normal) {
+
+    float dist = length(_light.position.xyz - _eyeToPoint);
+
+    // Compute vector from surface to light position
+    vec3 VP = (_light.position.xyz - _eyeToPoint) / dist;
+
+    // normal . light direction
+    float nDotVP = clamp(dot(_normal, VP), 0.0, 1.0);
+
+    // Attenuation defaults
+    float attenuation = 1.0;
+    if (_light.attenuationExponent != 0.0) {
+        float Rin = _light.innerRadius >= 0.0 ? _light.innerRadius : 1.0;
+        float e = _light.attenuationExponent;
+        if (_light.outerRadius >= 0.0) {
+            float Rdiff = _light.outerRadius-Rin;
+            float d = clamp(max(0.0,dist-Rin)/Rdiff, 0.0, 1.0);
+            attenuation = 1.0-(pow(d,e));
+        } else {
+            // If no outer is provide behaves like:
+            // https://imdoingitwrong.wordpress.com/2011/01/31/light-attenuation/
+            float d = max(0.0,dist-Rin)/Rin+1.0;
+            attenuation = clamp(1.0/(pow(d,e)), 0.0, 1.0);
+        }
+    } else {
+        float Rin = max(_light.innerRadius, 0.0);
+        if (_light.innerRadius >= 0.0) {
+            if (_light.outerRadius >= 0.0) {
+                float Rdiff = _light.outerRadius-Rin;
+                float d = clamp(max(0.0,dist-Rin)/Rdiff, 0.0, 1.0);
+                attenuation = 1.0-d*d;
+            } else {
+                // If no outer is provide behaves like:
+                // https://imdoingitwrong.wordpress.com/2011/01/31/light-attenuation/
+                float d = max(0.0,dist-Rin)/Rin+1.0;
+                attenuation = clamp(1.0/d, 0.0, 1.0);
+            }
+        } else {
+            if (_light.outerRadius >= 0.0) {
+                float d = clamp(dist/_light.outerRadius, 0.0, 1.0);
+                attenuation = 1.0-d*d;
+            } else {
+                attenuation = 1.0;
+            }
+        }
+    }
+
+    // spotlight attenuation factor
+    float spotAttenuation = 0.0;
+
+    // See if point on surface is inside cone of illumination
+    float spotDot = clamp(dot(-VP, _light.direction), 0.0, 1.0);
+
+    if (spotDot >= _light.spotCosCutoff) {
+        spotAttenuation = pow(spotDot, _light.spotExponent);
+    }
+    if (_light.useLumaAttenuation > 0.5) {
+        // Match luma.gl's minimum cone factor, including its small outside-cone contribution.
+        attenuation /= tangramNativeDistanceDenominator(_light.attenuationCoefficients, dist);
+        spotAttenuation = tangramNativeConeFactor(_light.lumaConeCos, spotDot) * pow(spotDot, _light.spotExponent);
+    }
+
+    light_accumulator_ambient.rgb += _light.ambient * attenuation * spotAttenuation;
+
+    #ifdef TANGRAM_MATERIAL_DIFFUSE
+        light_accumulator_diffuse.rgb += _light.diffuse * nDotVP * attenuation * spotAttenuation;
+    #endif
+
+    #ifdef TANGRAM_MATERIAL_SPECULAR
+        // Power factor for shiny speculars
+        float pf = 0.0;
+        if (nDotVP > 0.0) {
+            vec3 reflectVector = reflect(-VP, _normal);
+            float eyeDotR = max(dot(-normalize(_eyeToPoint), reflectVector), 0.0);
+            pf = pow(eyeDotR, material.shininess);
+        }
+        light_accumulator_specular.rgb += _light.specular * pf * attenuation * spotAttenuation;
+    #endif
+}

package/src/map-logic/draped-terrain-bounds.ts

@@ -0,0 +1,71 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {getGeographicProjectionProcedure, PROJECTION_CONSTANTS} from '../scene/projection_math';
+
+/** Immutable worker query channels; no scene, GPU, provider or query-index ownership. */
+interface DrapedTerrainBoundsInput {
+    /** Absolute Mercator XYZ, with authored offsets in meters. */
+    positions: Float64Array;
+    /** Current/previous physical DEM heights, interleaved per vertex. */
+    heights: Float32Array;
+    /** Optional current/previous affine globe bases and relief vectors, twelve channels per vertex. */
+    globeBasis?: Float32Array;
+    /** Actual rendered triangle indices. */
+    indices: Uint16Array | Uint32Array;
+    /** Optional trusted worker summary of these exact immutable channels. */
+    boundsSummary?: DrapedTerrainBoundsSummary;
+}
+
+/** Independent channel extrema enclose every convex rendered triangle throughout its height morph. */
+export interface DrapedTerrainBoundsSummary {
+    /** Radius-one globe directions of indexed vertices, not geographic rectangle corners. */
+    directions: {minimum: [number, number, number]; maximum: [number, number, number]};
+    /** Authored meter offsets, independent of relief exaggeration. */
+    offsets: readonly [number, number];
+    /** Physical current/previous DEM endpoints, conservatively enclosing all morph fractions. */
+    heights: readonly [number, number];
+    /** Affine globe channels enclose canonical face cuts without projecting them back onto the sphere. */
+    globe?: {
+        /** Zero-relief common-space endpoint extrema. */
+        base: {minimum: number[]; maximum: number[]};
+        /** Common-space displacement per unit exaggeration. */
+        relief: {minimum: number[]; maximum: number[]};
+    };
+}
+
+/** Compatibility owners without worker summaries pay one indexed scan, never one scan per eye/frame. */
+const boundsSummaries = new WeakMap<DrapedTerrainBoundsInput, DrapedTerrainBoundsSummary>();
+
+/** Compute bounds from the actual indexed vertices so long globe chords and unwrapped tiles remain enclosed. */
+export function summarizeDrapedTerrainBounds(mesh: DrapedTerrainBoundsInput): DrapedTerrainBoundsSummary {
+    const cached = mesh.boundsSummary ?? boundsSummaries.get(mesh);
+    if (cached) return cached;
+    const directions: DrapedTerrainBoundsSummary['directions'] = {minimum: [Infinity, Infinity, Infinity], maximum: [-Infinity, -Infinity, -Infinity]};
+    const offsets: [number, number] = [Infinity, -Infinity], heights: [number, number] = [Infinity, -Infinity];
+    const globeBounds = mesh.globeBasis ? {base: {minimum: [Infinity, Infinity, Infinity], maximum: [-Infinity, -Infinity, -Infinity]},
+        relief: {minimum: [Infinity, Infinity, Infinity], maximum: [-Infinity, -Infinity, -Infinity]}} : undefined;
+    if (mesh.globeBasis && mesh.globeBasis.length !== mesh.positions.length * 4) throw new Error('Invalid terrain globe basis channels');
+    const mercator = getGeographicProjectionProcedure('web-mercator'), globe = getGeographicProjectionProcedure('globe');
+    for (const vertex of mesh.indices) {
+        if (vertex * 3 + 2 >= mesh.positions.length) throw new Error('Invalid terrain bounds index');
+        const position = [mesh.positions[vertex * 3], mesh.positions[vertex * 3 + 1], mesh.positions[vertex * 3 + 2]] as const;
+        const current = mesh.heights[vertex * 2], previous = mesh.heights[vertex * 2 + 1];
+        if (![...position, current, previous].every(Number.isFinite)) throw new Error('Invalid terrain bounds channels');
+        const direction = globe.project(mercator.unproject([position[0], position[1], 0]));
+        for (const axis of [0, 1, 2]) {
+            directions.minimum[axis] = Math.min(directions.minimum[axis], direction[axis] / PROJECTION_CONSTANTS.globeRadius);
+            directions.maximum[axis] = Math.max(directions.maximum[axis], direction[axis] / PROJECTION_CONSTANTS.globeRadius);
+            if (mesh.globeBasis && globeBounds) for (const endpoint of [0, 6]) {
+                const base = mesh.globeBasis[vertex * 12 + endpoint + axis], relief = mesh.globeBasis[vertex * 12 + endpoint + 3 + axis];
+                if (!Number.isFinite(base) || !Number.isFinite(relief)) throw new Error('Invalid terrain globe basis channels');
+                globeBounds.base.minimum[axis] = Math.min(globeBounds.base.minimum[axis], base); globeBounds.base.maximum[axis] = Math.max(globeBounds.base.maximum[axis], base);
+                globeBounds.relief.minimum[axis] = Math.min(globeBounds.relief.minimum[axis], relief); globeBounds.relief.maximum[axis] = Math.max(globeBounds.relief.maximum[axis], relief);
+            }
+        }
+        offsets[0] = Math.min(offsets[0], position[2]); offsets[1] = Math.max(offsets[1], position[2]);
+        heights[0] = Math.min(heights[0], current, previous); heights[1] = Math.max(heights[1], current, previous);
+    }
+    const summary = {directions, offsets, heights, ...(globeBounds ? {globe: globeBounds} : {})}; boundsSummaries.set(mesh, summary); return summary;
+}

package/src/map-logic/globe-terrain-preparation.ts

@@ -0,0 +1,217 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {prepareGlobeTerrainMeshSteps, type GlobeTerrainMeshTemplate} from './globe-terrain';
+import type {TerrainHeightGrid} from './terrain-data';
+import type {TerrainResourceBudget, TerrainResourceLease} from './terrain-resource-budget';
+
+/** Complete, immutable neighborhood generation; only library-produced handles can resolve templates. */
+export interface GlobeTerrainPreparationSnapshot {
+    /** Ordered immutable source identities; applications must not mutate their samples. */
+    readonly grids: readonly TerrainHeightGrid[];
+    /** Uniform curved-cell resolution for all stitched tiles. */
+    readonly resolution: number;
+    /** Owned prepared typed arrays, excluding source, display/query buffers and GPU allocations. */
+    readonly byteLength: number;
+}
+
+/** One source and the touching immutable neighbors that determined its topology and lighting. */
+interface PreparedTile {
+    grid: TerrainHeightGrid;
+    neighbors: readonly TerrainHeightGrid[];
+    template: GlobeTerrainMeshTemplate;
+}
+
+/** Snapshot internals cannot be forged or modified through an exported handle. */
+const snapshots = new WeakMap<GlobeTerrainPreparationSnapshot, readonly PreparedTile[]>();
+
+/** Validate library ownership, including empty snapshots whose templates cannot be looked up. */
+export function assertGlobeTerrainPreparationSnapshot(snapshot: GlobeTerrainPreparationSnapshot): void {
+    if (!snapshots.has(snapshot)) throw new Error('Prepared globe terrain requires a completed snapshot');
+}
+
+/** Resolve only a source identity belonging to a completed preparation generation. */
+export function getPreparedGlobeTerrainTemplate(snapshot: GlobeTerrainPreparationSnapshot, grid: TerrainHeightGrid): GlobeTerrainMeshTemplate {
+    assertGlobeTerrainPreparationSnapshot(snapshot);
+    const tile = snapshots.get(snapshot)?.find(candidate => candidate.grid === grid);
+    if (!tile) throw new Error('Prepared globe terrain requires a completed snapshot and matching source identity');
+    return tile.template;
+}
+
+/** Detached cooperative-work diagnostics, not a frame-time or whole-process memory measurement. */
+export interface GlobeTerrainPreparationStatistics {
+    /** Tiles still awaiting preparation in the latest request. */
+    pending: number;
+    /** Unique current and staged template storage; shared templates count once. */
+    retainedBytes: number;
+    /** Maximum retained template bytes permitted by this owner. */
+    byteLimit: number;
+    /** Fully published generations. */
+    committed: number;
+    /** Requests replaced before completion. */
+    cancelled: number;
+    /** New templates admitted by the latest generation. */
+    prepared: number;
+    /** Templates reused by the latest generation. */
+    reused: number;
+    /** Cooperative CPU slices in the latest generation. */
+    slices: number;
+    /** Last slice's elapsed time; an indivisible step may exceed its target. */
+    lastSliceMs: number;
+    /** Largest observed slice in the latest generation. */
+    maxSliceMs: number;
+    /** CPU slice elapsed sum, excluding time yielded back to the host. */
+    workMs: number;
+    /** Largest current-plus-candidate typed-template requirement observed before allocation. */
+    requiredPeakBytes: number;
+    /** Last preparation/admission failure; retry is explicit. */
+    error?: string;
+}
+
+/** Same-datum touching footprints, including antimeridian edges and corners. */
+function getNeighbors(grid: TerrainHeightGrid, grids: readonly TerrainHeightGrid[]): TerrainHeightGrid[] {
+    const circumference = 2 * Math.PI * 6378137;
+    return grids.filter(candidate => candidate !== grid && [-circumference, 0, circumference].some(shift =>
+        candidate.bounds[0] + shift <= grid.bounds[2] && candidate.bounds[2] + shift >= grid.bounds[0] && candidate.bounds[1] <= grid.bounds[3] && candidate.bounds[3] >= grid.bounds[1]));
+}
+
+/** Ordered identity comparison; no expensive sample scan or source mutation is performed. */
+function sameGrids(first: readonly TerrainHeightGrid[], second: readonly TerrainHeightGrid[]): boolean {
+    return first.length === second.length && first.every((grid, index) => grid === second[index]);
+}
+
+/** Latest-request-wins preparation driven by the host, with atomic stitched snapshots and bounded retention. */
+export class GlobeTerrainPreparation {
+    private current?: GlobeTerrainPreparationSnapshot;
+    private target?: {grids: readonly TerrainHeightGrid[]; resolution: number};
+    private iterator?: Generator<void, void, void>;
+    private staged: PreparedTile[] = [];
+    private disposed = false;
+    private readonly statistics: GlobeTerrainPreparationStatistics;
+    /** Leases cover this owner's current/staged templates, not external snapshots or scratch. */
+    private readonly leases = new Map<GlobeTerrainMeshTemplate, TerrainResourceLease>();
+    /** Optional shared admission with sources, display preparation and renderer owners. */
+    private readonly resourceBudget?: TerrainResourceBudget;
+
+    /** Retention includes the currently displayed and partially prepared generations, but not transient scratch arrays. */
+    constructor(maxRetainedBytes = 96 * 1024 * 1024, options: {
+        /** Shared registered-allocation budget; independent local limits still apply. */
+        resourceBudget?: TerrainResourceBudget;
+    } = {}) {
+        if (!Number.isSafeInteger(maxRetainedBytes) || maxRetainedBytes < 0) throw new Error('Prepared terrain byte limit must be a non-negative integer');
+        this.resourceBudget = options.resourceBudget;
+        this.statistics = {pending: 0, retainedBytes: 0, byteLimit: maxRetainedBytes, committed: 0, cancelled: 0, prepared: 0, reused: 0, slices: 0, lastSliceMs: 0, maxSliceMs: 0, workMs: 0, requiredPeakBytes: 0};
+    }
+
+    /** Replace obsolete staged work; unchanged requests and failed generations do not restart automatically. */
+    request(grids: readonly TerrainHeightGrid[], resolution = 64): boolean {
+        if (this.disposed) throw new Error('Globe terrain preparation is disposed');
+        if (!Number.isSafeInteger(resolution) || resolution < 2 || resolution > 256) throw new Error('Globe terrain resolution must be an integer in [2, 256]');
+        if (grids.some(grid => grid.verticalDatum !== grids[0].verticalDatum)) throw new Error('Globe terrain grids require one compatible vertical datum');
+        if (new Set(grids.map(grid => grid.bounds.join(','))).size !== grids.length) throw new Error('Globe terrain grids must have distinct footprints');
+        if (this.target?.resolution === resolution && sameGrids(this.target.grids, grids)) return false;
+        this.cancel();
+        this.target = {grids: Object.freeze([...grids]), resolution};
+        Object.assign(this.statistics, {pending: grids.length, prepared: 0, reused: 0, slices: 0, lastSliceMs: 0, maxSliceMs: 0, workMs: 0, requiredPeakBytes: 0, error: undefined});
+        this.iterator = this.prepare(this.target.grids, resolution);
+        return true;
+    }
+
+    /** Run at least one bounded step, then yield after the elapsed target; true means a complete generation was committed. */
+    advance(budgetMs = 4, now: () => number = () => performance.now()): boolean {
+        if (!Number.isFinite(budgetMs) || budgetMs <= 0) throw new Error('Preparation slice target must be positive');
+        if (!this.iterator) return false;
+        const started = now();
+        let committed = false;
+        try {
+            do {
+                const result = this.iterator.next();
+                if (result.done) {this.iterator = undefined; committed = true; break;}
+            } while (now() - started < budgetMs);
+        } catch (error) {
+            this.iterator?.return(); this.iterator = undefined; this.staged = []; this.statistics.pending = 0;
+            this.releaseUnusedLeases();
+            this.statistics.error = error instanceof Error ? error.message : String(error);
+        }
+        const elapsed = Math.max(0, now() - started);
+        this.statistics.slices++; this.statistics.lastSliceMs = elapsed; this.statistics.maxSliceMs = Math.max(this.statistics.maxSliceMs, elapsed); this.statistics.workMs += elapsed;
+        return committed;
+    }
+
+    /** Retry a failed immutable request without resetting the displayed snapshot. */
+    retry(): boolean {
+        if (!this.statistics.error || !this.target || this.disposed) return false;
+        const {grids, resolution} = this.target; this.target = undefined;
+        return this.request(grids, resolution);
+    }
+
+    /** Completed snapshot only; partial generations are never exposed for rendering or picking. */
+    getSnapshot(): GlobeTerrainPreparationSnapshot | undefined {return this.current;}
+
+    /** Detached diagnostic snapshot, including unique current/staged template backing storage. */
+    getStatistics(): GlobeTerrainPreparationStatistics {
+        return {...this.statistics, retainedBytes: this.getRetainedBytes(this.staged)};
+    }
+
+    /** True until the latest generation commits, fails or is cancelled by teardown. */
+    isPending(): boolean {return Boolean(this.iterator);}
+
+    /** Cancel pending work and release its reservations without discarding the displayed snapshot. */
+    cancel(): boolean {
+        const pending = Boolean(this.iterator);
+        if (pending) this.statistics.cancelled++;
+        this.iterator?.return(); this.iterator = undefined; this.staged = []; this.target = undefined; this.statistics.pending = 0;
+        this.releaseUnusedLeases();
+        return pending;
+    }
+
+    /** Release references to current, staged and source data; safe to repeat. */
+    destroy(): void {
+        this.cancel(); this.current = undefined; this.releaseUnusedLeases();
+        this.statistics.pending = 0; this.disposed = true;
+    }
+
+    /** Count shared template handles once across visible and candidate generations. */
+    private getRetainedBytes(staged: readonly PreparedTile[]): number {
+        const templates = new Set([...(this.current ? snapshots.get(this.current) ?? [] : []), ...staged].map(tile => tile.template));
+        return [...templates].reduce((sum, template) => sum + template.byteLength, 0);
+    }
+
+    /** Release only templates no longer retained by this owner; external snapshot ownership is separate. */
+    private releaseUnusedLeases(): void {
+        const retained = new Set([...(this.current ? snapshots.get(this.current) ?? [] : []), ...this.staged].map(tile => tile.template));
+        for (const [template, lease] of this.leases) if (!retained.has(template)) {lease.release(); this.leases.delete(template);}
+    }
+
+    /** Preserve unaffected immutable neighborhoods; commit every stitched tile together only after admission succeeds. */
+    private *prepare(grids: readonly TerrainHeightGrid[], resolution: number): Generator<void, void, void> {
+        const previous = new Map((this.current ? snapshots.get(this.current) ?? [] : []).map(tile => [tile.grid, tile]));
+        for (const grid of grids) {
+            const neighbors = getNeighbors(grid, grids), retained = previous.get(grid);
+            const reuse = retained && this.current?.resolution === resolution && retained.neighbors.length === neighbors.length && retained.neighbors.every((neighbor, index) => neighbor === neighbors[index]);
+            let reservation: TerrainResourceLease | undefined;
+            let template: GlobeTerrainMeshTemplate;
+            try {
+                template = reuse ? retained.template : yield* prepareGlobeTerrainMeshSteps(grid, {resolution, neighbors,
+                    onAllocate: (bytes, allocation) => {
+                        const required = this.getRetainedBytes(this.staged) + bytes;
+                        this.statistics.requiredPeakBytes = Math.max(this.statistics.requiredPeakBytes, required);
+                        if (required > this.statistics.byteLimit) throw new Error('Prepared globe terrain retained-byte limit exceeded; current terrain retained');
+                        if (this.resourceBudget) {
+                            reservation = this.resourceBudget.reserveShared(allocation, 'retained', bytes) ?? undefined;
+                            if (!reservation) throw new Error('Prepared globe terrain shared resource budget exceeded; current terrain retained');
+                        }
+                    }});
+                if (reservation) {this.leases.set(template, reservation); reservation = undefined;}
+            } finally {reservation?.release();}
+            const candidate = {grid, neighbors, template};
+            if (this.getRetainedBytes([...this.staged, candidate]) > this.statistics.byteLimit) throw new Error('Prepared globe terrain retained-byte limit exceeded; current terrain retained');
+            this.staged.push(candidate); this.statistics.pending--;
+            if (reuse) this.statistics.reused++; else this.statistics.prepared++;
+            yield;
+        }
+        const snapshot = Object.freeze({grids, resolution, byteLength: this.staged.reduce((sum, tile) => sum + tile.template.byteLength, 0)});
+        snapshots.set(snapshot, this.staged); this.current = snapshot; this.staged = []; this.statistics.committed++; this.releaseUnusedLeases();
+    }
+}