@woosh/meep-engine 3.55.0 → 3.57.0

package/src/shade/renderer/shader/type/WebGPUStruct.js

@@ -1,455 +1,461 @@
-import { assert } from "../../../../core/assert.js";
-import LineBuilder from "../../../../core/codegen/LineBuilder.js";
-import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
-import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
-import { isArrayEqual } from "../../../../core/collection/array/isArrayEqual.js";
-import { round_up } from "../../../../core/math/round_up.js";
-import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
-import { CodeChunk } from "../compiler/CodeChunk.js";
-import { parse_wgsl_type } from "./parse_wgsl_type.js";
-import { WebGPUType } from "./WebGPUType.js";
-import { wgsl_struct_pack_field_heuristic } from "./wgsl_struct_pack_field_heuristic.js";
-import { WGSLStructField } from "./WGSLStructField.js";
-
-/**
- *
- * @type {number}
- */
-let id_counter = 0;
-
-/**
- * Unique name generator for WebGPU structs
- * @returns {string}
- */
-function generate_name() {
-    return `Struct_${id_counter++}`;
-}
-
-/**
- * WebGPU has somewhat unintuitive alignment rules, this structure exists to help with figuring those out automatically
- *
- * @see https://www.w3.org/TR/WGSL/#struct-types
- */
-export class WebGPUStruct extends WebGPUType {
-    /**
-     * Type name, used in declaration inside the shader
-     * @type {string}
-     */
-    #name = "";
-
-    get tag() {
-        return this.#name;
-    }
-
-    /**
-     *
-     * @param {string} value
-     */
-    set tag(value) {
-        this.#name = value;
-    }
-
-    /**
-     * @readonly
-     * @type {WGSLStructField[]}
-     */
-    fields = [];
-
-    /**
-     *
-     * @type {boolean}
-     */
-    #is_built = false;
-
-    #size = 0;
-    #align = 0;
-
-    get size() {
-        return this.#size;
-    }
-
-    get align() {
-        return this.#align;
-    }
-
-    /**
-     *
-     * @param {WebGPUStruct} other
-     * @returns {this}
-     */
-    copy(other) {
-        assert.isInstanceOf(other, WebGPUStruct, 'other');
-
-        this.#name = other.#name;
-        this.#size = other.#size;
-        this.#align = other.#align;
-
-        /**
-         * Carried with the layout it describes. Without it a clone claimed a size and per-field
-         * offsets while reading as unbuilt, and `pack()` — which reorders the fields and then
-         * rebuilds only `if (this.#is_built)` — left the declaration in the packed order and the
-         * offsets in the unpacked one. WGSL would lay a field out at one address and
-         * `write_struct_value` seek to another, with no error anywhere.
-         */
-        this.#is_built = other.#is_built;
-
-        //the cached WGSL text belongs to the struct that built it
-        this.#declaration_chunk = undefined;
-
-        this.fields = other.fields.map(f => f.clone());
-
-        return this;
-    }
-
-    /**
-     *
-     * @return {WebGPUStruct}
-     */
-    clone() {
-        const r = new WebGPUStruct();
-
-        r.copy(this);
-
-        r.#name = generate_name();
-
-        return r;
-    }
-
-    /**
-     * Construct a new instance declaration using specific values.
-     * Useful as it performs validation and orders fields correctly, making refactoring easier and code more readable.
-     *
-     * @param {Object} value
-     * @returns {string}
-     * @example
-     *    x = ${X.make({a:7,b:3})}; // x = X(7,3);
-     */
-    make(value) {
-        const builder = new LineBuilder();
-        builder.add(`${this.wgsl_ref}(`);
-        builder.indent();
-
-        const fields = this.fields;
-        const count = fields.length;
-
-        for (let i = 0; i < count; i++) {
-            const field = fields[i];
-
-            const name = field.name;
-
-            const input_value = value[name];
-
-            // TODO use defaults for missing fields, follow WGSL spec (0)
-            if (input_value === undefined) {
-                throw new Error(`Missing field '${name}'`);
-            }
-
-            builder.add(`${input_value},`);
-        }
-
-        builder.dedent();
-        builder.add(')');
-
-        return builder.build();
-    }
-
-    /**
-     * WebGPU has somewhat unintuitive alignment rules, this method will reorder fields to achieve the lowest memory usage possible.
-     * Make sure you use {@link make} method in code generation if you pack your data, as positions of fields are subject to change.
-     *
-     * @see https://www.w3.org/TR/WGSL/#struct-types
-     * @returns {this}
-     */
-    pack() {
-        if (this.fields.length <= 1) {
-            return this;
-        }
-
-        // a runtime-sized member (e.g. unbounded array) must remain the last field
-        const reorderable = [];
-        const trailing = [];
-        for (const f of this.fields) {
-            if (f.type.runtime_sized) {
-                trailing.push(f);
-            } else {
-                reorderable.push(f);
-            }
-        }
-
-        const ordered = wgsl_struct_pack_field_heuristic(reorderable);
-
-        this.fields = ordered.concat(trailing);
-
-        // The order of the fields has changed, so we need to rebuild the struct
-        if (this.#is_built) {
-            const old_size = this.#size
-
-            this.#build();
-
-            const new_size = this.#size;
-
-            if (new_size !== old_size) {
-                // console.log(`Struct ${this.#name} size changed from ${old_size} to ${new_size}`);
-            }
-        }
-
-        return this;
-    }
-
-    equals(other) {
-        if (other === this) {
-            return true;
-        }
-
-        if (!(other instanceof WebGPUStruct)) {
-            return false;
-        }
-
-        return this.#name === other.#name
-            && isArrayEqual(this.fields, other.fields)
-            ;
-    }
-
-    hash() {
-        return hash_mix2(
-            hash_mix3(
-                computeStringHash(this.name),
-                this.#size,
-                this.#align
-            ),
-            this.fields.length
-        );
-    }
-
-    get requires_declaration() {
-        return true;
-    }
-
-    get runtime_sized() {
-        const fields = this.fields;
-
-        for (let i = 0; i < fields.length; i++) {
-
-            const field = fields[i];
-
-            if (field.type.runtime_sized) {
-                return true;
-            }
-
-        }
-
-        return false;
-    }
-
-    /**
-     * @example
-     *  WebGPUStruct.from({
-     *      x: 'f32',
-     *      y: 'vec4f',
-     *      nested: WebGPUStruct.from({
-     *          a: 'f32',
-     *          m: 'mat4x4<f32>',
-     *      }),
-     *  });
-     *
-     * @param {Object<string|WebGPUType>} spec
-     * @param {string} [name] If not provided, a procedural name will be assigned instead. This is generally preferred to avoid name collisions
-     * @return {WebGPUStruct}
-     */
-    static from(
-        spec,
-        name = generate_name()
-    ) {
-        assert.isObject(spec, 'spec');
-        assert.isString(name, 'name');
-
-        const struct = new WebGPUStruct();
-
-        struct.#name = name;
-
-        for (const specKey in spec) {
-            const type_declarator = spec[specKey];
-
-            let type;
-            if (typeof type_declarator === 'string') {
-                // TODO deprecate
-                type = parse_wgsl_type(type_declarator);
-            } else if (type_declarator.isWebGPUType === true) {
-                type = type_declarator;
-            } else {
-                throw new Error(`Unsupported type declarator '${type_declarator}'`);
-            }
-
-            struct.#add(WGSLStructField.from(specKey, type));
-
-        }
-
-        struct.#build();
-
-        return struct;
-    }
-
-    /**
-     *
-     * @param {...WGSLStructField} fields
-     * @return {WebGPUStruct}
-     */
-    static fromFields(...fields) {
-        assert.isArray(fields, 'fields');
-        assert.greaterThanOrEqual(fields.length, 1, 'at least one field is required');
-
-        const r = new WebGPUStruct();
-
-        r.#name = generate_name();
-
-        for (const field of fields) {
-            r.#add(field);
-        }
-
-        r.#build();
-
-        return r;
-    }
-
-    /**
-     *
-     * @param {string} field_name
-     * @returns {boolean}
-     */
-    has(field_name) {
-        assert.isString(field_name, 'field_name');
-        return this.fields.some(f => f.name === field_name);
-    }
-
-
-    /**
-     *
-     * @param {string} field_name
-     * @return {WGSLStructField}
-     * @throws {Error} iff field not found
-     */
-    get(field_name) {
-        assert.isString(field_name, 'field_name');
-
-        const field = this.fields.find(f => f.name === field_name);
-
-        if (field === undefined) {
-            throw new Error(`Field '${field_name}' not found`);
-        }
-
-        return field;
-    }
-
-    /**
-     *
-     * @param {WGSLStructField} field
-     */
-    #add(field) {
-        assert.defined(field, 'field');
-        assert.notNull(field, 'field');
-        assert.isObject(field, 'field');
-        assert.equal(field.isWGSLStructField, true, 'field.isWGSLStructField !== true');
-
-        assert.notOk(this.has(field.name), `Field '${field.name}' already exists`);
-
-        this.fields.push(field);
-
-    }
-
-    #build() {
-
-        // TODO validate fields
-        //      - any runtime-sized field must be last
-
-        const fields = this.fields;
-        const field_count = fields.length;
-
-        let max_alignment = 1;
-
-        let cursor = 0;
-        for (let i = 0; i < field_count; i++) {
-            const field = fields[i];
-
-            const aligned_offset = round_up(cursor, field.align);
-
-            if (max_alignment < field.align) {
-                max_alignment = field.align;
-            }
-
-            field.offset = aligned_offset;
-
-            cursor = field.offset + field.size;
-        }
-
-        this.#align = max_alignment;
-        this.#size = round_up(cursor, max_alignment);
-
-        // clear declaration
-        this.#declaration_chunk = undefined;
-        this.#is_built = true;
-    }
-
-
-    get wgsl_ref() {
-        return this.#name;
-    }
-
-    get wgsl_declaration() {
-        const b = new LineBuilder();
-
-        b.add(`struct ${this.#name}{`);
-        b.indent();
-
-        for (let i = 0; i < this.fields.length; i++) {
-            const field = this.fields[i];
-
-
-            b.add(`${field.generate()},`);
-
-        }
-
-        b.dedent();
-        b.add(`}`);
-
-        return b.build();
-    }
-
-    /**
-     * @type {CodeChunk}
-     */
-    #declaration_chunk
-
-    get declaration_chunk() {
-
-        if (this.#declaration_chunk === undefined) {
-
-            // not yet present, construct
-
-            const chunk = CodeChunk.from(this.wgsl_declaration);
-
-            const fields = this.fields;
-            const field_count = fields.length;
-
-            for (let i = 0; i < field_count; i++) {
-                const field = fields[i];
-
-                const field_type = field.type;
-
-                if (field_type.requires_declaration) {
-                    chunk.addDependency(field_type.declaration_chunk)
-                }
-
-            }
-
-            this.#declaration_chunk = chunk;
-        }
-
-        return this.#declaration_chunk;
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-WebGPUStruct.prototype.isStruct = true;
+import { assert } from "../../../../core/assert.js";
+import LineBuilder from "../../../../core/codegen/LineBuilder.js";
+import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
+import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
+import { isArrayEqual } from "../../../../core/collection/array/isArrayEqual.js";
+import { round_up } from "../../../../core/math/round_up.js";
+import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import { CodeChunk } from "../compiler/CodeChunk.js";
+import { parse_wgsl_type } from "./parse_wgsl_type.js";
+import { type_has_f16 } from "./type_has_f16.js";
+import { WebGPUType } from "./WebGPUType.js";
+import { wgsl_struct_pack_field_heuristic } from "./wgsl_struct_pack_field_heuristic.js";
+import { WGSLStructField } from "./WGSLStructField.js";
+
+/**
+ *
+ * @type {number}
+ */
+let id_counter = 0;
+
+/**
+ * Unique name generator for WebGPU structs
+ * @returns {string}
+ */
+function generate_name() {
+    return `Struct_${id_counter++}`;
+}
+
+/**
+ * WebGPU has somewhat unintuitive alignment rules, this structure exists to help with figuring those out automatically
+ *
+ * @see https://www.w3.org/TR/WGSL/#struct-types
+ */
+export class WebGPUStruct extends WebGPUType {
+    /**
+     * Type name, used in declaration inside the shader
+     * @type {string}
+     */
+    #name = "";
+
+    get tag() {
+        return this.#name;
+    }
+
+    /**
+     *
+     * @param {string} value
+     */
+    set tag(value) {
+        this.#name = value;
+    }
+
+    /**
+     * @readonly
+     * @type {WGSLStructField[]}
+     */
+    fields = [];
+
+    /**
+     *
+     * @type {boolean}
+     */
+    #is_built = false;
+
+    #size = 0;
+    #align = 0;
+
+    get size() {
+        return this.#size;
+    }
+
+    get align() {
+        return this.#align;
+    }
+
+    /**
+     *
+     * @param {WebGPUStruct} other
+     * @returns {this}
+     */
+    copy(other) {
+        assert.isInstanceOf(other, WebGPUStruct, 'other');
+
+        this.#name = other.#name;
+        this.#size = other.#size;
+        this.#align = other.#align;
+
+        /**
+         * Carried with the layout it describes. Without it a clone claimed a size and per-field
+         * offsets while reading as unbuilt, and `pack()` — which reorders the fields and then
+         * rebuilds only `if (this.#is_built)` — left the declaration in the packed order and the
+         * offsets in the unpacked one. WGSL would lay a field out at one address and
+         * `write_struct_value` seek to another, with no error anywhere.
+         */
+        this.#is_built = other.#is_built;
+
+        //the cached WGSL text belongs to the struct that built it
+        this.#declaration_chunk = undefined;
+
+        this.fields = other.fields.map(f => f.clone());
+
+        return this;
+    }
+
+    /**
+     *
+     * @return {WebGPUStruct}
+     */
+    clone() {
+        const r = new WebGPUStruct();
+
+        r.copy(this);
+
+        r.#name = generate_name();
+
+        return r;
+    }
+
+    /**
+     * Construct a new instance declaration using specific values.
+     * Useful as it performs validation and orders fields correctly, making refactoring easier and code more readable.
+     *
+     * @param {Object} value
+     * @returns {string}
+     * @example
+     *    x = ${X.make({a:7,b:3})}; // x = X(7,3);
+     */
+    make(value) {
+        const builder = new LineBuilder();
+        builder.add(`${this.wgsl_ref}(`);
+        builder.indent();
+
+        const fields = this.fields;
+        const count = fields.length;
+
+        for (let i = 0; i < count; i++) {
+            const field = fields[i];
+
+            const name = field.name;
+
+            const input_value = value[name];
+
+            // TODO use defaults for missing fields, follow WGSL spec (0)
+            if (input_value === undefined) {
+                throw new Error(`Missing field '${name}'`);
+            }
+
+            builder.add(`${input_value},`);
+        }
+
+        builder.dedent();
+        builder.add(')');
+
+        return builder.build();
+    }
+
+    /**
+     * WebGPU has somewhat unintuitive alignment rules, this method will reorder fields to achieve the lowest memory usage possible.
+     * Make sure you use {@link make} method in code generation if you pack your data, as positions of fields are subject to change.
+     *
+     * @see https://www.w3.org/TR/WGSL/#struct-types
+     * @returns {this}
+     */
+    pack() {
+        if (this.fields.length <= 1) {
+            return this;
+        }
+
+        // a runtime-sized member (e.g. unbounded array) must remain the last field
+        const reorderable = [];
+        const trailing = [];
+        for (const f of this.fields) {
+            if (f.type.runtime_sized) {
+                trailing.push(f);
+            } else {
+                reorderable.push(f);
+            }
+        }
+
+        const ordered = wgsl_struct_pack_field_heuristic(reorderable);
+
+        this.fields = ordered.concat(trailing);
+
+        // The order of the fields has changed, so we need to rebuild the struct
+        if (this.#is_built) {
+            const old_size = this.#size
+
+            this.#build();
+
+            const new_size = this.#size;
+
+            if (new_size !== old_size) {
+                // console.log(`Struct ${this.#name} size changed from ${old_size} to ${new_size}`);
+            }
+        }
+
+        return this;
+    }
+
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+
+        if (!(other instanceof WebGPUStruct)) {
+            return false;
+        }
+
+        return this.#name === other.#name
+            && isArrayEqual(this.fields, other.fields)
+            ;
+    }
+
+    hash() {
+        return hash_mix2(
+            hash_mix3(
+                computeStringHash(this.name),
+                this.#size,
+                this.#align
+            ),
+            this.fields.length
+        );
+    }
+
+    get requires_declaration() {
+        return true;
+    }
+
+    get runtime_sized() {
+        const fields = this.fields;
+
+        for (let i = 0; i < fields.length; i++) {
+
+            const field = fields[i];
+
+            if (field.type.runtime_sized) {
+                return true;
+            }
+
+        }
+
+        return false;
+    }
+
+    /**
+     * @example
+     *  WebGPUStruct.from({
+     *      x: 'f32',
+     *      y: 'vec4f',
+     *      nested: WebGPUStruct.from({
+     *          a: 'f32',
+     *          m: 'mat4x4<f32>',
+     *      }),
+     *  });
+     *
+     * @param {Object<string|WebGPUType>} spec
+     * @param {string} [name] If not provided, a procedural name will be assigned instead. This is generally preferred to avoid name collisions
+     * @return {WebGPUStruct}
+     */
+    static from(
+        spec,
+        name = generate_name()
+    ) {
+        assert.isObject(spec, 'spec');
+        assert.isString(name, 'name');
+
+        const struct = new WebGPUStruct();
+
+        struct.#name = name;
+
+        for (const specKey in spec) {
+            const type_declarator = spec[specKey];
+
+            let type;
+            if (typeof type_declarator === 'string') {
+                // TODO deprecate
+                type = parse_wgsl_type(type_declarator);
+            } else if (type_declarator.isWebGPUType === true) {
+                type = type_declarator;
+            } else {
+                throw new Error(`Unsupported type declarator '${type_declarator}'`);
+            }
+
+            struct.#add(WGSLStructField.from(specKey, type));
+
+        }
+
+        struct.#build();
+
+        return struct;
+    }
+
+    /**
+     *
+     * @param {...WGSLStructField} fields
+     * @return {WebGPUStruct}
+     */
+    static fromFields(...fields) {
+        assert.isArray(fields, 'fields');
+        assert.greaterThanOrEqual(fields.length, 1, 'at least one field is required');
+
+        const r = new WebGPUStruct();
+
+        r.#name = generate_name();
+
+        for (const field of fields) {
+            r.#add(field);
+        }
+
+        r.#build();
+
+        return r;
+    }
+
+    /**
+     *
+     * @param {string} field_name
+     * @returns {boolean}
+     */
+    has(field_name) {
+        assert.isString(field_name, 'field_name');
+        return this.fields.some(f => f.name === field_name);
+    }
+
+
+    /**
+     *
+     * @param {string} field_name
+     * @return {WGSLStructField}
+     * @throws {Error} iff field not found
+     */
+    get(field_name) {
+        assert.isString(field_name, 'field_name');
+
+        const field = this.fields.find(f => f.name === field_name);
+
+        if (field === undefined) {
+            throw new Error(`Field '${field_name}' not found`);
+        }
+
+        return field;
+    }
+
+    /**
+     *
+     * @param {WGSLStructField} field
+     */
+    #add(field) {
+        assert.defined(field, 'field');
+        assert.notNull(field, 'field');
+        assert.isObject(field, 'field');
+        assert.equal(field.isWGSLStructField, true, 'field.isWGSLStructField !== true');
+
+        assert.notOk(this.has(field.name), `Field '${field.name}' already exists`);
+
+        this.fields.push(field);
+
+    }
+
+    #build() {
+
+        // TODO validate fields
+        //      - any runtime-sized field must be last
+
+        const fields = this.fields;
+        const field_count = fields.length;
+
+        let max_alignment = 1;
+
+        let cursor = 0;
+        for (let i = 0; i < field_count; i++) {
+            const field = fields[i];
+
+            const aligned_offset = round_up(cursor, field.align);
+
+            if (max_alignment < field.align) {
+                max_alignment = field.align;
+            }
+
+            field.offset = aligned_offset;
+
+            cursor = field.offset + field.size;
+        }
+
+        this.#align = max_alignment;
+        this.#size = round_up(cursor, max_alignment);
+
+        // clear declaration
+        this.#declaration_chunk = undefined;
+        this.#is_built = true;
+    }
+
+
+    get wgsl_ref() {
+        return this.#name;
+    }
+
+    get wgsl_declaration() {
+        const b = new LineBuilder();
+
+        b.add(`struct ${this.#name}{`);
+        b.indent();
+
+        for (let i = 0; i < this.fields.length; i++) {
+            const field = this.fields[i];
+
+
+            b.add(`${field.generate()},`);
+
+        }
+
+        b.dedent();
+        b.add(`}`);
+
+        return b.build();
+    }
+
+    /**
+     * @type {CodeChunk}
+     */
+    #declaration_chunk
+
+    get declaration_chunk() {
+
+        if (this.#declaration_chunk === undefined) {
+
+            // not yet present, construct
+
+            const chunk = CodeChunk.from(this.wgsl_declaration);
+
+            const fields = this.fields;
+            const field_count = fields.length;
+
+            for (let i = 0; i < field_count; i++) {
+                const field = fields[i];
+
+                const field_type = field.type;
+
+                if (field_type.requires_declaration) {
+                    chunk.addDependency(field_type.declaration_chunk)
+                }
+
+            }
+
+            if (type_has_f16(this)) {
+                chunk.addExtension(WebGPUExtensionType.ShaderF16);
+            }
+
+            this.#declaration_chunk = chunk;
+        }
+
+        return this.#declaration_chunk;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+WebGPUStruct.prototype.isStruct = true;