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

package/src/styles/filter.ts

@@ -0,0 +1,190 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+type FilterValue = unknown;
+/** Optional normalization for filter range bounds. */
+export interface FilterOptions {
+    rangeTransform?: (value: unknown) => unknown;
+}
+/** Generated filter retains authored function results; matching applies truthiness. */
+export type FilterFunction = (context: {
+    feature?: {properties: Record<string, unknown>};
+    [name: string]: unknown;
+}) => unknown;
+type FilterAst = string[];
+
+function notNull (x: FilterValue): boolean { return x != null; }
+function wrap (x: FilterValue): string { return '(' + x + ')';}
+
+function maybeQuote (value: FilterValue): FilterValue {
+    if (typeof value === 'string') {
+        return '"' + value + '"';
+    }
+    return value;
+}
+
+function lookUp (key: string): string {
+    if (key[0] === '$') {
+        // keys prefixed with $ are special properties in the context object (not feature properties)
+        return 'context[\'' + key.substring(1) + '\']';
+    }
+    else if (key.indexOf('.') > -1) {
+        if (key.indexOf('\\.') === -1) { // no escaped dot notation
+            // un-escaped dot notation indicates a nested feature property
+            return `context.feature.properties${key.split('.').map(k => '[\'' + k + '\']').join('')}`;
+        }
+        else { // mixed escaped/unescaped dot notation
+            // escaped dot notation will be interpreted as a single-level feature property with dots in the name
+            // this splits on unescaped dots, which requires a temporary swap of escaped and unescaped dots
+            let keys = key
+                .replace(/\\\./g, '__TANGRAM_DELIMITER__')
+                .split('.')
+                .map(s => s.replace(/__TANGRAM_DELIMITER__/g, '.'));
+            return `context.feature.properties${keys.map(k => '[\'' + k + '\']').join('')}`;
+        }
+    }
+    // single-level feature property
+    return 'context.feature.properties[\'' + key + '\']';
+}
+
+function nullValue (/*key, value*/ _key?: FilterValue, _value?: FilterValue): string {
+    return ' true ';
+}
+
+function propertyEqual (key: string, value: FilterValue): string {
+    return wrap(maybeQuote(value) + ' === ' + lookUp(key));
+}
+
+function propertyOr (key: string, values: FilterValue[]): string {
+    const arr = '[' + values.map(maybeQuote).join(',') + ']';
+    return wrap(`${arr}.indexOf(${lookUp(key)}) > -1`);
+}
+
+function printNested (values: FilterAst[], joiner: string): string {
+    return wrap(values.filter(notNull).map(function (x: FilterAst) {
+        return wrap(x.join(' && '));
+    }).join(' ' + joiner + ' '));
+}
+
+function any (_: FilterValue, values: FilterValue[], options: FilterOptions | undefined): string {
+    return (values && values.length > 0) ? printNested(values.map(function (v: FilterValue) { return parseFilter(v, options); }), '||') : 'true';
+}
+
+function all (_: FilterValue, values: FilterValue[], options: FilterOptions | undefined): string {
+    return (values && values.length > 0) ? printNested(values.map(function (v: FilterValue) { return parseFilter(v, options); }), '&&') : 'true';
+}
+
+function not (key: FilterValue, value: FilterValue, options: FilterOptions | undefined): string {
+    return '!' + wrap(parseFilter(value, options).join(' && '));
+}
+
+function none (key: FilterValue, values: FilterValue[], options: FilterOptions | undefined): string {
+    return '!' + wrap(any(null, values, options));
+}
+
+function propertyMatchesBoolean (key: string, value: boolean): string {
+    return wrap(lookUp(key) + (value ? ' != ' : ' == ')  + 'null');
+}
+
+function rangeMatch (key: string, value: Record<string, unknown>, options: FilterOptions | undefined): string {
+    var expressions = [];
+    var transform = options && (typeof options.rangeTransform === 'function') && options.rangeTransform;
+
+    if (value.max) {
+        var max = transform ? transform(value.max) : value.max;
+        expressions.push('' + lookUp(key) + ' < ' + max);
+    }
+
+    if (value.min) {
+        var min: unknown = transform ? min = transform(value.min) : value.min;
+        expressions.push('' + lookUp(key) + ' >= ' + min);
+    }
+
+    return wrap(expressions.join(' && '));
+}
+
+function includesMatch (key: string, value: Record<string, unknown>, _options?: FilterOptions): string {
+    let expressions = [];
+
+    // the array includes ONE OE MORE of the provided values (a single value is converted to an array)
+    if (value.includes_any) {
+        const vals = Array.isArray(value.includes_any) ? value.includes_any : [value.includes_any];
+        const arr = '['+ vals.map(maybeQuote).join(',') + ']';
+        expressions.push(`${lookUp(key)} != null && ${arr}.some(function(v) { return ${lookUp(key)}.indexOf(v) > -1 })`);
+    }
+
+    // the array includes ALL of the provided values (a single value is converted to an array)
+    if (value.includes_all) {
+        const vals = Array.isArray(value.includes_all) ? value.includes_all : [value.includes_all];
+        const arr = '[' + vals.map(maybeQuote).join(',') + ']';
+        expressions.push(`${lookUp(key)} != null && ${arr}.every(function(v) { return ${lookUp(key)}.indexOf(v) > -1 })`);
+    }
+
+    return wrap(expressions.join(' && '));
+}
+
+function parseFilter (filter: FilterValue, options: FilterOptions | undefined): FilterAst {
+    var filterAST: FilterAst = [];
+
+    // Function filter
+    if (typeof filter === 'function') {
+        return [wrap(wrap(filter.toString()) + '(context)')];
+    }
+    // Array filter, implicit 'any'
+    else if (Array.isArray(filter)) {
+        return [any(null, filter, options)];
+    }
+    // Null filter object
+    else if (filter == null) {
+        return ['true'];
+    }
+
+    // Object filter, e.g. implicit 'all'
+    var keys = Object.keys(filter as object);
+    for (var k=0; k < keys.length; k++) {
+        var key = keys[k];
+
+        var value = (filter as Record<string, unknown>)[key],
+            type  = typeof value;
+        if (type === 'string' || type === 'number') {
+            filterAST.push(propertyEqual(key, value));
+        } else if (type === 'boolean') {
+            filterAST.push(propertyMatchesBoolean(key, value as boolean));
+        } else if (key === 'not') {
+            filterAST.push(not(key, value, options));
+        } else if (key === 'any') {
+            filterAST.push(any(key, value as FilterValue[], options));
+        } else if (key === 'all') {
+            filterAST.push(all(key, value as FilterValue[], options));
+        } else if (key === 'none') {
+            filterAST.push(none(key, value as FilterValue[], options));
+        } else if (Array.isArray(value)) {
+            filterAST.push(propertyOr(key, value));
+        } else if (type === 'object' && value != null) {
+            if ((value as Record<string, unknown>).max || (value as Record<string, unknown>).min) {
+                filterAST.push(rangeMatch(key, value as Record<string, unknown>, options));
+            }
+            else if ((value as Record<string, unknown>).includes_any || (value as Record<string, unknown>).includes_all) {
+                filterAST.push(includesMatch(key, value as Record<string, unknown>, options));
+            }
+        } else if (value == null) {
+            filterAST.push(nullValue(key, value));
+        } else {
+            throw new Error('Unknown Query syntax: ' + value);
+        }
+    }
+
+    return keys.length === 0 ? ['true'] : filterAST;
+}
+
+function filterToString (filterAST: FilterAst): string {
+    return wrap(filterAST.join(' && '));
+}
+
+export function buildFilter (filter: FilterValue, options?: FilterOptions): FilterFunction {
+    if (filter == null) { return function () { return true; }; }
+    // jshint evil: true
+    return new Function('context', 'return ' + filterToString(parseFilter(filter, options)) + ';') as FilterFunction;
+}

