@luma.gl/core 9.0.0-alpha.9 → 9.0.0-beta.2

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

@@ -0,0 +1,133 @@
+// luma.gl, MIT license
+import type {Device} from '../device';
+import type {UniformValue} from '../types/types';
+import type {PrimitiveTopology, RenderPipelineParameters} from '../types/parameters';
+import type {ShaderLayout, Binding} from '../types/shader-layout';
+import type {BufferLayout} from '../types/buffer-layout';
+// import {normalizeAttributeMap} from '../helpers/attribute-bindings';
+import {Resource, ResourceProps} from './resource';
+import type {Shader} from './shader';
+import type {RenderPass} from './render-pass';
+import {VertexArray} from './vertex-array';
+import {TransformFeedback} from './transform-feedback';
+
+export type RenderPipelineProps = ResourceProps & {
+  // Shaders and shader layout
+
+  /** Compiled vertex shader */
+  vs?: Shader | null;
+  /** Vertex shader entry point (defaults to 'main'). WGSL only */
+  vsEntryPoint?: string; //
+  /** Constants to apply to compiled vertex shader (WGSL only) */
+  vsConstants?: Record<string, number>; // WGSL only
+  /** Compiled fragment shader */
+  fs?: Shader | null;
+  /** Fragment shader entry point (defaults to 'main'). WGSL only */
+  fsEntryPoint?: string; // WGSL only
+  /** Constants to apply to compiled fragment shader (WGSL only) */
+  fsConstants?: Record<string, number>;
+
+  /** Describes the attributes and bindings exposed by the pipeline shader(s). */
+  shaderLayout?: ShaderLayout | null;
+  /**
+   * Describes the buffers accepted by this pipeline and how they are mapped to shader attributes.
+   * A default mapping of one buffer per attribute is always created.
+   */
+  bufferLayout?: BufferLayout[]; // Record<string, Omit<BufferLayout, 'name'>
+
+  /** Determines how vertices are read from the 'vertex' attributes */
+  topology?: PrimitiveTopology;
+  /** Parameters that are controlled by pipeline */
+  parameters?: RenderPipelineParameters;
+
+  // Can be changed after creation
+  // TODO make pipeline immutable? these could be supplied to draw as parameters, in WebGPU they are set on the render pass
+
+  /** Number of vertices */
+  vertexCount?: number;
+  /** Number of instances */
+  instanceCount?: number;
+
+  /** Buffers, Textures, Samplers for the shader bindings */
+  bindings?: Record<string, Binding>;
+  /** @deprecated uniforms (WebGL only) */
+  uniforms?: Record<string, UniformValue>;
+};
+
+/**
+ * A compiled and linked shader program
+ */
+export abstract class RenderPipeline extends Resource<RenderPipelineProps> {
+  static override defaultProps: Required<RenderPipelineProps> = {
+    ...Resource.defaultProps,
+
+    vs: null,
+    vsEntryPoint: '', // main
+    vsConstants: {},
+
+    fs: null,
+    fsEntryPoint: '', // main
+    fsConstants: {},
+
+    shaderLayout: null,
+    bufferLayout: [],
+    topology: 'triangle-list',
+    parameters: {},
+
+    vertexCount: 0,
+    instanceCount: 0,
+
+    bindings: {},
+    uniforms: {}
+  };
+
+  override get [Symbol.toStringTag](): string {
+    return 'RenderPipeline';
+  }
+
+  hash: string = '';
+  abstract readonly vs: Shader;
+  abstract readonly fs: Shader | null;
+  /** The merged layout */
+  shaderLayout: ShaderLayout;
+  /** Buffer map describing buffer interleaving etc */
+  readonly bufferLayout: BufferLayout[];
+
+  constructor(device: Device, props: RenderPipelineProps) {
+    super(device, props, RenderPipeline.defaultProps);
+    this.shaderLayout = this.props.shaderLayout;
+    this.bufferLayout = this.props.bufferLayout || [];
+  }
+
+  /** Set bindings (stored on pipeline and set before each call) */
+  abstract setBindings(bindings: Record<string, Binding>): void;
+  /** Uniforms
+   * @deprecated Only supported on WebGL devices.
+   * @note textures, samplers and uniform buffers should be set via `setBindings()`, these are not considered uniforms.
+   * @note In WebGL uniforms have a performance penalty, they are reset before each call to enable pipeline sharing.
+   */
+  abstract setUniforms(bindings: Record<string, UniformValue>): void;
+
+  /** Draw call */
+  abstract draw(options: {
+    /** Render pass to draw into (targeting screen or framebuffer) */
+    renderPass?: RenderPass;
+    /** vertex attributes */
+    vertexArray: VertexArray;
+    /** Number of "rows" in index buffer */
+    indexCount?: number;
+    /** Number of "rows" in 'vertex' buffers */
+    vertexCount?: number;
+    /** Number of "rows" in 'instance' buffers */
+    instanceCount?: number;
+    /** First vertex to draw from */
+    firstVertex?: number;
+    /** First index to draw from */
+    firstIndex?: number;
+    /** First instance to draw from */
+    firstInstance?: number;
+    baseVertex?: number;
+    /** Transform feedback. WebGL 2 only. */
+    transformFeedback?: TransformFeedback;
+  }): void;
+}

