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

package/src/selection/terrain_surface.ts

@@ -0,0 +1,298 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Matrix4, Vector3} from '@math.gl/core';
+import {TriangleQueryIndex} from '../map-logic/triangle-query-index';
+import type HostFrame from '../scene/host_frame';
+import {getGeographicProjectionProcedure, PROJECTION_CONSTANTS} from '../scene/projection_math';
+import type {FeatureSelectionOptions} from '../types';
+import {intersectRayBounds} from '@math.gl/culling/queries';
+
+/** Detached conservative content-space bounds; null means the surface has no admitted triangles. */
+export interface TerrainSurfaceBounds {
+    /** Closed lower corner in the same units as query rays. */
+    minimum: [number, number, number];
+    /** Closed upper corner in the same units as query rays. */
+    maximum: [number, number, number];
+}
+
+/** A ray in the same absolute content coordinates as the supplied terrain. */
+export interface TerrainRay {
+    /** Absolute origin, before host view and room-placement transforms. */
+    origin: readonly [number, number, number];
+    /** Nonzero direction; the query normalizes its length. */
+    direction: readonly [number, number, number];
+}
+
+/** Nearest terrain triangle, not a worker feature ID or a GPU selection result. */
+export interface TerrainSurfaceHit {
+    /** Absolute EPSG:3857 meters or radius-256 globe common coordinates. */
+    position: [number, number, number];
+    /** Longitude/latitude degrees and physical altitude meters. */
+    coordinate: [number, number, number];
+    /** Distance from the ray origin in the surface's coordinate units. */
+    distance: number;
+    /** Normal in the supplied mesh's coordinate system, following triangle winding. */
+    normal: [number, number, number];
+    /** Triangle offset in the supplied index list. */
+    triangleIndex: number;
+    /** Vertex weights in index order. */
+    barycentric: [number, number, number];
+    /** Eye used for a screen query; absent for a content-space ray. */
+    renderViewId?: string;
+    /** Caller collection identity; absent on an individual surface query. */
+    surfaceId?: string;
+}
+
+/** Host-owned terrain query boundary; it does not load, render or displace a DEM. */
+export interface TerrainSurface {
+    /** Coordinate convention of both the mesh and rays. */
+    readonly projection: 'web-mercator' | 'globe';
+    /** Return the nearest two-sided hit within the finite camera segment, or null. */
+    intersectRay(ray: TerrainRay, maxDistance?: number): TerrainSurfaceHit | null;
+    /** Optional cheap bounds for near-first collection queries; must contain every accepted triangle. */
+    getBounds?(): TerrainSurfaceBounds | null;
+}
+
+/** One stable caller-owned surface identity; collections snapshot membership, not geometry. */
+export interface TerrainSurfaceEntry {
+    /** Unique nonempty identifier used to distinguish triangle offsets in different tiles. */
+    id: string;
+    /** Immutable terrain query owner, using the collection's projection. */
+    surface: TerrainSurface;
+}
+
+/** Nearest collection hit with the identity of its owning tile/surface. */
+export interface TerrainCollectionHit extends TerrainSurfaceHit {
+    /** Original caller identity, unaffected by nearest-hit clipping. */
+    surfaceId: string;
+}
+
+/** Explicit geographic probe bracket; altitude values describe displayed geometry, not source elevation. */
+export interface TerrainElevationProbe {
+    /** Lower geographic altitude in meters; must be strictly below maximumAltitude. */
+    minimumAltitude: number;
+    /** Upper geographic altitude in meters, above every surface that should be considered. */
+    maximumAltitude: number;
+    /** Optional Mercator longitude anchor for unwrapped tile coordinates. */
+    anchorLongitude?: number;
+}
+
+/** Snapshot tile membership and query nearest geometry without owning sources, views, buffers or resources. */
+export class TerrainSurfaceCollection implements TerrainSurface {
+    /** Shared absolute coordinate convention; mixed projections reject at construction. */
+    readonly projection: TerrainSurface['projection'];
+    /** Snapshotted membership and caller identities, retaining owners without copying their geometry. */
+    private readonly entries: readonly TerrainSurfaceEntry[];
+
+    /** Retain immutable surface references with unique IDs; caller membership changes do not affect this collection. */
+    constructor(projection: TerrainSurface['projection'], entries: readonly TerrainSurfaceEntry[]) {
+        if (!['web-mercator', 'globe'].includes(projection)) throw new Error('Terrain collection projection must be web-mercator or globe');
+        this.projection = projection;
+        this.entries = entries.map(({id, surface}) => {
+            if (typeof id !== 'string' || !id.length || surface.projection !== projection) throw new Error('Terrain collection requires nonempty IDs and matching projections');
+            return Object.freeze({id, surface});
+        });
+        if (new Set(this.entries.map(entry => entry.id)).size !== this.entries.length) throw new Error('Terrain collection IDs must be unique');
+    }
+
+    /** Clip farther tiles after an accepted hit; equal-distance ties retain original membership order. */
+    intersectRay(ray: TerrainRay, maxDistance = Infinity): TerrainCollectionHit | null {
+        if (maxDistance < 0 || Number.isNaN(maxDistance)) throw new Error('Terrain ray distance must be non-negative');
+        const length = Math.hypot(...ray.direction);
+        if (ray.origin.length !== 3 || ray.direction.length !== 3 || !ray.origin.every(Number.isFinite) || !ray.direction.every(Number.isFinite) || !Number.isFinite(length) || length === 0) return null;
+        const direction = ray.direction.map(component => component / length);
+        const candidates = this.entries.flatMap((entry, index) => {
+            if (!entry.surface.getBounds) return [{entry, index, distance: 0}];
+            const bounds = entry.surface.getBounds();
+            if (!bounds) return [];
+            const distance = intersectRayBounds(ray.origin, direction, bounds.minimum, bounds.maximum, maxDistance);
+            return distance === null ? [] : [{entry, index, distance}];
+        }).sort((first, second) => first.distance - second.distance || first.index - second.index);
+        let nearest: TerrainCollectionHit | null = null, nearestIndex = Infinity;
+        for (const {entry, index, distance} of candidates) {
+            if (distance > (nearest?.distance ?? maxDistance)) break;
+            const hit = entry.surface.intersectRay(ray, nearest?.distance ?? maxDistance);
+            if (hit && (!nearest || hit.distance < nearest.distance || hit.distance === nearest.distance && index < nearestIndex)) {
+                nearest = {...hit, surfaceId: entry.id}; nearestIndex = index;
+            }
+        }
+        return nearest;
+    }
+
+    /** Query a finite content-space sightline; misses mean no loaded triangle hit, not certified world visibility. */
+    intersectSegment(start: readonly [number, number, number], end: readonly [number, number, number], options: {
+        /** Trim origin self-intersections, in mesh coordinate units; defaults to zero. */
+        startInset?: number;
+        /** Trim target self-intersections, in mesh coordinate units; defaults to zero. */
+        endInset?: number;
+    } = {}): TerrainCollectionHit | null {
+        const startInset = options.startInset ?? 0, endInset = options.endInset ?? 0;
+        if (start.length !== 3 || end.length !== 3 || !start.every(Number.isFinite) || !end.every(Number.isFinite) || ![startInset, endInset].every(value => Number.isFinite(value) && value >= 0)) throw new Error('Terrain segment requires finite endpoints and non-negative finite insets');
+        const direction: [number, number, number] = [end[0] - start[0], end[1] - start[1], end[2] - start[2]], length = Math.hypot(...direction);
+        if (!Number.isFinite(length)) throw new Error('Terrain segment length must be finite');
+        if (length === 0 || startInset + endInset >= length) return null;
+        const origin: [number, number, number] = [start[0] + direction[0] * startInset / length, start[1] + direction[1] * startInset / length, start[2] + direction[2] * startInset / length];
+        const hit = this.intersectRay({origin, direction}, length - startInset - endInset);
+        return hit ? {...hit, distance: hit.distance + startInset} : null;
+    }
+}
+
+/** Probe loaded top triangles along geographic up; returned coordinate altitude retains physical source meters. */
+export function sampleTerrainElevation(surface: TerrainSurface, coordinate: readonly [number, number], options: TerrainElevationProbe): TerrainSurfaceHit | null {
+    if (coordinate.length !== 2 || !coordinate.every(Number.isFinite) || Math.abs(coordinate[1]) > 90 ||
+        ![options.minimumAltitude, options.maximumAltitude].every(Number.isFinite) || options.minimumAltitude >= options.maximumAltitude ||
+        options.anchorLongitude !== undefined && !Number.isFinite(options.anchorLongitude)) throw new Error('Invalid terrain elevation probe');
+    const projection = getGeographicProjectionProcedure(surface.projection);
+    if (Math.abs(coordinate[1]) > projection.latitudeLimit) return null;
+    // A radial bracket must not cross the globe center and sample its far hemisphere.
+    if (surface.projection === 'globe' && options.minimumAltitude <= -PROJECTION_CONSTANTS.earthRadius) throw new Error('Globe elevation probes must remain above the center');
+    const origin = projection.project([coordinate[0], coordinate[1], options.maximumAltitude], options.anchorLongitude);
+    const end = projection.project([coordinate[0], coordinate[1], options.minimumAltitude], options.anchorLongitude);
+    const direction: [number, number, number] = [end[0] - origin[0], end[1] - origin[1], end[2] - origin[2]];
+    if (!origin.every(Number.isFinite) || !end.every(Number.isFinite) || !Number.isFinite(Math.hypot(...direction))) throw new Error('Terrain elevation probe exceeds finite projection range');
+    return surface.intersectRay({origin, direction}, Math.hypot(...direction));
+}
+
+/** Resolve a Mercator camera/anchor floor; this is a point probe, not swept-volume collision or locomotion. */
+export function resolveTerrainClearance(surface: TerrainSurface, coordinate: readonly [number, number, number], clearance: number, options: TerrainElevationProbe): {
+    /** Geographic position raised only when it lies below displayed terrain plus clearance. */
+    coordinate: [number, number, number];
+    /** Source elevation meters, independent of any caller-provided display displacement. */
+    physicalElevation: number;
+    /** True when the supplied altitude was raised. */
+    adjusted: boolean;
+} | null {
+    if (surface.projection !== 'web-mercator') throw new Error('Terrain clearance requires a physical-meter Mercator frame');
+    if (coordinate.length !== 3 || !coordinate.every(Number.isFinite) || !Number.isFinite(clearance) || clearance < 0) throw new Error('Invalid terrain clearance');
+    const hit = sampleTerrainElevation(surface, [coordinate[0], coordinate[1]], options);
+    if (!hit) return null;
+    const altitude = Math.max(coordinate[2], hit.position[2] + clearance);
+    if (!Number.isFinite(altitude)) throw new Error('Terrain clearance exceeds finite altitude range');
+    return {coordinate: [coordinate[0], coordinate[1], altitude], physicalElevation: hit.coordinate[2], adjusted: altitude > coordinate[2]};
+}
+
+/** Indexed content-space triangles; source buffers are copied at construction. */
+export interface TerrainMeshOptions {
+    /** Coordinate convention, matching the HostFrame or XR placement. */
+    projection: TerrainSurface['projection'];
+    /** Interleaved absolute XYZ coordinates, not tile-local positions. */
+    positions: ArrayLike<number>;
+    /** Three zero-based vertex indices per triangle. */
+    indices: ArrayLike<number>;
+    /** Optional source meters per vertex, preserving physical queries on exaggerated display meshes. */
+    physicalHeights?: ArrayLike<number>;
+    /** Match an outward backface-culled draw pass; default false preserves two-sided queries. */
+    cullBackfaces?: boolean;
+    /** Lazy hierarchy typed-array limit; exact linear picking is used when acceleration does not fit. */
+    maxQueryIndexBytes?: number;
+    /** Keep queries exact and linear until an explicit cooperative warming pass completes. */
+    deferQueryIndexBuild?: boolean;
+}
+
+/** Detached retained-storage diagnostics; no GPU or JavaScript heap estimate is included. */
+export interface TerrainMeshStatistics {
+    /** Owned immutable positions, topology and optional physical heights. */
+    geometryBytes: number;
+    /** Currently allocated packed hierarchy storage. */
+    queryIndexBytes: number;
+    /** Required acceleration bytes, even when linear picking is selected. */
+    requiredQueryIndexBytes: number;
+}
+
+/** Immutable physical terrain surface backed by the reusable CPU triangle hierarchy. */
+export class TerrainMeshSurface implements TerrainSurface {
+    /** Mercator XY/physical Z meters, or already projected globe common coordinates. */
+    readonly projection: TerrainSurface['projection'];
+    /** Optional detached physical elevations; only indexed vertices must be finite. */
+    private readonly physicalHeights?: Float64Array;
+    /** Optional render-pass face convention; unrelated to geographic height units. */
+    private readonly cullBackfaces: boolean;
+    /** Projection-independent immutable triangle query index. */
+    private readonly queryIndex: TriangleQueryIndex;
+
+    /** Copy a finite indexed triangle mesh; mutation of caller buffers cannot change queries. */
+    constructor(options: TerrainMeshOptions) {
+        if (!['web-mercator', 'globe'].includes(options.projection)) throw new Error('Terrain projection must be web-mercator or globe');
+        if (options.positions.length % 3 || options.indices.length % 3) throw new Error('Terrain requires XYZ positions and triangle indices');
+        this.projection = options.projection;
+        try {
+            this.queryIndex = new TriangleQueryIndex(options.positions, options.indices, 8, {lazy: true, maxHierarchyBytes: options.maxQueryIndexBytes, deferBuild: options.deferQueryIndexBuild});
+        } catch (error) {throw new Error(`Terrain mesh: ${error instanceof Error ? error.message : String(error)}`);}
+        this.cullBackfaces = options.cullBackfaces ?? false;
+        const physicalHeights = options.physicalHeights;
+        if (physicalHeights) {
+            if (physicalHeights.length !== options.positions.length / 3) throw new Error('Terrain physical heights must match indexed vertices');
+            this.physicalHeights = Float64Array.from(physicalHeights);
+            for (let triangle = 0; triangle < this.queryIndex.triangleCount; triangle++) for (let vertex = 0; vertex < 3; vertex++) if (!Number.isFinite(this.physicalHeights[this.queryIndex.getVertexIndex(triangle, vertex)])) throw new Error('Terrain physical heights must match indexed vertices');
+        }
+    }
+
+    /** Exact retained typed arrays; snapshots cannot mutate query ownership. */
+    getStatistics(): TerrainMeshStatistics {
+        return {geometryBytes: this.queryIndex.geometryBytes + (this.physicalHeights?.byteLength ?? 0), queryIndexBytes: this.queryIndex.hierarchyBytes, requiredQueryIndexBytes: this.queryIndex.requiredHierarchyBytes};
+    }
+
+    /** Cooperatively warm picking acceleration; queries during preparation remain exact linear queries. */
+    *prepareQueryIndexSteps(): Generator<void, void, void> {yield* this.queryIndex.prepareHierarchySteps();}
+
+    /** Detached conservative mesh bounds; no mutable geometry or acceleration buffers escape. */
+    getBounds(): {minimum: [number, number, number]; maximum: [number, number, number]} | null {return this.queryIndex.getBounds();}
+
+    /** Indexed queries; an optional display clip rejects candidates before nearest-hit selection. */
+    intersectRay(ray: TerrainRay, maxDistance = Infinity, acceptPosition?: (position: readonly [number, number, number], triangleIndex: number, barycentric: readonly [number, number, number]) => boolean): TerrainSurfaceHit | null {
+        if (maxDistance < 0 || Number.isNaN(maxDistance)) throw new Error('Terrain ray distance must be non-negative');
+        const length = Math.hypot(...ray.direction);
+        if (ray.origin.length !== 3 || ray.direction.length !== 3 || !ray.origin.every(Number.isFinite) ||
+            !ray.direction.every(Number.isFinite) || !Number.isFinite(length) || length === 0 || !this.queryIndex.triangleCount) return null;
+        const direction: [number, number, number] = [ray.direction[0] / length, ray.direction[1] / length, ray.direction[2] / length];
+        const hit = this.queryIndex.queryRay(ray.origin, direction, maxDistance, candidate => {
+            if (acceptPosition && !acceptPosition([ray.origin[0] + direction[0] * candidate.parameter, ray.origin[1] + direction[1] * candidate.parameter, ray.origin[2] + direction[2] * candidate.parameter], candidate.triangleIndex, candidate.barycentric)) return false;
+            if (this.projection === 'globe' && Math.hypot(ray.origin[0] + direction[0] * candidate.parameter,
+                ray.origin[1] + direction[1] * candidate.parameter, ray.origin[2] + direction[2] * candidate.parameter) === 0) return false;
+            if (!this.cullBackfaces) return true;
+            const vertices = [0, 1, 2].map(vertex => this.queryIndex.getTriangleVertex(candidate.triangleIndex, vertex).position);
+            const first = new Vector3(vertices[0]);
+            const normal = new Vector3(vertices[1]).subtract(first).cross(new Vector3(vertices[2]).subtract(first));
+            return normal.dot(direction) < 0;
+        }).hit;
+        if (!hit) return null;
+        const index = hit.triangleIndex * 3;
+        const vertices = [0, 1, 2].map(offset => this.queryIndex.getTriangleVertex(hit.triangleIndex, offset).position);
+        const position: [number, number, number] = [ray.origin[0] + direction[0] * hit.parameter,
+            ray.origin[1] + direction[1] * hit.parameter, ray.origin[2] + direction[2] * hit.parameter];
+        const normal = new Vector3(vertices[1]).subtract(vertices[0]).cross(new Vector3(vertices[2]).subtract(vertices[0])).normalize();
+        const coordinate = getGeographicProjectionProcedure(this.projection).unproject(position);
+        const physicalHeights = this.physicalHeights;
+        if (physicalHeights) coordinate[2] = hit.barycentric.reduce((height, weight, vertex) => height + weight * physicalHeights[this.queryIndex.getVertexIndex(hit.triangleIndex, vertex)], 0);
+        return {position, coordinate,
+            distance: hit.parameter, normal: [normal[0], normal[1], normal[2]], triangleIndex: index / 3, barycentric: hit.barycentric};
+    }
+}
+
+/** Route top-origin CSS pixels through the actual HostFrame eye and its near/far segment. */
+export function pickTerrainAt(frame: HostFrame, pixel: {x: number; y: number}, surface: TerrainSurface,
+    options: FeatureSelectionOptions = {}, activeViewId?: string): TerrainSurfaceHit | null {
+    if (surface.projection !== frame.projection.type) throw new Error('Terrain surface and HostFrame projection must match');
+    if (![pixel.x, pixel.y].every(Number.isFinite)) throw new Error('Terrain query pixels must be finite');
+    if (options.radius !== undefined && options.radius !== 0) throw new Error('Terrain queries select one ray, not a pixel radius');
+    const resolved = frame.resolveSelectionPoint(pixel, options, activeViewId);
+    if (!resolved) return null;
+    const {view, pixel: local} = resolved;
+    const matrix = new Matrix4(Array.from(view.camera.projection));
+    // Globe HostCamera.projection already contains the host view matrix.
+    if (surface.projection !== 'globe') matrix.multiplyRight(Array.from(view.camera.view));
+    const determinant = matrix.determinant();
+    if (!Number.isFinite(determinant) || determinant === 0) return null;
+    matrix.invert();
+    const x = 2 * local.x / view.viewport.width - 1;
+    const y = 1 - 2 * local.y / view.viewport.height;
+    const points = [-1, 1].map(z => matrix.transform([x, y, z, 1]));
+    if (points.some(point => !point.every(Number.isFinite) || point[3] === 0)) return null;
+    const origin: [number, number, number] = [points[0][0] / points[0][3], points[0][1] / points[0][3], points[0][2] / points[0][3]];
+    const direction: [number, number, number] = [points[1][0] / points[1][3] - origin[0],
+        points[1][1] / points[1][3] - origin[1], points[1][2] / points[1][3] - origin[2]];
+    const hit = surface.intersectRay({origin, direction}, Math.hypot(...direction));
+    return hit ? {...hit, renderViewId: view.id} : null;
+}

