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

package/src/globe-line-angle-extension.ts

@@ -0,0 +1,131 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {LayerExtension, project32} from '@deck.gl/core';
+import type {Layer} from '@deck.gl/core';
+
+/**
+ * Turns a billboard drawn along a line on a globe from the line's direction at the anchor (the
+ * instance angle, counter-clockwise from east) to that direction as the view draws it, so the label
+ * follows its line on every frame, at any bearing, anywhere on the globe, without updating any
+ * attribute. The direction on screen is the line's tangent at the anchor, east and north on the
+ * globe's surface (the derivatives of `project_globe_`), through the view-projection matrix: exact,
+ * with no difference of nearby positions to lose precision.
+ *
+ * With `keepUpright`, a billboard that would read upside down there is turned by another half turn,
+ * as `getUprightAngle` turns it from the bearing alone: away from the middle of the view the bearing
+ * does not tell which way the view draws a line.
+ *
+ * With `pixelOffset`, the name of the layer's pixel offset attribute, that offset is not turned
+ * around with the billboard: it is a direction along and across the line (see
+ * `withLineDirection`), and stays on the same side of the line.
+ *
+ * The instance angle and pixel offset are only declared in the layer's own shader source, after the
+ * hook functions, so they are copied into globals at the start of `main`.
+ */
+const getGlobeLineAngleModule = (keepUpright: boolean, pixelOffset?: string) => ({
+  name: `globeLineAngle${keepUpright ? 'Upright' : ''}${pixelOffset ? `_${pixelOffset}` : ''}`,
+  dependencies: [project32],
+  inject: {
+    'vs:#decl': /* glsl */ `
+float globeLineAngle_angle;
+vec2 globeLineAngle_pixelOffset;
+`,
+    'vs:#main-start': /* glsl */ `
+  globeLineAngle_angle = radians(instanceAngles);
+  // As the layer adds it to the billboard's offset, y down.
+  globeLineAngle_pixelOffset = ${pixelOffset ? `vec2(${pixelOffset}.x, -${pixelOffset}.y)` : 'vec2(0.0)'};
+`,
+    'vs:DECKGL_FILTER_SIZE': /* glsl */ `
+  if (project.projectionMode == PROJECTION_MODE_GLOBE) {
+    float globeLineAngle_lambda = radians(geometry.worldPosition.x);
+    float globeLineAngle_phi = radians(geometry.worldPosition.y);
+    vec3 globeLineAngle_east = vec3(cos(globeLineAngle_lambda), sin(globeLineAngle_lambda), 0.0);
+    vec3 globeLineAngle_north = vec3(
+      -sin(globeLineAngle_lambda) * sin(globeLineAngle_phi),
+      cos(globeLineAngle_lambda) * sin(globeLineAngle_phi),
+      cos(globeLineAngle_phi)
+    );
+    vec3 globeLineAngle_tangent = cos(globeLineAngle_angle) * globeLineAngle_east +
+      sin(globeLineAngle_angle) * globeLineAngle_north;
+    vec4 globeLineAngle_clip = project_common_position_to_clipspace(
+      vec4(project_position(geometry.worldPosition), 1.0)
+    );
+    vec4 globeLineAngle_clipTangent = project.viewProjectionMatrix * vec4(globeLineAngle_tangent, 0.0);
+    // The derivative of the anchor's normalized device coordinates, times w squared, in pixels.
+    vec2 globeLineAngle_screen = (globeLineAngle_clipTangent.xy * globeLineAngle_clip.w -
+      globeLineAngle_clip.xy * globeLineAngle_clipTangent.w) * project.viewportSize;
+    float globeLineAngle_turn =
+      atan(globeLineAngle_screen.y, globeLineAngle_screen.x) - globeLineAngle_angle;
+    float globeLineAngle_cos = cos(globeLineAngle_turn);
+    float globeLineAngle_sin = sin(globeLineAngle_turn);
+    mat2 globeLineAngle_rotation =
+      mat2(globeLineAngle_cos, globeLineAngle_sin, -globeLineAngle_sin, globeLineAngle_cos);
+${
+  keepUpright
+    ? `    if (globeLineAngle_screen.x < 0.0) {
+      // Turned around, but for the pixel offset: -(size - offset) + offset.
+      size.xy = 2.0 * globeLineAngle_pixelOffset - size.xy;
+    }
+`
+    : ''
+}    size.xy = globeLineAngle_rotation * size.xy;
+  }
+`
+  }
+});
+
+const GLOBE_LINE_ANGLE_MODULES = {
+  free: getGlobeLineAngleModule(false),
+  upright: getGlobeLineAngleModule(true),
+  // The pixel offset attributes of `IconLayer` (and the glyphs of `TextLayer`) and of
+  // `TextLayer`'s backgrounds.
+  instancePixelOffset: getGlobeLineAngleModule(true, 'instancePixelOffset'),
+  instancePixelOffsets: getGlobeLineAngleModule(true, 'instancePixelOffsets')
+};
+
+/**
+ * Keeps billboards drawn along lines (labels and icons whose rotation is aligned to the map) on
+ * their lines in a `GlobeView`, which draws them in screen space: their angles are taken from
+ * north up, and the shader turns them as the view draws the line, upright with `keepUpright`. In
+ * other views it does nothing. Add it only to billboards (the shader would also turn the offset of
+ * a layer drawn in the map plane) whose angle is a direction on the map. WebGL only: on WebGPU the
+ * extension adds no shader code, and they stay as they are drawn from north up.
+ *
+ * Added to a composite layer such as `TextLayer`, it reaches the character and background
+ * sublayers. With `keepOffsetSide`, text kept upright is turned around without its pixel offset,
+ * which must then be a direction along and across the line, as `text-offset` is.
+ */
+export class GlobeLineAngleExtension extends LayerExtension<{
+  keepUpright: boolean;
+  keepOffsetSide?: boolean;
+}> {
+  static extensionName = 'GlobeLineAngleExtension';
+
+  constructor(opts: {keepUpright: boolean; keepOffsetSide?: boolean}) {
+    super(opts);
+  }
+
+  getShaders(this: Layer, extension: GlobeLineAngleExtension) {
+    if (this.context.device.type === 'webgpu') {
+      return {};
+    }
+    const {keepUpright, keepOffsetSide} = extension.opts;
+    if (!keepUpright) {
+      return {modules: [GLOBE_LINE_ANGLE_MODULES.free]};
+    }
+    if (!keepOffsetSide) {
+      return {modules: [GLOBE_LINE_ANGLE_MODULES.upright]};
+    }
+    // `TextLayer`'s backgrounds name the attribute in the plural.
+    const attributes = (this.getAttributeManager() as any)?.attributes || {};
+    return {
+      modules: [
+        attributes.instancePixelOffsets
+          ? GLOBE_LINE_ANGLE_MODULES.instancePixelOffsets
+          : GLOBE_LINE_ANGLE_MODULES.instancePixelOffset
+      ]
+    };
+  }
+}

