@luma.gl/test-utils 9.3.0-alpha.4 → 9.3.0-alpha.8

package/src/create-test-device.ts

@@ -10,13 +10,26 @@ import {nullAdapter} from './null-device/null-adapter';
 import {NullDevice} from './null-device/null-device';
 
 const DEFAULT_CANVAS_CONTEXT_PROPS: CanvasContextProps = {width: 1, height: 1};
+const TEST_DEVICE_CACHE_KEY = '__lumaTestDeviceCache';
 
-/** A null device intended for testing - @note Only available after getTestDevices() has completed */
-let nullDevicePromise = makeNullTestDevice();
-/** This WebGL Device can be used directly but will not have WebGL debugging initialized */
-const webglDevicePromise = makeWebGLTestDevice();
-/** A WebGL 2 Device intended for testing - @note Only available after getTestDevices() has completed */
-const webgpuDevicePromise = makeWebGPUTestDevice();
+type TestDeviceCache = {
+  /** A null device intended for testing - @note Only available after getTestDevices() has completed */
+  nullDevicePromise: Promise<NullDevice> | null;
+  /** This WebGL Device can be used directly but will not have WebGL debugging initialized */
+  webglDevicePromise: Promise<WebGLDevice> | null;
+  /** A shared offscreen WebGL device for presentation-context tests */
+  presentationWebglDevicePromise: Promise<WebGLDevice | null> | null;
+  /** A WebGL 2 Device intended for testing - @note Only available after getTestDevices() has completed */
+  webgpuDevicePromise: Promise<WebGPUDevice | null> | null;
+};
+
+declare global {
+  interface Window {
+    [TEST_DEVICE_CACHE_KEY]?: TestDeviceCache;
+  }
+}
+
+const testDeviceCache = getOrCreateTestDeviceCache();
 
 /** Includes WebGPU device if available */
 export async function getTestDevices(
@@ -32,29 +45,61 @@ export async function getTestDevice(
 ): Promise<Device | null> {
   switch (type) {
     case 'webgl':
-      return webglDevicePromise;
+      return getOrCreateWebGLTestDevicePromise();
     case 'webgpu':
-      return webgpuDevicePromise;
+      return getWebGPUTestDevice();
     case 'null':
-      return nullDevicePromise;
+      return getOrCreateNullTestDevicePromise();
     case 'unknown':
       return null;
   }
 }
 
 /** returns WebGPU device promise, if available */
-export function getWebGPUTestDevice(): Promise<WebGPUDevice | null> {
-  return webgpuDevicePromise;
+export async function getWebGPUTestDevice(): Promise<WebGPUDevice | null> {
+  const webgpuDevice = await getOrCreateWebGPUTestDevicePromise();
+  if (webgpuDevice?.isLost) {
+    if (testDeviceCache.webgpuDevicePromise) {
+      testDeviceCache.webgpuDevicePromise = null;
+    }
+    return getOrCreateWebGPUTestDevicePromise();
+  }
+  return webgpuDevice;
 }
 
 /** returns WebGL device promise, if available */
 export async function getWebGLTestDevice(): Promise<WebGLDevice> {
-  return webglDevicePromise;
+  return getOrCreateWebGLTestDevicePromise();
+}
+
+/** returns an offscreen WebGL device promise for presentation-context tests, if available */
+export async function getPresentationWebGLTestDevice(): Promise<WebGLDevice | null> {
+  return getOrCreatePresentationWebGLTestDevicePromise();
 }
 
 /** returns null device promise, if available */
 export async function getNullTestDevice(): Promise<NullDevice> {
-  return nullDevicePromise;
+  return getOrCreateNullTestDevicePromise();
+}
+
+function getOrCreateWebGPUTestDevicePromise(): Promise<WebGPUDevice | null> {
+  testDeviceCache.webgpuDevicePromise ||= makeWebGPUTestDevice();
+  return testDeviceCache.webgpuDevicePromise;
+}
+
+function getOrCreateWebGLTestDevicePromise(): Promise<WebGLDevice> {
+  testDeviceCache.webglDevicePromise ||= makeWebGLTestDevice();
+  return testDeviceCache.webglDevicePromise;
+}
+
+function getOrCreatePresentationWebGLTestDevicePromise(): Promise<WebGLDevice | null> {
+  testDeviceCache.presentationWebglDevicePromise ||= makePresentationWebGLTestDevice();
+  return testDeviceCache.presentationWebglDevicePromise;
+}
+
+function getOrCreateNullTestDevicePromise(): Promise<NullDevice> {
+  testDeviceCache.nullDevicePromise ||= makeNullTestDevice();
+  return testDeviceCache.nullDevicePromise;
 }
 
 async function makeWebGPUTestDevice(): Promise<WebGPUDevice | null> {
@@ -67,6 +112,11 @@ async function makeWebGPUTestDevice(): Promise<WebGPUDevice | null> {
       createCanvasContext: DEFAULT_CANVAS_CONTEXT_PROPS,
       debug: true
     })) as unknown as WebGPUDevice;
+    webgpuDevice.lost.finally(() => {
+      if (testDeviceCache.webgpuDevicePromise === webgpuDeviceResolvers.promise) {
+        testDeviceCache.webgpuDevicePromise = null;
+      }
+    });
     webgpuDeviceResolvers.resolve(webgpuDevice);
   } catch (error) {
     log.error(String(error))();
@@ -87,6 +137,11 @@ async function makeWebGLTestDevice(): Promise<WebGLDevice> {
       createCanvasContext: DEFAULT_CANVAS_CONTEXT_PROPS,
       debug: true
     })) as unknown as WebGLDevice;
