@luma.gl/core 9.3.0-alpha.4 → 9.3.0-alpha.8

package/src/factories/bind-group-factory.ts

@@ -0,0 +1,139 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  Bindings,
+  BindingsByGroup,
+  ComputeShaderLayout,
+  ShaderLayout
+} from '../adapter/types/shader-layout';
+import type {Device} from '../adapter/device';
+import type {ComputePipeline} from '../adapter/resources/compute-pipeline';
+import type {RenderPipeline} from '../adapter/resources/render-pipeline';
+import {normalizeBindingsByGroup} from '../adapter-utils/bind-groups';
+
+type AnyPipeline = RenderPipeline | ComputePipeline;
+type AnyShaderLayout = ShaderLayout | ComputeShaderLayout;
+type BindGroupCacheKeys = Partial<Record<number, object>>;
+type BindGroupMap = Partial<Record<number, unknown>>;
+type LayoutCache = Partial<Record<number, object>>;
+type LayoutBindGroupCache = {
+  bindGroupsBySource: WeakMap<object, unknown | null>;
+  emptyBindGroup?: unknown;
+};
+
+export class BindGroupFactory {
+  readonly device: Device;
+
+  private readonly _layoutCacheByPipeline: WeakMap<AnyPipeline, LayoutCache> = new WeakMap();
+  private readonly _bindGroupCacheByLayout: WeakMap<object, LayoutBindGroupCache> = new WeakMap();
+
+  constructor(device: Device) {
+    this.device = device;
+  }
+
+  getBindGroups(
+    pipeline: AnyPipeline,
+    bindings?: Bindings | BindingsByGroup,
+    bindGroupCacheKeys?: BindGroupCacheKeys
+  ): BindGroupMap {
+    if (this.device.type !== 'webgpu' || pipeline.shaderLayout.bindings.length === 0) {
+      return {};
+    }
+
+    const bindingsByGroup = normalizeBindingsByGroup(pipeline.shaderLayout, bindings);
+    const resolvedBindGroups: BindGroupMap = {};
+
+    for (const group of getBindGroupIndicesUpToMax(pipeline.shaderLayout.bindings)) {
+      const groupBindings = bindingsByGroup[group];
+      const bindGroupLayout = this._getBindGroupLayout(pipeline, group);
+
+      if (!groupBindings || Object.keys(groupBindings).length === 0) {
+        if (!hasBindingsInGroup(pipeline.shaderLayout.bindings, group)) {
+          resolvedBindGroups[group] = this._getEmptyBindGroup(
+            bindGroupLayout,
+            pipeline.shaderLayout,
+            group
+          );
+        }
+        continue;
+      }
+
+      const bindGroupCacheKey = bindGroupCacheKeys?.[group];
+      if (bindGroupCacheKey) {
+        const layoutCache = this._getLayoutBindGroupCache(bindGroupLayout);
+        if (layoutCache.bindGroupsBySource.has(bindGroupCacheKey)) {
+          resolvedBindGroups[group] = layoutCache.bindGroupsBySource.get(bindGroupCacheKey) || null;
+          continue;
+        }
+
+        const bindGroup = this.device._createBindGroupWebGPU(
+          bindGroupLayout,
+          pipeline.shaderLayout,
+          groupBindings,
+          group
+        );
+        layoutCache.bindGroupsBySource.set(bindGroupCacheKey, bindGroup);
+        resolvedBindGroups[group] = bindGroup;
+      } else {
+        resolvedBindGroups[group] = this.device._createBindGroupWebGPU(
+          bindGroupLayout,
+          pipeline.shaderLayout,
+          groupBindings,
+          group
+        );
+      }
+    }
+
+    return resolvedBindGroups;
+  }
+
+  private _getBindGroupLayout(pipeline: AnyPipeline, group: number): object {
+    let layoutCache = this._layoutCacheByPipeline.get(pipeline);
+    if (!layoutCache) {
+      layoutCache = {};
+      this._layoutCacheByPipeline.set(pipeline, layoutCache);
+    }
+
+    layoutCache[group] ||= this.device._createBindGroupLayoutWebGPU(pipeline, group) as object;
+    return layoutCache[group];
+  }
+
+  private _getEmptyBindGroup(
+    bindGroupLayout: object,
+    shaderLayout: AnyShaderLayout,
+    group: number
+  ): unknown {
+    const layoutCache = this._getLayoutBindGroupCache(bindGroupLayout);
+    layoutCache.emptyBindGroup ||=
+      this.device._createBindGroupWebGPU(bindGroupLayout, shaderLayout, {}, group) || null;
+    return layoutCache.emptyBindGroup;
+  }
+
+  private _getLayoutBindGroupCache(bindGroupLayout: object): LayoutBindGroupCache {
+    let layoutCache = this._bindGroupCacheByLayout.get(bindGroupLayout);
+    if (!layoutCache) {
+      layoutCache = {bindGroupsBySource: new WeakMap()};
+      this._bindGroupCacheByLayout.set(bindGroupLayout, layoutCache);
+    }
+    return layoutCache;
+  }
+}
+
+export function _getDefaultBindGroupFactory(device: Device): BindGroupFactory {
+  device._factories.bindGroupFactory ||= new BindGroupFactory(device);
+  return device._factories.bindGroupFactory as BindGroupFactory;
+}
+
+function getBindGroupIndicesUpToMax(bindings: AnyShaderLayout['bindings']): number[] {
+  const maxGroup = bindings.reduce(
+    (highestGroup, binding) => Math.max(highestGroup, binding.group),
+    -1
+  );
+  return Array.from({length: maxGroup + 1}, (_, group) => group);
+}
+
+function hasBindingsInGroup(bindings: AnyShaderLayout['bindings'], group: number): boolean {
+  return bindings.some(binding => binding.group === group);
+}