package/src/shader-modules/globe-horizon.ts

@@ -0,0 +1,52 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from '@luma.gl/shadertools';
+
+/** Adapt Tangram's globe anchor and segment test to an explicit sphere radius. */
+const glsl = `
+vec3 globeHorizon_getAnchor(vec3 direction, float altitude, float radius, float earthRadius) {
+    return normalize(direction) * radius * (1. + altitude / earthRadius);
+}
+bool globeHorizon_isOccluded(vec3 position, vec3 eye, float radius) {
+    vec3 sphere_eye = eye / radius;
+    if (dot(sphere_eye, sphere_eye) <= 1.) { return false; }
+    vec3 sphere_position = position / radius;
+    vec3 segment = sphere_position - sphere_eye;
+    float segment_length_squared = dot(segment, segment);
+    if (segment_length_squared == 0.) { return false; }
+    float closest_amount = clamp(-dot(sphere_eye, segment) / segment_length_squared, 0., 1.);
+    vec3 closest = mix(sphere_eye, sphere_position, closest_amount);
+    return dot(closest, closest) < 1. - 0.000001;
+}
+`;
+
+/** Same radius-normalized segment test and surface tolerance as Tangram's WGSL. */
+const wgsl = `
+fn globeHorizon_getAnchor(direction: vec3<f32>, altitude: f32, radius: f32, earthRadius: f32) -> vec3<f32> {
+    return normalize(direction) * radius * (1.0 + altitude / earthRadius);
+}
+fn globeHorizon_isOccluded(position: vec3<f32>, eye: vec3<f32>, radius: f32) -> bool {
+    let sphere_eye = eye / radius;
+    if (dot(sphere_eye, sphere_eye) <= 1.0) { return false; }
+    let sphere_position = position / radius;
+    let segment = sphere_position - sphere_eye;
+    let segment_length_squared = dot(segment, segment);
+    if (segment_length_squared == 0.0) { return false; }
+    let closest_amount = clamp(-dot(sphere_eye, segment) / segment_length_squared, 0.0, 1.0);
+    let closest = mix(sphere_eye, sphere_position, closest_amount);
+    return dot(closest, closest) < 1.0 - 0.000001;
+}
+`;
+
+/**
+ * Experimental binding-free sphere horizon occlusion adapted from Tangram label shaders.
+ * Position and eye are center-relative in the same orthonormal frame and linear units;
+ * radius must be positive. Missing/interior eyes have no exterior horizon (false).
+ * The finite eye-to-position segment, not an infinite ray, must enter the sphere by
+ * more than the squared-unit-radius 1e-6 tolerance. Elevated anchors are supported.
+ * getAnchor restores a nonzero direction's geographic radius using altitude and a
+ * positive earthRadius in identical units. Finite, f32-representable inputs required.
+ */
+export const globeHorizon = {name: 'globeHorizon', vs: glsl, fs: glsl, source: wgsl} satisfies ShaderModule;

