@luma.gl/webgpu 9.2.5 → 9.3.0-alpha.10

package/src/adapter/resources/webgpu-texture-view.ts

@@ -5,6 +5,7 @@
 import {TextureView, TextureViewProps} from '@luma.gl/core';
 import type {WebGPUDevice} from '../webgpu-device';
 import type {WebGPUTexture} from './webgpu-texture';
+import {getCpuHotspotProfiler, getTimestamp} from '../helpers/cpu-hotspot-profiler';
 
 /*
   // type = sampler
@@ -39,17 +40,15 @@ export class WebGPUTextureView extends TextureView {
     this.texture = props.texture;
 
     this.device.pushErrorScope('validation');
-    this.handle =
-      // props.handle ||
-      this.texture.handle.createView({
-        format: (this.props.format || this.texture.format) as GPUTextureFormat,
-        dimension: this.props.dimension || this.texture.dimension,
-        aspect: this.props.aspect,
-        baseMipLevel: this.props.baseMipLevel,
-        mipLevelCount: this.props.mipLevelCount,
-        baseArrayLayer: this.props.baseArrayLayer,
-        arrayLayerCount: this.props.arrayLayerCount
-      });
+    this.handle = this.texture.handle.createView({
+      format: (this.props.format || this.texture.format) as GPUTextureFormat,
+      dimension: this.props.dimension || this.texture.dimension,
+      aspect: this.props.aspect,
+      baseMipLevel: this.props.baseMipLevel,
+      mipLevelCount: this.props.mipLevelCount,
+      baseArrayLayer: this.props.baseArrayLayer,
+      arrayLayerCount: this.props.arrayLayerCount
+    });
     this.device.popErrorScope((error: GPUError) => {
       this.device.reportError(new Error(`TextureView constructor: ${error.message}`), this)();
       this.device.debug();
@@ -59,9 +58,50 @@ export class WebGPUTextureView extends TextureView {
   }
 
   override destroy(): void {
+    if (this.destroyed) {
+      return;
+    }
+
+    this.destroyResource();
     // GPUTextureView does not have a destroy method
     // this.handle.destroy();
     // @ts-expect-error readonly
     this.handle = null;
   }
+
+  /**
+   * Internal-only hook for the cached CanvasContext/PresentationContext swapchain path.
+   * Rebuilds the default view when the per-frame canvas texture handle changes, without
+   * replacing the long-lived luma.gl wrapper object.
+   */
+  _reinitialize(texture: WebGPUTexture): void {
+    // @ts-expect-error readonly
+    this.texture = texture;
+
+    const profiler = getCpuHotspotProfiler(this.device);
+    this.device.pushErrorScope('validation');
+    const createViewStartTime = profiler ? getTimestamp() : 0;
+    const handle = this.texture.handle.createView({
+      format: (this.props.format || this.texture.format) as GPUTextureFormat,
+      dimension: this.props.dimension || this.texture.dimension,
+      aspect: this.props.aspect,
+      baseMipLevel: this.props.baseMipLevel,
+      mipLevelCount: this.props.mipLevelCount,
+      baseArrayLayer: this.props.baseArrayLayer,
+      arrayLayerCount: this.props.arrayLayerCount
+    });
+    if (profiler) {
+      profiler.textureViewReinitializeCount = (profiler.textureViewReinitializeCount || 0) + 1;
+      profiler.textureViewReinitializeTimeMs =
+        (profiler.textureViewReinitializeTimeMs || 0) + (getTimestamp() - createViewStartTime);
+    }
+    this.device.popErrorScope((error: GPUError) => {
+      this.device.reportError(new Error(`TextureView constructor: ${error.message}`), this)();
+      this.device.debug();
+    });
+
+    handle.label = this.props.id;
+    // @ts-expect-error readonly
+    this.handle = handle;
+  }
 }

package/src/adapter/resources/webgpu-texture.ts

@@ -1,30 +1,43 @@
 // luma.gl, MIT license
