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

package/src/utils/media_capture.ts

@@ -0,0 +1,193 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import log from './log';
+import {createObjectURL} from './urls';
+import StyleParser from '../styles/style_parser';
+
+export default class MediaCapture {
+    canvas: any;
+    gl: any;
+    screenshot_canvas: HTMLCanvasElement | null;
+    screenshot_context: CanvasRenderingContext2D | null;
+    queue_screenshot: any;
+    video_capture: any;
+
+    constructor() {
+        this.canvas = null;
+        this.gl = null;
+        this.screenshot_canvas = null;
+        this.screenshot_context = null;
+        this.queue_screenshot = null;
+        this.video_capture = null;
+    }
+
+    setCanvas (canvas: any, gl: any): void {
+        this.canvas = canvas;
+        this.gl = gl;
+    }
+
+    // Take a screenshot, returns a promise that resolves with the screenshot data when available
+    // `background`: optional background color to blend screenshot with
+    screenshot ({ background }: {background?: string} = {}): Promise<any> {
+        if (this.queue_screenshot != null) {
+            return this.queue_screenshot.promise; // only capture one screenshot at a time
+        }
+
+        // Will resolve once rendering is complete and render buffer is captured
+        this.queue_screenshot = { background };
+        this.queue_screenshot.promise = new Promise((resolve, reject) => {
+            this.queue_screenshot.resolve = resolve;
+            this.queue_screenshot.reject = reject;
+        });
+        return this.queue_screenshot.promise;
+    }
+
+    // Called after rendering, captures render buffer and resolves promise with the image data
+    completeScreenshot (): void {
+        if (this.queue_screenshot != null) {
+            // Firefox appears to have an issue where its alpha conversion overflows some channels when
+            // the WebGL canvas content is captured. To get around this, we read pixels from the GL buffer
+            // directly, then flip and unmulitply the alpha on each pixel to get the desired RGB values.
+            // See https://github.com/tangrams/tangram/issues/551
+
+            // Get raw pixels from GL
+            let w = this.canvas.width;
+            let h = this.canvas.height;
+            let pixels = new Uint8Array(w * h * 4);
+            this.gl.readPixels(0, 0, w, h, this.gl.RGBA, this.gl.UNSIGNED_BYTE, pixels);
+
+            // Optional background to blend with (only RGB, alpha is ignored)
+            let background = this.queue_screenshot.background;
+            if (background && background !== 'transparent') {
+                background = (StyleParser as any).parseColor(background).slice(0, 3).map((c: number) => c * 255) as any;
+            }
+            else {
+                background = null; // skip blend if transparent
+            }
+
+            // Flip Y (GL buffer is upside down)
+            let flip = new Uint8ClampedArray(w * h * 4);    // canvas requires 'clamped' array type
+            for (let y=0; y < h; y++) {
+                for (let x=0; x < w; x++) {
+                    let s = ((h - y - 1) * w + x) * 4;      // source offset
+                    let d = (y * w + x) * 4;                // destination offset
+                    let a = pixels[s + 3];                  // unmultiply alpha
+                    flip[d + 0] = pixels[s + 0] * 255 / a;
+                    flip[d + 1] = pixels[s + 1] * 255 / a;
+                    flip[d + 2] = pixels[s + 2] * 255 / a;
+                    flip[d + 3] = a;
+
+                    if (background) {
+                        a /= 255;
+                        flip[d + 0] = (flip[d + 0] * a) + (background[0] * (1 - a));
+                        flip[d + 1] = (flip[d + 1] * a) + (background[1] * (1 - a));
+                        flip[d + 2] = (flip[d + 2] * a) + (background[2] * (1 - a));
+                        flip[d + 3] = 255;
+                    }
+                }
+            }
+
+            // Draw flipped pixels to a canvas
+            this.screenshot_canvas = this.screenshot_canvas || document.createElement('canvas');
+            let canvas = this.screenshot_canvas;
+            canvas.width = w;
+            canvas.height = h;
+
+            this.screenshot_context = this.screenshot_context || canvas.getContext('2d');
+            let ctx = this.screenshot_context;
+            let image = new ImageData(flip, w, h);
+            ctx!.putImageData(image, 0, 0);
+
+            // Get data URL from canvas and convert to blob
+            // Strip host/mimetype/etc., convert base64 to binary without UTF-8 mangling
+            // Adapted from: https://gist.github.com/unconed/4370822
+            const url = canvas.toDataURL('image/png');
+            const data = atob(url.slice(22));
+            const buffer = new Uint8Array(data.length);
+            for (let i = 0; i < data.length; ++i) {
+                buffer[i] = data.charCodeAt(i);
+            }
+            const blob = new Blob([buffer], { type: 'image/png' });
+
+            // Resolve with screenshot data
+            this.queue_screenshot.resolve({ url, blob, type: 'png' });
+            this.queue_screenshot = null;
+        }
+    }
+
+    // Starts capturing a video stream from the canvas
+    startVideoCapture (): boolean {
+        if (typeof window === 'undefined' || typeof window.MediaRecorder !== 'function' || !this.canvas || typeof this.canvas.captureStream !== 'function') {
+            log('warn', 'Video capture (Canvas.captureStream and/or MediaRecorder APIs) not supported by browser');
+            return false;
+        }
+        else if (this.video_capture) {
+            log('warn', 'Video capture already in progress, call Scene.stopVideoCapture() first');
+            return false;
+        }
+
+        // Start a new capture
+        try {
+            const cap: any = this.video_capture = {};
+            cap.chunks = [];
+            cap.stream = this.canvas.captureStream();
+            cap.options = { mimeType: 'video/webm' }; // TODO: support other format options
+            cap.media_recorder = new MediaRecorder(cap.stream, cap.options);
+            cap.media_recorder.ondataavailable = (event: any) => {
+                if (event.data.size > 0) {
+                    cap.chunks.push(event.data);
+                }
+
+                // Stopped recording? Create the final capture file blob
+                if (cap.resolve) {
+                    let blob = new Blob(cap.chunks, { type: cap.options.mimeType });
+                    let url = createObjectURL(blob);
+
+                    // Explicitly remove all stream tracks, and set objects to null
+                    if (cap.stream) {
+                        let tracks = cap.stream.getTracks() || [];
+                        tracks.forEach((track: MediaStreamTrack) => {
+                            track.stop();
+                            cap.stream.removeTrack(track);
+                        });
+                    }
+                    cap.stream = null;
+                    cap.media_recorder = null;
+                    this.video_capture = null;
+
+                    cap.resolve({ url, blob, type: 'webm' });
+                }
+            };
+            cap.media_recorder.start();
+        }
+        catch (e) {
+            this.video_capture = null;
+            log('error', 'Scene video capture failed', e);
+            return false;
+        }
+        return true;
+    }
+
+    // Stops capturing a video stream from the canvas, returns a promise that resolves with the video when available
+    stopVideoCapture (): Promise<any> {
+        if (!this.video_capture) {
+            log('warn', 'No scene video capture in progress, call Scene.startVideoCapture() first');
+            return Promise.resolve({});
+        }
+
+        // Promise that will resolve when final stream is available
+        this.video_capture.promise = new Promise((resolve, reject) => {
+            this.video_capture.resolve = resolve;
+            this.video_capture.reject = reject;
+        });
+
+        // Stop recording
+        this.video_capture.media_recorder.stop();
+
+        return this.video_capture.promise;
+    }
+
+}

