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

package/src/adapter/resources/command-encoder.ts

@@ -0,0 +1,172 @@
+// luma.gl, MIT license
+import {Device} from '../device';
+import {Resource, ResourceProps} from './resource';
+import {Buffer} from './buffer';
+import {Texture} from './texture';
+
+export type WriteBufferOptions = {
+  buffer: Buffer,
+  bufferOffset?: number,
+  data: BufferSource,
+  dataOffset?: number,
+  size?: number
+};
+
+export type WriteTextureOptions = {
+  destination: Texture;
+  mipLevel?: number; //  = 0;
+  origin?: [number, number, number] | number[];
+  aspect?: 'all' | 'stencil-only' | 'depth-only';
+  data: BufferSource;
+  // dataLayout;
+  offset: number;
+  bytesPerRow: number;
+  rowsPerImage: number;
+  size: [number, number, number] | number[];
+}
+
+export type CopyBufferToBufferOptions = {
+  source: Buffer;
+  sourceOffset?: number;
+  destination: Buffer;
+  destinationOffset?: number;
+  size: number;
+};
+
+export type CopyBufferToTextureOptions = {
+  source: Buffer;
+  byteOffset?: number;
+  destination: Texture;
+  mipLevel?: number //  = 0;
+  origin?: [number, number, number] | number[];
+  aspect?: 'all' | 'stencil-only' | 'depth-only';
+  bytesPerRow: number;
+  rowsPerImage: number;
+  size: [number, number, number] | number[];
+};
+
+export type CopyTextureToBufferOptions = {
+  /** Texture to copy to/from. */
+  source: Texture;
+  /**  Mip-map level of the texture to copy to/from. (Default 0) */
+  mipLevel?: number;
+  /** Defines the origin of the copy - the minimum corner of the texture sub-region to copy to/from.
+   * Together with `copySize`, defines the full copy sub-region.
+   */
+  /** Defines which aspects of the texture to copy to/from. */
+  aspect?: 'all' | 'stencil-only' | 'depth-only';
+
+  /** Width to copy */
+  width?: number;
+  height?: number;
+  depthOrArrayLayers?: number;
+  origin?: number[];
+
+  /** Destination buffer */
+  destination: Buffer;
+  /** Offset, in bytes, from the beginning of the buffer to the start of the image data (default 0) */
+  byteOffset?: number;
+  /**
+   * The stride, in bytes, between the beginning of each block row and the subsequent block row.
+   * Required if there are multiple block rows (i.e. the copy height or depth is more than one block).
+   */
+  bytesPerRow?: number;
+  /**
+   * Number of block rows per single image of the texture.
+   * rowsPerImage × bytesPerRow is the stride, in bytes, between the beginning of each image of data and the subsequent image.
+   * Required if there are multiple images (i.e. the copy depth is more than one).
+   */
+  rowsPerImage?: number;
+};
+
+export type CopyTextureToTextureOptions = {
+  /** Texture to copy to/from. */
+  source: Texture;
+  /**  Mip-map level of the texture to copy to/from. (Default 0) */
+  mipLevel?: number;
+  /** Defines the origin of the copy - the minimum corner of the texture sub-region to copy from. */
+  /** Defines which aspects of the {@link GPUImageCopyTexture#texture} to copy to/from. */
+  aspect?: 'all' | 'stencil-only' | 'depth-only';
+
+  /** Texture to copy to/from. */
+  destination: Texture;
+  /**  Mip-map level of the texture to copy to/from. (Default 0) */
+  destinationMipLevel?: number;
+  /** Defines the origin of the copy - the minimum corner of the texture sub-region to copy to. */
+  destinationOrigin?: number[];
+  /** Defines which aspects of the {@link GPUImageCopyTexture#texture} to copy to/from. */
+  destinationAspect?: 'all' | 'stencil-only' | 'depth-only';
+
+  origin?: number[];
+  /** Width to copy */
+  width?: number;
+  height?: number;
+  depthOrArrayLayers?: number;
+};
+
+// interface Queue {
+//   submit(commandBuffers);
+
+//   // onSubmittedWorkDone(): Promise<undefined>;
+
+//   writeBuffer(options: WriteBufferOptions): void;
+//   writeTexture(options: WriteTextureOptions): void;
+
+//   // copyExternalImageToTexture(
+//   //   GPUImageCopyExternalImage source,
+//   //   GPUImageCopyTextureTagged destination,
+//   //   GPUExtent3D copySize
+//   // ): void;
+// }
+
+export type CommandEncoderProps = ResourceProps & {
+  measureExecutionTime?: boolean;
+};
+
+/**
+ * Encodes commands to queue that can be executed later
+ */
+export abstract class CommandEncoder extends Resource<CommandEncoderProps> {
+  static override defaultProps: Required<CommandEncoderProps> = {
+    ...Resource.defaultProps,
+    measureExecutionTime: undefined
+  };
+  
+  override get [Symbol.toStringTag](): string {
+    return 'CommandEncoder';
+  }
+
+  constructor(device: Device, props: CommandEncoderProps) {
+    super(device, props, CommandEncoder.defaultProps);
+  }
+  
+  abstract finish(): void; // TODO - return the CommandBuffer?
+
+  // beginRenderPass(GPURenderPassDescriptor descriptor): GPURenderPassEncoder;
+  // beginComputePass(optional GPUComputePassDescriptor descriptor = {}): GPUComputePassEncoder;
+  // finish(options?: {id?: string}): GPUCommandBuffer;
+
+  abstract copyBufferToBuffer(options: CopyBufferToBufferOptions): void;
+
+  abstract copyBufferToTexture(options: CopyBufferToTextureOptions): void;
+
+  abstract copyTextureToBuffer(options: CopyTextureToBufferOptions): void;
+
+  abstract copyTextureToTexture(options: CopyTextureToTextureOptions): void;
+
+  pushDebugGroup(groupLabel: string): void {}
+
+  popDebugGroup() {}
+
+  insertDebugMarker(markerLabel: string): void {}
+
+  // writeTimestamp(querySet: Query, queryIndex: number): void;
+
+  // resolveQuerySet(options: {
+  //   querySet: GPUQuerySet,
+  //   firstQuery: number,
+  //   queryCount: number,
+  //   destination: Buffer,
+  //   destinationOffset?: number;
+  // }): void;
+}

