@deck.gl/aggregation-layers 9.0.40 → 9.1.0-beta.3

package/src/common/aggregator/gpu-aggregator/aggregation-transform-uniforms.ts

@@ -0,0 +1,33 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {NumberArray3, NumberArray4} from '@math.gl/core';
+import {ShaderModule} from '@luma.gl/shadertools';
+import {Texture} from '@luma.gl/core';
+
+const uniformBlock = /* glsl */ `\
+uniform aggregatorTransformUniforms {
+  ivec4 binIdRange;
+  bvec3 isCount;
+  bvec3 isMean;
+  float naN;
+} aggregatorTransform;
+`;
+
+export type AggregatorTransformProps = {
+  binIdRange: NumberArray4;
+  isCount: NumberArray3;
+  isMean: NumberArray3;
+  bins: Texture;
+};
+
+export const aggregatorTransformUniforms = {
+  name: 'aggregatorTransform',
+  vs: uniformBlock,
+  uniformTypes: {
+    binIdRange: 'vec4<i32>',
+    isCount: 'vec3<f32>',
+    isMean: 'vec3<f32>'
+  }
+} as const satisfies ShaderModule<AggregatorTransformProps>;

package/src/common/aggregator/gpu-aggregator/bin-sorter-uniforms.ts

@@ -0,0 +1,27 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {NumberArray2, NumberArray4} from '@math.gl/core';
+import {ShaderModule} from '@luma.gl/shadertools';
+
+const uniformBlock = /* glsl */ `\
+uniform binSorterUniforms {
+  ivec4 binIdRange;
+  ivec2 targetSize;
+} binSorter;
+`;
+
+export type BinSorterProps = {
+  binIdRange: NumberArray4;
+  targetSize: NumberArray2;
+};
+
+export const binSorterUniforms = {
+  name: 'binSorter',
+  vs: uniformBlock,
+  uniformTypes: {
+    binIdRange: 'vec4<i32>',
+    targetSize: 'vec2<i32>'
+  }
+} as const satisfies ShaderModule<BinSorterProps>;

package/src/common/aggregator/gpu-aggregator/utils.ts

@@ -0,0 +1,27 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Device, Framebuffer} from '@luma.gl/core';
+
+/**
+ * Create a float texture to store aggregation result
+ */
+export function createRenderTarget(device: Device, width: number, height: number): Framebuffer {
+  return device.createFramebuffer({
+    width,
+    height,
+    colorAttachments: [
+      device.createTexture({
+        width,
+        height,
+        format: 'rgba32float',
+        mipmaps: false,
+        sampler: {
+          minFilter: 'nearest',
+          magFilter: 'nearest'
+        }
+      })
+    ]
+  });
+}

package/src/common/aggregator/gpu-aggregator/webgl-aggregation-transform.ts