package/src/adapter/resources/resource.ts

@@ -0,0 +1,176 @@
+// luma.gl, MIT license
+import type {Device} from '../device';
+import {uid} from '../../utils/utils';
+
+export type ResourceProps = {
+  /** Name of resource, mainly for debugging purposes. A unique name will be assigned if not provided */
+  id?: string;
+  /** Handle for the underlying resources (WebGL object or WebGPU handle) */
+  handle?: any;
+  /** User provided data stored on this resource  */
+  userData?: {[key: string]: any};
+}
+
+/**
+ * Base class for GPU (WebGPU/WebGL) Resources
+ */
+export abstract class Resource<Props extends ResourceProps> {
+  /** Default properties for resource */
+  static defaultProps: Required<ResourceProps> = {
+    id: 'undefined',
+    handle: undefined,
+    userData: undefined,
+  };
+  
+  abstract get [Symbol.toStringTag](): string;
+
+  /** props.id, for debugging. */
+  id: string;
+  readonly props: Required<Props>;
+  readonly userData: Record<string, unknown> = {};
+  abstract readonly device: Device;
+  private _device: Device;
+
+  /** Whether this resource has been destroyed */
+  destroyed: boolean = false;
+  /** For resources that allocate GPU memory */
+  private allocatedBytes: number = 0;
+  /** Attached resources will be destroyed when this resource is destroyed. Tracks auto-created "sub" resources. */
+  private _attachedResources = new Set<Resource<unknown>>();
+
+
+  /**
+   * Create a new Resource. Called from Subclass
+   */
+  constructor(device: Device, props: Props, defaultProps: Required<Props>) {
+    if (!device) {
+      throw new Error('no device');
+    }
+    this._device = device;
+    this.props = selectivelyMerge<Props>(props, defaultProps);
+
+    const id = this.props.id !== 'undefined' ? this.props.id as string : uid(this[Symbol.toStringTag]);
+    this.props.id = id;
+    this.id = id;
+    this.userData = this.props.userData || {};
+
+    this.addStats();
+  }
+
+  /**
+   * destroy can be called on any resource to release it before it is garbage collected.
+   */
+  destroy(): void {
+    this.destroyResource();
+  }
+
+  /** @deprecated Use destroy() */
+  delete(): this {
+    this.destroy();
+    return this;
+  }
+
+  toString(): string {
+    return `${this[Symbol.toStringTag] || this.constructor.name}(${this.id})`;
+  }
+
+  /**
+   * Combines a map of user props and default props, only including props from defaultProps
+   * @returns returns a map of overridden default props
+   */
+  getProps(): object {
+    return this.props;
+  }
+
+  // ATTACHED RESOURCES
+
+  /** 
+   * Attaches a resource. Attached resources are auto destroyed when this resource is destroyed
+   * Called automatically when sub resources are auto created but can be called by application
+   */
+  attachResource(resource: Resource<unknown>): void {
+    this._attachedResources.add(resource);
+  }
+
+  /** 
+   * Detach an attached resource. The resource will no longer be auto-destroyed when this resource is destroyed.
+   */
+  detachResource(resource: Resource<unknown>): void {
+    this._attachedResources.delete(resource);
+  }
+  
+  /** 
+   * Destroys a resource (only if owned), and removes from the owned (auto-destroy) list for this resource.
+   */
+  destroyAttachedResource(resource: Resource<unknown>): void {
+    if (this._attachedResources.delete(resource)) {
+      resource.destroy();
+    }
+  }
+
+  /** Destroy all owned resources. Make sure the resources are no longer needed before calling. */
+  destroyAttachedResources(): void {
+    for (const resource of Object.values(this._attachedResources)) {
+      resource.destroy();
+    }
+    // don't remove while we are iterating
+    this._attachedResources = new Set<Resource<unknown>>();
+  }
+
+  // PROTECTED METHODS
+
+  /** Perform all destroy steps. Can be called by derived resources when overriding destroy() */
+  protected destroyResource(): void {
+    this.destroyAttachedResources();
+    this.removeStats();
+    this.destroyed = true;
+  }
+
+  /** Called by .destroy() to track object destruction. Subclass must call if overriding destroy() */
+  protected removeStats(): void {
+    const stats = this._device.statsManager.getStats('Resource Counts');
+    const name = this[Symbol.toStringTag];
+    stats.get(`${name}s Active`).decrementCount();
+  }
+
+  /** Called by subclass to track memory allocations */
+  protected trackAllocatedMemory(bytes: number, name = this[Symbol.toStringTag]): void {
+    const stats = this._device.statsManager.getStats('Resource Counts');
+    stats.get('GPU Memory').addCount(bytes);
+    stats.get(`${name} Memory`).addCount(bytes);
+    this.allocatedBytes = bytes;
+  }
+
+  /** Called by subclass to track memory deallocations */
+  protected trackDeallocatedMemory(name = this[Symbol.toStringTag]): void {
+    const stats = this._device.statsManager.getStats('Resource Counts');
+    stats.get('GPU Memory').subtractCount(this.allocatedBytes);
+    stats.get(`${name} Memory`).subtractCount(this.allocatedBytes);
+    this.allocatedBytes = 0;
+  }
+
+  /** Called by resource constructor to track object creation */
+  private addStats(): void {
+    const stats = this._device.statsManager.getStats('Resource Counts');
+    const name = this[Symbol.toStringTag];
+    stats.get('Resources Created').incrementCount();
+    stats.get(`${name}s Created`).incrementCount();
+    stats.get(`${name}s Active`).incrementCount();
+  }
+}
+
+/**
+ * Combines a map of user props and default props, only including props from defaultProps
+ * @param props
+ * @param defaultProps
+ * @returns returns a map of overridden default props
+ */
+function selectivelyMerge<Props>(props: Props, defaultProps: Required<Props>): Required<Props> {
+  const mergedProps = {...defaultProps};
+  for (const key in props) {
+    if (props[key] !== undefined) {
+      mergedProps[key] = props[key];
+    }
+  }
+  return mergedProps;
+}