-import type {
-  TextureProps,
-  TextureViewProps,
-  CopyExternalImageOptions,
-  CopyImageDataOptions,
-  SamplerProps
+import {
+  type TextureProps,
+  type TextureViewProps,
+  type CopyExternalImageOptions,
+  type TextureReadOptions,
+  type TextureWriteOptions,
+  type SamplerProps,
+  Buffer,
+  Texture,
+  log,
+  textureFormatDecoder
 } from '@luma.gl/core';
-import {Texture, log} from '@luma.gl/core';
 
 import {getWebGPUTextureFormat} from '../helpers/convert-texture-format';
 import type {WebGPUDevice} from '../webgpu-device';
 import {WebGPUSampler} from './webgpu-sampler';
 import {WebGPUTextureView} from './webgpu-texture-view';
+import {WebGPUBuffer} from './webgpu-buffer';
 
+/** WebGPU implementation of the luma.gl core Texture resource */
 export class WebGPUTexture extends Texture {
   readonly device: WebGPUDevice;
   readonly handle: GPUTexture;
   sampler: WebGPUSampler;
   view: WebGPUTextureView;
+  private _allocatedByteLength: number = 0;
 
   constructor(device: WebGPUDevice, props: TextureProps) {
-    super(device, props);
+    // WebGPU buffer copies use 256-byte row alignment. queue.writeTexture() can use tightly packed rows.
+    super(device, props, {byteAlignment: 256});
     this.device = device;
 
-    if (this.dimension === 'cube') {
-      this.depth = 6;
+    if (props.sampler instanceof WebGPUSampler) {
+      this.sampler = props.sampler;
+    } else if (props.sampler === undefined) {
+      this.sampler = this.device.getDefaultSampler();
+    } else {
+      this.sampler = new WebGPUSampler(this.device, (props.sampler as SamplerProps) || {});
+      this.attachResource(this.sampler);
     }
 
     this.device.pushErrorScope('out-of-memory');
@@ -54,19 +67,14 @@ export class WebGPUTexture extends Texture {
       this.device.debug();
     });
 
-    // Update props if external handle was supplied - used mainly by CanvasContext.getDefaultFramebuffer()
-    // TODO - Read all properties directly from the supplied handle?
     if (this.props.handle) {
       this.handle.label ||= this.id;
+      // @ts-expect-error readonly
       this.width = this.handle.width;
+      // @ts-expect-error readonly
       this.height = this.handle.height;
     }
 
-    this.sampler =
-      props.sampler instanceof WebGPUSampler
-        ? props.sampler
-        : new WebGPUSampler(this.device, (props.sampler as SamplerProps) || {});
-
     this.view = new WebGPUTextureView(this.device, {
       ...this.props,
       texture: this,
@@ -74,14 +82,34 @@ export class WebGPUTexture extends Texture {
       // Note: arrayLayerCount controls the view of array textures, but does not apply to 3d texture depths
       arrayLayerCount: this.dimension !== '3d' ? this.depth : 1
     });
+    this.attachResource(this.view);
 
     // Set initial data
     // Texture base class strips out the data prop from this.props, so we need to handle it here
     this._initializeData(props.data);
+
+    this._allocatedByteLength = this.getAllocatedByteLength();
+
+    if (!this.props.handle) {
+      this.trackAllocatedMemory(this._allocatedByteLength, 'Texture');
+    } else {
+      this.trackReferencedMemory(this._allocatedByteLength, 'Texture');
+    }
   }
 
   override destroy(): void {
-    this.handle?.destroy();
+    if (this.destroyed) {
+      return;
+    }
+
+    if (!this.props.handle && this.handle) {
+      this.trackDeallocatedMemory('Texture');
+      this.handle.destroy();
+    } else if (this.handle) {
+      this.trackDeallocatedReferencedMemory('Texture');
+    }
+
+    this.destroyResource();
     // @ts-expect-error readonly
     this.handle = null;
   }
@@ -90,37 +118,6 @@ export class WebGPUTexture extends Texture {
     return new WebGPUTextureView(this.device, {...props, texture: this});
   }
 
-  copyImageData(options_: CopyImageDataOptions): void {
-    const {width, height, depth} = this;
-    const options = this._normalizeCopyImageDataOptions(options_);
-    this.device.pushErrorScope('validation');
-    this.device.handle.queue.writeTexture(
-      // destination: GPUImageCopyTexture
-      {
-        // texture subresource
-        texture: this.handle,
-        mipLevel: options.mipLevel,
-        aspect: options.aspect,
-        // origin to write to
-        origin: [options.x, options.y, options.z]
-      },
-      // data
-      options.data,
-      // dataLayout: GPUImageDataLayout
-      {
-        offset: options.byteOffset,
-        bytesPerRow: options.bytesPerRow,
-        rowsPerImage: options.rowsPerImage
-      },
-      // size: GPUExtent3D - extents of the content to write
-      [width, height, depth]
-    );
-    this.device.popErrorScope((error: GPUError) => {
-      this.device.reportError(new Error(`copyImageData: ${error.message}`), this)();
-      this.device.debug();
-    });
-  }
-
   copyExternalImage(options_: CopyExternalImageOptions): {width: number; height: number} {
     const options = this._normalizeCopyExternalImageOptions(options_);
 
@@ -130,19 +127,19 @@ export class WebGPUTexture extends Texture {
       {
         source: options.image,
         origin: [options.sourceX, options.sourceY],
-        flipY: options.flipY
+        flipY: false // options.flipY
       },
       // destination: GPUImageCopyTextureTagged
       {
         texture: this.handle,
-        origin: [options.x, options.y, 0], // options.depth],
+        origin: [options.x, options.y, options.z],
         mipLevel: options.mipLevel,
         aspect: options.aspect,
         colorSpace: options.colorSpace,
         premultipliedAlpha: options.premultipliedAlpha
       },
       // copySize: GPUExtent3D
-      [options.width, options.height, 1]
+      [options.width, options.height, options.depth] // depth is always 1 for 2D textures
     );
     this.device.popErrorScope((error: GPUError) => {
       this.device.reportError(new Error(`copyExternalImage: ${error.message}`), this)();
@@ -157,72 +154,255 @@ export class WebGPUTexture extends Texture {
     log.warn(`${this}: generateMipmaps not supported in WebGPU`)();
   }
 
-  // WebGPU specific
+  getImageDataLayout(options: TextureReadOptions): {
+    byteLength: number;
+    bytesPerRow: number;
+    rowsPerImage: number;
+  } {
+    return {
+      byteLength: 0,
+      bytesPerRow: 0,
+      rowsPerImage: 0
+    };
+  }
 
-  /*
-  async readPixels() {
-    const readbackBuffer = device.createBuffer({
-        usage: Buffer.COPY_DST | Buffer.MAP_READ,
-        size: 4 * textureWidth * textureHeight,
-    });
+  override readBuffer(
+    options: TextureReadOptions & {byteOffset?: number} = {},
+    buffer?: Buffer
+  ): Buffer {
+    if (!buffer) {
+      throw new Error(`${this} readBuffer requires a destination buffer`);
+    }
+    const {x, y, z, width, height, depthOrArrayLayers, mipLevel, aspect} =
+      this._getSupportedColorReadOptions(options);
+    const byteOffset = options.byteOffset ?? 0;
+
+    const layout = this.computeMemoryLayout({width, height, depthOrArrayLayers, mipLevel});
+
+    const {byteLength} = layout;
 
-    // Copy data from the texture to the buffer.
-    const encoder = device.createCommandEncoder();
-    encoder.copyTextureToBuffer(
-        { texture },
-        { buffer, rowPitch: textureWidth * 4 },
-        [textureWidth, textureHeight],
+    if (buffer.byteLength < byteOffset + byteLength) {
+      throw new Error(
+        `${this} readBuffer target is too small (${buffer.byteLength} < ${byteOffset + byteLength})`
+      );
+    }
+
+    const gpuDevice = this.device.handle;
+    this.device.pushErrorScope('validation');
+    const commandEncoder = gpuDevice.createCommandEncoder();
+    this.copyToBuffer(
+      commandEncoder,
+      {x, y, z, width, height, depthOrArrayLayers, mipLevel, aspect, byteOffset},
+      buffer
     );
-    device.submit([encoder.finish()]);
 
-    // Get the data on the CPU.
-    await buffer.mapAndReadAsync(GPUMapMode.READ);
-    saveScreenshot(buffer.getMappedRange());
-    buffer.unmap();
-  }
+    const commandBuffer = commandEncoder.finish();
+    this.device.handle.queue.submit([commandBuffer]);
+    this.device.popErrorScope((error: GPUError) => {
+      this.device.reportError(new Error(`${this} readBuffer: ${error.message}`), this)();
+      this.device.debug();
+    });
 
-  setImageData(imageData, usage): this {
-    let data = null;
+    return buffer;
+  }
 
-    const bytesPerRow = Math.ceil((img.width * 4) / 256) * 256;
-    if (bytesPerRow == img.width * 4) {
-      data = imageData.data;
-    } else {
-      data = new Uint8Array(bytesPerRow * img.height);
-      let imagePixelIndex = 0;
-      for (let y = 0; y < img.height; ++y) {
-        for (let x = 0; x < img.width; ++x) {
-          const i = x * 4 + y * bytesPerRow;
-          data[i] = imageData.data[imagePixelIndex];
-          data[i + 1] = imageData.data[imagePixelIndex + 1];
-          data[i + 2] = imageData.data[imagePixelIndex + 2];
-          data[i + 3] = imageData.data[imagePixelIndex + 3];
-          imagePixelIndex += 4;
-        }
-      }
-    }
-    return this;
+  override async readDataAsync(options: TextureReadOptions = {}): Promise<ArrayBuffer> {
+    throw new Error(
+      `${this} readDataAsync is deprecated; use readBuffer() with an explicit destination buffer or DynamicTexture.readAsync()`
+    );
   }
 
-  setBuffer(textureDataBuffer, {bytesPerRow}): this {
-    const commandEncoder = this.device.handle.createCommandEncoder();
-    commandEncoder.copyBufferToTexture(
+  copyToBuffer(
+    commandEncoder: GPUCommandEncoder,
+    options: TextureReadOptions & {
+      byteOffset?: number;
+      bytesPerRow?: number;
+      rowsPerImage?: number;
+    } = {},
+    buffer: Buffer
+  ): void {
+    const {
+      byteOffset = 0,
+      bytesPerRow: requestedBytesPerRow,
+      rowsPerImage: requestedRowsPerImage,
+      ...textureReadOptions
+    } = options;
+    const {x, y, z, width, height, depthOrArrayLayers, mipLevel, aspect} =
+      this._getSupportedColorReadOptions(textureReadOptions);
+    const layout = this.computeMemoryLayout({width, height, depthOrArrayLayers, mipLevel});
+    const effectiveBytesPerRow = requestedBytesPerRow ?? layout.bytesPerRow;
+    const effectiveRowsPerImage = requestedRowsPerImage ?? layout.rowsPerImage;
+    const webgpuBuffer = buffer as WebGPUBuffer;
+
+    commandEncoder.copyTextureToBuffer(
       {
-        buffer: textureDataBuffer,
-        bytesPerRow
+        texture: this.handle,
+        origin: {x, y, z},
+        mipLevel,
+        aspect
       },
       {
-        texture: this.handle
+        buffer: webgpuBuffer.handle,
+        offset: byteOffset,
+        bytesPerRow: effectiveBytesPerRow,
+        rowsPerImage: effectiveRowsPerImage
       },
       {
         width,
         height,
-        depth
+        depthOrArrayLayers
       }
     );
+  }
+
+  override writeBuffer(buffer: Buffer, options_: TextureWriteOptions = {}) {
+    const options = this._normalizeTextureWriteOptions(options_);
+    const {
+      x,
+      y,
+      z,
+      width,
+      height,
+      depthOrArrayLayers,
+      mipLevel,
+      aspect,
+      byteOffset,
+      bytesPerRow,
+      rowsPerImage
+    } = options;
 
-    this.device.handle.defaultQueue.submit([commandEncoder.finish()]);
-    return this;
+    const gpuDevice = this.device.handle;
+
+    this.device.pushErrorScope('validation');
+    const commandEncoder = gpuDevice.createCommandEncoder();
+    commandEncoder.copyBufferToTexture(
+      {
+        buffer: buffer.handle as GPUBuffer,
+        offset: byteOffset,
+        bytesPerRow,
+        rowsPerImage
+      },
+      {
+        texture: this.handle,
+        origin: {x, y, z},
+        mipLevel,
+        aspect
+      },
+      {width, height, depthOrArrayLayers}
+    );
+    const commandBuffer = commandEncoder.finish();
+    this.device.handle.queue.submit([commandBuffer]);
+    this.device.popErrorScope((error: GPUError) => {
+      this.device.reportError(new Error(`${this} writeBuffer: ${error.message}`), this)();
+      this.device.debug();
+    });
+  }
+
+  override writeData(
+    data: ArrayBuffer | SharedArrayBuffer | ArrayBufferView,
+    options_: TextureWriteOptions = {}
+  ): void {
+    const device = this.device;
+    const options = this._normalizeTextureWriteOptions(options_);
+    const {x, y, z, width, height, depthOrArrayLayers, mipLevel, aspect, byteOffset} = options;
+    const source = data as GPUAllowSharedBufferSource;
+    const formatInfo = this.device.getTextureFormatInfo(this.format);
+    // queue.writeTexture() defaults to tightly packed rows, unlike WebGPU buffer copy paths.
+    const packedSourceLayout = textureFormatDecoder.computeMemoryLayout({
+      format: this.format,
+      width,
+      height,
+      depth: depthOrArrayLayers,
+      byteAlignment: 1
+    });
+    const bytesPerRow = options_.bytesPerRow ?? packedSourceLayout.bytesPerRow;
+    const rowsPerImage = options_.rowsPerImage ?? packedSourceLayout.rowsPerImage;
+    let copyWidth = width;
+    let copyHeight = height;
+
+    if (formatInfo.compressed) {
+      const blockWidth = formatInfo.blockWidth || 1;
+      const blockHeight = formatInfo.blockHeight || 1;
+      copyWidth = Math.ceil(width / blockWidth) * blockWidth;
+      copyHeight = Math.ceil(height / blockHeight) * blockHeight;
+    }
+
+    this.device.pushErrorScope('validation');
+    device.handle.queue.writeTexture(
+      {
+        texture: this.handle,
+        mipLevel,
+        aspect,
+        origin: {x, y, z}
+      },
+      source,
+      {
+        offset: byteOffset,
+        bytesPerRow,
+        rowsPerImage
+      },
+      {width: copyWidth, height: copyHeight, depthOrArrayLayers}
+    );
+    this.device.popErrorScope((error: GPUError) => {
+      this.device.reportError(new Error(`${this} writeData: ${error.message}`), this)();
+      this.device.debug();
+    });
+  }
+
+  /**
+   * Internal-only hook for the cached CanvasContext/PresentationContext swapchain path.
+   * Rebinds this handle-backed texture wrapper to the current per-frame canvas texture
+   * without allocating a new luma.gl Texture or TextureView wrapper.
+   */
+  _reinitialize(handle: GPUTexture, props?: Partial<TextureProps>): void {
+    const nextWidth = props?.width ?? handle.width ?? this.width;
+    const nextHeight = props?.height ?? handle.height ?? this.height;
+    const nextDepth = props?.depth ?? this.depth;
+    const nextFormat = props?.format ?? this.format;
+    const allocationMayHaveChanged =
+      nextWidth !== this.width ||
+      nextHeight !== this.height ||
+      nextDepth !== this.depth ||
+      nextFormat !== this.format;
+    handle.label ||= this.id;
+
+    // @ts-expect-error readonly
+    this.handle = handle;
+    // @ts-expect-error readonly
+    this.width = nextWidth;
+    // @ts-expect-error readonly
+    this.height = nextHeight;
+
+    if (props?.depth !== undefined) {
+      // @ts-expect-error readonly
+      this.depth = nextDepth;
+    }
+    if (props?.format !== undefined) {
+      // @ts-expect-error readonly
+      this.format = nextFormat;
+    }
+
+    this.props.handle = handle;
+    if (props?.width !== undefined) {
+      this.props.width = props.width;
+    }
+    if (props?.height !== undefined) {
+      this.props.height = props.height;
+    }
+    if (props?.depth !== undefined) {
+      this.props.depth = props.depth;
+    }
+    if (props?.format !== undefined) {
+      this.props.format = props.format;
+    }
+
+    if (allocationMayHaveChanged) {
+      const nextAllocation = this.getAllocatedByteLength();
+      if (nextAllocation !== this._allocatedByteLength) {
+        this._allocatedByteLength = nextAllocation;
+        this.trackReferencedMemory(nextAllocation, 'Texture');
+      }
+    }
+    this.view._reinitialize(this);
   }
-  */
 }

package/src/adapter/resources/webgpu-vertex-array.ts

@@ -14,7 +14,7 @@ import {WebGPURenderPass} from './webgpu-render-pass';
 /** VertexArrayObject wrapper */
 export class WebGPUVertexArray extends VertexArray {
   override get [Symbol.toStringTag](): string {
-    return 'WebGPUVertexArray';
+    return 'VertexArray';
   }
 
   readonly device: WebGPUDevice;

package/src/adapter/webgpu-adapter.ts

@@ -35,62 +35,60 @@ export class WebGPUAdapter extends Adapter {
       throw new Error('WebGPU not available. Recent Chrome browsers should work.');
     }
 
-    log.groupCollapsed(1, 'WebGPUDevice created')();
-    try {
-      const adapter = await navigator.gpu.requestAdapter({
-        powerPreference: 'high-performance'
-        // forceSoftware: false
-      });
+    const adapter = await navigator.gpu.requestAdapter({
+      powerPreference: 'high-performance'
+      // forceSoftware: false
+    });
 
-      if (!adapter) {
-        throw new Error('Failed to request WebGPU adapter');
-      }
+    if (!adapter) {
+      throw new Error('Failed to request WebGPU adapter');
+    }
 
-      //  Note: adapter.requestAdapterInfo() has been replaced with adapter.info. Fall back in case adapter.info is not available
-      const adapterInfo =
-        adapter.info ||
-        // @ts-ignore
-        (await adapter.requestAdapterInfo?.());
-      log.probe(2, 'Adapter available', adapterInfo)();
-
-      const requiredFeatures: GPUFeatureName[] = [];
-      const requiredLimits: Record<string, number> = {};
-
-      if (props._requestMaxLimits) {
-        // Require all features
-        requiredFeatures.push(...(Array.from(adapter.features) as GPUFeatureName[]));
-
-        // Require all limits
-        // Filter out chrome specific keys (avoid crash)
-        const limits = Object.keys(adapter.limits).filter(
-          key => !['minSubgroupSize', 'maxSubgroupSize'].includes(key)
-        );
-        for (const key of limits) {
-          const limit = key as keyof GPUSupportedLimits;
-          const value = adapter.limits[limit];
-          if (typeof value === 'number') {
-            requiredLimits[limit] = value;
-          }
+    //  Note: adapter.requestAdapterInfo() has been replaced with adapter.info. Fall back in case adapter.info is not available
+    const adapterInfo =
+      adapter.info ||
+      // @ts-ignore
+      (await adapter.requestAdapterInfo?.());
+    // log.probe(2, 'Adapter available', adapterInfo)();
+
+    const requiredFeatures: GPUFeatureName[] = [];
+    const requiredLimits: Record<string, number> = {};
+
+    if (props._requestMaxLimits) {
+      // Require all features
+      requiredFeatures.push(...(Array.from(adapter.features) as GPUFeatureName[]));
+
+      // Require all limits
+      // Filter out chrome specific keys (avoid crash)
+      const limits = Object.keys(adapter.limits).filter(
+        key => !['minSubgroupSize', 'maxSubgroupSize'].includes(key)
+      );
+      for (const key of limits) {
+        const limit = key as keyof GPUSupportedLimits;
+        const value = adapter.limits[limit];
+        if (typeof value === 'number') {
+          requiredLimits[limit] = value;
         }
       }
+    }
 
-      const gpuDevice = await adapter.requestDevice({
-        requiredFeatures,
-        requiredLimits
-      });
+    const gpuDevice = await adapter.requestDevice({
+      requiredFeatures,
+      requiredLimits
+    });
 
-      log.probe(1, 'GPUDevice available')();
+    // log.probe(1, 'GPUDevice available')();
 
-      const {WebGPUDevice} = await import('./webgpu-device');
+    const {WebGPUDevice} = await import('./webgpu-device');
 
+    log.groupCollapsed(1, 'WebGPUDevice created')();
+    try {
       const device = new WebGPUDevice(props, gpuDevice, adapter, adapterInfo);
-
       log.probe(
         1,
         'Device created. For more info, set chrome://flags/#enable-webgpu-developer-features'
       )();
       log.table(1, device.info)();
-
       return device;
     } finally {
       log.groupEnd(1)();