@woosh/meep-engine 3.43.0 → 3.44.0

package/src/engine/graphics3/prefab/prefab_place.d.ts

@@ -3,30 +3,37 @@
  * @typedef {import("./PrefabInstance.js").PrefabInstance} PrefabInstance
  * @typedef {import("../../ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
  * @typedef {import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
- * @typedef {import("../register_instance_animation.js").InstanceAnimationRegistration} InstanceAnimationRegistration
+ */
+/**
+ * One skinned primitive's registration: the mesh entity, and the skin id the animation manager
+ * issued for its `MeshSkin`.
+ *
+ * @typedef {{entity: number, skin_id: number}} PlacedSkin
  */
 /**
  * Put a model into a scene that has no systems: a playground, a preview, a tool.
  *
- * A game does this in two systems — `MeshSystem` spawns the prefab under the entity that wears
- * it, and `ShadedGeometrySystem` takes a mesh row for every primitive as its component appears.
- * A scene bound to a bare dataset has neither, so this does the same by hand, in one call: a root
- * entity carrying `placement`, the prefab spawned under it, a `transforms` row acquired for every
- * entity of the instance, a `meshes` row attached for every primitive (over a clone of its geometry
- * where the primitive is skinned), and the instance's skins and clips registered with the
- * animation manager — unless told otherwise.
+ * A game does this in three systems — `MeshSystem` spawns the prefab under the entity that wears
+ * it, `ShadedGeometrySystem` takes a mesh row for every primitive as its component appears, and
+ * `MeshSkinSystem` registers every `MeshSkin` and binds its mesh. A scene bound to a bare dataset
+ * has none of them, so this does the same by hand, in one call: a root entity carrying
+ * `placement`, the prefab spawned under it, a `transforms` row acquired for every entity of the
+ * instance, a `meshes` row attached for every primitive (over a clone of its geometry where the
+ * primitive is skinned), and each skinned primitive's skin registered with the animation manager —
+ * unless told otherwise. The rows are not marked when anything moves; a playground that moves a
+ * placed model marks what it moved.
  *
  * @param {GPUSceneContext} scene_context the scene's context — its rows are where the instance goes
  * @param {EntityComponentDataset} dataset the dataset the scene is bound to
  * @param {Prefab} prefab the model, compiled once
  * @param {Transform64} placement where the model's root goes; copied
  * @param {object} [options]
- * @param {boolean} [options.register_animation] whether the instance's skins and clips are
- *        registered; off leaves a skinned primitive's clone undeformed
+ * @param {boolean} [options.register_animation] whether the instance's skins are registered;
+ *        off leaves a skinned primitive's clone undeformed
  * @param {boolean} [options.skinned] whether skinned primitives take a row at all; a preview that
  *        registers no skin has nothing to pose them with and leaves them out
- * @returns {{root: number, instance: PrefabInstance, animation: InstanceAnimationRegistration|null, drawn: number}}
- *          `drawn` is how many primitives took a row
+ * @returns {{root: number, instance: PrefabInstance, skins: PlacedSkin[]|null, drawn: number}}
+ *          `skins` is null when nothing was registered; `drawn` is how many primitives took a row
  */
 export function prefab_place(scene_context: GPUSceneContext, dataset: EntityComponentDataset, prefab: Prefab, placement: Transform64, { register_animation, skinned }?: {
     register_animation?: boolean;
@@ -34,27 +41,34 @@ export function prefab_place(scene_context: GPUSceneContext, dataset: EntityComp
 }): {
     root: number;
     instance: PrefabInstance;
-    animation: InstanceAnimationRegistration | null;
+    skins: PlacedSkin[] | null;
     drawn: number;
 };
 /**
- * Take a placed model out again: its rows given back, its animation unregistered, its entities
+ * Take a placed model out again: its rows given back, its skins unregistered, its entities
  * removed — the root included, since {@link prefab_place} made it.
  *
  * @param {GPUSceneContext} scene_context
  * @param {EntityComponentDataset} dataset
- * @param {{root: number, instance: PrefabInstance, animation: InstanceAnimationRegistration|null}} placed
+ * @param {{root: number, instance: PrefabInstance, skins: PlacedSkin[]|null}} placed
  *        what {@link prefab_place} answered
  */
 export function prefab_unplace(scene_context: GPUSceneContext, dataset: EntityComponentDataset, placed: {
     root: number;
     instance: PrefabInstance;
-    animation: InstanceAnimationRegistration | null;
+    skins: PlacedSkin[] | null;
 }): void;
 export type Prefab = import("./Prefab.js").Prefab;
 export type PrefabInstance = import("./PrefabInstance.js").PrefabInstance;
 export type EntityComponentDataset = import("../../ecs/EntityComponentDataset.js").EntityComponentDataset;
 export type GPUSceneContext = import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext;
-export type InstanceAnimationRegistration = import("../register_instance_animation.js").InstanceAnimationRegistration;
+/**
+ * One skinned primitive's registration: the mesh entity, and the skin id the animation manager
+ * issued for its `MeshSkin`.
+ */
+export type PlacedSkin = {
+    entity: number;
+    skin_id: number;
+};
 import { Transform64 } from "../../ecs/transform/Transform64.js";
 //# sourceMappingURL=prefab_place.d.ts.map

package/src/engine/graphics3/prefab/prefab_place.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prefab_place.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/prefab/prefab_place.js"],"names":[],"mappings":"AAOA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4CAZW,eAAe,WACf,sBAAsB,UACtB,MAAM,aACN,WAAW;IAEO,kBAAkB,GAApC,OAAO;IAEW,OAAO,GAAzB,OAAO;IAEL;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,6BAA6B,GAAC,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAyDlH;AAED;;;;;;;;GAQG;AACH,8CALW,eAAe,WACf,sBAAsB,UACtB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,6BAA6B,GAAC,IAAI,CAAA;CAAC,QA6BjG;qBAzHY,OAAO,aAAa,EAAE,MAAM;6BAC5B,OAAO,qBAAqB,EAAE,cAAc;qCAC5C,OAAO,qCAAqC,EAAE,sBAAsB;8BACpE,OAAO,kDAAkD,EAAE,eAAe;4CAC1E,OAAO,mCAAmC,EAAE,6BAA6B;4BAX1D,oCAAoC"}
+{"version":3,"file":"prefab_place.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/prefab/prefab_place.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,4CAZW,eAAe,WACf,sBAAsB,UACtB,MAAM,aACN,WAAW;IAEO,kBAAkB,GAApC,OAAO;IAEW,OAAO,GAAzB,OAAO;IAEL;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,GAAC,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAyD7F;AAkCD;;;;;;;;GAQG;AACH,8CALW,eAAe,WACf,sBAAsB,UACtB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,GAAC,IAAI,CAAA;CAAC,QAkC5E;qBAtKY,OAAO,aAAa,EAAE,MAAM;6BAC5B,OAAO,qBAAqB,EAAE,cAAc;qCAC5C,OAAO,qCAAqC,EAAE,sBAAsB;8BACpE,OAAO,kDAAkD,EAAE,eAAe;;;;;yBAO1E;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC;4BAjBlB,oCAAoC"}

package/src/engine/graphics3/prefab/prefab_place.js

@@ -1,130 +1,175 @@
-import { assert } from "../../../core/assert.js";
-import { Transform64 } from "../../ecs/transform/Transform64.js";
-import { ShadedGeometry } from "../../graphics/ecs/mesh-v2/ShadedGeometry.js";
-import { ShadedGeometryFlags } from "../../graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
-import { register_instance_animation, unregister_instance_animation } from "../register_instance_animation.js";
-import { prefab_instance_destroy, prefab_instantiate } from "./prefab_instantiate.js";
-
-/**
- * @typedef {import("./Prefab.js").Prefab} Prefab
- * @typedef {import("./PrefabInstance.js").PrefabInstance} PrefabInstance
- * @typedef {import("../../ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
- * @typedef {import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
- * @typedef {import("../register_instance_animation.js").InstanceAnimationRegistration} InstanceAnimationRegistration
- */
-
-/**
- * Put a model into a scene that has no systems: a playground, a preview, a tool.
- *
- * A game does this in two systems — `MeshSystem` spawns the prefab under the entity that wears
- * it, and `ShadedGeometrySystem` takes a mesh row for every primitive as its component appears.
- * A scene bound to a bare dataset has neither, so this does the same by hand, in one call: a root
- * entity carrying `placement`, the prefab spawned under it, a `transforms` row acquired for every
- * entity of the instance, a `meshes` row attached for every primitive (over a clone of its geometry
- * where the primitive is skinned), and the instance's skins and clips registered with the
- * animation manager — unless told otherwise.
- *
- * @param {GPUSceneContext} scene_context the scene's context — its rows are where the instance goes
- * @param {EntityComponentDataset} dataset the dataset the scene is bound to
- * @param {Prefab} prefab the model, compiled once
- * @param {Transform64} placement where the model's root goes; copied
- * @param {object} [options]
- * @param {boolean} [options.register_animation] whether the instance's skins and clips are
- *        registered; off leaves a skinned primitive's clone undeformed
- * @param {boolean} [options.skinned] whether skinned primitives take a row at all; a preview that
- *        registers no skin has nothing to pose them with and leaves them out
- * @returns {{root: number, instance: PrefabInstance, animation: InstanceAnimationRegistration|null, drawn: number}}
- *          `drawn` is how many primitives took a row
- */
-export function prefab_place(scene_context, dataset, prefab, placement, { register_animation = true, skinned = true } = {}) {
-    assert.defined(scene_context, 'scene_context');
-    assert.defined(dataset, 'dataset');
-    assert.equal(dataset.isEntityComponentDataset, true, 'dataset.isEntityComponentDataset !== true');
-    assert.defined(prefab, 'prefab');
-    assert.equal(prefab.isPrefab, true, 'prefab.isPrefab !== true');
-    assert.defined(placement, 'placement');
-    assert.isBoolean(register_animation, 'register_animation');
-    assert.isBoolean(skinned, 'skinned');
-
-    // a fresh dataset knows no component types; the prefab registers its own, and the root is
-    // placed before the prefab is spawned
-    dataset.registerManyComponentTypes([Transform64]);
-
-    const root = dataset.createEntity();
-    const transform = new Transform64();
-
-    transform.copy(placement);
-    transform.updateMatrix();
-
-    dataset.addComponentToEntity(root, transform);
-
-    const instance = prefab_instantiate(prefab, dataset, root);
-
-    const rows = scene_context.rows;
-    const entities = instance.entities;
-
-    for (let i = 0; i < entities.length; i++) {
-        rows.acquire(entities[i]);
-    }
-
-    const mesh_entities = instance.mesh_entities;
-
-    let drawn = 0;
-
-    for (let i = 0; i < mesh_entities.length; i++) {
-        const entity = mesh_entities[i];
-        const geometry = dataset.getComponent(entity, ShadedGeometry);
-        const is_skinned = geometry.getFlag(ShadedGeometryFlags.Skinned);
-
-        if (is_skinned && !skinned) {
-            continue;
-        }
-
-        rows.attach_mesh(entity, geometry.geometry, geometry.material, is_skinned);
-
-        drawn++;
-    }
-
-    const animation = register_animation
-        ? register_instance_animation(scene_context, instance)
-        : null;
-
-    return { root, instance, animation, drawn };
-}
-
-/**
- * Take a placed model out again: its rows given back, its animation unregistered, its entities
- * removed — the root included, since {@link prefab_place} made it.
- *
- * @param {GPUSceneContext} scene_context
- * @param {EntityComponentDataset} dataset
- * @param {{root: number, instance: PrefabInstance, animation: InstanceAnimationRegistration|null}} placed
- *        what {@link prefab_place} answered
- */
-export function prefab_unplace(scene_context, dataset, placed) {
-    assert.defined(scene_context, 'scene_context');
-    assert.defined(dataset, 'dataset');
-    assert.defined(placed, 'placed');
-
-    if (placed.animation !== null) {
-        unregister_instance_animation(placed.animation);
-    }
-
-    const rows = scene_context.rows;
-    const instance = placed.instance;
-    const mesh_entities = instance.mesh_entities;
-
-    for (let i = 0; i < mesh_entities.length; i++) {
-        // safe on a skinned primitive that took no row
-        rows.detach_mesh(mesh_entities[i]);
-    }
-
-    const entities = instance.entities;
-
-    for (let i = 0; i < entities.length; i++) {
-        rows.release(entities[i]);
-    }
-
-    prefab_instance_destroy(dataset, instance);
-    dataset.removeEntity(placed.root);
-}
+import { assert } from "../../../core/assert.js";
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+import { ShadedGeometry } from "../../graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../../graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
+import { MeshSkin } from "../../graphics/ecs/mesh-v2/MeshSkin.js";
+import { prefab_instance_destroy, prefab_instantiate } from "./prefab_instantiate.js";
+
+/**
+ * @typedef {import("./Prefab.js").Prefab} Prefab
+ * @typedef {import("./PrefabInstance.js").PrefabInstance} PrefabInstance
+ * @typedef {import("../../ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ * @typedef {import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ */
+
+/**
+ * One skinned primitive's registration: the mesh entity, and the skin id the animation manager
+ * issued for its `MeshSkin`.
+ *
+ * @typedef {{entity: number, skin_id: number}} PlacedSkin
+ */
+
+/**
+ * Put a model into a scene that has no systems: a playground, a preview, a tool.
+ *
+ * A game does this in three systems — `MeshSystem` spawns the prefab under the entity that wears
+ * it, `ShadedGeometrySystem` takes a mesh row for every primitive as its component appears, and
+ * `MeshSkinSystem` registers every `MeshSkin` and binds its mesh. A scene bound to a bare dataset
+ * has none of them, so this does the same by hand, in one call: a root entity carrying
+ * `placement`, the prefab spawned under it, a `transforms` row acquired for every entity of the
+ * instance, a `meshes` row attached for every primitive (over a clone of its geometry where the
+ * primitive is skinned), and each skinned primitive's skin registered with the animation manager —
+ * unless told otherwise. The rows are not marked when anything moves; a playground that moves a
+ * placed model marks what it moved.
+ *
+ * @param {GPUSceneContext} scene_context the scene's context — its rows are where the instance goes
+ * @param {EntityComponentDataset} dataset the dataset the scene is bound to
+ * @param {Prefab} prefab the model, compiled once
+ * @param {Transform64} placement where the model's root goes; copied
+ * @param {object} [options]
+ * @param {boolean} [options.register_animation] whether the instance's skins are registered;
+ *        off leaves a skinned primitive's clone undeformed
+ * @param {boolean} [options.skinned] whether skinned primitives take a row at all; a preview that
+ *        registers no skin has nothing to pose them with and leaves them out
+ * @returns {{root: number, instance: PrefabInstance, skins: PlacedSkin[]|null, drawn: number}}
+ *          `skins` is null when nothing was registered; `drawn` is how many primitives took a row
+ */
+export function prefab_place(scene_context, dataset, prefab, placement, { register_animation = true, skinned = true } = {}) {
+    assert.defined(scene_context, 'scene_context');
+    assert.defined(dataset, 'dataset');
+    assert.equal(dataset.isEntityComponentDataset, true, 'dataset.isEntityComponentDataset !== true');
+    assert.defined(prefab, 'prefab');
+    assert.equal(prefab.isPrefab, true, 'prefab.isPrefab !== true');
+    assert.defined(placement, 'placement');
+    assert.isBoolean(register_animation, 'register_animation');
+    assert.isBoolean(skinned, 'skinned');
+
+    // a fresh dataset knows no component types; the prefab registers its own, and the root is
+    // placed before the prefab is spawned
+    dataset.registerManyComponentTypes([Transform64]);
+
+    const root = dataset.createEntity();
+    const transform = new Transform64();
+
+    transform.copy(placement);
+    transform.updateMatrix();
+
+    dataset.addComponentToEntity(root, transform);
+
+    const instance = prefab_instantiate(prefab, dataset, root);
+
+    const rows = scene_context.rows;
+    const entities = instance.entities;
+
+    for (let i = 0; i < entities.length; i++) {
+        rows.acquire(entities[i]);
+    }
+
+    const mesh_entities = instance.mesh_entities;
+
+    let drawn = 0;
+
+    for (let i = 0; i < mesh_entities.length; i++) {
+        const entity = mesh_entities[i];
+        const geometry = dataset.getComponent(entity, ShadedGeometry);
+        const is_skinned = geometry.getFlag(ShadedGeometryFlags.Skinned);
+
+        if (is_skinned && !skinned) {
+            continue;
+        }
+
+        rows.attach_mesh(entity, geometry.geometry, geometry.material, is_skinned);
+
+        drawn++;
+    }
+
+    const skins = register_animation
+        ? register_skins(scene_context, dataset, mesh_entities)
+        : null;
+
+    return { root, instance, skins, drawn };
+}
+
+/**
+ * Register the skin of every primitive that carries one, and bind the primitive to it — what
+ * `MeshSkinSystem` does for a game. Meshes of one skeleton bound the same way share a skin.
+ *
+ * @param {GPUSceneContext} scene_context
+ * @param {EntityComponentDataset} dataset
+ * @param {Int32Array} mesh_entities
+ * @returns {PlacedSkin[]}
+ */
+function register_skins(scene_context, dataset, mesh_entities) {
+    const manager = scene_context.animation_manager;
+
+    const skins = [];
+
+    for (let i = 0; i < mesh_entities.length; i++) {
+        const entity = mesh_entities[i];
+        const skin = dataset.getComponent(entity, MeshSkin);
+
+        if (skin === undefined) {
+            continue;
+        }
+
+        const skin_id = manager.register_skin(skin.joints, skin.inverse_bind_matrices);
+
+        manager.bind_skin_mesh(entity, skin_id);
+
+        skins.push({ entity, skin_id });
+    }
+
+    return skins;
+}
+
+/**
+ * Take a placed model out again: its rows given back, its skins unregistered, its entities
+ * removed — the root included, since {@link prefab_place} made it.
+ *
+ * @param {GPUSceneContext} scene_context
+ * @param {EntityComponentDataset} dataset
+ * @param {{root: number, instance: PrefabInstance, skins: PlacedSkin[]|null}} placed
+ *        what {@link prefab_place} answered
+ */
+export function prefab_unplace(scene_context, dataset, placed) {
+    assert.defined(scene_context, 'scene_context');
+    assert.defined(dataset, 'dataset');
+    assert.defined(placed, 'placed');
+
+    if (placed.skins !== null) {
+        const manager = scene_context.animation_manager;
+
+        for (const { entity, skin_id } of placed.skins) {
+            manager.unbind_skin_mesh(entity);
+            manager.unregister_skin(skin_id);
+        }
+    }
+
+    const rows = scene_context.rows;
+    const instance = placed.instance;
+    const mesh_entities = instance.mesh_entities;
+
+    for (let i = 0; i < mesh_entities.length; i++) {
+        // safe on a skinned primitive that took no row
+        rows.detach_mesh(mesh_entities[i]);
+    }
+
+    const entities = instance.entities;
+
+    for (let i = 0; i < entities.length; i++) {
+        rows.release(entities[i]);
+    }
+
+    prefab_instance_destroy(dataset, instance);
+    dataset.removeEntity(placed.root);
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Make some of an entity'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, and two registrations of one clip are two rows the accumulator would add together.
+ *
+ * @param {GPUSceneContext} context
+ * @param {ShadeAnimationClip[]} clips an entity's `AnimationClips`; their channels target entities
+ * @param {ArrayLike<number>} slots indices into `clips`; duplicates are ignored
+ * @returns {ClipRegistration}
+ */
+export function register_clips(context: GPUSceneContext, clips: ShadeAnimationClip[], slots: ArrayLike<number>): ClipRegistration;
+/**
+ * Give back everything {@link register_clips} took out, for a manager that is still the one that
+ * issued it. A restart takes the GPU scene context with it, and the ids it issued mean nothing to the
+ * one that replaces it, so a caller holding a registration from another context forgets it rather
+ * than handing it back here.
+ *
+ * @param {ClipRegistration} registration
+ */
+export function unregister_clips(registration: ClipRegistration): void;
+/**
+ * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ */
+/**
+ * The id a clip has when nobody registered it.
+ * @type {number}
+ */
+export const CLIP_NOT_REGISTERED: number;
+/**
+ * Which of an entity's clips a driver has playable, by their place in its `AnimationClips`.
+ *
+ * `ids[i]` is the manager's id for `clips[i]`, or {@link CLIP_NOT_REGISTERED} where this driver
+ * does not play that clip. Indexed by the clip's place rather than packed, because that is how
+ * both drivers already address a clip — the graph resolves a name to a slot, the clip list does the
+ * same — and a packed array would want a second table to say what each entry was.
+ */
+export class ClipRegistration {
+    /**
+     * 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**. 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.
+     *
+     * @type {GPUSceneContext|null}
+     */
+    context: GPUSceneContext | null;
+    /**
+     * @type {Int32Array}
+     */
+    ids: Int32Array;
+}
+export type GPUSceneContext = import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext;
+export type ShadeAnimationClip = import("../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip;
+//# sourceMappingURL=register_clips.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register_clips.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/register_clips.js"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;;;GAgBG;AACH,wCALW,eAAe,SACf,kBAAkB,EAAE,SACpB,UAAU,MAAM,CAAC,GACf,gBAAgB,CA6B5B;AAED;;;;;;;GAOG;AACH,+CAFW,gBAAgB,QAqB1B;AA/GD;;;GAGG;AAEH;;;GAGG;AACH,kCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH;IACI;;;;;;;;;OASG;IACH,SAFU,eAAe,GAAC,IAAI,CAEf;IAEf;;OAEG;IACH,KAFU,UAAU,CAEI;CAC3B;8BAnCY,OAAO,+CAA+C,EAAE,eAAe;iCACvE,OAAO,sDAAsD,EAAE,kBAAkB"}

package/src/engine/graphics3/register_clips.js

@@ -0,0 +1,114 @@
+import { assert } from "../../core/assert.js";
+
+/**
+ * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ */
+
+/**
+ * The id a clip has when nobody registered it.
+ * @type {number}
+ */
+export const CLIP_NOT_REGISTERED = -1;
+
+/**
+ * Which of an entity's clips a driver has playable, by their place in its `AnimationClips`.
+ *
+ * `ids[i]` is the manager's id for `clips[i]`, or {@link CLIP_NOT_REGISTERED} where this driver
+ * does not play that clip. Indexed by the clip's place rather than packed, because that is how
+ * both drivers already address a clip — the graph resolves a name to a slot, the clip list does the
+ * same — and a packed array would want a second table to say what each entry was.
+ */
+export class ClipRegistration {
+    /**
+     * 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**. 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.
+     *
+     * @type {GPUSceneContext|null}
+     */
+    context = null;
+
+    /**
+     * @type {Int32Array}
+     */
+    ids = new Int32Array(0);
+}
+
+/**
+ * Make some of an entity'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, and two registrations of one clip are two rows the accumulator would add together.
+ *
+ * @param {GPUSceneContext} context
+ * @param {ShadeAnimationClip[]} clips an entity's `AnimationClips`; their channels target entities
+ * @param {ArrayLike<number>} slots indices into `clips`; duplicates are ignored
+ * @returns {ClipRegistration}
+ */
+export function register_clips(context, clips, slots) {
+    assert.defined(context, 'context');
+    assert.isArray(clips, 'clips');
+    assert.defined(slots, 'slots');
+
+    const manager = context.animation_manager;
+
+    const r = new ClipRegistration();
+
+    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_clips} took out, for a manager that is still the one that
+ * issued it. A restart takes the GPU scene context with it, and the ids it issued mean nothing to the
+ * one that replaces it, so a caller holding a registration from another context forgets it rather
+ * than handing it back here.
+ *
+ * @param {ClipRegistration} registration
+ */
+export function unregister_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);
+}