package/src/utils/merge.ts

@@ -0,0 +1,44 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+// Deep/recursive merge of one or more source objects into a destination object
+type MutableRecord = Record<string, unknown>;
+
+function isMergeableObject(value: unknown): value is MutableRecord {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export default function mergeObjects<Destination extends object>(
+  destination: Destination,
+  ...sources: Array<object | null | undefined>
+): Destination {
+  const destinationRecord = destination as MutableRecord;
+
+  for (const source of sources) {
+    if (!source) {
+      continue;
+    }
+
+    for (const key in source) {
+      const sourceRecord = source as MutableRecord;
+      const value = sourceRecord[key];
+
+      // Recursively merge the source into the destination if it is a non-null key/value object.
+      // Arrays are treated as scalar values; null values overwrite the previous destination value.
+      if (isMergeableObject(value)) {
+        const destinationValue = destinationRecord[key];
+        destinationRecord[key] = isMergeableObject(destinationValue)
+          ? mergeObjects(destinationValue, value)
+          : mergeObjects({}, value);
+      }
+      // Undefined source properties are ignored. All other values overwrite the destination.
+      else if (value !== undefined) {
+        destinationRecord[key] = value;
+      }
+    }
+  }
+
+  return destination;
+}

package/src/utils/obb.ts

@@ -0,0 +1,134 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import {Vector2} from '@math.gl/core';
+import type {MutableNumericVector, NumericVector} from './vector';
+
+type Quad = [number, number, number, number, number, number, number, number];
+type Extent = [number, number, number, number];
+
+const ZERO_AXES: MutableNumericVector[] = [[1, 0], [0, 1]];
+const projectionA: MutableNumericVector = [];
+const projectionB: MutableNumericVector = [];
+
+/** Two-dimensional oriented bounding box. */
+export default class OBB {
+  /** Half-width and half-height. */
+  readonly dimension: [number, number];
+  /** Rotation angle in radians. */
+  angle: number;
+  /** Box center. */
+  readonly centroid: [number, number];
+  /** Flattened corner coordinates. */
+  quad!: Quad;
+  /** First normalized separating axis. */
+  axis_0!: MutableNumericVector;
+  /** Second normalized separating axis. */
+  axis_1!: MutableNumericVector;
+
+  constructor(x: number, y: number, angle: number, width: number, height: number) {
+    this.dimension = [width / 2, height / 2];
+    this.angle = angle;
+    this.centroid = [x, y];
+    this.update();
+  }
+
+  /** Returns a serializable representation of the box. */
+  toJSON(): {x: number; y: number; a: number; w: number; h: number} {
+    return {
+      x: this.centroid[0],
+      y: this.centroid[1],
+      a: this.angle,
+      w: this.dimension[0],
+      h: this.dimension[1]
+    };
+  }
+
+  /** Returns the axis-aligned extent containing the box. */
+  getExtent(): Extent {
+    if (this.angle === 0) {
+      return [this.quad[0], this.quad[1], this.quad[4], this.quad[5]];
+    }
+
+    return [
+      Math.min(this.quad[0], this.quad[2], this.quad[4], this.quad[6]),
+      Math.min(this.quad[1], this.quad[3], this.quad[5], this.quad[7]),
+      Math.max(this.quad[0], this.quad[2], this.quad[4], this.quad[6]),
+      Math.max(this.quad[1], this.quad[3], this.quad[5], this.quad[7])
+    ];
+  }
+
+  /** Recalculates the normalized box axes. */
+  updateAxes(): void {
+    this.axis_0 = new Vector2([
+      this.quad[4] - this.quad[6],
+      this.quad[5] - this.quad[7]
+    ]).normalize().toArray([]);
+    this.axis_1 = new Vector2([
+      this.quad[4] - this.quad[2],
+      this.quad[5] - this.quad[3]
+    ]).normalize().toArray([]);
+  }
+
+  /** Recalculates corners and axes from the current center, dimensions, and angle. */
+  update(): void {
+    const [centerX, centerY] = this.centroid;
+    const [halfWidth, halfHeight] = this.dimension;
+
+    if (this.angle === 0) {
+      this.quad = [
+        centerX - halfWidth, centerY - halfHeight,
+        centerX + halfWidth, centerY - halfHeight,
+        centerX + halfWidth, centerY + halfHeight,
+        centerX - halfWidth, centerY + halfHeight
+      ];
+      this.axis_0 = ZERO_AXES[0];
+      this.axis_1 = ZERO_AXES[1];
+      return;
+    }
+
+    const widthX = Math.cos(this.angle) * halfWidth;
+    const widthY = Math.sin(this.angle) * halfWidth;
+    const heightX = -Math.sin(this.angle) * halfHeight;
+    const heightY = Math.cos(this.angle) * halfHeight;
+    this.quad = [
+      centerX - widthX - heightX, centerY - widthY - heightY,
+      centerX + widthX - heightX, centerY + widthY - heightY,
+      centerX + widthX + heightX, centerY + widthY + heightY,
+      centerX - widthX + heightX, centerY - widthY + heightY
+    ];
+    this.updateAxes();
+  }
+
+  /** Projects a box onto an axis and writes its minimum and maximum values. */
+  static projectToAxis(box: OBB, axis: NumericVector, projection: MutableNumericVector): MutableNumericVector {
+    const dot0 = box.quad[0] * axis[0] + box.quad[1] * axis[1];
+    const dot1 = box.quad[2] * axis[0] + box.quad[3] * axis[1];
+    const dot2 = box.quad[4] * axis[0] + box.quad[5] * axis[1];
+    const dot3 = box.quad[6] * axis[0] + box.quad[7] * axis[1];
+    projection[0] = Math.min(dot0, dot1, dot2, dot3);
+    projection[1] = Math.max(dot0, dot1, dot2, dot3);
+    return projection;
+  }
+
+  /** Tests two separating axes for overlap. */
+  static axisCollide(first: OBB, second: OBB, axis0: NumericVector, axis1: NumericVector): boolean {
+    OBB.projectToAxis(first, axis0, projectionA);
+    OBB.projectToAxis(second, axis0, projectionB);
+    if (projectionB[0] > projectionA[1] || projectionB[1] < projectionA[0]) {
+      return false;
+    }
+
+    OBB.projectToAxis(first, axis1, projectionA);
+    OBB.projectToAxis(second, axis1, projectionB);
+    return !(projectionB[0] > projectionA[1] || projectionB[1] < projectionA[0]);
+  }
+
+  /** Tests whether two oriented boxes intersect. */
+  static intersect(first: OBB, second: OBB): boolean {
+    return OBB.axisCollide(first, second, first.axis_0, first.axis_1) &&
+      OBB.axisCollide(first, second, second.axis_0, second.axis_1);
+  }
+}

package/src/utils/props.ts

@@ -0,0 +1,43 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+// Get a value for a nested property with path provided as an array (`a.b.c` => ['a', 'b', 'c'])
+type PropertyTarget = Record<PropertyKey, unknown>;
+export type PropertyPath = readonly PropertyKey[];
+
+export function getPropertyPath(object: object, path: PropertyPath): unknown {
+  const property = path[path.length - 1];
+  return getPropertyPathTarget(object, path)?.[property];
+}
+
+// Set a value for a nested property with path provided as an array (`a.b.c` => ['a', 'b', 'c'])
+export function setPropertyPath(object: object, path: PropertyPath, value: unknown): void {
+  const property = path[path.length - 1];
+  const target = getPropertyPathTarget(object, path);
+  if (target) {
+    target[property] = value;
+  }
+}
+
+// Get the immediate parent object for a property path name provided as an array
+// e.g. for a single-depth path, this is just `object`, for path ['a', 'b'], this is `object[a]`
+export function getPropertyPathTarget(
+  object: object,
+  path: PropertyPath
+): PropertyTarget | undefined {
+  if (path.length === 0) {
+    return;
+  }
+
+  let target: unknown = object;
+  for (let index = 0; index < path.length - 1; index++) {
+    const property = path[index];
+    target = (target as PropertyTarget)[property];
+    if (target == null) {
+      return;
+    }
+  }
+  return target as PropertyTarget;
+}

package/src/utils/slice.ts

@@ -0,0 +1,14 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+
+export default function sliceObject<ObjectType extends object, Key extends keyof ObjectType>(
+  object: ObjectType,
+  keys: readonly Key[]
+): Pick<ObjectType, Key> {
+  const sliced = {} as Pick<ObjectType, Key>;
+  for (const key of keys) {
+    sliced[key] = object[key];
+  }
+  return sliced;
+}

package/src/utils/subscribe.ts

@@ -0,0 +1,58 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+
+import log from './log';
+
+export type EventListener = (...data: unknown[]) => void;
+export type EventListeners = Record<string, EventListener | unknown>;
+
+export type SubscriptionMethods = {
+  subscribe(listener: EventListeners): void;
+  unsubscribe(listener: EventListeners): void;
+  unsubscribeAll(): void;
+  trigger(event: string, ...data: unknown[]): void;
+  hasSubscribersFor(event: string): boolean;
+};
+
+export default function subscribeMixin<Target extends object>(
+  target: Target
+): Target & SubscriptionMethods {
+  let listeners: EventListeners[] = [];
+
+  return Object.assign(target, {
+    subscribe(listener: EventListeners): void {
+      if (!listeners.includes(listener)) {
+        listeners.push(listener);
+      }
+    },
+
+    unsubscribe(listener: EventListeners): void {
+      const index = listeners.indexOf(listener);
+      if (index >= 0) {
+        listeners.splice(index, 1);
+      }
+    },
+
+    unsubscribeAll(): void {
+      listeners = [];
+    },
+
+    trigger(event: string, ...data: unknown[]): void {
+      for (const listener of [...listeners]) {
+        const handler = listener[event];
+        if (typeof handler === 'function') {
+          try {
+            handler.call(listener, ...data);
+          } catch (error) {
+            log('warn', `Caught exception in listener for event '${event}':`, error);
+          }
+        }
+      }
+    },
+
+    hasSubscribersFor(event: string): boolean {
+      return listeners.some(listener => typeof listener[event] === 'function');
+    }
+  });
+}

package/src/utils/task.ts

@@ -0,0 +1,154 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+/** State shared by cooperative tasks for the current frame. */
+export type TaskState = Record<string, unknown> & {user_moving_view?: boolean};
+
+/** A cooperative task scheduled by the renderer. */
+export interface TaskRecord<Value = unknown> {
+  id?: number;
+  max_time?: number;
+  pause_factor?: number;
+  pause?: number;
+  immediate?: boolean;
+  user_moving_view?: boolean;
+  elapsed?: number;
+  total_elapsed?: number;
+  start_time?: number;
+  tile_id?: unknown;
+  stats?: {calls: number};
+  promise?: Promise<Value | undefined>;
+  resolve?: (value: Value | PromiseLike<Value> | undefined) => void;
+  reject?: (reason?: unknown) => void;
+  run: (task: TaskRecord<Value>) => unknown;
+  cancel?: (task: TaskRecord<Value>) => Value | undefined;
+  [property: string]: unknown;
+}
+
+/** Cooperative renderer task scheduler. */
+export interface TaskManager {
+  id: number;
+  queue: TaskRecord[];
+  max_time: number;
+  start_time: number | null;
+  elapsed?: number;
+  state: TaskState;
+  add<Value>(task: TaskRecord<Value>): Promise<Value | undefined>;
+  remove<Value>(task: TaskRecord<Value>): void;
+  process<Value>(task: TaskRecord<Value>): unknown;
+  processAll(): void;
+  finish<Value>(task: TaskRecord<Value>, value: Value): Promise<Value | undefined>;
+  cancel<Value>(task: TaskRecord<Value>): void;
+  shouldContinue<Value>(task: TaskRecord<Value>): boolean;
+  removeForTile(tileId: unknown): void;
+  setState(state: TaskState): void;
+}
+
+/** Shared renderer task scheduler. */
+export const Task: TaskManager = {
+  id: 0,
+  queue: [],
+  max_time: 20,
+  start_time: null,
+  state: {},
+
+  add<Value>(task: TaskRecord<Value>): Promise<Value | undefined> {
+    task.id = Task.id++;
+    task.max_time = task.max_time || Task.max_time;
+    task.pause_factor = task.pause_factor || 1;
+    task.promise = new Promise((resolve, reject) => {
+      task.resolve = resolve;
+      task.reject = reject;
+    });
+
+    task.elapsed = 0;
+    task.total_elapsed = 0;
+    task.stats = {calls: 0};
+    this.queue.push(task as TaskRecord);
+
+    this.start_time = this.start_time || performance.now();
+    this.elapsed = performance.now() - this.start_time;
+    if (this.elapsed < Task.max_time || task.immediate) {
+      this.process(task);
+    }
+
+    return task.promise;
+  },
+
+  remove<Value>(task: TaskRecord<Value>): void {
+    const index = this.queue.indexOf(task as TaskRecord);
+    if (index > -1) {
+      this.queue.splice(index, 1);
+    }
+  },
+
+  process<Value>(task: TaskRecord<Value>): unknown {
+    if (this.state.user_moving_view && task.user_moving_view === false) {
+      return;
+    }
+
+    if (task.pause) {
+      task.pause--;
+      return true;
+    }
+
+    task.stats!.calls++;
+    task.start_time = performance.now();
+    return task.run(task);
+  },
+
+  processAll(): void {
+    this.start_time = this.start_time || performance.now();
+    for (const task of this.queue) {
+      if (this.process(task) !== true) {
+        if (!task.pause) {
+          task.pause = task.elapsed! > task.max_time! ? task.pause_factor : 0;
+        }
+        task.total_elapsed! += task.elapsed!;
+      }
+
+      this.elapsed = performance.now() - this.start_time;
+      if (this.elapsed >= Task.max_time) {
+        this.start_time = null;
+        break;
+      }
+    }
+  },
+
+  finish<Value>(task: TaskRecord<Value>, value: Value): Promise<Value | undefined> {
+    task.elapsed = performance.now() - task.start_time!;
+    task.total_elapsed! += task.elapsed;
+    this.remove(task as TaskRecord);
+    task.resolve!(value);
+    return task.promise!;
+  },
+
+  cancel<Value>(task: TaskRecord<Value>): void {
+    const value = task.cancel?.(task);
+    task.resolve!(value);
+  },
+
+  shouldContinue<Value>(task: TaskRecord<Value>): boolean {
+    task.elapsed = performance.now() - task.start_time!;
+    this.elapsed = performance.now() - this.start_time!;
+    return task.elapsed < task.max_time! && this.elapsed < Task.max_time;
+  },
+
+  removeForTile(tileId: unknown): void {
+    for (let index = this.queue.length - 1; index >= 0; index--) {
+      const task = this.queue[index];
+      if (task.tile_id === tileId) {
+        this.cancel(task);
+        this.queue.splice(index, 1);
+      }
+    }
+  },
+
+  setState(state: TaskState): void {
+    this.state = state;
+  }
+};
+
+export default Task;

package/src/utils/thread.ts

@@ -0,0 +1,26 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+export type ThreadState = {
+  is_worker: boolean;
+  is_main: boolean;
+};
+
+// Node/SSR is neither a browser main thread nor a Web Worker. In particular,
+// do not install worker-only global shims while a server imports the package.
+const isMain = typeof window !== 'undefined' && typeof Window !== 'undefined' &&
+  typeof HTMLDocument !== 'undefined' && window instanceof Window && window.document instanceof HTMLDocument;
+const isWorker = typeof WorkerGlobalScope !== 'undefined' && globalThis instanceof WorkerGlobalScope;
+const Thread: ThreadState = {is_worker: isWorker, is_main: isMain};
+
+if (isWorker) {
+  // Patch for third-party libraries that require these globals to be present, specifically
+  // FontFaceObserver. This allows that library to load on worker threads.
+  const workerWindow = {document: {}};
+  Reflect.set(globalThis, 'window', workerWindow);
+  Reflect.set(globalThis, 'document', workerWindow.document);
+}
+
+export default Thread;