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

package/src/text-font.ts

@@ -0,0 +1,150 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * A label font as CSS: a family list ending with a generic family, a numeric weight and a style.
+ */
+export type LabelFont = {
+  /** CSS `font-family` list, e.g. `"Noto Sans", sans-serif`. */
+  fontFamily: string;
+  /** CSS numeric `font-weight`, 100-900. */
+  fontWeight: number;
+  /** CSS `font-style`. */
+  fontStyle: 'normal' | 'italic';
+};
+
+/**
+ * Overrides the label font derived from `text-font`. A string is the CSS family list for every
+ * label; the weight and style still come from `text-font`. A function receives the evaluated
+ * `text-font` names and returns a CSS family list, or any of the {@link LabelFont} fields; fields
+ * it leaves out, or a `null` result, keep the mapped values.
+ */
+export type LabelFontFamily =
+  | string
+  | ((fontStack: string[]) => string | Partial<LabelFont> | null | undefined);
+
+/** The style specification's default `text-font`. */
+export const DEFAULT_TEXT_FONT = ['Open Sans Regular', 'Arial Unicode MS Regular'];
+
+const FONT_WEIGHTS = new Map<string, number>([
+  ['thin', 100],
+  ['hairline', 100],
+  ['extralight', 200],
+  ['ultralight', 200],
+  ['light', 300],
+  ['regular', 400],
+  ['normal', 400],
+  ['book', 400],
+  ['roman', 400],
+  ['medium', 500],
+  ['semibold', 600],
+  ['demibold', 600],
+  ['bold', 700],
+  ['extrabold', 800],
+  ['ultrabold', 800],
+  ['black', 900],
+  ['heavy', 900]
+]);
+
+/** First words of two-word weights such as `Semi Bold` and `Extra Light`. */
+const WEIGHT_PREFIXES = new Set(['semi', 'demi', 'extra', 'ultra']);
+
+const FONT_STYLES = ['italic', 'oblique'];
+
+/**
+ * Splits a font name such as `Open Sans Semibold Italic` into its family and its trailing weight
+ * and style words. Only trailing words are read, and a name is never reduced to nothing.
+ */
+function parseFontName(name: string): {family: string; fontWeight: number; italic: boolean} {
+  const words = name.trim().split(/\s+/).filter(Boolean);
+  let fontWeight = 400;
+  let italic = false;
+
+  const last = words.at(-1)?.toLowerCase() || '';
+  const style = FONT_STYLES.find(suffix => last.endsWith(suffix));
+  const styleWeight = style ? last.slice(0, -style.length) : '';
+  if (style && words.length > 1 && (!styleWeight || FONT_WEIGHTS.has(styleWeight))) {
+    italic = true;
+    words.pop();
+    if (styleWeight) {
+      // A combined word such as `BoldItalic`.
+      return {family: words.join(' '), fontWeight: FONT_WEIGHTS.get(styleWeight)!, italic};
+    }
+  }
+
+  const weightWord = words.at(-1)?.toLowerCase() || '';
+  if (words.length > 1 && FONT_WEIGHTS.has(weightWord)) {
+    fontWeight = FONT_WEIGHTS.get(weightWord)!;
+    words.pop();
+    const prefix = words.at(-1)?.toLowerCase() || '';
+    if (words.length > 1 && WEIGHT_PREFIXES.has(prefix) && FONT_WEIGHTS.has(prefix + weightWord)) {
+      fontWeight = FONT_WEIGHTS.get(prefix + weightWord)!;
+      words.pop();
+    }
+  }
+
+  return {family: words.join(' '), fontWeight, italic};
+}
+
+/** The generic CSS family a font name implies: serif or monospace when it says so. */
+function getGenericFamily(family: string): string {
+  const words = family.toLowerCase().split(' ');
+  if (words.includes('mono') || words.includes('monospace')) {
+    return 'monospace';
+  }
+  if (words.includes('serif') && !words.includes('sans')) {
+    return 'serif';
+  }
+  return 'sans-serif';
+}
+
+function quoteFamily(family: string): string {
+  return `"${family.replace(/["\\]/g, '\\$&')}"`;
+}
+
+/**
+ * Maps a style's `text-font` stack to a CSS font. Each name's trailing weight and style words
+ * (`Regular`, `Bold`, `Semibold Italic`, ...) are stripped to give its family; the families are
+ * listed in stack order and end with a generic family, so labels still draw when none of the
+ * fonts is installed. `TextLayer` takes one weight per layer, so the weight and style come from
+ * the first font of the stack.
+ */
+export function getLabelFont(fontStack: string[]): LabelFont {
+  const fonts = fontStack.map(parseFontName);
+  const families = [...new Set(fonts.map(font => font.family))];
+  const generic = families.length ? getGenericFamily(families[0]) : 'sans-serif';
+  return {
+    fontFamily: [...families.map(quoteFamily), generic].join(', '),
+    fontWeight: fonts[0]?.fontWeight ?? 400,
+    fontStyle: fonts[0]?.italic ? 'italic' : 'normal'
+  };
+}
+
+/** {@link getLabelFont}, with the caller's {@link LabelFontFamily} override applied. */
+export function resolveLabelFont(
+  fontStack: string[],
+  fontFamily?: LabelFontFamily | null
+): LabelFont {
+  const font = getLabelFont(fontStack);
+  const override = typeof fontFamily === 'function' ? fontFamily(fontStack) : fontFamily;
+  if (typeof override === 'string') {
+    return {...font, fontFamily: override};
+  }
+  if (!override) {
+    return font;
+  }
+  const fields = Object.entries(override).filter(
+    ([, value]) => value !== undefined && value !== null
+  );
+  return {...font, ...Object.fromEntries(fields)};
+}
+
+/**
+ * `TextLayer`'s `fontWeight` prop for a font. `TextLayer` has no `fontStyle` prop and writes
+ * `fontWeight` in front of the size in the canvas font string, so an italic font puts its style
+ * in front of the weight there (`italic 400`), which is valid CSS font shorthand.
+ */
+export function getTextLayerFontWeight(font: LabelFont): number | string {
+  return font.fontStyle === 'italic' ? `italic ${font.fontWeight}` : font.fontWeight;
+}

