@deck.gl/extensions 9.4.0-beta.1 → 9.4.0-beta.3

package/package.json

@@ -3,7 +3,7 @@
   "description": "Plug-and-play functionalities for deck.gl layers",
   "license": "MIT",
   "type": "module",
-  "version": "9.4.0-beta.1",
+  "version": "9.4.0-beta.3",
   "publishConfig": {
     "access": "public"
   },
@@ -42,14 +42,14 @@
     "prepublishOnly": "npm run build-bundle && npm run build-bundle -- --env=dev"
   },
   "dependencies": {
-    "@luma.gl/shadertools": "^9.4.0-beta.3",
-    "@luma.gl/webgl": "^9.4.0-beta.3",
+    "@luma.gl/shadertools": "^9.4.0-beta.4",
+    "@luma.gl/webgl": "^9.4.0-beta.4",
     "@math.gl/core": "^4.1.0"
   },
   "peerDependencies": {
     "@deck.gl/core": "~9.3.0-beta.2",
-    "@luma.gl/core": "~9.4.0-beta.3",
-    "@luma.gl/engine": "~9.4.0-beta.3"
+    "@luma.gl/core": "~9.4.0-beta.4",
+    "@luma.gl/engine": "~9.4.0-beta.4"
   },
-  "gitHead": "5b00a0ced09284c2a642c8ffc56748629f5e796b"
+  "gitHead": "7f1e9e63019e6525b3f804cbadcf390ed9d40b65"
 }

package/src/fill-style/fill-style-extension.ts

@@ -5,31 +5,47 @@
 import {LayerExtension} from '@deck.gl/core';
 
 import {FillStyleModuleProps, patternShaders} from './shader-module';
+import {
+  packProceduralPatterns,
+  PROCEDURAL_PATTERN_TEXTURE_FORMAT,
+  type ProceduralPatternMapping
+} from './procedural-pattern';
 
 import type {
   Layer,
   LayerContext,
+  Color,
   DefaultProps,
   Accessor,
   AccessorFunction,
   TextureSource,
+  Unit,
   UpdateParameters
 } from '@deck.gl/core';
 import type {Texture} from '@luma.gl/core';
 
