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

package/src/gl/globe_mesh.ts

@@ -0,0 +1,285 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type VertexLayout from './vertex_layout';
+
+type VertexAttribute = VertexLayout['dynamic_attribs'][number];
+
+/** Packed triangle data after projection-aware refinement. */
+export type GlobeMeshData = {
+    /** Interleaved vertices, with the original vertices retained at their original indices. */
+    vertices: Uint8Array;
+    /** Triangle indices, promoted to 32 bits when necessary. */
+    indices: Uint16Array | Uint32Array;
+};
+
+/** Limits for globe refinement in Tangram tile-local coordinates. */
+export type GlobeMeshOptions = {
+    /** Actual source tile zoom, not the style zoom. */
+    tileZoom: number;
+    /** Tile-local units per tile edge. */
+    tileScale?: number;
+    /** Maximum Mercator angular edge span; conservatively bounds spherical span. */
+    maxAngularSpan?: number;
+    /** Maximum additional vertices; additional triangles are limited to twice this budget. */
+    maxAdditionalVertices?: number;
+    /** Optional expanded tile-space position for packed ribbons; never changes the preserved attributes. */
+    getPosition?: (vertex: DataView) => [number, number];
+    /** Optional packed height for topology checks on elevated surfaces; curvature still uses XY. */
+    getElevation?: (vertex: DataView) => number;
+    /** Optional additional edge decision; callers must use the same criterion across adjacent meshes. */
+    shouldSplitEdge?: (first: DataView, second: DataView) => boolean;
+    /** Fan partial-edge refinements around an interior vertex instead of introducing a long diagonal. */
+    splitRemainderInterior?: boolean;
+    /** Choose the shorter green-refinement diagonal; useful for floating terrain ribbons and thin MVT faces. */
+    splitRemainderShortest?: boolean;
+};
+
+const INTERPOLATED_ATTRIBUTES = new Set([
+    'a_position', 'a_normal', 'a_color', 'a_texcoord', 'a_extrude', 'a_offset',
+    'a_z_and_offset_scale', 'a_projected_position', 'a_projected_normal', 'a_projected_stroke', 'a_projected_normals', 'a_projected_widths'
+]);
+
+/**
+ * Split long triangle edges before spherical projection. Shared indexed edges share
+ * midpoints; independent tile edges use the same quantized midpoint rule. Selection
+ * IDs and layer order remain flat. Unknown varying attributes are rejected rather
+ * than guessing their interpolation semantics. Camera state is deliberately absent.
+ */
+export function refineGlobeMesh(
+    vertices: Uint8Array,
+    indices: Uint16Array | Uint32Array | false,
+    layout: {stride: number; dynamic_attribs: VertexAttribute[]},
+    options: GlobeMeshOptions
+): GlobeMeshData {
+    const tileScale = options.tileScale ?? 4096;
+    const angularSpan = options.maxAngularSpan ?? 4;
+    const budget = options.maxAdditionalVertices ?? 262144;
+    if (!Number.isInteger(options.tileZoom) || options.tileZoom < 0 || options.tileZoom > 30 ||
+        !Number.isFinite(tileScale) || tileScale <= 0 ||
+        !Number.isFinite(angularSpan) || angularSpan <= 0 || angularSpan > 180 ||
+        !Number.isInteger(budget) || budget < 0) {
+        throw new RangeError('Globe mesh: invalid refinement limits');
+    }
+    const maximumEdge = tileScale * 2 ** options.tileZoom * angularSpan / 360;
+    if (maximumEdge < 2) {
+        throw new RangeError('Globe mesh: refinement exceeds packed position precision');
+    }
+    const position = layout.dynamic_attribs.find(attribute => attribute.name === 'a_position');
+    if (!position || position.size < 2 || position.offset === undefined ||
+        layout.stride <= 0 || vertices.byteLength % layout.stride !== 0) {
+        throw new Error('Globe mesh: an aligned position layout is required');
+    }
+    const originalCount = vertices.byteLength / layout.stride;
+    const triangleIndices = indices || Uint32Array.from({length: originalCount}, (_, index) => index);
+    if (triangleIndices.length % 3 !== 0 || triangleIndices.some(index => index >= originalCount)) {
+        throw new Error('Globe mesh: invalid triangle indices');
+    }
+    const records: Uint8Array[] = [];
+    const positions: [number, number][] = [];
+    for (let index = 0; index < originalCount; index++) {
+        const record = vertices.subarray(index * layout.stride, (index + 1) * layout.stride);
+        records.push(record);
+        const view = new DataView(record.buffer, record.byteOffset, record.byteLength);
+        const point: [number, number] = options.getPosition ? options.getPosition(view) :
+            [readComponent(view, position, 0), readComponent(view, position, 1)];
+        if (!point.every(Number.isFinite)) {
+            throw new Error('Globe mesh: nonfinite position');
+        }
+        positions.push(point);
+    }
+    const midpoints = new Map<string, number>();
+    const output: number[] = [];
+    const pending: number[][] = [];
+    const maximumTriangles = triangleIndices.length / 3 + budget * 2;
+    // A LIFO worklist must start in reverse to preserve source triangle/feature draw order.
+    for (let index = triangleIndices.length - 3; index >= 0; index -= 3) {
+        pending.push([triangleIndices[index], triangleIndices[index + 1], triangleIndices[index + 2]]);
+    }
+    const isLong = (first: number, second: number): boolean => {
+        const distance = Math.hypot(positions[first][0] - positions[second][0], positions[first][1] - positions[second][1]);
+        return distance > maximumEdge || (distance >= 2 && Boolean(options.shouldSplitEdge?.(
+            new DataView(records[first].buffer, records[first].byteOffset, layout.stride),
+            new DataView(records[second].buffer, records[second].byteOffset, layout.stride))));
+    };
+    const getMidpoint = (first: number, second: number): number => {
+        const key = `${Math.min(first, second)}:${Math.max(first, second)}`;
+        const cached = midpoints.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        if (records.length >= originalCount + budget) {
+            throw new RangeError('Globe mesh: refinement vertex budget exceeded');
+        }
+        const record = interpolatePackedVertex(records[first], records[second], layout, 0.5);
+        const outputView = new DataView(record.buffer);
+        const midpoint = records.length;
+        records.push(record);
+        positions.push(options.getPosition ? options.getPosition(outputView) :
+            [readComponent(outputView, position, 0), readComponent(outputView, position, 1)]);
+        midpoints.set(key, midpoint);
+        return midpoint;
+    };
+    while (pending.length) {
+        const triangle = pending.pop()!;
+        const [first, second, third] = triangle;
+        const split = [isLong(first, second), isLong(second, third), isLong(third, first)];
+        const count = split.filter(Boolean).length;
+        if (count === 0) {
+            output.push(first, second, third);
+        }
+        else if (count === 3) {
+            const firstMidpoint = getMidpoint(first, second);
+            const secondMidpoint = getMidpoint(second, third);
+            const thirdMidpoint = getMidpoint(third, first);
+            pending.push([first, firstMidpoint, thirdMidpoint], [firstMidpoint, second, secondMidpoint],
+                [thirdMidpoint, secondMidpoint, third], [firstMidpoint, secondMidpoint, thirdMidpoint]);
+        }
+        else {
+            // Rotate the triangle to place the single split (or unsplit) edge first.
+            const edge = split.findIndex(value => value === (count === 1));
+            const start = triangle[edge];
+            const end = triangle[(edge + 1) % 3];
+            const opposite = triangle[(edge + 2) % 3];
+            if (options.splitRemainderInterior) {
+                // Repeated green triangulation can alternate long diagonals
+                // without converging. A centroid fan contracts interior edges
+                // and leaves every shared boundary midpoint unchanged.
+                const boundary = [start];
+                if (split[edge]) boundary.push(getMidpoint(start, end));
+                boundary.push(end);
+                if (split[(edge + 1) % 3]) boundary.push(getMidpoint(end, opposite));
+                boundary.push(opposite);
+                if (split[(edge + 2) % 3]) boundary.push(getMidpoint(opposite, start));
+                if (records.length >= originalCount + budget) {
+                    throw new RangeError('Globe mesh: refinement vertex budget exceeded');
+                }
+                const record = interpolatePackedVertex(
+                    interpolatePackedVertex(records[start], records[end], layout, 0.5),
+                    records[opposite], layout, 1 / 3);
+                const view = new DataView(record.buffer);
+                const point: [number, number] = options.getPosition ? options.getPosition(view) :
+                    [readComponent(view, position, 0), readComponent(view, position, 1)];
+                const cross = (first: number[], second: number[], third: number[]): number =>
+                    (second[0] - first[0]) * (third[1] - first[1]) - (second[1] - first[1]) * (third[0] - first[0]);
+                const topologyPosition = (index: number): [number, number, number] => [
+                    ...positions[index], options.getElevation?.(new DataView(records[index].buffer,
+                        records[index].byteOffset, layout.stride)) ?? 0];
+                const corners = [start, end, opposite].map(topologyPosition);
+                const axes = selectTrianglePlane(corners);
+                const flatten = (position: readonly [number, number, number]): [number, number] =>
+                    [position[axes[0]], position[axes[1]]];
+                const centerPoint = flatten([...point, options.getElevation?.(view) ?? 0]);
+                const orientation = cross(flatten(corners[0]), flatten(corners[1]), flatten(corners[2]));
+                if (boundary.some((corner, boundaryEdge) =>
+                    cross(flatten(topologyPosition(corner)), flatten(topologyPosition(boundary[(boundaryEdge + 1) % boundary.length])), centerPoint) * orientation <= 0)) {
+                    throw new RangeError('Globe mesh: refinement exceeds packed position precision');
+                }
+                const center = records.length;
+                records.push(record);
+                positions.push(point);
+                for (let boundaryEdge = 0; boundaryEdge < boundary.length; boundaryEdge++) {
+                    pending.push([boundary[boundaryEdge], boundary[(boundaryEdge + 1) % boundary.length], center]);
+                }
+            }
+            else if (count === 1) {
+                const midpoint = getMidpoint(start, end);
+                pending.push([start, midpoint, opposite], [midpoint, end, opposite]);
+            }
+            else {
+                const endMidpoint = getMidpoint(end, opposite);
+                const startMidpoint = getMidpoint(opposite, start);
+                const distance = (first: number, second: number) => Math.hypot(positions[first][0] - positions[second][0], positions[first][1] - positions[second][1]);
+                pending.push([opposite, startMidpoint, endMidpoint]);
+                if (options.splitRemainderShortest && distance(start, endMidpoint) < distance(end, startMidpoint)) {
+                    pending.push([start, end, endMidpoint], [start, endMidpoint, startMidpoint]);
+                } else {
+                    pending.push([start, end, startMidpoint], [end, endMidpoint, startMidpoint]);
+                }
+            }
+        }
+        if (pending.length + output.length / 3 > maximumTriangles) {
+            throw new RangeError('Globe mesh: refinement triangle budget exceeded');
+        }
+    }
+    if (records.length === originalCount) {
+        return {vertices, indices: triangleIndices};
+    }
+    const refinedVertices = new Uint8Array(records.length * layout.stride);
+    records.forEach((record, index) => refinedVertices.set(record, index * layout.stride));
+    return {
+        vertices: refinedVertices,
+        indices: records.length <= 65536 ? new Uint16Array(output) : new Uint32Array(output)
+    };
+}
+
+/** Choose the dominant source-space plane so vertical walls retain the same packed-precision checks as roofs. */
+export function selectTrianglePlane(points: readonly (readonly [number, number, number])[]): readonly [0 | 1 | 2, 0 | 1 | 2] {
+    const planes = [[0, 1], [0, 2], [1, 2]] as const;
+    let selected: typeof planes[number] = planes[0];
+    let maximumArea = 0;
+    for (const plane of planes) {
+        const [first, second] = plane;
+        const area = Math.abs((points[1][first] - points[0][first]) * (points[2][second] - points[0][second]) -
+            (points[1][second] - points[0][second]) * (points[2][first] - points[0][first]));
+        if (area > maximumArea) {maximumArea = area; selected = plane;}
+    }
+    return selected;
+}
+
+/** Preserve Tangram's packed interpolation and flat IDs at refinement or clipping intersections. */
+export function interpolatePackedVertex(first: Uint8Array, second: Uint8Array,
+    layout: {stride: number; dynamic_attribs: VertexAttribute[]}, fraction: number): Uint8Array {
+    const record = first.slice();
+    const firstView = new DataView(first.buffer, first.byteOffset, layout.stride);
+    const secondView = new DataView(second.buffer, second.byteOffset, layout.stride);
+    const outputView = new DataView(record.buffer);
+    for (const attribute of layout.dynamic_attribs) {
+        for (let component = 0; component < attribute.size; component++) {
+            const firstValue = readComponent(firstView, attribute, component);
+            const secondValue = readComponent(secondView, attribute, component);
+            const flat = attribute.name === 'a_selection_color' || (attribute.name === 'a_position' && component === 3);
+            if (flat || !INTERPOLATED_ATTRIBUTES.has(attribute.name)) {
+                if (firstValue !== secondValue) throw new Error(`Globe mesh: varying flat attribute ${attribute.name} is unsupported`);
+            }
+            else {
+                // Keep the exact existing midpoint arithmetic, including integer rounding.
+                writeComponent(outputView, attribute, component, fraction === 0.5 ?
+                    (firstValue + secondValue) / 2 : firstValue * (1 - fraction) + secondValue * fraction);
+            }
+        }
+    }
+    return record;
+}
+
+/** Read a component without assuming the interleaved buffer starts at byte zero. */
+function readComponent(view: DataView, attribute: VertexAttribute, component: number): number {
+    const offset = attribute.offset ?? 0;
+    switch (attribute.type) {
+    case 0x1400: return view.getInt8(offset + component);
+    case 0x1401: return view.getUint8(offset + component);
+    case 0x1402: return view.getInt16(offset + component * 2, true);
+    case 0x1403: return view.getUint16(offset + component * 2, true);
+    case 0x1404: return view.getInt32(offset + component * 4, true);
+    case 0x1405: return view.getUint32(offset + component * 4, true);
+    case 0x1406: return view.getFloat32(offset + component * 4, true);
+    default: throw new Error(`Globe mesh: unsupported attribute type ${attribute.type}`);
+    }
+}
+
+/** Interpolate in the attribute's packed domain, rounding integer coordinates consistently. */
+function writeComponent(view: DataView, attribute: VertexAttribute, component: number, value: number): void {
+    const offset = attribute.offset ?? 0;
+    const integer = Math.round(value);
+    switch (attribute.type) {
+    case 0x1400: view.setInt8(offset + component, integer); break;
+    case 0x1401: view.setUint8(offset + component, integer); break;
+    case 0x1402: view.setInt16(offset + component * 2, integer, true); break;
+    case 0x1403: view.setUint16(offset + component * 2, integer, true); break;
+    case 0x1404: view.setInt32(offset + component * 4, integer, true); break;
+    case 0x1405: view.setUint32(offset + component * 4, integer, true); break;
+    case 0x1406: view.setFloat32(offset + component * 4, value, true); break;
+    default: throw new Error(`Globe mesh: unsupported attribute type ${attribute.type}`);
+    }
+}

