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

package/src/tile/tangram_tileset_2d.ts

@@ -0,0 +1,108 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import TileBuildQueue from '../map-logic/tile-build-queue';
+import {TileResidency} from '../map-logic/tile-residency';
+import TileResourceCache from './tile_resource_cache';
+import type {ResourceTile} from './tile_resource_cache';
+import type {HostTileResourceOptions, TileResourceStatistics} from '../types';
+import type {TileCoordinates} from './tile_id';
+
+/** Host-independent traversal/bounds surface shared with loaders.gl's adapter contract. */
+export interface TileTraversalAdapter<ViewStateT> {
+    /** Logical tile indices before source/style normalization. */
+    getTileIndices(context: {viewState: ViewStateT}): TileCoordinates[];
+}
+
+/**
+ * Renderer-independent resident tile table, build scheduling, and cache policy.
+ *
+ * This is a pre-alignment boundary, not a replacement for loaders.gl's Tileset2D.
+ * Tangram's adapter still owns traversal, style keys, refinement, and GPU disposal.
+ */
+export default class TangramTileset2D<TileT extends ResourceTile> {
+    /** Shared submission queue; the adapter reports final worker replies and cancellation. */
+    readonly buildQueue = new TileBuildQueue();
+    /** Legacy keyed table, retained until renderer/worker adapters stop depending on its shape. */
+    tileRecords: Record<string, TileT> = {};
+    /** Recency and mesh-accounting metadata, separate from payload ownership. */
+    private readonly resourceCache = new TileResourceCache();
+    /** Limits already validated and copied by the host-frame boundary. */
+    private resourceLimits?: Readonly<HostTileResourceOptions>;
+    /** Optional shared consumers; the legacy renderer still supplies its own eye union. */
+    private readonly residency = new TileResidency();
+
+    /** Delegate logical selection without importing a View, Scene or host viewport implementation. */
+    getTileIndices<ViewStateT>(context: {viewState: ViewStateT}, adapter: TileTraversalAdapter<ViewStateT>): TileCoordinates[] {
+        return adapter.getTileIndices(context);
+    }
+
+    /** Attach a consumer without changing existing renderer-visible flags. */
+    attachConsumer(id: symbol): void { this.residency.attachConsumer(id); }
+
+    /** Replace one consumer's selections; other views continue protecting their own content. */
+    updateConsumer(id: symbol, selected: readonly string[], visible: readonly string[]): void {
+        this.residency.updateConsumer(id, selected, visible);
+    }
+
+    /** Release only this consumer's protection, never dispose another consumer's content. */
+    detachConsumer(id: symbol): void { this.residency.detachConsumer(id); }
+
+    /** Stable union of requested identities across optional shared consumers. */
+    get selectedTileKeys(): string[] {
+        return this.residency.getSelectedTileKeys();
+    }
+
+    /** Retained tiles in the same stable property order as the legacy manager. */
+    get tiles(): TileT[] { return Object.values(this.tileRecords); }
+
+    /** Retain a renderer-owned tile without submitting work or applying refinement. */
+    setTile(tile: TileT): void {
+        this.tileRecords[tile.key] = tile;
+        this.resourceCache.touch(tile.key);
+    }
+
+    /** Resolve a source/style identity without re-normalizing its data coordinates. */
+    getTile(key: string): TileT | undefined { return this.tileRecords[key]; }
+
+    /** Release ownership, update the adapter's hierarchy, then forget already-disposed content. */
+    forgetTile(key: string, beforeDelete?: (tile: TileT) => void): void {
+        this.buildQueue.cancel(key);
+        this.resourceCache.forget(key);
+        const tile = this.getTile(key);
+        if (tile !== undefined) beforeDelete?.(tile);
+        delete this.tileRecords[key];
+    }
+
+    /** Install a shared policy without submitting old work before a visibility batch is installed. */
+    setOptions(options: Readonly<HostTileResourceOptions> | undefined): void {
+        this.resourceLimits = options;
+        this.buildQueue.setLimit(options?.maxConcurrentBuilds);
+    }
+
+    /** Select eviction candidates; only the renderer adapter may dispose payload resources. */
+    getEvictionKeys(isPinned: (key: string) => boolean): string[] {
+        const tiles = this.tiles;
+        const isProtected = (key: string): boolean => isPinned(key) || this.buildQueue.has(key) || this.residency.isProtected(key);
+        for (const tile of tiles) {
+            if (this.resourceCache.isProtected(tile, isProtected)) this.resourceCache.touch(tile.key);
+        }
+        return this.resourceCache.selectEvictions(tiles, this.resourceLimits, isProtected);
+    }
+
+    /** Detached shared residency and queue counters, independent of rendering backend. */
+    getStatistics(isPinned: (key: string) => boolean): TileResourceStatistics {
+        return this.resourceCache.getStatistics(this.tiles,
+            key => isPinned(key) || this.buildQueue.has(key) || this.residency.isProtected(key), this.buildQueue.getCounts());
+    }
+
+    /** Stop scheduling, dispose adapter-owned content, and release all resident metadata. */
+    finalize(onTileUnload: (tile: TileT) => void): void {
+        this.buildQueue.clear();
+        this.resourceCache.clear();
+        this.residency.clear();
+        for (const key in this.tileRecords) onTileUnload(this.tileRecords[key]);
+        this.tileRecords = {};
+    }
+}

