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

package/src/gl/vbo_mesh.ts

@@ -0,0 +1,349 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+// Manage rendering for primitives
+import type {Buffer, PrimitiveTopology} from '@luma.gl/core';
+import type {TangramMeshBufferOptions, TangramMeshDrawDescriptor} from '../gpu/tangram_gpu_backend';
+import type {MeshContext, MeshVertexData, MeshElementData, MeshVertexLayout, MeshOptions, MeshProgram, MeshRenderOptions, MeshVertexArrays} from './mesh-types';
+import ShaderProgram from './shader_program';
+import VertexArrayObject from './vao';
+import Texture from './texture';
+import {refineGlobeMesh, type GlobeMeshOptions} from './globe_mesh';
+import {notifyGPUResourceDisposal} from '../gpu/resource_lifecycle';
+
+// A single mesh/VBO, described by a vertex layout, that can be drawn with one or more programs
+export default class VBOMesh  {
+    /** Worker variant policy attached by the tile uploader without changing constructor ownership. */
+    declare variant: import('../tile/tile-build-types').TileMeshVariant;
+    /** Optional worker annotation ranges attached during upload. */
+    declare labels?: Record<string, import('../labels/main-pass-types').MeshLabel>;
+    /** Exact ground query channels transferred with the final worker draw mesh. */
+    terrainQueryMesh?: import('../selection/draped-terrain-surface').DrapedTerrainQueryMesh;
+    /** One admitted terrain generation's shared transition origin. */
+    terrainVisibleAt?: number;
+    /** Display blend saved for exact terrain query snapshots. */
+    declare terrainBlend?: number;
+    /** Next automatically assigned mesh identifier. */
+    declare static id: number;
+    declare gl: MeshContext | null;
+    declare vertex_data?: MeshVertexData;
+    declare element_data?: MeshElementData;
+    declare vertex_layout: MeshVertexLayout;
+    declare id: string | number;
+    declare buffer_factory: MeshOptions['bufferFactory'];
+    declare vertex_buffer_resource: Buffer | null;
+    declare element_buffer_resource?: Buffer | null;
+    declare vertex_buffer: Buffer | WebGLBuffer | null;
+    declare element_buffer?: Buffer | WebGLBuffer | null;
+    declare draw_mode: number;
+    declare data_usage: number | null;
+    declare vertices_per_geometry: number;
+    declare uniforms: MeshOptions['uniforms'];
+    declare textures: MeshOptions['textures'];
+    declare retain: boolean;
+    declare fade_in_time: number;
+    declare globe_refinement_error: string | undefined;
+    declare vertex_count: number;
+    declare element_count: number;
+    declare element_type: number;
+    declare vaos: MeshVertexArrays;
+    declare toggle_element_array: boolean;
+    declare valid: boolean;
+
+    /** Vertex/index allocation bytes, excluding textures and projection-specific child meshes. */
+    declare buffer_size: number;
+
+    /** Triangle count of the original planar mesh. */
+    geometry_count: number;
+    /** Shared fade origin for planar and globe variants. */
+    created_at: number;
+    /** Lazily allocated globe buffers, owned by this mesh. */
+    globe_mesh?: VBOMesh | null;
+    /** Immutable coarse tile data, released once refinement completes. */
+    globe_source?: {
+        vertices: MeshVertexData;
+        indices: MeshElementData;
+        options: MeshOptions & {globeRefinement: GlobeMeshOptions};
+    };
+
+    constructor(gl: MeshContext | null, vertex_data: MeshVertexData, element_data: MeshElementData, vertex_layout: MeshVertexLayout, options?: MeshOptions) {
+        options = options || {};
+
+        this.gl = gl;
+        this.vertex_data = vertex_data; // typed array
+        this.element_data = element_data; // typed array
+        this.vertex_layout = vertex_layout;
+        this.id = options.id != null ? options.id : VBOMesh.id++;
+        this.buffer_factory = options.bufferFactory;
+        this.vertex_buffer_resource = createBufferResource(this.buffer_factory, {
+            id: `mesh-${this.id}-vertices`,
+            usage: 'vertex',
+            data: this.vertex_data
+        });
+        this.vertex_buffer = this.vertex_buffer_resource || this.gl!.createBuffer();
+        this.buffer_size = this.vertex_data.byteLength;
+        this.draw_mode = options.draw_mode || 0x0004;
+        this.data_usage = options.data_usage || (this.vertex_buffer_resource ? null : this.gl!.STATIC_DRAW);
+        this.vertices_per_geometry = 3; // TODO: support lines, strip, fan, etc.
+        this.uniforms = options.uniforms;
+        this.textures = options.textures; // any textures owned by this mesh
+        this.retain = options.retain || false; // whether to retain mesh data in CPU after uploading to GPU
+        this.created_at = +new Date();
+        this.fade_in_time = options.fade_in_time || 0; // optional time to fade in mesh
+        this.globe_refinement_error = options.globeRefinementError;
+        // Only coarse, immutable triangle meshes need a second projection-specific buffer.
+        if (options.globeRefinement && options.globeRefinement.tileZoom < 7 &&
+            this.draw_mode === 0x0004 && !this.retain) {
+            this.globe_source = {vertices: vertex_data, indices: element_data, options: options as MeshOptions & {globeRefinement: GlobeMeshOptions}};
+        }
+
+        this.vertex_count = this.vertex_data.byteLength / this.vertex_layout.stride;
+        this.element_count = 0;
+        this.vaos = {}; // map of VertexArrayObjects, keyed by program
+
+        this.toggle_element_array = false;
+        if (this.element_data) {
+            this.toggle_element_array = true;
+            this.element_count = this.element_data.length;
+            this.geometry_count = this.element_count / this.vertices_per_geometry;
+            this.element_type = (this.element_data.constructor === Uint16Array) ? 0x1403 : 0x1405;
+            try {
+                this.element_buffer_resource = createBufferResource(this.buffer_factory, {
+                    id: `mesh-${this.id}-indices`,
+                    usage: 'index',
+                    indexType: this.element_data.constructor === Uint16Array ? 'uint16' : 'uint32',
+                    data: this.element_data
+                });
+            }
+            catch (error) {
+                if (this.vertex_buffer_resource) {
+                    this.vertex_buffer_resource.destroy();
+                    this.vertex_buffer_resource = null;
+                }
+                throw error;
+            }
+            this.element_buffer = this.element_buffer_resource || this.gl!.createBuffer();
+            this.buffer_size += this.element_data.byteLength;
+            if (!this.element_buffer_resource) {
+                this.gl!.bindBuffer(this.gl!.ELEMENT_ARRAY_BUFFER, this.element_buffer as WebGLBuffer | null);
+                this.gl!.bufferData(this.gl!.ELEMENT_ARRAY_BUFFER, this.element_data, this.data_usage!);
+            }
+        }
+        else {
+            this.geometry_count = this.vertex_count / this.vertices_per_geometry;
+        }
+
+        if (!this.vertex_buffer_resource) {
+            this.upload();
+        }
+
+        if (!this.retain) {
+            delete this.vertex_data;
+            delete this.element_data;
+        }
+        this.valid = true;
+    }
+
+    // Render, by default with currently bound program, or otherwise with optionally provided one
+    // Returns true if mesh requests a render on next frame (e.g. for fade animations)
+    render(options: MeshRenderOptions = {}): boolean {
+        if (!this.valid) {
+            return false;
+        }
+
+        if (options.projection === 'globe') {
+            if (this.globe_refinement_error) {
+                throw new Error(this.globe_refinement_error);
+            }
+            if (this.globe_source && this.globe_mesh === undefined) {
+                const {vertices, indices, options: meshOptions} = this.globe_source;
+                const refined = refineGlobeMesh(vertices as Uint8Array, indices as Uint16Array | Uint32Array | false,
+                    this.vertex_layout as MeshVertexLayout & {dynamic_attribs: NonNullable<MeshVertexLayout['dynamic_attribs']>}, meshOptions.globeRefinement);
+                this.globe_mesh = refined.vertices === vertices ? null : new VBOMesh(
+                    this.gl, refined.vertices, refined.indices, this.vertex_layout,
+                    {...meshOptions, id: undefined, globeRefinement: undefined, textures: undefined}
+                );
+                if (this.globe_mesh) {
+                    this.globe_mesh.created_at = this.created_at;
+                }
+                // A completed refinement no longer needs the duplicate CPU data.
+                delete this.globe_source;
+            }
+            if (this.globe_mesh) {
+                return this.globe_mesh.render(options);
+            }
+        }
+
+        var program: MeshProgram = (options.program || ShaderProgram.current)!;
+        let visible_time = (+new Date() - this.created_at) / 1000;
+        if (options.meshRenderer && typeof options.meshRenderer.drawMesh === 'function') {
+            const needs_redraw = options.meshRenderer.drawMesh({
+                mesh: this,
+                program,
+                renderPass: options.renderPass!,
+                renderState: options.renderState,
+                visibleTime: visible_time
+            });
+            if (needs_redraw !== null) {
+                return Boolean(needs_redraw) || visible_time < this.fade_in_time;
+            }
+        }
+
+        program.use(options.meshRenderer ? { bindUniformBlocks: true } : undefined);
+
+        if (this.uniforms) {
+            program.saveUniforms(this.uniforms);
+            program.setUniforms(this.uniforms, false); // don't reset texture unit
+        }
+
+        program.uniform('1f', 'u_visible_time', visible_time);
+
+        this.bind(program);
+
+        if (this.toggle_element_array){
+            this.gl!.drawElements(this.draw_mode, this.element_count, this.element_type, 0);
+        }
+        else {
+            this.gl!.drawArrays(this.draw_mode, 0, this.vertex_count);
+        }
+
+        VertexArrayObject.bind(this.gl!, null);
+
+        if (this.uniforms) {
+            program.restoreUniforms(this.uniforms);
+        }
+
+        // Request next render if mesh is fading in
+        return (visible_time < this.fade_in_time);
+    }
+
+    // Return the renderer-independent resources and draw parameters for this mesh.
+    getDrawDescriptor(): TangramMeshDrawDescriptor & {indexType: 'uint16' | 'uint32' | null} {
+        return {
+            topology: getTopology(this.draw_mode),
+            vertexCount: this.vertex_count,
+            indexCount: this.element_count,
+            indexType: this.toggle_element_array ?
+                (this.element_type === 0x1403 ? 'uint16' : 'uint32') : null,
+            vertexBuffer: this.vertex_buffer_resource,
+            indexBuffer: this.element_buffer_resource || null,
+            bufferLayout: this.vertex_layout.getBufferLayout(),
+            staticAttributes: this.vertex_layout.getStaticAttributes()
+        };
+    }
+
+    // Bind buffers and vertex attributes to prepare for rendering
+    bind(program: MeshProgram): void {
+        // Bind VAO for this progam, or create one
+        let vao = this.vaos[program.id];
+        if (vao) {
+            VertexArrayObject.bind(this.gl!, vao);
+        }
+        else {
+            this.vaos[program.id] = VertexArrayObject.create(this.gl!, () => {
+                this.gl!.bindBuffer(this.gl!.ARRAY_BUFFER, this.vertex_buffer as WebGLBuffer | null);
+                if (this.toggle_element_array) {
+                    this.gl!.bindBuffer(this.gl!.ELEMENT_ARRAY_BUFFER, this.element_buffer as WebGLBuffer | null);
+                }
+                this.vertex_layout.enableDynamicAttributes!(this.gl!, program);
+            });
+        }
+
+        this.vertex_layout.enableStaticAttributes!(this.gl!, program);
+    }
+
+    // Upload buffer data to GPU
+    upload(): void {
+        if (this.vertex_buffer_resource) {
+            if (typeof this.vertex_buffer_resource.write !== 'function') {
+                throw new Error('VBOMesh: portable vertex buffers must support write');
+            }
+            this.vertex_buffer_resource.write(this.vertex_data!);
+            return;
+        }
+        this.gl!.bindBuffer(this.gl!.ARRAY_BUFFER, this.vertex_buffer as WebGLBuffer | null);
+        this.gl!.bufferData(this.gl!.ARRAY_BUFFER, this.vertex_data!, this.data_usage!);
+    }
+
+    destroy(): boolean {
+        this.terrainQueryMesh = undefined;
+        if (!this.valid) {
+            return false;
+        }
+        this.valid = false;
+        try {
+            notifyGPUResourceDisposal(this);
+        }
+        finally {
+            this.globe_mesh?.destroy();
+            this.globe_mesh = null;
+            delete this.globe_source;
+
+            for (let v in this.vaos) {
+                VertexArrayObject.destroy(this.gl!, this.vaos[v]);
+            }
+
+            if (this.vertex_buffer_resource) {
+                this.vertex_buffer_resource.destroy();
+                this.vertex_buffer_resource = null;
+            }
+            else {
+                this.gl!.deleteBuffer(this.vertex_buffer as WebGLBuffer | null);
+            }
+            this.vertex_buffer = null;
+
+            if (this.element_buffer) {
+                if (this.element_buffer_resource) {
+                    this.element_buffer_resource.destroy();
+                    this.element_buffer_resource = null;
+                }
+                else {
+                    this.gl!.deleteBuffer(this.element_buffer as WebGLBuffer | null);
+                }
+                this.element_buffer = null;
+            }
+
+            delete this.vertex_data;
+            delete this.element_data;
+
+            if (this.textures) {
+                this.textures.forEach(t => Texture.release(t));
+            }
+        }
+
+        return true;
+    }
+
+}
+
+VBOMesh.id = 0;
+
+function createBufferResource(buffer_factory: MeshOptions['bufferFactory'], options: TangramMeshBufferOptions): Buffer | null {
+    if (typeof buffer_factory !== 'function') {
+        return null;
+    }
+    const resource = buffer_factory(options);
+    if (!resource || typeof resource.destroy !== 'function') {
+        throw new Error('VBOMesh: bufferFactory must return a GPU resource with destroy');
+    }
+    return resource;
+}
+
+function getTopology(draw_mode: number): PrimitiveTopology {
+    switch (draw_mode) {
+    case 0x0000:
+        return 'point-list';
+    case 0x0001:
+        return 'line-list';
+    case 0x0003:
+        return 'line-strip';
+    case 0x0004:
+        return 'triangle-list';
+    case 0x0005:
+        return 'triangle-strip';
+    default:
+        throw new Error(`VBOMesh: unsupported draw mode ${draw_mode}`);
+    }
+}

