docs(core) replace glOptions with deviceProps

docs/api-reference/core/deck.md

@@ -48,13 +48,19 @@ The following properties are used to initialize a `Deck` instance. Any custom va
 
 The canvas to render into. Can be either a HTMLCanvasElement or the element id. Will be auto-created if not supplied.
 
-#### `gl` (WebGLContext) {#gl}
+#### `device` ([Device](https://luma.gl/docs/api-reference/core/device))
+
+luma.gl Device used to manage the application's connection with the GPU. Will be auto-created if not supplied.
+
+#### `deviceProps` ([DeviceProps](https://luma.gl/docs/api-reference/core/device#deviceprops) | [WebGLDeviceProps](https://luma.gl/docs/api-reference/webgl/#webgldeviceprops)) {#deviceprops}
 
-WebGL context. Will be auto-created if not supplied.
+Options used for creating a new luma.gl GPU [Device](https://luma.gl/docs/api-reference/core/device). 
 
-#### `glOptions` (object) {#gloptions}
+Note that when using WebGL, `props.deviceProps.webgl` can be used to specify [WebGL context attributes](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext#contextattributes).
+
+#### `gl` (WebGLContext) {#gl}
 
-Additional options used when creating the WebGLContext. See [WebGL context attributes](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext).
+WebGL context to use. This prop is deprecated and replaced by `device`.
 
 #### `id` (string) {#id}
 
@@ -434,7 +440,7 @@ Called once the [Device](https://luma.gl/docs/api-reference/core/device) context
 
 Receives arguments:
 
-* `device` (Device) - a `WEBGLDevice` or `WebGPUDevice`.
+* `device` (Device) - a `WebGLDevice` or `WebGPUDevice`.
 
 #### `onViewStateChange` (Function) {#onviewstatechange}
 

docs/upgrade-guide.md

@@ -50,11 +50,13 @@ The biggest changes in deck.gl v9 are due to the upgrade to the luma.gl v9 API.
 
 Quick summary:
 
-- All references to `gl: WebGLRenderingContext` should be replaced with `device`: [Device](https://luma.gl/docs/api-reference/core/device).
-- Layer props `parameters` and `textureParameters` no longer use WebGL constants, but instead use (WebGPU style) [string constants](https://luma.gl/docs/api-reference/core/parameters/).
-- Deck class prop `onWebGLInitialized` is now `onDeviceInitialized`.
+- `DeckProps.gl (WebGLRenderingContext)` should be replaced with `device`: [Device](https://luma.gl/docs/api-reference/core/device).
+- `DeckProps.glOptions (WebGLContextAttributes)` should be replaced with `DeckProps.deviceProps.webgl`: `deviceProps: {type: 'webgl', webgl: ...glOptions}`: [WebGLDeviceProps](https://luma.gl/docs/api-reference/webgl/#webgldeviceprops)
+- `DeckProps.glOptions.preserveDrawingBuffers` is now set by default, and does not need to be overridden.
+- `DeckProps.onWebGLInitialized` callback is now `DeckProps.onDeviceInitialized`.
+- `LayerProps.parameters` and `LayerProps.textureParameters` no longer use WebGL constants, but instead use (WebGPU style) [string constants](https://luma.gl/docs/api-reference/core/parameters/).
 - When providing [binary data attributes](./api-reference/core/layer.md#data), `type` is now a WebGPU-style [string format](https://luma.gl/docs/api-guide/gpu/gpu-attributes#vertexformat) instead of a GL constant.
-- GPU resources should no longer be initiated from classes. For example, instead of `new Buffer()` use `device.createBuffer()`, instead of `new Texture()` use `device.createTexture()`. See [Device methods](https://luma.gl/docs/api-reference/core/device#methods).
+- GPU resources should no longer be created by directly instantiating classes. For example, instead of `new Buffer(gl)` use `device.createBuffer()`, instead of `new Texture()` use `device.createTexture()`. See [Device methods](https://luma.gl/docs/api-reference/core/device#methods).
 
 #### Custom Layers
 

modules/aggregation-layers/typed/aggregation-layer.d.ts

@@ -0,0 +1,48 @@
+import {
+  CompositeLayer,
+  AttributeManager,
+  UpdateParameters,
+  CompositeLayerProps
+} from '@deck.gl/core';
+export declare type AggregationLayerProps<DataT = any> = CompositeLayerProps<DataT>;
+export default abstract class AggregationLayer<
+  ExtraPropsT = {}
+> extends CompositeLayer<ExtraPropsT> {
+  static layerName: string;
+  state: CompositeLayer['state'] & {
+    ignoreProps?: Record<string, any>;
+    dimensions?: any;
+  };
+  initializeAggregationLayer(dimensions: any): void;
+  updateState(opts: UpdateParameters<this>): void;
+  updateAttributes(changedAttributes: any): void;
+  getAttributes(): {
+    [id: string]: import('modules/core/src/lib/attribute/shader-attribute').IShaderAttribute;
+  };
+  getModuleSettings(): any;
+  updateShaders(shaders: any): void;
+  /**
+   * Checks if aggregation is dirty
+   * @param {Object} updateOpts - object {props, oldProps, changeFlags}
+   * @param {Object} params - object {dimension, compareAll}
+   * @param {Object} params.dimension - {props, accessors} array of props and/or accessors
+   * @param {Boolean} params.compareAll - when `true` it will include non layer props for comparision
+   * @returns {Boolean} - returns true if dimensions' prop or accessor is changed
+   **/
+  isAggregationDirty(
+    updateOpts: any,
+    params?: {
+      compareAll?: boolean;
+      dimension?: any;
+    }
+  ): string | boolean;
+  /**
+   * Checks if an attribute is changed
+   * @param {String} name - name of the attribute
+   * @returns {Boolean} - `true` if attribute `name` is changed, `false` otherwise,
+   *                       If `name` is not passed or `undefiend`, `true` if any attribute is changed, `false` otherwise
+   **/
+  isAttributeChanged(name?: string): boolean;
+  _getAttributeManager(): AttributeManager;
+}
+// # sourceMappingURL=aggregation-layer.d.ts.map

modules/aggregation-layers/typed/contour-layer/contour-layer.d.ts

@@ -0,0 +1,86 @@
+import {
+  Accessor,
+  AccessorFunction,
+  Color,
+  Layer,
+  Position,
+  UpdateParameters,
+  DefaultProps
+} from '@deck.gl/core';
+import GridAggregationLayer, {GridAggregationLayerProps} from '../grid-aggregation-layer';
+/** All properties supported by ContourLayer. */
+export declare type ContourLayerProps<DataT = any> = _ContourLayerProps<DataT> &
+  GridAggregationLayerProps<DataT>;
+/** Properties added by ContourLayer. */
+export declare type _ContourLayerProps<DataT> = {
+  /**
+   * Size of each cell in meters.
+   * @default 1000
+   */
+  cellSize?: number;
+  /**
+   * When set to true, aggregation is performed on GPU, provided other conditions are met.
+   * @default true
+   */
+  gpuAggregation?: boolean;
+  /**
+   * Defines the type of aggregation operation, valid values are 'SUM', 'MEAN', 'MIN' and 'MAX'.
+   * @default 'SUM'
+   */
+  aggregation?: 'SUM' | 'MEAN' | 'MIN' | 'MAX';
+  /**
+   * Definition of contours to be drawn.
+   * @default [{threshold: 1}]
+   */
+  contours: {
+    /**
+     * Isolines: `threshold` value must be a single `Number`, Isolines are generated based on this threshold value.
+     *
+     * Isobands: `threshold` value must be an Array of two `Number`s. Isobands are generated using `[threshold[0], threshold[1])` as threshold range, i.e area that has values `>= threshold[0]` and `< threshold[1]` are rendered with corresponding color. NOTE: `threshold[0]` is inclusive and `threshold[1]` is not inclusive.
+     */
+    threshold: number | number[];
+    /**
+     * RGBA color array to be used to render the contour.
+     * @default [255, 255, 255, 255]
+     */
+    color?: Color;
+    /**
+     * Applicable for `Isoline`s only, width of the Isoline in pixels.
+     * @default 1
+     */
+    strokeWidth?: number;
+    /** Defines z order of the contour. */
+    zIndex?: number;
+  }[];
+  /**
+   * A very small z offset that is added for each vertex of a contour (Isoline or Isoband).
+   * @default 0.005
+   */
+  zOffset?: number;
+  /**
+   * Method called to retrieve the position of each object.
+   * @default object => object.position
+   */
+  getPosition?: AccessorFunction<DataT, Position>;
+  /**
+   * The weight of each object.
+   * @default 1
+   */
+  getWeight?: Accessor<DataT, number>;
+};
+/** Aggregate data into iso-lines or iso-bands for a given threshold and cell size. */
+export default class ContourLayer<DataT = any, ExtraPropsT = {}> extends GridAggregationLayer<
+  ExtraPropsT & Required<_ContourLayerProps<DataT>>
+> {
+  static layerName: string;
+  static defaultProps: DefaultProps<ContourLayerProps<any>>;
+  initializeState(): void;
+  updateState(opts: UpdateParameters<this>): void;
+  renderLayers(): Layer[];
+  updateAggregationState(opts: any): void;
+  private _updateAccessors;
+  private _resetResults;
+  private _generateContours;
+  private _updateThresholdData;
+}
+// # sourceMappingURL=contour-layer.d.ts.map

modules/aggregation-layers/typed/contour-layer/contour-utils.d.ts

@@ -0,0 +1,24 @@
+export declare function generateContours({
+  thresholdData,
+  cellWeights,
+  gridSize,
+  gridOrigin,
+  cellSize
+}: {
+  thresholdData: any;
+  cellWeights: Float32Array;
+  gridSize: number[];
+  gridOrigin: number[];
+  cellSize: number[];
+}): {
+  contourSegments: {
+    start: number[];
+    end: number[];
+    contour: any;
+  }[];
+  contourPolygons: {
+    vertices: number[][];
+    contour: any;
+  }[];
+};
+// # sourceMappingURL=contour-utils.d.ts.map

modules/aggregation-layers/typed/contour-layer/marching-squares-codes.d.ts

@@ -0,0 +1,34 @@
+export declare const ISOLINES_CODE_OFFSET_MAP: {
+  0: any[];
+  1: number[][][];
+  2: number[][][];
+  3: number[][][];
+  4: number[][][];
+  5: {
+    0: number[][][];
+    1: number[][][];
+  };
+  6: number[][][];
+  7: number[][][];
+  8: number[][][];
+  9: number[][][];
+  10: {
+    0: number[][][];
+    1: number[][][];
+  };
+  11: number[][][];
+  12: number[][][];
+  13: number[][][];
+  14: number[][][];
+  15: any[];
+};
+export declare const ISOBANDS_CODE_OFFSET_MAP: {
+  [x: number]:
+    | number[][][]
+    | {
+        0: number[][][];
+        1: number[][][];
+        2: number[][][];
+      };
+};
+// # sourceMappingURL=marching-squares-codes.d.ts.map

modules/aggregation-layers/typed/contour-layer/marching-squares.d.ts

@@ -0,0 +1,10 @@
+export declare const CONTOUR_TYPE: {
+  ISO_LINES: number;
+  ISO_BANDS: number;
+};
+export declare function getCode(opts: any): {
+  code: number;
+  meanCode: number;
+};
+export declare function getVertices(opts: any): number[][] | number[][][];
+// # sourceMappingURL=marching-squares.d.ts.map