@luma.gl/test-utils 9.0.0-beta.5 → 9.0.0-beta.7

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

@@ -0,0 +1,194 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  DeviceProps,
+  CanvasContextProps,
+  TextureFormat,
+  VertexArray,
+  VertexArrayProps
+} from '@luma.gl/core';
+import {Device, CanvasContext, uid, DeviceFeatures} from '@luma.gl/core';
+
+import type {
+  BufferProps,
+  ShaderProps,
+  SamplerProps,
+  TextureProps,
+  ExternalTexture,
+  ExternalTextureProps,
+  FramebufferProps,
+  RenderPipelineProps,
+  ComputePipeline,
+  ComputePipelineProps,
+  RenderPassProps,
+  ComputePass,
+  ComputePassProps,
+  CommandEncoderProps,
+  TransformFeedbackProps,
+  QuerySetProps
+} from '@luma.gl/core';
+
+import {NullDeviceInfo} from './null-device-info';
+import {NullDeviceLimits} from './null-device-features';
+import {NullCanvasContext} from './null-canvas-context';
+import {NullBuffer} from './resources/null-buffer';
+import {NullFramebuffer} from './resources/null-framebuffer';
+import {NullShader} from './resources/null-shader';
+import {NullCommandEncoder} from './resources/null-command-buffer';
+import {NullSampler} from './resources/null-sampler';
+import {NullTexture} from './resources/null-texture';
+import {NullRenderPass} from './resources/null-render-pass';
+import {NullRenderPipeline} from './resources/null-render-pipeline';
+import {NullVertexArray} from './resources/null-vertex-array';
+import {NullTransformFeedback} from './resources/null-transform-feedback';
+import {NullQuerySet} from './resources/null-query-set';
+
+/** Do-nothing device implementation for testing */
+export class NullDevice extends Device {
+  static isSupported(): boolean {
+    return true;
+  }
+  static type: string = 'unknown';
+  readonly type = 'unknown';
+  features: DeviceFeatures = new DeviceFeatures([], this.props.disabledFeatures);
+  limits: NullDeviceLimits = new NullDeviceLimits();
+  readonly info = NullDeviceInfo;
+
+  readonly canvasContext: NullCanvasContext;
+  readonly lost: Promise<{reason: 'destroyed'; message: string}>;
+
+  static async create(props: DeviceProps = {}): Promise<NullDevice> {
+    // Wait for page to load: if canvas is a string we need to query the DOM for the canvas element.
+    // We only wait when props.canvas is string to avoids setting the global page onload callback unless necessary.
+    if (typeof props.canvas === 'string') {
+      await CanvasContext.pageLoaded;
+    }
+
+    return new NullDevice(props);
+  }
+
+  constructor(props: DeviceProps) {
+    super({...props, id: props.id || uid('dummy-device')});
+
+    this.canvasContext = new NullCanvasContext(this, props);
+    this.lost = new Promise(resolve => {});
+    this.canvasContext.resize();
+  }
+
+  /**
+   * Destroys the context
+   * @note Has no effect for WebGL browser contexts, there is no browser API for destroying contexts
+   */
+  destroy(): void {}
+
+  get isLost(): boolean {
+    return false;
+  }
+
+  getSize(): [number, number] {
+    return [this.canvasContext.width, this.canvasContext.height];
+  }
+
+  isTextureFormatSupported(format: TextureFormat): boolean {
+    return true;
+  }
+
+  isTextureFormatFilterable(format: TextureFormat): boolean {
+    return true;
+  }
+
+  isTextureFormatRenderable(format: TextureFormat): boolean {
+    return true;
+  }
+
+  // IMPLEMENTATION OF ABSTRACT DEVICE
+
+  createCanvasContext(props: CanvasContextProps): NullCanvasContext {
+    return new NullCanvasContext(this, props);
+  }
+
+  createBuffer(props: BufferProps | ArrayBuffer | ArrayBufferView): NullBuffer {
+    const newProps = this._getBufferProps(props);
+    return new NullBuffer(this, newProps);
+  }
+
+  getDefaultRenderPass(): NullRenderPass {
+    return new NullRenderPass(this, {});
+  }
+
+  _createTexture(props: TextureProps): NullTexture {
+    return new NullTexture(this, props);
+  }
+
+  createExternalTexture(props: ExternalTextureProps): ExternalTexture {
+    throw new Error('createExternalTexture() not implemented'); // return new Program(props);
+  }
+
+  createSampler(props: SamplerProps): NullSampler {
+    return new NullSampler(this, props);
+  }
+
+  createShader(props: ShaderProps): NullShader {
+    return new NullShader(this, props);
+  }
+
+  createFramebuffer(props: FramebufferProps): NullFramebuffer {
+    return new NullFramebuffer(this, props);
+  }
+
+  createVertexArray(props: VertexArrayProps): VertexArray {
+    return new NullVertexArray(this, props);
+  }
+
+  createTransformFeedback(props: TransformFeedbackProps): NullTransformFeedback {
+    return new NullTransformFeedback(this, props);
+  }
+
+  createQuerySet(props: QuerySetProps): NullQuerySet {
+    return new NullQuerySet(this, props);
+  }
+
+  createRenderPipeline(props: RenderPipelineProps): NullRenderPipeline {
+    return new NullRenderPipeline(this, props);
+  }
+
+  beginRenderPass(props: RenderPassProps): NullRenderPass {
+    return new NullRenderPass(this, props);
+  }
+
+  createComputePipeline(props?: ComputePipelineProps): ComputePipeline {
+    throw new Error('ComputePipeline not supported in WebGL');
+  }
+
+  beginComputePass(props: ComputePassProps): ComputePass {
+    throw new Error('ComputePass not supported in WebGL');
+  }
+
+  override createCommandEncoder(props: CommandEncoderProps = {}): NullCommandEncoder {
+    return new NullCommandEncoder(this, props);
+  }
+
+  submit(): void {}
+
+  override setParametersWebGL(parameters: any): void {}
+
+  override getParametersWebGL(parameters: any): any {}
+
+  override withParametersWebGL(parameters: any, func: any): any {
+    const {nocatch = true} = parameters;
+    let value: any;
+    if (nocatch) {
+      // Avoid try catch to minimize stack size impact for safe execution paths
+      return func();
+    }
+    // Wrap in a try-catch to ensure that parameters are restored on exceptions
+    try {
+      value = func();
+    } catch {
+      // ignore
+    }
+    return value;
+  }
+}

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

