@tangram.gl/basemap-layers 0.0.0-stage → 0.0.1

package/src/shared-texture.ts

@@ -0,0 +1,153 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Device, SamplerProps, Texture, TextureProps} from '@luma.gl/core';
+
+/** The sampler deck.gl gives the textures it creates from `image` props. */
+const DEFAULT_SAMPLER: SamplerProps = {
+  minFilter: 'linear',
+  mipmapFilter: 'linear',
+  magFilter: 'linear',
+  addressModeU: 'clamp-to-edge',
+  addressModeV: 'clamp-to-edge'
+};
+
+type SharedTexture = {texture: Texture; users: number};
+
+/** Options of a `SharedTextureSet`. Sets with different options share no textures. */
+export type SharedTextureOptions = {
+  /**
+   * Most mip levels of a texture, the full image included: 1 for none. Default: the full chain.
+   * Fewer levels keep a minified texture sharper, at the cost of aliasing beyond the last level.
+   */
+  maxMipLevels?: number;
+};
+
+/**
+ * The shared textures of each device, by the options they were created with (see `getOptionsKey`)
+ * and the image they were created from.
+ */
+const sharedTextures = new WeakMap<Device, Map<string, Map<object, SharedTexture>>>();
+
+function getOptionsKey({maxMipLevels}: SharedTextureOptions): string {
+  return maxMipLevels === undefined ? 'mip:all' : `mip:${maxMipLevels}`;
+}
+
+/**
+ * Creates a texture from an image as deck.gl does for an `image` prop: an `ImageBitmap` or canvas,
+ * or a plain object with `data`, `width` and `height`, with mipmaps (at most `maxMipLevels`).
+ */
+function createTexture(
+  device: Device,
+  image: object,
+  {maxMipLevels}: SharedTextureOptions
+): Texture {
+  const source = (
+    image.constructor && image.constructor.name !== 'Object' ? {data: image} : image
+  ) as {data: {width?: number; height?: number}; width?: number; height?: number};
+  // A plain object gives its size; raw pixel data has none of its own.
+  const width = source.width ?? source.data.width ?? 1;
+  const height = source.height ?? source.data.height ?? 1;
+  const texture = device.createTexture({
+    ...source,
+    sampler: DEFAULT_SAMPLER,
+    mipLevels: Math.max(
+      1,
+      Math.min(maxMipLevels ?? Infinity, device.getMipLevelCount(width, height))
+    )
+  } as TextureProps);
+  if (device.type === 'webgl') {
+    texture.generateMipmapsWebGL();
+  } else if (device.type === 'webgpu') {
+    (device as any).generateMipmapsWebGPU(texture);
+  }
+  return texture;
+}
+
+/**
+ * The textures one layer uses, shared with every other layer that uses the same image on the
+ * same device. deck.gl creates a texture, and uploads the image, for each layer that is handed an
+ * image: every label sublayer of every tile would upload the same font atlas and sprite sheet. A
+ * shared texture is created on first use and destroyed when its last user releases it.
+ */
+export class SharedTextureSet {
+  private images = new Set<object>();
+  /** The options, as given at construction: they are part of the cache key. */
+  readonly options: Readonly<SharedTextureOptions>;
+  private optionsKey: string;
+
+  constructor(
+    private device: Device,
+    {maxMipLevels}: SharedTextureOptions = {}
+  ) {
+    this.options = {maxMipLevels};
+    this.optionsKey = getOptionsKey(this.options);
+  }
+
+  /** The textures shared by the sets with this set's options on its device. */
+  private getTextures(): Map<object, SharedTexture> {
+    let byOptions = sharedTextures.get(this.device);
+    if (!byOptions) {
+      byOptions = new Map();
+      sharedTextures.set(this.device, byOptions);
+    }
+    let textures = byOptions.get(this.optionsKey);
+    if (!textures) {
+      textures = new Map();
+      byOptions.set(this.optionsKey, textures);
+    }
+    return textures;
+  }
+
+  /** Returns the shared texture of `image`, which this set uses until `retainOnly` drops it. */
+  get(image: object): Texture {
+    const textures = this.getTextures();
+    let entry = textures.get(image);
+    if (!entry) {
+      entry = {texture: createTexture(this.device, image, this.options), users: 0};
+      textures.set(image, entry);
+    }
+    if (!this.images.has(image)) {
+      this.images.add(image);
+      entry.users++;
+    }
+    return entry.texture;
+  }
+
+  /** Releases the textures of every image this set uses that is not in `images`. */
+  retainOnly(images: Iterable<object>): void {
+    const kept = new Set(images);
+    for (const image of this.images) {
+      if (!kept.has(image)) {
+        this.release(image);
+      }
+    }
+  }
+
+  /** Releases every texture this set uses. */
+  releaseAll(): void {
+    for (const image of this.images) {
+      this.release(image);
+    }
+  }
+
+  private release(image: object): void {
+    this.images.delete(image);
+    const textures = this.getTextures();
+    const entry = textures.get(image);
+    if (entry && --entry.users <= 0) {
+      entry.texture.destroy();
+      textures.delete(image);
+    }
+  }
+}
+
+/** The number of shared textures alive on a device, for tests. */
+export function getSharedTextureCount(device: Device): number {
+  let count = 0;
+  for (const textures of sharedTextures.get(device)?.values() || []) {
+    count += textures.size;
+  }
+  return count;
+}