package/src/adapter/resources/compute-pass.ts

@@ -0,0 +1,52 @@
+import {Resource, ResourceProps} from './resource';
+import {ComputePipeline} from './compute-pipeline';
+import {Buffer} from './buffer';
+import type {Device} from '../device';
+
+export type ComputePassProps = ResourceProps & {};
+
+export abstract class ComputePass extends Resource<ComputePassProps> {
+  static override defaultProps: Required<ComputePassProps> = {
+    ...Resource.defaultProps
+  }
+
+  override get [Symbol.toStringTag](): string {
+    return 'ComputePass';
+  }
+
+  constructor(device: Device, props: ComputePassProps) {
+    super(device, props, Resource.defaultProps);
+  }
+
+  abstract override destroy(): void;
+
+  abstract end(): void;
+
+  abstract setPipeline(pipeline: ComputePipeline): void;
+
+  /** Sets an array of bindings (uniform buffers, samplers, textures, ...) */
+  // abstract setBindings(bindings: Binding[]): void;
+
+  /**
+   * Dispatch work to be performed with the current ComputePipeline.
+   * @param x X dimension of the grid of workgroups to dispatch.
+   * @param y Y dimension of the grid of workgroups to dispatch.
+   * @param z Z dimension of the grid of workgroups to dispatch.
+   */
+  abstract dispatch(x: number, y?: number, z?: number): void;
+
+  /**
+   * Dispatch work to be performed with the current ComputePipeline.
+   * @param indirectBuffer buffer must be a tightly packed block of three 32-bit unsigned integer values (12 bytes total), given in the same order as the arguments for dispatch()
+   * @param indirectOffset
+   */
+  abstract dispatchIndirect(indirectBuffer: Buffer, indirectOffset?: number): void;
+
+  abstract pushDebugGroup(groupLabel: string): void;
+  abstract popDebugGroup(): void;
+  abstract insertDebugMarker(markerLabel: string): void;
+
+  // writeTimestamp(querySet: GPUQuerySet, queryIndex: number): void;
+  // beginPipelineStatisticsQuery(querySet: GPUQuerySet, queryIndex: number): void;
+  // endPipelineStatisticsQuery(querySet: GPUQuerySet, queryIndex: number): void;
+}

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

