@luma.gl/engine 9.3.0-alpha.2 → 9.3.0-alpha.6

package/src/dynamic-texture/dynamic-texture.ts

@@ -1,7 +1,7 @@
 // luma.gl, MIT license
 // Copyright (c) vis.gl contributors
 
-import type {TextureProps, SamplerProps, TextureView, Device} from '@luma.gl/core';
+import type {TextureProps, SamplerProps, TextureView, Device, TextureFormat} from '@luma.gl/core';
 
 import {Texture, Sampler, log} from '@luma.gl/core';
 
@@ -29,6 +29,7 @@ import {
 
   // Helpers
   getTextureSizeFromData,
+  resolveTextureImageFormat,
   getTexture1DSubresources,
   getTexture2DSubresources,
   getTexture3DSubresources,
@@ -129,7 +130,7 @@ export class DynamicTexture {
   }
 
   /** @note Fire and forget; caller can await `ready` */
-  async initAsync(originalPropsWithAsyncData: TextureDataAsyncProps): Promise<void> {
+  async initAsync(originalPropsWithAsyncData: DynamicTextureProps): Promise<void> {
     try {
       // TODO - Accept URL string for 2D: turn into ExternalImage promise
       // const dataProps =
@@ -139,6 +140,11 @@ export class DynamicTexture {
 
       const propsWithSyncData = await this._loadAllData(originalPropsWithAsyncData);
       this._checkNotDestroyed();
+      const subresources = propsWithSyncData.data ? getTextureSubresources(propsWithSyncData) : [];
+      const userProvidedFormat =
+        'format' in originalPropsWithAsyncData && originalPropsWithAsyncData.format !== undefined;
+      const userProvidedUsage =
+        'usage' in originalPropsWithAsyncData && originalPropsWithAsyncData.usage !== undefined;
 
       // Deduce size when not explicitly provided
       // TODO - what about depth?
@@ -160,18 +166,44 @@ export class DynamicTexture {
         throw new Error(`${this} size could not be determined or was zero`);
       }
 
+      // Normalize caller-provided subresources into one validated mip chain description.
+      const textureData = analyzeTextureSubresources(this.device, subresources, size, {
+        format: userProvidedFormat ? originalPropsWithAsyncData.format : undefined
+      });
+      const resolvedFormat = textureData.format ?? this.props.format;
+
       // Create a minimal TextureProps and validate via `satisfies`
       const baseTextureProps = {
         ...this.props,
         ...size,
+        format: resolvedFormat,
         mipLevels: 1, // temporary; updated below
         data: undefined
       } satisfies TextureProps;
 
+      if (this.device.isTextureFormatCompressed(resolvedFormat) && !userProvidedUsage) {
+        baseTextureProps.usage = Texture.SAMPLE | Texture.COPY_DST;
+      }
+
+      // Explicit mip arrays take ownership of the mip chain; otherwise we may auto-generate it.
+      const shouldGenerateMipmaps =
+        this.props.mipmaps &&
+        !textureData.hasExplicitMipChain &&
+        !this.device.isTextureFormatCompressed(resolvedFormat);
+
+      if (this.device.type === 'webgpu' && shouldGenerateMipmaps) {
+        const requiredUsage =
+          this.props.dimension === '3d'
+            ? Texture.SAMPLE | Texture.STORAGE | Texture.COPY_DST | Texture.COPY_SRC
+            : Texture.SAMPLE | Texture.RENDER | Texture.COPY_DST | Texture.COPY_SRC;
+        baseTextureProps.usage |= requiredUsage;
+      }
+
       // Compute mip levels (auto clamps to max)
       const maxMips = this.device.getMipLevelCount(baseTextureProps.width, baseTextureProps.height);
-      const desired =
-        this.props.mipLevels === 'auto'
+      const desired = textureData.hasExplicitMipChain
+        ? textureData.mipLevels
+        : this.props.mipLevels === 'auto'
           ? maxMips
           : Math.max(1, Math.min(maxMips, this.props.mipLevels ?? 1));
 
@@ -182,33 +214,15 @@ export class DynamicTexture {
       this._view = this.texture.view;
 
       // Upload data if provided
-      if (propsWithSyncData.data) {
-        switch (propsWithSyncData.dimension) {
-          case '1d':
-            this.setTexture1DData(propsWithSyncData.data);
-            break;
-          case '2d':
-            this.setTexture2DData(propsWithSyncData.data);
-            break;
-          case '3d':
-            this.setTexture3DData(propsWithSyncData.data);
-            break;
-          case '2d-array':
-            this.setTextureArrayData(propsWithSyncData.data);
-            break;
-          case 'cube':
-            this.setTextureCubeData(propsWithSyncData.data);
-            break;
-          case 'cube-array':
-            this.setTextureCubeArrayData(propsWithSyncData.data);
-            break;
-          default: {
-            throw new Error(`Unhandled dimension ${propsWithSyncData.dimension}`);
-          }
-        }
+      if (textureData.subresources.length) {
+        this._setTextureSubresources(textureData.subresources);
       }
 
-      if (this.props.mipmaps) {
+      if (this.props.mipmaps && !textureData.hasExplicitMipChain && !shouldGenerateMipmaps) {
+        log.warn(`${this} skipping auto-generated mipmaps for compressed texture format`)();
+      }
+
+      if (shouldGenerateMipmaps) {
         this.generateMipmaps();
       }
 
@@ -234,14 +248,12 @@ export class DynamicTexture {
   }
 
   generateMipmaps(): void {
-    // Call the WebGL-style mipmap generation helper
-    // WebGL implementation generates mipmaps, WebGPU logs a warning
     if (this.device.type === 'webgl') {
       this.texture.generateMipmapsWebGL();
+    } else if (this.device.type === 'webgpu') {
+      this.device.generateMipmapsWebGPU(this.texture);
     } else {
-      log.warn(
-        'Mipmap generation not yet implemented on WebGPU: your texture data will not be correctly initialized'
-      );
+      log.warn(`${this} mipmaps not supported on ${this.device.type}`);
     }
   }
 
@@ -334,7 +346,7 @@ export class DynamicTexture {
   }
 
   /** Cube array: multiple cubes (faces×layers), each face may carry multiple mips */
-  private setTextureCubeArrayData(data: TextureCubeArrayData): void {
+  setTextureCubeArrayData(data: TextureCubeArrayData): void {
     if (this.texture.props.dimension !== 'cube-array') {
       throw new Error(`${this} is not cube-array`);
     }
@@ -359,10 +371,21 @@ export class DynamicTexture {
           this.texture.copyExternalImage({image, z, mipLevel, flipY});
           break;
         case 'texture-data':
-          const {data} = subresource;
-          // TODO - we are throwing away some of the info in data.
-          // Did we not need it in the first place? Can we use it to validate?
-          this.texture.copyImageData({data: data.data, z, mipLevel});
+          const {data, textureFormat} = subresource;
+          if (textureFormat && textureFormat !== this.texture.format) {
+            throw new Error(
+              `${this} mip level ${mipLevel} uses format "${textureFormat}" but texture format is "${this.texture.format}"`
+            );
+          }
+          this.texture.writeData(data.data, {
+            x: 0,
+            y: 0,
+            z,
+            width: data.width,
+            height: data.height,
+            depthOrArrayLayers: 1,
+            mipLevel
+          });
           break;
         default:
           throw new Error('Unsupported 2D mip-level payload');
@@ -399,6 +422,192 @@ export class DynamicTexture {
   };
 }
 
+type TextureSubresourceAnalysis = {
+  readonly subresources: TextureSubresource[];
+  readonly mipLevels: number;
+  readonly format?: TextureFormat;
+  readonly hasExplicitMipChain: boolean;
+};
+
+// Flatten dimension-specific texture data into one list of uploadable subresources.
+function getTextureSubresources(props: TextureDataProps): TextureSubresource[] {
+  if (!props.data) {
+    return [];
+  }
+
+  switch (props.dimension) {
+    case '1d':
+      return getTexture1DSubresources(props.data);
+    case '2d':
+      return getTexture2DSubresources(0, props.data);
+    case '3d':
+      return getTexture3DSubresources(props.data);
+    case '2d-array':
+      return getTextureArraySubresources(props.data);
+    case 'cube':
+      return getTextureCubeSubresources(props.data);
+    case 'cube-array':
+      return getTextureCubeArraySubresources(props.data);
+    default:
+      throw new Error(`Unhandled dimension ${(props as TextureDataProps).dimension}`);
+  }
+}
+
+// Resolve a consistent texture format and the longest mip chain valid across all slices.
+function analyzeTextureSubresources(
+  device: Device,
+  subresources: TextureSubresource[],
+  size: {width: number; height: number},
+  options: {format?: TextureFormat}
+): TextureSubresourceAnalysis {
+  if (subresources.length === 0) {
+    return {
+      subresources,
+      mipLevels: 1,
+      format: options.format,
+      hasExplicitMipChain: false
+    };
+  }
+
+  const groupedSubresources = new Map<number, TextureSubresource[]>();
+  for (const subresource of subresources) {
+    const group = groupedSubresources.get(subresource.z) ?? [];
+    group.push(subresource);
+    groupedSubresources.set(subresource.z, group);
+  }
+
+  const hasExplicitMipChain = subresources.some(subresource => subresource.mipLevel > 0);
+  let resolvedFormat = options.format;
+  let resolvedMipLevels = Number.POSITIVE_INFINITY;
+  const validSubresources: TextureSubresource[] = [];
+
+  for (const [z, sliceSubresources] of groupedSubresources) {
+    // Validate each slice independently, then keep only the mip levels that are valid everywhere.
+    const sortedSubresources = [...sliceSubresources].sort(
+      (left, right) => left.mipLevel - right.mipLevel
+    );
+    const baseLevel = sortedSubresources[0];
+    if (!baseLevel || baseLevel.mipLevel !== 0) {
+      throw new Error(`DynamicTexture: slice ${z} is missing mip level 0`);
+    }
+
+    const baseSize = getTextureSubresourceSize(device, baseLevel);
+    if (baseSize.width !== size.width || baseSize.height !== size.height) {
+      throw new Error(
+        `DynamicTexture: slice ${z} base level dimensions ${baseSize.width}x${baseSize.height} do not match expected ${size.width}x${size.height}`
+      );
+    }
+
+    const baseFormat = getTextureSubresourceFormat(baseLevel);
+    if (baseFormat) {
+      if (resolvedFormat && resolvedFormat !== baseFormat) {
+        throw new Error(
+          `DynamicTexture: slice ${z} base level format "${baseFormat}" does not match texture format "${resolvedFormat}"`
+        );
+      }
+      resolvedFormat = baseFormat;
+    }
+
+    const mipLevelLimit =
+      resolvedFormat && device.isTextureFormatCompressed(resolvedFormat)
+        ? // Block-compressed formats cannot have mips smaller than a single compression block.
+          getMaxCompressedMipLevels(device, baseSize.width, baseSize.height, resolvedFormat)
+        : device.getMipLevelCount(baseSize.width, baseSize.height);
+
+    let validMipLevelsForSlice = 0;
+    for (
+      let expectedMipLevel = 0;
+      expectedMipLevel < sortedSubresources.length;
+      expectedMipLevel++
+    ) {
+      const subresource = sortedSubresources[expectedMipLevel];
+      // Stop at the first gap so callers can provide extra trailing data without breaking creation.
+      if (!subresource || subresource.mipLevel !== expectedMipLevel) {
+        break;
+      }
+      if (expectedMipLevel >= mipLevelLimit) {
+        break;
+      }
+
+      const subresourceSize = getTextureSubresourceSize(device, subresource);
+      const expectedWidth = Math.max(1, baseSize.width >> expectedMipLevel);
+      const expectedHeight = Math.max(1, baseSize.height >> expectedMipLevel);
+      if (subresourceSize.width !== expectedWidth || subresourceSize.height !== expectedHeight) {
+        break;
+      }
+
+      const subresourceFormat = getTextureSubresourceFormat(subresource);
+      if (subresourceFormat) {
+        if (!resolvedFormat) {
+          resolvedFormat = subresourceFormat;
+        }
+        // Later mip levels must stay on the same format as the validated base level.
+        if (subresourceFormat !== resolvedFormat) {
+          break;
+        }
+      }
+
+      validMipLevelsForSlice++;
+      validSubresources.push(subresource);
+    }
+
+    resolvedMipLevels = Math.min(resolvedMipLevels, validMipLevelsForSlice);
+  }
+
+  const mipLevels = Number.isFinite(resolvedMipLevels) ? Math.max(1, resolvedMipLevels) : 1;
+
+  return {
+    // Keep every slice trimmed to the same mip count so the texture shape stays internally consistent.
+    subresources: validSubresources.filter(subresource => subresource.mipLevel < mipLevels),
+    mipLevels,
+    format: resolvedFormat,
+    hasExplicitMipChain
+  };
+}
+
+// Read the per-level format using the transitional textureFormat -> format fallback rules.
+function getTextureSubresourceFormat(subresource: TextureSubresource): TextureFormat | undefined {
+  if (subresource.type !== 'texture-data') {
+    return undefined;
+  }
+  return subresource.textureFormat ?? resolveTextureImageFormat(subresource.data);
+}
+
+// Resolve dimensions from either raw bytes or external-image subresources.
+function getTextureSubresourceSize(
+  device: Device,
+  subresource: TextureSubresource
+): {width: number; height: number} {
+  switch (subresource.type) {
+    case 'external-image':
+      return device.getExternalImageSize(subresource.image);
+    case 'texture-data':
+      return {width: subresource.data.width, height: subresource.data.height};
+    default:
+      throw new Error('Unsupported texture subresource');
+  }
+}
+
+// Count the mip levels that stay at or above one compression block in each dimension.
+function getMaxCompressedMipLevels(
+  device: Device,
+  baseWidth: number,
+  baseHeight: number,
+  format: TextureFormat
+): number {
+  const {blockWidth = 1, blockHeight = 1} = device.getTextureFormatInfo(format);
+  let mipLevels = 1;
+  for (let mipLevel = 1; ; mipLevel++) {
+    const width = Math.max(1, baseWidth >> mipLevel);
+    const height = Math.max(1, baseHeight >> mipLevel);
+    if (width < blockWidth || height < blockHeight) {
+      break;
+    }
+    mipLevels++;
+  }
+  return mipLevels;
+}
+
 // HELPERS
 
 /** Resolve all promises in a nested data structure */

package/src/dynamic-texture/texture-data.ts

@@ -9,6 +9,8 @@ export type TextureImageSource = ExternalImage;
  * additional optional fields can describe compressed texture data.
  */
 export type TextureImageData = {
+  /** Preferred WebGPU style format string. */
+  textureFormat?: TextureFormat;
   /** WebGPU style format string. Defaults to 'rgba8unorm' */
   format?: TextureFormat;
   /** Typed Array with the bytes of the image. @note beware row byte alignment requirements */
@@ -104,6 +106,7 @@ export type TextureSubresource = {
   | {
       type: 'texture-data';
       data: TextureImageData;
+      textureFormat?: TextureFormat;
     }
 );
 
@@ -184,6 +187,16 @@ function isTextureImageData(data: TextureMipLevelData): data is TextureImageData
   );
 }
 
+export function resolveTextureImageFormat(data: TextureImageData): TextureFormat | undefined {
+  const {textureFormat, format} = data;
+  if (textureFormat && format && textureFormat !== format) {
+    throw new Error(
+      `Conflicting texture formats "${textureFormat}" and "${format}" provided for the same mip level`
+    );
+  }
+  return textureFormat ?? format;
+}
+
 /** Resolve size for a single mip-level datum */
 // function getTextureMipLevelSizeFromData(data: TextureMipLevelData): {
 //   width: number;
@@ -249,6 +262,7 @@ export function getTexture2DSubresources(
       subresources.push({
         type: 'texture-data',
         data: imageData,
+        textureFormat: resolveTextureImageFormat(imageData),
         z,
         mipLevel
       });
@@ -294,7 +308,7 @@ export function getTextureCubeArraySubresources(data: TextureCubeArrayData): Tex
   data.forEach((cubeData, cubeIndex) => {
     for (const [face, faceData] of Object.entries(cubeData)) {
       const faceDepth = getCubeArrayFaceIndex(cubeIndex, face as TextureCubeFace);
-      getTexture2DSubresources(faceDepth, faceData);
+      subresources.push(...getTexture2DSubresources(faceDepth, faceData));
     }
   });
   return subresources;

package/src/factories/pipeline-factory.ts

@@ -2,15 +2,14 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {RenderPipelineProps, ComputePipelineProps} from '@luma.gl/core';
-import {Device, RenderPipeline, ComputePipeline, log} from '@luma.gl/core';
+import type {RenderPipelineProps, ComputePipelineProps, SharedRenderPipeline} from '@luma.gl/core';
+import {Device, RenderPipeline, ComputePipeline, Resource, log} from '@luma.gl/core';
 import type {EngineModuleState} from '../types';
 import {uid} from '../utils/uid';
 
 export type PipelineFactoryProps = RenderPipelineProps;
 
-type RenderPipelineCacheItem = {pipeline: RenderPipeline; useCount: number};
-type ComputePipelineCacheItem = {pipeline: ComputePipeline; useCount: number};
+type CacheItem<ResourceT extends Resource<any>> = {resource: ResourceT; useCount: number};
 
 /**
  * Efficiently creates / caches pipelines
@@ -26,14 +25,12 @@ export class PipelineFactory {
   }
 
   readonly device: Device;
-  readonly cachingEnabled: boolean;
-  readonly destroyPolicy: 'unused' | 'never';
-  readonly debug: boolean;
 
   private _hashCounter: number = 0;
   private readonly _hashes: Record<string, number> = {};
-  private readonly _renderPipelineCache: Record<string, RenderPipelineCacheItem> = {};
-  private readonly _computePipelineCache: Record<string, ComputePipelineCacheItem> = {};
+  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';
@@ -45,14 +42,11 @@ export class PipelineFactory {
 
   constructor(device: Device) {
     this.device = device;
-    this.cachingEnabled = device.props._cachePipelines;
-    this.destroyPolicy = device.props._cacheDestroyPolicy;
-    this.debug = device.props.debugFactories;
   }
 
   /** Return a RenderPipeline matching supplied props. Reuses an equivalent pipeline if already created. */
   createRenderPipeline(props: RenderPipelineProps): RenderPipeline {
-    if (!this.cachingEnabled) {
+    if (!this.device.props._cachePipelines) {
       return this.device.createRenderPipeline(props);
     }
 
@@ -61,23 +55,28 @@ export class PipelineFactory {
     const cache = this._renderPipelineCache;
     const hash = this._hashRenderPipeline(allProps);
 
-    let pipeline: RenderPipeline = cache[hash]?.pipeline;
+    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')
+        id: allProps.id ? `${allProps.id}-cached` : uid('unnamed-cached'),
+        _sharedRenderPipeline: sharedRenderPipeline
       });
       pipeline.hash = hash;
-      cache[hash] = {pipeline, useCount: 1};
-      if (this.debug) {
+      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.debug) {
+      if (this.device.props.debugFactories) {
         log.log(
           3,
-          `${this}: ${cache[hash].pipeline} reused, count=${cache[hash].useCount}, (id=${props.id})`
+          `${this}: ${cache[hash].resource} reused, count=${cache[hash].useCount}, (id=${props.id})`
         )();
       }
     }
@@ -87,7 +86,7 @@ export class PipelineFactory {
 
   /** Return a ComputePipeline matching supplied props. Reuses an equivalent pipeline if already created. */
   createComputePipeline(props: ComputePipelineProps): ComputePipeline {
-    if (!this.cachingEnabled) {
+    if (!this.device.props._cachePipelines) {
       return this.device.createComputePipeline(props);
     }
 
@@ -96,23 +95,23 @@ export class PipelineFactory {
     const cache = this._computePipelineCache;
     const hash = this._hashComputePipeline(allProps);
 
-    let pipeline: ComputePipeline = cache[hash]?.pipeline;
+    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] = {pipeline, useCount: 1};
-      if (this.debug) {
+      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.debug) {
+      if (this.device.props.debugFactories) {
         log.log(
           3,
-          `${this}: ${cache[hash].pipeline} reused, count=${cache[hash].useCount}, (id=${props.id})`
+          `${this}: ${cache[hash].resource} reused, count=${cache[hash].useCount}, (id=${props.id})`
         )();
       }
     }
@@ -121,7 +120,7 @@ export class PipelineFactory {
   }
 
   release(pipeline: RenderPipeline | ComputePipeline): void {
-    if (!this.cachingEnabled) {
+    if (!this.device.props._cachePipelines) {
       pipeline.destroy();
       return;
     }
@@ -132,40 +131,72 @@ export class PipelineFactory {
     cache[hash].useCount--;
     if (cache[hash].useCount === 0) {
       this._destroyPipeline(pipeline);
-      if (this.debug) {
+      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.debug) {
+    } 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 (depending on destroy policy) */
+  /** 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);
 
-    switch (this.destroyPolicy) {
-      case 'never':
-        return false;
-      case 'unused':
-        delete cache[pipeline.hash];
-        pipeline.destroy();
-        return true;
+    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, RenderPipelineCacheItem> | Record<string, ComputePipelineCacheItem> {
+  ): Record<string, CacheItem<RenderPipeline>> | Record<string, CacheItem<ComputePipeline>> {
     let cache:
-      | Record<string, RenderPipelineCacheItem>
-      | Record<string, ComputePipelineCacheItem>
+      | Record<string, CacheItem<RenderPipeline>>
+      | Record<string, CacheItem<ComputePipeline>>
       | undefined;
     if (pipeline instanceof ComputePipeline) {
       cache = this._computePipelineCache;
@@ -193,18 +224,16 @@ export class PipelineFactory {
   private _hashRenderPipeline(props: RenderPipelineProps): string {
     const vsHash = props.vs ? this._getHash(props.vs.source) : 0;
     const fsHash = props.fs ? this._getHash(props.fs.source) : 0;
-
-    // WebGL specific
-    // const {varyings = [], bufferMode = {}} = props;
-    // const varyingHashes = varyings.map((v) => this._getHash(v));
-    const varyingHash = '-'; // `${varyingHashes.join('/')}B${bufferMode}`
+    const varyingHash = this._getWebGLVaryingHash(props);
     const bufferLayoutHash = this._getHash(JSON.stringify(props.bufferLayout));
 
     const {type} = this.device;
     switch (type) {
       case 'webgl':
-        // WebGL is more dynamic
-        return `${type}/R/${vsHash}/${fsHash}V${varyingHash}BL${bufferLayoutHash}`;
+        // WebGL wrappers preserve default topology and parameter semantics for direct
+        // callers, even though the underlying linked program may be shared separately.
+        const webglParameterHash = this._getHash(JSON.stringify(props.parameters));
+        return `${type}/R/${vsHash}/${fsHash}V${varyingHash}T${props.topology}P${webglParameterHash}BL${bufferLayoutHash}`;
 
       case 'webgpu':
       default:
@@ -216,10 +245,22 @@ export class PipelineFactory {
     }
   }
 
+  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}));
+  }
 }