package/src/sort-key.ts

@@ -0,0 +1,63 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {getStyleAccessor} from './style-accessor';
+import type {ResolvedBasemapStyleLayer as BasemapStyleLayer} from './style-resolver';
+
+/** The latest sorted features per tile content and style layer. */
+const sortedFeatureCache = new WeakMap<
+  any[],
+  WeakMap<BasemapStyleLayer, {key: unknown[]; features: any[]}>
+>();
+
+/**
+ * A tile's features of a style layer in the order of their sort key (`circle-sort-key`,
+ * `line-sort-key`), ascending, as MapLibre GL JS orders a bucket: features with a higher key draw
+ * over those with a lower one, and features with the same key keep their tile order. Without a
+ * per-feature key, the features are returned as they are. The sorted array is reused while the
+ * features, the key and (for a key that depends on zoom) the style zoom are unchanged, so deck.gl
+ * does not re-tessellate the features at every zoom step.
+ */
+export function sortFeaturesByKey(
+  features: any[],
+  styleLayer: BasemapStyleLayer,
+  propertyName: 'circle-sort-key' | 'line-sort-key',
+  zoom: number
+): any[] {
+  const sortKey = styleLayer.layout?.[propertyName];
+  if (sortKey === undefined) {
+    return features;
+  }
+  const accessor = getStyleAccessor(styleLayer, [propertyName], zoom, ([key]) => Number(key) || 0);
+  const {value} = accessor;
+  const key = [
+    propertyName,
+    sortKey,
+    features.length,
+    typeof value === 'function' ? accessor.updateTrigger : value
+  ];
+  let byStyleLayer = sortedFeatureCache.get(features);
+  if (!byStyleLayer) {
+    byStyleLayer = new WeakMap();
+    sortedFeatureCache.set(features, byStyleLayer);
+  }
+  const cached = byStyleLayer.get(styleLayer);
+  if (cached && cached.key.every((entry, index) => entry === key[index])) {
+    return cached.features;
+  }
+  // `Array.prototype.sort` is stable.
+  const sorted =
+    typeof value === 'function'
+      ? features
+          .map(feature => ({feature, key: value(feature)}))
+          .sort((a, b) => a.key - b.key)
+          .map(entry => entry.feature)
+      : features;
+  byStyleLayer.set(styleLayer, {key, features: sorted});
+  return sorted;
+}

package/src/sprite.ts

