@luma.gl/engine 9.0.0-alpha.9 → 9.0.0-beta.10

package/src/computation.ts

@@ -0,0 +1,346 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TypedArray} from '@luma.gl/core';
+import type {DeviceFeature, ComputePipelineProps, Shader, Binding} from '@luma.gl/core';
+import {Device, Buffer, ComputePipeline, ComputePass, UniformStore} from '@luma.gl/core';
+import {log, uid, isNumberArray} from '@luma.gl/core';
+import {getTypedArrayFromDataType} from '@luma.gl/core';
+import type {ShaderModule, PlatformInfo} from '@luma.gl/shadertools';
+import {ShaderAssembler, getShaderLayoutFromWGSL} from '@luma.gl/shadertools';
+import {ShaderInputs} from './shader-inputs';
+import {PipelineFactory} from './lib/pipeline-factory';
+import {ShaderFactory} from './lib/shader-factory';
+// import {getDebugTableForShaderLayout} from '../debug/debug-shader-layout';
+
+const LOG_DRAW_PRIORITY = 2;
+const LOG_DRAW_TIMEOUT = 10000;
+
+export type ComputationProps = Omit<ComputePipelineProps, 'shader'> & {
+  source?: string;
+
+  /** shadertool shader modules (added to shader code) */
+  modules?: ShaderModule[];
+  /** Shadertool module defines (configures shader code)*/
+  defines?: Record<string, string | number | boolean>;
+  // TODO - injections, hooks etc?
+
+  /** Shader inputs, used to generated uniform buffers and bindings */
+  shaderInputs?: ShaderInputs;
+
+  /** Bindings */
+  bindings?: Record<string, Binding>;
+
+  /** Show shader source in browser? */
+  debugShaders?: 'never' | 'errors' | 'warnings' | 'always';
+
+  /** Factory used to create a {@link ComputePipeline}. Defaults to {@link Device} default factory. */
+  pipelineFactory?: PipelineFactory;
+  /** Factory used to create a {@link Shader}. Defaults to {@link Device} default factory. */
+  shaderFactory?: ShaderFactory;
+  /** Shader assembler. Defaults to the ShaderAssembler.getShaderAssembler() */
+  shaderAssembler?: ShaderAssembler;
+};
+
+/**
+ * v9 Model API
+ * A model
+ * - automatically reuses pipelines (programs) when possible
+ * - automatically rebuilds pipelines if necessary to accommodate changed settings
+ * shadertools integration
+ * - accepts modules and performs shader transpilation
+ */
+export class Computation {
+  static defaultProps: Required<ComputationProps> = {
+    ...ComputePipeline.defaultProps,
+    id: 'unnamed',
+    handle: undefined,
+    userData: {},
+
+    source: '',
+    modules: [],
+    defines: {},
+
+    bindings: undefined!,
+    shaderInputs: undefined!,
+
+    pipelineFactory: undefined!,
+    shaderFactory: undefined!,
+    shaderAssembler: ShaderAssembler.getDefaultShaderAssembler(),
+
+    debugShaders: undefined
+  };
+
+  readonly device: Device;
+  readonly id: string;
+
+  readonly pipelineFactory: PipelineFactory;
+  readonly shaderFactory: ShaderFactory;
+
+  userData: {[key: string]: any} = {};
+
+  /** Bindings (textures, samplers, uniform buffers) */
+  bindings: Record<string, Binding> = {};
+
+  /** The underlying GPU "program". @note May be recreated if parameters change */
+  pipeline: ComputePipeline;
+  /** the underlying compiled compute shader */
+  shader: Shader;
+  source: string;
+
+  /** ShaderInputs instance */
+  shaderInputs: ShaderInputs;
+
+  _uniformStore: UniformStore;
+
+  _pipelineNeedsUpdate: string | false = 'newly created';
+
+  private _getModuleUniforms: (props?: Record<string, Record<string, any>>) => Record<string, any>;
+  private props: Required<ComputationProps>;
+
+  private _destroyed = false;
+
+  constructor(device: Device, props: ComputationProps) {
+    if (device.type !== 'webgpu') {
+      throw new Error('Computation is only supported in WebGPU');
+    }
+
+    this.props = {...Computation.defaultProps, ...props};
+    props = this.props;
+    this.id = props.id || uid('model');
+    this.device = device;
+
+    Object.assign(this.userData, props.userData);
+
+    // Setup shader module inputs
+    const moduleMap = Object.fromEntries(
+      this.props.modules?.map(module => [module.name, module]) || []
+    );
+    this.setShaderInputs(props.shaderInputs || new ShaderInputs(moduleMap));
+
+    // Support WGSL shader layout introspection
+    // TODO - Don't modify props!!
+    this.props.shaderLayout ||= getShaderLayoutFromWGSL(this.props.source);
+
+    // Setup shader assembler
+    const platformInfo = getPlatformInfo(device);
+
+    // Extract modules from shader inputs if not supplied
+    const modules =
+      (this.props.modules?.length > 0 ? this.props.modules : this.shaderInputs?.getModules()) || [];
+
+    this.pipelineFactory =
+      props.pipelineFactory || PipelineFactory.getDefaultPipelineFactory(this.device);
+    this.shaderFactory = props.shaderFactory || ShaderFactory.getDefaultShaderFactory(this.device);
+
+    const {source, getUniforms} = this.props.shaderAssembler.assembleShader({
+      platformInfo,
+      ...this.props,
+      modules
+    });
+
+    this.source = source;
+
+    this._getModuleUniforms = getUniforms;
+
+    // Create the pipeline
+    // @note order is important
+    this.pipeline = this._updatePipeline();
+
+    // Apply any dynamic settings that will not trigger pipeline change
+    if (props.bindings) {
+      this.setBindings(props.bindings);
+    }
+
+    // Catch any access to non-standard props
+    Object.seal(this);
+  }
+
+  destroy(): void {
+    if (this._destroyed) return;
+    this.pipelineFactory.release(this.pipeline);
+    this.shaderFactory.release(this.shader);
+    this._uniformStore.destroy();
+    this._destroyed = true;
+  }
+
+  // Draw call
+
+  predraw() {
+    // Update uniform buffers if needed
+    this.updateShaderInputs();
+  }
+
+  dispatch(computePass: ComputePass, x: number, y?: number, z?: number): void {
+    try {
+      this._logDrawCallStart();
+
+      // Check if the pipeline is invalidated
+      // TODO - this is likely the worst place to do this from performance perspective. Perhaps add a predraw()?
+      this.pipeline = this._updatePipeline();
+
+      // Set pipeline state, we may be sharing a pipeline so we need to set all state on every draw
+      // Any caching needs to be done inside the pipeline functions
+      this.pipeline.setBindings(this.bindings);
+      computePass.setPipeline(this.pipeline);
+      // @ts-expect-error
+      computePass.setBindings([]);
+
+      computePass.dispatch(x, y, z);
+    } finally {
+      this._logDrawCallEnd();
+    }
+  }
+
+  // Update fixed fields (can trigger pipeline rebuild)
+
+  // Update dynamic fields
+
+  /**
+   * Updates the vertex count (used in draw calls)
+   * @note Any attributes with stepMode=vertex need to be at least this big
+   */
+  setVertexCount(vertexCount: number): void {
+    // this.vertexCount = vertexCount;
+  }
+
+  /**
+   * Updates the instance count (used in draw calls)
+   * @note Any attributes with stepMode=instance need to be at least this big
+   */
+  setInstanceCount(instanceCount: number): void {
+    // this.instanceCount = instanceCount;
+  }
+
+  setShaderInputs(shaderInputs: ShaderInputs): void {
+    this.shaderInputs = shaderInputs;
+    this._uniformStore = new UniformStore(this.shaderInputs.modules);
+    // Create uniform buffer bindings for all modules
+    for (const moduleName of Object.keys(this.shaderInputs.modules)) {
+      const uniformBuffer = this._uniformStore.getManagedUniformBuffer(this.device, moduleName);
+      this.bindings[`${moduleName}Uniforms`] = uniformBuffer;
+    }
+  }
+
+  /**
+   * Updates shader module settings (which results in uniforms being set)
+   */
+  setShaderModuleProps(props: Record<string, any>): void {
+    const uniforms = this._getModuleUniforms(props);
+
+    // Extract textures & framebuffers set by the modules
+    // TODO better way to extract bindings
+    const keys = Object.keys(uniforms).filter(k => {
+      const uniform = uniforms[k];
+      return !isNumberArray(uniform) && typeof uniform !== 'number' && typeof uniform !== 'boolean';
+    });
+    const bindings: Record<string, Binding> = {};
+    for (const k of keys) {
+      bindings[k] = uniforms[k];
+      delete uniforms[k];
+    }
+  }
+
+  updateShaderInputs(): void {
+    this._uniformStore.setUniforms(this.shaderInputs.getUniformValues());
+  }
+
+  /**
+   * Sets bindings (textures, samplers, uniform buffers)
+   */
+  setBindings(bindings: Record<string, Binding>): void {
+    Object.assign(this.bindings, bindings);
+  }
+
+  _setPipelineNeedsUpdate(reason: string): void {
+    this._pipelineNeedsUpdate = this._pipelineNeedsUpdate || reason;
+  }
+
+  _updatePipeline(): ComputePipeline {
+    if (this._pipelineNeedsUpdate) {
+      let prevShader: Shader | null = null;
+      if (this.pipeline) {
+        log.log(
+          1,
+          `Model ${this.id}: Recreating pipeline because "${this._pipelineNeedsUpdate}".`
+        )();
+        prevShader = this.shader;
+      }
+
+      this._pipelineNeedsUpdate = false;
+
+      this.shader = this.shaderFactory.createShader({
+        id: `${this.id}-fragment`,
+        stage: 'compute',
+        source: this.source,
+        debug: this.props.debugShaders
+      });
+
+      this.pipeline = this.pipelineFactory.createComputePipeline({
+        ...this.props,
+        shader: this.shader
+      });
+
+      if (prevShader) {
+        this.shaderFactory.release(prevShader);
+      }
+    }
+    return this.pipeline;
+  }
+
+  /** Throttle draw call logging */
+  _lastLogTime = 0;
+  _logOpen = false;
+
+  _logDrawCallStart(): void {
+    // IF level is 4 or higher, log every frame.
+    const logDrawTimeout = log.level > 3 ? 0 : LOG_DRAW_TIMEOUT;
+    if (log.level < 2 || Date.now() - this._lastLogTime < logDrawTimeout) {
+      return;
+    }
+
+    this._lastLogTime = Date.now();
+    this._logOpen = true;
+
+    log.group(LOG_DRAW_PRIORITY, `>>> DRAWING MODEL ${this.id}`, {collapsed: log.level <= 2})();
+  }
+
+  _logDrawCallEnd(): void {
+    if (this._logOpen) {
+      // const shaderLayoutTable = getDebugTableForShaderLayout(this.pipeline.props.shaderLayout, this.id);
+
+      // log.table(logLevel, attributeTable)();
+      // log.table(logLevel, uniformTable)();
+      // log.table(LOG_DRAW_PRIORITY, shaderLayoutTable)();
+
+      const uniformTable = this.shaderInputs.getDebugTable();
+      log.table(LOG_DRAW_PRIORITY, uniformTable)();
+
+      log.groupEnd(LOG_DRAW_PRIORITY)();
+      this._logOpen = false;
+    }
+  }
+
+  protected _drawCount = 0;
+
+  // TODO - fix typing of luma data types
+  _getBufferOrConstantValues(attribute: Buffer | TypedArray, dataType: any): string {
+    const TypedArrayConstructor = getTypedArrayFromDataType(dataType);
+    const typedArray =
+      attribute instanceof Buffer ? new TypedArrayConstructor(attribute.debugData) : attribute;
+    return typedArray.toString();
+  }
+}
+
+/** Create a shadertools platform info from the Device */
+export function getPlatformInfo(device: Device): PlatformInfo {
+  return {
+    type: device.type,
+    shaderLanguage: device.info.shadingLanguage,
+    shaderLanguageVersion: device.info.shadingLanguageVersion as 100 | 300,
+    gpu: device.info.gpu,
+    // HACK - we pretend that the DeviceFeatures is a Set, it has a similar API
+    features: device.features as unknown as Set<DeviceFeature>
+  };
+}