package/src/styles/geometry-style-types.ts

@@ -0,0 +1,209 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type VertexData from '../gl/vertex_data';
+import type VertexLayout from '../gl/vertex_layout';
+import type UniformBuffer from '../gl/uniform_buffer';
+import type {UniformBufferOptions} from '../gl/uniform_buffer';
+import type {VertexAttribute} from '../gl/vertex-types';
+import type {GeometryLine, GeometryPolygon, PolylineStyle} from '../builders/geometry-types';
+import type {PropertyCache, PropertyContext, StyleFeature} from './property-types';
+import type {ProjectedBasemapOptions} from '../procedures/mesh-projector';
+
+/** Geometry feature properties normalized by the source and style expression boundary. */
+export interface GeometryFeature extends StyleFeature {
+    properties: Record<string, unknown> & {height?: number; min_height?: number};
+}
+/** Tile state consumed by line width interpolation and edge clipping. */
+export interface GeometryTile {
+    id: string | number;
+    pad_scale: number;
+    overzoom2: number;
+}
+/** Evaluation context with the tile conversions needed by geometry construction. */
+export interface GeometryContext extends PropertyContext {
+    /** EPSG:3857 meters per CSS pixel at the style zoom. */
+    meters_per_pixel: number;
+    feature: GeometryFeature;
+    zoom: number;
+    units_per_meter_overzoom: number;
+    tile: GeometryTile;
+    winding?: string;
+}
+/** Authored extrusion resolves to a flag, height, or [minimum height, height]. */
+export type GeometryExtrusion = boolean | number | number[] | null | undefined;
+/** Normalized mesh variant shared by outlines, polygons, and portable attributes. */
+export interface GeometryMeshVariant {
+    key: string | number;
+    blend_order: number | undefined;
+    mesh_order: number;
+    selection: number;
+    normal?: number;
+    offset?: number;
+    z_or_offset?: number;
+    texcoords?: number | boolean;
+    texture?: string | null | false;
+    dash?: number[] | null | false;
+    dash_key?: string | null | false;
+    dash_background_color?: number[] | null | false;
+}
+/** Per-draw cache fields after property preprocessing, not evaluated feature values. */
+export interface GeometryDraw {
+    /** Internal fixed-pixel stroke marker captured before distance preprocessing. */
+    projected_pixel_width?: boolean;
+    color?: PropertyCache | null;
+    alpha?: PropertyCache;
+    width?: PropertyCache;
+    next_width?: PropertyCache;
+    offset?: PropertyCache | null;
+    next_offset?: PropertyCache;
+    z?: PropertyCache;
+    extrude?: unknown;
+    interactive?: unknown;
+    cap?: PolylineStyle['cap'];
+    join?: PolylineStyle['join'];
+    miter_limit?: number;
+    variant: string | number;
+    tile_edges?: boolean;
+    texcoords?: number | boolean;
+    inline_texcoord_width?: number | null;
+    offset_precalc?: number;
+    offset_scale_precalc?: number;
+    dash?: number[] | null | false;
+    dash_key?: string | null | false;
+    dash_background_color?: number[] | null | false;
+    texture?: string | null;
+    texture_merged?: string | null | false;
+    is_outline?: boolean;
+    visible?: boolean;
+    order?: unknown;
+    blend_order?: number;
+    layers: string[];
+    style: string;
+    preprocessed?: boolean;
+    outline?: GeometryDraw | null;
+}
+/** Values may be authored scalars/functions before the cache wrappers are installed. */
+export type RawGeometryDraw = Omit<GeometryDraw, 'variant' | 'color' | 'alpha' | 'width' | 'offset' | 'z' | 'dash_background_color' | 'outline'> & {
+    variant?: string | number;
+    color?: unknown;
+    alpha?: unknown;
+    width?: unknown;
+    offset?: unknown;
+    z?: unknown;
+    dash_background_color?: unknown;
+    outline?: RawGeometryDraw | null;
+};
+/** Reused feature record; the base style and parsing methods populate it before building. */
+export interface PolygonFeatureStyle {
+    color: number[];
+    alpha?: number;
+    variant: string | number;
+    z: number;
+    height: number;
+    min_height: number;
+    extrude: GeometryExtrusion;
+    tile_edges?: boolean;
+    order: number;
+    selection_color: number[];
+}
+/** Computed line values, including interpolation and a reusable cached outline. */
+export interface LineFeatureStyle extends Omit<PolygonFeatureStyle, 'min_height'>, PolylineStyle {
+    /** Packed extrusion units per CSS pixel, zero for meter-width strokes. */
+    projected_pixel_scale?: number;
+    width_unscaled: number;
+    next_width_unscaled: number;
+    width_scale: number;
+    offset_scale: number;
+    outline?: GeometryOutlineDraw;
+}
+/** The outline scratch record always owns width caches, populated before submission. */
+export interface GeometryOutlineDraw extends GeometryDraw {
+    width: PropertyCache;
+    next_width: PropertyCache;
+    order: number;
+}
+/** Worker-side mesh records while packed geometry is still being accumulated. */
+export interface GeometryBuildMesh {
+    vertex_data: VertexData;
+    variant: GeometryMeshVariant;
+    uniforms?: Record<string, unknown>;
+}
+/** Completed tile records used to assign dash/texture uniforms before submission. */
+export interface GeometryTileData {
+    uniforms: Record<string, unknown>;
+    meshes: Record<string, {variant: GeometryMeshVariant; uniforms?: Record<string, unknown>}>;
+}
+/** Checked geometry style surface; inherited base lifecycle remains a separate tranche. */
+export interface GeometryStyleRuntime<FeatureStyle extends Omit<PolygonFeatureStyle, 'min_height'> = PolygonFeatureStyle> {
+    /** Opt-in validated worker height field; absent preserves the original packed layout. */
+    terrain?: import('../procedures/terrain-draping').TerrainDrapingSnapshot;
+    name: string;
+    built_in: boolean;
+    vertex_shader_src: string;
+    fragment_shader_src: string;
+    selection: boolean;
+    animated?: boolean;
+    texcoords?: boolean;
+    raster?: string | boolean;
+    shader_language: 'glsl' | 'wgsl';
+    /** Optional scene-wide CPU projection of ground surfaces and fixed-meter line ribbons. */
+    cpu_projection?: ProjectedBasemapOptions;
+    /** Authored polygon lighting, disabled for initial CPU-projected ground. */
+    lighting?: 'vertex' | 'fragment' | boolean;
+    /** Position blocks and custom attributes are outside the initial contract. */
+    shaders?: {blocks?: {position?: unknown}; attributes?: unknown};
+    /** Underlying builtin style after inheritance and mixins. */
+    baseStyle(): string;
+    portable_lighting_mode?: 'vertex' | 'fragment' | false;
+    portable_light_count?: number;
+    defines: Record<string, boolean | number | string | undefined>;
+    feature_style: FeatureStyle;
+    vertex_template: number[];
+    variants: Record<string | number, GeometryMeshVariant>;
+    vertex_layouts: Record<string | number, VertexLayout>;
+    texture?: string;
+    dash?: number[] | null | false;
+    dash_background_color?: number[] | null | false;
+    init(options?: Record<string, unknown>): void;
+    destroy(): void;
+    setGL(context: unknown, blocks?: Record<string, UniformBuffer>, options?: Record<string, unknown>): void;
+    getWGSLShaderSource(selection?: boolean): string;
+    _parseFeature(feature: GeometryFeature, draw: GeometryDraw, context: GeometryContext): FeatureStyle | null | undefined;
+    _preprocess(draw: RawGeometryDraw): GeometryDraw;
+    computeVariant(draw: GeometryDraw | RawGeometryDraw): void;
+    getBlendOrderForDraw(draw: GeometryDraw | RawGeometryDraw): number;
+    vertexLayoutForMeshVariant(variant: GeometryMeshVariant): VertexLayout;
+    meshVariantTypeForDraw(draw: Pick<GeometryDraw, 'variant'>): GeometryMeshVariant;
+    makeVertexTemplate(style: FeatureStyle, mesh: GeometryBuildMesh): number[];
+    parseColor(property: PropertyCache | null | undefined, context: GeometryContext): number[];
+    parseOrder(value: unknown, context: GeometryContext): number;
+    scaleOrder(order: number): number;
+    addCustomAttributesToAttributeList(attributes: VertexAttribute[]): void;
+    addCustomAttributesToVertexTemplate(style: FeatureStyle, offset: number): void;
+    getTileMesh(tile: GeometryTile, variant: GeometryMeshVariant): GeometryBuildMesh;
+    startData(tile: GeometryTile): void;
+    addFeature(feature: GeometryFeature, draw: GeometryDraw, context: GeometryContext): void;
+    buildPolygons(polygons: GeometryPolygon[], style: FeatureStyle, context: GeometryContext): number;
+    endData(tile: GeometryTile): Promise<GeometryTileData | null>;
+}
+/** Additional lifecycle and interpolation owned only by line styles. */
+export interface LineStyleRuntime extends GeometryStyleRuntime<LineFeatureStyle> {
+    inline_feature_style: LineFeatureStyle;
+    outline_feature_style: LineFeatureStyle;
+    styles: Record<string, GeometryStyleRuntime<LineFeatureStyle>>;
+    dash_textures: Record<string, boolean>;
+    main_thread_target: string;
+    resource_context: object | null;
+    line_uniform_buffer?: UniformBuffer | null;
+    uniform_blocks?: Record<string, UniformBuffer> | null;
+    uniform_block_factory?: ((options: UniformBufferOptions) => UniformBuffer) | null;
+    calcDistance(property: PropertyCache | null | undefined, context: GeometryContext): number;
+    calcDistanceNextZoom(property: PropertyCache | null | undefined, context: GeometryContext): number;
+    calcWidth(draw: GeometryDraw, style: LineFeatureStyle, context: GeometryContext): boolean | undefined;
+    calcOffset(draw: GeometryDraw, style: LineFeatureStyle, context: GeometryContext): void;
+    buildLines(lines: GeometryLine[], style: LineFeatureStyle, context: GeometryContext, options?: {closed_polygon?: boolean; remove_tile_edges?: boolean}): number;
+    dashTextureKey(dash: number[]): string;
+    getDashTexture(dash: number[]): void;
+}