package/src/gl/vertex-constants.ts

@@ -0,0 +1,19 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Packed signed-short height units per physical meter, shared by builders and optional projection workers. */
+export const PACKED_HEIGHT_SCALE = 16;
+
+/** Validate physical annotation meters before signed-short storage can silently wrap. */
+export function packProjectedAnnotationHeight(height: unknown, allowElevation = false): number {
+    const meters = height ?? 0;
+    if (typeof meters !== 'number' || !Number.isFinite(meters)) {
+        throw new Error('Projected annotation height must be finite meters');
+    }
+    if (meters !== 0 && !allowElevation) throw new Error('Projected symbols require ground anchors unless allowElevation is enabled');
+    if (meters < -32768 / PACKED_HEIGHT_SCALE || meters > 32767 / PACKED_HEIGHT_SCALE) {
+        throw new Error('Projected annotation height exceeds signed-short storage');
+    }
+    return Math.trunc(meters * PACKED_HEIGHT_SCALE);
+}

package/src/gl/vertex-types.ts

@@ -0,0 +1,35 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {BufferLayout, VertexFormat} from '@luma.gl/core';
+
+/** Numeric views used to pack Tangram's heterogeneous interleaved vertex data. */
+export type VertexArray = Float32Array | Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array;
+/** Views of the same backing allocation indexed by legacy GL component type. */
+export type VertexBufferViews = Record<number, VertexArray>;
+/** Generated writer preserving component offsets and packed conversion semantics. */
+export type AddVertexFunction = (vertex: number[], views: VertexBufferViews, offset: number) => void;
+/** Authored attribute plus the offsets populated by VertexLayout construction. */
+export interface VertexAttribute {
+    name: string;
+    size: number;
+    type: number;
+    normalized?: boolean;
+    static?: number | number[] | null;
+    offset?: number;
+    byte_size?: number;
+    method?: `vertexAttrib${1 | 2 | 3 | 4}fv`;
+}
+/** Portable layout returned after all dynamic attribute offsets are assigned. */
+export type VertexBufferLayout = BufferLayout & {
+    attributes: {attribute: string; format: VertexFormat; byteOffset: number}[];
+};
+/** Shader-side attribute lookup consumed by the classic binding path. */
+export interface VertexAttributeProgram {
+    attribute(name: string): {location: number} | undefined;
+}
+/** Classic WebGL operations consumed by layouts; portable devices bypass this surface. */
+export type VertexAttributeContext = Pick<WebGLRenderingContext,
+    'enableVertexAttribArray' | 'disableVertexAttribArray' | 'vertexAttribPointer'> &
+    Partial<Record<`vertexAttrib${1 | 2 | 3 | 4}fv`, (location: number, value: number[]) => void>>;