package/src/debug/copy-texture-to-image.ts

@@ -0,0 +1,70 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Texture, Framebuffer} from '@luma.gl/core';
+import {flipRows, scalePixels} from './pixel-data-utils';
+
+/**
+ * Options for copying texture pixels to image
+ * @todo - support gl.readBuffer
+ */
+export type CopyTextureToImageOptions = {
+  sourceAttachment?: number;
+  targetMaxHeight?: number;
+  targetImage?: HTMLImageElement;
+};
+
+/**
+ * Reads pixels from a Framebuffer or Texture object into an HTML Image
+ * @todo - can we move this to @luma.gl/core?
+ * @param source
+ * @param options options passed to copyToDataUrl
+ * @returns
+ */
+export function copyTextureToImage(
+  source: Texture | Framebuffer,
+  options?: CopyTextureToImageOptions
+): HTMLImageElement {
+  const dataUrl = copyTextureToDataUrl(source, options);
+  const targetImage: HTMLImageElement = options?.targetImage || new Image();
+  targetImage.src = dataUrl;
+
+  return targetImage;
+}
+
+/**
+ * Reads pixels from a Framebuffer or Texture object to a dataUrl
+ * @todo - can we move this to @luma.gl/core?
+ * @param source texture or framebuffer to read from
+ * @param options
+ */
+export function copyTextureToDataUrl(
+  source: Texture | Framebuffer,
+  options: CopyTextureToImageOptions = {}
+): string {
+  const {sourceAttachment, targetMaxHeight = Number.MAX_SAFE_INTEGER} = options;
+
+  let data = source.device.readPixelsToArrayWebGL(source, {sourceAttachment});
+
+  // Scale down
+  let {width, height} = source;
+  while (height > targetMaxHeight) {
+    ({data, width, height} = scalePixels({data, width, height}));
+  }
+
+  // Flip to top down coordinate system
+  flipRows({data, width, height});
+
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  const context = canvas.getContext('2d');
+
+  // Copy the pixels to a 2D canvas
+  const imageData = context.createImageData(width, height);
+  imageData.data.set(data);
+  context.putImageData(imageData, 0, 0);
+
+  return canvas.toDataURL('image/png');
+}

