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

package/src/animation-loop/animation-loop.ts

@@ -3,7 +3,10 @@
 // Copyright (c) vis.gl contributors
 
 import {luma, Device} from '@luma.gl/core';
-import {requestAnimationFrame, cancelAnimationFrame} from './request-animation-frame';
+import {
+  requestAnimationFramePolyfill,
+  cancelAnimationFramePolyfill
+} from './request-animation-frame';
 import {Timeline} from '../animation/timeline';
 import {AnimationProps} from './animation-props';
 import {Stats, Stat} from '@probe.gl/stats';
@@ -77,6 +80,7 @@ export class AnimationLoop {
   _nextFramePromise: Promise<AnimationLoop> | null = null;
   _resolveNextFrame: ((animationLoop: AnimationLoop) => void) | null = null;
   _cpuStartTime: number = 0;
+  _error: Error | null = null;
 
   // _gpuTimeQuery: Query | null = null;
 
@@ -123,6 +127,23 @@ export class AnimationLoop {
     this.destroy();
   }
 
+  setError(error: Error): void {
+    this.props.onError(error);
+    this._error = Error();
+    const canvas = this.device?.canvasContext?.canvas;
+    if (canvas instanceof HTMLCanvasElement) {
+      const errorDiv = document.createElement('h1');
+      errorDiv.innerHTML = error.message;
+      errorDiv.style.position = 'absolute';
+      errorDiv.style.top = '20%'; // left: 50%; transform: translate(-50%, -50%);';
+      errorDiv.style.left = '10px';
+      errorDiv.style.color = 'black';
+      errorDiv.style.backgroundColor = 'red';
+      document.body.appendChild(errorDiv);
+      // canvas.style.position = 'absolute';
+    }
+  }
+
   /** Flags this animation loop as needing redraw */
   setNeedsRedraw(reason: string): this {
     this.needsRedraw = this.needsRedraw || reason;
@@ -189,7 +210,7 @@ export class AnimationLoop {
     if (this._running) {
       // call callback
       // If stop is called immediately, we can end up in a state where props haven't been initialized...
-      if (this.animationProps) {
+      if (this.animationProps && !this._error) {
         this.props.onFinalize(this.animationProps);
       }
 
@@ -203,7 +224,7 @@ export class AnimationLoop {
 
   /** Explicitly draw a frame */
   redraw(): this {
-    if (this.device?.isLost) {
+    if (this.device?.isLost || this._error) {
       return this;
     }
 
@@ -302,7 +323,7 @@ export class AnimationLoop {
     // if (this.display && this.display.requestAnimationFrame) {
     //   this._animationFrameId = this.display.requestAnimationFrame(this._animationFrame.bind(this));
     // }
-    this._animationFrameId = requestAnimationFrame(this._animationFrame.bind(this));
+    this._animationFrameId = requestAnimationFramePolyfill(this._animationFrame.bind(this));
   }
 
   _cancelAnimationFrame(): void {
@@ -313,10 +334,10 @@ export class AnimationLoop {
     // VR display has a separate animation frame to sync with headset
     // TODO WebVR API discontinued, replaced by WebXR: https://immersive-web.github.io/webxr/
     // See https://developer.mozilla.org/en-US/docs/Web/API/VRDisplay/requestAnimationFrame
-    // if (this.display && this.display.cancelAnimationFrame) {
+    // if (this.display && this.display.cancelAnimationFramePolyfill) {
     //   this.display.cancelAnimationFrame(this._animationFrameId);
     // }
-    cancelAnimationFrame(this._animationFrameId);
+    cancelAnimationFramePolyfill(this._animationFrameId);
     this._animationFrameId = null;
   }
 

package/src/animation-loop/make-animation-loop.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {luma} from '@luma.gl/core';
+import {luma, Adapter} from '@luma.gl/core';
 import {AnimationLoopTemplate} from './animation-loop-template';
 import {AnimationLoop, AnimationLoopProps} from './animation-loop';
 import type {AnimationProps} from './animation-props';
@@ -10,7 +10,10 @@ import type {AnimationProps} from './animation-props';
 export type MakeAnimationLoopProps = Omit<
   AnimationLoopProps,
   'onCreateDevice' | 'onInitialize' | 'onRedraw' | 'onFinalize'
->;
+> & {
+  /** List of adapters to use when creating the device */
+  adapters?: Adapter[];
+};
 
 /** Instantiates and runs the render loop */
 export function makeAnimationLoop(
@@ -19,7 +22,9 @@ export function makeAnimationLoop(
 ): AnimationLoop {
   let renderLoop: AnimationLoopTemplate | null = null;
 
-  const device = props?.device || luma.createDevice({id: 'animation-loop'});
+  const device =
+    props?.device ||
+    luma.createDevice({id: 'animation-loop', adapters: props?.adapters, createCanvasContext: true});
 
   // Create an animation loop;
   const animationLoop = new AnimationLoop({

package/src/animation-loop/request-animation-frame.ts

@@ -2,17 +2,18 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-// Node.js polyfills for requestAnimationFrame and cancelAnimationFrame
 /* global window, setTimeout, clearTimeout */
 
+/** Node.js polyfill for requestAnimationFrame */
 // / <reference types="@types/node" />
-export function requestAnimationFrame(callback: (time?: any) => void): any {
+export function requestAnimationFramePolyfill(callback: (time?: any) => void): any {
   return typeof window !== 'undefined' && window.requestAnimationFrame
     ? window.requestAnimationFrame(callback)
     : setTimeout(callback, 1000 / 60);
 }
 
-export function cancelAnimationFrame(timerId: any): void {
+/** Node.js polyfill for cancelAnimationFrame */
+export function cancelAnimationFramePolyfill(timerId: any): void {
   return typeof window !== 'undefined' && window.cancelAnimationFrame
     ? window.cancelAnimationFrame(timerId)
     : clearTimeout(timerId);

package/src/application-utils/load-file.ts

@@ -11,8 +11,6 @@ export function setPathPrefix(prefix: string) {
   pathPrefix = prefix;
 }
 
-// TODO - keep only loadImageBitmap
-
 /**
  * Loads ImageBitmap asynchronously. Respects setPathPrefix.
  * image.crossOrigin can be set via opts.crossOrigin, default to 'anonymous'
@@ -20,13 +18,13 @@ export function setPathPrefix(prefix: string) {
  */
 export async function loadImageBitmap(
   url: string,
-  opts?: {crossOrigin?: string}
+  opts?: {crossOrigin?: string} & ImageBitmapOptions
 ): Promise<ImageBitmap> {
   const image = new Image();
   image.crossOrigin = opts?.crossOrigin || 'anonymous';
   image.src = url.startsWith('http') ? url : pathPrefix + url;
   await image.decode();
-  return await createImageBitmap(image);
+  return opts ? await createImageBitmap(image, opts) : await createImageBitmap(image);
 }
 
 /**

package/src/async-texture/async-texture.ts

@@ -1,9 +1,12 @@
 // luma.gl, MIT license
 // Copyright (c) vis.gl contributors
 
-import type {Texture, TextureProps, Sampler, TextureView, Device} from '@luma.gl/core';
-
 import type {
+  Texture,
+  TextureProps,
+  Sampler,
+  TextureView,
+  Device,
   Texture1DData,
   Texture2DData,
   Texture3DData,
@@ -13,6 +16,7 @@ import type {
 } from '@luma.gl/core';
 
 import {loadImageBitmap} from '../application-utils/load-file';
+import {uid} from '../utils/uid';
 
 export type AsyncTextureProps = Omit<TextureProps, 'data'> & AsyncTextureDataProps;
 
@@ -51,6 +55,7 @@ type AsyncTextureData = AsyncTextureProps['data'];
  */
 export class AsyncTexture {
   readonly device: Device;
+  readonly id: string;
 
   // TODO - should we type these as possibly `null`? It will make usage harder?
   // @ts-expect-error
@@ -67,8 +72,18 @@ export class AsyncTexture {
   protected resolveReady: () => void = () => {};
   protected rejectReady: (error: Error) => void = () => {};
 
+  get [Symbol.toStringTag]() {
+    return 'AsyncTexture';
+  }
+
+  toString(): string {
+    return `AsyncTexture:"${this.id}"(${this.isReady ? 'ready' : 'loading'})`;
+  }
+
   constructor(device: Device, props: AsyncTextureProps) {
     this.device = device;
+    this.id = props.id || uid('async-texture');
+    // this.id = typeof props?.data === 'string' ? props.data.slice(-20) : uid('async-texture');
 
     // Signature: new AsyncTexture(device, {data: url})
     if (typeof props?.data === 'string' && props.dimension === '2d') {
@@ -117,11 +132,28 @@ export class AsyncTexture {
     this.destroyed = true;
   }
 
-  // We could implement resize by replacing the texture
-  // resize(width: number, height: number): boolean {
-  //   throw new Error('Not implemented');
-  //   // return false;
-  // }
+  /**
+   * Textures are immutable and cannot be resized after creation,
+   * but we can create a similar texture with the same parameters but a new size.
+   * @note Does not copy contents of the texture
+   * @todo Abort pending promise and create a texture with the new size?
+   */
+  resize(size: {width: number; height: number}): boolean {
+    if (!this.isReady) {
+      throw new Error('Cannot resize texture before it is ready');
+    }
+
+    if (size.width === this.texture.width && size.height === this.texture.height) {
+      return false;
+    }
+
+    if (this.texture) {
+      const texture = this.texture;
+      this.texture = texture.clone(size);
+      texture.destroy();
+    }
+    return true;
+  }
 }
 
 // HELPERS

package/src/{transform → compute}/buffer-transform.ts

@@ -9,28 +9,37 @@ import type {ModelProps} from '../model/model';
 
 /**
  * Properties for creating a {@link BufferTransform}
- * @deprecated
+ * @note Only works under WebGL2.
  */
 export type BufferTransformProps = Omit<ModelProps, 'fs'> & {
+  /** Optional fragment shader - normally not used in transforms */
   fs?: ModelProps['fs']; // override as optional
+  /** A list of named outputs corresponding to shader declarations (varyings in WebGL) */
+  outputs?: string[];
+  /** @deprecated Use run({outputBuffers}) instead - Map of output buffers that the shaders will write results of computations to */
   feedbackBuffers?: Record<string, Buffer | BufferRange>;
 };
 
 /**
- * Creates a pipeline for buffer→buffer transforms.
- * @deprecated
+ * Manages a WebGL program (pipeline) for buffer→buffer transforms.
+ * @note Only works under WebGL2.
  */
 export class BufferTransform {
   readonly device: Device;
   readonly model: Model;
   readonly transformFeedback: TransformFeedback;
 
-  /** @deprecated Use device feature test. */
+  static defaultProps: Required<BufferTransformProps> = {
+    ...Model.defaultProps,
+    outputs: undefined!,
+    feedbackBuffers: undefined!
+  };
+
   static isSupported(device: Device): boolean {
     return device?.info?.type === 'webgl';
   }
 
-  constructor(device: Device, props: BufferTransformProps = Model.defaultProps) {
+  constructor(device: Device, props: BufferTransformProps = BufferTransform.defaultProps) {
     if (!BufferTransform.isSupported(device)) {
       throw new Error('BufferTransform not yet implemented on WebGPU');
     }
@@ -41,6 +50,7 @@ export class BufferTransform {
       id: props.id || 'buffer-transform-model',
       fs: props.fs || getPassthroughFS(),
       topology: props.topology || 'point-list',
+      varyings: props.outputs || props.varyings,
       ...props
     });
 
@@ -68,25 +78,31 @@ export class BufferTransform {
   }
 
   /** Run one transform loop. */
-  run(options?: RenderPassProps): void {
+  run(
+    options?: RenderPassProps & {
+      inputBuffers?: Record<string, Buffer>;
+      outputBuffers?: Record<string, Buffer>;
+    }
+  ): void {
+    if (options?.inputBuffers) {
+      this.model.setAttributes(options.inputBuffers);
+    }
+    if (options?.outputBuffers) {
+      this.transformFeedback.setBuffers(options.outputBuffers);
+    }
     const renderPass = this.device.beginRenderPass(options);
     this.model.draw(renderPass);
     renderPass.end();
   }
 
-  /** @deprecated */
-  update(...args: any[]): void {
-    // TODO(v9): Method should likely be removed for v9. Keeping a method stub
-    // to assist with migrating DeckGL usage.
-    // eslint-disable-next-line no-console
-    console.warn('TextureTransform#update() not implemented');
-  }
+  // DEPRECATED METHODS
 
-  /** Returns the {@link Buffer} or {@link BufferRange} for given varying name. */
+  /** @deprecated App knows what buffers it is passing in - Returns the {@link Buffer} or {@link BufferRange} for given varying name. */
   getBuffer(varyingName: string): Buffer | BufferRange | null {
     return this.transformFeedback.getBuffer(varyingName);
   }
 
+  /** @deprecated App knows what buffers it is passing in - Reads the {@link Buffer} or {@link BufferRange} for given varying name. */
   readAsync(varyingName: string): Promise<Uint8Array> {
     const result = this.getBuffer(varyingName);
     if (!result) {

package/src/{computation.ts → compute/computation.ts}

@@ -3,16 +3,22 @@
 // Copyright (c) vis.gl contributors
 
 import type {DeviceFeature, ComputePipelineProps, Shader, Binding} from '@luma.gl/core';
-import {Device, Buffer, ComputePipeline, ComputePass, UniformStore} from '@luma.gl/core';
-import {log} from '@luma.gl/core';
-import {getTypedArrayFromDataType} from '@luma.gl/core';
+import {
+  Device,
+  Buffer,
+  ComputePipeline,
+  ComputePass,
+  UniformStore,
+  log,
+  getTypedArrayFromDataType
+} from '@luma.gl/core';
 import type {ShaderModule, PlatformInfo} from '@luma.gl/shadertools';
 import {ShaderAssembler, getShaderLayoutFromWGSL} from '@luma.gl/shadertools';
 import {TypedArray, isNumericArray} from '@math.gl/types';
-import {ShaderInputs} from './shader-inputs';
-import {PipelineFactory} from './lib/pipeline-factory';
-import {ShaderFactory} from './lib/shader-factory';
-import {uid} from './utils/uid';
+import {ShaderInputs} from '../shader-inputs';
+import {PipelineFactory} from '../factories/pipeline-factory';
+import {ShaderFactory} from '../factories/shader-factory';
+import {uid} from '../utils/uid';
 // import {getDebugTableForShaderLayout} from '../debug/debug-shader-layout';
 
 const LOG_DRAW_PRIORITY = 2;
@@ -282,7 +288,7 @@ export class Computation {
         id: `${this.id}-fragment`,
         stage: 'compute',
         source: this.source,
-        debug: this.props.debugShaders
+        debugShaders: this.props.debugShaders
       });
 
       this.pipeline = this.pipelineFactory.createComputePipeline({

package/src/compute/swap.ts

@@ -0,0 +1,116 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {BufferProps, FramebufferProps} from '@luma.gl/core';
+import {Device, Resource, Buffer, Framebuffer, Texture} from '@luma.gl/core';
+
+/**
+ * Helper class for working with repeated transformations / computations
+ * Primarily intended for GPU buffers `Swap<Buffer>` or textures `Swap<Texture>`)
+ * @note the two resources are expected to be structurally identical (same size, length, format, etc)
+ * @note the two resources can be destroyed by calling `destroy()`
+ */
+export class Swap<T extends Resource<any>> {
+  /** The current resource - usually the source for renders or computations */
+  current: T;
+  /** The next resource - usually the target/destination for transforms / computations */
+  next: T;
+
+  constructor(props: {current: T; next: T}) {
+    this.current = props.current;
+    this.next = props.next;
+  }
+
+  /** Destroys the two managed resources */
+  destroy() {
+    this.current?.destroy();
+    this.next?.destroy();
+  }
+
+  /** Make the next resource into the current resource, and reuse the current resource as the next resource */
+  swap() {
+    const current = this.current;
+    this.current = this.next;
+    this.next = current;
+  }
+}
+
+/** Helper for managing double-buffered framebuffers */
+export class SwapFramebuffers extends Swap<Framebuffer> {
+  constructor(device: Device, props: FramebufferProps) {
+    props = {...props};
+
+    let colorAttachments = props.colorAttachments?.map(colorAttachment =>
+      typeof colorAttachment !== 'string'
+        ? colorAttachment
+        : device.createTexture({
+            format: colorAttachment,
+            usage: Texture.COPY_DST | Texture.RENDER_ATTACHMENT
+          })
+    );
+
+    const current = device.createFramebuffer({...props, colorAttachments});
+
+    colorAttachments = props.colorAttachments?.map(colorAttachment =>
+      typeof colorAttachment !== 'string'
+        ? colorAttachment
+        : device.createTexture({
+            format: colorAttachment,
+            usage: Texture.COPY_DST | Texture.RENDER_ATTACHMENT
+          })
+    );
+
+    const next = device.createFramebuffer({...props, colorAttachments});
+
+    super({current, next});
+  }
+
+  /**
+   * Resizes the Framebuffers.
+   * @returns true if the size changed, otherwise exiting framebuffers were preserved
+   * @note any contents are not preserved!
+   */
+  resize(size: {width: number; height: number}): boolean {
+    if (size.width === this.current.width && size.height === this.current.height) {
+      return false;
+    }
+    const {current, next} = this;
+
+    this.current = current.clone(size);
+    current.destroy();
+
+    this.next = next.clone(size);
+    next.destroy();
+
+    return true;
+  }
+}
+
+/** Helper for managing double-buffered GPU buffers */
+export class SwapBuffers extends Swap<Buffer> {
+  constructor(device: Device, props: BufferProps) {
+    super({current: device.createBuffer(props), next: device.createBuffer(props)});
+  }
+
+  /**
+   * Resizes the Buffers.
+   * @returns true if the size changed, otherwise exiting buffers were preserved.
+   * @note any contents are not preserved!
+   */
+  resize(props: {byteLength: number}) {
+    if (props.byteLength === this.current.byteLength) {
+      return false;
+    }
+
+    const {current, next} = this;
+
+    this.current = current.clone(props);
+    current.destroy();
+
+    this.next = next.clone(props);
+    next.destroy();
+
+    return true;
+  }
+}

package/src/{transform → compute}/texture-transform.ts

@@ -3,12 +3,12 @@
 // Copyright (c) vis.gl contributors
 
 import {Buffer, Device, Framebuffer, RenderPassProps, Sampler, Texture} from '@luma.gl/core';
-import {Model, ModelProps} from '../model/model';
 import {getPassthroughFS} from '@luma.gl/shadertools';
+import {Model, ModelProps} from '../model/model';
+import {uid} from '../utils/uid';
 
 /**
  * Properties for creating a {@link TextureTransform}
- * @deprecated
  */
 export type TextureTransformProps = Omit<ModelProps, 'fs'> & {
   fs?: ModelProps['fs']; // override as optional
@@ -61,7 +61,7 @@ export class TextureTransform {
     });
 
     this.model = new Model(this.device, {
-      id: props.id || 'texture-transform-model',
+      id: props.id || uid('texture-transform-model'),
       fs:
         props.fs ||
         getPassthroughFS({
@@ -78,7 +78,12 @@ export class TextureTransform {
   }
 
   // Delete owned resources.
-  destroy(): void {}
+  destroy(): void {
+    this.model.destroy();
+    for (const binding of this.bindings) {
+      binding.framebuffer?.destroy();
+    }
+  }
 
   /** @deprecated Use {@link destroy}. */
   delete(): void {
@@ -92,20 +97,6 @@ export class TextureTransform {
     renderPass.end();
   }
 
-  /** @deprecated */
-  update(...args: any[]): void {
-    // TODO(v9): Method should likely be removed for v9. Keeping a method stub
-    // to assist with migrating DeckGL usage.
-    // eslint-disable-next-line no-console
-    console.warn('TextureTransform#update() not implemented');
-  }
-
-  getData({packed = false} = {}) {
-    // TODO(v9): Method should likely be removed for v9. Keeping a method stub
-    // to assist with migrating DeckGL usage.
-    throw new Error('getData() not implemented');
-  }
-
   getTargetTexture(): Texture {
     const {targetTexture} = this.bindings[this.currentIndex];
     return targetTexture;

package/src/debug/debug-framebuffer.ts

@@ -38,7 +38,7 @@ export function debugFramebuffer(
     canvas.style.position = 'absolute';
     canvas.style.top = top; // ⚠️
     canvas.style.left = left; // ⚠️
-    canvas.style.border = 'blue 1px solid';
+    canvas.style.border = 'blue 5px solid';
     canvas.style.transform = 'scaleY(-1)';
     document.body.appendChild(canvas);
 

package/src/debug/debug-shader-layout.ts

@@ -31,7 +31,7 @@ export function getDebugTableForShaderLayout(
 
   for (const varyingDeclaration of layout.varyings || []) {
     const glslDeclaration = `${varyingDeclaration.location} ${varyingDeclaration.name}`;
-    table[`out ${glslDeclaration}`] = {[header]: JSON.stringify(varyingDeclaration.accessor)};
+    table[`out ${glslDeclaration}`] = {[header]: JSON.stringify(varyingDeclaration)};
   }
 
   return table;