visgl / deck.gl / 8264260624

// Copyright (c) 2015 - 2017 Uber Technologies, Inc.

//

// Permission is hereby granted, free of charge, to any person obtaining a copy

// of this software and associated documentation files (the "Software"), to deal

// in the Software without restriction, including without limitation the rights

// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

// copies of the Software, and to permit persons to whom the Software is

// furnished to do so, subject to the following conditions:

//

// The above copyright notice and this permission notice shall be included in

// all copies or substantial portions of the Software.

//

// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN

// THE SOFTWARE.

/* eslint-disable react/no-direct-mutation-state */

import {Buffer, TypedArray} from '@luma.gl/core';

import {COORDINATE_SYSTEM} from './constants';

import AttributeManager from './attribute/attribute-manager';

import UniformTransitionManager from './uniform-transition-manager';

import {diffProps, validateProps} from '../lifecycle/props';

import {LIFECYCLE, Lifecycle} from '../lifecycle/constants';

import {count} from '../utils/count';

import log from '../utils/log';

import debug from '../debug/index';

import assert from '../utils/assert';

import memoize from '../utils/memoize';

import {mergeShaders} from '../utils/shader';

import {projectPosition, getWorldPosition} from '../shaderlib/project/project-functions';

import typedArrayManager from '../utils/typed-array-manager';

import Component from '../lifecycle/component';

import LayerState, {ChangeFlags} from './layer-state';

import {worldToPixels} from '@math.gl/web-mercator';

import {load} from '@loaders.gl/core';

import type {Loader} from '@loaders.gl/loader-utils';

import type {CoordinateSystem} from './constants';

import type Attribute from './attribute/attribute';

import type {Model} from '@luma.gl/engine';

import type {PickingInfo, GetPickingInfoParams} from './picking/pick-info';

import type Viewport from '../viewports/viewport';

import type {NumericArray} from '../types/types';

import type {DefaultProps} from '../lifecycle/prop-types';

import type {LayerData, LayerProps} from '../types/layer-props';

import type {LayerContext} from './layer-manager';

import type {BinaryAttribute} from './attribute/attribute';

import {RenderPass} from '@luma.gl/core';

import {PickingProps} from '@luma.gl/shadertools';

const TRACE_CHANGE_FLAG = 'layer.changeFlag';

const TRACE_INITIALIZE = 'layer.initialize';

const TRACE_UPDATE = 'layer.update';

const TRACE_FINALIZE = 'layer.finalize';

const TRACE_MATCHED = 'layer.matched';

const MAX_PICKING_COLOR_CACHE_SIZE = 2 ** 24 - 1;

const EMPTY_ARRAY = Object.freeze([]);

// Only compare the same two viewports once

const areViewportsEqual = memoize(

  ({oldViewport, viewport}: {oldViewport: Viewport; viewport: Viewport}): boolean => {

    return oldViewport.equals(viewport);

  }

);

let pickingColorCache = new Uint8ClampedArray(0);