package/src/glyph-font-renderer.ts

@@ -0,0 +1,173 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import TinySDF from '@mapbox/tiny-sdf';
+import type {TextLayerProps} from '@deck.gl/layers';
+import {GLYPH_BORDER, GLYPH_EM} from './glyph-pbf';
+import type {Glyph} from './glyph-pbf';
+import {isLocalGlyph} from './glyph-store';
+import type {GlyphStore} from './glyph-store';
+
+type GetFontRenderer = NonNullable<TextLayerProps['_getFontRenderer']>;
+type FontRenderer = ReturnType<GetFontRenderer>;
+
+/**
+ * `TextLayer`'s font settings for glyphs from a style's `glyphs` URL: distance fields one em of
+ * {@link GLYPH_EM} pixels high, reaching 8 pixels, with the edge at 0.75, as MapLibre GL JS draws
+ * them. Cells are packed `buffer` pixels apart, the border of the glyph bitmaps.
+ */
+export const GLYPH_FONT_SETTINGS = {
+  sdf: true,
+  fontSize: GLYPH_EM,
+  buffer: GLYPH_BORDER,
+  radius: 8,
+  cutoff: 0.25,
+  smoothing: 0.1
+};
+
+/**
+ * MapLibre GL JS sets each line's glyphs this many pixels below the line's top, at one em of
+ * {@link GLYPH_EM} pixels (`SHAPING_DEFAULT_OFFSET`, negated).
+ */
+const LINE_GLYPH_OFFSET = 17;
+
+/**
+ * MapLibre GL JS's alignment of a glyph drawn with the browser's fonts (see `isLocalGlyph`) with
+ * the glyphs of glyph ranges, whose `top` is measured from above the em box.
+ */
+const LOCAL_GLYPH_TOP = 27.5;
+const LOCAL_GLYPH_LEFT = 0.5;
+
+/** The font-weight MapLibre GL JS draws local glyphs in, from the font stack's names. */
+function getLocalGlyphWeight(fontStack: string): string {
+  if (/bold/i.test(fontStack)) return '900';
+  if (/medium/i.test(fontStack)) return '500';
+  if (/light/i.test(fontStack)) return '200';
+  return '400';
+}
+
+const LOCAL_GLYPH_SDFS = new Map<string, TinySDF>();
+
+/**
+ * A glyph that MapLibre GL JS draws with the browser's fonts, as a glyph of a glyph range. MapLibre
+ * draws these at twice the resolution; here they share the one-em atlas of the other glyphs.
+ */
+function getLocalGlyph(fontStack: string, codePoint: number): Glyph | null {
+  if (typeof document === 'undefined' && typeof OffscreenCanvas === 'undefined') {
+    return null;
+  }
+  const fontWeight = getLocalGlyphWeight(fontStack);
+  let sdf = LOCAL_GLYPH_SDFS.get(fontWeight);
+  if (!sdf) {
+    sdf = new TinySDF({
+      fontSize: GLYPH_EM,
+      buffer: GLYPH_BORDER,
+      radius: GLYPH_FONT_SETTINGS.radius,
+      cutoff: GLYPH_FONT_SETTINGS.cutoff,
+      fontFamily: 'sans-serif',
+      fontWeight
+    });
+    LOCAL_GLYPH_SDFS.set(fontWeight, sdf);
+  }
+  const drawn = sdf.draw(String.fromCodePoint(codePoint));
+  const width = drawn.glyphWidth;
+  const height = drawn.glyphHeight;
+  return {
+    id: codePoint,
+    // TinySDF draws `glyphWidth + 2 * buffer` by `glyphHeight + 2 * buffer`, as a glyph range does.
+    bitmap: width && height ? drawn.data : new Uint8Array(0),
+    width: width && height ? width : 0,
+    height: width && height ? height : 0,
+    left: drawn.glyphLeft + LOCAL_GLYPH_LEFT,
+    top: drawn.glyphTop - LOCAL_GLYPH_TOP,
+    advance: drawn.glyphAdvance
+  };
+}
+
+/**
+ * The glyph a character of `fontStack` is drawn with: from the store's ranges, or with the browser's
+ * fonts for the characters MapLibre GL JS draws so. Null while its range loads, and when the range
+ * has none: the character is then not drawn, as in MapLibre.
+ */
+export function getStyleGlyph(
+  store: GlyphStore,
+  fontStack: string,
+  character: string
+): Glyph | null {
+  const codePoint = character.codePointAt(0);
+  if (codePoint === undefined) {
+    return null;
+  }
+  if (isLocalGlyph(codePoint)) {
+    return getLocalGlyph(fontStack, codePoint);
+  }
+  return store.getGlyph(fontStack, codePoint) ?? null;
+}
+
+/**
+ * A function giving a character's advance in ems: the glyph's advance, as MapLibre GL JS lays text
+ * out. A character without a glyph advances nothing.
+ */
+export function getGlyphCharacterMeasurer(
+  store: GlyphStore,
+  fontStack: string
+): (character: string) => number {
+  const widths = new Map<string, number>();
+  return character => {
+    let width = widths.get(character);
+    if (width === undefined) {
+      const glyph = getStyleGlyph(store, fontStack, character);
+      width = (glyph?.advance ?? 0) / GLYPH_EM;
+      // A character whose range is still loading is measured again once it has loaded.
+      if (glyph || store.hasGlyphs(fontStack, character)) {
+        widths.set(character, width);
+      }
+    }
+    return width;
+  };
+}
+
+/**
+ * `TextLayer`'s font renderer for the glyphs of a font stack. With
+ * {@link GLYPH_FONT_SETTINGS}, `TextLayer` lays each character's glyph out as MapLibre GL JS does:
+ * the line's baseline offset puts it {@link LINE_GLYPH_OFFSET} pixels below the line's top, and the
+ * glyph's bitmap is drawn `top` pixels below that and `left` pixels right of the pen.
+ */
+export function getGlyphFontRenderer(store: GlyphStore, fontStack: string): FontRenderer {
+  return {
+    measure(character?: string) {
+      if (character === undefined) {
+        // `TextLayer` sets the baseline `(ascent - descent) / 2` from the middle of the line.
+        return {advance: 0, width: 0, ascent: 0, descent: 2 * LINE_GLYPH_OFFSET};
+      }
+      const glyph = getStyleGlyph(store, fontStack, character);
+      if (!glyph) {
+        return {advance: 0, width: 0, ascent: 0, descent: 0};
+      }
+      return {
+        advance: glyph.advance,
+        width: glyph.width,
+        ascent: glyph.top,
+        descent: glyph.height - glyph.top
+      };
+    },
+    draw(character: string) {
+      const glyph = getStyleGlyph(store, fontStack, character);
+      if (!glyph || !glyph.bitmap.length) {
+        return {data: new ImageData(1, 1), left: 0, top: 0};
+      }
+      const width = glyph.width + 2 * GLYPH_BORDER;
+      const height = glyph.height + 2 * GLYPH_BORDER;
+      const data = new ImageData(width, height);
+      for (let i = 0; i < glyph.bitmap.length; i++) {
+        data.data[4 * i + 3] = glyph.bitmap[i];
+      }
+      return {data, left: GLYPH_BORDER - glyph.left, top: GLYPH_BORDER};
+    }
+  };
+}