@@ -0,0 +1,247 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {BufferTransform} from '@luma.gl/engine';
+import {createRenderTarget} from './utils';
+
+import type {Device, Framebuffer, Buffer, Texture} from '@luma.gl/core';
+import type {WebGLAggregatorProps} from './webgl-aggregator';
+import type {AggregationOperation} from '../aggregator';
+
+import {TEXTURE_WIDTH} from './webgl-bin-sorter';
+import {
+  AggregatorTransformProps,
+  aggregatorTransformUniforms
+} from './aggregation-transform-uniforms';
+import {NumberArray3} from '@math.gl/core';
+
+const MAX_FLOAT32 = 3e38;
+
+export class WebGLAggregationTransform {
+  device: Device;
+  channelCount: number;
+
+  /** Packed from bin ids */
+  binBuffer: Buffer | null = null;
+  /** Packed values from each channel of each bin
+   * Stride is number of channels * 4 bytes (float32)
+   */
+  valueBuffer: Buffer | null = null;
+
+  private transform: BufferTransform;
+  /** Render target for calculating domain */
+  private domainFBO: Framebuffer;
+  /** Aggregated [min, max] for each channel */
+  private _domains: [min: number, max: number][] | null = null;
+
+  constructor(device: Device, props: WebGLAggregatorProps) {
+    this.device = device;
+    this.channelCount = props.channelCount;
+    this.transform = createTransform(device, props);
+    this.domainFBO = createRenderTarget(device, 2, 1);
+  }
+
+  destroy() {
+    this.transform.destroy();
+    this.binBuffer?.destroy();
+    this.valueBuffer?.destroy();
+    this.domainFBO.colorAttachments[0].texture.destroy();
+    this.domainFBO.destroy();
+  }
+
+  get domains(): [min: number, max: number][] {
+    if (!this._domains) {
+      // Domain model has run, but result has not been read to CPU
+      const buffer = this.device.readPixelsToArrayWebGL(this.domainFBO).buffer;
+      const domain = new Float32Array(buffer);
+      this._domains = [
+        [-domain[4], domain[0]],
+        [-domain[5], domain[1]],
+        [-domain[6], domain[2]]
+      ].slice(0, this.channelCount) as [number, number][];
+    }
+    return this._domains;
+  }
+
+  setDimensions(binCount: number, binIdRange: [number, number][]) {
+    const {model, transformFeedback} = this.transform;
+    model.setVertexCount(binCount);
+    const aggregatorTransformProps: Partial<AggregatorTransformProps> = {
+      binIdRange: [
+        binIdRange[0][0],
+        binIdRange[0][1],
+        binIdRange[1]?.[0] || 0,
+        binIdRange[1]?.[1] || 0
+      ]
+    };
+    model.shaderInputs.setProps({aggregatorTransform: aggregatorTransformProps});
+
+    // Only destroy existing buffer if it is not large enough
+    const binBufferByteLength = binCount * binIdRange.length * 4;
+    if (!this.binBuffer || this.binBuffer.byteLength < binBufferByteLength) {
+      this.binBuffer?.destroy();
+      this.binBuffer = this.device.createBuffer({byteLength: binBufferByteLength});
+      transformFeedback.setBuffer('binIds', this.binBuffer);
+    }
+
+    const valueBufferByteLength = binCount * this.channelCount * 4;
+    if (!this.valueBuffer || this.valueBuffer.byteLength < valueBufferByteLength) {
+      this.valueBuffer?.destroy();
+      this.valueBuffer = this.device.createBuffer({byteLength: valueBufferByteLength});
+      transformFeedback.setBuffer('values', this.valueBuffer);
+    }
+  }
+
+  update(bins: Texture | null, operations: AggregationOperation[]) {
+    if (!bins) {
+      return;
+    }
+    const transform = this.transform;
+    const target = this.domainFBO;
+
+    const isCount = [0, 1, 2].map(i => (operations[i] === 'COUNT' ? 1 : 0));
+    const isMean = [0, 1, 2].map(i => (operations[i] === 'MEAN' ? 1 : 0));
+    const aggregatorTransformProps: Partial<AggregatorTransformProps> = {
+      isCount: isCount as NumberArray3,
+      isMean: isMean as NumberArray3,
+      bins
+    };
+    transform.model.shaderInputs.setProps({aggregatorTransform: aggregatorTransformProps});
+
+    transform.run({
+      id: 'gpu-aggregation-domain',
+      framebuffer: target,
+      parameters: {
+        viewport: [0, 0, 2, 1]
+      },
+      clearColor: [-MAX_FLOAT32, -MAX_FLOAT32, -MAX_FLOAT32, 0],
+      clearDepth: false,
+      clearStencil: false
+    });
+
+    // Clear the last read results. This will be lazy-populated if used.
+    this._domains = null;
+  }
+}
+
+function createTransform(device: Device, props: WebGLAggregatorProps): BufferTransform {
+  const vs = /* glsl */ `\
+#version 300 es
+#define SHADER_NAME gpu-aggregation-domain-vertex
+
+uniform sampler2D bins;
+
+#if NUM_DIMS == 1
+out float binIds;
+#else
+out vec2 binIds;
+#endif
+
+#if NUM_CHANNELS == 1
+flat out float values;
+#elif NUM_CHANNELS == 2
+flat out vec2 values;
+#else
+flat out vec3 values;
+#endif
+
+const float NAN = intBitsToFloat(-1);
+
+void main() {
+  int row = gl_VertexID / SAMPLER_WIDTH;
+  int col = gl_VertexID - row * SAMPLER_WIDTH;
+  vec4 weights = texelFetch(bins, ivec2(col, row), 0);
+  vec3 value3 = mix(
+    mix(weights.rgb, vec3(weights.a), aggregatorTransform.isCount),
+    weights.rgb / max(weights.a, 1.0),
+    aggregatorTransform.isMean
+  );
+  if (weights.a == 0.0) {
+    value3 = vec3(NAN);
+  }
+
+#if NUM_DIMS == 1
+  binIds = float(gl_VertexID + aggregatorTransform.binIdRange.x);
+#else
+  int y = gl_VertexID / (aggregatorTransform.binIdRange.y - aggregatorTransform.binIdRange.x);
+  int x = gl_VertexID - y * (aggregatorTransform.binIdRange.y - aggregatorTransform.binIdRange.x);
+  binIds.y = float(y + aggregatorTransform.binIdRange.z);
+  binIds.x = float(x + aggregatorTransform.binIdRange.x);
+#endif
+
+#if NUM_CHANNELS == 3
+  values = value3;
+#elif NUM_CHANNELS == 2
+  values = value3.xy;
+#else
+  values = value3.x;
+#endif
+
+  gl_Position = vec4(0., 0., 0., 1.);
+  // This model renders into a 2x1 texture to obtain min and max simultaneously.
+  // See comments in fragment shader
+  gl_PointSize = 2.0;
+}
+`;
+
+  const fs = /* glsl */ `\
+#version 300 es
+#define SHADER_NAME gpu-aggregation-domain-fragment
+
+precision highp float;
+
+#if NUM_CHANNELS == 1
+flat in float values;
+#elif NUM_CHANNELS == 2
+flat in vec2 values;
+#else
+flat in vec3 values;
+#endif
+
+out vec4 fragColor;
+
+void main() {
+  vec3 value3;
+#if NUM_CHANNELS == 3
+  value3 = values;
+#elif NUM_CHANNELS == 2
+  value3.xy = values;
+#else
+  value3.x = values;
+#endif
+  if (isnan(value3.x)) discard;
+  // This shader renders into a 2x1 texture with blending=max
+  // The left pixel yields the max value of each channel
+  // The right pixel yields the min value of each channel
+  if (gl_FragCoord.x < 1.0) {
+    fragColor = vec4(value3, 1.0);
+  } else {
+    fragColor = vec4(-value3, 1.0);
+  }
+}
+`;
+
+  return new BufferTransform(device, {
+    vs,
+    fs,
+    topology: 'point-list',
+    modules: [aggregatorTransformUniforms],
+    parameters: {
+      blend: true,
+      blendColorSrcFactor: 'one',
+      blendColorDstFactor: 'one',
+      blendColorOperation: 'max',
+      blendAlphaSrcFactor: 'one',
+      blendAlphaDstFactor: 'one',
+      blendAlphaOperation: 'max'
+    },
+    defines: {
+      NUM_DIMS: props.dimensions,
+      NUM_CHANNELS: props.channelCount,
+      SAMPLER_WIDTH: TEXTURE_WIDTH
+    },
+    varyings: ['binIds', 'values'],
+    disableWarnings: true
+  });
+}

