@woosh/meep-engine 3.43.0 → 3.45.0

package/src/shade/renderer/water/surface/particles/GPUWaterParticles.js

@@ -1,5 +1,8 @@
 import { assert } from "../../../../../core/assert.js";
-import { graph_prefix_scan_csdldf } from "../../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import {
+    graph_prefix_scan_csdldf,
+    prefix_scan_csdldf_output_descriptor
+} from "../../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
 import {
     build_indirect_compute_dispatch_command,
     INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
@@ -53,11 +56,14 @@ export class GPUWaterParticles {
     #parity = 0;
     #particles = [];
     #children = null;
+    #child_sums = null;
     #images = null;
     #fronts = null;
+    #front_sums = null;
     #runs = null;
     #draw = null;
     #buckets = null;
+    #offsets = null;
     #slots = null;
     #bucket_amplitude = null;
     #bucket_weight = null;
@@ -69,7 +75,7 @@ export class GPUWaterParticles {
     #commands = null;
 
     /** @returns {GPUBuffer} the frame's hash: table size, then inclusive bucket offsets */
-    get offsets() { return this.#buckets; }
+    get offsets() { return this.#offsets; }
     /** @returns {GPUBuffer} the frame's entries, bucket by bucket, each bucket ordered by particle */
     get entries() { return this.#entries; }
     /** @returns {GPUBuffer} per wave row: occupied-level mask, then a height bound per level (f32 bits) */
@@ -102,15 +108,21 @@ export class GPUWaterParticles {
                 size: Math.max(16, size), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC | usage });
             const array_size = 16 + capacity * WATER_PARTICLE_STRUCT.size;
             this.#particles = [buffer('a', array_size), buffer('b', array_size)];
+            // a scan reads one buffer and writes another: per particle how many it leaves, then where they end
+            const sums = elements => prefix_scan_csdldf_output_descriptor(elements).size;
             this.#children = buffer('children', 16 + capacity * 4);
+            this.#child_sums = buffer('child sums', sums(capacity));
             // per particle the mirror image the step left beside it at the outline
             this.#images = buffer('images', capacity * WATER_PARTICLE_STRUCT.size);
-            // per particle the scanned run it is in; per run its first particle and its share; per particle its run
-            // and how it is drawn
+            // per particle whether it starts a run, then the scanned run it is in; per run its first particle and its
+            // share; per particle its run and how it is drawn
             this.#fronts = buffer('fronts', 16 + capacity * 4);
+            this.#front_sums = buffer('front sums', sums(capacity));
             this.#runs = buffer('runs', capacity * 8);
             this.#draw = buffer('draw', capacity * 8);
+            // per bucket its entries, then the hash: table size and inclusive offsets
             this.#buckets = buffer('buckets', 16 + this.#table_limit * 4);
+            this.#offsets = buffer('offsets', sums(this.#table_limit));
             this.#slots = buffer('slots', capacity * WATER_PARTICLE_CORNERS * 4);
             this.#bucket_amplitude = buffer('bucket amplitude', this.#table_limit * 4);
             // the summed steepness, the largest front and front complement entered, and the entries; then the most a point
@@ -145,13 +157,15 @@ export class GPUWaterParticles {
     }
 
     dispose() {
-        for (const buffer of [...this.#particles, this.#children, this.#images, this.#fronts, this.#runs, this.#draw, this.#buckets, this.#slots,
-            this.#bucket_amplitude, this.#bucket_weight, this.#bucket_nest, this.#visible, this.#staging, this.#entries, this.#body_bounds, ...(this.#commands ?? [])]) {
+        for (const buffer of [...this.#particles, this.#children, this.#child_sums, this.#images, this.#fronts, this.#front_sums, this.#runs,
+            this.#draw, this.#buckets, this.#offsets, this.#slots, this.#bucket_amplitude, this.#bucket_weight, this.#bucket_nest, this.#visible,
+            this.#staging, this.#entries, this.#body_bounds, ...(this.#commands ?? [])]) {
             buffer?.destroy();
         }
         this.#particles = [];
-        this.#children = this.#images = this.#buckets = this.#slots = this.#bucket_amplitude = this.#staging = this.#entries = null;
-        this.#fronts = this.#runs = this.#draw = null;
+        this.#children = this.#child_sums = this.#images = this.#buckets = this.#offsets = this.#slots = this.#bucket_amplitude = null;
+        this.#staging = this.#entries = null;
+        this.#fronts = this.#front_sums = this.#runs = this.#draw = null;
         this.#bucket_weight = this.#bucket_nest = this.#visible = null;
         this.#body_bounds = null;
         this.#commands = null;
@@ -188,8 +202,11 @@ export class GPUWaterParticles {
         const [command_current, command_next, command_table] = this.#commands;
         const geometries = scene.geometries;
         let children = graph_import_buffer(graph, this.#children, 'Water / particle children');
+        let child_sums = graph_import_buffer(graph, this.#child_sums, 'Water / particle child sums');
         let buckets = graph_import_buffer(graph, this.#buckets, 'Water / particle buckets');
+        let offsets = graph_import_buffer(graph, this.#offsets, 'Water / particle offsets');
         let fronts = graph_import_buffer(graph, this.#fronts, 'Water / particle fronts');
+        let front_sums = graph_import_buffer(graph, this.#front_sums, 'Water / particle front sums');
         const node = (name, execute, reads, writes) => {
             const data = {};
             const pass = graph.add(name, data, (d, resources, context) => execute(resources, context, d));
@@ -211,19 +228,19 @@ export class GPUWaterParticles {
                     meshlet_metadata: geometries.meshlets.buffer_metadata, meshlet_data: geometries.meshlets.buffer_data,
                 } });
             }, {}, { children }).children;
-            children = graph_prefix_scan_csdldf({ graph, data: children, element_max_count: capacity });
+            child_sums = graph_prefix_scan_csdldf({ graph, input: children, output: child_sums, element_max_count: capacity });
 
             // What they leave into the next array, then the frame's splashes after them.
             node('Water / particles split and emit', (resources, { encoder }) => {
                 shader_water_particles_split.dispatchIndirect({ encoder, command: command_current, bindings: {
-                    capacity, particles: current, children: this.#children, images: this.#images, next } });
-                shader_water_particles_total.dispatch({ encoder, bindings: { capacity, children: this.#children, next } });
+                    capacity, particles: current, children: this.#child_sums, images: this.#images, next } });
+                shader_water_particles_total.dispatch({ encoder, bindings: { capacity, children: this.#child_sums, next } });
                 shader_water_particles_emit.dispatchIndirect({ encoder, command: commands, command_offset: emit_command,
                     bindings: { capacity, scene_database: scene.scene_database_buffer, emit_rows, steep, activity,
                         particle_bounds: this.#body_bounds, next } });
                 shader_water_particles_finalize.dispatch({ encoder, bindings: { limits: { capacity, table_limit }, next, offsets: this.#buckets,
                     table_command: command_table } });
-            }, { children }, {});
+            }, { child_sums }, {});
         }
 
         // Each front's run of particles, so that a whole one is drawn as the seven it was emitted as.
@@ -237,14 +254,14 @@ export class GPUWaterParticles {
             encoder.copyBufferToBuffer(next, 0, this.#fronts, 0, 4);
             shader_water_particles_fronts.dispatchIndirect({ encoder, command: command_next, bindings: { next, fronts: this.#fronts } });
         }, {}, { fronts }).fronts;
-        fronts = graph_prefix_scan_csdldf({ graph, data: fronts, element_max_count: capacity });
+        front_sums = graph_prefix_scan_csdldf({ graph, input: fronts, output: front_sums, element_max_count: capacity });
 
         // The frame's hash: how each particle is drawn, how crowded each cell is and so how much of each run its crowd
         // leaves drawn, then each packet drawn into the cells its support overlaps, offsets, entries in order.
         buckets = node('Water / particles bin', (resources, { encoder }) => {
             const draw = this.#draw, runs = this.#runs;
-            shader_water_particles_runs.dispatchIndirect({ encoder, command: command_next, bindings: { next, fronts: this.#fronts, runs } });
-            shader_water_particles_groups.dispatchIndirect({ encoder, command: command_next, bindings: { next, fronts: this.#fronts, runs, draw } });
+            shader_water_particles_runs.dispatchIndirect({ encoder, command: command_next, bindings: { next, fronts: this.#front_sums, runs } });
+            shader_water_particles_groups.dispatchIndirect({ encoder, command: command_next, bindings: { next, fronts: this.#front_sums, runs, draw } });
             shader_water_particles_clear.dispatchIndirect({ encoder, command: command_table, bindings: {
                 buckets: this.#buckets, bucket_amplitude: this.#bucket_amplitude, bucket_weight: this.#bucket_weight,
                 bucket_nest: this.#bucket_nest } });
@@ -259,16 +276,16 @@ export class GPUWaterParticles {
             shader_water_particles_bin.dispatchIndirect({ encoder, command: command_next, bindings: {
                 next, activity, buckets: this.#buckets, slots: this.#slots, bucket_amplitude: this.#bucket_amplitude,
                 body_bounds: this.#body_bounds, draw, runs, visible: this.#visible } });
-        }, { fronts }, { buckets }).buckets;
-        buckets = graph_prefix_scan_csdldf({ graph, data: buckets, element_max_count: table_limit });
+        }, { front_sums }, { buckets }).buckets;
+        offsets = graph_prefix_scan_csdldf({ graph, input: buckets, output: offsets, element_max_count: table_limit });
         node('Water / particles order and bound', (resources, { encoder }) => {
-            const bindings = { next, offsets: this.#buckets, slots: this.#slots, draw: this.#draw };
+            const bindings = { next, offsets: this.#offsets, slots: this.#slots, draw: this.#draw };
             shader_water_particles_scatter.dispatchIndirect({ encoder, command: command_next, bindings: { ...bindings,
                 visible: this.#visible, staging: this.#staging } });
             shader_water_particles_rank.dispatchIndirect({ encoder, command: command_next, bindings: { ...bindings,
                 staging: this.#staging, entries: this.#entries } });
             shader_water_particles_bounds.dispatchIndirect({ encoder, command: command_next, bindings: { next, activity,
-                offsets: this.#buckets, bucket_amplitude: this.#bucket_amplitude, draw: this.#draw, body_bounds: this.#body_bounds } });
-        }, { buckets }, {});
+                offsets: this.#offsets, bucket_amplitude: this.#bucket_amplitude, draw: this.#draw, body_bounds: this.#body_bounds } });
+        }, { offsets }, {});
     }
 }

package/src/shade/wgsl/validate_wgsl_source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate_wgsl_source.d.ts","sourceRoot":"","sources":["../../../../src/shade/wgsl/validate_wgsl_source.js"],"names":[],"mappings":"AAuKA;;;;;;GAMG;AACH,6CAJW,MAAM,UACN,OAAO,iBAAiB,EAAE,UAAU,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CA6M7D"}
+{"version":3,"file":"validate_wgsl_source.d.ts","sourceRoot":"","sources":["../../../../src/shade/wgsl/validate_wgsl_source.js"],"names":[],"mappings":"AAqMA;;;;;;GAMG;AACH,6CAJW,MAAM,UACN,OAAO,iBAAiB,EAAE,UAAU,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAsP7D"}

package/src/shade/wgsl/validate_wgsl_source.js

@@ -12,6 +12,8 @@ import { WGSLLanguageCore } from "./emulator/WGSLLanguageCore.js";
  *  - immutable-assignment: assigning to a `let`/`const` local or a function parameter
  *    (all immutable in WGSL); only `var` is mutable.
  *  - swizzle-store: assigning to a multi-component swizzle (`v.xy = …`), which WGSL forbids.
+ *    A struct may name a member `xy`, and then the store is legal; where one does, only a base
+ *    declared as a vector is flagged.
  *  - foreign-token: HLSL/GLSL constructs that are not WGSL (`float3`, `int2`, `#if`,
  *    `imageAtomicMax`, `lerp(`, `rsqrt(`, …) — unambiguous, lexical.
  *  - reserved-keyword: an identifier that is a WGSL reserved word (`target`, `filter`,
@@ -87,13 +89,16 @@ const WGSL_BUILTIN_NAMES = new Set([
 
 const SWIZZLE_COMPONENTS = /^[xyzwrgba]+$/;
 const LHS_SWIZZLE_TAIL = /\.([xyzwrgba]{2,})\s*$/;
+const VECTOR_TYPE_NAME = /^vec[234][fhiu]?$/;
 
-// Unambiguous non-WGSL tokens. Each entry is a regex and a human label.
+// Unambiguous non-WGSL tokens. Each entry is a regex and a human label. The bare scalar names
+// (`float`, `int`, `half`, `fixed`) are neither keywords nor reserved words in WGSL, so they are
+// legal identifiers (`let half = n / 2u;`) and only their vector forms are matched.
 const FOREIGN_TOKENS = [
     [/\bfloat[1-4]x[1-4]\b/, 'HLSL matrix type (use matNxM<f32>)'],
     [/\bfloat[2-4]\b/, 'HLSL vector type (use vecN<f32>)'],
     [/\b(?:int|uint)[2-4]\b/, 'HLSL integer vector type (use vecN<i32|u32>)'],
-    [/\b(?:half|fixed)[2-4]?\b/, 'HLSL scalar/vector type'],
+    [/\b(?:half|fixed)[2-4]\b/, 'HLSL vector type (use vecN<f16>)'],
     [/#\s*(?:if|ifdef|ifndef|endif|else|elif|define|pragma)\b/, 'C-preprocessor directive'],
     [/\bimageAtomic(?:Max|Min|Add|And|Or|Xor|Exchange)\b/, 'GLSL image atomic (use atomic* on a storage binding)'],
     [/\bimageStore\b/, 'GLSL imageStore (use textureStore)'],
@@ -153,6 +158,31 @@ function firstIdentToken(node) {
     return null;
 }
 
+/**
+ * Whether a `type_specifier` or `call_phrase` names a vector type (`vec3<f32>`, `vec4f`, …).
+ * @param {Node} node
+ */
+function namesVector(node) {
+    const ident = node.namedChildren.find(c => c.type === 'template_elaborated_ident')
+        ?.namedChildren.find(c => c.type === 'ident');
+    return ident !== undefined && VECTOR_TYPE_NAME.test(ident.text.trim());
+}
+
+/**
+ * Whether a declaration can be seen to be a vector without inferring types: its type annotation
+ * names one, or, unannotated, its whole initializer is a vector constructor (`vec3<f32>(0.0)`).
+ * @param {Node|undefined} type_specifier
+ * @param {Node|undefined} initializer
+ */
+function declaresVector(type_specifier, initializer) {
+    if (type_specifier !== undefined) return namesVector(type_specifier);
+    if (initializer === undefined) return false;
+
+    let node = initializer;
+    while (node.namedChildren.length === 1) node = node.namedChildren[0];
+    return node.type === 'call_phrase' && namesVector(node);
+}
+
 /**
  * Strip line comments and block comments and string-free WGSL has no strings, so a coarse
  * comment strip is enough to keep the lexical foreign-token scan from firing inside a
@@ -181,6 +211,8 @@ export function validate_wgsl_source(source, parser) {
     // ── collect the symbol table (user functions + structs) ──
     const declared_functions = new Set();
     const declared_structs = new Set();
+    /** Every struct member name; one shaped like a swizzle makes `x.xy = …` legal on that struct. */
+    const declared_members = new Set();
 
     for (const fn of descendantsOfType(root, 'function_decl')) {
         const header = fn.namedChildren.find(c => c.type === 'function_header');
@@ -191,6 +223,11 @@ export function validate_wgsl_source(source, parser) {
     for (const s of descendantsOfType(root, 'struct_decl')) {
         const ident = s.namedChildren.find(c => c.type === 'ident');
         if (ident !== undefined) declared_structs.add(ident.text.trim());
+
+        for (const member of descendantsOfType(s, 'struct_member')) {
+            const name = member.namedChildren.find(c => c.type === 'member_ident');
+            if (name !== undefined) declared_members.add(name.text.trim());
+        }
     }
 
     const core_builtins = new Set(Object.keys(WGSLLanguageCore));
@@ -209,6 +246,21 @@ export function validate_wgsl_source(source, parser) {
         /** Everything a const-expression may NOT read: parameters, `var`, `let`. @type {Set<string>} */
         const runtime = new Set();
 
+        // Scopes are flat here, so a name is a vector only if every declaration of it says so.
+        /** Names every declaration of which is seen to be a vector. @type {Set<string>} */
+        const vectors = new Set();
+        /** Names declared at least once as anything else. @type {Set<string>} */
+        const not_vectors = new Set();
+
+        const declare_vector = (name, is_vector) => {
+            if (is_vector && !not_vectors.has(name)) {
+                vectors.add(name);
+            } else {
+                vectors.delete(name);
+                not_vectors.add(name);
+            }
+        };
+
         // Value parameters are immutable; POINTER parameters are not — writing through a
         // pointer (`*p = …`, `p.x = …`, `memory[i] = …`) is the legal, common case in this
         // codebase, so excluding them is what keeps this rule free of false positives.
@@ -223,6 +275,7 @@ export function validate_wgsl_source(source, parser) {
                     if (!is_pointer) immutable.add(id.text.trim());
 
                     runtime.add(id.text.trim());
+                    declare_vector(id.text.trim(), declaresVector(type, undefined));
                 }
             }
         }
@@ -237,6 +290,11 @@ export function validate_wgsl_source(source, parser) {
             const name = opt !== undefined && opt !== null ? firstIdentToken(opt) : null;
             if (name === null) continue;
 
+            declare_vector(name, declaresVector(
+                opt.namedChildren.find(c => c.type === 'type_specifier'),
+                decl.namedChildren.find(c => c.type === 'expression'),
+            ));
+
             if (is_var) {
                 mutable.add(name);
                 immutable.delete(name);
@@ -269,8 +327,21 @@ export function validate_wgsl_source(source, parser) {
             if (lhs === undefined) return;
 
             // swizzle-store
+            //
+            // `.xy` is an l-value only as a struct member, so with no struct declaring one the
+            // store is illegal whatever the base is. With one, the base has to be seen to be a
+            // vector: a parameter or local declared as one and stored to directly (`v.xy`).
             const tail = lhs.text.match(LHS_SWIZZLE_TAIL);
-            if (tail !== null && SWIZZLE_COMPONENTS.test(tail[1])) {
+            const core = lhs.namedChildren.find(c => c.type === 'core_lhs_expression');
+            const access = lhs.namedChildren.find(c => c.type === 'component_or_swizzle_specifier');
+            const base = core?.namedChildren.find(c => c.type === 'ident');
+            const on_vector = base !== undefined
+                && access !== undefined
+                && access.namedChildren.length === 1
+                && access.namedChildren[0].type === 'member_ident'
+                && vectors.has(base.text.trim());
+
+            if (tail !== null && SWIZZLE_COMPONENTS.test(tail[1]) && (!declared_members.has(tail[1]) || on_vector)) {
                 diagnostics.push({
                     rule: 'swizzle-store',
                     message: `assignment to multi-component swizzle '.${tail[1]}' is not an l-value in WGSL`,

package/src/engine/graphics3/register_instance_animation.d.ts

@@ -1,114 +0,0 @@
-/**
- * Hand one entity's instance to the GPU: its skins become deformations.
- *
- * **Registration is eventually consistent by design**, which is what makes this callable the moment
- * an instance exists rather than at some later moment when the scene is known to be built. An id is
- * allocated and returned synchronously, while the skin's meshes are bound to it only once every
- * joint has a row in the scene. Until then the skin is inert rather than wrong: its meshes draw
- * undeformed.
- *
- * The instance's entities therefore do **not** have to hold their rows yet.
- *
- * @param {GPUSceneContext} context the scene's GPU state, which owns the manager and is what the
- * registration is stamped with so it can be given back to the right one
- * @param {PrefabInstance} instance its skins name joint and mesh entities
- * @returns {InstanceAnimationRegistration}
- */
-export function register_instance_animation(context: GPUSceneContext, instance: PrefabInstance): InstanceAnimationRegistration;
-/**
- * Give back everything {@link register_instance_animation} took out, for a manager that is still
- * the one that issued it.
- *
- * **A destroyed manager must not be handed its own ids back.** A renderer restart takes the GPU
- * scene context with it, and the ids it issued mean nothing to the context that replaces it — so
- * the caller forgets them rather than returning them. This is only for the ordinary case: an entity
- * that leaves while the renderer it registered with is still running, and the registration's own
- * {@link InstanceAnimationRegistration#context} is how a caller tells the two apart.
- *
- * @param {InstanceAnimationRegistration} registration
- */
-export function unregister_instance_animation(registration: InstanceAnimationRegistration): void;
-/**
- * Make some of an instance's clips playable — the ones a driver actually plays, and no others.
- *
- * **Registering a clip is not free of consequence, which is why this takes a set.** The pose
- * accumulator marks a joint dirty for every bound clip that writes to it, whatever its weight, so a
- * bound clip at weight zero resolves the joints only it drives to zero rather than leaving them at
- * rest. A driver therefore registers what it can play and re-registers when that changes; a clip no
- * driver claims is never bound and so moves nothing.
- *
- * Each index is registered once however many times it is named. Two states of one graph can play
- * the same clip of the model, and two registrations of one clip are two rows the accumulator would
- * add together.
- *
- * @param {GPUSceneContext} context
- * @param {PrefabInstance} instance its clips target entities
- * @param {ArrayLike<number>} slots indices into `instance.clips`; duplicates are ignored
- * @returns {InstanceClipRegistration}
- */
-export function register_instance_clips(context: GPUSceneContext, instance: PrefabInstance, slots: ArrayLike<number>): InstanceClipRegistration;
-/**
- * Give back everything {@link register_instance_clips} took out, for a manager that is still the one
- * that issued it — see {@link unregister_instance_animation} for why that qualification matters.
- *
- * @param {InstanceClipRegistration} registration
- */
-export function unregister_instance_clips(registration: InstanceClipRegistration): void;
-/**
- * What the animation manager handed back for one {@link PrefabInstance}'s **skins**.
- *
- * Positional: `skins[i]` is the id of the instance's `skins[i]`.
- *
- * **Clips are not here, and that is D37.** A skin belongs to the model — it is how the mesh
- * deforms, and every placement of the model needs it whatever is playing — so the system that
- * places the model registers it. A clip belongs to whatever plays it, and a clip nothing plays must
- * not be registered at all: the pose accumulator marks a joint dirty for any *bound* clip, weight
- * and all, so a joint driven only by clips at weight zero resolves to zero rather than to its rest
- * pose. A model carrying clips and no animation component used to render the sum of every one of
- * them. See {@link register_instance_clips}.
- */
-export class InstanceAnimationRegistration {
-    /**
-     * The GPU scene context these ids were issued by.
-     *
-     * Carried rather than inferred, because **an id may only be handed back to the manager that
-     * issued it** and there is no other way to be sure. A renderer restart builds a new context, and
-     * a holder comparing this against what `scene_context` answers now knows in one `===` whether
-     * giving the ids back is returning them or corrupting a stranger's table — without depending on
-     * when anything last ran.
-     *
-     * @type {GPUSceneContext}
-     */
-    context: GPUSceneContext;
-    /**
-     * @type {number[]}
-     */
-    skins: number[];
-}
-/**
- * The id a clip has when nobody registered it.
- * @type {number}
- */
-export const CLIP_NOT_REGISTERED: number;
-/**
- * Which of an instance's clips a driver has playable, by the instance's own clip index.
- *
- * `ids[i]` is the manager's id for `instance.clips[i]`, or {@link CLIP_NOT_REGISTERED} where this
- * driver does not play that clip. Indexed by the instance rather than packed, because that is how
- * both drivers already address a clip — the graph resolves a name to a model slot, the clip list
- * does the same — and a packed array would want a second table to say what each entry was.
- */
-export class InstanceClipRegistration {
-    /**
-     * The GPU scene context these ids were issued by. See
-     * {@link InstanceAnimationRegistration#context} — same reasoning, same `===` check.
-     *
-     * @type {GPUSceneContext|null}
-     */
-    context: GPUSceneContext | null;
-    /**
-     * @type {Int32Array}
-     */
-    ids: Int32Array;
-}
-//# sourceMappingURL=register_instance_animation.d.ts.map

package/src/engine/graphics3/register_instance_animation.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"register_instance_animation.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/register_instance_animation.js"],"names":[],"mappings":"AAmCA;;;;;;;;;;;;;;;GAeG;AACH,iGAFa,6BAA6B,CAmBzC;AAED;;;;;;;;;;;GAWG;AACH,4DAFW,6BAA6B,QAevC;AA+BD;;;;;;;;;;;;;;;;;GAiBG;AACH,mGAHW,UAAU,MAAM,CAAC,GACf,wBAAwB,CA+BpC;AAED;;;;;GAKG;AACH,wDAFW,wBAAwB,QAqBlC;AAtMD;;;;;;;;;;;;GAYG;AACH;IACI;;;;;;;;;;OAUG;IACH,yBAAe;IAEf;;OAEG;IACH,OAFU,MAAM,EAAE,CAEP;CACd;AAgED;;;GAGG;AACH,kCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH;IACI;;;;;OAKG;IACH,SAFU,kBAAgB,IAAI,CAEf;IAEf;;OAEG;IACH,KAFU,UAAU,CAEI;CAC3B"}

package/src/engine/graphics3/register_instance_animation.js

@@ -1,201 +0,0 @@
-import { assert } from "../../core/assert.js";
-
-/**
- * What the animation manager handed back for one {@link PrefabInstance}'s **skins**.
- *
- * Positional: `skins[i]` is the id of the instance's `skins[i]`.
- *
- * **Clips are not here, and that is D37.** A skin belongs to the model — it is how the mesh
- * deforms, and every placement of the model needs it whatever is playing — so the system that
- * places the model registers it. A clip belongs to whatever plays it, and a clip nothing plays must
- * not be registered at all: the pose accumulator marks a joint dirty for any *bound* clip, weight
- * and all, so a joint driven only by clips at weight zero resolves to zero rather than to its rest
- * pose. A model carrying clips and no animation component used to render the sum of every one of
- * them. See {@link register_instance_clips}.
- */
-export class InstanceAnimationRegistration {
-    /**
-     * The GPU scene context these ids were issued by.
-     *
-     * Carried rather than inferred, because **an id may only be handed back to the manager that
-     * issued it** and there is no other way to be sure. A renderer restart builds a new context, and
-     * a holder comparing this against what `scene_context` answers now knows in one `===` whether
-     * giving the ids back is returning them or corrupting a stranger's table — without depending on
-     * when anything last ran.
-     *
-     * @type {GPUSceneContext}
-     */
-    context = null;
-
-    /**
-     * @type {number[]}
-     */
-    skins = [];
-}
-
-/**
- * Hand one entity's instance to the GPU: its skins become deformations.
- *
- * **Registration is eventually consistent by design**, which is what makes this callable the moment
- * an instance exists rather than at some later moment when the scene is known to be built. An id is
- * allocated and returned synchronously, while the skin's meshes are bound to it only once every
- * joint has a row in the scene. Until then the skin is inert rather than wrong: its meshes draw
- * undeformed.
- *
- * The instance's entities therefore do **not** have to hold their rows yet.
- *
- * @param {GPUSceneContext} context the scene's GPU state, which owns the manager and is what the
- * registration is stamped with so it can be given back to the right one
- * @param {PrefabInstance} instance its skins name joint and mesh entities
- * @returns {InstanceAnimationRegistration}
- */
-export function register_instance_animation(context, instance) {
-    assert.defined(context, 'context');
-    assert.defined(instance, 'instance');
-
-    const manager = context.animation_manager;
-
-    const r = new InstanceAnimationRegistration();
-
-    r.context = context;
-
-    const skins = instance.skins;
-
-    for (let i = 0; i < skins.length; i++) {
-        r.skins.push(manager.register_skin(skins[i]));
-    }
-
-    return r;
-}
-
-/**
- * Give back everything {@link register_instance_animation} took out, for a manager that is still
- * the one that issued it.
- *
- * **A destroyed manager must not be handed its own ids back.** A renderer restart takes the GPU
- * scene context with it, and the ids it issued mean nothing to the context that replaces it — so
- * the caller forgets them rather than returning them. This is only for the ordinary case: an entity
- * that leaves while the renderer it registered with is still running, and the registration's own
- * {@link InstanceAnimationRegistration#context} is how a caller tells the two apart.
- *
- * @param {InstanceAnimationRegistration} registration
- */
-export function unregister_instance_animation(registration) {
-    assert.defined(registration, 'registration');
-    assert.defined(registration.context, 'registration.context');
-
-    const manager = registration.context.animation_manager;
-
-    const skins = registration.skins;
-
-    for (let i = 0; i < skins.length; i++) {
-        manager.unregister_skin(skins[i]);
-    }
-
-    skins.length = 0;
-}
-
-/**
- * The id a clip has when nobody registered it.
- * @type {number}
- */
-export const CLIP_NOT_REGISTERED = -1;
-
-/**
- * Which of an instance's clips a driver has playable, by the instance's own clip index.
- *
- * `ids[i]` is the manager's id for `instance.clips[i]`, or {@link CLIP_NOT_REGISTERED} where this
- * driver does not play that clip. Indexed by the instance rather than packed, because that is how
- * both drivers already address a clip — the graph resolves a name to a model slot, the clip list
- * does the same — and a packed array would want a second table to say what each entry was.
- */
-export class InstanceClipRegistration {
-    /**
-     * The GPU scene context these ids were issued by. See
-     * {@link InstanceAnimationRegistration#context} — same reasoning, same `===` check.
-     *
-     * @type {GPUSceneContext|null}
-     */
-    context = null;
-
-    /**
-     * @type {Int32Array}
-     */
-    ids = new Int32Array(0);
-}
-
-/**
- * Make some of an instance's clips playable — the ones a driver actually plays, and no others.
- *
- * **Registering a clip is not free of consequence, which is why this takes a set.** The pose
- * accumulator marks a joint dirty for every bound clip that writes to it, whatever its weight, so a
- * bound clip at weight zero resolves the joints only it drives to zero rather than leaving them at
- * rest. A driver therefore registers what it can play and re-registers when that changes; a clip no
- * driver claims is never bound and so moves nothing.
- *
- * Each index is registered once however many times it is named. Two states of one graph can play
- * the same clip of the model, and two registrations of one clip are two rows the accumulator would
- * add together.
- *
- * @param {GPUSceneContext} context
- * @param {PrefabInstance} instance its clips target entities
- * @param {ArrayLike<number>} slots indices into `instance.clips`; duplicates are ignored
- * @returns {InstanceClipRegistration}
- */
-export function register_instance_clips(context, instance, slots) {
-    assert.defined(context, 'context');
-    assert.defined(instance, 'instance');
-    assert.defined(slots, 'slots');
-
-    const manager = context.animation_manager;
-
-    const clips = instance.clips;
-
-    const r = new InstanceClipRegistration();
-
-    r.context = context;
-    r.ids = new Int32Array(clips.length).fill(CLIP_NOT_REGISTERED);
-
-    for (let i = 0; i < slots.length; i++) {
-        const slot = slots[i];
-
-        assert.isNonNegativeInteger(slot, 'slot');
-        assert.lessThan(slot, clips.length, 'slot');
-
-        if (r.ids[slot] !== CLIP_NOT_REGISTERED) {
-            // named twice by one driver, which is one clip either way
-            continue;
-        }
-
-        r.ids[slot] = manager.register_clip(clips[slot]);
-    }
-
-    return r;
-}
-
-/**
- * Give back everything {@link register_instance_clips} took out, for a manager that is still the one
- * that issued it — see {@link unregister_instance_animation} for why that qualification matters.
- *
- * @param {InstanceClipRegistration} registration
- */
-export function unregister_instance_clips(registration) {
-    assert.defined(registration, 'registration');
-    assert.defined(registration.context, 'registration.context');
-
-    const manager = registration.context.animation_manager;
-
-    const ids = registration.ids;
-
-    for (let i = 0; i < ids.length; i++) {
-        const id = ids[i];
-
-        if (id === CLIP_NOT_REGISTERED) {
-            continue;
-        }
-
-        manager.unregister_clip(id);
-    }
-
-    ids.fill(CLIP_NOT_REGISTERED);
-}