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

package/src/adapter/resources/texture.ts

@@ -2,14 +2,20 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {TypedArray} from '@math.gl/types';
-import type {Device} from '../device';
-import type {TextureFormat} from '../../shadertypes/textures/texture-formats';
-import type {TextureView, TextureViewProps} from './texture-view';
-import {Resource, ResourceProps} from './resource';
-import {Sampler, SamplerProps} from './sampler';
-import {ExternalImage} from '../../image-utils/image-types';
+import {type TypedArray} from '@math.gl/types';
+import {type Device} from '../device';
+import {
+  type TextureFormat,
+  type TextureMemoryLayout,
+  type TextureFormatInfo
+} from '../../shadertypes/texture-types/texture-formats';
+import {type ExternalImage} from '../../shadertypes/image-types/image-types';
+import {type TextureView, type TextureViewProps} from './texture-view';
+import {Resource, type ResourceProps} from './resource';
+import {Sampler, type SamplerProps} from './sampler';
+import {Buffer} from './buffer';
 import {log} from '../../utils/log';
+import {textureFormatDecoder} from '../../shadertypes/texture-types/texture-format-decoder';
 
 /** Options for Texture.copyExternalImage */
 export type CopyExternalImageOptions = {
@@ -49,10 +55,18 @@ export type CopyImageDataOptions = {
   data: ArrayBuffer | SharedArrayBuffer | ArrayBufferView;
   /** Offset into the data (in addition to any offset built-in to the ArrayBufferView) */
   byteOffset?: number;
-  /** The stride, in bytes, between the beginning of each texel block row and the subsequent texel block row. Required if there are multiple texel block rows (i.e. the copy height or depth is more than one block). */
+  /** The stride, in bytes, between successive texel rows in the CPU source data. Tightly packed uploads can omit this. */
   bytesPerRow?: number;
-  /** Number or rows per image (needed if multiple images are being set) */
+  /** Number of rows that make up one image when uploading multiple layers or depth slices from CPU memory. */
   rowsPerImage?: number;
+  /** Width to copy */
+  width?: number;
+  /** Height to copy */
+  height?: number;
+  /** Copy depth or number of layers */
+  depthOrArrayLayers?: number;
+  /** @deprecated Use `depthOrArrayLayers` */
+  depth?: number;
   /** Start copying into offset x (default 0) */
   x?: number;
   /** Start copying into offset y (default 0) */
@@ -65,18 +79,62 @@ export type CopyImageDataOptions = {
   aspect?: 'all' | 'stencil-only' | 'depth-only';
 };
 
-const BASE_DIMENSIONS: Record<string, '1d' | '2d' | '3d'> = {
+export type TextureReadOptions = {
+  /** Start reading from offset x (default 0) */
+  x?: number;
+  /** Start reading from offset y (default 0) */
+  y?: number;
+  /** Start reading from layer / depth slice z (default 0) */
+  z?: number;
+  /** Width of the region to read. Defaults to the mip width. */
+  width?: number;
+  /** Height of the region to read. Defaults to the mip height. */
+  height?: number;
+  /** Number of array layers or depth slices to read. Defaults to 1. */
+  depthOrArrayLayers?: number;
+  /** Which mip-level to read from (default 0) */
+  mipLevel?: number;
+  /** When reading from depth stencil textures (default 'all') */
+  aspect?: 'all' | 'stencil-only' | 'depth-only';
+};
+
+export type TextureWriteOptions = {
+  /** Offset into the source data or buffer, in bytes. */
+  byteOffset?: number;
+  /** The stride, in bytes, between successive texel rows in the source data or buffer. */
+  bytesPerRow?: number;
+  /** The number of rows that make up one image when writing multiple layers or slices. */
+  rowsPerImage?: number;
+  /** Start writing into offset x (default 0) */
+  x?: number;
+  /** Start writing into offset y (default 0) */
+  y?: number;
+  /** Start writing into layer / depth slice z (default 0) */
+  z?: number;
+  /** Width of the region to write. Defaults to the mip width. */
+  width?: number;
+  /** Height of the region to write. Defaults to the mip height. */
+  height?: number;
+  /** Number of array layers or depth slices to write. Defaults to 1, or the full mip depth for 3D textures. */
+  depthOrArrayLayers?: number;
+  /** Which mip-level to write into (default 0) */
+  mipLevel?: number;
+  /** When writing into depth stencil textures (default 'all') */
+  aspect?: 'all' | 'stencil-only' | 'depth-only';
+};
+
+const BASE_DIMENSIONS = {
   '1d': '1d',
   '2d': '2d',
   '2d-array': '2d',
   cube: '2d',
   'cube-array': '2d',
   '3d': '3d'
-};
+} as const satisfies Record<string, '1d' | '2d' | '3d'>;
 
 /** Texture properties */
 export type TextureProps = ResourceProps & {
-  /** @deprecated Use AsyncTexture to create textures with data. */
+  /** @deprecated Use DynamicTexture to create textures with data. */
   data?: ExternalImage | TypedArray | null;
   /** Dimension of this texture. Defaults to '2d' */
   dimension?: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d';
@@ -130,19 +188,28 @@ export abstract class Texture extends Resource<TextureProps> {
   /** format of this texture */
   readonly format: TextureFormat;
   /** width in pixels of this texture */
-  width: number;
+  readonly width: number;
   /** height in pixels of this texture */
-  height: number;
+  readonly height: number;
   /** depth of this texture */
-  depth: number;
+  readonly depth: number;
   /** mip levels in this texture */
-  mipLevels: number;
+  readonly mipLevels: number;
+  /** sample count */
+  readonly samples: number;
+  /** Rows are multiples of this length, padded with extra bytes if needed */
+  readonly byteAlignment: number;
   /** Default sampler for this texture */
   abstract sampler: Sampler;
   /** Default view for this texture */
   abstract view: TextureView;
 
-  /** "Time" of last update. Monotonically increasing timestamp. TODO move to AsyncTexture? */
+  /** The ready promise is always resolved. It is provided for type compatibility with DynamicTexture. */
+  readonly ready: Promise<Texture> = Promise.resolve(this);
+  /** isReady is always true. It is provided for type compatibility with DynamicTexture. */
+  readonly isReady: boolean = true;
+
+  /** "Time" of last update. Monotonically increasing timestamp. TODO move to DynamicTexture? */
   updateTimestamp: number;
 
   override get [Symbol.toStringTag](): string {
@@ -154,7 +221,7 @@ export abstract class Texture extends Resource<TextureProps> {
   }
 
   /** Do not use directly. Create with device.createTexture() */
-  constructor(device: Device, props: TextureProps) {
+  constructor(device: Device, props: TextureProps, backendProps?: {byteAlignment?: number}) {
     props = Texture.normalizeProps(device, props);
     super(device, props, Texture.defaultProps);
     this.dimension = this.props.dimension;
@@ -166,6 +233,11 @@ export abstract class Texture extends Resource<TextureProps> {
     this.height = this.props.height;
     this.depth = this.props.depth;
     this.mipLevels = this.props.mipLevels;
+    this.samples = this.props.samples || 1;
+
+    if (this.dimension === 'cube') {
+      this.depth = 6;
+    }
 
     // Calculate size, if not provided
     if (this.props.width === undefined || this.props.height === undefined) {
@@ -178,38 +250,149 @@ export abstract class Texture extends Resource<TextureProps> {
         this.height = 1;
         if (this.props.width === undefined || this.props.height === undefined) {
           log.warn(
-            `${this} created with undefined width or height. This is deprecated. Use AsyncTexture instead.`
+            `${this} created with undefined width or height. This is deprecated. Use DynamicTexture instead.`
           )();
         }
       }
     }
 
+    this.byteAlignment = backendProps?.byteAlignment || 1;
+
     // TODO - perhaps this should be set on async write completion?
     this.updateTimestamp = device.incrementTimestamp();
   }
 
+  /**
+   * Create a new texture with the same parameters and optionally a different size
+   * @note Textures are immutable and cannot be resized after creation, but we can create a similar texture with the same parameters but a new size.
+   * @note Does not copy contents of the texture
+   */
+  clone(size?: {width: number; height: number}): Texture {
+    return this.device.createTexture({...this.props, ...size});
+  }
+
   /** Set sampler props associated with this texture */
   setSampler(sampler: Sampler | SamplerProps): void {
     this.sampler = sampler instanceof Sampler ? sampler : this.device.createSampler(sampler);
   }
+
   /** Create a texture view for this texture */
   abstract createView(props: TextureViewProps): TextureView;
+
   /** Copy an image (e.g an ImageBitmap) into the texture */
   abstract copyExternalImage(options: CopyExternalImageOptions): {width: number; height: number};
-  /** Copy raw image data (bytes) into the texture */
-  abstract copyImageData(options: CopyImageDataOptions): void;
-  /** Generate mipmaps (WebGL only) */
-  abstract generateMipmapsWebGL(): void;
 
   /**
-   * Create a new texture with the same parameters and optionally a different size
-   * @note Textures are immutable and cannot be resized after creation, but we can create a similar texture with the same parameters but a new size.
-   * @note Does not copy contents of the texture
+   * Copy raw image data (bytes) into the texture.
+   *
+   * @note Deprecated compatibility wrapper over {@link writeData}.
+   * @note Uses the same layout defaults and alignment rules as {@link writeData}.
+   * @note Tightly packed CPU uploads can omit `bytesPerRow` and `rowsPerImage`.
+   * @note If the CPU source rows are padded, pass explicit `bytesPerRow` and `rowsPerImage`.
+   * @deprecated Use writeData()
    */
-  clone(size?: {width: number; height: number}): Texture {
-    return this.device.createTexture({...this.props, ...size});
+  copyImageData(options: CopyImageDataOptions): void {
+    const {data, depth, ...writeOptions} = options;
+    this.writeData(data, {
+      ...writeOptions,
+      depthOrArrayLayers: writeOptions.depthOrArrayLayers ?? depth
+    });
+  }
+
+  /**
+   * Calculates the memory layout of the texture, required when reading and writing data.
+   * @return the backend-aligned linear layout, in particular bytesPerRow which includes any required padding for buffer copy/read paths
+   */
+  computeMemoryLayout(options_: TextureReadOptions = {}): TextureMemoryLayout {
+    const options = this._normalizeTextureReadOptions(options_);
+    const {width = this.width, height = this.height, depthOrArrayLayers = this.depth} = options;
+    const {format, byteAlignment} = this;
+
+    // TODO - does the overriding above make sense?
+    // return textureFormatDecoder.computeMemoryLayout(this);
+    return textureFormatDecoder.computeMemoryLayout({
+      format,
+      width,
+      height,
+      depth: depthOrArrayLayers,
+      byteAlignment
+    });
+  }
+
+  /**
+   * Read the contents of a texture into a GPU Buffer.
+   * @returns A Buffer containing the texture data.
+   *
+   * @note The memory layout of the texture data is determined by the texture format and dimensions.
+   * @note The application can call Texture.computeMemoryLayout() to compute the backend-aligned layout.
+   * @note The application can call Buffer.readAsync() to read the returned buffer on the CPU.
+   * @note The destination buffer must be supplied by the caller and must be large enough for the requested region.
+   * @note On WebGPU this corresponds to a texture-to-buffer copy and uses buffer-copy alignment rules.
+   * @note On WebGL, luma.gl emulates the same logical readback behavior.
+   */
+  readBuffer(options?: TextureReadOptions, buffer?: Buffer): Buffer {
+    throw new Error('readBuffer not implemented');
   }
 
+  /**
+   * Reads data from a texture into an ArrayBuffer.
+   * @returns An ArrayBuffer containing the texture data.
+   *
+   * @note The memory layout of the texture data is determined by the texture format and dimensions.
+   * @note The application can call Texture.computeMemoryLayout() to compute the layout.
+   * @deprecated Use Texture.readBuffer() with an explicit destination buffer, or DynamicTexture.readAsync() for convenience readback.
+   */
+  readDataAsync(options?: TextureReadOptions): Promise<ArrayBuffer> {
+    throw new Error('readBuffer not implemented');
+  }
+
+  /**
+   * Writes a GPU Buffer into a texture.
+   *
+   * @param buffer - Source GPU buffer.
+   * @param options - Destination subresource, extent, and source layout options.
+   * @note The memory layout of the texture data is determined by the texture format and dimensions.
+   * @note The application can call Texture.computeMemoryLayout() to compute the backend-aligned layout.
+   * @note On WebGPU this corresponds to a buffer-to-texture copy and uses buffer-copy alignment rules.
+   * @note On WebGL, luma.gl emulates the same destination and layout semantics.
+   */
+  writeBuffer(buffer: Buffer, options?: TextureWriteOptions): void {
+    throw new Error('readBuffer not implemented');
+  }
+
+  /**
+   * Writes an array buffer into a texture.
+   *
+   * @param data - Source texel data.
+   * @param options - Destination subresource, extent, and source layout options.
+   * @note If `bytesPerRow` and `rowsPerImage` are omitted, luma.gl computes a tightly packed CPU-memory layout for the requested region.
+   * @note On WebGPU this corresponds to `GPUQueue.writeTexture()` and does not implicitly pad rows to 256 bytes.
+   * @note On WebGL, padded CPU data is supported via the same `bytesPerRow` and `rowsPerImage` options.
+   */
+  writeData(
+    data: ArrayBuffer | SharedArrayBuffer | ArrayBufferView,
+    options?: TextureWriteOptions
+  ): void {
+    throw new Error('readBuffer not implemented');
+  }
+
+  // IMPLEMENTATION SPECIFIC
+
+  /**
+   * WebGL can read data synchronously.
+   * @note While it is convenient, the performance penalty is very significant
+   */
+  readDataSyncWebGL(options?: TextureReadOptions): ArrayBuffer | ArrayBufferView {
+    throw new Error('readDataSyncWebGL not available');
+  }
+
+  /** Generate mipmaps (WebGL only) */
+  generateMipmapsWebGL(): void {
+    throw new Error('generateMipmapsWebGL not available');
+  }
+
+  // HELPERS
+
   /** Ensure we have integer coordinates */
   protected static normalizeProps(device: Device, props: TextureProps): TextureProps {
     const newProps = {...props};
@@ -225,8 +408,6 @@ export abstract class Texture extends Resource<TextureProps> {
     return newProps;
   }
 
-  // HELPERS
-
   /** Initialize texture with supplied props */
   // eslint-disable-next-line max-statements
   _initializeData(data: TextureProps['data']): void {
@@ -263,40 +444,208 @@ export abstract class Texture extends Resource<TextureProps> {
   }
 
   _normalizeCopyImageDataOptions(options_: CopyImageDataOptions): Required<CopyImageDataOptions> {
-    const {width, height, depth} = this;
-    const options = {...Texture.defaultCopyDataOptions, width, height, depth, ...options_};
-
-    const info = this.device.getTextureFormatInfo(this.format);
-    if (!options_.bytesPerRow && !info.bytesPerPixel) {
-      throw new Error(`bytesPerRow must be provided for texture format ${this.format}`);
-    }
-    options.bytesPerRow = options_.bytesPerRow || width * (info.bytesPerPixel || 4);
-    options.rowsPerImage = options_.rowsPerImage || height;
-
-    // WebGL will error if we try to copy outside the bounds of the texture
-    // options.width = Math.min(options.width, this.width - options.x);
-    // options.height = Math.min(options.height, this.height - options.y);
-    return options;
+    const {data, depth, ...writeOptions} = options_;
+    const options = this._normalizeTextureWriteOptions({
+      ...writeOptions,
+      depthOrArrayLayers: writeOptions.depthOrArrayLayers ?? depth
+    });
+    return {data, depth: options.depthOrArrayLayers, ...options};
   }
 
   _normalizeCopyExternalImageOptions(
     options_: CopyExternalImageOptions
   ): Required<CopyExternalImageOptions> {
+    const optionsWithoutUndefined = Texture._omitUndefined(options_);
+    const mipLevel = optionsWithoutUndefined.mipLevel ?? 0;
+    const mipLevelSize = this._getMipLevelSize(mipLevel);
     const size = this.device.getExternalImageSize(options_.image);
-    const options = {...Texture.defaultCopyExternalImageOptions, ...size, ...options_};
+    const options = {
+      ...Texture.defaultCopyExternalImageOptions,
+      ...mipLevelSize,
+      ...size,
+      ...optionsWithoutUndefined
+    };
     // WebGL will error if we try to copy outside the bounds of the texture
-    options.width = Math.min(options.width, this.width - options.x);
-    options.height = Math.min(options.height, this.height - options.y);
+    options.width = Math.min(options.width, mipLevelSize.width - options.x);
+    options.height = Math.min(options.height, mipLevelSize.height - options.y);
+    options.depth = Math.min(options.depth, mipLevelSize.depthOrArrayLayers - options.z);
     return options;
   }
 
-  /** Default options */
+  _normalizeTextureReadOptions(options_: TextureReadOptions): Required<TextureReadOptions> {
+    const optionsWithoutUndefined = Texture._omitUndefined(options_);
+    const mipLevel = optionsWithoutUndefined.mipLevel ?? 0;
+    const mipLevelSize = this._getMipLevelSize(mipLevel);
+    const options = {
+      ...Texture.defaultTextureReadOptions,
+      ...mipLevelSize,
+      ...optionsWithoutUndefined
+    };
+    // WebGL will error if we try to copy outside the bounds of the texture
+    options.width = Math.min(options.width, mipLevelSize.width - options.x);
+    options.height = Math.min(options.height, mipLevelSize.height - options.y);
+    options.depthOrArrayLayers = Math.min(
+      options.depthOrArrayLayers,
+      mipLevelSize.depthOrArrayLayers - options.z
+    );
+    return options;
+  }
+
+  /**
+   * Normalizes a texture read request and validates the color-only readback contract used by the
+   * current texture read APIs. Supported dimensions are `2d`, `cube`, `cube-array`,
+   * `2d-array`, and `3d`.
+   *
+   * @throws if the texture format, aspect, or dimension is not supported by the first-pass
+   * color-read implementation.
+   */
+  protected _getSupportedColorReadOptions(
+    options_: TextureReadOptions
+  ): Required<TextureReadOptions> {
+    const options = this._normalizeTextureReadOptions(options_);
+    const formatInfo = textureFormatDecoder.getInfo(this.format);
+
+    this._validateColorReadAspect(options);
+    this._validateColorReadFormat(formatInfo);
+
+    switch (this.dimension) {
+      case '2d':
+      case 'cube':
+      case 'cube-array':
+      case '2d-array':
+      case '3d':
+        return options;
+
+      default:
+        throw new Error(`${this} color readback does not support ${this.dimension} textures`);
+    }
+  }
+
+  /** Validates that a read request targets the full color aspect of the texture. */
+  protected _validateColorReadAspect(options: Required<TextureReadOptions>): void {
+    if (options.aspect !== 'all') {
+      throw new Error(`${this} color readback only supports aspect 'all'`);
+    }
+  }
+
+  /** Validates that a read request targets an uncompressed color-renderable texture format. */
+  protected _validateColorReadFormat(formatInfo: TextureFormatInfo): void {
+    if (formatInfo.compressed) {
+      throw new Error(
+        `${this} color readback does not support compressed formats (${this.format})`
+      );
+    }
+
+    switch (formatInfo.attachment) {
+      case 'color':
+        return;
+
+      case 'depth':
+        throw new Error(`${this} color readback does not support depth formats (${this.format})`);
+
+      case 'stencil':
+        throw new Error(`${this} color readback does not support stencil formats (${this.format})`);
+
+      case 'depth-stencil':
+        throw new Error(
+          `${this} color readback does not support depth-stencil formats (${this.format})`
+        );
+
+      default:
+        throw new Error(`${this} color readback does not support format ${this.format}`);
+    }
+  }
+
+  _normalizeTextureWriteOptions(options_: TextureWriteOptions): Required<TextureWriteOptions> {
+    const optionsWithoutUndefined = Texture._omitUndefined(options_);
+    const mipLevel = optionsWithoutUndefined.mipLevel ?? 0;
+    const mipLevelSize = this._getMipLevelSize(mipLevel);
+    const options = {
+      ...Texture.defaultTextureWriteOptions,
+      ...mipLevelSize,
+      ...optionsWithoutUndefined
+    };
+
+    options.width = Math.min(options.width, mipLevelSize.width - options.x);
+    options.height = Math.min(options.height, mipLevelSize.height - options.y);
+    options.depthOrArrayLayers = Math.min(
+      options.depthOrArrayLayers,
+      mipLevelSize.depthOrArrayLayers - options.z
+    );
+
+    const layout = textureFormatDecoder.computeMemoryLayout({
+      format: this.format,
+      width: options.width,
+      height: options.height,
+      depth: options.depthOrArrayLayers,
+      byteAlignment: this.byteAlignment
+    });
+
+    const minimumBytesPerRow = layout.bytesPerPixel * options.width;
+    options.bytesPerRow = optionsWithoutUndefined.bytesPerRow ?? layout.bytesPerRow;
+    options.rowsPerImage = optionsWithoutUndefined.rowsPerImage ?? options.height;
+
+    if (options.bytesPerRow < minimumBytesPerRow) {
+      throw new Error(
+        `bytesPerRow (${options.bytesPerRow}) must be at least ${minimumBytesPerRow} for ${this.format}`
+      );
+    }
+    if (options.rowsPerImage < options.height) {
+      throw new Error(
+        `rowsPerImage (${options.rowsPerImage}) must be at least ${options.height} for ${this.format}`
+      );
+    }
+
+    const bytesPerPixel = this.device.getTextureFormatInfo(this.format).bytesPerPixel;
+    if (bytesPerPixel && options.bytesPerRow % bytesPerPixel !== 0) {
+      throw new Error(
+        `bytesPerRow (${options.bytesPerRow}) must be a multiple of bytesPerPixel (${bytesPerPixel}) for ${this.format}`
+      );
+    }
+
+    return options;
+  }
+
+  protected _getMipLevelSize(
+    mipLevel: number
+  ): Required<Pick<TextureReadOptions, 'width' | 'height' | 'depthOrArrayLayers'>> {
+    const width = Math.max(1, this.width >> mipLevel);
+    const height = this.baseDimension === '1d' ? 1 : Math.max(1, this.height >> mipLevel);
+    const depthOrArrayLayers =
+      this.dimension === '3d' ? Math.max(1, this.depth >> mipLevel) : this.depth;
+
+    return {width, height, depthOrArrayLayers};
+  }
+
+  protected getAllocatedByteLength(): number {
+    let allocatedByteLength = 0;
+
+    for (let mipLevel = 0; mipLevel < this.mipLevels; mipLevel++) {
+      const {width, height, depthOrArrayLayers} = this._getMipLevelSize(mipLevel);
+      allocatedByteLength += textureFormatDecoder.computeMemoryLayout({
+        format: this.format,
+        width,
+        height,
+        depth: depthOrArrayLayers,
+        byteAlignment: 1
+      }).byteLength;
+    }
+
+    return allocatedByteLength * this.samples;
+  }
+
+  protected static _omitUndefined<T extends object>(options: T): Partial<T> {
+    return Object.fromEntries(
+      Object.entries(options).filter(([, value]) => value !== undefined)
+    ) as Partial<T>;
+  }
+
   static override defaultProps: Required<TextureProps> = {
     ...Resource.defaultProps,
     data: null,
     dimension: '2d',
     format: 'rgba8unorm',
-    usage: Texture.TEXTURE | Texture.RENDER_ATTACHMENT | Texture.COPY_DST,
+    usage: Texture.SAMPLE | Texture.RENDER | Texture.COPY_DST,
     width: undefined!,
     height: undefined!,
     depth: 1,
@@ -311,6 +660,10 @@ export abstract class Texture extends Resource<TextureProps> {
     byteOffset: 0,
     bytesPerRow: undefined!,
     rowsPerImage: undefined!,
+    width: undefined!,
+    height: undefined!,
+    depthOrArrayLayers: undefined!,
+    depth: 1,
     mipLevel: 0,
     x: 0,
     y: 0,
@@ -335,4 +688,29 @@ export abstract class Texture extends Resource<TextureProps> {
     premultipliedAlpha: false,
     flipY: false
   };
+
+  protected static defaultTextureReadOptions: Required<TextureReadOptions> = {
+    x: 0,
+    y: 0,
+    z: 0,
+    width: undefined!,
+    height: undefined!,
+    depthOrArrayLayers: 1,
+    mipLevel: 0,
+    aspect: 'all'
+  };
+
+  protected static defaultTextureWriteOptions: Required<TextureWriteOptions> = {
+    byteOffset: 0,
+    bytesPerRow: undefined!,
+    rowsPerImage: undefined!,
+    x: 0,
+    y: 0,
+    z: 0,
+    width: undefined!,
+    height: undefined!,
+    depthOrArrayLayers: 1,
+    mipLevel: 0,
+    aspect: 'all'
+  };
 }

package/src/adapter/types/attachments.ts

@@ -6,7 +6,7 @@ import type {
   TextureFormatColor,
   TextureFormatDepthStencil,
   TextureFormat
-} from '../../shadertypes/textures/texture-formats';
+} from '../../shadertypes/texture-types/texture-formats';
 import type {Texture} from '../resources/texture'; // TextureView...
 import type {TextureView} from '../resources/texture-view'; // TextureView...
 

package/src/adapter/types/buffer-layout.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {VertexFormat} from '../../shadertypes/vertex-arrays/vertex-formats';
+import type {VertexFormat} from '../../shadertypes/vertex-types/vertex-formats';
 
 /**
  * Provides specific details about the memory layout of the actual buffers

package/src/adapter/types/parameters.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import {NumberArray4, NumberArray6} from '@math.gl/types';
-import {TextureFormatDepthStencil} from '../../shadertypes/textures/texture-formats';
+import {TextureFormatDepthStencil} from '../../shadertypes/texture-types/texture-formats';
 
 export type CompareFunction =
   | 'never'
@@ -102,6 +102,8 @@ export type DepthStencilParameters = {
   depthCompare?: CompareFunction;
   /** The format of depthStencilAttachment this GPURenderPipeline will be compatible with. */
   depthFormat?: TextureFormatDepthStencil;
+  /** Depth value used when clearing depth buffers. */
+  clearDepth?: number;
 
   /** Bitmask controlling which depthStencilAttachment stencil value bits are read when performing stencil comparison tests. */
   stencilReadMask?: number;
@@ -217,6 +219,7 @@ export const DEFAULT_PARAMETERS: Required<Parameters> = {
   depthWriteEnabled: false,
   depthCompare: 'always',
   depthFormat: 'depth24plus',
+  clearDepth: 1,
 
   depthBias: 0,
   depthBiasSlopeScale: 0,