package/src/gl/vertex_data.ts

@@ -0,0 +1,126 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import gl from './constants'; // web workers don't have access to GL context, so import all GL constants
+import log from '../utils/log';
+import VertexElements from './vertex_elements';
+import type {VertexAttribute, AddVertexFunction, VertexBufferViews} from './vertex-types';
+
+type VertexLayoutLike = {
+    stride: number;
+    index: Record<string, number>;
+    dynamic_attribs: VertexAttribute[];
+    getAddVertexFunction(): AddVertexFunction;
+};
+
+// Maps GL types to JS array types
+let array_types = {
+    [gl.FLOAT]: Float32Array,
+    [gl.BYTE]: Int8Array,
+    [gl.UNSIGNED_BYTE]: Uint8Array,
+    [gl.INT]: Int32Array,
+    [gl.UNSIGNED_INT]: Uint32Array,
+    [gl.SHORT]: Int16Array,
+    [gl.UNSIGNED_SHORT]: Uint16Array
+};
+
+// An intermediary object that holds vertex data in typed arrays, according to a given vertex layout
+// Used to construct a mesh/VBO for rendering
+export default class VertexData {
+
+    static array_pool: Uint8Array[] = [];
+    vertex_layout: VertexLayoutLike;
+    vertex_elements: VertexElements;
+    stride: number;
+    vertex_buffer: Uint8Array;
+    element_buffer!: Uint16Array | Uint32Array | false;
+    byte_length: number;
+    size: number;
+    offset: number;
+    vertex_count: number;
+    realloc_count: number;
+    views!: VertexBufferViews;
+    vertexLayoutAddVertex!: AddVertexFunction;
+
+    constructor (vertex_layout: VertexLayoutLike, { prealloc = 500 }: {prealloc?: number} = {}) {
+        this.vertex_layout = vertex_layout;
+        this.vertex_elements = new VertexElements();
+        this.stride = this.vertex_layout.stride;
+
+        if (VertexData.array_pool.length > 0) {
+            this.vertex_buffer = VertexData.array_pool.pop()!;
+            this.byte_length = this.vertex_buffer.byteLength;
+            this.size = Math.floor(this.byte_length / this.stride);
+            log('trace', `VertexData: reused buffer of bytes ${this.byte_length}, ${this.size} vertices`);
+        }
+        else {
+            this.size = prealloc; // # of vertices to allocate
+            this.byte_length = this.stride * this.size;
+            this.vertex_buffer = new Uint8Array(this.byte_length);
+        }
+        this.offset = 0;             // byte offset into currently allocated buffer
+
+        this.vertex_count = 0;
+        this.realloc_count = 0;
+        this.setBufferViews();
+        this.setAddVertexFunction();
+    }
+
+    // (Re-)allocate typed views into the main buffer - only create the types we need for this layout
+    setBufferViews (): void {
+        this.views = {};
+        this.views[gl.UNSIGNED_BYTE] = this.vertex_buffer;
+        this.vertex_layout.dynamic_attribs.forEach(attrib => {
+            // Need view for this type?
+            if (this.views[attrib.type] == null) {
+                const arrayType = array_types[attrib.type];
+                this.views[attrib.type] = new arrayType(this.vertex_buffer.buffer as ArrayBuffer);
+            }
+        });
+    }
+
+    // Check allocated buffer size, expand/realloc buffer if needed
+    checkBufferSize (): void {
+        if ((this.offset + this.stride) > this.byte_length) {
+            this.size = Math.floor(this.size * 1.5);
+            this.size -= this.size % 4;
+            this.byte_length = this.stride * this.size;
+            var new_view = new Uint8Array(this.byte_length);
+            new_view.set(this.vertex_buffer); // copy existing data to new buffer
+            VertexData.array_pool.push(this.vertex_buffer); // save previous buffer for use by next tile
+            this.vertex_buffer = new_view;
+            this.setBufferViews();
+            this.realloc_count++;
+            // log('info', `VertexData: expanded vertex block to ${this.size} vertices`);
+        }
+    }
+
+    // Initialize the add vertex function (lazily compiled by vertex layout)
+    setAddVertexFunction (): void {
+        this.vertexLayoutAddVertex = this.vertex_layout.getAddVertexFunction();
+    }
+
+    // Add a vertex, copied from a plain JS array of elements matching the order of the vertex layout
+    addVertex (vertex: number[]): void {
+        this.checkBufferSize();
+        this.vertexLayoutAddVertex(vertex, this.views, this.offset);
+        this.offset += this.stride;
+        this.vertex_count++;
+    }
+
+    // Finalize vertex buffer for use in constructing a mesh
+    end (): this {
+        // Clip the buffer to size used for this VBO
+        this.vertex_buffer = this.vertex_buffer.subarray(0, this.offset);
+        this.element_buffer = this.vertex_elements.end();
+
+        log('trace', `VertexData: ${this.size} vertices total, realloc count ${this.realloc_count}`);
+
+        return this;
+    }
+
+}
+
+// Pool of currently available (previously used) buffers (uint8).