const defaultProps: DefaultProps<LayerProps> = {

  // data: Special handling for null, see below

  data: {type: 'data', value: EMPTY_ARRAY, async: true},

  dataComparator: {type: 'function', value: null, optional: true},

  _dataDiff: {

    type: 'function',

    // @ts-ignore __diff is not defined on data

    value: data => data && data.__diff,

    optional: true

  },

  dataTransform: {type: 'function', value: null, optional: true},

  onDataLoad: {type: 'function', value: null, optional: true},

  onError: {type: 'function', value: null, optional: true},

  fetch: {

    type: 'function',

    value: <LayerT extends Layer>(

      url: string,

      {

        propName,

        layer,

        loaders,

        loadOptions,

        signal

      }: {

        propName: string;

        layer: LayerT;

        loaders?: Loader[];

        loadOptions?: any;

        signal?: AbortSignal;

      }

    ) => {

      const {resourceManager} = layer.context;

      loadOptions = loadOptions || layer.getLoadOptions();

      loaders = loaders || layer.props.loaders;

      if (signal) {

        loadOptions = {

          ...loadOptions,

          fetch: {

            ...loadOptions?.fetch,

            signal

          }

        };

      }

      let inResourceManager = resourceManager.contains(url);

      if (!inResourceManager && !loadOptions) {

        // If there is no layer-specific load options, then attempt to cache this resource in the data manager

        resourceManager.add({resourceId: url, data: load(url, loaders), persistent: false});

        inResourceManager = true;

      }

      if (inResourceManager) {

        return resourceManager.subscribe({

          resourceId: url,

          onChange: data => layer.internalState?.reloadAsyncProp(propName, data),

          consumerId: layer.id,

          requestId: propName

        });

      }

      return load(url, loaders, loadOptions);

    }

  },

  updateTriggers: {}, // Update triggers: a core change detection mechanism in deck.gl

  visible: true,

  pickable: false,

  opacity: {type: 'number', min: 0, max: 1, value: 1},

  operation: 'draw',

  onHover: {type: 'function', value: null, optional: true},

  onClick: {type: 'function', value: null, optional: true},

  onDragStart: {type: 'function', value: null, optional: true},

  onDrag: {type: 'function', value: null, optional: true},

  onDragEnd: {type: 'function', value: null, optional: true},

  coordinateSystem: COORDINATE_SYSTEM.DEFAULT,

  coordinateOrigin: {type: 'array', value: [0, 0, 0], compare: true},

  modelMatrix: {type: 'array', value: null, compare: true, optional: true},

  wrapLongitude: false,

  positionFormat: 'XYZ',

  colorFormat: 'RGBA',

  parameters: {type: 'object', value: {}, optional: true, compare: 2},

  loadOptions: {type: 'object', value: null, optional: true, ignore: true},

  transitions: null,

  extensions: [],

  loaders: {type: 'array', value: [], optional: true, ignore: true},

  // Offset depth based on layer index to avoid z-fighting.

  // Negative values pull layer towards the camera

  // https://www.opengl.org/archives/resources/faq/technical/polygonoffset.htm

  getPolygonOffset: {

    type: 'function',

    value: ({layerIndex}) => [0, -layerIndex * 100]

  },

  // Selection/Highlighting

  highlightedObjectIndex: null,

  autoHighlight: false,

  highlightColor: {type: 'accessor', value: [0, 0, 128, 128]}

};

export type UpdateParameters<LayerT extends Layer> = {

  props: LayerT['props'];

  oldProps: LayerT['props'];

  context: LayerContext;

  changeFlags: ChangeFlags;

};

export type DrawOptions = {

  context: LayerContext;

  moduleParameters: any;

  parameters: any;

  renderPass: RenderPass;

  uniforms: any;

};

type SharedLayerState = {

  [key: string]: unknown;

};

export default abstract class Layer<PropsT extends {} = {}> extends Component<

  PropsT & Required<LayerProps>