package/src/glyph-pbf.ts

@@ -0,0 +1,164 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * The pixels of distance field around each glyph of a glyph range, on every side, beyond its
+ * `width` and `height`: a bitmap is `width + 6` by `height + 6`.
+ */
+export const GLYPH_BORDER = 3;
+
+/** The size, in pixels, at which glyph ranges are drawn: one em. */
+export const GLYPH_EM = 24;
+
+/** Code points per glyph range: a range file holds `256 * n` to `256 * n + 255`. */
+export const GLYPH_RANGE_SIZE = 256;
+
+/**
+ * A glyph of a glyph range, as MapLibre GL JS reads it: a signed distance field and its metrics,
+ * in pixels at {@link GLYPH_EM}.
+ */
+export type Glyph = {
+  /** Unicode code point. */
+  id: number;
+  /**
+   * One byte per pixel, `width + 2 * GLYPH_BORDER` by `height + 2 * GLYPH_BORDER`; empty for a
+   * glyph without ink, such as a space.
+   */
+  bitmap: Uint8Array | Uint8ClampedArray;
+  /** Width of the ink. */
+  width: number;
+  /** Height of the ink. */
+  height: number;
+  /** From the pen position to the left of the ink. */
+  left: number;
+  /** Vertical bearing of the top of the ink, as MapLibre GL JS reads it. */
+  top: number;
+  /** From the pen position to the next. */
+  advance: number;
+};
+
+/** A reader of the protocol buffer encoding: just what glyph ranges use. */
+class Reader {
+  position = 0;
+  constructor(readonly bytes: Uint8Array) {}
+
+  readVarint(): number {
+    let value = 0;
+    let shift = 0;
+    for (;;) {
+      if (this.position >= this.bytes.length) {
+        throw new Error('Truncated glyph range');
+      }
+      const byte = this.bytes[this.position++];
+      // Glyph fields fit in 32 bits; multiplying keeps larger values exact, up to 2^53.
+      value += (byte & 0x7f) * 2 ** shift;
+      if (byte < 0x80) {
+        return value;
+      }
+      shift += 7;
+      if (shift > 49) {
+        throw new Error('Invalid varint in glyph range');
+      }
+    }
+  }
+
+  readSVarint(): number {
+    const value = this.readVarint();
+    return value % 2 === 1 ? -(value + 1) / 2 : value / 2;
+  }
+
+  /** The bytes of a length-delimited field, which the reader then skips. */
+  readBytes(): Uint8Array {
+    const length = this.readVarint();
+    const end = this.position + length;
+    if (end > this.bytes.length) {
+      throw new Error('Truncated glyph range');
+    }
+    const bytes = this.bytes.subarray(this.position, end);
+    this.position = end;
+    return bytes;
+  }
+
+  skip(wireType: number): void {
+    if (wireType === 0) {
+      this.readVarint();
+    } else if (wireType === 1) {
+      this.position += 8;
+    } else if (wireType === 2) {
+      this.readBytes();
+    } else if (wireType === 5) {
+      this.position += 4;
+    } else {
+      throw new Error(`Unsupported wire type ${wireType} in glyph range`);
+    }
+  }
+
+  /** Calls `read` with the tag and wire type of each field, which `read` must consume or skip. */
+  readFields(read: (tag: number, wireType: number) => void): void {
+    while (this.position < this.bytes.length) {
+      const key = this.readVarint();
+      read(Math.floor(key / 8), key % 8);
+    }
+  }
+}
+
+function readGlyph(bytes: Uint8Array): Glyph | null {
+  const reader = new Reader(bytes);
+  const glyph: Partial<Glyph> = {};
+  reader.readFields((tag, wireType) => {
+    if (tag === 1 && wireType === 0) glyph.id = reader.readVarint();
+    else if (tag === 2 && wireType === 2) glyph.bitmap = reader.readBytes();
+    else if (tag === 3 && wireType === 0) glyph.width = reader.readVarint();
+    else if (tag === 4 && wireType === 0) glyph.height = reader.readVarint();
+    else if (tag === 5 && wireType === 0) glyph.left = reader.readSVarint();
+    else if (tag === 6 && wireType === 0) glyph.top = reader.readSVarint();
+    else if (tag === 7 && wireType === 0) glyph.advance = reader.readVarint();
+    else reader.skip(wireType);
+  });
+  const {id, width = 0, height = 0, left = 0, top = 0, advance = 0} = glyph;
+  if (id === undefined) {
+    return null;
+  }
+  // MapLibre GL JS reads every bitmap as `width + 6` by `height + 6` (its `AlphaImage`) and fails on
+  // any other size. A glyph without ink, such as a space, may leave its bitmap out or carry just
+  // the border (CARTO's glyphs do): either way it draws nothing, and only its advance counts.
+  const inked = width > 0 && height > 0;
+  const size = (width + 2 * GLYPH_BORDER) * (height + 2 * GLYPH_BORDER);
+  if (glyph.bitmap ? glyph.bitmap.length !== size : inked) {
+    return null;
+  }
+  const bitmap = inked ? glyph.bitmap! : new Uint8Array(0);
+  return {id, bitmap, width, height, left, top, advance};
+}
+
+/**
+ * Reads a glyph range, the `{fontstack}/{range}.pbf` file a style's `glyphs` URL points to: the
+ * glyphs of every font stack it holds. Glyphs whose bitmap does not match their size are skipped.
+ */
+export function parseGlyphRange(data: ArrayBuffer | Uint8Array): Glyph[] {
+  const glyphs: Glyph[] = [];
+  const reader = new Reader(data instanceof Uint8Array ? data : new Uint8Array(data));
+  reader.readFields((tag, wireType) => {
+    if (tag !== 1 || wireType !== 2) {
+      reader.skip(wireType);
+      return;
+    }
+    const fontstack = new Reader(reader.readBytes());
+    fontstack.readFields((fontstackTag, fontstackWireType) => {
+      if (fontstackTag === 3 && fontstackWireType === 2) {
+        const glyph = readGlyph(fontstack.readBytes());
+        if (glyph) {
+          glyphs.push(glyph);
+        }
+      } else {
+        fontstack.skip(fontstackWireType);
+      }
+    });
+  });
+  return glyphs;
+}