package/src/debug/debug-framebuffer.ts

@@ -0,0 +1,70 @@
+import type {Framebuffer, Texture} from '@luma.gl/core';
+// import {copyTextureToImage} from '../debug/copy-texture-to-image';
+
+/** Only works with 1st device? */
+let canvas: HTMLCanvasElement | null = null;
+let ctx: CanvasRenderingContext2D | null = null;
+// let targetImage: HTMLImageElement | null = null;
+
+/** Debug utility to draw FBO contents onto screen */
+// eslint-disable-next-line
+export function debugFramebuffer(
+  fbo: Framebuffer | Texture,
+  {
+    id,
+    minimap,
+    opaque,
+    top = '0',
+    left = '0',
+    rgbaScale = 1
+  }: {
+    id: string;
+    minimap?: boolean;
+    opaque?: boolean;
+    top?: string;
+    left?: string;
+    rgbaScale?: number;
+  }
+) {
+  if (!canvas) {
+    canvas = document.createElement('canvas');
+    canvas.id = id;
+    canvas.title = id;
+    canvas.style.zIndex = '100';
+    canvas.style.position = 'absolute';
+    canvas.style.top = top; // ⚠️
+    canvas.style.left = left; // ⚠️
+    canvas.style.border = 'blue 1px solid';
+    canvas.style.transform = 'scaleY(-1)';
+    document.body.appendChild(canvas);
+
+    ctx = canvas.getContext('2d');
+    // targetImage = new Image();
+  }
+
+  // const canvasHeight = (minimap ? 2 : 1) * fbo.height;
+  if (canvas.width !== fbo.width || canvas.height !== fbo.height) {
+    canvas.width = fbo.width / 2;
+    canvas.height = fbo.height / 2;
+    canvas.style.width = '400px';
+    canvas.style.height = '400px';
+  }
+
+  // const image = copyTextureToImage(fbo, {targetMaxHeight: 100, targetImage});
+  // ctx.drawImage(image, 0, 0);
+
+  const color = fbo.device.readPixelsToArrayWebGL(fbo);
+  const imageData = ctx.createImageData(fbo.width, fbo.height);
+  // Full map
+  const offset = 0;
+  // if (color.some((v) => v > 0)) {
+  //   console.error('THERE IS NON-ZERO DATA IN THE FBO!');
+  // }
+  for (let i = 0; i < color.length; i += 4) {
+    imageData.data[offset + i + 0] = color[i + 0] * rgbaScale;
+    imageData.data[offset + i + 1] = color[i + 1] * rgbaScale;
+    imageData.data[offset + i + 2] = color[i + 2] * rgbaScale;
+    imageData.data[offset + i + 3] = opaque ? 255 : color[i + 3] * rgbaScale;
+  }
+  ctx.putImageData(imageData, 0, 0);
+}