package/src/shader-modules/height-decode.ts

@@ -0,0 +1,41 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from '@luma.gl/shadertools';
+
+/** Decode linear normalized RGB samples; coefficients and offsets define output units. */
+const glsl = `
+float heightDecode_getHeight(vec3 rgb, vec3 coefficients, float offset) {
+    return dot(rgb * 255., coefficients) + offset;
+}
+float heightDecode_getTerrarium(vec3 rgb) {
+    // Subtract the red-channel offset before adding fractional blue elevation.
+    return (rgb.r * 255. - 128.) * 256. + rgb.g * 255. + rgb.b * (255. / 256.);
+}
+float heightDecode_getTerrainRGB(vec3 rgb) {
+    return heightDecode_getHeight(rgb, vec3(65536., 256., 1.), 0.) * 0.1 - 10000.;
+}
+`;
+
+/** WGSL counterpart; sampling, sRGB conversion and no-data policy remain host-owned. */
+const wgsl = `
+fn heightDecode_getHeight(rgb: vec3<f32>, coefficients: vec3<f32>, offset: f32) -> f32 {
+    return dot(rgb * 255.0, coefficients) + offset;
+}
+fn heightDecode_getTerrarium(rgb: vec3<f32>) -> f32 {
+    return (rgb.r * 255.0 - 128.0) * 256.0 + rgb.g * 255.0 + rgb.b * (255.0 / 256.0);
+}
+fn heightDecode_getTerrainRGB(rgb: vec3<f32>) -> f32 {
+    return heightDecode_getHeight(rgb, vec3<f32>(65536.0, 256.0, 1.0), 0.0) * 0.1 - 10000.0;
+}
+`;
+
+/**
+ * Experimental binding-free RGB elevation decoding for normalized linear samples.
+ * Terrarium and Terrain-RGB return meters. Custom coefficients apply to byte-valued
+ * channels (normalized RGB multiplied by 255); custom output units are host-defined.
+ * No rounding, clamping, alpha/no-data interpretation or sampling is performed.
+ * Finite inputs are required; f32 precision limits apply, especially at large heights.
+ */
+export const heightDecode = {name: 'heightDecode', vs: glsl, fs: glsl, source: wgsl} satisfies ShaderModule;