> {

  static defaultProps: DefaultProps = defaultProps;

  static layerName: string = 'Layer';

  static override get componentName() {

    return Object.prototype.hasOwnProperty.call(this, 'layerName') ? this.layerName : '';

  }

  internalState: LayerState<this> | null = null;

  lifecycle: Lifecycle = LIFECYCLE.NO_STATE; // Helps track and debug the life cycle of the layers

  // context and state can technically be null before a layer is initialized/matched.

  // However, they are most extensively accessed in a layer's lifecycle methods, where they are always defined.

  // Checking for null state constantly in layer implementation is unnecessarily verbose.

  context!: LayerContext; // Will reference layer manager's context, contains state shared by layers

  state!: SharedLayerState; // Will be set to the shared layer state object during layer matching

  parent: Layer | null = null;

  get root(): Layer {

  toString(): string {

    return `${className}({id: '${this.props.id}'})`;

  }

  // Public API for users

  /** Projects a point with current view state from the current layer's coordinate system to screen */

  project(xyz: number[]): number[] {

  /** Unprojects a screen pixel to the current view's default coordinate system

      Note: this does not reverse `project`. */

  unproject(xy: number[]): number[] {

  /** Projects a point with current view state from the current layer's coordinate system to the world space */

  projectPosition(

    xyz: number[],

    params?: {

      /** The viewport to use */

      viewport?: Viewport;

      /** The coordinate system that the supplied position is in. Default to the same as `coordinateSystem`. */

      fromCoordinateSystem?: CoordinateSystem;

      /** The coordinate origin that the supplied position is in. Default to the same as `coordinateOrigin`. */

      fromCoordinateOrigin?: [number, number, number];

      /** Whether to apply offset mode automatically as does the project shader module.

       * Offset mode places the origin of the common space at the given viewport's center. It is used in some use cases

       * to improve precision in the vertex shader due to the fp32 float limitation.

       * Use `autoOffset:false` if the returned position should not be dependent on the current viewport.

       * Default `true` */

      autoOffset?: boolean;

    }

  ): [number, number, number] {

    assert(this.internalState);

    return projectPosition(xyz, {

      viewport,

      modelMatrix: this.props.modelMatrix,

      coordinateOrigin: this.props.coordinateOrigin,

      coordinateSystem: this.props.coordinateSystem,

      ...params

    });

  }

  // Public API for custom layer implementation

  /** `true` if this layer renders other layers */

  get isComposite(): boolean {

    return false;

  }

  /** Updates selected state members and marks the layer for redraw */

  setState(partialState: any): void {

    this.setChangeFlags({stateChanged: true});

    Object.assign(this.state, partialState);

    this.setNeedsRedraw();

  }

  /** Sets the redraw flag for this layer, will trigger a redraw next animation frame */

  setNeedsRedraw(): void {

    if (this.internalState) {

      this.internalState.needsRedraw = true;

    }

  }

  /** Mark this layer as needs a deep update */

  setNeedsUpdate() {

    if (this.internalState) {

      this.context.layerManager.setNeedsUpdate(String(this));

      this.internalState.needsUpdate = true;

    }

  }

  /** Returns true if all async resources are loaded */

  get isLoaded(): boolean {

  }

  /** Returns true if using shader-based WGS84 longitude wrapping */

  get wrapLongitude(): boolean {

    return this.props.wrapLongitude;

  }

  /** @deprecated Returns true if the layer is visible in the picking pass */

  isPickable(): boolean {

  /** Returns an array of models used by this layer, can be overriden by layer subclass */

  getModels(): Model[] {

    const state = this.state as {

      models?: Model[];

      model: Model;

    };

    return (state && (state.models || (state.model && [state.model]))) || [];

  }

  // TODO deprecate in favour of setShaderModuleProps

  /** Update shader module parameters */

  setModuleParameters(moduleParameters: any): void {

    for (const model of this.getModels()) {

      model.updateModuleSettings(moduleParameters);

    }

  }

  /** Update shader input parameters */

  setShaderModuleProps(...props: Parameters<Model['shaderInputs']['setProps']>): void {

    for (const model of this.getModels()) {

      model.shaderInputs.setProps(...props);

    }

  }

  /** Returns the attribute manager of this layer */

  getAttributeManager(): AttributeManager | null {

    return this.internalState && this.internalState.attributeManager;

  }

  /** Returns the most recent layer that matched to this state

    (When reacting to an async event, this layer may no longer be the latest) */

  getCurrentLayer(): Layer<PropsT> | null {

  /** Returns the default parse options for async props */

  getLoadOptions(): any {

    return this.props.loadOptions;

  }

  use64bitPositions(): boolean {

    const {coordinateSystem} = this.props;

    return (

      coordinateSystem === COORDINATE_SYSTEM.DEFAULT ||

      coordinateSystem === COORDINATE_SYSTEM.LNGLAT ||

      coordinateSystem === COORDINATE_SYSTEM.CARTESIAN

    );

  }

  // Event handling

  onHover(info: PickingInfo, pickingEvent): boolean {

    return false;

  }

  onClick(info: PickingInfo, pickingEvent): boolean {

    return false;

  }

  // Returns the picking color that doesn't match any subfeature

  // Use if some graphics do not belong to any pickable subfeature

  // @return {Array} - a black color

  nullPickingColor() {

  // Returns the picking color that doesn't match any subfeature

  // Use if some graphics do not belong to any pickable subfeature

  encodePickingColor(i, target: number[] = []): number[] {

    target[0] = (i + 1) & 255;

    target[1] = ((i + 1) >> 8) & 255;

    target[2] = (((i + 1) >> 8) >> 8) & 255;

    return target;

  }

  // Returns the index corresponding to a picking color that doesn't match any subfeature

  // @param {Uint8Array} color - color array to be decoded

  // @return {Array} - the decoded picking color

  decodePickingColor(color) {

    assert(color instanceof Uint8Array);

    const [i1, i2, i3] = color;

    // 1 was added to seperate from no selection

    const index = i1 + i2 * 256 + i3 * 65536 - 1;

    return index;

  }

  /** Deduces number of instances. Intention is to support:

    - Explicit setting of numInstances

    - Auto-deduction for ES6 containers that define a size member

    - Auto-deduction for Classic Arrays via the built-in length attribute

    - Auto-deduction via arrays */

  getNumInstances(): number {

    // First Check if app has provided an explicit value

    if (Number.isFinite(this.props.numInstances)) {

      return this.props.numInstances as number;

    }

    // Second check if the layer has set its own value

    if (this.state && this.state.numInstances !== undefined) {

      return this.state.numInstances as number;

    }

    // Use container library to get a count for any ES6 container or object

    return count(this.props.data);

  }

  /** Buffer layout describes how many attribute values are packed for each data object

      The default (null) is one value each object.

      Some data formats (e.g. paths, polygons) have various length. Their buffer layout

      is in the form of [L0, L1, L2, ...] */

  getStartIndices(): NumericArray | null {

    // First Check if startIndices is provided as an explicit value

    if (this.props.startIndices) {

      return this.props.startIndices;

    }

    // Second check if the layer has set its own value

    if (this.state && this.state.startIndices) {

      return this.state.startIndices as NumericArray;

    }

    return null;

  }

  // Default implementation

  getBounds(): [number[], number[]] | null {

  // / LIFECYCLE METHODS - overridden by the layer subclasses

  /** Called once to set up the initial state. Layers can create WebGL resources here. */

  abstract initializeState(context: LayerContext): void;

  getShaders(shaders: any): any {

    for (const extension of this.props.extensions) {

      shaders = mergeShaders(shaders, extension.getShaders.call(this, extension));

    }

    return shaders;

  }

  /** Controls if updateState should be called. By default returns true if any prop has changed */

  shouldUpdateState(params: UpdateParameters<Layer<PropsT>>): boolean {

    return params.changeFlags.propsOrDataChanged;

  }

  /** Default implementation, all attributes will be invalidated and updated when data changes */

  // eslint-disable-next-line complexity

  updateState(params: UpdateParameters<Layer<PropsT>>): void {

    const attributeManager = this.getAttributeManager();

    const {dataChanged} = params.changeFlags;

    if (dataChanged && attributeManager) {

      if (Array.isArray(dataChanged)) {

        // is partial update

        for (const dataRange of dataChanged) {

          attributeManager.invalidateAll(dataRange);

        }

      } else {

        attributeManager.invalidateAll();

      }

    }

    // Enable/disable picking buffer

    if (attributeManager) {

      const {props} = params;

      const hasPickingBuffer = this.internalState!.hasPickingBuffer;

      const needsPickingBuffer =

        Number.isInteger(props.highlightedObjectIndex) ||

        props.pickable ||

        props.extensions.some(extension => extension.getNeedsPickingBuffer.call(this, extension));

      // Only generate picking buffer if needed

      if (hasPickingBuffer !== needsPickingBuffer) {

        this.internalState!.hasPickingBuffer = needsPickingBuffer;

        const {pickingColors, instancePickingColors} = attributeManager.attributes;

        const pickingColorsAttribute = pickingColors || instancePickingColors;

        if (pickingColorsAttribute) {

          if (needsPickingBuffer && pickingColorsAttribute.constant) {

            pickingColorsAttribute.constant = false;

            attributeManager.invalidate(pickingColorsAttribute.id);

          }

          if (!pickingColorsAttribute.value && !needsPickingBuffer) {

            pickingColorsAttribute.constant = true;

            pickingColorsAttribute.value = [0, 0, 0];

          }

        }

      }

    }

  }

  /** Called once when layer is no longer matched and state will be discarded. Layers can destroy WebGL resources here. */

  finalizeState(context: LayerContext): void {

    for (const model of this.getModels()) {

      model.destroy();

    }

    const attributeManager = this.getAttributeManager();

    if (attributeManager) {

      attributeManager.finalize();

    }

    if (this.context) {

      this.context.resourceManager.unsubscribe({consumerId: this.id});

    }

    if (this.internalState) {

      this.internalState.uniformTransitions.clear();

      this.internalState.finalize();

    }

  }

  // If state has a model, draw it with supplied uniforms

  draw(opts: DrawOptions) {

  }

  // called to populate the info object that is passed to the event handler

  // @return null to cancel event

  getPickingInfo({info, mode, sourceLayer}: GetPickingInfoParams) {

    const {index} = info;

    if (index >= 0) {

      // If props.data is an indexable array, get the object

      if (Array.isArray(this.props.data)) {

        info.object = this.props.data[index];

      }

    }

    return info;

  }

  // END LIFECYCLE METHODS

  // / INTERNAL METHODS - called by LayerManager, DeckRenderer and DeckPicker

  /** (Internal) Propagate an error event through the system */

  raiseError(error: Error, message: string): void {

    if (message) {

      // Duplicating error message for backward compatibility, see #7986

      // TODO - revisit in v9

      error = new Error(`${message}: ${error.message}`, {cause: error});

    }

      this.context?.onError?.(error, this);

    }

  }

  /** (Internal) Checks if this layer needs redraw */

  getNeedsRedraw(

    opts: {

      /** Reset redraw flags to false after the check */

      clearRedrawFlags: boolean;

    } = {clearRedrawFlags: false}

  ): string | false {

    return this._getNeedsRedraw(opts);

  }

  /** (Internal) Checks if this layer needs a deep update */

  needsUpdate(): boolean {

    // Call subclass lifecycle method

    return (

      this.internalState.needsUpdate ||

      this.hasUniformTransition() ||

      this.shouldUpdateState(this._getUpdateParams())

    );

    // End lifecycle method

  }

  /** Checks if this layer has ongoing uniform transition */

  hasUniformTransition(): boolean {

    return this.internalState?.uniformTransitions.active || false;

  }

  /** Called when this layer is rendered into the given viewport */

  activateViewport(viewport: Viewport): void {

    const oldViewport = this.internalState.viewport;

    this.internalState.viewport = viewport;

    if (!oldViewport || !areViewportsEqual({oldViewport, viewport})) {

      this.setChangeFlags({viewportChanged: true});

      if (this.isComposite) {

        if (this.needsUpdate()) {

          // Composite layers may add/remove sublayers on viewport change

          // Because we cannot change the layers list during a draw cycle, we don't want to update sublayers right away

          // This will not call update immediately, but mark the layerManager as needs update on the next frame

          this.setNeedsUpdate();

        }

      } else {

        this._update();

      }

    }

  }

  /** Default implementation of attribute invalidation, can be redefined */

  protected invalidateAttribute(name = 'all'): void {

    const attributeManager = this.getAttributeManager();

    if (!attributeManager) {

      return;

    }

    if (name === 'all') {

      attributeManager.invalidateAll();

    } else {

      attributeManager.invalidate(name);

    }

  }

  /** Send updated attributes to the WebGL model */

  protected updateAttributes(changedAttributes: {[id: string]: Attribute}) {

    // If some buffer layout changed

    let bufferLayoutChanged = false;

    for (const id in changedAttributes) {

      if (changedAttributes[id].layoutChanged()) {

        bufferLayoutChanged = true;

      }

    }

    for (const model of this.getModels()) {

      this._setModelAttributes(model, changedAttributes, bufferLayoutChanged);

    }

  }

  /** Recalculate any attributes if needed */

  protected _updateAttributes(): void {

    const attributeManager = this.getAttributeManager();

    const props = this.props;

    // Figure out data length

    const numInstances = this.getNumInstances();

    const startIndices = this.getStartIndices();

    attributeManager.update({

      data: props.data,

      numInstances,

      startIndices,

      props,

      transitions: props.transitions,

      // @ts-ignore (TS2339) property attribute is not present on some acceptable data types

      buffers: props.data.attributes,

      context: this

    });

    const changedAttributes = attributeManager.getChangedAttributes({clearChangedFlags: true});

    this.updateAttributes(changedAttributes);

  }

  /** Update attribute transitions. This is called in drawLayer, no model updates required. */

  private _updateAttributeTransition() {

    const attributeManager = this.getAttributeManager();

    if (attributeManager) {

      attributeManager.updateTransition();

    }

  }

  /** Update uniform (prop) transitions. This is called in updateState, may result in model updates. */

  private _updateUniformTransition(): Layer<PropsT>['props'] {

    // @ts-ignore (TS2339) internalState is alwasy defined when this method is called

    const {uniformTransitions} = this.internalState;

    return this.props;

  }

  /** Updater for the automatically populated instancePickingColors attribute */

  protected calculateInstancePickingColors(

    attribute: Attribute,

    {numInstances}: {numInstances: number}

  ) {

    // calculateInstancePickingColors always generates the same sequence.

    // pickingColorCache saves the largest generated sequence for reuse

    const cacheSize = Math.floor(pickingColorCache.length / 4);

    // Record when using the picking buffer cache, so that layers can always point at the most recently allocated cache

    // @ts-ignore (TS2531) internalState is always defined when this method is called

    this.internalState.usesPickingColorCache = true;

    if (cacheSize < numInstances) {

      pickingColorCache = typedArrayManager.allocate(pickingColorCache, numInstances, {

        size: 4,

        copy: true,

        maxCount: Math.max(numInstances, MAX_PICKING_COLOR_CACHE_SIZE)

      });

      // If the attribute is larger than the cache, resize the cache and populate the missing chunk

      const newCacheSize = Math.floor(pickingColorCache.length / 4);

      const pickingColor = [];

      for (let i = cacheSize; i < newCacheSize; i++) {

        this.encodePickingColor(i, pickingColor);

        pickingColorCache[i * 4 + 0] = pickingColor[0];

        pickingColorCache[i * 4 + 1] = pickingColor[1];

        pickingColorCache[i * 4 + 2] = pickingColor[2];

      }

    }

    attribute.value = pickingColorCache.subarray(0, numInstances * 4);

  }

  /** Apply changed attributes to model */

  protected _setModelAttributes(

    model: Model,

    changedAttributes: {

      [id: string]: Attribute;

    },

    bufferLayoutChanged = false

  ) {

    if (!Object.keys(changedAttributes).length) {

      return;

    }

    if (bufferLayoutChanged) {

      // AttributeManager is always defined when this method is called

      const attributeManager = this.getAttributeManager()!;

      model.setBufferLayout(attributeManager.getBufferLayouts());

      // All attributes must be reset after buffer layout change

      changedAttributes = attributeManager.getAttributes();

    }

    // @ts-ignore luma.gl type issue

    const excludeAttributes = model.userData?.excludeAttributes || {};

    const attributeBuffers: Record<string, Buffer> = {};

    const constantAttributes: Record<string, TypedArray> = {};

    for (const name in changedAttributes) {

      if (excludeAttributes[name]) {

        continue;

      }

      const values = changedAttributes[name].getValue();

      for (const attributeName in values) {

        const value = values[attributeName];

        if (value instanceof Buffer) {

          if (changedAttributes[name].settings.isIndexed) {

            model.setIndexBuffer(value);

          } else {

            attributeBuffers[attributeName] = value;

          }

        } else if (value) {

          constantAttributes[attributeName] = value;

        }

      }

    }

    // TODO - update buffer map?

    model.setAttributes(attributeBuffers);

    model.setConstantAttributes(constantAttributes);

  }

  /** (Internal) Sets the picking color at the specified index to null picking color. Used for multi-depth picking.

     This method may be overriden by layer implementations */

  disablePickingIndex(objectIndex: number) {

  // TODO - simplify subclassing interface

  protected _disablePickingIndex(objectIndex: number): void {

  /** (Internal) Re-enable all picking indices after multi-depth picking */

  restorePickingColors(): void {