@@ -0,0 +1,42 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {BufferProps} from '@luma.gl/core';
+import {Buffer, assert} from '@luma.gl/core';
+import type {NullDevice} from '../null-device';
+
+export class NullBuffer extends Buffer {
+  device: NullDevice;
+
+  byteLength: number;
+
+  constructor(device: NullDevice, props: BufferProps = {}) {
+    super(device, props);
+    this.device = device;
+
+    const byteOffset = props.byteOffset || 0;
+    const byteLength = props.byteLength ?? (props.data ? props.data.byteLength + byteOffset : 0);
+
+    assert(byteLength >= 0);
+
+    this.byteLength = byteLength;
+    this.trackAllocatedMemory(byteLength);
+  }
+
+  override destroy(): void {
+    if (!this.destroyed) {
+      super.destroy();
+      this.trackDeallocatedMemory();
+    }
+  }
+
+  async readAsync(byteOffset = 0, byteLength?: number): Promise<Uint8Array> {
+    byteLength = byteLength ?? this.byteLength - byteOffset;
+    return new Uint8Array(byteLength);
+  }
+
+  write(data: ArrayBufferView, byteOffset: number = 0): void {
+    assert(data.byteLength + byteOffset <= this.byteLength);
+  }
+}

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

@@ -0,0 +1,38 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {CommandEncoder, CommandEncoderProps} from '@luma.gl/core';
+import type {
+  CopyBufferToBufferOptions,
+  CopyBufferToTextureOptions,
+  CopyTextureToBufferOptions,
+  CopyTextureToTextureOptions,
+  QuerySet
+} from '@luma.gl/core';
+import type {NullDevice} from '../null-device';
+
+export class NullCommandEncoder extends CommandEncoder {
+  device: NullDevice;
+
+  constructor(device: NullDevice, props: CommandEncoderProps) {
+    super(device, props);
+    this.device = device;
+  }
+
+  finish(): void {}
+
+  copyBufferToBuffer(options: CopyBufferToBufferOptions): void {}
+
+  copyBufferToTexture(options: CopyBufferToTextureOptions) {}
+
+  copyTextureToBuffer(options: CopyTextureToBufferOptions): void {}
+
+  copyTextureToTexture(options: CopyTextureToTextureOptions): void {}
+
+  pushDebugGroup(groupLabel: string): void {}
+  popDebugGroup() {}
+
+  insertDebugMarker(markerLabel: string): void {}
+  resolveQuerySet(querySet: QuerySet): void {}
+}

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