package/src/gl/glsl.ts

@@ -0,0 +1,257 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+type UniformValue = number | string | boolean | number[] | string[] | number[][];
+type ParsedUniform = {
+    type: string;
+    method: string;
+    name: string;
+    value: UniformValue;
+    path: (string | number)[];
+};
+
+interface GLSLNamespace {
+    parseUniforms(uniforms?: Record<string, unknown>): ParsedUniform[];
+    defineVariable(name: string, value: unknown): string | undefined;
+    defineUniform(name: string, value: unknown): string | undefined;
+    expandVec3(value: UniformValue, z?: number): number[] | undefined;
+    expandVec4(value: UniformValue, w?: number): number[] | undefined;
+}
+
+const GLSL = {} as GLSLNamespace;
+export default GLSL;
+
+/**
+    Parse uniforms from a JS object, infers types and returns an array of objects with the
+    necessary information to set uniform values on a GL program. Each object in the returned
+    array has the form:
+    { type, method, name, value }
+
+    type: the GL uniform type, such as 'vec3', 'float', etc.
+    method: the GL uniform setter method to use, such as '1f', '3fv', etc.
+    name: the fully qualified name of the GL uniform location, e.g. 'array[0].field', etc.
+    value: the value to be passed to the GL uniform setter for that type, e.g. [1, 2, 3] for a vec3
+
+    Textures have special behavior: uniforms with string values are treated as textures, and
+    the string is used as a unique texture 'key' to be interpreted by the caller (which is responsible
+    for actually setting the uniforms). For example, this could be used as a key into a dictionary of
+    known texture names, or it could simply be used as a URL to dynamically load the texture from.
+*/
+GLSL.parseUniforms = function (uniforms: Record<string, unknown> = {}): ParsedUniform[] {
+    const parsed: ParsedUniform[] = [];
+
+    for (const [name, uniform] of Object.entries(uniforms)) {
+        // Single float
+        if (typeof uniform === 'number') {
+            parsed.push({
+                type: 'float',
+                method: '1f',
+                name,
+                value: uniform,
+                path: [name]
+            });
+        }
+        // Array: vector, array of floats, array of textures
+        else if (Array.isArray(uniform)) {
+            // Numeric values
+            if (typeof uniform[0] === 'number') {
+                // float vectors (vec2, vec3, vec4)
+                if (uniform.length >= 2 && uniform.length <= 4) {
+                    parsed.push({
+                        type: 'vec' + uniform.length,
+                        method: uniform.length + 'fv',
+                        name,
+                        value: uniform,
+                        path: [name]
+                    });
+                }
+                // float array
+                else if (uniform.length > 4) {
+                    parsed.push({
+                        type: 'float[]',
+                        method: '1fv',
+                        name: name + '[0]',
+                        value: uniform,
+                        path: [name]
+                    });
+                }
+                // TODO: assume matrix for (typeof == Float32Array && length == 16)?
+            }
+            // Array of textures
+            else if (typeof uniform[0] === 'string') {
+                for (let u = 0; u < uniform.length; u++) {
+                    parsed.push({
+                        type: 'sampler2D',
+                        method: '1i',
+                        name: name + '[' + u + ']',
+                        value: uniform[u],
+                        path: [name, u]
+                    });
+                }
+            }
+            // Array of arrays - but only arrays of vectors are allowed in this case
+            else if (Array.isArray(uniform[0]) && typeof uniform[0][0] === 'number') {
+                // float vectors (vec2, vec3, vec4)
+                if (uniform[0].length >= 2 && uniform[0].length <= 4) {
+                    // Set each vector in the array
+                    for (let u = 0; u < uniform.length; u++) {
+                        parsed.push({
+                            type: 'vec' + uniform[0].length,
+                            method: uniform[0].length + 'fv',
+                            name: name + '[' + u + ']',
+                            value: uniform[u],
+                            path: [name, u]
+                        });
+                    }
+                }
+            }
+            // TODO: else warning
+        }
+        // Boolean
+        else if (typeof uniform === 'boolean') {
+            parsed.push({
+                type: 'bool',
+                method: '1i',
+                name,
+                value: uniform,
+                path: [name]
+            });
+        }
+        // Texture
+        else if (typeof uniform === 'string') {
+            parsed.push({
+                type: 'sampler2D',
+                method: '1i',
+                name,
+                value: uniform,
+                path: [name]
+            });
+        }
+    }
+
+    return parsed;
+};
+
+/**
+    Generate a GLSL variable definition from a JS object
+*/
+GLSL.defineVariable = function (name: string, value: unknown): string | undefined {
+    let type: string | undefined;
+    let array: number | undefined;
+
+    // Single float
+    if (typeof value === 'number') {
+        type = 'float';
+    }
+    // Multiple floats - vector or array
+    else if (Array.isArray(value)) {
+        // Numeric values
+        if (typeof value[0] === 'number') {
+            // float vectors (vec2, vec3, vec4)
+            if (value.length >= 2 && value.length <= 4) {
+                type = 'vec' + value.length;
+            }
+            // float array
+            else { //if (value.length > 4) {
+                type = 'float';
+                array = value.length;
+            }
+            // TODO: assume matrix for (typeof == Float32Array && length == 16)?
+        }
+        // Array of textures
+        else if (typeof value[0] === 'string') {
+            type = 'sampler2D';
+            array = value.length;
+        }
+        // Array of arrays - but only arrays of vectors are allowed in this case
+        else if (Array.isArray(value[0]) && typeof value[0][0] === 'number') {
+            // float vectors (vec2, vec3, vec4)
+            if (value[0].length >= 2 && value[0].length <= 4) {
+                type = 'vec' + value[0].length;
+                array = value.length;
+            }
+        }
+    }
+    // Boolean
+    else if (typeof value === 'boolean') {
+        type = 'bool';
+    }
+    // Texture
+    else if (typeof value === 'string') {
+        type = 'sampler2D';
+    }
+    else {
+        return; // no valid type found
+    }
+
+    // Construct variable definition
+    var variable = '';
+    variable += `${type} ${name}`;
+    if (array) {
+        variable += `[${array}]`;
+    }
+    variable += ';\n';
+
+    return variable;
+};
+
+/**
+    Generate a GLSL uniform definition from a JS object
+*/
+GLSL.defineUniform = function (name: string, value: unknown): string | undefined {
+    var def = GLSL.defineVariable(name, value);
+    if (!def) {
+        return;
+    }
+    return 'uniform ' + def;
+};
+
+/**
+    Expand a single value or 2-element array into a 3-element array, with the last ( z )
+    coordinate defaulting to 1 (with option to specify). Also runs parseFloat to try to maintain
+    data integrity. Returns null if input couldn't be parsed.
+*/
+GLSL.expandVec3 = function (v: UniformValue, z = 1): number[] | undefined {
+    let x: number[];
+    if (Array.isArray(v)) {
+        if (v.length === 2) {
+            x = [...v, z].map(parseFloat as any);
+        }
+        else {
+            return v as number[];
+        }
+    }
+    else {
+        x = [v, v, v].map(parseFloat as any);
+    }
+
+    if (x && x.every(n => typeof n === 'number' && !isNaN(n))) {
+        return x;
+    }
+};
+
+/**
+    Expand a single value or 3-element array into a 4-element array, with the last (e.g. w or a)
+    coordinate defaulting to 1 (with option to specify). Also runs parseFloat to try to maintain
+    data integrity. Returns null if input couldn't be parsed.
+*/
+GLSL.expandVec4 = function (v: UniformValue, w = 1): number[] | undefined {
+    let x: number[];
+    if (Array.isArray(v)) {
+        if (v.length === 3) {
+            x = [...v, w].map(parseFloat as any);
+        }
+        else {
+            return v as number[];
+        }
+    }
+    else {
+        x = [v, v, v, w].map(parseFloat as any);
+    }
+
+    if (x && x.every(n => typeof n === 'number' && !isNaN(n))) {
+        return x;
+    }
+};

