@luma.gl/engine 9.1.0-alpha.9 → 9.1.0-beta.1

package/src/factories/pipeline-factory.ts

@@ -0,0 +1,222 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {RenderPipelineProps, ComputePipelineProps} from '@luma.gl/core';
+import {Device, RenderPipeline, ComputePipeline, log} from '@luma.gl/core';
+import {uid} from '../utils/uid';
+
+export type PipelineFactoryProps = RenderPipelineProps;
+
+type RenderPipelineCacheItem = {pipeline: RenderPipeline; useCount: number};
+type ComputePipelineCacheItem = {pipeline: ComputePipeline; useCount: number};
+
+/**
+ * Efficiently creates / caches pipelines
+ */
+export class PipelineFactory {
+  static defaultProps: Required<PipelineFactoryProps> = {...RenderPipeline.defaultProps};
+
+  /** Get the singleton default pipeline factory for the specified device */
+  static getDefaultPipelineFactory(device: Device): PipelineFactory {
+    device._lumaData.defaultPipelineFactory =
+      device._lumaData.defaultPipelineFactory || new PipelineFactory(device);
+    return device._lumaData.defaultPipelineFactory as PipelineFactory;
+  }
+
+  readonly device: Device;
+  readonly cachingEnabled: boolean;
+  readonly destroyPolicy: 'unused' | 'never';
+  readonly debug: boolean;
+
+  private _hashCounter: number = 0;
+  private readonly _hashes: Record<string, number> = {};
+  private readonly _renderPipelineCache: Record<string, RenderPipelineCacheItem> = {};
+  private readonly _computePipelineCache: Record<string, ComputePipelineCacheItem> = {};
+
+  get [Symbol.toStringTag](): string {
+    return 'PipelineFactory';
+  }
+
+  toString(): string {
+    return `PipelineFactory(${this.device.id})`;
+  }
+
+  constructor(device: Device) {
+    this.device = device;
+    this.cachingEnabled = device.props._cachePipelines;
+    this.destroyPolicy = device.props._cacheDestroyPolicy;
+    this.debug = device.props.debugFactories;
+  }
+
+  /** Return a RenderPipeline matching supplied props. Reuses an equivalent pipeline if already created. */
+  createRenderPipeline(props: RenderPipelineProps): RenderPipeline {
+    if (!this.cachingEnabled) {
+      return this.device.createRenderPipeline(props);
+    }
+
+    const allProps: Required<RenderPipelineProps> = {...RenderPipeline.defaultProps, ...props};
+
+    const cache = this._renderPipelineCache;
+    const hash = this._hashRenderPipeline(allProps);
+
+    let pipeline: RenderPipeline = cache[hash]?.pipeline;
+    if (!pipeline) {
+      pipeline = this.device.createRenderPipeline({
+        ...allProps,
+        id: allProps.id ? `${allProps.id}-cached` : uid('unnamed-cached')
+      });
+      pipeline.hash = hash;
+      cache[hash] = {pipeline, useCount: 1};
+      if (this.debug) {
+        log.warn(`${this}: ${pipeline} created, count=${cache[hash].useCount}`)();
+      }
+    } else {
+      cache[hash].useCount++;
+      if (this.debug) {
+        log.warn(
+          `${this}: ${cache[hash].pipeline} reused, count=${cache[hash].useCount}, (id=${props.id})`
+        )();
+      }
+    }
+
+    return pipeline;
+  }
+
+  /** Return a ComputePipeline matching supplied props. Reuses an equivalent pipeline if already created. */
+  createComputePipeline(props: ComputePipelineProps): ComputePipeline {
+    if (!this.cachingEnabled) {
+      return this.device.createComputePipeline(props);
+    }
+
+    const allProps: Required<ComputePipelineProps> = {...ComputePipeline.defaultProps, ...props};
+
+    const cache = this._computePipelineCache;
+    const hash = this._hashComputePipeline(allProps);
+
+    let pipeline: ComputePipeline = cache[hash]?.pipeline;
+    if (!pipeline) {
+      pipeline = this.device.createComputePipeline({
+        ...allProps,
+        id: allProps.id ? `${allProps.id}-cached` : undefined
+      });
+      pipeline.hash = hash;
+      cache[hash] = {pipeline, useCount: 1};
+      if (this.debug) {
+        log.warn(`${this}: ${pipeline} created, count=${cache[hash].useCount}`)();
+      }
+    } else {
+      cache[hash].useCount++;
+      if (this.debug) {
+        log.warn(
+          `${this}: ${cache[hash].pipeline} reused, count=${cache[hash].useCount}, (id=${props.id})`
+        )();
+      }
+    }
+
+    return pipeline;
+  }
+
+  release(pipeline: RenderPipeline | ComputePipeline): void {
+    if (!this.cachingEnabled) {
+      pipeline.destroy();
+      return;
+    }
+
+    const cache = this._getCache(pipeline);
+    const hash = pipeline.hash;
+
+    cache[hash].useCount--;
+    if (cache[hash].useCount === 0) {
+      this._destroyPipeline(pipeline);
+      if (this.debug) {
+        log.warn(`${this}: ${pipeline} released and destroyed`)();
+      }
+    } else if (cache[hash].useCount < 0) {
+      log.error(`${this}: ${pipeline} released, useCount < 0, resetting`)();
+      cache[hash].useCount = 0;
+    } else if (this.debug) {
+      log.warn(`${this}: ${pipeline} released, count=${cache[hash].useCount}`)();
+    }
+  }
+
+  // PRIVATE
+
+  /** Destroy a cached pipeline, removing it from the cache (depending on destroy policy) */
+  private _destroyPipeline(pipeline: RenderPipeline | ComputePipeline): boolean {
+    const cache = this._getCache(pipeline);
+
+    switch (this.destroyPolicy) {
+      case 'never':
+        return false;
+      case 'unused':
+        delete cache[pipeline.hash];
+        pipeline.destroy();
+        return true;
+    }
+  }
+
+  /** Get the appropriate cache for the type of pipeline */
+  private _getCache(
+    pipeline: RenderPipeline | ComputePipeline
+  ): Record<string, RenderPipelineCacheItem> | Record<string, ComputePipelineCacheItem> {
+    let cache:
+      | Record<string, RenderPipelineCacheItem>
+      | Record<string, ComputePipelineCacheItem>
+      | undefined;
+    if (pipeline instanceof ComputePipeline) {
+      cache = this._computePipelineCache;
+    }
+    if (pipeline instanceof RenderPipeline) {
+      cache = this._renderPipelineCache;
+    }
+    if (!cache) {
+      throw new Error(`${this}`);
+    }
+    if (!cache[pipeline.hash]) {
+      throw new Error(`${this}: ${pipeline} matched incorrect entry`);
+    }
+    return cache;
+  }
+
+  /** Calculate a hash based on all the inputs for a compute pipeline */
+  private _hashComputePipeline(props: ComputePipelineProps): string {
+    const {type} = this.device;
+    const shaderHash = this._getHash(props.shader.source);
+    return `${type}/C/${shaderHash}`;
+  }
+
+  /** Calculate a hash based on all the inputs for a render pipeline */
+  private _hashRenderPipeline(props: RenderPipelineProps): string {
+    const vsHash = props.vs ? this._getHash(props.vs.source) : 0;
+    const fsHash = props.fs ? this._getHash(props.fs.source) : 0;
+
+    // WebGL specific
+    // const {varyings = [], bufferMode = {}} = props;
+    // const varyingHashes = varyings.map((v) => this._getHash(v));
+    const varyingHash = '-'; // `${varyingHashes.join('/')}B${bufferMode}`
+    const bufferLayoutHash = this._getHash(JSON.stringify(props.bufferLayout));
+
+    const {type} = this.device;
+    switch (type) {
+      case 'webgl':
+        // WebGL is more dynamic
+        return `${type}/R/${vsHash}/${fsHash}V${varyingHash}BL${bufferLayoutHash}`;
+
+      case 'webgpu':
+      default:
+        // On WebGPU we need to rebuild the pipeline if topology, parameters or bufferLayout change
+        const parameterHash = this._getHash(JSON.stringify(props.parameters));
+        // TODO - Can json.stringify() generate different strings for equivalent objects if order of params is different?
+        // create a deepHash() to deduplicate?
+        return `${type}/R/${vsHash}/${fsHash}V${varyingHash}T${props.topology}P${parameterHash}BL${bufferLayoutHash}`;
+    }
+  }
+
+  private _getHash(key: string): number {
+    if (this._hashes[key] === undefined) {
+      this._hashes[key] = this._hashCounter++;
+    }
+    return this._hashes[key];
+  }
+}