package/src/adapter/resources/sampler.ts

@@ -0,0 +1,69 @@
+// luma.gl, MIT license
+// Copyright (c) vis.gl contributors
+
+import type {Device} from '../device';
+import {CompareFunction} from '../types/parameters';
+import {Resource, ResourceProps} from './resource';
+
+/** Edge values sampling mode */
+export type SamplerAddressMode = 'clamp-to-edge' | 'repeat' | 'mirror-repeat';
+
+/** Sampler filtering mode */
+export type SamplerFilterMode = 'nearest' | 'linear';
+
+/**
+ * Properties for initializing a sampler
+ */
+export type SamplerProps = ResourceProps & {
+  /** Comparison / shadow samplers are used with depth textures. See the `Sampler.compare` field */
+  type?: 'color-sampler' | 'comparison-sampler';
+  /** Edge value sampling in X direction */
+  addressModeU?: 'clamp-to-edge' | 'repeat' | 'mirror-repeat';
+  /** Edge value sampling in Y direction */
+  addressModeV?: 'clamp-to-edge' | 'repeat' | 'mirror-repeat';
+  /** Edge value sampling in Z direction */
+  addressModeW?: 'clamp-to-edge' | 'repeat' | 'mirror-repeat';
+
+  /** Magnification: the area of the fragment in texture space is smaller than a texel */
+  magFilter?: 'nearest' | 'linear';
+  /** Minification: the area of the fragment in texture space is larger than a texel */
+  minFilter?: 'nearest' | 'linear';
+  /** mipmapping: select between multiple mipmaps based on angle and size of the texture relative to the screen. */
+  mipmapFilter?: 'nearest' | 'linear';
+  /** Affects the mipmap image selection */
+  lodMinClamp?: number;
+  /** Affects the mipmap image selection */
+  lodMaxClamp?: number;
+  /** Maximum number of samples that can be taken of the texture during any one texture fetch */
+  maxAnisotropy?: number;  
+  /** How to compare reference values provided in shader shadow sampler calls with those pulled from the texture */
+  compare?: CompareFunction;
+};
+
+export type SamplerParameters = Omit<SamplerProps, keyof ResourceProps>;
+
+/** Immutable Sampler object */
+export abstract class Sampler extends Resource<SamplerProps> {
+  static override defaultProps: Required<SamplerProps> = {
+    ...Resource.defaultProps,
+    type: 'color-sampler',
+    addressModeU: 'clamp-to-edge',
+    addressModeV: 'clamp-to-edge',
+    addressModeW: 'clamp-to-edge',
+    magFilter: 'nearest',
+    minFilter: 'nearest',
+    mipmapFilter: 'nearest',
+    lodMinClamp: 0,
+    lodMaxClamp: 32, // Per WebGPU spec
+    compare: 'less-equal',
+    maxAnisotropy: 1
+  };
+  
+  override get [Symbol.toStringTag](): string {
+    return 'Sampler';
+  }
+
+  constructor(device: Device, props: SamplerProps) {
+    super(device, props, Sampler.defaultProps);
+  }
+}

