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

package/dist/computation.js

@@ -0,0 +1,248 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { Buffer, ComputePipeline, UniformStore } from '@luma.gl/core';
+import { log, uid, isNumberArray } from '@luma.gl/core';
+import { getTypedArrayFromDataType } from '@luma.gl/core';
+import { ShaderAssembler, getShaderLayoutFromWGSL } from '@luma.gl/shadertools';
+import { ShaderInputs } from "./shader-inputs.js";
+import { PipelineFactory } from "./lib/pipeline-factory.js";
+import { ShaderFactory } from "./lib/shader-factory.js";
+// import {getDebugTableForShaderLayout} from '../debug/debug-shader-layout';
+const LOG_DRAW_PRIORITY = 2;
+const LOG_DRAW_TIMEOUT = 10000;
+/**
+ * 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 = {
+        ...ComputePipeline.defaultProps,
+        id: 'unnamed',
+        handle: undefined,
+        userData: {},
+        source: '',
+        modules: [],
+        defines: {},
+        bindings: undefined,
+        shaderInputs: undefined,
+        pipelineFactory: undefined,
+        shaderFactory: undefined,
+        shaderAssembler: ShaderAssembler.getDefaultShaderAssembler(),
+        debugShaders: undefined
+    };
+    device;
+    id;
+    pipelineFactory;
+    shaderFactory;
+    userData = {};
+    /** Bindings (textures, samplers, uniform buffers) */
+    bindings = {};
+    /** The underlying GPU "program". @note May be recreated if parameters change */
+    pipeline;
+    /** the underlying compiled compute shader */
+    shader;
+    source;
+    /** ShaderInputs instance */
+    shaderInputs;
+    _uniformStore;
+    _pipelineNeedsUpdate = 'newly created';
+    _getModuleUniforms;
+    props;
+    _destroyed = false;
+    constructor(device, props) {
+        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() {
+        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, x, y, z) {
+        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) {
+        // 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) {
+        // this.instanceCount = instanceCount;
+    }
+    setShaderInputs(shaderInputs) {
+        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) {
+        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 = {};
+        for (const k of keys) {
+            bindings[k] = uniforms[k];
+            delete uniforms[k];
+        }
+    }
+    updateShaderInputs() {
+        this._uniformStore.setUniforms(this.shaderInputs.getUniformValues());
+    }
+    /**
+     * Sets bindings (textures, samplers, uniform buffers)
+     */
+    setBindings(bindings) {
+        Object.assign(this.bindings, bindings);
+    }
+    _setPipelineNeedsUpdate(reason) {
+        this._pipelineNeedsUpdate = this._pipelineNeedsUpdate || reason;
+    }
+    _updatePipeline() {
+        if (this._pipelineNeedsUpdate) {
+            let prevShader = 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() {
+        // 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() {
+        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;
+        }
+    }
+    _drawCount = 0;
+    // TODO - fix typing of luma data types
+    _getBufferOrConstantValues(attribute, dataType) {
+        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) {
+    return {
+        type: device.type,
+        shaderLanguage: device.info.shadingLanguage,
+        shaderLanguageVersion: device.info.shadingLanguageVersion,
+        gpu: device.info.gpu,
+        // HACK - we pretend that the DeviceFeatures is a Set, it has a similar API
+        features: device.features
+    };
+}

package/dist/debug/copy-texture-to-image.d.ts

@@ -0,0 +1,26 @@
+import { Texture, Framebuffer } from '@luma.gl/core';
+/**
+ * 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 declare function copyTextureToImage(source: Texture | Framebuffer, options?: CopyTextureToImageOptions): HTMLImageElement;
+/**
+ * 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 declare function copyTextureToDataUrl(source: Texture | Framebuffer, options?: CopyTextureToImageOptions): string;
+//# sourceMappingURL=copy-texture-to-image.d.ts.map

package/dist/debug/copy-texture-to-image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy-texture-to-image.d.ts","sourceRoot":"","sources":["../../src/debug/copy-texture-to-image.ts"],"names":[],"mappings":"AAIA,OAAO,EAAC,OAAO,EAAE,WAAW,EAAC,MAAM,eAAe,CAAC;AAGnD;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,gBAAgB,CAAC;CAChC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,GAAG,WAAW,EAC7B,OAAO,CAAC,EAAE,yBAAyB,GAClC,gBAAgB,CAMlB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,GAAG,WAAW,EAC7B,OAAO,GAAE,yBAA8B,GACtC,MAAM,CAyBR"}

package/dist/debug/copy-texture-to-image.js

@@ -0,0 +1,43 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { flipRows, scalePixels } from "./pixel-data-utils.js";
+/**
+ * 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, options) {
+    const dataUrl = copyTextureToDataUrl(source, options);
+    const targetImage = 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, options = {}) {
+    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/dist/debug/debug-framebuffer.d.ts

@@ -0,0 +1,11 @@
+import type { Framebuffer, Texture } from '@luma.gl/core';
+/** Debug utility to draw FBO contents onto screen */
+export declare function debugFramebuffer(fbo: Framebuffer | Texture, { id, minimap, opaque, top, left, rgbaScale }: {
+    id: string;
+    minimap?: boolean;
+    opaque?: boolean;
+    top?: string;
+    left?: string;
+    rgbaScale?: number;
+}): void;
+//# sourceMappingURL=debug-framebuffer.d.ts.map

package/dist/debug/debug-framebuffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-framebuffer.d.ts","sourceRoot":"","sources":["../../src/debug/debug-framebuffer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,WAAW,EAAE,OAAO,EAAC,MAAM,eAAe,CAAC;AAQxD,qDAAqD;AAErD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,WAAW,GAAG,OAAO,EAC1B,EACE,EAAE,EACF,OAAO,EACP,MAAM,EACN,GAAS,EACT,IAAU,EACV,SAAa,EACd,EAAE;IACD,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,QA2CF"}

package/dist/debug/debug-framebuffer.js

@@ -0,0 +1,46 @@
+// import {copyTextureToImage} from '../debug/copy-texture-to-image';
+/** Only works with 1st device? */
+let canvas = null;
+let ctx = null;
+// let targetImage: HTMLImageElement | null = null;
+/** Debug utility to draw FBO contents onto screen */
+// eslint-disable-next-line
+export function debugFramebuffer(fbo, { id, minimap, opaque, top = '0', left = '0', rgbaScale = 1 }) {
+    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/dist/debug/debug-shader-layout.d.ts

@@ -0,0 +1,9 @@
+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 declare function getDebugTableForShaderLayout(layout: ShaderLayout, name: string): Record<string, Record<string, string>>;
+//# sourceMappingURL=debug-shader-layout.d.ts.map

package/dist/debug/debug-shader-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-shader-layout.d.ts","sourceRoot":"","sources":["../../src/debug/debug-shader-layout.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAsBxC"}

package/dist/debug/debug-shader-layout.js

@@ -0,0 +1,27 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+/**
+ * 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, name) {
+    const table = {};
+    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/dist/debug/pixel-data-utils.d.ts

@@ -0,0 +1,24 @@
+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 declare function flipRows(options: {
+    data: TypedArray;
+    width: number;
+    height: number;
+    bytesPerPixel?: number;
+    temp?: Uint8Array;
+}): void;
+export declare function scalePixels(options: {
+    data: TypedArray;
+    width: number;
+    height: number;
+}): {
+    data: Uint8Array;
+    width: number;
+    height: number;
+};
+//# sourceMappingURL=pixel-data-utils.d.ts.map

package/dist/debug/pixel-data-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixel-data-utils.d.ts","sourceRoot":"","sources":["../../src/debug/pixel-data-utils.ts"],"names":[],"mappings":"AAIA,OAAO,EAAC,UAAU,EAAC,MAAM,eAAe,CAAC;AAEzC;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE;IAChC,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB,GAAG,IAAI,CAgBP;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,GAAG;IACvF,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAaA"}

package/dist/debug/pixel-data-utils.js

@@ -0,0 +1,39 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+/**
+ * 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) {
+    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) {
+    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 };
+}