package/src/factories/core-module-state.ts

@@ -0,0 +1,11 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {PipelineFactory} from './pipeline-factory';
+import type {ShaderFactory} from './shader-factory';
+
+export type CoreModuleState = {
+  defaultPipelineFactory?: PipelineFactory;
+  defaultShaderFactory?: ShaderFactory;
+};

package/src/factories/pipeline-factory.ts

@@ -0,0 +1,328 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Device} from '../adapter/device';
+import {ComputePipeline, type ComputePipelineProps} from '../adapter/resources/compute-pipeline';
+import {RenderPipeline, type RenderPipelineProps} from '../adapter/resources/render-pipeline';
+import {Resource} from '../adapter/resources/resource';
+import type {SharedRenderPipeline} from '../adapter/resources/shared-render-pipeline';
+import {log} from '../utils/log';
+import {uid} from '../utils/uid';
+import type {CoreModuleState} from './core-module-state';
+
+export type PipelineFactoryProps = RenderPipelineProps;
+
+type CacheItem<ResourceT extends Resource<any>> = {resource: ResourceT; useCount: number};
+
+/**
+ * Efficiently creates / caches pipelines
+ */
+export class PipelineFactory {
+  static defaultProps: Required<PipelineFactoryProps> = {...RenderPipeline.defaultProps};
+
+  /** Get the singleton default pipeline factory for the specified device */
+  static getDefaultPipelineFactory(device: Device): PipelineFactory {
+    const moduleData = device.getModuleData<CoreModuleState>('@luma.gl/core');
+    moduleData.defaultPipelineFactory ||= new PipelineFactory(device);
+    return moduleData.defaultPipelineFactory;
+  }
+
+  readonly device: Device;
+
+  private _hashCounter: number = 0;
+  private readonly _hashes: Record<string, number> = {};
+  private readonly _renderPipelineCache: Record<string, CacheItem<RenderPipeline>> = {};
+  private readonly _computePipelineCache: Record<string, CacheItem<ComputePipeline>> = {};
+  private readonly _sharedRenderPipelineCache: Record<string, CacheItem<SharedRenderPipeline>> = {};
+
+  get [Symbol.toStringTag](): string {
+    return 'PipelineFactory';
+  }
+
+  toString(): string {
+    return `PipelineFactory(${this.device.id})`;
+  }
+
+  constructor(device: Device) {
+    this.device = device;
+  }
+
+  /**
+   * WebGL has two cache layers with different priorities:
+   * - `_sharedRenderPipelineCache` owns `WEBGLSharedRenderPipeline` / `WebGLProgram` reuse.
+   * - `_renderPipelineCache` owns `RenderPipeline` wrapper reuse.
+   *
+   * Shared WebGL program reuse is the hard requirement. Wrapper reuse is beneficial,
+   * but wrapper cache misses are acceptable if that keeps the cache logic simple and
+   * prevents incorrect cache hits.
+   *
+   * In particular, wrapper hash logic must never force program creation or linked-program
+   * introspection just to decide whether a shared WebGL program can be reused.
+   */
+  /** Return a RenderPipeline matching supplied props. Reuses an equivalent pipeline if already created. */
+  createRenderPipeline(props: RenderPipelineProps): RenderPipeline {
+    if (!this.device.props._cachePipelines) {
+      return this.device.createRenderPipeline(props);
+    }
+
+    const allProps: Required<RenderPipelineProps> = {...RenderPipeline.defaultProps, ...props};
+
+    const cache = this._renderPipelineCache;
+    const hash = this._hashRenderPipeline(allProps);
+
+    let pipeline: RenderPipeline = cache[hash]?.resource;
+    if (!pipeline) {
+      const sharedRenderPipeline =
+        this.device.type === 'webgl' && this.device.props._sharePipelines
+          ? this.createSharedRenderPipeline(allProps)
+          : undefined;
+      pipeline = this.device.createRenderPipeline({
+        ...allProps,
+        id: allProps.id ? `${allProps.id}-cached` : uid('unnamed-cached'),
+        _sharedRenderPipeline: sharedRenderPipeline
+      });
+      pipeline.hash = hash;
+      cache[hash] = {resource: pipeline, useCount: 1};
+      if (this.device.props.debugFactories) {
+        log.log(3, `${this}: ${pipeline} created, count=${cache[hash].useCount}`)();
+      }
+    } else {
+      cache[hash].useCount++;
+      if (this.device.props.debugFactories) {
+        log.log(
+          3,
+          `${this}: ${cache[hash].resource} reused, count=${cache[hash].useCount}, (id=${props.id})`
+        )();
+      }
+    }
+
+    return pipeline;
+  }
+
+  /** Return a ComputePipeline matching supplied props. Reuses an equivalent pipeline if already created. */
+  createComputePipeline(props: ComputePipelineProps): ComputePipeline {
+    if (!this.device.props._cachePipelines) {
+      return this.device.createComputePipeline(props);
+    }
+
+    const allProps: Required<ComputePipelineProps> = {...ComputePipeline.defaultProps, ...props};
+
+    const cache = this._computePipelineCache;
+    const hash = this._hashComputePipeline(allProps);
+
+    let pipeline: ComputePipeline = cache[hash]?.resource;
+    if (!pipeline) {
+      pipeline = this.device.createComputePipeline({
+        ...allProps,
+        id: allProps.id ? `${allProps.id}-cached` : undefined
+      });
+      pipeline.hash = hash;
+      cache[hash] = {resource: pipeline, useCount: 1};
+      if (this.device.props.debugFactories) {
+        log.log(3, `${this}: ${pipeline} created, count=${cache[hash].useCount}`)();
+      }
+    } else {
+      cache[hash].useCount++;
+      if (this.device.props.debugFactories) {
+        log.log(
+          3,
+          `${this}: ${cache[hash].resource} reused, count=${cache[hash].useCount}, (id=${props.id})`
+        )();
+      }
+    }
+
+    return pipeline;
+  }
+
+  release(pipeline: RenderPipeline | ComputePipeline): void {
+    if (!this.device.props._cachePipelines) {
+      pipeline.destroy();
+      return;
+    }
+
+    const cache = this._getCache(pipeline);
+    const hash = pipeline.hash;
+
+    cache[hash].useCount--;
+    if (cache[hash].useCount === 0) {
+      this._destroyPipeline(pipeline);
+      if (this.device.props.debugFactories) {
+        log.log(3, `${this}: ${pipeline} released and destroyed`)();
+      }
+    } else if (cache[hash].useCount < 0) {
+      log.error(`${this}: ${pipeline} released, useCount < 0, resetting`)();
+      cache[hash].useCount = 0;
+    } else if (this.device.props.debugFactories) {
+      log.log(3, `${this}: ${pipeline} released, count=${cache[hash].useCount}`)();
+    }
+  }
+
+  createSharedRenderPipeline(props: RenderPipelineProps): SharedRenderPipeline {
+    const sharedPipelineHash = this._hashSharedRenderPipeline(props);
+    let sharedCacheItem = this._sharedRenderPipelineCache[sharedPipelineHash];
+    if (!sharedCacheItem) {
+      const sharedRenderPipeline = this.device._createSharedRenderPipelineWebGL(props);
+      sharedCacheItem = {resource: sharedRenderPipeline, useCount: 0};
+      this._sharedRenderPipelineCache[sharedPipelineHash] = sharedCacheItem;
+    }
+    sharedCacheItem.useCount++;
+    return sharedCacheItem.resource;
+  }
+
+  releaseSharedRenderPipeline(pipeline: RenderPipeline): void {
+    if (!pipeline.sharedRenderPipeline) {
+      return;
+    }
+
+    const sharedPipelineHash = this._hashSharedRenderPipeline(pipeline.sharedRenderPipeline.props);
+    const sharedCacheItem = this._sharedRenderPipelineCache[sharedPipelineHash];
+    if (!sharedCacheItem) {
+      return;
+    }
+
+    sharedCacheItem.useCount--;
+    if (sharedCacheItem.useCount === 0) {
+      sharedCacheItem.resource.destroy();
+      delete this._sharedRenderPipelineCache[sharedPipelineHash];
+    }
+  }
+
+  // PRIVATE
+
+  /** Destroy a cached pipeline, removing it from the cache if configured to do so. */
+  private _destroyPipeline(pipeline: RenderPipeline | ComputePipeline): boolean {
+    const cache = this._getCache(pipeline);
+
+    if (!this.device.props._destroyPipelines) {
+      return false;
+    }
+
+    delete cache[pipeline.hash];
+    pipeline.destroy();
+    if (pipeline instanceof RenderPipeline) {
+      this.releaseSharedRenderPipeline(pipeline);
+    }
+    return true;
+  }
+
+  /** Get the appropriate cache for the type of pipeline */
+  private _getCache(
+    pipeline: RenderPipeline | ComputePipeline
+  ): Record<string, CacheItem<RenderPipeline>> | Record<string, CacheItem<ComputePipeline>> {
+    let cache:
+      | Record<string, CacheItem<RenderPipeline>>
+      | Record<string, CacheItem<ComputePipeline>>
+      | undefined;
+    if (pipeline instanceof ComputePipeline) {
+      cache = this._computePipelineCache;
+    }
+    if (pipeline instanceof RenderPipeline) {
+      cache = this._renderPipelineCache;
+    }
+    if (!cache) {
+      throw new Error(`${this}`);
+    }
+    if (!cache[pipeline.hash]) {
+      throw new Error(`${this}: ${pipeline} matched incorrect entry`);
+    }
+    return cache;
+  }
+
+  /** Calculate a hash based on all the inputs for a compute pipeline */
+  private _hashComputePipeline(props: ComputePipelineProps): string {
+    const {type} = this.device;
+    const shaderHash = this._getHash(props.shader.source);
+    const shaderLayoutHash = this._getHash(JSON.stringify(props.shaderLayout));
+    return `${type}/C/${shaderHash}SL${shaderLayoutHash}`;
+  }
+
+  /** Calculate a hash based on all the inputs for a render pipeline */
+  private _hashRenderPipeline(props: RenderPipelineProps): string {
+    // Backend-specific hashing requirements:
+    // - WebGPU hash keys must include every immutable descriptor-shaping input that can
+    //   change the created `GPURenderPipeline`, including attachment formats.
+    // - WebGL hash keys only govern wrapper reuse. They must remain compatible with
+    //   shared-program reuse and must not depend on linked-program introspection just
+    //   to decide whether a shared `WebGLProgram` can be reused.
+    //
+    // General exclusions:
+    // - `id`, `handle`: resource identity / caller-supplied handles, not cache shape
+    // - `bindings`: mutable per-pipeline compatibility state
+    // - `disableWarnings`: logging only, no rendering impact
+    // - `vsConstants`, `fsConstants`: currently unused by pipeline creation
+    const vsHash = props.vs ? this._getHash(props.vs.source) : 0;
+    const fsHash = props.fs ? this._getHash(props.fs.source) : 0;
+    const varyingHash = this._getWebGLVaryingHash(props);
+    const shaderLayoutHash = this._getHash(JSON.stringify(props.shaderLayout));
+    const bufferLayoutHash = this._getHash(JSON.stringify(props.bufferLayout));
+
+    const {type} = this.device;
+    switch (type) {
+      case 'webgl':
+        // WebGL wrappers preserve default topology and parameter semantics for direct
+        // callers, even though the underlying linked program may be shared separately.
+        // Future WebGL-only additions here must not turn wrapper reuse into a prerequisite
+        // for shared `WebGLProgram` reuse.
+        const webglParameterHash = this._getHash(JSON.stringify(props.parameters));
+        return `${type}/R/${vsHash}/${fsHash}V${varyingHash}T${props.topology}P${webglParameterHash}SL${shaderLayoutHash}BL${bufferLayoutHash}`;
+
+      case 'webgpu':
+      default:
+        // On WebGPU we need to rebuild the pipeline if topology, entry points,
+        // shader/layout data, parameters, bufferLayout or attachment formats change.
+        // Attachment formats must stay in the key so screen and offscreen passes do not
+        // accidentally alias the same cached `GPURenderPipeline`.
+        const entryPointHash = this._getHash(
+          JSON.stringify({
+            vertexEntryPoint: props.vertexEntryPoint,
+            fragmentEntryPoint: props.fragmentEntryPoint
+          })
+        );
+        const parameterHash = this._getHash(JSON.stringify(props.parameters));
+        const attachmentHash = this._getWebGPUAttachmentHash(props);
+        // TODO - Can json.stringify() generate different strings for equivalent objects if order of params is different?
+        // create a deepHash() to deduplicate?
+        return `${type}/R/${vsHash}/${fsHash}V${varyingHash}T${props.topology}EP${entryPointHash}P${parameterHash}SL${shaderLayoutHash}BL${bufferLayoutHash}A${attachmentHash}`;
+    }
+  }
+
+  // This is the only gate for shared `WebGLProgram` reuse.
+  // Only include inputs that affect program linking or transform-feedback linkage.
+  // Wrapper-only concerns such as topology, parameters, attachment formats and layout
+  // overrides must not be added here.
+  private _hashSharedRenderPipeline(props: RenderPipelineProps): string {
+    const vsHash = props.vs ? this._getHash(props.vs.source) : 0;
+    const fsHash = props.fs ? this._getHash(props.fs.source) : 0;
+    const varyingHash = this._getWebGLVaryingHash(props);
+    return `webgl/S/${vsHash}/${fsHash}V${varyingHash}`;
+  }
+
+  private _getHash(key: string): number {
+    if (this._hashes[key] === undefined) {
+      this._hashes[key] = this._hashCounter++;
+    }
+    return this._hashes[key];
+  }
+
+  private _getWebGLVaryingHash(props: RenderPipelineProps): number {
+    const {varyings = [], bufferMode = null} = props;
+    return this._getHash(JSON.stringify({varyings, bufferMode}));
+  }
+
+  private _getWebGPUAttachmentHash(props: RenderPipelineProps): number {
+    const colorAttachmentFormats = props.colorAttachmentFormats ?? [
+      this.device.preferredColorFormat
+    ];
+    const depthStencilAttachmentFormat = props.parameters?.depthWriteEnabled
+      ? props.depthStencilAttachmentFormat || this.device.preferredDepthFormat
+      : null;
+
+    return this._getHash(
+      JSON.stringify({
+        colorAttachmentFormats,
+        depthStencilAttachmentFormat
+      })
+    );
+  }
+}