package/src/adapter/resources/shader.ts

@@ -0,0 +1,143 @@
+// luma.gl, MIT license
+import type {Device} from '../device';
+import {Resource, ResourceProps} from './resource';
+// import { log } from '../../utils/log';
+import {uid} from '../../utils/utils';
+import {CompilerMessage} from '../../lib/compiler-log/compiler-message';
+import {formatCompilerLog} from '../../lib/compiler-log/format-compiler-log';
+import {getShaderInfo} from '../../lib/compiler-log/get-shader-info';
+
+/**
+ * Properties for a Shader
+ */
+export type ShaderProps = ResourceProps & {
+  /** Shader language (defaults to auto) */
+  language?: 'glsl' | 'wgsl' | 'auto';
+  /** Which stage are we compiling? Required by WebGL and GLSL transpiler */
+  stage: 'vertex' | 'fragment' | 'compute';
+  /** Shader source code */
+  source: string;
+  /** Optional shader source map (WebGPU only) */
+  sourceMap?: string | null;
+  /** Optional shader entry point (WebGPU only) */
+  entryPoint?: string;
+  /** Show shader source in browser? */
+  debug?: 'never' | 'errors' | 'warnings' | 'always';
+};
+
+/**
+ * Immutable Shader object
+ * In WebGPU the handle can be copied between threads
+ */
+export abstract class Shader extends Resource<ShaderProps> {
+  static override defaultProps: Required<ShaderProps> = {
+    ...Resource.defaultProps,
+    language: 'auto',
+    stage: 'vertex',
+    source: '',
+    sourceMap: null,
+    entryPoint: 'main',
+    debug: 'errors'
+  };
+
+  override get [Symbol.toStringTag](): string {
+    return 'Shader';
+  }
+
+  /** The stage of this shader */
+  readonly stage: 'vertex' | 'fragment' | 'compute';
+  /** The source code of this shader */
+  readonly source: string;
+  /** The compilation status of this shader. May be 'pending' if compilation is done asynchronously */
+  compilationStatus: 'success' | 'error' | 'pending' = 'pending';
+
+  /** Create a new Shader instance */
+  constructor(device: Device, props: ShaderProps) {
+    super(device, {id: getShaderIdFromProps(props), ...props}, Shader.defaultProps);
+    this.stage = this.props.stage;
+    this.source = this.props.source;
+  }
+
+  /** Get compiler log asynchronously */
+  abstract getCompilationInfo(): Promise<readonly CompilerMessage[]>;
+
+  /** Get compiler log synchronously (WebGL only) */
+  getCompilationInfoSync(): readonly CompilerMessage[] | null {
+    return null;
+  }
+
+  // PORTABLE HELPERS
+
+  /** In browser logging of errors */
+  async debugShader(): Promise<void> {
+    switch (this.props.debug) {
+      case 'never':
+        return;
+      case 'errors':
+        // On WebGL - Don't extract the log unless errors
+        if (this.compilationStatus === 'success') {
+          return;
+        }
+        break;
+      case 'warnings':
+      case 'always':
+        break;
+    }
+
+    const messages = await this.getCompilationInfo();
+    if (this.props.debug === 'warnings' && messages?.length === 0) {
+      return;
+    }
+    this._displayShaderLog(messages);
+  }
+
+  // PRIVATE
+
+  /** In-browser UI logging of errors */
+  protected _displayShaderLog(messages: readonly CompilerMessage[]): void {
+    // Return if under Node.js / incomplete `document` polyfills
+    if (typeof document === 'undefined' || !document?.createElement) {
+      return;
+    }
+
+    const shaderName: string = getShaderInfo(this.source).name;
+    const shaderTitle: string = `${this.stage} ${shaderName}`;
+    const htmlLog = formatCompilerLog(messages, this.source, {showSourceCode: 'all', html: true});
+
+    // Make it clickable so we can copy to clipboard
+    const button = document.createElement('Button');
+    button.innerHTML = `
+<h1>Shader Compilation Error in ${shaderTitle}</h1><br /><br />
+<code style="user-select:text;"><pre>
+${htmlLog}
+</pre></code>`;
+    button.style.top = '10px';
+    button.style.left = '10px';
+    button.style.position = 'absolute';
+    button.style.zIndex = '9999';
+    button.style.width = '100%';
+    button.style.textAlign = 'left';
+    document.body.appendChild(button);
+
+    const errors = document.getElementsByClassName('luma-compiler-log-error');
+    if (errors[0]?.scrollIntoView) {
+      errors[0].scrollIntoView();
+    }
+
+    // TODO - add a small embedded copy button (instead of main button)
+    button.onclick = () => {
+      // const source = this.source.replaceAll('\n', '<br />');
+      const dataURI = `data:text/plain,${encodeURIComponent(this.source)}`;
+      navigator.clipboard.writeText(dataURI);
+    };
+
+    // TODO - add a small embedded close button
+  }
+}
+
+// HELPERS
+
+/** Deduce an id, from shader source, or supplied id, or shader type */
+function getShaderIdFromProps(props: ShaderProps): string {
+  return getShaderInfo(props.source).name || props.id || uid(`unnamed ${props.stage}-shader`);
+}