+function leastCommonMultiple(a: number, b: number): number {
+  if (!Number.isInteger(b) || b <= 0) return 0;
+  if (a === 0) return b;
+  let [x, y] = [a, b];
+  while (y > 0) [x, y] = [y, x % y];
+  return (a / x) * b;
+}
+
 const defaultProps: DefaultProps<FillStyleExtensionProps> = {
   fillPatternEnabled: true,
   fillPatternAtlas: {
     type: 'image',
     value: null,
-    async: true,
-    parameters: {lodMaxClamp: 0}
+    async: true
   },
   fillPatternMapping: {type: 'object', value: {}, async: true},
   fillPatternMask: true,
+  fillPatternSizeUnits: 'meters',
   getFillPattern: {type: 'accessor', value: d => d.pattern},
   getFillPatternScale: {type: 'accessor', value: 1},
-  getFillPatternOffset: {type: 'accessor', value: [0, 0]}
+  getFillPatternOffset: {type: 'accessor', value: [0, 0]},
+  getFillPatternBackgroundColor: {type: 'accessor', value: [0, 0, 0, 0]}
 };
 
 export type FillStyleExtensionProps<DataT = any> = {
@@ -37,11 +53,12 @@ export type FillStyleExtensionProps<DataT = any> = {
    * @default true
    */
   fillPatternEnabled?: boolean;
-  /** Sprite image url or texture that packs all your patterns into one layout. */
+  /** Sprite image url or texture that packs all your patterns into one layout. Ignored for procedural patterns. */
   fillPatternAtlas?: string | TextureSource;
-  /** Pattern names mapped to pattern definitions, or a url that points to a JSON file. */
+  /** Pattern names mapped to atlas frames or procedural definitions, or a URL to a JSON file. */
   fillPatternMapping?:
     | string
+    | ProceduralPatternMapping
     | Record<
         string,
         {
@@ -60,9 +77,19 @@ export type FillStyleExtensionProps<DataT = any> = {
    * @default true
    */
   fillPatternMask?: boolean;
+  /**
+   * The units of the pattern size, one of `'meters'`, `'common'` and `'pixels'`. A 24 x 24 pixel
+   * pattern at scale `1` covers 24 units of the chosen unit.
+   *
+   * With `'meters'` (the default) the pattern is anchored to the ground and zooms with the map.
+   * With `'pixels'` it keeps a constant size on screen instead, re-anchored at each integer zoom
+   * level so that the tiling is stable while zooming within a level.
+   * @default 'meters'
+   */
+  fillPatternSizeUnits?: Unit;
   /** Accessor for the name of the pattern. */
   getFillPattern?: AccessorFunction<DataT, string>;
-  /** Accessor for the scale of the pattern, relative to the original size. If the pattern is 24 x 24 pixels, scale `1` roughly yields 24 meters.
+  /** Accessor for the scale of the pattern, relative to its dimensions in `fillPatternSizeUnits`.
    * @default 1
    */
   getFillPatternScale?: Accessor<DataT, number>;
@@ -71,6 +98,13 @@ export type FillStyleExtensionProps<DataT = any> = {
    * @default [0, 0]
    */
   getFillPatternOffset?: Accessor<DataT, Readonly<[number, number]>>;
+  /**
+   * Accessor for the color filled behind the pattern. The pattern is composited on top of it, so
+   * the background is visible wherever the pattern is transparent. Fully transparent by default,
+   * which leaves the area behind the pattern unfilled.
+   * @default [0, 0, 0, 0]
+   */
+  getFillPatternBackgroundColor?: Accessor<DataT, Color>;
 };
 
 export type FillStyleExtensionOptions = {
@@ -78,6 +112,10 @@ export type FillStyleExtensionOptions = {
    * @default false
    */
   pattern: boolean;
+  /** If `true`, generates patterns in the fragment shader instead of sampling an image atlas.
+   * @default false
+   */
+  proceduralPattern: boolean;
 };
 
 /** Adds selected features to layers that render a "fill", such as the `PolygonLayer` and `ScatterplotLayer`. */
@@ -85,8 +123,11 @@ export default class FillStyleExtension extends LayerExtension<FillStyleExtensio
   static defaultProps = defaultProps;
   static extensionName = 'FillStyleExtension';
 
-  constructor({pattern = false}: Partial<FillStyleExtensionOptions> = {}) {
-    super({pattern});
+  constructor({
+    pattern = false,
+    proceduralPattern = false
+  }: Partial<FillStyleExtensionOptions> = {}) {
+    super({pattern: pattern || proceduralPattern, proceduralPattern});
   }
 
   isEnabled(layer: Layer<FillStyleExtensionProps>): boolean {
@@ -116,7 +157,9 @@ export default class FillStyleExtension extends LayerExtension<FillStyleExtensio
           size: 4,
           stepMode: 'dynamic',
           accessor: 'getFillPattern',
-          transform: extension.getPatternFrame.bind(this)
+          transform: extension.opts.proceduralPattern
+            ? extension.getProceduralPatternIndex.bind(this)
+            : extension.getPatternFrame.bind(this)
         },
         fillPatternScales: {
           size: 1,
@@ -128,6 +171,13 @@ export default class FillStyleExtension extends LayerExtension<FillStyleExtensio
           size: 2,
           stepMode: 'dynamic',
           accessor: 'getFillPatternOffset'
+        },
+        fillPatternBackgroundColors: {
+          size: 4,
+          type: 'unorm8',
+          stepMode: 'dynamic',
+          accessor: 'getFillPatternBackgroundColor',
+          defaultValue: [0, 0, 0, 255]
         }
       });
     }
@@ -136,7 +186,9 @@ export default class FillStyleExtension extends LayerExtension<FillStyleExtensio
         data: new Uint8Array(4),
         width: 1,
         height: 1
-      })
+      }),
+      ...(extension.opts.proceduralPattern &&
+        extension.createProceduralPatternTexture.call(this, {}))
     });
   }
 
@@ -150,8 +202,25 @@ export default class FillStyleExtension extends LayerExtension<FillStyleExtensio
     }
 
     if (props.fillPatternMapping && props.fillPatternMapping !== oldProps.fillPatternMapping) {
+      if (extension.opts.proceduralPattern && typeof props.fillPatternMapping !== 'string') {
+        const oldTexture = this.state.proceduralPatternTexture as Texture | undefined;
+        this.setState(
+          extension.createProceduralPatternTexture.call(
+            this,
+            props.fillPatternMapping as ProceduralPatternMapping
+          )
+        );
+        oldTexture?.delete();
+      }
       this.getAttributeManager()!.invalidate('getFillPattern');
     }