package/src/shader-modules/hillshade.ts

@@ -0,0 +1,70 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from '@luma.gl/shadertools';
+
+/** Projection-independent finite-difference normals and directional hillshading. */
+const glsl = `
+// Heights are west, east, south, north, in the same linear units as spacing.
+// Positive local X is east, positive Y is north, and positive Z is up.
+vec3 hillshade_getNormal(vec4 heights, vec2 spacing) {
+    vec2 safe_spacing = max(abs(spacing), vec2(0.000001));
+    vec2 gradient = vec2(heights.x - heights.y, heights.z - heights.w) / (2. * safe_spacing);
+    return normalize(vec3(gradient, 1.));
+}
+
+// Rescaling avoids length underflow/overflow and keeps every nonzero direction scale invariant.
+vec3 hillshade_normalizeDirection(vec3 direction) {
+    float scale = max(max(abs(direction.x), abs(direction.y)), abs(direction.z));
+    if (scale == 0.) { return vec3(0.); }
+    return normalize(direction / scale);
+}
+
+// Light direction points from the surface towards the light in the same local frame.
+float hillshade_getIntensity(vec3 normal, vec3 light_direction, float ambient) {
+    vec3 unit_normal = hillshade_normalizeDirection(normal);
+    vec3 unit_light = hillshade_normalizeDirection(light_direction);
+    float diffuse = clamp(dot(unit_normal, unit_light), 0., 1.);
+    float base = clamp(ambient, 0., 1.);
+    return base + (1. - base) * diffuse;
+}
+`;
+
+/** WGSL equivalent of the GLSL helpers, with no bindings or implicit coordinate conversion. */
+const wgsl = `
+// Heights: west, east, south, north. Local axes: east, north, up.
+fn hillshade_getNormal(heights: vec4<f32>, spacing: vec2<f32>) -> vec3<f32> {
+    let safe_spacing = max(abs(spacing), vec2<f32>(0.000001));
+    let gradient = vec2<f32>(heights.x - heights.y, heights.z - heights.w) / (2.0 * safe_spacing);
+    return normalize(vec3<f32>(gradient, 1.0));
+}
+
+fn hillshade_normalizeDirection(direction: vec3<f32>) -> vec3<f32> {
+    let scale = max(max(abs(direction.x), abs(direction.y)), abs(direction.z));
+    if (scale == 0.0) { return vec3<f32>(0.0); }
+    return normalize(direction / scale);
+}
+
+fn hillshade_getIntensity(normal: vec3<f32>, light_direction: vec3<f32>, ambient: f32) -> f32 {
+    let unit_normal = hillshade_normalizeDirection(normal);
+    let unit_light = hillshade_normalizeDirection(light_direction);
+    let diffuse = clamp(dot(unit_normal, unit_light), 0.0, 1.0);
+    let base = clamp(ambient, 0.0, 1.0);
+    return base + (1.0 - base) * diffuse;
+}
+`;
+
+/**
+ * Experimental luma.gl ShaderModule with provider-independent hillshade functions.
+ * Hosts supply decoded, finite heights, positive finite neighbor spacing, and a
+ * local-frame light vector. Sampling, no-data handling, seam stitching, coordinate
+ * transforms, vertical exaggeration and color composition stay with the host.
+ * No uniforms, samplers, injection hooks, or runtime dependencies are introduced.
+ */
+export const hillshade = {
+    name: 'hillshade',
+    vs: glsl,
+    fs: glsl,
+    source: wgsl
+} satisfies ShaderModule;