@@ -0,0 +1,39 @@
+//
+import {Resource, ResourceProps} from './resource';
+import {BindingDeclaration} from '../types/shader-layout';
+import type {Device} from '../device';
+import type {Shader} from './shader';
+
+/**
+ * Properties for a compute pipeline
+ */
+export type ComputePipelineProps = ResourceProps & {
+  handle?: unknown;
+  cs: Shader;
+  csEntryPoint?: string;
+  csConstants?: Record<string, number>; // WGSL only
+  shaderLayout?: BindingDeclaration[];
+};
+
+/**
+ * A compiled and linked shader program for compute
+ */
+export abstract class ComputePipeline extends Resource<ComputePipelineProps> {
+  static override defaultProps: Required<ComputePipelineProps> = {
+    ...Resource.defaultProps,
+    cs: undefined,
+    csEntryPoint: undefined,
+    csConstants: {},
+    shaderLayout: []
+  };  
+
+  override get [Symbol.toStringTag](): string {
+    return 'ComputePipeline';
+  }
+
+  hash: string = '';
+
+  constructor(device: Device, props: ComputePipelineProps) {
+    super(device, props, ComputePipeline.defaultProps);
+  }
+}

package/src/adapter/resources/external-texture.ts

@@ -0,0 +1,20 @@
+import type {Device} from '../device';
+import {Resource, ResourceProps} from './resource';
+
+export type ExternalTextureProps = ResourceProps & {
+  source: HTMLVideoElement | null;
+  colorSpace?: 'srgb';
+}
+export abstract class ExternalTexture extends Resource<ExternalTextureProps> {
+  static override defaultProps: Required<ExternalTextureProps> = {
+    ...Resource.defaultProps,
+    source: null,
+    colorSpace: 'srgb'
+  };
+
+  override get [Symbol.toStringTag](): string { return 'ExternalTexture'; }
+
+  constructor(device: Device, props: ExternalTextureProps) {
+    super(device, props, ExternalTexture.defaultProps);
+  }
+}

package/src/adapter/resources/framebuffer.ts