@@ -0,0 +1,16 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {FramebufferProps} from '@luma.gl/core';
+import {Framebuffer} from '@luma.gl/core';
+import type {NullDevice} from '../null-device';
+
+export class NullFramebuffer extends Framebuffer {
+  device: NullDevice;
+
+  constructor(device: NullDevice, props: FramebufferProps) {
+    super(device, props);
+    this.device = device;
+  }
+}

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

@@ -0,0 +1,15 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {QuerySet, QuerySetProps} from '@luma.gl/core';
+import {NullDevice} from '../null-device';
+
+export class NullQuerySet extends QuerySet {
+  device: NullDevice;
+
+  constructor(device: NullDevice, props: QuerySetProps) {
+    super(device, props);
+    this.device = device;
+  }
+}

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

@@ -0,0 +1,26 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {RenderPass, RenderPassProps, RenderPassParameters} from '@luma.gl/core';
+import {NullDevice} from '../null-device';
+
+export class NullRenderPass extends RenderPass {
+  readonly device: NullDevice;
+
+  constructor(device: NullDevice, props: RenderPassProps) {
+    super(device, props);
+    this.device = device;
+  }
+
+  end(): void {}
+
+  pushDebugGroup(groupLabel: string): void {}
+  popDebugGroup(): void {}
+  insertDebugMarker(markerLabel: string): void {}
+
+  setParameters(parameters: RenderPassParameters = {}): void {}
+
+  beginOcclusionQuery(queryIndex: number): void {}
+  endOcclusionQuery(): void {}
+}

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

@@ -0,0 +1,62 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {UniformValue, RenderPipelineProps, Binding} from '@luma.gl/core';
+import type {RenderPass, VertexArray} from '@luma.gl/core';
+import {RenderPipeline, cast} from '@luma.gl/core';
+
+import type {NullDevice} from '../null-device';
+import {NullShader} from './null-shader';
+
+/** Creates a new render pipeline */
+export class NullRenderPipeline extends RenderPipeline {
+  device: NullDevice;
+  vs: NullShader;
+  fs: NullShader;
+
+  uniforms: Record<string, UniformValue> = {};
+  bindings: Record<string, Binding> = {};
+
+  constructor(device: NullDevice, props: RenderPipelineProps) {
+    super(device, props);
+    this.device = device;
+
+    this.vs = cast<NullShader>(props.vs);
+    this.fs = cast<NullShader>(props.fs);
+
+    this.shaderLayout = props.shaderLayout || {
+      attributes: [],
+      bindings: [],
+      uniforms: []
+    };
+  }
+
+  setBindings(bindings: Record<string, Binding>): void {
+    Object.assign(this.bindings, bindings);
+  }
+
+  override setUniformsWebGL(uniforms: Record<string, UniformValue>): void {
+    Object.assign(this.uniforms, uniforms);
+  }
+
+  draw(options: {
+    renderPass: RenderPass;
+    vertexArray: VertexArray;
+    vertexCount?: number;
+    instanceCount?: number;
+  }): boolean {
+    const {renderPass, vertexArray} = options;
+
+    // const isIndexed: boolean = Boolean(vertexArray.indexBuffer);
+    // const isInstanced: boolean = Number(instanceCount) > 0;
+
+    vertexArray.bindBeforeRender(renderPass);
+
+    // TODO - verify buffer size
+
+    vertexArray.unbindAfterRender(renderPass);
+
+    return true;
+  }
+}

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