package/src/shader-modules/index.ts

@@ -0,0 +1,10 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export {hillshade} from './hillshade';
+export {triplanar} from './triplanar';
+export {planar} from './planar';
+export {sphereMap} from './sphere-map';
+export {heightDecode} from './height-decode';
+export {globeHorizon} from './globe-horizon';

package/src/shader-modules/planar.ts

@@ -0,0 +1,24 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import type {ShaderModule} from '@luma.gl/shadertools';
+
+/** Tangram uses one frequency for both world XY coordinates, not anisotropic XY scaling. */
+const glsl = `
+vec2 planar_getUV(vec3 position, float frequency) { return fract(position.xy * frequency); }
+`;
+
+/** WGSL equivalent with explicit wrapping, including negative positions and frequencies. */
+const wgsl = `
+fn planar_getUV(position: vec3<f32>, frequency: f32) -> vec2<f32> { return fract(position.xy * frequency); }
+`;
+
+/**
+ * Experimental binding-free planar mapping extracted from Tangram material GLSL.
+ * Frequency is repeats per position unit; finite inputs must retain f32 UV precision.
+ * Tangram's legacy vec2 scale uses only scale.x: pass that component here.
+ * The host owns textures, sampling, filtering and coordinate transforms.
+ */
+export const planar = {name: 'planar', vs: glsl, fs: glsl, source: wgsl} satisfies ShaderModule;