package/src/text-halo-blur-extension.ts

@@ -0,0 +1,115 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {LayerExtension} from '@deck.gl/core';
+import type {Layer} from '@deck.gl/core';
+
+/**
+ * MapLibre GL JS's symbol shader widens the halo edge by `text-halo-blur * 1.19` pixels on each
+ * side of the halo edge, on top of the edge's own antialiasing.
+ */
+const MAPLIBRE_HALO_BLUR_SCALE = 1.19;
+
+/**
+ * Converts a `text-halo-blur`, in pixels, to the signed distance by which `TextLayer`'s halo edge
+ * fades on each side, beyond the edge's own smoothing, for text of `textSize` pixels drawn from a
+ * font atlas of `fontSize` pixels whose distance field reaches `radius` atlas pixels. As in
+ * MapLibre, the fade is `1.19 * blur` screen pixels on each side of the halo edge; an atlas pixel
+ * is `textSize / fontSize` screen pixels and `1 / radius` of the distance field.
+ */
+export function getHaloBlurGamma(
+  haloBlur: number,
+  textSize: number,
+  {fontSize, radius}: {fontSize: number; radius: number}
+): number {
+  if (!(haloBlur > 0) || !(textSize > 0)) {
+    return 0;
+  }
+  const atlasPixels = (MAPLIBRE_HALO_BLUR_SCALE * haloBlur * fontSize) / textSize;
+  // Rounded so that labels whose blurs differ imperceptibly share one text sublayer.
+  return Math.round((atlasPixels / radius) * 1000) / 1000;
+}
+
+const textHaloBlurModule = {
+  name: 'textHaloBlur',
+  fs: /* glsl */ `\
+layout(std140) uniform textHaloBlurUniforms {
+  float gamma;
+  float capped;
+} textHaloBlur;
+`,
+  uniformTypes: {gamma: 'f32', capped: 'f32'}
+} as const;
+
+/**
+ * `LabelCharactersLayer` (the characters of a `LabelTextLayer`) sets the alpha of a halo with this
+ * statement, from the halo edge's own antialiasing, `labelHaloGamma`. It runs in the halo pass
+ * only: the pass that draws the glyphs on top draws no outline. `haloGamma`, the width the halo
+ * fades over, is also the width of the ring's inner edge, which the layer draws next.
+ */
+const OUTLINE_ALPHA_STATEMENT = 'alpha = inBorder;';
+
+const injection = {
+  [OUTLINE_ALPHA_STATEMENT]: /* glsl */ `
+      if (textHaloBlur.gamma > 0.0) {
+        // Fades the halo over the wider edge. The blur widens by 1 / cos(pitch) on a pitched map,
+        // as the edge's own antialiasing does: MapLibre divides both by its u_gamma_scale. With
+        // 'capped', capped so that the halo is transparent where the distance field ends, at the
+        // edge of the glyph's quad: the font atlas stores a few 1/255 steps of distance there.
+        // Uncapped, as MapLibre draws its glyphs, the faintest part of a wide fade is cut there.
+        haloGamma = labelHaloGamma + textHaloBlur.gamma / labelEdge.foreshortening;
+        if (textHaloBlur.capped > 0.5) {
+          haloGamma = max(labelHaloGamma, min(haloGamma, sdf.outlineBuffer - 4.0 / 255.0));
+        }
+        alpha = smoothstep(sdf.outlineBuffer - haloGamma, sdf.outlineBuffer + haloGamma, distance);
+      }
+`
+};
+
+type TextHaloBlurExtensionProps = {
+  /** Distance by which the halo edge fades on each side, see {@link getHaloBlurGamma}. */
+  textHaloBlurGamma?: number;
+  /**
+   * Whether the fade ends where the distance field does (default), or reaches past it and is cut
+   * at the glyph's quad, as MapLibre GL JS draws its glyphs.
+   */
+  textHaloBlurCapped?: boolean;
+};
+
+/**
+ * Blurs the halo of a `LabelTextLayer`, as MapLibre GL JS draws `text-halo-blur`: the halo edge
+ * fades over `textHaloBlurGamma` more distance on each side, beyond its own antialiasing of 0.84
+ * device pixels (see `LabelCharactersLayer`), as MapLibre's. Labels that lie on a pitched map fade
+ * over 1 / cos(pitch) times that distance, blur and antialiasing alike, as MapLibre's (see
+ * `getLabelForeshortening`). The glyphs stay as sharp as without the extension. WebGL only; on
+ * WebGPU the halo draws without blur.
+ */
+export class TextHaloBlurExtension extends LayerExtension {
+  static extensionName = 'TextHaloBlurExtension';
+  static defaultProps = {textHaloBlurGamma: 0, textHaloBlurCapped: true};
+
+  getShaders(this: Layer<TextHaloBlurExtensionProps>) {
+    if (this.context.device.type === 'webgpu') {
+      return {};
+    }
+    // The statement is only in the characters' shader, so the text background is unchanged.
+    return {modules: [textHaloBlurModule], inject: injection};
+  }
+
+  draw(this: Layer<TextHaloBlurExtensionProps>) {
+    if (this.context.device.type === 'webgpu') {
+      return;
+    }
+    this.setShaderModuleProps({
+      textHaloBlur: {
+        gamma: this.props.textHaloBlurGamma ?? 0,
+        capped: this.props.textHaloBlurCapped === false ? 0 : 1
+      }
+    });
+  }
+}