package/src/common/aggregator/gpu-aggregator/webgl-aggregator.ts

@@ -0,0 +1,274 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {ModelProps} from '@luma.gl/engine';
+import {WebGLBinSorter} from './webgl-bin-sorter';
+import {WebGLAggregationTransform} from './webgl-aggregation-transform';
+import {_deepEqual as deepEqual, log, BinaryAttribute} from '@deck.gl/core';
+
+import type {Aggregator, AggregationProps, AggregatedBin} from '../aggregator';
+import type {Device, Buffer, BufferLayout, TypedArray} from '@luma.gl/core';
+import type {ShaderModule} from '@luma.gl/shadertools';
+
+/** Options used to construct a new WebGLAggregator */
+export type WebGLAggregatorProps = {
+  /** Size of bin IDs */
+  dimensions: 1 | 2;
+  /** How many properties to perform aggregation on */
+  channelCount: 1 | 2 | 3;
+  /** Buffer layout for input attributes */
+  bufferLayout?: BufferLayout[];
+  /** Define a shader function with one of the signatures
+   *  `void getBin(out int binId)`: if dimensions=1
+   *  `void getBin(out ivec2 binId)`: if dimensions=2
+   * And a shader function with one of the signatures
+   *  `void getValue(out float value)`: if channelCount=1
+   *  `void getValue(out vec2 value)`: if channelCount=2
+   *  `void getValue(out vec3 value)`: if channelCount=3
+   */
+  vs: string;
+  /** Shader modules
+   * Required to support certain layer extensions (e.g. data filter)
+   */
+  modules?: ShaderModule[];
+  /** Shadertool module defines */
+  defines?: Record<string, string | number | boolean>;
+} & Partial<WebGLAggregationProps>;
+
+/** Props used to run GPU aggregation, can be changed at any time */
+type WebGLAggregationProps = AggregationProps & {
+  /** Limits of binId defined for each dimension. Ids outside of the [start, end) are ignored.
+   */
+  binIdRange: [start: number, end: number][];
+  /** Context props passed to the shader modules */
+  shaderModuleProps?: Record<string, any>;
+};
+
+/** An Aggregator implementation that calculates aggregation on the GPU */
+export class WebGLAggregator implements Aggregator {
+  /** Checks if the current device supports GPU aggregation */
+  static isSupported(device: Device): boolean {
+    return (
+      device.features.has('float32-renderable-webgl') &&
+      device.features.has('texture-blend-float-webgl')
+    );
+  }
+
+  readonly dimensions: 1 | 2;
+  readonly channelCount: 1 | 2 | 3;
+  binCount: number = 0;
+
+  readonly device: Device;
+  props: WebGLAggregatorProps & WebGLAggregationProps;
+
+  /** Dirty flag per channel */
+  protected needsUpdate: boolean[];
+  /** Step 1. sort data points into bins, blended using an aggregation opera†ion */
+  protected binSorter: WebGLBinSorter;
+  /** Step 2. (optional) calculate the min/max across all bins */
+  protected aggregationTransform: WebGLAggregationTransform;
+
+  /** Cached outputs */
+  protected binIds: BinaryAttribute | null = null;
+  protected results: BinaryAttribute[] = [];
+
+  constructor(device: Device, props: WebGLAggregatorProps) {
+    this.device = device;
+    this.dimensions = props.dimensions;
+    this.channelCount = props.channelCount;
+    this.props = {
+      ...props,
+      pointCount: 0,
+      binIdRange: [[0, 0]],
+      operations: [],
+      attributes: {},
+      binOptions: {}
+    };
+    this.needsUpdate = new Array(this.channelCount).fill(true);
+    this.binSorter = new WebGLBinSorter(device, props);
+    this.aggregationTransform = new WebGLAggregationTransform(device, props);
+    this.setProps(props);
+  }
+
+  getBins(): BinaryAttribute | null {
+    const buffer = this.aggregationTransform.binBuffer;
+    if (!buffer) {
+      return null;
+    }
+    if (this.binIds?.buffer !== buffer) {
+      // deck.gl Attribute.setBinaryValue uses shallow comparison to determine if attribute value has changed
+      // For performance, only create a new binary attribute descriptor when Buffer changes
+      this.binIds = {buffer, type: 'float32', size: this.dimensions};
+    }
+    return this.binIds;
+  }
+
+  /** Returns an accessor to the output for a given channel. */
+  getResult(channel: 0 | 1 | 2): BinaryAttribute | null {
+    const buffer = this.aggregationTransform.valueBuffer;
+    if (!buffer || channel >= this.channelCount) {
+      return null;
+    }
+    if (this.results[channel]?.buffer !== buffer) {
+      this.results[channel] = {
+        buffer,
+        type: 'float32',
+        size: 1,
+        stride: this.channelCount * 4,
+        offset: channel * 4
+      };
+    }
+    return this.results[channel];
+  }
+
+  /** Returns the [min, max] of aggregated values for a given channel. */
+  getResultDomain(channel: 0 | 1 | 2): [min: number, max: number] {
+    return this.aggregationTransform.domains[channel];
+  }
+
+  /** Returns the information for a given bin. */
+  getBin(index: number): AggregatedBin | null {
+    if (index < 0 || index >= this.binCount) {
+      return null;
+    }
+    const {binIdRange} = this.props;
+    let id: number[];
+
+    if (this.dimensions === 1) {
+      id = [index + binIdRange[0][0]];
+    } else {
+      const [[x0, x1], [y0]] = binIdRange;
+      const width = x1 - x0;
+      id = [(index % width) + x0, Math.floor(index / width) + y0];
+    }
+
+    const pixel = this.binSorter.getBinValues(index);
+    if (!pixel) {
+      return null;
+    }
+    const count = pixel[3];
+    const value: number[] = [];
+    for (let channel = 0; channel < this.channelCount; channel++) {
+      const operation = this.props.operations[channel];
+      if (operation === 'COUNT') {
+        value[channel] = count;
+      } else if (count === 0) {
+        value[channel] = NaN;
+      } else {
+        value[channel] = operation === 'MEAN' ? pixel[channel] / count : pixel[channel];
+      }
+    }
+    return {id, value, count};
+  }
+
+  /** Release GPU resources */
+  destroy() {
+    this.binSorter.destroy();
+    this.aggregationTransform.destroy();
+  }
+
+  /** Update aggregation props. Normalize prop values and set change flags. */
+  setProps(props: Partial<WebGLAggregationProps>) {
+    const oldProps = this.props;
+
+    // Update local settings. These will set the flag this._needsUpdate
+    if ('binIdRange' in props && !deepEqual(props.binIdRange, oldProps.binIdRange, 2)) {
+      const binIdRange = props.binIdRange!;
+      log.assert(binIdRange.length === this.dimensions);
+
+      if (this.dimensions === 1) {
+        const [[x0, x1]] = binIdRange;
+        this.binCount = x1 - x0;
+      } else {
+        const [[x0, x1], [y0, y1]] = binIdRange;
+        this.binCount = (x1 - x0) * (y1 - y0);
+      }
+
+      this.binSorter.setDimensions(this.binCount, binIdRange);
+      this.aggregationTransform.setDimensions(this.binCount, binIdRange);
+      this.setNeedsUpdate();
+    }
+    if (props.operations) {
+      for (let channel = 0; channel < this.channelCount; channel++) {
+        if (props.operations[channel] !== oldProps.operations[channel]) {
+          this.setNeedsUpdate(channel);
+        }
+      }
+    }
+    if (props.pointCount !== undefined && props.pointCount !== oldProps.pointCount) {
+      this.binSorter.setModelProps({vertexCount: props.pointCount});
+      this.setNeedsUpdate();
+    }
+    if (props.binOptions) {
+      if (!deepEqual(props.binOptions, oldProps.binOptions, 2)) {
+        this.setNeedsUpdate();
+      }
+      this.binSorter.model.shaderInputs.setProps({binOptions: props.binOptions});
+    }
+    if (props.attributes) {
+      const attributeBuffers: Record<string, Buffer> = {};
+      const constantAttributes: Record<string, TypedArray> = {};
+
+      for (const attribute of Object.values(props.attributes)) {
+        for (const [attributeName, value] of Object.entries(attribute.getValue())) {
+          if (ArrayBuffer.isView(value)) {
+            constantAttributes[attributeName] = value;
+          } else if (value) {
+            attributeBuffers[attributeName] = value;
+          }
+        }
+      }
+      this.binSorter.setModelProps({attributes: attributeBuffers, constantAttributes});
+    }
+    if (props.shaderModuleProps) {
+      this.binSorter.setModelProps({shaderModuleProps: props.shaderModuleProps});
+    }
+
+    Object.assign(this.props, props);
+  }
+
+  /** Flags a channel to need update.
+   * This is called internally by setProps() if certain props change
+   * Users of this class still need to manually set the dirty flag sometimes, because even if no props changed
+   * the underlying buffers could have been updated and require rerunning the aggregation
+   * @param {number} channel - mark the given channel as dirty. If not provided, all channels will be updated.
+   */
+  setNeedsUpdate(channel?: number) {
+    if (channel === undefined) {
+      this.needsUpdate.fill(true);
+    } else {
+      this.needsUpdate[channel] = true;
+    }
+  }
+
+  update() {}
+
+  /** Run aggregation */
+  preDraw() {
+    if (!this.needsUpdate.some(Boolean)) {
+      return;
+    }
+
+    const {operations} = this.props;
+    const operationsToUpdate = this.needsUpdate.map((needsUpdate, i) =>
+      needsUpdate ? operations[i] : null
+    );
+    // Render data to bins
+    this.binSorter.update(operationsToUpdate);
+    // Read to buffer and calculate domain
+    this.aggregationTransform.update(this.binSorter.texture, operations);
+
+    for (let i = 0; i < this.channelCount; i++) {
+      if (this.needsUpdate[i]) {
+        this.needsUpdate[i] = false;
+        this.props.onUpdate?.({channel: i});
+      }
+    }
+
+    // Uncomment to debug
+    // console.log('binsFBO', new Float32Array(this.device.readPixelsToArrayWebGL(this.binSorter.texture!).buffer));
+    // console.log('binsBuffer', new Float32Array(this.aggregationTransform.binBuffer?.readSyncWebGL().buffer!));
+    // console.log('resultBuffer', new Float32Array(this.aggregationTransform.valueBuffer?.readSyncWebGL().buffer!));
+  }
+}