package/src/styles/globe_visibility_wgsl.ts

@@ -0,0 +1,22 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {globeHorizon} from '../shader-modules/globe-horizon';
+
+/** Shared GLSL horizon math with Tangram's radius-256, geographic-altitude contract. */
+export const GLOBE_VISIBILITY_GLSL = `${globeHorizon.vs}
+bool tangramGlobeOccluded(vec3 position, float altitude, vec3 eye) {
+    return globeHorizon_isOccluded(
+        globeHorizon_getAnchor(position, altitude, 256., 6370972.), eye, 256.);
+}
+`;
+
+/** Shared WGSL horizon math with the same common-space and altitude contract. */
+export const GLOBE_VISIBILITY_WGSL = `
+${globeHorizon.source}
+fn tangramGlobeOccluded(position: vec3<f32>, altitude: f32, eye: vec3<f32>) -> bool {
+    return globeHorizon_isOccluded(
+        globeHorizon_getAnchor(position, altitude, 256.0, 6370972.0), eye, 256.0);
+}
+`;

package/src/styles/layer-types.ts

@@ -0,0 +1,45 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {PropertyContext} from './property-types';
+import type {LayerTree, LayerLeaf} from './layer';
+
+/** Raw YAML members validated lazily during matching. */
+export type SceneLayerDefinition = Record<string, unknown>;
+/** Extensible evaluated draw properties for built-in and custom styles. */
+export interface LayerDrawGroup extends Record<string, unknown> {
+    /** Resolved style registry name, when it differs from the draw-group name. */
+    style?: string;
+    visible?: boolean;
+    key?: string;
+    layers?: string[];
+    group?: string;
+}
+/** Named draw groups at one scene-tree depth. */
+export type LayerDrawGroups = Record<string, LayerDrawGroup | null>;
+/** Leaf/tree candidates sharing the legacy matching order. */
+export type SceneLayer = LayerTree | LayerLeaf;
+/** A lazy layer constructor's reserved properties. */
+export interface LayerConfig {
+    layer: SceneLayerDefinition;
+    name: string;
+    parent?: LayerTree | null;
+    draw?: Record<string, unknown>;
+    visible?: boolean;
+    enabled?: boolean;
+    filter?: unknown;
+    exclusive?: boolean;
+    priority?: number;
+    styles?: Record<string, unknown>;
+    layers?: SceneLayer[];
+}
+/** Context used by feature, property, and zoom filters. */
+export interface LayerMatchContext extends PropertyContext {
+    zoom: number;
+    feature: NonNullable<PropertyContext['feature']>;
+}
+/** Optimized match retaining the original comparison values. */
+export type LayerPropertyMatch = [string, unknown[]];
+/** Null means evaluated with no draw; undefined means not evaluated. */
+export type LayerCombinationCache = Record<string, LayerDrawGroups | null | undefined>;