package/src/tile/tile-build-types.ts

@@ -0,0 +1,155 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type VBOMesh from '../gl/vbo_mesh';
+import type {MeshOptions, MeshElementData} from '../gl/mesh-types';
+import type {MeshLabel} from '../labels/main-pass-types';
+import type {DrapedTerrainQueryMesh} from '../selection/draped-terrain-surface';
+import type {StyleFeature, StyleParseTile, PropertyContext} from '../styles/property-types';
+import type {LayerDrawGroup} from '../styles/layer-types';
+import type {TileDataContext} from '../sources/tile_source_state';
+
+/** Counters shared by worker replies and the main-thread tile debugger. */
+export interface TileDebug extends Record<string, unknown> {
+    /** Elapsed geometry construction time, or its start timestamp while building. */
+    building?: number;
+    /** Features visited by the geometry builder. */
+    feature_count?: number;
+    /** Drawn primitive count accumulated across mesh batches. */
+    geometry_count?: number;
+    /** Uploaded buffer bytes accumulated across mesh batches. */
+    buffer_size?: number;
+    /** Formatted primitive/feature ratio after the final batch. */
+    geometry_ratio?: string;
+    /** Optional introspection counters grouped by authored layer. */
+    layers?: {list: Record<string, LayerDebugCounts>; tree: Record<string, LayerDebugCounts>} | null;
+}
+
+/** Hierarchical authored-layer counters without geometry or GPU ownership. */
+export interface LayerDebugCounts {
+    /** Feature contributions. */
+    features: number;
+    /** Geometry contributions. */
+    geoms: number;
+    /** Style names contributing to this layer. */
+    styles: Record<string, number>;
+    /** Whether this node is an authored base layer. */
+    base: Record<string, number>;
+    /** Child layer counters. */
+    layers?: Record<string, LayerDebugCounts>;
+}
+
+/** Worker mesh attributes preserved during upload and temporal terrain replacement. */
+export interface TileMeshVariant extends Record<string, unknown> {
+    /** Authored style draw order, absent on non-style fixture or incomplete meshes. */
+    blend_order?: number;
+    /** Stable variant draw order, assigned on upload if absent. */
+    mesh_order?: number;
+    /** Captured height-blend duration for admitted geometry. */
+    terrainTransitionDuration?: number;
+    /** Terrain field epoch whose meshes share one display transition origin, independent of scene rebuilds. */
+    terrainGeneration?: number;
+    /** Complete canonical ground cells require half-open tile ownership clipping. */
+    terrainGroundClip?: boolean;
+    /** Worker-side terrain cost captured on this final mesh variant. */
+    terrainStatistics?: import('../procedures/terrain-draping').TerrainMeshPreparation;
+}
+
+/** One transferred mesh variant; collision and ground query channels are optional. */
+export interface TileMeshPayload {
+    /** Completed interleaved vertex buffer. */
+    vertex_data?: Uint8Array;
+    /** Indexed or non-indexed draw topology. */
+    vertex_elements?: MeshElementData;
+    /** Per-variant shader values. */
+    uniforms?: Record<string, unknown>;
+    /** Captured immutable style/refinement policy. */
+    variant: TileMeshVariant;
+    /** Worker label identities and byte ranges. */
+    labels?: Record<string, MeshLabel>;
+    /** Exact ground query channels, when requested by the host. */
+    terrain_surface?: DrapedTerrainQueryMesh;
+}
+
+/** Per-style worker output, including transferred texture references. */
+export interface TileStylePayload extends MeshOptions {
+    /** Variant names preserve deterministic worker draw order. */
+    meshes: Record<string, TileMeshPayload>;
+    /** Variant metadata supplied only to an individual uploaded mesh. */
+    variant?: TileMeshVariant;
+    /** Source detail passed to mesh refinement. */
+    tileZoom?: number;
+}
+
+/** Worker-side build envelope; independent of the main-thread Tile class. */
+export type DecodedTileFeature = Omit<StyleFeature, 'geometry'> & {type?: string; geometry: import('../utils/geo').Geometry | null};
+
+/** Worker-side build envelope; independent of the main-thread Tile class. */
+export interface WorkerBuildTile extends TileDataContext, StyleParseTile, Record<string, unknown> {
+    /** Source-normalized tile address retained in every build envelope. */
+    coords: import('./tile_id').TileCoordinate;
+    /** Absolute Mercator upper-left and lower-right tile corners. */
+    min: {x: number; y: number};
+    max: {x: number; y: number};
+    /** Source-detail scale relative to the worker style zoom. */
+    overzoom2?: number;
+    /** Collision/task identity. */
+    id: number | string;
+    /** Normalized source/style key. */
+    key: string;
+    /** Authored source name, not a main-thread DataSource instance. */
+    source: string;
+    /** Mutable build counters. */
+    debug: TileDebug;
+    /** Normalized decoded feature collections. */
+    source_data?: {layers?: Record<string, {features: DecodedTileFeature[]} | undefined>; request_id?: string | null; error?: string | null; url?: string};
+    /** Transferred style payloads, absent after upload. */
+    mesh_data?: Record<string, TileStylePayload>;
+    /** Loading and generation state carried in replies. */
+    loading?: boolean;
+    loaded?: boolean;
+    generation?: number | null;
+    error?: string | null;
+    /** Cancellation flag written before aborting pending source work. */
+    canceled?: boolean;
+}
+
+/** Per-style lifecycle required by the geometry builder and GPU uploader. */
+export interface TileBuildStyle {
+    /** Style registry identity. */
+    name: string;
+    /** Collision work belongs to the deferred annotation batch. */
+    collision?: boolean;
+    /** External projection moves label collision to the host. */
+    cpu_projection?: unknown;
+    screen_space_labels?: boolean;
+    /** Whether this tile owns unfinished geometry for the style. */
+    hasDataForTile(tile: WorkerBuildTile): boolean;
+    /** Normalize an authored draw group before feature evaluation. */
+    preprocess(group: LayerDrawGroup): LayerDrawGroup | null;
+    /** Append one normalized feature to this style's tile batch. */
+    addFeature(feature: StyleFeature, group: LayerDrawGroup, context: PropertyContext): unknown;
+    /** Complete worker geometry, including asynchronous collision and textures. */
+    endData(tile: WorkerBuildTile): Promise<TileStylePayload | null | undefined>;
+    /** Allocate a main-thread mesh owner from a completed worker variant. */
+    makeMesh(vertices: Uint8Array, elements: MeshElementData, options: TileStylePayload): VBOMesh;
+}
+
+/** Incremental completion state shared by a tile's collision and non-collision batches. */
+export interface TileBuildProgress {
+    /** First worker batch resets main-thread geometry counters. */
+    start?: boolean;
+    /** All style batches completed. */
+    done?: boolean;
+    /** First build failure, serialized across worker boundaries. */
+    error?: string;
+}
+
+/** Root scene layer capabilities used by geometry dispatch, not leaf-only tree nodes. */
+export interface TileBuildLayer {
+    /** Authored source selector, validated by the scene's layer parser. */
+    config_data?: {source?: unknown; all_layers?: unknown; layer?: unknown} | null;
+    /** Resolve all matching draw groups in their existing order. */
+    buildDrawGroups(context: PropertyContext, build?: boolean): Record<string, LayerDrawGroup | null> | null | undefined;
+}