package/src/factories/shader-factory.ts

@@ -0,0 +1,103 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Device} from '../adapter/device';
+import {Shader, type ShaderProps} from '../adapter/resources/shader';
+import {log} from '../utils/log';
+import type {CoreModuleState} from './core-module-state';
+
+type CacheItem = {resource: Shader; useCount: number};
+
+/** Manages a cached pool of Shaders for reuse. */
+export class ShaderFactory {
+  static readonly defaultProps: Required<ShaderProps> = {...Shader.defaultProps};
+
+  /** Returns the default ShaderFactory for the given {@link Device}, creating one if necessary. */
+  static getDefaultShaderFactory(device: Device): ShaderFactory {
+    const moduleData = device.getModuleData<CoreModuleState>('@luma.gl/core');
+    moduleData.defaultShaderFactory ||= new ShaderFactory(device);
+    return moduleData.defaultShaderFactory;
+  }
+
+  public readonly device: Device;
+
+  private readonly _cache: Record<string, CacheItem> = {};
+
+  get [Symbol.toStringTag](): string {
+    return 'ShaderFactory';
+  }
+
+  toString(): string {
+    return `${this[Symbol.toStringTag]}(${this.device.id})`;
+  }
+
+  /** @internal */
+  constructor(device: Device) {
+    this.device = device;
+  }
+
+  /** Requests a {@link Shader} from the cache, creating a new Shader only if necessary. */
+  createShader(props: ShaderProps): Shader {
+    if (!this.device.props._cacheShaders) {
+      return this.device.createShader(props);
+    }
+
+    const key = this._hashShader(props);
+
+    let cacheEntry = this._cache[key];
+    if (!cacheEntry) {
+      const resource = this.device.createShader({
+        ...props,
+        id: props.id ? `${props.id}-cached` : undefined
+      });
+      this._cache[key] = cacheEntry = {resource, useCount: 1};
+      if (this.device.props.debugFactories) {
+        log.log(3, `${this}: Created new shader ${resource.id}`)();
+      }
+    } else {
+      cacheEntry.useCount++;
+      if (this.device.props.debugFactories) {
+        log.log(
+          3,
+          `${this}: Reusing shader ${cacheEntry.resource.id} count=${cacheEntry.useCount}`
+        )();
+      }
+    }
+
+    return cacheEntry.resource;
+  }
+
+  /** Releases a previously-requested {@link Shader}, destroying it if no users remain. */
+  release(shader: Shader): void {
+    if (!this.device.props._cacheShaders) {
+      shader.destroy();
+      return;
+    }
+
+    const key = this._hashShader(shader);
+    const cacheEntry = this._cache[key];
+    if (cacheEntry) {
+      cacheEntry.useCount--;
+      if (cacheEntry.useCount === 0) {
+        if (this.device.props._destroyShaders) {
+          delete this._cache[key];
+          cacheEntry.resource.destroy();
+          if (this.device.props.debugFactories) {
+            log.log(3, `${this}: Releasing shader ${shader.id}, destroyed`)();
+          }
+        }
+      } else if (cacheEntry.useCount < 0) {
+        throw new Error(`ShaderFactory: Shader ${shader.id} released too many times`);
+      } else if (this.device.props.debugFactories) {
+        log.log(3, `${this}: Releasing shader ${shader.id} count=${cacheEntry.useCount}`)();
+      }
+    }
+  }
+
+  // PRIVATE
+
+  protected _hashShader(value: Shader | ShaderProps): string {
+    return `${value.stage}:${value.source}`;
+  }
+}