package/src/gl/vertex_elements.ts

@@ -0,0 +1,54 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+let MAX_VALUE = Math.pow(2, 16) - 1;
+let has_element_index_uint = false;
+
+export default class VertexElements {
+    static setElementIndexUint: (flag: boolean) => void;
+    array: number[];
+    has_overflown: boolean;
+
+    constructor () {
+        this.array = [];
+        this.has_overflown = false;
+    }
+    push (value: number): void {
+        // If values have overflown and no Uint32 option is available, do not push values
+        if (this.has_overflown && !has_element_index_uint) {
+            return;
+        }
+
+        // Trigger overflow if value is greater than Uint16 max
+        if (value > MAX_VALUE) {
+            this.has_overflown = true;
+            if (!has_element_index_uint) {
+                return;
+            }
+        }
+
+        this.array.push(value);
+    }
+    end (): Uint16Array | Uint32Array | false {
+        if (this.array.length){
+            let buffer = createBuffer(this.array, this.has_overflown);
+            this.array = [];
+            this.has_overflown = false;
+            return buffer;
+        }
+        else {
+            return false;
+        }
+    }
+}
+
+VertexElements.setElementIndexUint = function(flag: boolean): void {
+    has_element_index_uint = flag;
+};
+
+function createBuffer(array: number[], overflown: boolean): Uint16Array | Uint32Array {
+    var typedArray = (overflown && has_element_index_uint) ? Uint32Array : Uint16Array;
+    return new typedArray(array);
+}