package/src/shader-modules/sphere-map.ts

@@ -0,0 +1,38 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import type {ShaderModule} from '@luma.gl/shadertools';
+
+/** Reflection-map coordinates, not geographic sphere coordinates. */
+const glsl = `
+vec2 sphereMap_getUV(vec3 eye_to_point, vec3 normal, vec2 skew) {
+    vec3 eye = normalize(eye_to_point);
+    eye.xy -= skew;
+    eye = normalize(eye);
+    vec3 reflected = reflect(eye, normal);
+    reflected.z += 1.0;
+    return reflected.xy / (2.0 * length(reflected)) + 0.5;
+}
+`;
+
+/** WGSL equivalent retaining camera-skew and reflection order. */
+const wgsl = `
+fn sphereMap_getUV(eye_to_point: vec3<f32>, normal: vec3<f32>, skew: vec2<f32>) -> vec2<f32> {
+    var eye = normalize(eye_to_point);
+    eye = normalize(vec3<f32>(eye.xy - skew, eye.z));
+    var reflected = reflect(eye, normal);
+    reflected.z += 1.0;
+    return reflected.xy / (2.0 * length(reflected)) + 0.5;
+}
+`;
+
+/**
+ * Experimental binding-free sphere-map reflection UVs for luma assemblers.
+ * Supply a nonzero camera-to-surface vector and unit surface normal in one frame.
+ * Inputs, their intermediate lengths and UVs must be finite. The back-facing
+ * reflection pole (0, 0, -1) and a zero post-skew eye are undefined, as in Tangram.
+ * This is environment mapping, not equirectangular mapping or GlobeView projection.
+ */
+export const sphereMap = {name: 'sphereMap', vs: glsl, fs: glsl, source: wgsl} satisfies ShaderModule;