package/src/adapter/resources/texture.ts

@@ -0,0 +1,140 @@
+// luma.gl, MIT license
+import type {Device} from '../device';
+import type {TypedArray} from '../../types';
+import type {TextureFormat} from '../types/texture-formats';
+import {Resource, ResourceProps} from './resource';
+import {Sampler, SamplerProps} from './sampler';
+
+// 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>>
+  ;
+
+export type ExternalTextureData = HTMLVideoElement;
+
+/** Abstract Texture interface */
+export type TextureProps = ResourceProps & {
+  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;
+  sampler?: Sampler | SamplerProps;
+
+  mipLevels?: number;
+  samples?: number;
+  type?: number;
+  compressed?: boolean;
+};
+
+export type WebGPUTextureProps = ResourceProps & {
+  width: number;
+  height: number;
+  depth?: number;
+  mipLevels?: number;
+  format?: string;
+};
+
+export type TextureViewProps = {
+  format: string;
+  dimension: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d';
+  aspect?: 'all' | 'stencil-only' | 'depth-only';
+  arrayLayerCount: number;
+  baseArrayLayer?: number;
+  mipLevels?: number;
+  baseMipLevel?: number;
+};
+
+/** 
+ * @deprecated
+ * @todo remove, are these even used anymore?
+ */
+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;
+};
+
+/**
+ * Abstract Texture interface
+ * Texture Object
+ * https://gpuweb.github.io/gpuweb/#gputexture
+ */
+export abstract class Texture<Props extends TextureProps = TextureProps> extends Resource<Props> {
+  static override defaultProps: Required<TextureProps> = {
+    ...Resource.defaultProps,
+    data: null,
+    dimension: '2d',
+    format: 'rgba8unorm',
+    width: undefined!,
+    height: undefined!,
+    depth: 1,
+    mipmaps: true,
+    sampler: {},
+    // type: undefined,
+    compressed: false,
+    // mipLevels: 1,
+    usage: 0,
+    // usage: GPUTextureUsage.COPY_DST
+    mipLevels: undefined!,
+    samples: undefined!,
+    type: 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'; }
+
+  /** dimension of this texture */
+  readonly dimension: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d';
+  /** format of this texture */
+  readonly format: TextureFormat;
+  /** width in pixels of this texture */
+  width: number;
+  /** height in pixels of this texture */
+  height: number;
+  /** depth of this texture */
+  readonly depth: number;
+  /** Default sampler for this texture */
+  abstract sampler: Sampler;
+
+  constructor(device: Device, props: Props, defaultProps = Texture.defaultProps as Required<Props>) {
+    super(device, props, defaultProps);
+    this.dimension = this.props.dimension;
+    this.format = this.props.format ;
+    this.width = this.props.width;
+    this.height = this.props.height;
+    this.depth = this.props.depth;
+  }
+}