+
+    if (
+      props.fillPatternMapping !== oldProps.fillPatternMapping ||
+      props.getFillPatternScale !== oldProps.getFillPatternScale
+    ) {
+      this.setState({commonFrame: extension.getCommonFrame(props)});
+    }
   }
 
   draw(this: Layer<FillStyleExtensionProps>, params: any, extension: this) {
@@ -159,12 +228,18 @@ export default class FillStyleExtension extends LayerExtension<FillStyleExtensio
       return;
     }
 
-    const {fillPatternAtlas, fillPatternEnabled, fillPatternMask} = this.props;
+    const {fillPatternAtlas, fillPatternEnabled, fillPatternMask, fillPatternSizeUnits} =
+      this.props;
     const fillProps: FillStyleModuleProps = {
       project: params.shaderModuleProps.project,
       fillPatternEnabled,
       fillPatternMask,
-      fillPatternTexture: (fillPatternAtlas || this.state.emptyTexture) as Texture
+      fillPatternSizeUnits,
+      procedural: extension.opts.proceduralPattern,
+      fillPatternTexture: (extension.opts.proceduralPattern
+        ? this.state.proceduralPatternTexture || this.state.emptyTexture
+        : fillPatternAtlas || this.state.emptyTexture) as Texture,
+      fillPatternCommonFrame: this.state.commonFrame as [number, number] | null
     };
     this.setShaderModuleProps({fill: fillProps});
   }
@@ -172,11 +247,58 @@ export default class FillStyleExtension extends LayerExtension<FillStyleExtensio
   finalizeState(this: Layer<FillStyleExtensionProps>) {
     const emptyTexture = this.state.emptyTexture as Texture;
     emptyTexture?.delete();
+    const proceduralPatternTexture = this.state.proceduralPatternTexture as Texture;
+    proceduralPatternTexture?.delete();
   }
 
   getPatternFrame(this: Layer<FillStyleExtensionProps>, name: string) {
     const {fillPatternMapping} = this.getCurrentLayer()!.props;
     const def = fillPatternMapping && fillPatternMapping[name];
-    return def ? [def.x, def.y, def.width, def.height] : [0, 0, 0, 0];
+    return def && 'x' in def ? [def.x, def.y, def.width, def.height] : [0, 0, 0, 0];
+  }
+
+  /**
+   * Returns common frame into which all patterns fit as integer multiples
+   */
+  getCommonFrame(props: FillStyleExtensionProps): [number, number] | null {
+    const {fillPatternMapping, getFillPatternScale: scale} = props;
+    if (typeof scale !== 'number' || !(scale > 0) || typeof fillPatternMapping !== 'object') {
+      return null;
+    }
+    let width = 0;
+    let height = 0;
+    for (const name in fillPatternMapping) {
+      const frame = fillPatternMapping[name];
+      // Procedural definitions do not have atlas dimensions and do not need origin reduction here.
+      if (!('width' in frame)) return null;
+      width = leastCommonMultiple(width, frame.width);
+      height = leastCommonMultiple(height, frame.height);
+      if (!width || !height) return null;
+    }
+    return width ? [scale * width, scale * height] : null;
+  }
+
+  getProceduralPatternIndex(this: Layer<FillStyleExtensionProps>, name: string) {
+    const patternIndices = this.state.proceduralPatternIndices as
+      | ReadonlyMap<string, number>
+      | undefined;
+    return [patternIndices?.get(name) ?? 0, 0, 0, 0];
+  }
+
+  createProceduralPatternTexture(
+    this: Layer<FillStyleExtensionProps>,
+    mapping: ProceduralPatternMapping
+  ) {
+    const packedPatterns = packProceduralPatterns(mapping);
+    return {
+      proceduralPatternIndices: packedPatterns.patternIndices,
+      proceduralPatternTexture: this.context.device.createTexture({
+        data: packedPatterns.data,
+        width: packedPatterns.width,
+        height: packedPatterns.height,
+        format: PROCEDURAL_PATTERN_TEXTURE_FORMAT,
+        sampler: {minFilter: 'nearest', magFilter: 'nearest'}
+      })
+    };
   }
 }