@@ -0,0 +1,15 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Sampler, SamplerProps} from '@luma.gl/core';
+import type {NullDevice} from '../null-device';
+
+export class NullSampler extends Sampler {
+  readonly device: NullDevice;
+
+  constructor(device: NullDevice, props: SamplerProps) {
+    super(device, props);
+    this.device = device;
+  }
+}

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

@@ -0,0 +1,19 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Shader, ShaderProps, CompilerMessage} from '@luma.gl/core';
+import {NullDevice} from '../null-device';
+
+export class NullShader extends Shader {
+  readonly device: NullDevice;
+
+  constructor(device: NullDevice, props: ShaderProps) {
+    super(device, props);
+    this.device = device;
+  }
+
+  async getCompilationInfo(): Promise<readonly CompilerMessage[]> {
+    return [];
+  }
+}

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

@@ -0,0 +1,21 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TextureViewProps} from '@luma.gl/core';
+import {TextureView, Texture} from '@luma.gl/core';
+
+import type {NullDevice} from '../null-device';
+import type {NullTexture} from './null-texture';
+
+export class NullTextureView extends TextureView {
+  readonly device: NullDevice;
+  readonly texture: NullTexture;
+
+  constructor(device: NullDevice, props: TextureViewProps & {texture: NullTexture}) {
+    super(device, {...Texture.defaultProps, ...props});
+
+    this.device = device;
+    this.texture = props.texture;
+  }
+}

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

@@ -0,0 +1,121 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TextureProps, Sampler, SamplerProps, TextureViewProps} from '@luma.gl/core';
+import {Texture, assert, loadImage} from '@luma.gl/core';
+import {NullDevice} from '../null-device';
+import {NullSampler} from './null-sampler';
+import {NullTextureView} from './null-texture-view';
+
+export class NullTexture extends Texture<TextureProps> {
+  readonly device: NullDevice;
+
+  sampler!: NullSampler;
+  view!: NullTextureView;
+
+  constructor(device: NullDevice, props: TextureProps) {
+    super(device, props);
+
+    this.device = device;
+
+    // Signature: new Texture2D(gl, {data: url})
+    if (typeof this.props?.data === 'string') {
+      Object.assign(this.props, {data: loadImage(this.props.data)});
+    }
+
+    this.initialize(this.props);
+
+    Object.seal(this);
+  }
+
+  override destroy(): void {
+    if (!this.destroyed) {
+      super.destroy();
+      this.trackDeallocatedMemory('Texture');
+    }
+  }
+
+  createView(props: TextureViewProps): NullTextureView {
+    return new NullTextureView(this.device, {...props, texture: this});
+  }
+
+  initialize(props: TextureProps = {}): this {
+    const data = props.data;
+
+    if (data instanceof Promise) {
+      data.then(resolvedImageData =>
+        this.initialize(
+          Object.assign({}, props, {
+            pixels: resolvedImageData,
+            data: resolvedImageData
+          })
+        )
+      );
+      return this;
+    }
+
+    this.setImageData(props);
+
+    this.setSampler(props.sampler);
+
+    this.view = new NullTextureView(this.device, {
+      ...props,
+      texture: this,
+      mipLevelCount: 1,
+      arrayLayerCount: 1
+    });
+
+    return this;
+  }
+
+  setSampler(sampler: Sampler | SamplerProps = {}): this {
+    if (sampler instanceof NullSampler) {
+      this.sampler = sampler;
+    } else {
+      this.sampler = new NullSampler(this.device, sampler);
+    }
+
+    return this;
+  }
+
+  resize(options: {height: number; width: number; mipmaps?: boolean}): this {
+    const {height, width, mipmaps = false} = options;
+    if (width !== this.width || height !== this.height) {
+      return this.initialize({
+        width,
+        height,
+        mipmaps
+      });
+    }
+    return this;
+  }
+
+  setImageData(options: {data?: any; width?: number; height?: number}) {
+    this.trackDeallocatedMemory('Texture');
+
+    const {data} = options;
+
+    if (data && data.byteLength) {
+      this.trackAllocatedMemory(data.byteLength, 'Texture');
+    } else {
+      const bytesPerPixel = 4;
+      this.trackAllocatedMemory(this.width * this.height * bytesPerPixel, 'Texture');
+    }
+
+    const width = options.width ?? (data as ImageBitmap).width;
+    const height = options.height ?? (data as ImageBitmap).height;
+
+    this.width = width;
+    this.height = height;
+
+    return this;
+  }
+
+  setSubImageData(options: {data: any; width?: number; height?: number; x?: number; y?: number}) {
+    const {data, x = 0, y = 0} = options;
+    const width = options.width ?? (data as ImageBitmap).width;
+    const height = options.height ?? (data as ImageBitmap).height;
+    assert(width + x <= this.width && height + y <= this.height);
+  }
+}