package/src/shader-modules/triplanar.ts

@@ -0,0 +1,45 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import type {ShaderModule} from '@luma.gl/shadertools';
+
+/** Binding-free helpers extracted from lights/material.glsl; axis scales are UV frequencies. */
+const glsl = `
+vec3 triplanar_getWeights(vec3 normal) {
+    vec3 weights = normalize(max(abs(normal), vec3(0.00001)));
+    return weights / (weights.x + weights.y + weights.z);
+}
+vec2 triplanar_getUVX(vec3 position, vec3 scale) { return fract(position.yz * scale.x); }
+vec2 triplanar_getUVY(vec3 position, vec3 scale) { return fract(position.xz * scale.y); }
+vec2 triplanar_getUVZ(vec3 position, vec3 scale) { return fract(position.xy * scale.z); }
+vec4 triplanar_blend(vec4 sample_x, vec4 sample_y, vec4 sample_z, vec3 weights) {
+    return sample_x * weights.x + sample_y * weights.y + sample_z * weights.z;
+}
+`;
+
+/** WGSL equivalent; callers sample their own textures before blending. */
+const wgsl = `
+fn triplanar_getWeights(normal: vec3<f32>) -> vec3<f32> {
+    let weights = normalize(max(abs(normal), vec3<f32>(0.00001)));
+    return weights / (weights.x + weights.y + weights.z);
+}
+fn triplanar_getUVX(position: vec3<f32>, scale: vec3<f32>) -> vec2<f32> { return fract(position.yz * scale.x); }
+fn triplanar_getUVY(position: vec3<f32>, scale: vec3<f32>) -> vec2<f32> { return fract(position.xz * scale.y); }
+fn triplanar_getUVZ(position: vec3<f32>, scale: vec3<f32>) -> vec2<f32> { return fract(position.xy * scale.z); }
+fn triplanar_blend(sample_x: vec4<f32>, sample_y: vec4<f32>, sample_z: vec4<f32>, weights: vec3<f32>) -> vec4<f32> {
+    return sample_x * weights.x + sample_y * weights.y + sample_z * weights.z;
+}
+`;
+
+/**
+ * Experimental Tangram-compatible triplanar UVs and RGBA blending for luma assemblers.
+ * Inputs must be finite and small enough for f32 normalization and UV precision.
+ * Normal components have a 1e-5 floor; a zero normal gives equal weights.
+ * Position and normal share a coordinate frame. Each scale component multiplies
+ * both UV coordinates of its projection plane, including negative frequencies.
+ * No sign-dependent UV mirroring or tangent-space normal reorientation is applied.
+ * Hosts own texture bindings, sampling, derivatives, color space and normal maps.
+ */
+export const triplanar = {name: 'triplanar', vs: glsl, fs: glsl, source: wgsl} satisfies ShaderModule;