package/src/gl/mesh-types.ts

@@ -0,0 +1,56 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Buffer, RenderPass, RenderPipelineParameters} from '@luma.gl/core';
+import type {GlobeMeshOptions} from './globe_mesh';
+import type {VertexArrayBinding, VertexArrayContext} from './vao';
+import type {VertexAttribute, VertexAttributeProgram, VertexAttributeContext} from './vertex-types';
+import type VBOMesh from './vbo_mesh';
+import type {TangramDrawableProgram, TangramMeshBufferOptions, TangramMeshDrawOptions, TangramMeshDrawDescriptor} from '../gpu/tangram_gpu_backend';
+
+/** Original packed vertex/index bytes retained only when CPU updates or refinement need them. */
+export type MeshVertexData = Uint8Array | Int8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array;
+/** Missing element data means the mesh uses a non-indexed draw. */
+export type MeshElementData = Uint16Array | Uint32Array | false | null | undefined;
+/** The classic mesh path uses raw GL; the portable path needs no GL context. */
+export type MeshContext = Pick<WebGLRenderingContext, 'STATIC_DRAW' | 'ELEMENT_ARRAY_BUFFER' | 'ARRAY_BUFFER' |
+    'createBuffer' | 'bindBuffer' | 'bufferData' | 'drawElements' | 'drawArrays' | 'deleteBuffer'> & VertexArrayContext & VertexAttributeContext;
+/** Layout capabilities shared by device meshes and their classic attribute bindings. */
+export interface MeshVertexLayout {
+    stride: number;
+    /** Packed attribute offsets, absent only for minimal non-annotation layouts. */
+    offset?: Record<string, number>;
+    dynamic_attribs?: VertexAttribute[];
+    getBufferLayout(): TangramMeshDrawDescriptor['bufferLayout'];
+    getStaticAttributes(): {attribute: string; value: number[]}[];
+    enableDynamicAttributes?(context: VertexAttributeContext, program: VertexAttributeProgram): void;
+    enableStaticAttributes?(context: VertexAttributeContext, program: VertexAttributeProgram): void;
+}
+/** Legacy program operations added to the device submission contract. */
+export interface MeshProgram extends TangramDrawableProgram, VertexAttributeProgram {
+    use(options?: {bindUniformBlocks: boolean}): void;
+}
+/** Caller-supplied allocation and owned texture/fade/refinement state. */
+export interface MeshOptions {
+    id?: string | number;
+    bufferFactory?: (options: TangramMeshBufferOptions) => Buffer;
+    draw_mode?: number;
+    data_usage?: number;
+    uniforms?: Record<string, unknown>;
+    textures?: string[];
+    retain?: boolean;
+    fade_in_time?: number;
+    globeRefinement?: GlobeMeshOptions;
+    globeRefinementError?: string;
+}
+/** Per-draw host state; camera projection controls lazy geometry refinement only. */
+export interface MeshRenderOptions {
+    projection?: string;
+    program?: MeshProgram;
+    meshRenderer?: {drawMesh(options: Omit<TangramMeshDrawOptions, 'mesh'> & {mesh: VBOMesh}): boolean | null};
+    renderPass?: RenderPass;
+    renderState?: RenderPipelineParameters;
+}
+/** Classic bindings are opaque to device renderers and keyed by program identity. */
+export type MeshVertexArrays = Record<string | number, VertexArrayBinding>;