package/src/{lib → factories}/shader-factory.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {Device, Shader, ShaderProps} from '@luma.gl/core';
+import {Device, Shader, ShaderProps, log} from '@luma.gl/core';
 
 /** Manages a cached pool of Shaders for reuse. */
 export class ShaderFactory {
@@ -15,17 +15,34 @@ export class ShaderFactory {
   }
 
   public readonly device: Device;
+  readonly cachingEnabled: boolean;
   readonly destroyPolicy: 'unused' | 'never';
+  readonly debug: boolean;
+
   private readonly _cache: Record<string, {shader: Shader; useCount: number}> = {};
 
+  get [Symbol.toStringTag](): string {
+    return 'ShaderFactory';
+  }
+
+  toString(): string {
+    return `${this[Symbol.toStringTag]}(${this.device.id})`;
+  }
+
   /** @internal */
   constructor(device: Device) {
     this.device = device;
-    this.destroyPolicy = device.props._factoryDestroyPolicy;
+    this.cachingEnabled = device.props._cacheShaders;
+    this.destroyPolicy = device.props._cacheDestroyPolicy;
+    this.debug = true; // device.props.debugFactories;
   }
 
   /** Requests a {@link Shader} from the cache, creating a new Shader only if necessary. */
   createShader(props: ShaderProps): Shader {
+    if (!this.cachingEnabled) {
+      return this.device.createShader(props);
+    }
+
     const key = this._hashShader(props);
 
     let cacheEntry = this._cache[key];
@@ -34,15 +51,27 @@ export class ShaderFactory {
         ...props,
         id: props.id ? `${props.id}-cached` : undefined
       });
-      this._cache[key] = cacheEntry = {shader, useCount: 0};
+      this._cache[key] = cacheEntry = {shader, useCount: 1};
+      if (this.debug) {
+        log.warn(`${this}: Created new shader ${shader.id}`)();
+      }
+    } else {
+      cacheEntry.useCount++;
+      if (this.debug) {
+        log.warn(`${this}: Reusing shader ${cacheEntry.shader.id} count=${cacheEntry.useCount}`)();
+      }
     }
 