package/src/debug/debug-shader-layout.ts

@@ -0,0 +1,38 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ShaderLayout} from '@luma.gl/core';
+
+/**
+ * Extracts a table suitable for `console.table()` from a shader layout to assist in debugging.
+ * @param layout shader layout
+ * @param name app should provide the most meaningful name, usually the model or pipeline name / id.
+ * @returns
+ */
+export function getDebugTableForShaderLayout(
+  layout: ShaderLayout,
+  name: string
+): Record<string, Record<string, string>> {
+  const table: Record<string, Record<string, string>> = {};
+
+  const header = 'Values'; // '`Shader Layout for ${name}`;
+
+  if (layout.attributes.length === 0 && !layout.varyings?.length) {
+    return {'No attributes or varyings': {[header]: 'N/A'}};
+  }
+
+  for (const attributeDeclaration of layout.attributes) {
+    if (attributeDeclaration) {
+      const glslDeclaration = `${attributeDeclaration.location} ${attributeDeclaration.name}: ${attributeDeclaration.type}`;
+      table[`in ${glslDeclaration}`] = {[header]: attributeDeclaration.stepMode || 'vertex'};
+    }
+  }
+
+  for (const varyingDeclaration of layout.varyings || []) {
+    const glslDeclaration = `${varyingDeclaration.location} ${varyingDeclaration.name}`;
+    table[`out ${glslDeclaration}`] = {[header]: JSON.stringify(varyingDeclaration.accessor)};
+  }
+
+  return table;
+}