package/src/fill-style/procedural-pattern.ts

@@ -0,0 +1,203 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export type HatchPatternConfig = {
+  type: 'hatch';
+  /** Direction of the hatch lines in degrees. @default 0 */
+  angle?: number;
+  /** Width of each hatch line. @default 1 */
+  strokeWidth?: number;
+  /** Empty edge-to-edge distance between lines. A tuple alternates the two gap values. @default 1 */
+  gap?: number | Readonly<[number, number]>;
+};
+
+export type CrossHatchPatternConfig = {
+  type: 'cross-hatch';
+  /** Directions of the two intersecting sets of hatch lines in degrees. @default [45, 135] */
+  angles?: Readonly<[number, number]>;
+  /** Width of each hatch line. @default 1 */
+  strokeWidth?: number;
+  /** Empty edge-to-edge distance between adjacent lines. @default 1 */
+  gap?: number;
+};
+
+export type DotPatternConfig = {
+  type: 'dots';
+  /** Radius of each dot. @default 1 */
+  radius?: number;
+  /** Empty edge-to-edge distance between dots along both grid axes. @default 1 */
+  gap?: number;
+  /** Rotation of the dot grid in degrees. @default 0 */
+  angle?: number;
+  /** Degrees that the second grid axis tilts toward the first; 0 produces an orthogonal grid. @default 0 */
+  skew?: number;
+};
+
+/** Procedural pattern shapes supported by FillStyleExtension. */
+export type ProceduralPatternConfig =
+  | HatchPatternConfig
+  | CrossHatchPatternConfig
+  | DotPatternConfig;
+
+export type ProceduralPatternMapping = Readonly<Record<string, ProceduralPatternConfig>>;
+
+export const PROCEDURAL_PATTERN_TEXTURE_FORMAT = 'rg32float' as const;
+export const PROCEDURAL_PATTERN_COMPONENTS_PER_TEXEL = 2;
+export const PROCEDURAL_PATTERN_TEXELS_PER_PATTERN = 4;
+
+export const PROCEDURAL_PATTERN_TYPES = {
+  none: 0,
+  hatch: 1,
+  crossHatch: 2,
+  dots: 3
+} as const;
+
+/** Component offsets within each fixed-width pattern record. */
+export const PROCEDURAL_PATTERN_OFFSETS = {
+  type: 0,
+  size: 1,
+  gap0: 2,
+  gap1: 3,
+  angle0: 4,
+  angle1: 5,
+  /** Number of alternating gaps, hatch directions, or dot-grid axes, depending on type. */
+  elementCount: 6
+} as const;
+
+export type PackedProceduralPatterns = {
+  data: Float32Array;
+  width: number;
+  height: 1;
+  /** Maps the user-facing pattern id to its record in the data texture. Index 0 is reserved for none. */
+  patternIndices: ReadonlyMap<string, number>;
+};
+
+const COMPONENTS_PER_PATTERN =
+  PROCEDURAL_PATTERN_COMPONENTS_PER_TEXEL * PROCEDURAL_PATTERN_TEXELS_PER_PATTERN;
+const DEGREES_TO_RADIANS = Math.PI / 180;
+const DEFAULT_SIZE = 1;
+const DEFAULT_GAP = 1;
+const DEFAULT_HATCH_ANGLE = 0;
+const DEFAULT_CROSS_HATCH_ANGLES = [45, 135] as const;
+const DEFAULT_DOT_ANGLE = 0;
+const DEFAULT_DOT_SKEW = 0;
+
+/**
+ * Packs procedural pattern definitions into an `rg32float`-compatible data array.
+ * The fixed record width keeps vertex-shader lookup independent of the pattern type.
+ */
+export function packProceduralPatterns(
+  mapping: ProceduralPatternMapping
+): PackedProceduralPatterns {
+  const entries = Object.entries(mapping);
+  // The zero-filled first record represents a missing or disabled pattern.
+  const data = new Float32Array((entries.length + 1) * COMPONENTS_PER_PATTERN);
+  const patternIndices = new Map<string, number>();
+
+  entries.forEach(([id, config], entryIndex) => {
+    const patternIndex = entryIndex + 1;
+    const offset = patternIndex * COMPONENTS_PER_PATTERN;
+    patternIndices.set(id, patternIndex);
+
+    switch (config.type) {
+      case 'hatch': {
+        const gap = config.gap === undefined ? DEFAULT_GAP : config.gap;
+        const strokeWidth = config.strokeWidth === undefined ? DEFAULT_SIZE : config.strokeWidth;
+        const angle = config.angle === undefined ? DEFAULT_HATCH_ANGLE : config.angle;
+        if (Array.isArray(gap) && gap.length !== 2) {
+          throw new Error(`${id}.gap must be a number or a two-element array`);
+        }
+        const gaps = Array.isArray(gap) ? gap : [gap, gap];
+        validatePositive(strokeWidth, `${id}.strokeWidth`);
+        validateNonNegative(gaps[0], `${id}.gap[0]`);
+        validateNonNegative(gaps[1], `${id}.gap[1]`);
+        validateAngle(angle, `${id}.angle`);
+
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.type] = PROCEDURAL_PATTERN_TYPES.hatch;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.size] = strokeWidth;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.gap0] = gaps[0];
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.gap1] = gaps[1];
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.angle0] = angle * DEGREES_TO_RADIANS;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.elementCount] = Array.isArray(gap) ? 2 : 1;
+        break;
+      }
+
+      case 'cross-hatch': {
+        const angles = config.angles === undefined ? DEFAULT_CROSS_HATCH_ANGLES : config.angles;
+        const strokeWidth = config.strokeWidth === undefined ? DEFAULT_SIZE : config.strokeWidth;
+        const gap = config.gap === undefined ? DEFAULT_GAP : config.gap;
+        if (!Array.isArray(angles) || angles.length !== 2) {
+          throw new Error(`${id}.angles must be a two-element array`);
+        }
+        validatePositive(strokeWidth, `${id}.strokeWidth`);
+        validateNonNegative(gap, `${id}.gap`);
+        validateAngle(angles[0], `${id}.angles[0]`);
+        validateAngle(angles[1], `${id}.angles[1]`);
+
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.type] = PROCEDURAL_PATTERN_TYPES.crossHatch;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.size] = strokeWidth;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.gap0] = gap;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.gap1] = gap;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.angle0] = angles[0] * DEGREES_TO_RADIANS;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.angle1] = angles[1] * DEGREES_TO_RADIANS;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.elementCount] = 2;
+        break;
+      }
+
+      case 'dots': {
+        const radius = config.radius === undefined ? DEFAULT_SIZE : config.radius;
+        const gap = config.gap === undefined ? DEFAULT_GAP : config.gap;
+        const angle = config.angle === undefined ? DEFAULT_DOT_ANGLE : config.angle;
+        const skew = config.skew === undefined ? DEFAULT_DOT_SKEW : config.skew;
+        validatePositive(radius, `${id}.radius`);
+        validateNonNegative(gap, `${id}.gap`);
+        validateAngle(angle, `${id}.angle`);
+        validateSkew(skew, `${id}.skew`);
+
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.type] = PROCEDURAL_PATTERN_TYPES.dots;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.size] = radius;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.gap0] = gap;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.gap1] = gap;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.angle0] = angle * DEGREES_TO_RADIANS;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.angle1] = skew * DEGREES_TO_RADIANS;
+        data[offset + PROCEDURAL_PATTERN_OFFSETS.elementCount] = 2;
+        break;
+      }
+
+      default:
+        throw new Error(`${id}.type is not a supported procedural pattern type`);
+    }
+  });
+
+  return {
+    data,
+    width: data.length / PROCEDURAL_PATTERN_COMPONENTS_PER_TEXEL,
+    height: 1,
+    patternIndices
+  };
+}
+
+function validatePositive(value: number, name: string): void {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be a finite number greater than 0`);
+  }
+}
+
+function validateNonNegative(value: number, name: string): void {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`${name} must be a finite number greater than or equal to 0`);
+  }
+}
+
+function validateAngle(value: number, name: string): void {
+  if (!Number.isFinite(value)) {
+    throw new Error(`${name} must be a finite number`);
+  }
+}
+
+function validateSkew(value: number, name: string): void {
+  if (!Number.isFinite(value) || value <= -90 || value >= 90) {
+    throw new Error(`${name} must be a finite number greater than -90 and less than 90`);
+  }
+}