@@ -0,0 +1,230 @@
+// luma.gl, MIT license
+// Copyright (c) vis.gl contributors
+
+import type {ColorTextureFormat, DepthStencilTextureFormat, TextureFormat} from '../types/texture-formats';
+import type {Device} from '../device';
+import {Resource, ResourceProps} from './resource';
+import {Texture} from './texture';
+import {log} from '../../utils/log';
+
+export type FramebufferProps = ResourceProps & {
+  width?: number;
+  height?: number;
+  colorAttachments?: (Texture | ColorTextureFormat)[];
+  depthStencilAttachment?: (Texture | DepthStencilTextureFormat) | null;
+};
+
+/**
+ * Create new textures with correct size for all attachments.
+ * @note resize() destroys existing textures (if size has changed).
+ */
+export abstract class Framebuffer extends Resource<FramebufferProps> {
+  static override defaultProps: Required<FramebufferProps> = {
+    ...Resource.defaultProps,
+    width: 1,
+    height: 1,
+    colorAttachments: [], // ['rgba8unorm-unsized'],
+    depthStencilAttachment: null // 'depth24plus-stencil8'
+  };  
+
+  override get [Symbol.toStringTag](): string {
+    return 'Framebuffer';
+  }
+
+  /** Width of all attachments in this framebuffer */
+  width: number;
+  /** Height of all attachments in this framebuffer */
+  height: number;
+  /** Color attachments */
+  colorAttachments: Texture[] = [];
+  /** Depth-stencil attachment, if provided */
+  depthStencilAttachment: Texture | null = null;
+
+  constructor(device: Device, props: FramebufferProps = {}) {
+    super(device, props, Framebuffer.defaultProps);
+    this.width = this.props.width;
+    this.height = this.props.height;
+
+    // NOTE: call from subclass constructor as we cannot call overridden methods here (subclass not yet constructed)
+    // this.autoCreateAttachmentTextures();
+  }
+
+  /**
+   * Resizes all attachments
+   * @note resize() destroys existing textures (if size has changed).
+   */
+  resize(size: {width: number; height: number;}): void;
+  resize(size: [width: number, height: number]): void;
+  resize(): void;
+  resize(size?: {width: number; height: number} | [width: number, height: number]): void {
+    let updateSize: boolean = !size;
+    if (size) {
+      const [width, height] = Array.isArray(size) ? size : [size.width, size.height];
+      updateSize = updateSize || height !== this.height || width !== this.width;
+      this.width = width;
+      this.height = height;
+    }
+    if (updateSize) {
+      log.log(2, `Resizing framebuffer ${this.id} to ${this.width}x${this.height}`)();
+      this.resizeAttachments(this.width, this.height);
+    }
+  }
+
+  // /** Returns fully populated attachment object. */
+  // protected normalizeColorAttachment(
+  //   attachment: Texture | ColorTextureFormat
+  // ): Required<ColorAttachment> {
+
+  //   const COLOR_ATTACHMENT_DEFAULTS: Required<ColorAttachment> = {
+  //     texture: undefined!,
+  //     format: undefined!,
+  //     clearValue: [0.0, 0.0, 0.0, 0.0],
+  //     loadOp: 'clear',
+  //     storeOp: 'store'
+  //   };
+
+  //   if (attachment instanceof Texture) {
+  //     return {...COLOR_ATTACHMENT_DEFAULTS, texture: attachment};
+  //   }
+  //   if (typeof attachment === 'string') {
+  //     return {...COLOR_ATTACHMENT_DEFAULTS, format: attachment};
+  //   }
+  //   return {...COLOR_ATTACHMENT_DEFAULTS, ...attachment};
+  // }
+
+  // /** Wraps texture inside fully populated attachment object. */
+  // protected normalizeDepthStencilAttachment(
+  //   attachment: DepthStencilAttachment | Texture | DepthStencilTextureFormat
+  // ): Required<DepthStencilAttachment> {
+  //   const DEPTH_STENCIL_ATTACHMENT_DEFAULTS: Required<DepthStencilAttachment> = {
+  //     texture: undefined!,
+  //     format: undefined!,
+
+  //     depthClearValue: 1.0,
+  //     depthLoadOp: 'clear',
+  //     depthStoreOp: 'store',
+  //     depthReadOnly: false,
+
+  //     stencilClearValue: 0,
+  //     stencilLoadOp: 'clear',
+  //     stencilStoreOp: 'store',
+  //     stencilReadOnly: false
+  //   };
+
+  //   if (typeof attachment === 'string') {
+  //     return {...DEPTH_STENCIL_ATTACHMENT_DEFAULTS, format: attachment};
+  //   }
+  //   // @ts-expect-error attachment instanceof Texture doesn't cover Renderbuffer
+  //   if (attachment.handle || attachment instanceof Texture) {
+  //     return {...DEPTH_STENCIL_ATTACHMENT_DEFAULTS, texture: attachment as Texture};
+  //   }
+  //   return {...DEPTH_STENCIL_ATTACHMENT_DEFAULTS, ...attachment};
+  // }
+
+  /** Auto creates any textures */
+  protected autoCreateAttachmentTextures(){
+    this.colorAttachments = this.props.colorAttachments.map(attachment => {
+      if (typeof attachment === 'string') {
+        const texture = this.createColorTexture(attachment);
+        this.attachResource(texture);
+        return texture;
+      }
+      return attachment;
+    });
+
+    if (this.props.depthStencilAttachment) {
+      if (typeof this.props.depthStencilAttachment === 'string') {
+        const texture = this.createDepthStencilTexture(this.props.depthStencilAttachment);
+        this.attachResource(texture);
+        this.depthStencilAttachment = texture;
+      } else {
+        this.depthStencilAttachment = this.props.depthStencilAttachment;
+      }
+    }
+  }
+
+  /** Create a color texture */
+  protected createColorTexture(format: TextureFormat): Texture {
+    return this.device.createTexture({
+      id: 'color-attachment',
+      usage: Texture.RENDER_ATTACHMENT,
+      format,
+      width: this.width,
+      height: this.height,
+    });
+  }
+
+  /** Create depth stencil texture */
+  protected createDepthStencilTexture(format: TextureFormat): Texture {
+    return this.device.createTexture({
+      id: 'depth-stencil-attachment',
+      usage: Texture.RENDER_ATTACHMENT,
+      format,
+      width: this.width,
+      height: this.height
+    });
+  }
+
+  /**
+   * Default implementation of resize
+   * Creates new textures with correct size for all attachments.
+   * and destroys existing textures if owned
+   */
+  protected resizeAttachments(width: number, height: number): void {
+    for (let i = 0; i < this.colorAttachments.length; ++i) {
+      if (this.colorAttachments[i]) {
+        const resizedTexture = this.device._createTexture({
+          ...this.colorAttachments[i].props,
+          width,
+          height
+        });
+        this.destroyAttachedResource(this.colorAttachments[i]);
+        this.colorAttachments[i] = resizedTexture;
+        this.attachResource(resizedTexture);
+      }
+    }
+
+    if (this.depthStencilAttachment) {
+      const resizedTexture = this.device._createTexture({
+        ...this.depthStencilAttachment.props,
+        width,
+        height
+      });
+      this.destroyAttachedResource(this.depthStencilAttachment);
+      this.depthStencilAttachment = resizedTexture;
+      this.attachResource(resizedTexture);
+    }
+  }
+
+  /** Create a color attachment for WebGL *
+  protected override createColorTexture(colorAttachment: Required<ColorAttachment>): Required<ColorAttachment> {
+    return this.device._createTexture({
+      id: `${this.id}-color`,
+      data: null, // reserves texture memory, but texels are undefined
+      format,
+      // type: GL.UNSIGNED_BYTE,
+      width: this.width,
+      height: this.height,
+      // Note: Mipmapping can be disabled by texture resource when we resize the texture
+      // to a non-power-of-two dimenstion (NPOT texture) under WebGL1. To have consistant
+      // behavior we always disable mipmaps.
+      mipmaps: false,
+      // Set MIN and MAG filtering parameters so mipmaps are not used in sampling.
+      // Use LINEAR so subpixel algos like fxaa work.
+      // Set WRAP modes that support NPOT textures too.
+      sampler: {
+        minFilter: 'linear',
+        magFilter: 'linear',
+        addressModeU: 'clamp-to-edge',
+        addressModeV: 'clamp-to-edge'
+      }
+      // parameters: {
+      //   [GL.TEXTURE_MIN_FILTER]: GL.LINEAR,
+      //   [GL.TEXTURE_MAG_FILTER]: GL.LINEAR,
+      //   [GL.TEXTURE_WRAP_S]: GL.CLAMP_TO_EDGE,
+      //   [GL.TEXTURE_WRAP_T]: GL.CLAMP_TO_EDGE
+      // }
+    });
+  }
+  */
+}

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