package/src/debug/pixel-data-utils.ts

@@ -0,0 +1,54 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {TypedArray} from '@luma.gl/core';
+
+/**
+ * Flip rows (can be used on arrays returned from `Framebuffer.readPixels`)
+ * https: *stackoverflow.com/questions/41969562/
+ * how-can-i-flip-the-result-of-webglrenderingcontext-readpixels
+ * @param param0
+ */
+export function flipRows(options: {
+  data: TypedArray;
+  width: number;
+  height: number;
+  bytesPerPixel?: number;
+  temp?: Uint8Array;
+}): void {
+  const {data, width, height, bytesPerPixel = 4, temp} = options;
+  const bytesPerRow = width * bytesPerPixel;
+
+  // make a temp buffer to hold one row
+  const tempBuffer = temp || new Uint8Array(bytesPerRow);
+  for (let y = 0; y < height / 2; ++y) {
+    const topOffset = y * bytesPerRow;
+    const bottomOffset = (height - y - 1) * bytesPerRow;
+    // make copy of a row on the top half
+    tempBuffer.set(data.subarray(topOffset, topOffset + bytesPerRow));
+    // copy a row from the bottom half to the top
+    data.copyWithin(topOffset, bottomOffset, bottomOffset + bytesPerRow);
+    // copy the copy of the top half row to the bottom half
+    data.set(tempBuffer, bottomOffset);
+  }
+}
+
+export function scalePixels(options: {data: TypedArray; width: number; height: number}): {
+  data: Uint8Array;
+  width: number;
+  height: number;
+} {
+  const {data, width, height} = options;
+  const newWidth = Math.round(width / 2);
+  const newHeight = Math.round(height / 2);
+  const newData = new Uint8Array(newWidth * newHeight * 4);
+  for (let y = 0; y < newHeight; y++) {
+    for (let x = 0; x < newWidth; x++) {
+      for (let c = 0; c < 4; c++) {
+        newData[(y * newWidth + x) * 4 + c] = data[(y * 2 * width + x * 2) * 4 + c];
+      }
+    }
+  }
+  return {data: newData, width: newWidth, height: newHeight};
+}

package/src/geometries/cone-geometry.ts

@@ -1,4 +1,4 @@
-import {uid} from '@luma.gl/api';
+import {uid} from '@luma.gl/core';
 import {TruncatedConeGeometry} from './truncated-cone-geometry';
 
 export type ConeGeometryProps = {