+    webglDevice.lost.finally(() => {
+      if (testDeviceCache.webglDevicePromise === webglDeviceResolvers.promise) {
+        testDeviceCache.webglDevicePromise = null;
+      }
+    });
     webglDeviceResolvers.resolve(webglDevice);
   } catch (error) {
     log.error(String(error))();
@@ -96,6 +151,35 @@ async function makeWebGLTestDevice(): Promise<WebGLDevice> {
   return webglDeviceResolvers.promise;
 }
 
+async function makePresentationWebGLTestDevice(): Promise<WebGLDevice | null> {
+  if (typeof OffscreenCanvas === 'undefined') {
+    return null;
+  }
+
+  const presentationWebGLDeviceResolvers = withResolvers<WebGLDevice | null>();
+  try {
+    const webglDevice = (await luma.createDevice({
+      id: 'webgl-presentation-context-test-device',
+      type: 'webgl',
+      adapters: [webgl2Adapter],
+      createCanvasContext: {canvas: new OffscreenCanvas(4, 4)},
+      debug: true
+    })) as unknown as WebGLDevice;
+    webglDevice.lost.finally(() => {
+      if (
+        testDeviceCache.presentationWebglDevicePromise === presentationWebGLDeviceResolvers.promise
+      ) {
+        testDeviceCache.presentationWebglDevicePromise = null;
+      }
+    });
+    presentationWebGLDeviceResolvers.resolve(webglDevice);
+  } catch (error) {
+    log.error(String(error))();
+    presentationWebGLDeviceResolvers.resolve(null);
+  }
+  return presentationWebGLDeviceResolvers.promise;
+}
+
 /** returns null device promise, if available */
 async function makeNullTestDevice(): Promise<NullDevice> {
   const nullDeviceResolvers = withResolvers<NullDevice>();
@@ -111,13 +195,28 @@ async function makeNullTestDevice(): Promise<NullDevice> {
   } catch (error) {
     log.error(String(error))();
     // @ts-ignore TODO
-    nullDevicePromise = Promise.resolve(null);
+    testDeviceCache.nullDevicePromise = Promise.resolve(null);
   }
   return nullDeviceResolvers.promise;
 }
 
 // HELPERS
 
+function getOrCreateTestDeviceCache(): TestDeviceCache {
+  const rootObject = globalThis as typeof globalThis & {
+    [TEST_DEVICE_CACHE_KEY]?: TestDeviceCache;
+  };
+
+  rootObject[TEST_DEVICE_CACHE_KEY] ||= {
+    nullDevicePromise: null,
+    webglDevicePromise: null,
+    presentationWebglDevicePromise: null,
+    webgpuDevicePromise: null
+  };
+
+  return rootObject[TEST_DEVICE_CACHE_KEY];
+}
+
 // TODO - replace with Promise.withResolvers once we upgrade TS baseline
 function withResolvers<T>(): {
   promise: Promise<T>;

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

@@ -163,9 +163,9 @@ export class ClassicAnimationLoop {
     this.gl = (this.device && this.device.gl) || props.gl;
 
     this.stats = props.stats;
+    this.frameRate = this.stats.get('Frame Rate');
     this.cpuTime = this.stats.get('CPU Time');
     this.gpuTime = this.stats.get('GPU Time');
-    this.frameRate = this.stats.get('Frame Rate');
 
     this.setProps({
       autoResizeViewport: props.autoResizeViewport,
@@ -613,15 +613,7 @@ export class ClassicAnimationLoop {
     const width = this.gl.drawingBufferWidth;
     const height = this.gl.drawingBufferHeight;
 
-    // https://webglfundamentals.org/webgl/lessons/webgl-anti-patterns.html
-    let aspect = 1;
-
-    const canvas = getHTMLCanvasElement(this.gl.canvas);
-    if (canvas && canvas.clientHeight) {
-      aspect = canvas.clientWidth / canvas.clientHeight;
-    } else if (width > 0 && height > 0) {
-      aspect = width / height;
-    }
+    const aspect = width > 0 && height > 0 ? width / height : 1;
 
     return {width, height, aspect};
   }

package/src/deprecated/sync-test-device.ts

@@ -16,9 +16,22 @@ const DEFAULT_CANVAS_CONTEXT_PROPS: CanvasContextProps = {
  * @deprecated Use getWebGLTestDevice().
  */
 export function createTestDevice(): WebGLDevice | null {
+  if (cachedWebglDevice) {
+    return cachedWebglDevice;
+  }
+
+  if (
+    typeof navigator === 'undefined' ||
+    typeof document === 'undefined' ||
+    typeof HTMLCanvasElement === 'undefined'
+  ) {
+    return null;
+  }
+
   try {
     // TODO - We do not use luma.createDevice since createTestDevice currently expect WebGL context to be created synchronously
-    return new WebGLDevice({createCanvasContext: DEFAULT_CANVAS_CONTEXT_PROPS});
+    cachedWebglDevice = new WebGLDevice({createCanvasContext: DEFAULT_CANVAS_CONTEXT_PROPS});
+    return cachedWebglDevice;
   } catch (error) {
     // eslint-disable-next-line no-console
     console.error(`Failed to created device: ${(error as Error).message}`);
@@ -32,4 +45,6 @@ export function createTestDevice(): WebGLDevice | null {
  * @note This WebGL Device is create synchronously and can be used directly but will not have WebGL debugging initialized
  * @deprecated Use getWebGLTestDevice().
  */
+let cachedWebglDevice: WebGLDevice | null = null;
+
 export const webglDevice = createTestDevice();

package/src/index.ts

@@ -12,6 +12,7 @@ export {
   getTestDevices,
   getTestDevice,
   getWebGLTestDevice,
+  getPresentationWebGLTestDevice,
   getWebGPUTestDevice,
   getNullTestDevice
 } from './create-test-device';

package/src/null-device/null-canvas-context.ts

@@ -29,6 +29,7 @@ export class NullCanvasContext extends CanvasContext {
     // Base class constructor cannot access derived methods/fields, so we need to call these functions in the subclass constructor
     this._setAutoCreatedCanvasId(`${this.device.id}-canvas`);
     this._configureDevice();
+    this._startObservers();
   }
 
   _getCurrentFramebuffer(): NullFramebuffer {

package/src/null-device/null-device.ts

@@ -5,6 +5,8 @@
 import type {
   DeviceProps,
   CanvasContextProps,
+  PresentationContextProps,
+  PresentationContext,
   VertexArray,
   VertexArrayProps,
   BufferProps,
@@ -22,6 +24,7 @@ import type {
   QuerySetProps
 } from '@luma.gl/core';
 import {Device, DeviceFeatures} from '@luma.gl/core';
+import type {NullCommandBuffer} from './resources/null-command-buffer';
 
 import {NullDeviceInfo} from './null-device-info';
 import {NullDeviceLimits} from './null-device-features';
@@ -72,7 +75,9 @@ export class NullDevice extends Device {
    * Destroys the context
    * @note Has no effect for null contexts
    */
-  destroy(): void {}
+  destroy(): void {
+    this.commandEncoder?.destroy();
+  }
 
   get isLost(): boolean {
     return false;
@@ -84,6 +89,10 @@ export class NullDevice extends Device {
     return new NullCanvasContext(this, props);
   }
 
+  createPresentationContext(_props?: PresentationContextProps): PresentationContext {
+    throw new Error('PresentationContext is not supported on NullDevice');
+  }
+
   createBuffer(props: BufferProps | ArrayBuffer | ArrayBufferView): NullBuffer {
     const newProps = this._normalizeBufferProps(props);
     return new NullBuffer(this, newProps);
@@ -133,15 +142,23 @@ export class NullDevice extends Device {
     return new NullRenderPipeline(this, props);
   }
 
-  createComputePipeline(props?: ComputePipelineProps): ComputePipeline {
-    throw new Error('ComputePipeline not supported in WebGL');
+  createComputePipeline(_props?: ComputePipelineProps): ComputePipeline {
+    throw new Error('ComputePipeline is not supported on NullDevice');
   }
 
   override createCommandEncoder(props: CommandEncoderProps = {}): NullCommandEncoder {
     return new NullCommandEncoder(this, props);
   }
 
-  submit(): void {}
+  submit(commandBuffer?: NullCommandBuffer): void {
+    if (!commandBuffer) {
+      commandBuffer = this.commandEncoder.finish({id: `${this.id}-default-command-buffer`});
+      this.commandEncoder.destroy();
+      this.commandEncoder = this.createCommandEncoder({id: `${this.id}-default-command-encoder`});
+    }
+
+    commandBuffer.destroy();
+  }
 
   override setParametersWebGL(parameters: any): void {}
 

package/src/null-device/resources/null-command-buffer.ts

@@ -14,25 +14,35 @@ import {CommandBuffer} from '@luma.gl/core';
 import type {NullDevice} from '../null-device';
 
 export class NullCommandBuffer extends CommandBuffer {
-  device: NullDevice;
-  handle: null = null;
+  readonly device: NullDevice;
+  readonly handle: null = null;
 
   constructor(device: NullDevice, props: CommandBufferProps) {
     super(device, props);
     this.device = device;
   }
 
-  copyBufferToBuffer(options: CopyBufferToBufferOptions): void {}
+  copyBufferToBuffer(_options: CopyBufferToBufferOptions): void {
+    throw new Error('copyBufferToBuffer is not supported on NullDevice');
+  }
 
-  copyBufferToTexture(options: CopyBufferToTextureOptions) {}
+  copyBufferToTexture(_options: CopyBufferToTextureOptions) {
+    throw new Error('copyBufferToTexture is not supported on NullDevice');
+  }
 
-  copyTextureToBuffer(options: CopyTextureToBufferOptions): void {}
+  copyTextureToBuffer(_options: CopyTextureToBufferOptions): void {
+    throw new Error('copyTextureToBuffer is not supported on NullDevice');
+  }
 
-  copyTextureToTexture(options: CopyTextureToTextureOptions): void {}
+  copyTextureToTexture(_options: CopyTextureToTextureOptions): void {
+    throw new Error('copyTextureToTexture is not supported on NullDevice');
+  }
 
   pushDebugGroup(groupLabel: string): void {}
   popDebugGroup() {}
 
-  insertDebugMarker(markerLabel: string): void {}
-  resolveQuerySet(querySet: QuerySet): void {}
+  insertDebugMarker(_markerLabel: string): void {}
+  resolveQuerySet(_querySet: QuerySet): void {
+    throw new Error('resolveQuerySet is not supported on NullDevice');
+  }
 }

package/src/null-device/resources/null-command-encoder.ts

@@ -27,27 +27,43 @@ export class NullCommandEncoder extends CommandEncoder {
     this.device = device;
   }
 
-  finish(props: CommandBufferProps): NullCommandBuffer {
-    return new NullCommandBuffer(this.device, props);
+  override destroy(): void {
+    this.destroyResource();
+  }
+
+  finish(props: CommandBufferProps = {}): NullCommandBuffer {
+    const commandBuffer = new NullCommandBuffer(this.device, props);
+    this.destroy();
+    return commandBuffer;
   }
 
   beginRenderPass(props: RenderPassProps): NullRenderPass {
     return new NullRenderPass(this.device, props);
   }
 
-  beginComputePass(props: ComputePassProps): ComputePass {
-    throw new Error('ComputePass not supported in WebGL');
+  beginComputePass(_props: ComputePassProps): ComputePass {
+    throw new Error('ComputePass is not supported on NullDevice');
   }
 
-  copyBufferToBuffer(options: CopyBufferToBufferOptions): void {}
+  copyBufferToBuffer(_options: CopyBufferToBufferOptions): void {
+    throw new Error('copyBufferToBuffer is not supported on NullDevice');
+  }
 
-  copyBufferToTexture(options: CopyBufferToTextureOptions) {}
+  copyBufferToTexture(_options: CopyBufferToTextureOptions) {
+    throw new Error('copyBufferToTexture is not supported on NullDevice');
+  }
 
-  copyTextureToBuffer(options: CopyTextureToBufferOptions): void {}
+  copyTextureToBuffer(_options: CopyTextureToBufferOptions): void {
+    throw new Error('copyTextureToBuffer is not supported on NullDevice');
+  }
 
-  copyTextureToTexture(options: CopyTextureToTextureOptions): void {}
+  copyTextureToTexture(_options: CopyTextureToTextureOptions): void {
+    throw new Error('copyTextureToTexture is not supported on NullDevice');
+  }
 
-  resolveQuerySet(querySet: QuerySet): void {}
+  resolveQuerySet(_querySet: QuerySet): void {
+    throw new Error('resolveQuerySet is not supported on NullDevice');
+  }
 
   pushDebugGroup(groupLabel: string): void {}
   popDebugGroup() {}

package/src/null-device/resources/null-query-set.ts

@@ -13,4 +13,18 @@ export class NullQuerySet extends QuerySet {
     super(device, props);
     this.device = device;
   }
+
+  isResultAvailable(_queryIndex?: number): boolean {
+    return false;
+  }
+
+  async readResults(options?: {firstQuery?: number; queryCount?: number}): Promise<bigint[]> {
+    const firstQuery = options?.firstQuery || 0;
+    const queryCount = options?.queryCount || this.props.count - firstQuery;
+    return new Array(queryCount).fill(0n);
+  }
+
+  async readTimestampDuration(_beginIndex: number, _endIndex: number): Promise<number> {
+    return 0;
+  }
 }

package/src/null-device/resources/null-render-pass.ts

@@ -14,7 +14,12 @@ export class NullRenderPass extends RenderPass {
     this.device = device;
   }
 
-  end(): void {}
+  end(): void {
+    if (this.destroyed) {
+      return;
+    }
+    this.destroy();
+  }
 
   pushDebugGroup(groupLabel: string): void {}
   popDebugGroup(): void {}

package/src/null-device/resources/null-render-pipeline.ts

@@ -2,13 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {
-  UniformValue,
-  RenderPipelineProps,
-  Binding,
-  RenderPass,
-  VertexArray
-} from '@luma.gl/core';
+import type {RenderPipelineProps, Binding, RenderPass, VertexArray} from '@luma.gl/core';
 import {RenderPipeline} from '@luma.gl/core';
 
 import type {NullDevice} from '../null-device';
@@ -22,9 +16,6 @@ export class NullRenderPipeline extends RenderPipeline {
   vs: NullShader;
   fs: NullShader;
 
-  uniforms: Record<string, UniformValue> = {};
-  bindings: Record<string, Binding> = {};
-
   constructor(device: NullDevice, props: RenderPipelineProps) {
     super(device, props);
     this.device = device;
@@ -39,15 +30,13 @@ export class NullRenderPipeline extends RenderPipeline {
     };
   }
 
-  setBindings(bindings: Record<string, Binding>): void {
-    Object.assign(this.bindings, bindings);
-  }
-
   draw(options: {
     renderPass: RenderPass;
     vertexArray: VertexArray;
     vertexCount?: number;
     instanceCount?: number;
+    bindings?: Record<string, Binding>;
+    uniforms?: Record<string, unknown>;
   }): boolean {
     const {renderPass, vertexArray} = options;
     vertexArray.bindBeforeRender(renderPass);

package/src/null-device/resources/null-texture.ts

@@ -46,6 +46,8 @@ export class NullTexture extends Texture {
       arrayLayerCount: 1
     });
 
+    this.trackAllocatedMemory(this.getAllocatedByteLength(), 'Texture');
+
     Object.seal(this);
   }
 
@@ -61,16 +63,6 @@ export class NullTexture extends Texture {
   }
 
   copyExternalImage(options: CopyExternalImageOptions): {width: number; height: number} {
-    this.trackDeallocatedMemory('Texture');
-
-    // const {image: data} = options;
-    // if (data && data.byteLength) {
-    //   this.trackAllocatedMemory(data.byteLength, 'Texture');
-    // } else {
-    const bytesPerPixel = 4;
-    this.trackAllocatedMemory(this.width * this.height * bytesPerPixel, 'Texture');
-    // }
-
     return {width: this.width, height: this.height};
   }
 
@@ -78,23 +70,31 @@ export class NullTexture extends Texture {
     // ignore
   }
 
-  copyImageData(options: CopyImageDataOptions): void {
-    throw new Error('copyImageData not implemented');
+  override copyImageData(options: CopyImageDataOptions): void {
+    super.copyImageData(options);
   }
 
-  override readBuffer(options: TextureReadOptions = {}, buffer?: Buffer): Buffer {
-    return this.device.createBuffer({});
+  override readBuffer(_options: TextureReadOptions = {}, buffer?: Buffer): Buffer {
+    if (!buffer) {
+      throw new Error('buffer required');
+    }
+    return buffer;
   }
 
-  override async readDataAsync(options: TextureReadOptions = {}): Promise<ArrayBuffer> {
-    return new ArrayBuffer(0);
+  override async readDataAsync(_options: TextureReadOptions = {}): Promise<ArrayBuffer> {
+    throw new Error(
+      `${this} readDataAsync is deprecated; use readBuffer() with an explicit destination buffer or DynamicTexture.readAsync()`
+    );
   }
 
   override writeBuffer(buffer: Buffer, options: TextureWriteOptions = {}) {
     // ignore
   }
 
-  override writeData(data: ArrayBuffer | ArrayBufferView, options: TextureWriteOptions = {}): void {
+  override writeData(
+    data: ArrayBuffer | SharedArrayBuffer | ArrayBufferView,
+    options: TextureWriteOptions = {}
+  ): void {
     // ignore
   }
 }

package/src/test-runner.ts

@@ -7,6 +7,7 @@
 
 import {AnimationProps} from '@luma.gl/engine';
 import {getWebGLTestDevice} from './create-test-device';
+import {createTestDevice} from './deprecated/sync-test-device';
 
 // TODO - Replace with new AnimationLoop from `@luma.gl/engine`
 import {ClassicAnimationLoop as AnimationLoop} from './deprecated/classic-animation-loop';
@@ -65,7 +66,7 @@ const DEFAULT_TEST_PROPS: Required<TestRunnerProps> = {
 
 /** Runs an array of test cases */
 export class TestRunner {
-  device = webglDevice;
+  device = createTestDevice();
   props: Record<string, any>;
   isRunning: boolean = false;
   testOptions: Required<TestRunnerProps> = {...DEFAULT_TEST_PROPS};

package/src/utils/resource-tracker.ts

@@ -1,7 +1,7 @@
 /* global luma */
 export function getResourceCounts() {
   // @ts-ignore
-  const resourceStats = luma.stats.get('Resource Counts');
+  const resourceStats = luma.stats.get('GPU Resource Counts');
   return {
     Texture2D: resourceStats.get('Texture2Ds Active').count,
     Buffer: resourceStats.get('Buffers Active').count