27877741225

Committed 20 Jun 2026 04:53PM UTC coverage: 70.762% (+0.03%) from 70.733%

Build # 27877741225

Build Type

push

github

Committed by

web-flow

Commit Message

feat(experimental): HTMLTexture via HTML-in-Canvas (#2674)

Coverage Stats

9977 of 15874 branches covered (62.85%)

Branch coverage included in aggregate %.

76 of 136 new or added lines in 8 files covered. (55.88%)

131 existing lines in 5 files now uncovered.

20249 of 26841 relevant lines covered (75.44%)

4021.12 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

76.8

/modules/webgpu/src/adapter/webgpu-device.ts

// luma.gl
// SPDX-License-Identifier: MIT
// Copyright (c) vis.gl contributors

// biome-ignore format: preserve layout
// / <reference types="@webgpu/types" />

import type {
  Bindings,
  ComputePipeline,
  ComputeShaderLayout,
  DeviceInfo,
  DeviceLimits,
  DeviceFeature,
  DeviceTextureFormatCapabilities,
  VertexFormat,
  CanvasContextProps,
  PresentationContextProps,
  PresentationContext,
  BufferProps,
  SamplerProps,
  ShaderProps,
  TextureProps,
  Texture,
  ExternalTextureProps,
  FramebufferProps,
  RenderPipelineProps,
  ComputePipelineProps,
  VertexArrayProps,
  TransformFeedback,
  TransformFeedbackProps,
  QuerySet,
  QuerySetProps,
  DeviceProps,
  CommandEncoderProps,
  CommandEncoder,
  PipelineLayoutProps,
  RenderPipeline,
  RenderBundleEncoderProps,
  ShaderLayout
} from '@luma.gl/core';
import {Buffer, Device, DeviceFeatures, isHTMLInCanvasSupported} from '@luma.gl/core';
import {WebGPUBuffer} from './resources/webgpu-buffer';
import {WebGPUTexture} from './resources/webgpu-texture';
import {WebGPUExternalTexture} from './resources/webgpu-external-texture';
import {WebGPUSampler, type WebGPUSamplerProps} from './resources/webgpu-sampler';
import {WebGPUShader} from './resources/webgpu-shader';
import {WebGPURenderPipeline} from './resources/webgpu-render-pipeline';
import {WebGPURenderBundleEncoder} from './resources/webgpu-render-bundle';
import {WebGPUFramebuffer} from './resources/webgpu-framebuffer';
import {WebGPUComputePipeline} from './resources/webgpu-compute-pipeline';
import {WebGPUVertexArray} from './resources/webgpu-vertex-array';

import {WebGPUCanvasContext} from './webgpu-canvas-context';
import {WebGPUPresentationContext} from './webgpu-presentation-context';
import {WebGPUCommandEncoder} from './resources/webgpu-command-encoder';
import {WebGPUCommandBuffer} from './resources/webgpu-command-buffer';
import {WebGPUQuerySet} from './resources/webgpu-query-set';
import {WebGPUPipelineLayout} from './resources/webgpu-pipeline-layout';
import {WebGPUFence} from './resources/webgpu-fence';

import {getShaderLayoutFromWGSL} from '../wgsl/get-shader-layout-wgsl';
import {generateMipmapsWebGPU} from './helpers/generate-mipmaps-webgpu';
import {getBindGroup} from './helpers/get-bind-group';
import {
  getCpuHotspotProfiler as getWebGPUCpuHotspotProfiler,
  getCpuHotspotSubmitReason as getWebGPUCpuHotspotSubmitReason,
  getTimestamp
} from './helpers/cpu-hotspot-profiler';

/** WebGPU Device implementation */
export class WebGPUDevice extends Device {
  /** The underlying WebGPU device */
  readonly handle: GPUDevice;
  /* The underlying WebGPU adapter */
  readonly adapter: GPUAdapter;
  /* The underlying WebGPU adapter's info */
  readonly adapterInfo: GPUAdapterInfo;

  /** type of this device */
  readonly type = 'webgpu';

  readonly preferredColorFormat = navigator.gpu.getPreferredCanvasFormat() as
    | 'rgba8unorm'
    | 'bgra8unorm';
  readonly preferredDepthFormat = 'depth24plus';

  readonly features: DeviceFeatures;
  readonly info: DeviceInfo;
  readonly limits: DeviceLimits;

  readonly lost: Promise<{reason: 'destroyed'; message: string}>;

  override canvasContext: WebGPUCanvasContext | null = null;

  private _isLost: boolean = false;
  private _defaultSampler: WebGPUSampler | null = null;
  commandEncoder: WebGPUCommandEncoder;

  override get [Symbol.toStringTag](): string {
    return 'WebGPUDevice';
  }

  override toString(): string {
    return `WebGPUDevice(${this.id})`;
  }

  constructor(
    props: DeviceProps,
    device: GPUDevice,
    adapter: GPUAdapter,
    adapterInfo: GPUAdapterInfo
  ) {
    super({...props, id: props.id || 'webgpu-device'});
    this.handle = device;
    this.adapter = adapter;
    this.adapterInfo = adapterInfo;

    this.info = this._getInfo();
    this.features = this._getFeatures();
    this.limits = getWebGPUDeviceLimits(this.handle.limits);

    // Listen for uncaptured WebGPU errors
    device.addEventListener('uncapturederror', (event: Event) => {
      event.preventDefault();
      // TODO is this the right way to make sure the error is an Error instance?
      const errorMessage =
        event instanceof GPUUncapturedErrorEvent ? event.error.message : 'Unknown WebGPU error';
      this.reportError(new Error(errorMessage), this)();
      this.debug();
    });

    // "Context" loss handling
    this.lost = this.handle.lost.then(lostInfo => {
      this._isLost = true;
      return {reason: 'destroyed', message: lostInfo.message};
    });

    // Note: WebGPU devices can be created without a canvas, for compute shader purposes
    const canvasContextProps = Device._getCanvasContextProps(props);
    if (canvasContextProps) {
      this.canvasContext = new WebGPUCanvasContext(this, this.adapter, canvasContextProps);
    }

    this.commandEncoder = this.createCommandEncoder({});
  }

  // TODO
  // Load the glslang module now so that it is available synchronously when compiling shaders
  // const {glsl = true} = props;
  // this.glslang = glsl && await loadGlslangModule();

  destroy(): void {
    this.commandEncoder?.destroy();
    this._defaultSampler?.destroy();
    this._defaultSampler = null;
    this.handle.destroy();
  }

  get isLost(): boolean {
    return this._isLost;
  }

  getShaderLayout(source: string) {
    return getShaderLayoutFromWGSL(source);
  }

  override isVertexFormatSupported(format: VertexFormat): boolean {
    const info = this.getVertexFormatInfo(format);
    return !info.webglOnly;
  }

  createBuffer(props: BufferProps | ArrayBuffer | ArrayBufferView): WebGPUBuffer {
    const newProps = this._normalizeBufferProps(props);
    return new WebGPUBuffer(this, newProps);
  }

  createTexture(props: TextureProps): WebGPUTexture {
    return new WebGPUTexture(this, props);
  }

  createExternalTexture(props: ExternalTextureProps): WebGPUExternalTexture {
    return new WebGPUExternalTexture(this, props);
  }

  createShader(props: ShaderProps): WebGPUShader {
    return new WebGPUShader(this, props);
  }

  createSampler(props: SamplerProps): WebGPUSampler {
    return new WebGPUSampler(this, props as WebGPUSamplerProps);
  }

  getDefaultSampler(): WebGPUSampler {
    this._defaultSampler ||= new WebGPUSampler(this, {
      id: `${this.id}-default-sampler`
    });
    return this._defaultSampler;
  }

  createRenderPipeline(props: RenderPipelineProps): WebGPURenderPipeline {
    return new WebGPURenderPipeline(this, props);
  }

  createFramebuffer(props: FramebufferProps): WebGPUFramebuffer {
    return new WebGPUFramebuffer(this, props);
  }

  createComputePipeline(props: ComputePipelineProps): WebGPUComputePipeline {
    return new WebGPUComputePipeline(this, props);
  }

  /** Creates an encoder for reusable WebGPU draw commands. */
  createRenderBundleEncoder(props: RenderBundleEncoderProps = {}): WebGPURenderBundleEncoder {
    return new WebGPURenderBundleEncoder(this, props);
  }

  createVertexArray(props: VertexArrayProps): WebGPUVertexArray {
    return new WebGPUVertexArray(this, props);
  }

  override createCommandEncoder(props?: CommandEncoderProps): WebGPUCommandEncoder {
    return new WebGPUCommandEncoder(this, props);
  }

  override writeBufferViaCommandEncoder(
    commandEncoder: CommandEncoder,
    destinationBuffer: Buffer,
    data: ArrayBufferLike | ArrayBufferView | SharedArrayBuffer,
    byteOffset: number = 0
  ): void {
    const webgpuCommandEncoder = commandEncoder as WebGPUCommandEncoder;
    const uploadData = ArrayBuffer.isView(data)
      ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
      : new Uint8Array(data);
    // WebGPU cannot encode CPU writes directly on a command encoder. Record the
    // upload as a staging-buffer copy so it stays ordered with the draw/dispatch
    // commands that will consume the destination buffer.
    const uploadBuffer = this.createBuffer({
      usage: Buffer.COPY_SRC,
      data: uploadData
    });

    webgpuCommandEncoder.trackTransientUploadBuffer(uploadBuffer);
    webgpuCommandEncoder.copyBufferToBuffer({
      sourceBuffer: uploadBuffer,
      destinationBuffer,
      destinationOffset: byteOffset,
      size: uploadData.byteLength
    });
  }

  // WebGPU specifics

  createTransformFeedback(props: TransformFeedbackProps): TransformFeedback {
    throw new Error('Transform feedback not supported in WebGPU');
  }

  override createQuerySet(props: QuerySetProps): QuerySet {
    return new WebGPUQuerySet(this, props);
  }

  override createFence(): WebGPUFence {
    return new WebGPUFence(this);
  }

  createCanvasContext(props: CanvasContextProps): WebGPUCanvasContext {
    return new WebGPUCanvasContext(this, this.adapter, props);
  }

  createPresentationContext(props?: PresentationContextProps): PresentationContext {
    return new WebGPUPresentationContext(this, props);
  }

  createPipelineLayout(props: PipelineLayoutProps): WebGPUPipelineLayout {
    return new WebGPUPipelineLayout(this, props);
  }

  override generateMipmapsWebGPU(texture: Texture): void {
    generateMipmapsWebGPU(this, texture);
  }

  override _createBindGroupLayoutWebGPU(
    pipeline: RenderPipeline | ComputePipeline,
    group: number
  ): GPUBindGroupLayout {
    return (pipeline as WebGPURenderPipeline | WebGPUComputePipeline).handle.getBindGroupLayout(
      group
    );
  }

  override _createBindGroupWebGPU(
    bindGroupLayout: unknown,
    shaderLayout: ShaderLayout | ComputeShaderLayout,
    bindings: Bindings,
    group: number,
    label?: string
  ): GPUBindGroup | null {
    if (Object.keys(bindings).length === 0) {
      return this.handle.createBindGroup({
        label,
        layout: bindGroupLayout as GPUBindGroupLayout,
        entries: []
      });
    }

    return getBindGroup(
      this,
      bindGroupLayout as GPUBindGroupLayout,
      shaderLayout,
      bindings,
      group,
      label
    );
  }

  submit(commandBuffer?: WebGPUCommandBuffer): void {
    let submittedCommandEncoder: WebGPUCommandEncoder | null = null;
    if (!commandBuffer) {
      ({submittedCommandEncoder, commandBuffer} = this._finalizeDefaultCommandEncoderForSubmit());
    }

    const profiler = getWebGPUCpuHotspotProfiler(this);
    const startTime = profiler ? getTimestamp() : 0;
    const submitReason = getWebGPUCpuHotspotSubmitReason(this);
    const transientUploadBuffers = commandBuffer.transientUploadBuffers;
    let didSubmit = false;
    try {
      this.pushErrorScope('validation');
      const queueSubmitStartTime = profiler ? getTimestamp() : 0;
      this.handle.queue.submit([commandBuffer.handle]);
      didSubmit = true;
      if (profiler) {
        profiler.queueSubmitCount = (profiler.queueSubmitCount || 0) + 1;
        profiler.queueSubmitTimeMs =
          (profiler.queueSubmitTimeMs || 0) + (getTimestamp() - queueSubmitStartTime);
      }
      this.popErrorScope((error: GPUError) => {
        this.reportError(new Error(`${this} command submission: ${error.message}`), this)();
        this.debug();
      });

      if (submittedCommandEncoder) {
        const submitResolveKickoffStartTime = profiler ? getTimestamp() : 0;
        scheduleMicrotask(() => {
          submittedCommandEncoder
            .resolveTimeProfilingQuerySet()
            .then(() => {
              this.commandEncoder._gpuTimeMs = submittedCommandEncoder._gpuTimeMs;
            })
            .catch(() => {});
        });
        if (profiler) {
          profiler.submitResolveKickoffCount = (profiler.submitResolveKickoffCount || 0) + 1;
          profiler.submitResolveKickoffTimeMs =
            (profiler.submitResolveKickoffTimeMs || 0) +
            (getTimestamp() - submitResolveKickoffStartTime);
        }
      }
    } finally {
      if (transientUploadBuffers.length) {
        if (didSubmit) {
          // The GPU may still be reading from the staging buffers after
          // queue.submit() returns, so defer destruction until the submitted
          // work has fully completed.
          this.handle.queue
            .onSubmittedWorkDone()
            .then(() => {
              for (const uploadBuffer of transientUploadBuffers) {
                uploadBuffer.destroy();
              }
            })
            .catch(() => {
              for (const uploadBuffer of transientUploadBuffers) {
                uploadBuffer.destroy();
              }
            });
        } else {
          for (const uploadBuffer of transientUploadBuffers) {
            uploadBuffer.destroy();
          }
        }
      }
      if (profiler) {
        profiler.submitCount = (profiler.submitCount || 0) + 1;
        profiler.submitTimeMs = (profiler.submitTimeMs || 0) + (getTimestamp() - startTime);
        const reasonCountKey =
          submitReason === 'query-readback' ? 'queryReadbackSubmitCount' : 'defaultSubmitCount';
        const reasonTimeKey =
          submitReason === 'query-readback' ? 'queryReadbackSubmitTimeMs' : 'defaultSubmitTimeMs';
        profiler[reasonCountKey] = (profiler[reasonCountKey] || 0) + 1;
        profiler[reasonTimeKey] = (profiler[reasonTimeKey] || 0) + (getTimestamp() - startTime);
      }
      const commandBufferDestroyStartTime = profiler ? getTimestamp() : 0;
      commandBuffer.destroy();
      if (profiler) {
        profiler.commandBufferDestroyCount = (profiler.commandBufferDestroyCount || 0) + 1;
        profiler.commandBufferDestroyTimeMs =
          (profiler.commandBufferDestroyTimeMs || 0) +
          (getTimestamp() - commandBufferDestroyStartTime);
      }
    }
  }

  private _finalizeDefaultCommandEncoderForSubmit(): {
    submittedCommandEncoder: WebGPUCommandEncoder;
    commandBuffer: WebGPUCommandBuffer;
  } {
    const submittedCommandEncoder = this.commandEncoder;
    if (
      submittedCommandEncoder.getTimeProfilingSlotCount() > 0 &&
      submittedCommandEncoder.getTimeProfilingQuerySet() instanceof WebGPUQuerySet
    ) {
      const querySet = submittedCommandEncoder.getTimeProfilingQuerySet() as WebGPUQuerySet;
      querySet._encodeResolveToReadBuffer(submittedCommandEncoder, {
        firstQuery: 0,
        queryCount: submittedCommandEncoder.getTimeProfilingSlotCount()
      });
    }

    const commandBuffer = submittedCommandEncoder.finish();
    this.commandEncoder.destroy();
    this.commandEncoder = this.createCommandEncoder({
      id: submittedCommandEncoder.props.id,
      timeProfilingQuerySet: submittedCommandEncoder.getTimeProfilingQuerySet()
    });

    return {submittedCommandEncoder, commandBuffer};
  }

  // WebGPU specific

  pushErrorScope(scope: 'validation' | 'out-of-memory'): void {
    if (!this.props.debug) {
      return;
    }
    const profiler = getWebGPUCpuHotspotProfiler(this);
    const startTime = profiler ? getTimestamp() : 0;
    this.handle.pushErrorScope(scope);
    if (profiler) {
      profiler.errorScopePushCount = (profiler.errorScopePushCount || 0) + 1;
      profiler.errorScopeTimeMs = (profiler.errorScopeTimeMs || 0) + (getTimestamp() - startTime);
    }
  }

  popErrorScope(handler: (error: GPUError) => void): void {
    if (!this.props.debug) {
      return;
    }
    const profiler = getWebGPUCpuHotspotProfiler(this);
    const startTime = profiler ? getTimestamp() : 0;
    this.handle
      .popErrorScope()
      .then((error: GPUError | null) => {
        if (error) {
          handler(error);
        }
      })
      .catch((error: unknown) => {
        if (this.shouldIgnoreDroppedInstanceError(error, 'popErrorScope')) {
          return;
        }

        const errorMessage = error instanceof Error ? error.message : String(error);
        this.reportError(new Error(`${this} popErrorScope failed: ${errorMessage}`), this)();
        this.debug();
      });
    if (profiler) {
      profiler.errorScopePopCount = (profiler.errorScopePopCount || 0) + 1;
      profiler.errorScopeTimeMs = (profiler.errorScopeTimeMs || 0) + (getTimestamp() - startTime);
    }
  }

  // PRIVATE METHODS

  protected _getInfo(): DeviceInfo {
    const [driver, driverVersion] = ((this.adapterInfo as any).driver || '').split(' Version ');

    // See https://developer.chrome.com/blog/new-in-webgpu-120#adapter_information_updates
    const vendor = this.adapterInfo.vendor || this.adapter.__brand || 'unknown';
    const renderer = driver || '';
    const version = driverVersion || '';
    const fallback = Boolean(
      (this.adapterInfo as any).isFallbackAdapter ??
        (this.adapter as any).isFallbackAdapter ??
        false
    );
    const softwareRenderer = /SwiftShader/i.test(
      `${vendor} ${renderer} ${this.adapterInfo.architecture || ''}`
    );

    const gpuArchitecture = this.adapterInfo.architecture || 'unknown';
    const gpu =
      identifyGPUVendor(vendor, renderer) ??
      (softwareRenderer || fallback ? 'software' : 'unknown');
    const gpuBackend = (this.adapterInfo as any).backend || 'unknown';
    const gpuType =
      ((this.adapterInfo as any).type || '').split(' ')[0].toLowerCase() ||
      (softwareRenderer || fallback ? 'cpu' : 'unknown');

    return {
      type: 'webgpu',
      vendor,
      renderer,
      version,
      gpu,
      gpuType,
      gpuBackend,
      gpuArchitecture,
      fallback,
      featureLevel: getWebGPUDeviceFeatureLevel(this.props.featureLevel),
      shadingLanguage: 'wgsl',
      shadingLanguageVersion: 100
    };
  }

  shouldIgnoreDroppedInstanceError(error: unknown, operation?: string): boolean {
    const errorMessage = error instanceof Error ? error.message : String(error);
    return (
      errorMessage.includes('Instance dropped') &&
      (!operation || errorMessage.includes(operation)) &&
      (this._isLost ||
        this.info.gpu === 'software' ||
        this.info.gpuType === 'cpu' ||
        Boolean(this.info.fallback))
    );
  }

  protected _getFeatures(): DeviceFeatures {
    // Initialize with actual WebGPU Features (note that unknown features may not be in DeviceFeature type)
    const features = new Set<DeviceFeature>(this.handle.features as Set<DeviceFeature>);
    // Fixups for pre-standard names: https://github.com/webgpu-native/webgpu-headers/issues/133
    // @ts-expect-error Chrome Canary v99
    if (features.has('depth-clamping')) {
      // @ts-expect-error Chrome Canary v99
      features.delete('depth-clamping');
      features.add('depth-clip-control');
    }

    // Some subsets of WebGPU extensions correspond to WebGL extensions
    if (features.has('texture-compression-bc')) {
      features.add('texture-compression-bc5-webgl');
    }

    if (this.handle.features.has('chromium-experimental-norm16-texture-formats')) {
      features.add('norm16-renderable-webgl');
    }

    if (this.handle.features.has('chromium-experimental-snorm16-texture-formats')) {
      features.add('snorm16-renderable-webgl');
    }

    const WEBGPU_ALWAYS_FEATURES: DeviceFeature[] = [
      'compilation-status-async-webgl',
      'float32-renderable-webgl',
      'float16-renderable-webgl',
      'norm16-renderable-webgl',
      'texture-filterable-anisotropic-webgl',
      'shader-noperspective-interpolation-webgl'
    ];

    for (const feature of WEBGPU_ALWAYS_FEATURES) {
      features.add(feature);
    }

    if (
      isHTMLInCanvasSupported() &&
      typeof (
        this.handle.queue as GPUQueue & {
          copyElementImageToTexture?: unknown;
        }
      ).copyElementImageToTexture === 'function'
    ) {
      features.add('html-in-canvas');
    }

    return new DeviceFeatures(Array.from(features), this.props._disabledFeatures);
  }

  override _getDeviceSpecificTextureFormatCapabilities(
    capabilities: DeviceTextureFormatCapabilities
  ): DeviceTextureFormatCapabilities {
    const {format} = capabilities;
    if (format.includes('webgl')) {
      return {format, create: false, render: false, filter: false, blend: false, store: false};
    }
    return capabilities;
  }
}

function getWebGPUDeviceLimits(limits: GPUSupportedLimits): DeviceLimits {
  const stageSpecificLimits: Partial<Record<keyof DeviceLimits, number>> = {
    maxStorageBuffersInVertexStage:
      limits.maxStorageBuffersInVertexStage ?? limits.maxStorageBuffersPerShaderStage,
    maxStorageBuffersInFragmentStage:
      limits.maxStorageBuffersInFragmentStage ?? limits.maxStorageBuffersPerShaderStage,
    maxStorageTexturesInVertexStage:
      limits.maxStorageTexturesInVertexStage ?? limits.maxStorageTexturesPerShaderStage,
    maxStorageTexturesInFragmentStage:
      limits.maxStorageTexturesInFragmentStage ?? limits.maxStorageTexturesPerShaderStage
  };

  return new Proxy(limits, {
    get(target, property) {
      return typeof property === 'string' && property in stageSpecificLimits
        ? stageSpecificLimits[property as keyof DeviceLimits]
        : Reflect.get(target, property, target);
    }
  }) as DeviceLimits;
}

function getWebGPUDeviceFeatureLevel(
  featureLevel: DeviceProps['featureLevel']
): NonNullable<DeviceInfo['featureLevel']> {
  return featureLevel === 'best-available' ? 'core' : featureLevel || 'core';
}

function identifyGPUVendor(
  vendor: string,
  renderer: string
): 'nvidia' | 'intel' | 'apple' | 'amd' | null {
  if (/NVIDIA/i.exec(vendor) || /NVIDIA/i.exec(renderer)) {
    return 'nvidia';
  }
  if (/INTEL/i.exec(vendor) || /INTEL/i.exec(renderer)) {
    return 'intel';
  }
  if (/Apple/i.exec(vendor) || /Apple/i.exec(renderer)) {
    return 'apple';
  }
  if (
    /AMD/i.exec(vendor) ||
    /AMD/i.exec(renderer) ||
    /ATI/i.exec(vendor) ||
    /ATI/i.exec(renderer)
  ) {
    return 'amd';
  }
  return null;
}

function scheduleMicrotask(callback: () => void): void {
  if (globalThis.queueMicrotask) {
    globalThis.queueMicrotask(callback);
    return;
  }
  Promise.resolve()
    .then(callback)
    .catch(() => {});
}

visgl / luma.gl / 27877741225

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous