@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/shade_node_to_entity_composition.js

@@ -1,84 +1,84 @@
-import { Name } from "../ecs/name/Name.js";
-import { EntityNode } from "../ecs/parent/EntityNode.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { transform_copy_from_t64 } from "../ecs/transform/transform_copy_from_t64.js";
-import { DrawMode } from "../graphics/ecs/mesh-v2/DrawMode.js";
-import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
-
-/**
- * Turn a loaded model's node tree into entities.
- *
- * **This is what a hierarchy is in an ECS** (D47). meep has no scene graph to hand a model to: it
- * has entities, `EntityNode` to parent them, and `ShadedGeometry` for the ones that draw. A model
- * file is therefore not a thing an entity *holds* — it is a shape an entity's descendants take, and
- * this function is where the file stops being the renderer's tree and becomes the dataset's.
- *
- * It is `three_object_to_entity_composition` with the source swapped: the same output, built from
- * Shade's `Node3D`s instead of three's `Object3D`s. The two exist side by side for as long as both
- * renderers do.
- *
- * **Geometry and material are shared, not copied.** Two entities placing the same model name the
- * same `MeshletGeometry` and the same `ShadeMaterial`; what is per-entity is the row each one gets
- * in the scene, which is `ShadedGeometrySystem3`'s business. That is the whole reason a static model
- * needs no clone of the bundle at all.
- *
- * **A skinned mesh is not expanded, and that is a boundary rather than an omission.** Its vertices
- * are deformed against a skeleton the renderer owns and the GPU poses, and making those joints
- * entities is a design this program does not do (D47). A `SkinnedMesh` node therefore contributes
- * its transform and its name and no geometry, and whatever placed the model keeps drawing it the way
- * Phase 4 built.
- *
- * @param {Node3D} node
- * @returns {EntityNode}
- */
-export function shade_node_to_entity_composition(node) {
-    const result = new EntityNode();
-
-    // the hierarchy's own transform: what this node is, relative to its parent
-    transform_copy_from_t64(result.transform, node.transform_local);
-
-    const entity = result.entity;
-
-    entity.add(transform_copy_from_t64(new Transform(), node.transform_global));
-    entity.add(new Name(node.name));
-
-    if (node.isMesh === true && node.isSkinnedMesh !== true) {
-        entity.add(ShadedGeometry.from(node.geometry, node.material, DrawMode.Triangles));
-    }
-
-    const children = node.children;
-
-    for (let i = 0; i < children.length; i++) {
-        result.addChild(shade_node_to_entity_composition(children[i]));
-    }
-
-    return result;
-}
-
-/**
- * The same, for everything a loader produced.
- *
- * A bundle can carry more than one scene — glTF allows it — and the entity that placed the file owns
- * all of them, so they become children of one root rather than several compositions nobody joins.
- *
- * @param {SceneBundle} bundle
- * @returns {EntityNode}
- */
-export function shade_bundle_to_entity_composition(bundle) {
-    const scenes = bundle.scenes;
-
-    if (scenes.length === 1) {
-        return shade_node_to_entity_composition(scenes[0]);
-    }
-
-    const root = new EntityNode();
-
-    root.entity.add(new Transform());
-    root.entity.add(new Name(""));
-
-    for (let i = 0; i < scenes.length; i++) {
-        root.addChild(shade_node_to_entity_composition(scenes[i]));
-    }
-
-    return root;
-}
+import { Name } from "../ecs/name/Name.js";
+import { EntityNode } from "../ecs/parent/EntityNode.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { transform_copy_from_t64 } from "../ecs/transform/transform_copy_from_t64.js";
+import { DrawMode } from "../graphics/ecs/mesh-v2/DrawMode.js";
+import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
+
+/**
+ * Turn a loaded model's node tree into entities.
+ *
+ * **This is what a hierarchy is in an ECS** (D47). meep has no scene graph to hand a model to: it
+ * has entities, `EntityNode` to parent them, and `ShadedGeometry` for the ones that draw. A model
+ * file is therefore not a thing an entity *holds* — it is a shape an entity's descendants take, and
+ * this function is where the file stops being the renderer's tree and becomes the dataset's.
+ *
+ * It is `three_object_to_entity_composition` with the source swapped: the same output, built from
+ * Shade's `Node3D`s instead of three's `Object3D`s. The two exist side by side for as long as both
+ * renderers do.
+ *
+ * **Geometry and material are shared, not copied.** Two entities placing the same model name the
+ * same `MeshletGeometry` and the same `ShadeMaterial`; what is per-entity is the row each one gets
+ * in the scene, which is `ShadedGeometrySystem`'s business. That is the whole reason a static model
+ * needs no clone of the bundle at all.
+ *
+ * **A skinned mesh is not expanded, and that is a boundary rather than an omission.** Its vertices
+ * are deformed against a skeleton the renderer owns and the GPU poses, and making those joints
+ * entities is a design this program does not do (D47). A `SkinnedMesh` node therefore contributes
+ * its transform and its name and no geometry, and whatever placed the model keeps drawing it the way
+ * Phase 4 built.
+ *
+ * @param {Node3D} node
+ * @returns {EntityNode}
+ */
+export function shade_node_to_entity_composition(node) {
+    const result = new EntityNode();
+
+    // the hierarchy's own transform: what this node is, relative to its parent
+    transform_copy_from_t64(result.transform, node.transform_local);
+
+    const entity = result.entity;
+
+    entity.add(transform_copy_from_t64(new Transform(), node.transform_global));
+    entity.add(new Name(node.name));
+
+    if (node.isMesh === true && node.isSkinnedMesh !== true) {
+        entity.add(ShadedGeometry.from(node.geometry, node.material, DrawMode.Triangles));
+    }
+
+    const children = node.children;
+
+    for (let i = 0; i < children.length; i++) {
+        result.addChild(shade_node_to_entity_composition(children[i]));
+    }
+
+    return result;
+}
+
+/**
+ * The same, for everything a loader produced.
+ *
+ * A bundle can carry more than one scene — glTF allows it — and the entity that placed the file owns
+ * all of them, so they become children of one root rather than several compositions nobody joins.
+ *
+ * @param {SceneBundle} bundle
+ * @returns {EntityNode}
+ */
+export function shade_bundle_to_entity_composition(bundle) {
+    const scenes = bundle.scenes;
+
+    if (scenes.length === 1) {
+        return shade_node_to_entity_composition(scenes[0]);
+    }
+
+    const root = new EntityNode();
+
+    root.entity.add(new Transform());
+    root.entity.add(new Name(""));
+
+    for (let i = 0; i < scenes.length; i++) {
+        root.addChild(shade_node_to_entity_composition(scenes[i]));
+    }
+
+    return root;
+}

package/src/shade/descriptor/pipeline/PipelineLayoutDescriptor.d.ts

@@ -12,12 +12,13 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
      * @param {GPUShaderStage|number} stage
      * @param {(BufferBindingLayout|SamplerBindingLayout|TextureBindingLayout|StorageTextureBindingLayout|ExternalTextureBindingLayout)[][]} bindings
      */
-    static forStage(stage: GPUShaderStage | number, bindings: (BufferBindingLayout | SamplerBindingLayout | TextureBindingLayout | StorageTextureBindingLayout | ExternalTextureBindingLayout)[][]): PipelineLayoutDescriptor;
+    static forStage(stage: GPUShaderStage | number, bindings: (BufferBindingLayout | SamplerBindingLayout | TextureBindingLayout | StorageTextureBindingLayout | ExternalTextureBindingLayout)[][], immediate_size?: number): PipelineLayoutDescriptor;
     /**
      *
      * @param {BindGroupLayoutDescriptor[]} bind_groups
+     * @param {number} [immediate_size] bytes of immediate data, 0 when the shader declares none
      */
-    static from(bind_groups: BindGroupLayoutDescriptor[]): PipelineLayoutDescriptor;
+    static from(bind_groups: BindGroupLayoutDescriptor[], immediate_size?: number): PipelineLayoutDescriptor;
     /**
      *
      * @param {JSONPipelineLayoutDescriptor} json
@@ -29,6 +30,19 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
      * @type {BindGroupLayoutDescriptor[]}
      */
     bindGroupLayouts: BindGroupLayoutDescriptor[];
+    /**
+     * Bytes of immediate data the pipelines using this layout read, 0 when they read none.
+     *
+     * Not a bind group and not a binding — immediate data is part of the shader interface without
+     * being part of its resource interface, so it hangs off the layout itself.
+     *
+     * Must be a multiple of 4 and no larger than the device's `maxImmediateSize`; both are
+     * validated where the layout is created, not here, because this descriptor never sees a device.
+     *
+     * @see https://www.w3.org/TR/webgpu/#dom-gpupipelinelayoutdescriptor-immediatesize
+     * @type {number}
+     */
+    immediateSize: number;
     /**
      *
      * @param {JSONPipelineLayoutDescriptor} json

package/src/shade/descriptor/pipeline/PipelineLayoutDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PipelineLayoutDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/descriptor/pipeline/PipelineLayoutDescriptor.js"],"names":[],"mappings":"AASA;;;;GAIG;AAEH;;GAEG;AACH;IAQI;;;;OAIG;IACH,uBAHW,iBAAe,MAAM,YACrB,CAAC,8HAAsH,CAAC,EAAE,EAAE,4BAgBtI;IAGD;;;OAGG;IACH,yBAFW,yBAAyB,EAAE,4BAsBrC;IAED;;;;OAIG;IACH,gDAFY,wBAAwB,CAQnC;IAjED;;;OAGG;IACH,kBAFU,yBAAyB,EAAE,CAEhB;IAgErB;;;OAGG;IACH,8CAQC;IASD,4BAOC;IAED;;;OAGG;IACH,YAFW,wBAAwB,QAKlC;IAED;;;OAGG;IACH,SAFY,wBAAwB,CAQnC;IAGL;;;OAGG;IACH,qCAFU,OAAO,CAE4C;CAN5D;;qCAnIoC,4BAA4B;0CADvB,yCAAyC"}
+{"version":3,"file":"PipelineLayoutDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/descriptor/pipeline/PipelineLayoutDescriptor.js"],"names":[],"mappings":"AASA;;;;GAIG;AAEH;;GAEG;AACH;IAsBI;;;;OAIG;IACH,uBAHW,iBAAe,MAAM,YACrB,CAAC,8HAAsH,CAAC,EAAE,EAAE,qDAgBtI;IAGD;;;;OAIG;IACH,yBAHW,yBAAyB,EAAE,mBAC3B,MAAM,4BAyBhB;IAED;;;;OAIG;IACH,gDAFY,wBAAwB,CAQnC;IAnFD;;;OAGG;IACH,kBAFU,yBAAyB,EAAE,CAEhB;IAErB;;;;;;;;;;;OAWG;IACH,eAFU,MAAM,CAEC;IAoEjB;;;OAGG;IACH,8CASC;IAYD,4BAQC;IAED;;;OAGG;IACH,YAFW,wBAAwB,QAMlC;IAED;;;OAGG;IACH,SAFY,wBAAwB,CAQnC;IAGL;;;OAGG;IACH,qCAFU,OAAO,CAE4C;CAN5D;;qCA3JoC,4BAA4B;0CADvB,yCAAyC"}

package/src/shade/descriptor/pipeline/PipelineLayoutDescriptor.js

@@ -24,12 +24,26 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
      */
     bindGroupLayouts = []
 
+    /**
+     * Bytes of immediate data the pipelines using this layout read, 0 when they read none.
+     *
+     * Not a bind group and not a binding — immediate data is part of the shader interface without
+     * being part of its resource interface, so it hangs off the layout itself.
+     *
+     * Must be a multiple of 4 and no larger than the device's `maxImmediateSize`; both are
+     * validated where the layout is created, not here, because this descriptor never sees a device.
+     *
+     * @see https://www.w3.org/TR/webgpu/#dom-gpupipelinelayoutdescriptor-immediatesize
+     * @type {number}
+     */
+    immediateSize = 0
+
     /**
      *
      * @param {GPUShaderStage|number} stage
      * @param {(BufferBindingLayout|SamplerBindingLayout|TextureBindingLayout|StorageTextureBindingLayout|ExternalTextureBindingLayout)[][]} bindings
      */
-    static forStage(stage, bindings) {
+    static forStage(stage, bindings, immediate_size = 0) {
         assert.isArray(bindings, 'bindings');
 
         const bind_group_count = bindings.length;
@@ -42,20 +56,24 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
             bind_groups[i] = BindGroupLayoutDescriptor.forStage(stage, "", binding_set);
         }
 
-        return PipelineLayoutDescriptor.from(bind_groups);
+        return PipelineLayoutDescriptor.from(bind_groups, immediate_size);
     }
 
 
     /**
      *
      * @param {BindGroupLayoutDescriptor[]} bind_groups
+     * @param {number} [immediate_size] bytes of immediate data, 0 when the shader declares none
      */
-    static from(bind_groups) {
+    static from(bind_groups, immediate_size = 0) {
 
         assert.isArray(bind_groups, 'bind_groups');
+        assert.isNonNegativeInteger(immediate_size, 'immediate_size');
 
         const r = new PipelineLayoutDescriptor();
 
+        r.immediateSize = immediate_size;
+
         const count = bind_groups.length;
 
         for (let i = 0; i < count; i++) {
@@ -98,12 +116,16 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
         const bindGroupLayouts = json.bindGroupLayouts ?? [];
 
         this.bindGroupLayouts = bindGroupLayouts.map(BindGroupLayoutDescriptor.fromJSON);
+        this.immediateSize = json.immediateSize ?? 0;
     }
 
     hash() {
         return combine_hash(
             super.hash(),
-            computeHashArray(this.bindGroupLayouts, invokeObjectHash)
+            computeHashArray(this.bindGroupLayouts, invokeObjectHash),
+            // two layouts that differ only in immediate size are different layouts; leaving this out
+            // would alias them in the manager's cache and hand a pipeline someone else's budget
+            this.immediateSize
         );
     }
 
@@ -113,6 +135,7 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
         }
 
         return super.equals(other)
+            && this.immediateSize === other.immediateSize
             && isArrayEqual(this.bindGroupLayouts, other.bindGroupLayouts);
     }
 
@@ -123,6 +146,7 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
     copy(other) {
         super.copy(other);
         this.bindGroupLayouts = other.bindGroupLayouts.map(optional_clone);
+        this.immediateSize = other.immediateSize;
     }
 
     /**

package/src/shade/descriptor/pipeline/compute/ComputePipelineDescriptor.d.ts

@@ -12,7 +12,7 @@ export class ComputePipelineDescriptor extends PipelineDescriptorBase {
      * @param {(BufferBindingLayout|SamplerBindingLayout|TextureBindingLayout|StorageTextureBindingLayout|ExternalTextureBindingLayout)[][]} bindings
      * @param {Object<number>} [constants]
      */
-    static simplified({ label, code, bindings, constants }: string): ComputePipelineDescriptor;
+    static simplified({ label, code, bindings, constants, immediate_size }: string): ComputePipelineDescriptor;
     /**
      *
      * @param {GPUComputePipelineDescriptor} json

package/src/shade/descriptor/pipeline/compute/ComputePipelineDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ComputePipelineDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/pipeline/compute/ComputePipelineDescriptor.js"],"names":[],"mappings":"AAQA;IAGI;;;;;OAKG;IACH,mBAJW,MAAM,QACN,MAAM,UACN,wBAAwB,6BAalC;IAED;;;;;OAKG;IACH,wDALW,MAAM,6BAsBhB;IAED;;;OAGG;IACH,+EAMC;IAxDD,2BAAkC;IA0DlC;;;OAGG;IACH,mDAMC;IAED;;;;OAIG;IACH,cAHW,yBAAyB,GACxB,OAAO,CAMlB;IAUL;;;OAGG;IACH,sCAFU,OAAO,CAE8C;CAN9D;uCA7FsC,8BAA8B;kCAEnC,yBAAyB;yCADlB,gCAAgC"}
+{"version":3,"file":"ComputePipelineDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/pipeline/compute/ComputePipelineDescriptor.js"],"names":[],"mappings":"AAQA;IAGI;;;;;OAKG;IACH,mBAJW,MAAM,QACN,MAAM,UACN,wBAAwB,6BAalC;IAED;;;;;OAKG;IACH,wEALW,MAAM,6BAyBhB;IAED;;;OAGG;IACH,+EAMC;IA3DD,2BAAkC;IA6DlC;;;OAGG;IACH,mDAMC;IAED;;;;OAIG;IACH,cAHW,yBAAyB,GACxB,OAAO,CAMlB;IAUL;;;OAGG;IACH,sCAFU,OAAO,CAE8C;CAN9D;uCAhGsC,8BAA8B;kCAEnC,yBAAyB;yCADlB,gCAAgC"}

package/src/shade/descriptor/pipeline/compute/ComputePipelineDescriptor.js

@@ -34,7 +34,7 @@ export class ComputePipelineDescriptor extends PipelineDescriptorBase {
      * @param {(BufferBindingLayout|SamplerBindingLayout|TextureBindingLayout|StorageTextureBindingLayout|ExternalTextureBindingLayout)[][]} bindings
      * @param {Object<number>} [constants]
      */
-    static simplified({ label = "", code, bindings, constants }) {
+    static simplified({ label = "", code, bindings, constants, immediate_size = 0 }) {
         assert.isString(label, 'label');
 
         const r = new ComputePipelineDescriptor();
@@ -42,7 +42,10 @@ export class ComputePipelineDescriptor extends PipelineDescriptorBase {
         r.label = label;
         r.compute.module = ShaderModuleDescriptor.fromCode(code);
 
-        r.layout = PipelineLayoutDescriptor.forStage(GPUShaderStage.COMPUTE, bindings);
+        // `immediate_size` must travel with the bindings: a shader that reads immediate data whose
+        // layout declares none is a pipeline-creation error on a real device, and the two numbers are
+        // derived from the same descriptor
+        r.layout = PipelineLayoutDescriptor.forStage(GPUShaderStage.COMPUTE, bindings, immediate_size);
 
         if(constants !== undefined){
             assert.isObject(constants,'constants');