@luma.gl/core 9.2.6 → 9.3.0-alpha.10

package/src/adapter/resources/resource.ts

@@ -3,8 +3,76 @@
 // Copyright (c) vis.gl contributors
 
 import type {Device} from '../device';
+import type {Stat, Stats} from '@probe.gl/stats';
 import {uid} from '../../utils/uid';
 
+const CPU_HOTSPOT_PROFILER_MODULE = 'cpu-hotspot-profiler';
+const RESOURCE_COUNTS_STATS = 'GPU Resource Counts';
+const LEGACY_RESOURCE_COUNTS_STATS = 'Resource Counts';
+const GPU_TIME_AND_MEMORY_STATS = 'GPU Time and Memory';
+const BASE_RESOURCE_COUNT_ORDER = [
+  'Resources',
+  'Buffers',
+  'Textures',
+  'Samplers',
+  'TextureViews',
+  'Framebuffers',
+  'QuerySets',
+  'Shaders',
+  'RenderPipelines',
+  'ComputePipelines',
+  'PipelineLayouts',
+  'VertexArrays',
+  'RenderPasss',
+  'ComputePasss',
+  'CommandEncoders',
+  'CommandBuffers'
+] as const;
+const WEBGL_RESOURCE_COUNT_ORDER = [
+  'Resources',
+  'Buffers',
+  'Textures',
+  'Samplers',
+  'TextureViews',
+  'Framebuffers',
+  'QuerySets',
+  'Shaders',
+  'RenderPipelines',
+  'SharedRenderPipelines',
+  'ComputePipelines',
+  'PipelineLayouts',
+  'VertexArrays',
+  'RenderPasss',
+  'ComputePasss',
+  'CommandEncoders',
+  'CommandBuffers'
+] as const;
+const BASE_RESOURCE_COUNT_STAT_ORDER = BASE_RESOURCE_COUNT_ORDER.flatMap(resourceType => [
+  `${resourceType} Created`,
+  `${resourceType} Active`
+]);
+const WEBGL_RESOURCE_COUNT_STAT_ORDER = WEBGL_RESOURCE_COUNT_ORDER.flatMap(resourceType => [
+  `${resourceType} Created`,
+  `${resourceType} Active`
+]);
+const ORDERED_STATS_CACHE = new WeakMap<
+  Stats,
+  {orderedStatNames: readonly string[]; statCount: number}
+>();
+const ORDERED_STAT_NAME_SET_CACHE = new WeakMap<readonly string[], Set<string>>();
+
+type CpuHotspotProfiler = {
+  enabled?: boolean;
+  activeDefaultFramebufferAcquireDepth?: number;
+  statsBookkeepingTimeMs?: number;
+  statsBookkeepingCalls?: number;
+  transientCanvasResourceCreates?: number;
+  transientCanvasTextureCreates?: number;
+  transientCanvasTextureViewCreates?: number;
+  transientCanvasSamplerCreates?: number;
+  transientCanvasFramebufferCreates?: number;
+};
+
 export type ResourceProps = {
   /** Name of resource, mainly for debugging purposes. A unique name will be assigned if not provided */
   id?: string;
@@ -33,16 +101,23 @@ export abstract class Resource<Props extends ResourceProps> {
 
   /** props.id, for debugging. */
   id: string;
+  /** The props that this resource was created with */
   readonly props: Required<Props>;
+  /** User data object, reserved for the application */
   readonly userData: Record<string, unknown> = {};
+  /** The device that this resource is associated with */
   abstract readonly device: Device;
+  /** The handle for the underlying resource, e.g. WebGL object or WebGPU handle */
   abstract readonly handle: unknown;
+  /** The device that this resource is associated with - TODO can we remove this dup? */
   private _device: Device;
 
   /** Whether this resource has been destroyed */
   destroyed: boolean = false;
   /** For resources that allocate GPU memory */
   private allocatedBytes: number = 0;
+  /** Stats bucket currently holding the tracked allocation */
+  private allocatedBytesName: string | null = null;
   /** Attached resources will be destroyed when this resource is destroyed. Tracks auto-created "sub" resources. */
   private _attachedResources = new Set<Resource<ResourceProps>>();
 
@@ -69,6 +144,9 @@ export abstract class Resource<Props extends ResourceProps> {
    * destroy can be called on any resource to release it before it is garbage collected.
    */
   destroy(): void {
+    if (this.destroyed) {
+      return;
+    }
     this.destroyResource();
   }
 
@@ -114,7 +192,7 @@ export abstract class Resource<Props extends ResourceProps> {
 
   /** Destroy all owned resources. Make sure the resources are no longer needed before calling. */
   destroyAttachedResources(): void {
-    for (const resource of Object.values(this._attachedResources)) {
+    for (const resource of this._attachedResources) {
       resource.destroy();
     }
     // don't remove while we are iterating
@@ -125,6 +203,9 @@ export abstract class Resource<Props extends ResourceProps> {
 
   /** Perform all destroy steps. Can be called by derived resources when overriding destroy() */
   protected destroyResource(): void {
+    if (this.destroyed) {
+      return;
+    }
     this.destroyAttachedResources();
     this.removeStats();
     this.destroyed = true;
@@ -132,34 +213,111 @@ export abstract class Resource<Props extends ResourceProps> {
 
   /** Called by .destroy() to track object destruction. Subclass must call if overriding destroy() */
   protected removeStats(): void {
-    const stats = this._device.statsManager.getStats('Resource Counts');
-    const name = this[Symbol.toStringTag];
-    stats.get(`${name}s Active`).decrementCount();
+    const profiler = getCpuHotspotProfiler(this._device);
+    const startTime = profiler ? getTimestamp() : 0;
+    const statsObjects = [
+      this._device.statsManager.getStats(RESOURCE_COUNTS_STATS),
+      this._device.statsManager.getStats(LEGACY_RESOURCE_COUNTS_STATS)
+    ];
+    const orderedStatNames = getResourceCountStatOrder(this._device);
+    for (const stats of statsObjects) {
+      initializeStats(stats, orderedStatNames);
+    }
+    const name = this.getStatsName();
+    for (const stats of statsObjects) {
+      stats.get('Resources Active').decrementCount();
+      stats.get(`${name}s Active`).decrementCount();
+    }
+    if (profiler) {
+      profiler.statsBookkeepingCalls = (profiler.statsBookkeepingCalls || 0) + 1;
+      profiler.statsBookkeepingTimeMs =
+        (profiler.statsBookkeepingTimeMs || 0) + (getTimestamp() - startTime);
+    }
   }
 
   /** Called by subclass to track memory allocations */
-  protected trackAllocatedMemory(bytes: number, name = this[Symbol.toStringTag]): void {
-    const stats = this._device.statsManager.getStats('Resource Counts');
+  protected trackAllocatedMemory(bytes: number, name = this.getStatsName()): void {
+    const profiler = getCpuHotspotProfiler(this._device);
+    const startTime = profiler ? getTimestamp() : 0;
+    const stats = this._device.statsManager.getStats(GPU_TIME_AND_MEMORY_STATS);
+
+    if (this.allocatedBytes > 0 && this.allocatedBytesName) {
+      stats.get('GPU Memory').subtractCount(this.allocatedBytes);
+      stats.get(`${this.allocatedBytesName} Memory`).subtractCount(this.allocatedBytes);
+    }
+
     stats.get('GPU Memory').addCount(bytes);
     stats.get(`${name} Memory`).addCount(bytes);
+    if (profiler) {
+      profiler.statsBookkeepingCalls = (profiler.statsBookkeepingCalls || 0) + 1;
+      profiler.statsBookkeepingTimeMs =
+        (profiler.statsBookkeepingTimeMs || 0) + (getTimestamp() - startTime);
+    }
     this.allocatedBytes = bytes;
+    this.allocatedBytesName = name;
+  }
+
+  /** Called by subclass to track handle-backed memory allocations separately from owned allocations */
+  protected trackReferencedMemory(bytes: number, name = this.getStatsName()): void {
+    this.trackAllocatedMemory(bytes, `Referenced ${name}`);
   }
 
   /** Called by subclass to track memory deallocations */
-  protected trackDeallocatedMemory(name = this[Symbol.toStringTag]): void {
-    const stats = this._device.statsManager.getStats('Resource Counts');
+  protected trackDeallocatedMemory(name = this.getStatsName()): void {
+    if (this.allocatedBytes === 0) {
+      this.allocatedBytesName = null;
+      return;
+    }
+
+    const profiler = getCpuHotspotProfiler(this._device);
+    const startTime = profiler ? getTimestamp() : 0;
+    const stats = this._device.statsManager.getStats(GPU_TIME_AND_MEMORY_STATS);
     stats.get('GPU Memory').subtractCount(this.allocatedBytes);
-    stats.get(`${name} Memory`).subtractCount(this.allocatedBytes);
+    stats.get(`${this.allocatedBytesName || name} Memory`).subtractCount(this.allocatedBytes);
+    if (profiler) {
+      profiler.statsBookkeepingCalls = (profiler.statsBookkeepingCalls || 0) + 1;
+      profiler.statsBookkeepingTimeMs =
+        (profiler.statsBookkeepingTimeMs || 0) + (getTimestamp() - startTime);
+    }
     this.allocatedBytes = 0;
+    this.allocatedBytesName = null;
+  }
+
+  /** Called by subclass to deallocate handle-backed memory tracked via trackReferencedMemory() */
+  protected trackDeallocatedReferencedMemory(name = this.getStatsName()): void {
+    this.trackDeallocatedMemory(`Referenced ${name}`);
   }
 
   /** Called by resource constructor to track object creation */
   private addStats(): void {
-    const stats = this._device.statsManager.getStats('Resource Counts');
-    const name = this[Symbol.toStringTag];
-    stats.get('Resources Created').incrementCount();
-    stats.get(`${name}s Created`).incrementCount();
-    stats.get(`${name}s Active`).incrementCount();
+    const name = this.getStatsName();
+    const profiler = getCpuHotspotProfiler(this._device);
+    const startTime = profiler ? getTimestamp() : 0;
+    const statsObjects = [
+      this._device.statsManager.getStats(RESOURCE_COUNTS_STATS),
+      this._device.statsManager.getStats(LEGACY_RESOURCE_COUNTS_STATS)
+    ];
+    const orderedStatNames = getResourceCountStatOrder(this._device);
+    for (const stats of statsObjects) {
+      initializeStats(stats, orderedStatNames);
+    }
+    for (const stats of statsObjects) {
+      stats.get('Resources Created').incrementCount();
+      stats.get('Resources Active').incrementCount();
+      stats.get(`${name}s Created`).incrementCount();
+      stats.get(`${name}s Active`).incrementCount();
+    }
+    if (profiler) {
+      profiler.statsBookkeepingCalls = (profiler.statsBookkeepingCalls || 0) + 1;
+      profiler.statsBookkeepingTimeMs =
+        (profiler.statsBookkeepingTimeMs || 0) + (getTimestamp() - startTime);
+    }
+    recordTransientCanvasResourceCreate(this._device, name);
+  }
+
+  /** Canonical resource name used for stats buckets. */
+  protected getStatsName(): string {
+    return getCanonicalResourceName(this);
   }
 }
 
@@ -178,3 +336,120 @@ function selectivelyMerge<Props>(props: Props, defaultProps: Required<Props>): R
   }
   return mergedProps;
 }
+
+function initializeStats(stats: Stats, orderedStatNames: readonly string[]): void {
+  const statsMap = stats.stats;
+  let addedOrderedStat = false;
+  for (const statName of orderedStatNames) {
+    if (!statsMap[statName]) {
+      stats.get(statName);
+      addedOrderedStat = true;
+    }
+  }
+
+  const statCount = Object.keys(statsMap).length;
+  const cachedStats = ORDERED_STATS_CACHE.get(stats);
+  if (
+    !addedOrderedStat &&
+    cachedStats?.orderedStatNames === orderedStatNames &&
+    cachedStats.statCount === statCount
+  ) {
+    return;
+  }
+
+  const reorderedStats: Record<string, Stat> = {};
+  let orderedStatNamesSet = ORDERED_STAT_NAME_SET_CACHE.get(orderedStatNames);
+  if (!orderedStatNamesSet) {
+    orderedStatNamesSet = new Set(orderedStatNames);
+    ORDERED_STAT_NAME_SET_CACHE.set(orderedStatNames, orderedStatNamesSet);
+  }
+
+  for (const statName of orderedStatNames) {
+    if (statsMap[statName]) {
+      reorderedStats[statName] = statsMap[statName];
+    }
+  }
+
+  for (const [statName, stat] of Object.entries(statsMap)) {
+    if (!orderedStatNamesSet.has(statName)) {
+      reorderedStats[statName] = stat;
+    }
+  }
+
+  for (const statName of Object.keys(statsMap)) {
+    delete statsMap[statName];
+  }
+
+  Object.assign(statsMap, reorderedStats);
+  ORDERED_STATS_CACHE.set(stats, {orderedStatNames, statCount});
+}
+
+function getResourceCountStatOrder(device: Device): readonly string[] {
+  return device.type === 'webgl' ? WEBGL_RESOURCE_COUNT_STAT_ORDER : BASE_RESOURCE_COUNT_STAT_ORDER;
+}
+
+function getCpuHotspotProfiler(device: Device): CpuHotspotProfiler | null {
+  const profiler = device.userData[CPU_HOTSPOT_PROFILER_MODULE] as CpuHotspotProfiler | undefined;
+  return profiler?.enabled ? profiler : null;
+}
+
+function getTimestamp(): number {
+  return globalThis.performance?.now?.() ?? Date.now();
+}
+
+function recordTransientCanvasResourceCreate(device: Device, name: string): void {
+  const profiler = getCpuHotspotProfiler(device);
+  if (!profiler || !profiler.activeDefaultFramebufferAcquireDepth) {
+    return;
+  }
+
+  profiler.transientCanvasResourceCreates = (profiler.transientCanvasResourceCreates || 0) + 1;
+
+  switch (name) {
+    case 'Texture':
+      profiler.transientCanvasTextureCreates = (profiler.transientCanvasTextureCreates || 0) + 1;
+      break;
+    case 'TextureView':
+      profiler.transientCanvasTextureViewCreates =
+        (profiler.transientCanvasTextureViewCreates || 0) + 1;
+      break;
+    case 'Sampler':
+      profiler.transientCanvasSamplerCreates = (profiler.transientCanvasSamplerCreates || 0) + 1;
+      break;
+    case 'Framebuffer':
+      profiler.transientCanvasFramebufferCreates =
+        (profiler.transientCanvasFramebufferCreates || 0) + 1;
+      break;
+    default:
+      break;
+  }
+}
+
+function getCanonicalResourceName(resource: Resource<any>): string {
+  let prototype = Object.getPrototypeOf(resource);
+
+  while (prototype) {
+    const parentPrototype = Object.getPrototypeOf(prototype);
+    if (!parentPrototype || parentPrototype === Resource.prototype) {
+      return (
+        getPrototypeToStringTag(prototype) ||
+        resource[Symbol.toStringTag] ||
+        resource.constructor.name
+      );
+    }
+    prototype = parentPrototype;
+  }
+
+  return resource[Symbol.toStringTag] || resource.constructor.name;
+}
+
+function getPrototypeToStringTag(prototype: object): string | null {
+  const descriptor = Object.getOwnPropertyDescriptor(prototype, Symbol.toStringTag);
+  if (typeof descriptor?.get === 'function') {
+    return descriptor.get.call(prototype);
+  }
+  if (typeof descriptor?.value === 'string') {
+    return descriptor.value;
+  }
+  return null;
+}

package/src/adapter/resources/shader.ts

@@ -106,38 +106,38 @@ export abstract class Shader extends Resource<ShaderProps> {
 
     const shaderName: string = shaderId; // getShaderName(this.source) || ;
     const shaderTitle: string = `${this.stage} shader "${shaderName}"`;
-    let htmlLog = formatCompilerLog(messages, this.source, {showSourceCode: 'all', html: true});
+    const htmlLog = formatCompilerLog(messages, this.source, {showSourceCode: 'all', html: true});
     // Show translated source if available
     const translatedSource = this.getTranslatedSource();
+
+    const container = document.createElement('div');
+    container.innerHTML = `\
+<h1>Compilation error in ${shaderTitle}</h1>
+<div style="display:flex;position:fixed;top:10px;right:20px;gap:2px;">
+<button id="copy">Copy source</button><br/>
+<button id="close">Close</button>
+</div>
+<code><pre>${htmlLog}</pre></code>`;
     if (translatedSource) {
-      htmlLog += `<br /><br /><h1>Translated Source</h1><br /><br /><code style="user-select:text;"><pre>${translatedSource}</pre></code>`;
+      container.innerHTML += `<br /><h1>Translated Source</h1><br /><br /><code><pre>${translatedSource}</pre></code>`;
     }
-    // Make it clickable so we can copy to clipboard
-    const button = document.createElement('Button');
-    button.innerHTML = `
-<h1>Compilation error in ${shaderTitle}</h1><br /><br />
-<code style="user-select:text;"><pre>
-${htmlLog}
-</pre></code>`;
-    button.style.top = '10px';
-    button.style.left = '10px';
-    button.style.position = 'absolute';
-    button.style.zIndex = '9999';
-    button.style.width = '100%';
-    button.style.textAlign = 'left';
-    document.body.appendChild(button);
-
-    const errors = document.getElementsByClassName('luma-compiler-log-error');
-    errors[0]?.scrollIntoView();
-
-    // TODO - add a small embedded copy button (instead of main button)
-    button.onclick = () => {
-      // const source = this.source.replaceAll('\n', '<br />');
-      const dataURI = `data:text/plain,${encodeURIComponent(this.source)}`;
-      navigator.clipboard.writeText(dataURI);
+    container.style.top = '0';
+    container.style.left = '0';
+    container.style.background = 'white';
+    container.style.position = 'fixed';
+    container.style.zIndex = '9999';
+    container.style.maxWidth = '100vw';
+    container.style.maxHeight = '100vh';
+    container.style.overflowY = 'auto';
+    document.body.appendChild(container);
+    const error = container.querySelector('.luma-compiler-log-error');
+    error?.scrollIntoView();
+    (container.querySelector('button#close') as HTMLButtonElement).onclick = () => {
+      container.remove();
+    };
+    (container.querySelector('button#copy') as HTMLButtonElement).onclick = () => {
+      navigator.clipboard.writeText(this.source);
     };
-
-    // TODO - add a small embedded close button
   }
 
   static override defaultProps: Required<ShaderProps> = {
@@ -162,5 +162,5 @@ function getShaderIdFromProps(props: ShaderProps): string {
 function getShaderName(shader: string, defaultName: string = 'unnamed'): string {
   const SHADER_NAME_REGEXP = /#define[\s*]SHADER_NAME[\s*]([A-Za-z0-9_-]+)[\s*]/;
   const match = SHADER_NAME_REGEXP.exec(shader);
-  return match ? match[1] : defaultName;
+  return match?.[1] ?? defaultName;
 }

package/src/adapter/resources/shared-render-pipeline.ts

@@ -0,0 +1,40 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Device} from '../device';
+import type {Shader} from './shader';
+import {Resource, type ResourceProps} from './resource';
+
+export type SharedRenderPipelineProps = ResourceProps & {
+  handle?: unknown;
+  vs: Shader;
+  fs: Shader;
+  varyings?: string[];
+  bufferMode?: number;
+};
+
+/**
+ * Internal base class for backend-specific shared render-pipeline implementations.
+ * Backends may use this to share expensive linked/program state across multiple
+ * `RenderPipeline` wrappers.
+ */
+export abstract class SharedRenderPipeline extends Resource<SharedRenderPipelineProps> {
+  override get [Symbol.toStringTag](): string {
+    return 'SharedRenderPipeline';
+  }
+
+  abstract override readonly device: Device;
+  abstract override readonly handle: unknown;
+
+  constructor(device: Device, props: SharedRenderPipelineProps) {
+    super(device, props, {
+      ...Resource.defaultProps,
+      handle: undefined!,
+      vs: undefined!,
+      fs: undefined!,
+      varyings: undefined!,
+      bufferMode: undefined!
+    });
+  }
+}

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

@@ -4,7 +4,7 @@
 
 import type {Device} from '../device';
 import type {Texture} from './texture';
-import type {TextureFormat} from '../../shadertypes/textures/texture-formats';
+import type {TextureFormat} from '../../shadertypes/texture-types/texture-formats';
 import {Resource, ResourceProps} from './resource';
 
 /** Properties for initializing a texture view */