@deck.gl/extensions 9.0.0-beta.3 → 9.0.0-beta.5

package/package.json

@@ -3,7 +3,7 @@
   "description": "Plug-and-play functionalities for deck.gl layers",
   "license": "MIT",
   "type": "module",
-  "version": "9.0.0-beta.3",
+  "version": "9.0.0-beta.5",
   "publishConfig": {
     "access": "public"
   },
@@ -51,5 +51,5 @@
     "@math.gl/core": "^4.0.0",
     "@math.gl/web-mercator": "^4.0.0"
   },
-  "gitHead": "643d1009268bbf92b5bc0941d00aa59d5e3a582b"
+  "gitHead": "02588aba7cbf25d48cec20b30a686bba9be32bff"
 }

package/src/data-filter/data-filter-extension.ts

@@ -22,27 +22,36 @@ import {GL} from '@luma.gl/constants';
 import type {Framebuffer} from '@luma.gl/core';
 import type {Model} from '@luma.gl/engine';
 import type {Layer, LayerContext, Accessor, UpdateParameters} from '@deck.gl/core';
-import {LayerExtension} from '@deck.gl/core';
+import {_deepEqual as deepEqual, LayerExtension, log} from '@deck.gl/core';
 import {shaderModule, shaderModule64} from './shader-module';
 import * as aggregator from './aggregator';
 
 const defaultProps = {
   getFilterValue: {type: 'accessor', value: 0},
+  getFilterCategory: {type: 'accessor', value: 0},
   onFilteredItemsChange: {type: 'function', value: null, optional: true},
 
   filterEnabled: true,
   filterRange: [-1, 1],
   filterSoftRange: null,
+  filterCategories: [0],
   filterTransformSize: true,
   filterTransformColor: true
 };
 
+type FilterCategory = number | string;
+
 export type DataFilterExtensionProps<DataT = any> = {
   /**
    * Accessor to retrieve the value for each object that it will be filtered by.
    * Returns either a number (if `filterSize: 1`) or an array of numbers.
    */
   getFilterValue?: Accessor<DataT, number | number[]>;
+  /**
+   * Accessor to retrieve the category (`number | string`) for each object that it will be filtered by.
+   * Returns either a single category (if `filterSize: 1`) or an array of categories.
+   */
+  getFilterCategory?: Accessor<DataT, FilterCategory | FilterCategory[]>;
   /**
    * Enable/disable the data filter. If the data filter is disabled, all objects are rendered.
    * @default true
@@ -70,6 +79,11 @@ export type DataFilterExtensionProps<DataT = any> = {
    * @default true
    */
   filterTransformColor?: boolean;
+  /**
+   * The categories which define whether an object should be rendered.
+   * @default []
+   */
+  filterCategories: FilterCategory[] | FilterCategory[][];
   /**
    * Only called if the `countItems` option is enabled.
    */
@@ -82,21 +96,33 @@ export type DataFilterExtensionProps<DataT = any> = {
 };
 
 type DataFilterExtensionOptions = {
+  /**
+   * The size of the category filter (number of columns to filter by). The category filter can show/hide data based on 1-4 properties of each object.
+   * @default 1
+   */
+  categorySize?: 1 | 2 | 3 | 4;
   /**
    * The size of the filter (number of columns to filter by). The data filter can show/hide data based on 1-4 numeric properties of each object.
    * @default 1
    */
-  filterSize: number;
+  filterSize?: 1 | 2 | 3 | 4;
   /**
    * Use 64-bit precision instead of 32-bit.
    * @default false
    */
-  fp64: boolean;
+  fp64?: boolean;
   /**
    * If `true`, reports the number of filtered objects with the `onFilteredItemsChange` callback.
    * @default `false`.
    */
-  countItems: boolean;
+  countItems?: boolean;
+};
+
+const defaultOptions: Required<DataFilterExtensionOptions> = {
+  categorySize: 1,
+  filterSize: 1,
+  fp64: false,
+  countItems: false
 };
 
 const DATA_TYPE_FROM_SIZE = {
@@ -107,28 +133,24 @@ const DATA_TYPE_FROM_SIZE = {
 };
 
 /** Adds GPU-based data filtering functionalities to layers. It allows the layer to show/hide objects based on user-defined properties. */
-export default class DataFilterExtension extends LayerExtension<DataFilterExtensionOptions> {
+export default class DataFilterExtension extends LayerExtension<
+  Required<DataFilterExtensionOptions>
+> {
   static defaultProps = defaultProps;
   static extensionName = 'DataFilterExtension';
 
-  constructor({
-    filterSize = 1,
-    fp64 = false,
-    countItems = false
-  }: Partial<DataFilterExtensionOptions> = {}) {
-    if (!DATA_TYPE_FROM_SIZE[filterSize]) {
-      throw new Error('filterSize out of range');
-    }
-
-    super({filterSize, fp64, countItems});
+  constructor(opts: DataFilterExtensionOptions) {
+    super({...defaultOptions, ...opts});
   }
 
   getShaders(this: Layer<DataFilterExtensionProps>, extension: this): any {
-    const {filterSize, fp64} = extension.opts;
+    const {categorySize, filterSize, fp64} = extension.opts;
 
     return {
       modules: [fp64 ? shaderModule64 : shaderModule],
       defines: {
+        DATACATEGORY_TYPE: DATA_TYPE_FROM_SIZE[categorySize],
+        DATACATEGORY_CHANNELS: categorySize,
         DATAFILTER_TYPE: DATA_TYPE_FROM_SIZE[filterSize],
         DATAFILTER_DOUBLE: Boolean(fp64)
       }
@@ -137,11 +159,13 @@ export default class DataFilterExtension extends LayerExtension<DataFilterExtens
 
   initializeState(this: Layer<DataFilterExtensionProps>, context: LayerContext, extension: this) {
     const attributeManager = this.getAttributeManager();
+    const {categorySize, filterSize, fp64} = extension.opts;
+
     if (attributeManager) {
       attributeManager.add({
         filterValues: {
-          size: extension.opts.filterSize,
-          type: extension.opts.fp64 ? GL.DOUBLE : GL.FLOAT,
+          size: filterSize,
+          type: fp64 ? GL.DOUBLE : GL.FLOAT,
           accessor: 'getFilterValue',
           shaderAttributes: {
             filterValues: {
@@ -151,6 +175,23 @@ export default class DataFilterExtension extends LayerExtension<DataFilterExtens
               divisor: 1
             }
           }
+        },
+        filterCategoryValues: {
+          size: categorySize,
+          type: GL.FLOAT,
+          accessor: 'getFilterCategory',
+          transform:
+            categorySize === 1
+              ? d => extension._getCategoryKey.call(this, d, 0)
+              : d => d.map((x, i) => extension._getCategoryKey.call(this, x, i)),
+          shaderAttributes: {
+            filterCategoryValues: {
+              divisor: 0
+            },
+            instanceFilterCategoryValues: {
+              divisor: 1
+            }
+          }
         }
       });
     }
@@ -194,31 +235,60 @@ export default class DataFilterExtension extends LayerExtension<DataFilterExtens
 
   updateState(
     this: Layer<DataFilterExtensionProps>,
-    {props, oldProps}: UpdateParameters<Layer<DataFilterExtensionProps>>
+    {props, oldProps, changeFlags}: UpdateParameters<Layer<DataFilterExtensionProps>>,
+    extension: this
   ) {
+    const attributeManager = this.getAttributeManager();
+    const {categorySize} = extension.opts;
     if (this.state.filterModel) {
-      const attributeManager = this.getAttributeManager();
       const filterNeedsUpdate =
         // attributeManager must be defined for filterModel to be set
         attributeManager!.attributes.filterValues.needsUpdate() ||
+        attributeManager!.attributes.filterCategoryValues?.needsUpdate() ||
         props.filterEnabled !== oldProps.filterEnabled ||
         props.filterRange !== oldProps.filterRange ||
-        props.filterSoftRange !== oldProps.filterSoftRange;
+        props.filterSoftRange !== oldProps.filterSoftRange ||
+        props.filterCategories !== oldProps.filterCategories;
       if (filterNeedsUpdate) {
         this.setState({filterNeedsUpdate});
       }
     }
+    if (attributeManager?.attributes.filterCategoryValues) {
+      // Update bitmask if accessor or selected categories has changed
+      const categoryBitMaskNeedsUpdate =
+        attributeManager.attributes.filterCategoryValues.needsUpdate() ||
+        !deepEqual(props.filterCategories, oldProps.filterCategories, 2);
+      if (categoryBitMaskNeedsUpdate) {
+        this.setState({categoryBitMaskNeedsUpdate});
+      }
+
+      // Need to recreate category map if categorySize has changed
+      const resetCategories = changeFlags.dataChanged;
+      if (resetCategories) {
+        this.setState({
+          categoryMap: Array(categorySize)
+            .fill(0)
+            .map(() => ({}))
+        });
+        attributeManager.attributes.filterCategoryValues.setNeedsUpdate('categoryMap');
+      }
+    }
   }
 
   draw(this: Layer<DataFilterExtensionProps>, params: any, extension: this) {
     const filterFBO = this.state.filterFBO as Framebuffer;
     const filterModel = this.state.filterModel as Model;
     const filterNeedsUpdate = this.state.filterNeedsUpdate as boolean;
+    const categoryBitMaskNeedsUpdate = this.state.categoryBitMaskNeedsUpdate as boolean;
 
     const {onFilteredItemsChange} = this.props;
+
+    if (categoryBitMaskNeedsUpdate) {
+      extension._updateCategoryBitMask.call(this, params, extension);
+    }
     if (filterNeedsUpdate && onFilteredItemsChange && filterModel) {
       const {
-        attributes: {filterValues, filterIndices}
+        attributes: {filterValues, filterCategoryValues, filterIndices}
       } = this.getAttributeManager()!;
       filterModel.setVertexCount(this.getNumInstances());
 
@@ -228,8 +298,10 @@ export default class DataFilterExtension extends LayerExtension<DataFilterExtens
       // @ts-expect-error filterValue and filterIndices should always have buffer value
       filterModel.setAttributes({
         ...filterValues.getValue(),
+        ...filterCategoryValues?.getValue(),
         ...filterIndices?.getValue()
       });
+      filterModel.setUniforms(params.uniforms);
       filterModel.device.withParametersWebGL(
         {
           framebuffer: filterFBO,
@@ -260,4 +332,54 @@ export default class DataFilterExtension extends LayerExtension<DataFilterExtens
     filterFBO?.destroy();
     filterModel?.destroy();
   }
+
+  /**
+   * Updates the bitmask used on the GPU to perform the filter based on the
+   * `filterCategories` prop. The mapping between categories and bit in the bitmask
+   * is performed by `_getCategoryKey()`
+   */
+  _updateCategoryBitMask(
+    this: Layer<DataFilterExtensionProps>,
+    params: any,
+    extension: this
+  ): void {
+    const {categorySize} = extension.opts;
+    const {filterCategories} = this.props;
+    const categoryBitMask = new Uint32Array([0, 0, 0, 0]);
+    const categoryFilters = (
+      categorySize === 1 ? [filterCategories] : filterCategories
+    ) as FilterCategory[][];
+    const maxCategories = categorySize === 1 ? 128 : categorySize === 2 ? 64 : 32;
+    for (let c = 0; c < categoryFilters.length; c++) {
+      const categoryFilter = categoryFilters[c];
+      for (const category of categoryFilter) {
+        const key = extension._getCategoryKey.call(this, category, c);
+        if (key < maxCategories) {
+          const channel = c * (maxCategories / 32) + Math.floor(key / 32);
+          categoryBitMask[channel] += Math.pow(2, key % 32); // 1 << key fails for key > 30
+        } else {
+          log.warn(`Exceeded maximum number of categories (${maxCategories})`)();
+        }
+      }
+    }
+    /* eslint-disable-next-line camelcase */
+    params.uniforms.filter_categoryBitMask = categoryBitMask;
+    this.state.categoryBitMaskNeedsUpdate = false;
+  }
+
+  /**
+   * Returns an index of bit in the bitmask for a given category. If the category has
+   * not yet been assigned a bit, a new one is assigned.
+   */
+  _getCategoryKey(
+    this: Layer<DataFilterExtensionProps>,
+    category: FilterCategory,
+    channel: number
+  ) {
+    const categoryMap = (this.state.categoryMap as Record<FilterCategory, number>[])[channel];
+    if (!(category in categoryMap)) {
+      categoryMap[category] = Object.keys(categoryMap).length;
+    }
+    return categoryMap[category];
+  }
 }

package/src/data-filter/shader-module.ts

@@ -12,13 +12,16 @@ uniform DATAFILTER_TYPE filter_max;
 uniform bool filter_useSoftMargin;
 uniform bool filter_enabled;
 uniform bool filter_transformSize;
+uniform ivec4 filter_categoryBitMask;
 
 #ifdef NON_INSTANCED_MODEL
   #define DATAFILTER_ATTRIB filterValues
   #define DATAFILTER_ATTRIB_64LOW filterValues64Low
+  #define DATACATEGORY_ATTRIB filterCategoryValues
 #else
   #define DATAFILTER_ATTRIB instanceFilterValues
   #define DATAFILTER_ATTRIB_64LOW instanceFilterValues64Low
+  #define DATACATEGORY_ATTRIB instanceFilterCategoryValues
 #endif
 
 in DATAFILTER_TYPE DATAFILTER_ATTRIB;
@@ -28,6 +31,7 @@ in DATAFILTER_TYPE DATAFILTER_ATTRIB;
   uniform DATAFILTER_TYPE filter_min64High;
   uniform DATAFILTER_TYPE filter_max64High;
 #endif
+in DATACATEGORY_TYPE DATACATEGORY_ATTRIB;
 
 out float dataFilter_value;
 
@@ -43,7 +47,7 @@ float dataFilter_reduceValue(vec3 value) {
 float dataFilter_reduceValue(vec4 value) {
   return min(min(value.x, value.y), min(value.z, value.w));
 }
-void dataFilter_setValue(DATAFILTER_TYPE valueFromMin, DATAFILTER_TYPE valueFromMax) {
+void dataFilter_setValue(DATAFILTER_TYPE valueFromMin, DATAFILTER_TYPE valueFromMax, DATACATEGORY_TYPE category) {
   if (filter_enabled) {
     if (filter_useSoftMargin) {
       dataFilter_value = dataFilter_reduceValue(
@@ -55,6 +59,29 @@ void dataFilter_setValue(DATAFILTER_TYPE valueFromMin, DATAFILTER_TYPE valueFrom
         step(filter_min, valueFromMin) * step(valueFromMax, filter_max)
       );
     }
+
+    #if DATACATEGORY_CHANNELS == 1 // One 128-bit mask
+      int dataFilter_masks = filter_categoryBitMask[int(category / 32.0)];
+    #elif DATACATEGORY_CHANNELS == 2 // Two 64-bit masks
+      ivec2 dataFilter_masks = ivec2(
+        filter_categoryBitMask[int(category.x / 32.0)],
+        filter_categoryBitMask[int(category.y / 32.0) + 2]
+      );
+    #elif DATACATEGORY_CHANNELS == 3 // Three 32-bit masks
+      ivec3 dataFilter_masks = filter_categoryBitMask.xyz;
+    #else // Four 32-bit masks
+      ivec4 dataFilter_masks = filter_categoryBitMask;
+    #endif
+
+    // Shift mask and extract relevant bits
+    DATACATEGORY_TYPE dataFilter_bits = DATACATEGORY_TYPE(dataFilter_masks) / pow(DATACATEGORY_TYPE(2.0), mod(category, 32.0));
+    dataFilter_bits = mod(floor(dataFilter_bits), 2.0);
+
+    #if DATACATEGORY_CHANNELS == 1
+      if(dataFilter_bits == 0.0) dataFilter_value = 0.0;
+    #else
+    if(any(equal(dataFilter_bits, DATACATEGORY_TYPE(0.0)))) dataFilter_value = 0.0;
+    #endif
   } else {
     dataFilter_value = 1.0;
   }
@@ -138,10 +165,11 @@ const inject = {
     #ifdef DATAFILTER_DOUBLE
       dataFilter_setValue(
         DATAFILTER_ATTRIB - filter_min64High + DATAFILTER_ATTRIB_64LOW,
-        DATAFILTER_ATTRIB - filter_max64High + DATAFILTER_ATTRIB_64LOW
+        DATAFILTER_ATTRIB - filter_max64High + DATAFILTER_ATTRIB_64LOW,
+        DATACATEGORY_ATTRIB
       );
     #else
-      dataFilter_setValue(DATAFILTER_ATTRIB, DATAFILTER_ATTRIB);
+      dataFilter_setValue(DATAFILTER_ATTRIB, DATAFILTER_ATTRIB, DATACATEGORY_ATTRIB);
     #endif
   `,