@woosh/meep-engine 3.11.3 → 3.12.0

package/src/shade/renderer/shader/util/compute_infer_workgroup_size_from_source.js

@@ -0,0 +1,448 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * WGSL blankspace, as the set of code points with the Unicode `Pattern_White_Space` property.
+ *
+ * Spelled out rather than using `\s`, which is wrong in both directions here: it omits next line
+ * (U+0085) and the two bidi marks that WGSL counts as blankspace, and it adds no-break space, the
+ * ogham space mark, the en/em quad family and the byte order mark, which WGSL does not.
+ *
+ * @see https://www.w3.org/TR/WGSL/#blankspace-and-line-breaks
+ * @type {string}
+ */
+const BLANKSPACE = '[\\u0020\\u0009\\u000A\\u000B\\u000C\\u000D\\u0085\\u200E\\u200F\\u2028\\u2029]';
+
+/**
+ * A WGSL `int_literal`, being a `decimal_int_literal` or a `hex_int_literal`.
+ *
+ * The hexadecimal form is tried first, otherwise `0x40` would match the bare `0` of the decimal
+ * form and leave `x40` behind. The decimal form rejects a leading zero on a non-zero number, which
+ * WGSL forbids so that `012` cannot be misread as octal by someone arriving from another language.
+ *
+ * @see https://www.w3.org/TR/WGSL/#syntax-int_literal
+ * @type {string}
+ */
+const INT_LITERAL = '(?:0[xX][0-9a-fA-F]+[iu]?|[1-9][0-9]*[iu]?|0[iu]?)';
+
+/**
+ * A WGSL `ident_pattern_token`.
+ *
+ * Deliberately looser than the grammar, which also excludes the keywords and the lone underscore.
+ * Nothing is lost by admitting them: a name is only ever looked up among the module's constants,
+ * and `const if = 1;` is no more a declaration than `if` is an identifier.
+ *
+ * No identifier may begin with a digit, which is what lets a matched argument be sorted into
+ * literal or name by its first code point alone.
+ *
+ * @see https://www.w3.org/TR/WGSL/#identifiers
+ * @type {string}
+ */
+const IDENTIFIER = '(?:[_\\p{XID_Start}][\\p{XID_Continue}]*)';
+
+/**
+ * One argument of `@workgroup_size`: an integer literal, or a name that may resolve to one.
+ *
+ * @type {string}
+ */
+const ARGUMENT = `(?:${INT_LITERAL}|${IDENTIFIER})`;
+
+/**
+ * `@workgroup_size` up to and including its opening parenthesis.
+ *
+ * `'@'` and `'workgroup_size'` are separate tokens in the grammar, and the tokenizer discards
+ * blankspace ahead of every token, so `@ workgroup_size (` is as valid as `@workgroup_size(`. The
+ * lookahead stops `@workgroup_size_hint(...)` from matching, because the longest-match rule reads
+ * that as a single identifier token that merely starts with the name we are looking for.
+ *
+ * @see https://www.w3.org/TR/WGSL/#syntax-workgroup_size_attr
+ * @type {RegExp}
+ */
+const ATTRIBUTE_HEAD = new RegExp(
+    `@${BLANKSPACE}*workgroup_size(?!\\p{XID_Continue})${BLANKSPACE}*\\(`,
+    'gu'
+);
+
+/**
+ * The argument list of `@workgroup_size`, matched sticky from just past the opening parenthesis.
+ *
+ * One, two or three arguments, with a single optional trailing comma before the closing
+ * parenthesis. Requiring `)` immediately after the arguments is what makes a compound expression
+ * such as `BLOCK_DIM / 2u` fail to match outright rather than match some prefix of itself.
+ *
+ * @type {RegExp}
+ */
+const ATTRIBUTE_ARGUMENTS = new RegExp(
+    `${BLANKSPACE}*(${ARGUMENT})`
+    + `(?:${BLANKSPACE}*,${BLANKSPACE}*(${ARGUMENT}))?`
+    + `(?:${BLANKSPACE}*,${BLANKSPACE}*(${ARGUMENT}))?`
+    + `${BLANKSPACE}*(?:,${BLANKSPACE}*)?\\)`,
+    'uy'
+);
+
+/**
+ * A `const` declaration whose value is written as a plain integer literal.
+ *
+ * This is one level of aliasing and no more: the value must be the literal itself, so
+ * `const BLOCK_DIM = 256u;` and `const BLOCK_DIM: u32 = 256u;` are read, while
+ * `const HALF_BLOCK = BLOCK_DIM / 2u;` does not match at all and that name stays unresolved. One
+ * level is the whole of what a shader needs in order to state its block size once, and stopping
+ * there keeps this a scanner rather than the beginnings of a const-expression evaluator.
+ *
+ * The lookaround around `const` keeps it a whole token, so neither `myconst` nor `const_assert` is
+ * mistaken for the keyword.
+ *
+ * @see https://www.w3.org/TR/WGSL/#const-decls
+ * @type {RegExp}
+ */
+const CONST_DECLARATION = new RegExp(
+    `(?<!\\p{XID_Continue})const(?!\\p{XID_Continue})`
+    + `${BLANKSPACE}*(${IDENTIFIER})${BLANKSPACE}*`
+    + `(?::${BLANKSPACE}*${IDENTIFIER}${BLANKSPACE}*)?`
+    + `=${BLANKSPACE}*(${INT_LITERAL})${BLANKSPACE}*;`,
+    'gu'
+);
+
+const SOLIDUS = 0x2F;
+const ASTERISK = 0x2A;
+
+/**
+ * Code points that end a line-ending comment, being the WGSL line breaks.
+ *
+ * Carriage return terminates the comment whether or not a line feed follows it; leaving that line
+ * feed behind is harmless, as it is blankspace either way.
+ *
+ * @see https://www.w3.org/TR/WGSL/#blankspace-and-line-breaks
+ * @param {number} code_point
+ * @returns {boolean}
+ */
+function is_line_break(code_point) {
+    return code_point === 0x000A
+        || code_point === 0x000B
+        || code_point === 0x000C
+        || code_point === 0x000D
+        || code_point === 0x0085
+        || code_point === 0x2028
+        || code_point === 0x2029;
+}
+
+/**
+ * Replace every comment with a single space, which is the first step the spec takes when parsing a
+ * module, before it has any notion of tokens or attributes.
+ *
+ * This has to happen before the search, and it cannot be folded into the search as another
+ * alternative in a regular expression: WGSL block comments nest, and the spec points out that this
+ * puts them outside the regular languages. A commented-out `@workgroup_size(1)` sitting above a
+ * real entry point is otherwise indistinguishable from the real thing.
+ *
+ * An unterminated block comment is not a legal comment at all, so such a module is already invalid.
+ * It is treated as running to the end of the source, which is the reading that declines to find an
+ * attribute inside the wreckage rather than inventing one.
+ *
+ * @see https://www.w3.org/TR/WGSL/#parsing
+ * @param {string} code WGSL source
+ * @returns {string}
+ */
+function strip_comments(code) {
+    if (!code.includes('/')) {
+        // no comment can exist without a solidus, and most shaders reach here
+        return code;
+    }
+
+    const length = code.length;
+
+    let result = '';
+    let copy_from = 0;
+    let i = 0;
+
+    while (i < length) {
+
+        if (code.charCodeAt(i) !== SOLIDUS) {
+            i++;
+            continue;
+        }
+
+        const next = code.charCodeAt(i + 1);
+
+        if (next === SOLIDUS) {
+
+            result += code.slice(copy_from, i) + ' ';
+
+            i += 2;
+
+            while (i < length && !is_line_break(code.charCodeAt(i))) {
+                i++;
+            }
+
+            copy_from = i;
+
+        } else if (next === ASTERISK) {
+
+            result += code.slice(copy_from, i) + ' ';
+
+            i += 2;
+
+            let depth = 1;
+
+            while (i < length && depth > 0) {
+
+                const head = code.charCodeAt(i);
+                const tail = code.charCodeAt(i + 1);
+
+                if (head === SOLIDUS && tail === ASTERISK) {
+                    depth++;
+                    i += 2;
+                } else if (head === ASTERISK && tail === SOLIDUS) {
+                    depth--;
+                    i += 2;
+                } else {
+                    i++;
+                }
+
+            }
+
+            copy_from = i;
+
+        } else {
+            i++;
+        }
+
+    }
+
+    return result + code.slice(copy_from);
+}
+
+/**
+ * The start of an attribute, for quoting back in a diagnostic.
+ *
+ * Quoted rather than located by offset: the search runs over the comment-stripped source, whose
+ * offsets drift from the caller's source by however much comment text was removed ahead of them, so
+ * any index reported here would point somewhere subtly wrong in the file the caller is reading.
+ *
+ * @param {string} source comment-stripped WGSL
+ * @param {number} index
+ * @returns {string}
+ */
+function quote_attribute(source, index) {
+    const LIMIT = 64;
+
+    const excerpt = source.slice(index, index + LIMIT);
+
+    return source.length > index + LIMIT
+        ? `'${excerpt}...'`
+        : `'${excerpt}'`;
+}
+
+/**
+ * Read one integer literal as a number.
+ *
+ * The `i`/`u` suffix is dropped; it records the literal's type, which has no bearing on its value.
+ *
+ * @param {string} literal
+ * @returns {number}
+ */
+function literal_to_number(literal) {
+    const suffix = literal.charCodeAt(literal.length - 1);
+
+    const digits = (suffix === 0x69 /* i */ || suffix === 0x75 /* u */)
+        ? literal.slice(0, -1)
+        : literal;
+
+    return Number(digits);
+}
+
+/**
+ * Whether a matched argument is an integer literal rather than a name.
+ *
+ * The argument came out of {@link ARGUMENT}, so it is one or the other, and no identifier may begin
+ * with a digit — the first code point settles it.
+ *
+ * @param {string} argument
+ * @returns {boolean}
+ */
+function is_int_literal(argument) {
+    const first = argument.charCodeAt(0);
+
+    return first >= 0x30 /* 0 */ && first <= 0x39 /* 9 */;
+}
+
+/**
+ * Every name the module binds directly to an integer literal with `const`.
+ *
+ * A name declared twice with disagreeing values maps to `null` rather than to either of them. WGSL
+ * lets a function-scope `const` shadow a module-scope one, and telling those apart is a question of
+ * scope, which this scanner does not track — so a name that means two things is taken to mean
+ * neither.
+ *
+ * @param {string} source comment-stripped WGSL
+ * @returns {Map<string, number|null>} name to value, or to `null` where declarations disagree
+ */
+function collect_integer_constants(source) {
+    const result = new Map();
+
+    CONST_DECLARATION.lastIndex = 0;
+
+    let declaration;
+
+    while ((declaration = CONST_DECLARATION.exec(source)) !== null) {
+
+        const name = declaration[1];
+        const value = literal_to_number(declaration[2]);
+
+        const existing = result.get(name);
+
+        result.set(name, (existing === undefined || existing === value) ? value : null);
+
+    }
+
+    return result;
+}
+
+/**
+ * Recover a compute entry point's workgroup size from its WGSL source.
+ *
+ * Follows the `workgroup_size_attr` grammar, so every spelling below is read alike, and the omitted
+ * dimensions default to `1`:
+ *
+ * ```wgsl
+ * @workgroup_size(64)              // -> [64, 1, 1]
+ * @workgroup_size(8, 8)            // -> [8, 8, 1]
+ * @workgroup_size( 8 , 8 , 4 , )   // -> [8, 8, 4], blankspace anywhere, trailing comma
+ * @workgroup_size(0x40u)           // -> [64, 1, 1], hexadecimal, and the i/u type suffixes
+ * ```
+ *
+ * An argument may also name a `const` that the same module binds directly to an integer literal,
+ * which is how a shader states its block size once and then uses it in both the attribute and the
+ * body:
+ *
+ * ```wgsl
+ * const BLOCK_DIM = 256u;
+ * @workgroup_size(BLOCK_DIM)       // -> [256, 1, 1]
+ * ```
+ *
+ * Comments count as blankspace and are removed first, so they may sit between any two tokens of the
+ * attribute, and an attribute that is itself commented out is correctly not found.
+ *
+ * **One level of aliasing, and no arithmetic.** WGSL permits any const-expression or
+ * override-expression, so `@workgroup_size(BLOCK_DIM / 2u)` is legal, and so is
+ * `@workgroup_size(WG_X)` for an `override WG_X` whose value only arrives with the pipeline.
+ * Neither is resolvable from the source text alone. Such a shader throws rather than being guessed
+ * at, because every caller for this number divides a thread count by it, and a wrong divisor
+ * silently dispatches the wrong fraction of the workload. A loud failure is recoverable; a
+ * plausible one is not.
+ *
+ * Entry points that disagree are an error for the same reason. A module may hold several, and
+ * choosing between two conflicting sizes would be choosing at random.
+ *
+ * @param {string} code WGSL source
+ * @returns {[number, number, number]} `[x, y, z]`
+ * @throws {Error} if no `@workgroup_size` attribute is present, if its arguments are neither
+ * integer literals nor names resolving to one, if a dimension is not a positive integer, or if
+ * entry points disagree on the size
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function compute_infer_workgroup_size_from_source(code) {
+    assert.isString(code, 'code');
+
+    const source = strip_comments(code);
+
+    ATTRIBUTE_HEAD.lastIndex = 0;
+
+    /**
+     * Built on first demand, as most shaders spell the size out and never ask for it.
+     * @type {Map<string, number|null>|null}
+     */
+    let constants = null;
+
+    let result = null;
+
+    let head;
+
+    while ((head = ATTRIBUTE_HEAD.exec(source)) !== null) {
+
+        ATTRIBUTE_ARGUMENTS.lastIndex = head.index + head[0].length;
+
+        const args = ATTRIBUTE_ARGUMENTS.exec(source);
+
+        if (args === null) {
+            throw new Error(
+                `@workgroup_size does not have one to three arguments, each an integer literal or a`
+                + ` name, and nothing else can be read from source: ${quote_attribute(source, head.index)}`
+            );
+        }
+
+        const size = [1, 1, 1];
+
+        for (let i = 0; i < 3; i++) {
+
+            const argument = args[i + 1];
+
+            if (argument === undefined) {
+                // "The second parameter, if provided, specifies the y dimension, otherwise is
+                // assumed to be 1."
+                continue;
+            }
+
+            if (is_int_literal(argument)) {
+                size[i] = literal_to_number(argument);
+                continue;
+            }
+
+            if (constants === null) {
+                constants = collect_integer_constants(source);
+            }
+
+            const value = constants.get(argument);
+
+            if (value === undefined) {
+                throw new Error(
+                    `@workgroup_size argument '${argument}' is not an integer literal, and the module`
+                    + ` has no 'const ${argument} = <integer literal>;' to resolve it by — an override,`
+                    + ` or a const bound to an expression, cannot be read from source:`
+                    + ` ${quote_attribute(source, head.index)}`
+                );
+            }
+
+            if (value === null) {
+                throw new Error(
+                    `@workgroup_size argument '${argument}' has conflicting 'const' declarations, so`
+                    + ` which of them the attribute sees cannot be told from source:`
+                    + ` ${quote_attribute(source, head.index)}`
+                );
+            }
+
+            size[i] = value;
+
+        }
+
+        for (let i = 0; i < 3; i++) {
+            const dimension = size[i];
+
+            if (!Number.isSafeInteger(dimension) || dimension < 1) {
+                // "A shader-creation error results if any specified parameter is a const-expression
+                // that evaluates to a non-positive value."
+                throw new Error(
+                    `@workgroup_size has dimension ${'xyz'[i]}=${dimension},`
+                    + ` expected a positive integer: ${quote_attribute(source, head.index)}`
+                );
+            }
+        }
+
+        if (result === null) {
+            result = size;
+        } else if (result[0] !== size[0] || result[1] !== size[1] || result[2] !== size[2]) {
+            throw new Error(
+                `source declares more than one workgroup size, [${result}] and [${size}]`
+                + ` in ${quote_attribute(source, head.index)}, so no single size can be inferred`
+            );
+        }
+
+    }
+
+    if (result === null) {
+        throw new Error('source does not declare a @workgroup_size attribute');
+    }
+
+    return result;
+}