@@ -0,0 +1,244 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {log} from '@deck.gl/core';
+import type {BasemapLoadOptions} from './style-resolver';
+
+/** One image in a style sprite, as listed in the sprite's JSON index. */
+export type SpriteImage = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Device pixels per CSS pixel of the image. Default 1. */
+  pixelRatio?: number;
+  /** `true` for signed-distance-field images, which are tinted with `icon-color`. */
+  sdf?: boolean;
+};
+
+/** A deck.gl `IconLayer` mapping entry for one sprite image. */
+export type SpriteIconMappingEntry = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** `true` for SDF images: deck.gl tints masked icons with `getColor`. */
+  mask: boolean;
+  /** Device pixels per CSS pixel; `icon-size` scales `height / pixelRatio`. */
+  pixelRatio: number;
+};
+
+/** A loaded sprite: the atlas image and its deck.gl icon mapping. */
+export type SpriteAtlas = {
+  /**
+   * Sprite id. `'default'` for a style whose `sprite` is a single URL; otherwise the id from the
+   * style's sprite array, which prefixes its image names as `id:name`.
+   */
+  id: string;
+  /**
+   * The atlas image, decoded once and shared by every icon layer, or its URL where
+   * `createImageBitmap` is unavailable (each `IconLayer` then loads the URL itself).
+   */
+  image: ImageBitmap | string;
+  /** Icon mapping keyed by image name, without the `id:` prefix. */
+  mapping: Record<string, SpriteIconMappingEntry>;
+};
+
+/** A style's `sprite` value: a URL, or the array form with one `{id, url}` per sprite. */
+export type StyleSprite = string | Array<{id: string; url: string}>;
+
+/** A sprite source after relative URLs are resolved. */
+export type SpriteSource = {id: string; url: string};
+
+/** Options for {@link loadSpriteAtlases}. */
+export type SpriteLoadOptions = {
+  /** Base URL that relative sprite URLs resolve against, normally the style URL. */
+  baseUrl?: string;
+  /** Device pixel ratio. At 2 or more, the `@2x` sprite is requested first. Default 1. */
+  pixelRatio?: number;
+} & Pick<NonNullable<BasemapLoadOptions>, 'fetch' | 'fetchOptions'>;
+
+/** Resolves a style's `sprite` value into sprite sources with absolute URLs. */
+export function getSpriteSources(sprite: unknown, baseUrl?: string): SpriteSource[] {
+  const resolve = (url: string) => {
+    try {
+      return new URL(url, baseUrl).toString();
+    } catch {
+      return url;
+    }
+  };
+  if (typeof sprite === 'string' && sprite) {
+    return [{id: 'default', url: resolve(sprite)}];
+  }
+  if (Array.isArray(sprite)) {
+    return sprite
+      .filter(entry => entry && typeof entry.id === 'string' && typeof entry.url === 'string')
+      .map(entry => ({id: entry.id, url: resolve(entry.url)}));
+  }
+  return [];
+}
+
+/** Converts a sprite JSON index into a deck.gl `IconLayer` mapping. */
+export function getSpriteIconMapping(
+  index: Record<string, SpriteImage>
+): Record<string, SpriteIconMappingEntry> {
+  const mapping: Record<string, SpriteIconMappingEntry> = {};
+  for (const [name, image] of Object.entries(index || {})) {
+    mapping[name] = {
+      x: image.x,
+      y: image.y,
+      width: image.width,
+      height: image.height,
+      mask: Boolean(image.sdf),
+      pixelRatio: image.pixelRatio || 1
+    };
+  }
+  return mapping;
+}
+
+/**
+ * Decodes the atlas PNG once, so the per-tile icon layers share one image instead of each
+ * requesting it. Without `createImageBitmap` (e.g. in Node), returns the URL.
+ */
+async function loadSpriteImage(
+  url: string,
+  fetchFn: typeof fetch,
+  fetchOptions?: RequestInit
+): Promise<ImageBitmap | string> {
+  if (typeof createImageBitmap !== 'function') {
+    return url;
+  }
+  const response = await fetchFn(url, fetchOptions);
+  if (!response.ok) {
+    throw new Error(`Failed to load sprite image: ${url} (${response.status})`);
+  }
+  return await createImageBitmap(await response.blob());
+}
+
+/** Appends a suffix and extension to a sprite URL's path, keeping its query string and hash. */
+function getSpriteFileUrl(url: string, suffix: string, extension: string): string {
+  const pathEnd = url.search(/[?#]/);
+  return pathEnd < 0
+    ? `${url}${suffix}${extension}`
+    : `${url.slice(0, pathEnd)}${suffix}${extension}${url.slice(pathEnd)}`;
+}
+
+/**
+ * Loads one sprite: the `@2x` variant first at any pixel ratio above 1, as MapLibre does, falling
+ * back to `@1x`.
+ */
+async function loadSpriteAtlas(
+  source: SpriteSource,
+  options: SpriteLoadOptions
+): Promise<SpriteAtlas> {
+  const fetchFn = options.fetch || fetch;
+  const suffixes = (options.pixelRatio ?? 1) > 1 ? ['@2x', ''] : [''];
+  let lastError: unknown;
+  for (const suffix of suffixes) {
+    const jsonUrl = getSpriteFileUrl(source.url, suffix, '.json');
+    try {
+      const response = await fetchFn(jsonUrl, options.fetchOptions);
+      if (!response.ok) {
+        throw new Error(`Failed to load sprite: ${jsonUrl} (${response.status})`);
+      }
+      const index = (await response.json()) as Record<string, SpriteImage>;
+      return {
+        id: source.id,
+        image: await loadSpriteImage(
+          getSpriteFileUrl(source.url, suffix, '.png'),
+          fetchFn,
+          options.fetchOptions
+        ),
+        mapping: getSpriteIconMapping(index)
+      };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * Loads every sprite a style references. A sprite that fails to load is skipped with a warning,
+ * so its icons are not drawn and the rest of the style still renders.
+ */
+export async function loadSpriteAtlases(
+  sprite: unknown,
+  options: SpriteLoadOptions = {}
+): Promise<SpriteAtlas[]> {
+  const sources = getSpriteSources(sprite, options.baseUrl);
+  const atlases = await Promise.all(
+    sources.map(source =>
+      loadSpriteAtlas(source, options).catch(error => {
+        log.warn(
+          `[BasemapLayer] Sprite ${source.url} failed to load; its icons are skipped`,
+          error
+        )();
+        return null;
+      })
+    )
+  );
+  return atlases.filter((atlas): atlas is SpriteAtlas => Boolean(atlas));
+}
+
+const imageNamesCache = new WeakMap<readonly SpriteAtlas[], string[]>();
+
+/**
+ * The image names `icon-image` can reference: unprefixed for the `'default'` sprite and `id:name`
+ * for the others. Passed to expression evaluation so `["image", ...]` sees which images exist.
+ */
+export function getSpriteImageNames(atlases: readonly SpriteAtlas[] | null | undefined): string[] {
+  if (!atlases) {
+    return [];
+  }
+  let names = imageNamesCache.get(atlases);
+  if (!names) {
+    names = atlases.flatMap(atlas =>
+      Object.keys(atlas.mapping).map(name =>
+        atlas.id === 'default' ? name : `${atlas.id}:${name}`
+      )
+    );
+    imageNamesCache.set(atlases, names);
+  }
+  return names;
+}
+
+/** An icon resolved against the loaded sprites. */
+export type ResolvedSpriteIcon = {atlas: SpriteAtlas; name: string; entry: SpriteIconMappingEntry};
+
+/**
+ * Finds the sprite and mapping entry for an `icon-image` name. Names from the `'default'` sprite
+ * are unprefixed; names from other sprites are written `id:name`, as in MapLibre.
+ */
+export function resolveSpriteIcon(
+  atlases: readonly SpriteAtlas[] | undefined,
+  iconImage: string
+): ResolvedSpriteIcon | null {
+  if (!atlases || !iconImage) {
+    return null;
+  }
+  const separator = iconImage.indexOf(':');
+  if (separator > 0) {
+    const atlas = atlases.find(candidate => candidate.id === iconImage.slice(0, separator));
+    const name = iconImage.slice(separator + 1);
+    if (atlas?.mapping[name]) {
+      return {atlas, name, entry: atlas.mapping[name]};
+    }
+  }
+  const atlas = atlases.find(candidate => candidate.id === 'default');
+  if (atlas?.mapping[iconImage]) {
+    return {atlas, name: iconImage, entry: atlas.mapping[iconImage]};
+  }
+  return null;
+}
+
+const warnedMissingIcons = new Set<string>();
+
+/** Warns once per icon name that a style references an image no loaded sprite contains. */
+export function warnMissingIcon(iconImage: string): void {
+  if (!warnedMissingIcons.has(iconImage)) {
+    warnedMissingIcons.add(iconImage);
+    log.warn(`[BasemapLayer] icon-image "${iconImage}" is not in the style's sprite; skipped`)();
+  }
+}

package/src/style-accessor.ts

@@ -0,0 +1,95 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {getCompiledStyleProperty, type StyleFeature} from './style-expression';
+
+type StyleLayerLike = {
+  paint?: Record<string, unknown>;
+  layout?: Record<string, unknown>;
+};
+
+/**
+ * Zoom step at which style values are evaluated. Paint and layout values step every
+ * `STYLE_ZOOM_STEP` zoom levels instead of following the zoom continuously.
+ */
+export const STYLE_ZOOM_STEP = 0.25;
+
+/**
+ * Zoom at which paint and layout values are evaluated: the zoom rounded down to a
+ * `STYLE_ZOOM_STEP`.
+ *
+ * This is a temporary simplification, not MapLibre's behaviour. MapLibre evaluates zoom-dependent
+ * expressions at the integer zooms on either side of the current zoom and interpolates between
+ * them on the GPU, which remains the long-term plan here. Stepping keeps every tile on the same
+ * evaluation zoom, so neighbouring tiles agree at their seams.
+ */
+export function getZoomBucket(zoom: number): number {
+  return Math.floor(zoom / STYLE_ZOOM_STEP) * STYLE_ZOOM_STEP;
+}
+
+/** Zoom at which filters are evaluated: the integer zoom, as the style spec specifies. */
+export function getFilterZoom(zoom: number): number {
+  return Math.floor(zoom);
+}
+
+/**
+ * A key that changes whenever style evaluation or layer visibility changes: at every
+ * `STYLE_ZOOM_STEP` (which includes every integer zoom, where filters change), and at every
+ * fractional `minzoom`/`maxzoom` in `zoomLimits`. Layer visibility uses the exact zoom, as in
+ * MapLibre, so crossing a fractional limit must regenerate sublayers too.
+ */
+export function getStyleZoomKey(zoom: number, zoomLimits: readonly (number | undefined)[]): string {
+  const crossed = zoomLimits.filter(
+    limit => limit !== undefined && !Number.isInteger(limit) && zoom >= limit
+  ).length;
+  return `${getZoomBucket(zoom)}:${crossed}`;
+}
+
+/** A deck.gl accessor built from one or more style properties. */
+export type StyleAccessor<T> = {
+  /** A constant when no property depends on feature data, otherwise a per-feature function. */
+  value: T | ((feature: StyleFeature) => T);
+  /** Set to the evaluation zoom (`getZoomBucket`) when a per-feature value also depends on zoom. */
+  updateTrigger?: number;
+};
+
+/**
+ * Builds a deck.gl accessor from style properties, evaluated at the stepped zoom
+ * (`getZoomBucket`). Feature-independent values become constants. Data-driven values become
+ * per-feature functions, with an update trigger when they also depend on zoom.
+ */
+export function getStyleAccessor<T>(
+  styleLayer: StyleLayerLike,
+  propertyNames: string[],
+  zoom: number,
+  combine: (values: any[]) => T
+): StyleAccessor<T> {
+  const properties = propertyNames.map(name => getCompiledStyleProperty(styleLayer, name));
+  const isFeatureDependent = properties.some(property => property?.isFeatureDependent);
+  const zoomBucket = getZoomBucket(zoom);
+
+  if (!isFeatureDependent) {
+    return {value: combine(properties.map(property => property?.evaluate(zoomBucket)))};
+  }
+
+  const isZoomDependent = properties.some(property => property?.isZoomDependent);
+  return {
+    value: (feature: StyleFeature) =>
+      combine(properties.map(property => property?.evaluate(zoomBucket, feature))),
+    updateTrigger: isZoomDependent ? zoomBucket : undefined
+  };
+}
+
+/** Converts a style color (alpha 0-1 or 0-255) and opacity into a deck.gl RGBA color. */
+export function withOpacity(
+  color: number[] | null | undefined,
+  opacity = 1
+): [number, number, number, number] {
+  if (!color) {
+    return [0, 0, 0, 0];
+  }
+
+  const alpha = color.length > 3 ? (color[3] <= 1 ? color[3] * 255 : color[3]) : 255;
+  return [color[0], color[1], color[2], Math.round(alpha * opacity)];
+}