@luma.gl/core 9.0.11 → 9.1.0-alpha.1

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 '../types/texture-formats';
+import type {TextureFormat} from '../../gpu-type-utils/texture-formats';
 import {Resource, ResourceProps} from './resource';
 
 /** Properties for initializing a texture view */
@@ -29,13 +29,13 @@ export type TextureViewProps = ResourceProps & {
 export abstract class TextureView extends Resource<TextureViewProps> {
   static override defaultProps: Required<TextureViewProps> = {
     ...Resource.defaultProps,
-    format: undefined,
-    dimension: undefined,
+    format: undefined!,
+    dimension: undefined!,
     aspect: 'all',
     baseMipLevel: 0,
-    mipLevelCount: undefined,
+    mipLevelCount: undefined!,
     baseArrayLayer: 0,
-    arrayLayerCount: undefined
+    arrayLayerCount: undefined!
   };
 
   abstract texture: Texture;

package/src/adapter/resources/texture.ts

@@ -4,81 +4,138 @@
 
 import type {Device} from '../device';
 import type {TypedArray} from '../../types';
-import type {TextureFormat} from '../types/texture-formats';
+import type {TextureFormat} from '../../gpu-type-utils/texture-formats';
+import type {TextureView, TextureViewProps} from './texture-view';
 import {Resource, ResourceProps} from './resource';
 import {Sampler, SamplerProps} from './sampler';
-import {TextureView, TextureViewProps} from './texture-view';
 
-// required GPUExtent3D size;
-// GPUIntegerCoordinate mipLevelCount = 1;
-// GPUSize32 sampleCount = 1;
-// GPUTextureDimension dimension = "2d";
-// required GPUTextureFormat format;
-// required GPUTextureUsageFlags usage;
-
-/** Data types that can be used to initialize textures */
-export type TextureData = TypedArray | ArrayBuffer | Buffer | ImageBitmap | HTMLImageElement;
-
-export type CubeTextureData = Record<string, TextureData> | Record<string, Promise<TextureData>>;
+/**
+ * These represent the main compressed texture formats
+ * Each format typically has a number of more specific subformats
+ */
+export type TextureCompressionFormat =
+  | 'dxt'
+  | 'dxt-srgb'
+  | 'etc1'
+  | 'etc2'
+  | 'pvrtc'
+  | 'atc'
+  | 'astc'
+  | 'rgtc';
 
-export type ExternalTextureData = HTMLVideoElement;
+/** Names of cube texture faces */
+export type TextureCubeFace = '+X' | '-X' | '+Y' | '-Y' | '+Z' | '-Z';
 
-/** Abstract Texture interface */
-export type TextureProps = ResourceProps & {
+/**
+ * One mip level
+ * Basic data structure is similar to `ImageData`
+ * additional optional fields can describe compressed texture data.
+ */
+export type TextureLevelData = {
+  /** WebGPU style format string. Defaults to 'rgba8unorm' */
   format?: TextureFormat;
-  dimension?: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d';
-  width?: number | undefined;
-  height?: number | undefined;
-  depth?: number;
-  usage?: number;
-
-  data?: TextureData | Promise<TextureData> | CubeTextureData | string | HTMLVideoElement | null;
-  mipmaps?: boolean;
-
-  mipLevels?: number;
-  samples?: number;
-  type?: number;
-  compressed?: boolean;
-
-  sampler?: Sampler | SamplerProps;
-  view?: TextureViewProps;
-};
-
-export type WebGPUTextureProps = ResourceProps & {
+  data: TypedArray;
   width: number;
   height: number;
-  depth?: number;
-  mipLevels?: number;
-  format?: string;
+
+  compressed?: boolean;
+  byteLength?: number;
+  hasAlpha?: boolean;
 };
 
 /**
- * @deprecated
- * @todo remove, are these even used anymore?
+ * Built-in data types that can be used to initialize textures
+ * @note WebGL supports OffscreenCanvas but seems WebGPU does not?
  */
-export type DeprecatedWebGLTextureProps = {
-  /** @deprecated use props.sampler */
-  parameters?: Record<number, number>;
-  /** @deprecated use props.data */
-  pixels?: any;
-  /** @deprecated use props.format */
-  dataFormat?: number | null;
-  /** @deprecated rarely supported */
-  border?: number;
-  /** @deprecated WebGL only. */
-  pixelStore?: object;
-  /** @deprecated WebGL only. */
-  textureUnit?: number;
-  /** @deprecated WebGL only. Use dimension. */
-  target?: number;
-};
+export type ExternalImage =
+  | ImageData
+  | ImageBitmap
+  | HTMLImageElement
+  | HTMLVideoElement
+  | HTMLCanvasElement;
+
+export type TextureLevelSource = TextureLevelData | ExternalImage;
+
+/** Texture data can be one or more mip levels */
+export type TextureData = TextureLevelData | ExternalImage | (TextureLevelData | ExternalImage)[];
+
+/** @todo - define what data type is supported for 1D textures */
+export type Texture1DData = TypedArray | TextureLevelData;
+
+/** Texture data can be one or more mip levels */
+export type Texture2DData =
+  | TypedArray
+  | TextureLevelData
+  | ExternalImage
+  | (TextureLevelData | ExternalImage)[];
+
+/** Array of textures */
+export type Texture3DData = TypedArray | TextureData[];
+
+/** 6 face textures */
+export type TextureCubeData = Record<TextureCubeFace, Texture2DData>;
+
+/** Array of textures */
+export type TextureArrayData = TextureData[];
+
+/** Array of 6 face textures */
+export type TextureCubeArrayData = Record<TextureCubeFace, TextureData>[];
+
+type TextureDataProps =
+  | Texture1DProps
+  | Texture2DProps
+  | Texture3DProps
+  | TextureArrayProps
+  | TextureCubeProps
+  | TextureCubeArrayProps;
+
+type Texture1DProps = {dimension: '1d'; data?: Texture1DData | null};
+type Texture2DProps = {dimension?: '2d'; data?: Texture2DData | null};
+type Texture3DProps = {dimension: '3d'; data?: Texture3DData | null};
+type TextureArrayProps = {dimension: '2d-array'; data?: TextureArrayData | null};
+type TextureCubeProps = {dimension: 'cube'; data?: TextureCubeData | null};
+type TextureCubeArrayProps = {dimension: 'cube-array'; data: TextureCubeArrayData | null};
+
+/** Texture properties */
+export type TextureProps = ResourceProps &
+  TextureDataProps & {
+    format?: TextureFormat;
+    width?: number | undefined;
+    height?: number | undefined;
+    depth?: number;
+    usage?: number;
+
+    /** How many mip levels */
+    mipLevels?: number | 'pyramid';
+    /** Multi sampling */
+    samples?: number;
+
+    /** Specifying mipmaps will default mipLevels to 'pyramid' and attempt to generate mipmaps */
+    mipmaps?: boolean;
+
+    /** Sampler (or SamplerProps) for the default sampler for this texture. Used if no sampler provided. Note that other samplers can still be used. */
+    sampler?: Sampler | SamplerProps;
+    /** Props for the default TextureView for this texture. Note that other views can still be created and used. */
+    view?: TextureViewProps;
+
+    /** @deprecated - this is implicit from format */
+    compressed?: boolean;
+  };
 
 /**
  * Abstract Texture interface
  * Texture Object
  * https://gpuweb.github.io/gpuweb/#gputexture
  */
-export abstract class Texture<Props extends TextureProps = TextureProps> extends Resource<Props> {
+export abstract class Texture extends Resource<TextureProps> {
+  static COPY_SRC = 0x01;
+  static COPY_DST = 0x02;
+  static TEXTURE = 0x04;
+  static STORAGE = 0x08;
+  static RENDER_ATTACHMENT = 0x10;
+
+  static CubeFaces: TextureCubeFace[] = ['+X', '-X', '+Y', '-Y', '+Z', '-Z'];
+
   static override defaultProps: Required<TextureProps> = {
     ...Resource.defaultProps,
     data: null,
@@ -87,25 +144,15 @@ export abstract class Texture<Props extends TextureProps = TextureProps> extends
     width: undefined!,
     height: undefined!,
     depth: 1,
-    mipmaps: true,
-    // type: undefined,
+    mipmaps: false,
     compressed: false,
-    // mipLevels: 1,
     usage: 0,
-    // usage: GPUTextureUsage.COPY_DST
     mipLevels: undefined!,
     samples: undefined!,
-    type: undefined!,
     sampler: {},
     view: undefined!
   };
 
-  static COPY_SRC = 0x01;
-  static COPY_DST = 0x02;
-  static TEXTURE_BINDING = 0x04;
-  static STORAGE_BINDING = 0x08;
-  static RENDER_ATTACHMENT = 0x10;
-
   override get [Symbol.toStringTag](): string {
     return 'Texture';
   }
@@ -119,34 +166,136 @@ export abstract class Texture<Props extends TextureProps = TextureProps> extends
   /** height in pixels of this texture */
   height: number;
   /** depth of this texture */
-  readonly depth: number;
+  depth: number;
+  /** mip levels in this texture */
+  mipLevels: number;
 
   /** Default sampler for this texture */
   abstract sampler: Sampler;
-
   /** Default view for this texture */
   abstract view: TextureView;
 
   /** "Time" of last update. Monotonically increasing timestamp */
   updateTimestamp: number;
 
+  /** Check if data is an external image */
+  static isExternalImage(data: unknown): data is ExternalImage {
+    return (
+      (typeof ImageData !== 'undefined' && data instanceof ImageData) ||
+      (typeof ImageBitmap !== 'undefined' && data instanceof ImageBitmap) ||
+      (typeof HTMLImageElement !== 'undefined' && data instanceof HTMLImageElement) ||
+      (typeof HTMLCanvasElement !== 'undefined' && data instanceof HTMLCanvasElement) ||
+      (typeof HTMLVideoElement !== 'undefined' && data instanceof HTMLVideoElement)
+    );
+  }
+
+  /** Determine size (width and height) of provided image data */
+  static getExternalImageSize(data: ExternalImage): {width: number; height: number} | null {
+    if (
+      (typeof ImageData !== 'undefined' && data instanceof ImageData) ||
+      (typeof ImageBitmap !== 'undefined' && data instanceof ImageBitmap) ||
+      (typeof HTMLCanvasElement !== 'undefined' && data instanceof HTMLCanvasElement)
+    ) {
+      return {width: data.width, height: data.height};
+    }
+    if (typeof HTMLImageElement !== 'undefined' && data instanceof HTMLImageElement) {
+      return {width: data.naturalWidth, height: data.naturalHeight};
+    }
+    if (typeof HTMLVideoElement !== 'undefined' && data instanceof HTMLVideoElement) {
+      return {width: data.videoWidth, height: data.videoHeight};
+    }
+    return null;
+  }
+
+  /** Check if texture data is a typed array */
+  isTextureLevelData(data: TextureData): data is TextureLevelData {
+    const typedArray = (data as TextureLevelData)?.data;
+    return ArrayBuffer.isView(typedArray);
+  }
+
+  /** Get the size of the texture described by the provided TextureData */
+  getTextureDataSize(
+    data: TextureData | TextureCubeData | TextureArrayData | TextureCubeArrayData | TypedArray
+  ): {width: number; height: number} | null {
+    if (!data) {
+      return null;
+    }
+    if (ArrayBuffer.isView(data)) {
+      return null;
+    }
+    // Recurse into arrays (array of miplevels)
+    if (Array.isArray(data)) {
+      return this.getTextureDataSize(data[0]);
+    }
+    if (Texture.isExternalImage(data)) {
+      return Texture.getExternalImageSize(data);
+    }
+    if (data && typeof data === 'object' && data.constructor === Object) {
+      const untypedData = data as unknown as Record<string, number>;
+      return {width: untypedData.width, height: untypedData.height};
+    }
+    throw new Error('texture size deduction failed');
+  }
+
+  /** Calculate the number of mip levels for a texture of width and height */
+  getMipLevelCount(width: number, height: number): number {
+    return Math.floor(Math.log2(Math.max(width, height))) + 1;
+  }
+
+  /** Convert luma.gl cubemap face constants to depth index */
+  getCubeFaceDepth(face: TextureCubeFace): number {
+    // prettier-ignore
+    switch (face) {
+        case '+X': return  0;
+        case '-X': return  1;
+        case '+Y': return  2;
+        case '-Y': return  3;
+        case '+Z': return  4;
+        case '-Z': return  5;
+        default: throw new Error(face);
+      }
+  }
+
   /** Do not use directly. Create with device.createTexture() */
-  constructor(
-    device: Device,
-    props: Props,
-    defaultProps = Texture.defaultProps as Required<Props>
-  ) {
-    super(device, props, defaultProps);
+  constructor(device: Device, props: TextureProps) {
+    super(device, props, Texture.defaultProps);
     this.dimension = this.props.dimension;
     this.format = this.props.format;
+
+    // Size
     this.width = this.props.width;
     this.height = this.props.height;
     this.depth = this.props.depth;
 
+    // Calculate size, if not provided
+    if (this.props.width === undefined || this.props.height === undefined) {
+      // @ts-ignore
+      const size = this.getTextureDataSize(this.props.data);
+      this.width = size?.width || 1;
+      this.height = size?.height || 1;
+    }
+
+    // mipLevels
+
+    // If mipmap generation is requested and mipLevels is not provided, initialize a full pyramid
+    if (this.props.mipmaps && this.props.mipLevels === undefined) {
+      this.props.mipLevels = 'pyramid';
+    }
+
+    // Auto-calculate the number of mip levels as a convenience
+    // TODO - Should we clamp to 1-getMipLevelCount?
+    this.mipLevels =
+      this.props.mipLevels === 'pyramid'
+        ? this.getMipLevelCount(this.width, this.height)
+        : this.props.mipLevels || 1;
+
     // TODO - perhaps this should be set on async write completion?
     this.updateTimestamp = device.incrementTimestamp();
   }
 
   /** Create a texture view for this texture */
-  abstract createView(props?: TextureViewProps): TextureView;
+  abstract createView(props: TextureViewProps): TextureView;
+
+  /** Set sampler props associated with this texture */
+  abstract setSampler(sampler?: Sampler | SamplerProps): void;
 }

package/src/adapter/resources/transform-feedback.ts

@@ -35,7 +35,7 @@ export abstract class TransformFeedback extends Resource<TransformFeedbackProps>
     return 'TransformFeedback';
   }
 
-  constructor(device: Device, props?: TransformFeedbackProps) {
+  constructor(device: Device, props: TransformFeedbackProps) {
     super(device, props, TransformFeedback.defaultProps);
   }
 

package/src/adapter/resources/vertex-array.ts

@@ -6,7 +6,7 @@ import type {TypedArray} from '../../types';
 import {
   AttributeInfo,
   getAttributeInfosByLocation
-} from '../attribute-utils/get-attribute-from-layouts';
+} from '../../adapter-utils/get-attribute-from-layouts';
 import type {Device} from '../device';
 import type {Buffer} from './buffer';
 import type {RenderPass} from './render-pass';
@@ -49,9 +49,13 @@ export abstract class VertexArray extends Resource<VertexArrayProps> {
     super(device, props, VertexArray.defaultProps);
     this.maxVertexAttributes = device.limits.maxVertexAttributes;
     this.attributes = new Array(this.maxVertexAttributes).fill(null);
+    const {shaderLayout, bufferLayout} = props.renderPipeline || {};
+    if (!shaderLayout || !bufferLayout) {
+      throw new Error('VertexArray');
+    }
     this.attributeInfos = getAttributeInfosByLocation(
-      props.renderPipeline.shaderLayout,
-      props.renderPipeline.bufferLayout,
+      shaderLayout,
+      bufferLayout,
       this.maxVertexAttributes
     );
   }

package/src/adapter/types/{types.ts → attachments.ts}

@@ -3,20 +3,19 @@
 // Copyright (c) vis.gl contributors
 
 import {NumberArray} from '../../types';
-import type {ColorTextureFormat, DepthStencilTextureFormat, TextureFormat} from './texture-formats';
-import type {Buffer} from '../resources/buffer';
+import type {
+  ColorTextureFormat,
+  DepthStencilTextureFormat,
+  TextureFormat
+} from '../../gpu-type-utils/texture-formats';
 import type {Texture} from '../resources/texture'; // TextureView...
+import type {TextureView} from '../resources/texture-view'; // TextureView...
 
 // UNIFORMS
 
 /** Valid values for uniforms. @note boolean values get converted to 0 or 1 before setting */
 export type UniformValue = number | boolean | Readonly<NumberArray>; // Float32Array> | Readonly<Int32Array> | Readonly<Uint32Array> | Readonly<number[]>;
 
-// BINDINGS
-
-/** Buffer bindings */
-export type Binding = Texture | Buffer | {buffer: Buffer; offset?: number; size?: number};
-
 // BINDING LAYOUTS
 
 /** Describes a buffer binding layout */
@@ -55,14 +54,6 @@ export type BindingDeclaration =
   | TextureBindingLayout
   | StorageTextureBindingLayout;
 
-// TEXTURE VIEWS
-
-export type TextureView = {
-  texture: WebGLTexture;
-  layer?: number; //  = 0
-  level?: number; // = 0
-};
-
 // ATTACHMENTS (See Framebuffer)
 
 /**
@@ -71,7 +62,7 @@ export type TextureView = {
  */
 export type ColorAttachment = {
   /** Describes the texture subresource that will be output to for this color attachment. */
-  texture?: Texture;
+  texture?: TextureView | Texture;
   /** Format of the texture resource. Used to auto create texture if not supplied */
   format?: ColorTextureFormat;
   /* Describes the texture subresource that will receive  resolved output for this color attachment if multisampled. */
@@ -91,7 +82,7 @@ export type ColorAttachment = {
  */
 export type DepthStencilAttachment = {
   /** Describes the texture subresource that will be output to and read from for this depth/stencil attachment. */
-  texture?: Texture;
+  texture?: TextureView | Texture;
   /** Format of the texture resource. Used to auto create texture if not supplied */
   format?: DepthStencilTextureFormat;
 

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

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

package/src/adapter/types/parameters.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {DepthStencilTextureFormat} from './texture-formats';
+import {DepthStencilTextureFormat} from '../../gpu-type-utils/texture-formats';
 
 export type CompareFunction =
   | 'never'
@@ -20,12 +20,8 @@ export type PrimitiveTopology =
   | 'point-list'
   | 'line-list'
   | 'line-strip'
-  /** @deprecated */
-  | 'line-loop-webgl'
   | 'triangle-list'
-  | 'triangle-strip'
-  /** @deprecated */
-  | 'triangle-fan-webgl';
+  | 'triangle-strip';
 
 export type IndexFormat = 'uint16' | 'uint32';
 
@@ -251,12 +247,12 @@ export const DEFAULT_PARAMETERS: Required<Parameters> = {
   polygonMode: 'fill',
   polygonOffsetLine: false,
 
-  clipDistance0: undefined,
-  clipDistance1: undefined,
-  clipDistance2: undefined,
-  clipDistance3: undefined,
-  clipDistance4: undefined,
-  clipDistance5: undefined,
-  clipDistance6: undefined,
-  clipDistance7: undefined
+  clipDistance0: undefined!,
+  clipDistance1: undefined!,
+  clipDistance2: undefined!,
+  clipDistance3: undefined!,
+  clipDistance4: undefined!,
+  clipDistance5: undefined!,
+  clipDistance6: undefined!,
+  clipDistance7: undefined!
 };

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

@@ -2,9 +2,8 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {TextureFormat} from '../types/texture-formats';
-import type {ShaderUniformType, ShaderAttributeType} from './shader-types';
-import {AccessorObject} from '../types/accessor';
+import type {TextureFormat} from '../../gpu-type-utils/texture-formats';
+import type {ShaderUniformType, ShaderAttributeType} from '../../gpu-type-utils/shader-types';
 import type {Buffer} from '../resources/buffer';
 import type {Sampler} from '../resources/sampler';
 import type {Texture} from '../resources/texture';
@@ -64,32 +63,6 @@ export type AttributeDeclaration = {
 
 // BINDING LAYOUTS
 
-/*
-type Binding = {
-  binding: number;
-  visibility: number;
-
-  buffer?: {
-    type?: 'uniform' | 'storage' | 'read-only-storage';
-    hasDynamicOffset?: false;
-    minBindingSize?: number;
-  };
-
-  // type = sampler
-  samplerType?: 'filtering' | 'non-filtering' | 'comparison';
-
-  // type = texture
-  viewDimension?: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d';
-  sampleType?: 'float' | 'unfilterable-float' | 'depth' | 'sint' | 'uint';
-  multisampled?: boolean;
-
-  // type = storage
-  viewDimension?: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d';
-  access: 'read-only' | 'write-only';
-  format: string;
-};
-*/
-
 /** ShaderLayout for bindings */
 export type BindingDeclaration =
   | UniformBufferBindingLayout
@@ -205,3 +178,32 @@ export type AttributeBinding = {
   location: number;
   accessor: AccessorObject;
 };
+
+/**
+ * Attribute descriptor object
+ * @deprecated Use ShaderLayout
+ */
+export interface AccessorObject {
+  buffer?: Buffer;
+  // format: VertexFormat;
+  offset?: number;
+  // can now be described with single WebGPU-style `format` string
+
+  //
+  stride?: number;
+
+  /** @deprecated - Use accessor.stepMode */
+  divisor?: number;
+
+  /** @deprecated - Infer from format */
+  type?: number;
+  /** @deprecated - Infer from format */
+  size?: number;
+  /** @deprecated - Infer from format */
+  normalized?: boolean;
+  /** @deprecated - Infer from format */
+  integer?: boolean;
+
+  /** @deprecated */
+  index?: number;
+}

package/src/adapter/types/uniforms.ts

@@ -0,0 +1,10 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {NumberArray} from '../../types';
+
+// UNIFORMS
+
+/** Valid values for uniforms. @note boolean values get converted to 0 or 1 before setting */
+export type UniformValue = number | boolean | Readonly<NumberArray>; // Float32Array> | Readonly<Int32Array> | Readonly<Uint32Array> | Readonly<number[]>;

package/src/{lib/compiler-log → adapter-utils}/format-compiler-log.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {CompilerMessage} from './compiler-message';
+import type {CompilerMessage} from '../adapter/types/compiler-message';
 
 /** @returns annotated errors or warnings */
 export function formatCompilerLog(