-    cacheEntry.useCount++;
     return cacheEntry.shader;
   }
 
   /** Releases a previously-requested {@link Shader}, destroying it if no users remain. */
   release(shader: Shader): void {
+    if (!this.cachingEnabled) {
+      shader.destroy();
+      return;
+    }
+
     const key = this._hashShader(shader);
     const cacheEntry = this._cache[key];
     if (cacheEntry) {
@@ -51,14 +80,21 @@ export class ShaderFactory {
         if (this.destroyPolicy === 'unused') {
           delete this._cache[key];
           cacheEntry.shader.destroy();
+          if (this.debug) {
+            log.warn(`${this}: Releasing shader ${shader.id}, destroyed`)();
+          }
         }
+      } else if (cacheEntry.useCount < 0) {
+        throw new Error(`ShaderFactory: Shader ${shader.id} released too many times`);
+      } else if (this.debug) {
+        log.warn(`${this}: Releasing shader ${shader.id} count=${cacheEntry.useCount}`)();
       }
     }
   }
 
   // PRIVATE
 
-  private _hashShader(value: Shader | ShaderProps): string {
+  protected _hashShader(value: Shader | ShaderProps): string {
     return `${value.stage}:${value.source}`;
   }
 }

package/src/index.ts

@@ -21,16 +21,19 @@ export type {ModelProps} from './model/model';
 export {Model} from './model/model';
 
 // Transforms
-export type {BufferTransformProps} from './transform/buffer-transform';
-export {BufferTransform} from './transform/buffer-transform';
-export type {TextureTransformProps} from './transform/texture-transform';
-export {TextureTransform} from './transform/texture-transform';
+export type {BufferTransformProps} from './compute/buffer-transform';
+export {BufferTransform} from './compute/buffer-transform';
+export type {TextureTransformProps} from './compute/texture-transform';
+export {TextureTransform} from './compute/texture-transform';
 
-export {PipelineFactory} from './lib/pipeline-factory';
-export {ShaderFactory} from './lib/shader-factory';
+export {PipelineFactory} from './factories/pipeline-factory';
+export {ShaderFactory} from './factories/shader-factory';
 
-// Utils
-export {ClipSpace} from './lib/clip-space';
+// Models
+export type {ClipSpaceProps} from './models/clip-space';
+export {ClipSpace} from './models/clip-space';
+export type {BackgroundTextureModelProps} from './models/billboard-texture-model';
+export {BackgroundTextureModel} from './models/billboard-texture-model';
 
 // Scenegraph Core nodes
 export {ScenegraphNode} from './scenegraph/scenegraph-node';
@@ -60,19 +63,35 @@ export {SphereGeometry} from './geometries/sphere-geometry';
 export type {TruncatedConeGeometryProps} from './geometries/truncated-cone-geometry';
 export {TruncatedConeGeometry} from './geometries/truncated-cone-geometry';
 
+export {ShaderInputs} from './shader-inputs';
+
 // Application Utilities
 export {makeRandomGenerator} from './application-utils/random';
 export {setPathPrefix, loadImage, loadImageBitmap} from './application-utils/load-file';
 
 // EXPERIMENTAL
-export type {ShaderModuleInputs} from './shader-inputs';
-export {ShaderInputs as _ShaderInputs} from './shader-inputs';
-export type {ComputationProps} from './computation';
-export {Computation} from './computation';
-export {
-  requestAnimationFrame,
-  cancelAnimationFrame
-} from './animation-loop/request-animation-frame';
+export type {ShaderPassRendererProps} from './passes/shader-pass-renderer';
+export {ShaderPassRenderer} from './passes/shader-pass-renderer';
+
+export {Swap} from './compute/swap';
+export {SwapBuffers} from './compute/swap';
+export {SwapFramebuffers} from './compute/swap';
+
+export type {ComputationProps} from './compute/computation';
+export {Computation} from './compute/computation';
 
 export type {AsyncTextureProps} from './async-texture/async-texture';
 export {AsyncTexture} from './async-texture/async-texture';
+
+export {PickingManager} from './modules/picking/picking-manager';
+export {picking as indexPicking} from './modules/picking/index-picking';
+export {picking as colorPicking} from './modules/picking/color-picking';
+
+export {
+  requestAnimationFramePolyfill,
+  cancelAnimationFramePolyfill
+} from './animation-loop/request-animation-frame';
+
+// DEPRECATED
+
+export {LegacyPickingManager} from './modules/picking/legacy-picking-manager';