@@ -0,0 +1,117 @@
+// luma.gl, MIT license
+import type {Device} from '../device'
+import type { RenderPassParameters } from '../types/parameters';
+// import {Binding} from '../types/shader-layout';
+import {Resource, ResourceProps} from './resource';
+// import {Buffer} from './buffer';
+// import {RenderPipeline} from './render-pipeline';
+// import {CommandEncoder} from './command-encoder';
+import {Framebuffer} from './framebuffer';
+import {NumberArray} from '../..';
+
+/**
+ * Properties for a RenderPass instance is a required parameter to all draw calls.
+ */
+export type RenderPassProps = ResourceProps & {
+  /** Framebuffer specifies which textures to render into. Default gets framebuffer from canvas context. */
+  framebuffer?: Framebuffer | null;
+  /** Control viewport, scissor rect, blend constant and stencil ref */
+  parameters?: RenderPassParameters;
+  /** Clear value for color attachment, or `load` to preserve the previous value */
+  clearColor?: NumberArray | false;
+  /** Clear value for depth attachment, or `load` to preserve the previous value */
+  clearDepth?: number | false;
+  /** Clear value for stencil attachment, or `load` to preserve the previous value */
+  clearStencil?: number | false;
+  /** Indicates that the depth component is read only. */
+  depthReadOnly?: boolean;
+  /** Indicates that the stencil component is read only. */
+  stencilReadOnly?: boolean;
+  /** Whether to disable / discard the output of the rasterizer */
+  discard?: boolean; 
+};
+
+/**
+ * A RenderPass instance is a required parameter to all draw calls.
+ * 
+ * It holds a combination of 
+ * - render targets (specified via a framebuffer)
+ * - clear colors, read/write, discard information for the framebuffer attachments
+ * - a couple of mutable parameters ()
+ */
+export abstract class RenderPass extends Resource<RenderPassProps> {
+
+  /** Default properties for RenderPass */
+  static override defaultProps: Required<RenderPassProps> = {
+    ...Resource.defaultProps,
+    framebuffer: null,
+    parameters: undefined,
+    clearColor: [0, 0, 0, 0],
+    clearDepth: 1,
+    clearStencil: 0,
+    depthReadOnly: false,
+    stencilReadOnly: false,
+    discard: false
+  };
+
+  override get [Symbol.toStringTag](): string {
+    return 'RenderPass';
+  }
+
+  constructor(device: Device, props: RenderPassProps) {
+    super(device, props, RenderPass.defaultProps);
+  }
+
+  /** Call when rendering is done in this pass. */
+  abstract end(): void;
+
+  /** 
+   * A small set of parameters can be changed between every draw call 
+   * (viewport, scissorRect, blendColor, stencilReference) 
+   */
+  abstract setParameters(parameters: RenderPassParameters): void;
+
+  abstract pushDebugGroup(groupLabel: string): void;
+  abstract popDebugGroup(): void;
+  abstract insertDebugMarker(markerLabel: string): void;
+
+  // writeTimestamp(querySet: GPUQuerySet, queryIndex: number): void;
+
+  // beginOcclusionQuery(queryIndex: number): void;
+  // endOcclusionQuery(): void;
+
+  // executeBundles(bundles: Iterable<GPURenderBundle>): void;
+
+  // In WebGPU the following methods are on the renderpass.
+  // luma.gl keeps them on the pipeline for now
+
+  /*
+  setPipeline(pipeline: RenderPipeline): void {}
+
+  setIndexBuffer(
+    buffer: Buffer,
+    indexFormat: 'uint16' | 'uint32',
+    offset?: number,
+    size?: number
+  ): void {}
+
+  abstract setVertexBuffer(slot: number, buffer: Buffer, offset: number): void;
+
+  abstract setBindings(bindings: Record<string, Binding>): void;
+
+  abstract setParameters(parameters: RenderPassParameters);
+
+  draw(options: {
+    vertexCount?: number; // Either vertexCount or indexCount must be provided
+    indexCount?: number;  // Activates indexed drawing (call setIndexBuffer())
+    instanceCount?: number; //
+    firstVertex?: number;
+    firstIndex?: number; // requires device.features.has('indirect-first-instance')?
+    firstInstance?: number;
+    baseVertex?: number;
+  }): void {}
+
+  drawIndirect(indirectBuffer: GPUBuffer, indirectOffset: number): void;
+  drawIndexedIndirect(indirectBuffer: GPUBuffer, indirectOffset: number): void;
+  */
+}