package/src/shade/renderer/shadow/map/csm/graph_csm_setup_cascades.js

@@ -27,14 +27,14 @@ export function graph_csm_setup_cascades({
 
         const encoder = context.encoder;
 
-        shader_depth_reduce.dispatch({
+        shader_depth_reduce.dispatchThreads({
             encoder,
             bindings: {
                 tDepth: depth,
                 output,
             },
-            group_count_x: Math.ceil(depth.width / 8),
-            group_count_y: Math.ceil(depth.height / 8),
+            thread_count_x: depth.width,
+            thread_count_y: depth.height,
         });
 
     }

package/src/shade/renderer/shadow/ray/staged/gen/graph_gen_rays.js

@@ -41,10 +41,10 @@ export function graph_gen_rays({
 
         const scene_ctx = view.scene;
 
-        shader_generate_rays.dispatch({
+        shader_generate_rays.dispatchThreads({
             encoder: context.encoder,
-            group_count_x: Math.ceil(resolution[0] / 8),
-            group_count_y: Math.ceil(resolution[1] / 4),
+            thread_count_x: resolution[0],
+            thread_count_y: resolution[1],
             bindings: {
                 settings,
                 camera: view.camera.buffer.buffer,

package/src/shade/renderer/shadow/ray/staged/trace/graph_trace_rays.js

@@ -50,9 +50,9 @@ export function graph_trace_rays({
         // sees a different sample pattern from each glass occluder hit.
         const seed = (view.frame_index | 0) >>> 0;
 
-        shader_trace_rays.dispatch({
+        shader_trace_rays.dispatchThreads({
             encoder: context.encoder,
-            group_count_x: Math.ceil((resolution[0] * resolution[1]) / 32),
+            thread_count_x: resolution[0] * resolution[1],
             bindings: {
                 resolution_width: context.encoder.allocateTransientValueBuffer(u32, resolution[0]),
                 random_seed: context.encoder.allocateTransientValueBuffer(u32, seed),

package/src/shade/renderer/shadow/sdf/cascade/CascadedSceneSDF.js

@@ -147,7 +147,7 @@ export class CascadedSceneSDF {
          */
         const blas = geometries.blas;
 
-        shader.dispatch({
+        shader.dispatchThreads({
             encoder: command_ctx,
             bindings: {
                 output_texture: this.#texture.obtainView(),
@@ -161,9 +161,9 @@ export class CascadedSceneSDF {
                 meshlet_metadata: geometries.meshlets.buffer_metadata,
                 meshlet_data: geometries.meshlets.buffer_data,
             },
-            group_count_x: Math.ceil(size[0] / 4),
-            group_count_y: Math.ceil(size[1] / 4),
-            group_count_z: Math.ceil(size[2] / 4),
+            thread_count_x: size[0],
+            thread_count_y: size[1],
+            thread_count_z: size[2],
         });
 
     }

package/src/shade/renderer/texture/virtual/build_shader_vt_feedback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build_shader_vt_feedback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/virtual/build_shader_vt_feedback.js"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAJ6B,eAAe,EAAjC,SAAS;IACM,aAAa,EAA5B,MAAM;IACJ,aAAa,CAkKzB;AA7MD;;;;;;;;GAQG;AACH,qDAI8B;AAS9B,2CAA4C;0BA9BlB,oCAAoC;8BAChC,+BAA+B;6BAjBhC,mCAAmC"}
+{"version":3,"file":"build_shader_vt_feedback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/virtual/build_shader_vt_feedback.js"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAJ6B,eAAe,EAAjC,SAAS;IACM,aAAa,EAA5B,MAAM;IACJ,aAAa,CAiKzB;AA5MD;;;;;;;;GAQG;AACH,qDAI8B;AAS9B,2CAA4C;0BA9BlB,oCAAoC;8BAChC,+BAA+B;6BAjBhC,mCAAmC"}