package/src/null-device/resources/null-transform-feedback.ts

@@ -0,0 +1,46 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {PrimitiveTopology, ShaderLayout, TransformFeedbackProps} from '@luma.gl/core';
+import {TransformFeedback, Buffer, BufferRange} from '@luma.gl/core';
+import type {NullDevice} from '../null-device';
+
+export class NullTransformFeedback extends TransformFeedback {
+  readonly device: NullDevice;
+
+  readonly layout: ShaderLayout;
+  buffers: Record<string, Buffer | BufferRange> = {};
+
+  constructor(device: NullDevice, props: TransformFeedbackProps) {
+    super(device, props);
+    this.device = device;
+    this.layout = this.props.layout;
+
+    if (props.buffers) {
+      this.setBuffers(props.buffers);
+    }
+
+    Object.seal(this);
+  }
+
+  begin(topology: PrimitiveTopology = 'point-list'): void {}
+
+  end(): void {}
+
+  setBuffers(buffers: Record<string, Buffer | BufferRange>): void {
+    this.buffers = {};
+
+    for (const bufferName in buffers) {
+      this.setBuffer(bufferName, buffers[bufferName]);
+    }
+  }
+
+  setBuffer(locationOrName: string | number, bufferOrRange: Buffer | BufferRange): void {
+    this.buffers[locationOrName] = bufferOrRange;
+  }
+
+  getBuffer(locationOrName: string | number): Buffer | BufferRange | null {
+    return this.buffers[locationOrName] || null;
+  }
+}

package/src/null-device/resources/null-vertex-array.ts

@@ -0,0 +1,37 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Buffer, VertexArrayProps, TypedArray} from '@luma.gl/core';
+import {VertexArray} from '@luma.gl/core';
+
+import type {NullDevice} from '../null-device';
+
+export class NullVertexArray extends VertexArray {
+  device: NullDevice;
+
+  // Create a VertexArray
+  constructor(device: NullDevice, props: VertexArrayProps) {
+    super(device, props);
+    this.device = device;
+  }
+
+  setIndexBuffer(indexBuffer: Buffer | null): void {
+    this.indexBuffer = indexBuffer;
+  }
+
+  /** Set a location in vertex attributes array to a buffer, enables the location, sets divisor */
+  setBuffer(location: number, attributeBuffer: Buffer): void {
+    const attributeInfo = this.attributeInfos[location];
+    if (!attributeInfo) {
+      throw new Error(`Unknown attribute location ${location}`);
+    }
+    this.attributes[location] = attributeBuffer;
+  }
+
+  bindBeforeRender(): void {}
+
+  unbindAfterRender(): void {}
+
+  override setConstantWebGL(location: number, value: TypedArray | null): void {}
+}

package/src/performance-test-runner.ts

@@ -1,4 +1,5 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 import {Stats, Stat} from '@probe.gl/stats';

package/src/register-devices.ts

@@ -1,4 +1,5 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 import {luma} from '@luma.gl/core';