@aardworx/wombat.rendering 0.21.3 → 0.21.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aardworx/wombat.rendering",
-  "version": "0.21.3",
-  "description": "WebGPU rendering layer for the Wombat TypeScript stack \u2014 RenderObject/RenderTask/runtime + window glue, port of Aardvark.Rendering's lower layers on top of WebGPU and wombat.shader.",
+  "version": "0.21.4",
+  "description": "WebGPU rendering layer for the Wombat TypeScript stack — RenderObject/RenderTask/runtime + window glue, port of Aardvark.Rendering's lower layers on top of WebGPU and wombat.shader.",
   "license": "MIT",
   "author": "krauthaufen",
   "repository": {
@@ -66,4 +66,4 @@
     "access": "public"
   },
   "private": false
-}
+}

package/src/core/renderObject.ts

@@ -129,4 +129,29 @@ export interface RenderObject {
    * See docs/gpu-transform-propagation.md.
    */
   readonly modelChain?: readonly aval<import("@aardworx/wombat.base").Trafo3d>[];
+  /**
+   * Producer-asserted heap eligibility. When `true`, the hybrid
+   * partition routes this RO to the heap path WITHOUT building the
+   * per-RO reactive `isHeapEligible` predicate — for an RO with an
+   * adaptive `drawCall` that predicate is a live custom aval + a
+   * negation aval + their subscriptions, retained per RO for the
+   * scene's lifetime; at collection scale (thousands of row-shaped
+   * ROs) that is pure ballast because the producer already knows the
+   * answer statically.
+   *
+   * The producer GUARANTEES, for the RO's whole lifetime:
+   *   - every attribute/index buffer aval resolves to `kind: "host"`,
+   *   - ≤ 1 distinct texture aval and ≤ 1 distinct sampler aval,
+   *     each heap-servable; no `storageBuffers`,
+   *   - index format (if indexed) is uint16/uint32,
+   *   - `drawCall.firstInstance === 0`; non-indexed ⇒
+   *     `firstVertex === 0`; `instanceCount ≥ 0` (0 draws nothing),
+   *   - payload stays within the heap ingest budget.
+   *
+   * Only the global `heapEnabled` toggle still applies (one shared
+   * aval per scene). A wrong assertion produces wrong routing —
+   * intended for scene-graph layers that verify these conditions
+   * once per template, never for hand-built ROs.
+   */
+  readonly heapAsserted?: boolean;
 }

package/src/runtime/heapAdapter.ts

@@ -605,7 +605,11 @@ export function renderObjectToHeapSpec(
     pipelineState: ro.pipelineState,
     inputs,
     ...(instanceAttributes !== undefined ? { instanceAttributes } : {}),
-    ...(dc.instanceCount > 1 ? { instanceCount: dc.instanceCount } : {}),
+    // ≠ 1 (not > 1): instanceCount 0 must flow through — the scan
+    // kernel emits indexCount × 0 = nothing, matching what the legacy
+    // path draws for zero instances. Omitting it would default to 1
+    // and pack a garbage instance from empty per-instance arrays.
+    ...(dc.instanceCount !== 1 ? { instanceCount: dc.instanceCount } : {}),
     ...geom,
     ...(textures !== undefined ? { textures } : {}),
     ...(ro.injectedStorage !== undefined && ro.injectedStorage.count > 0

package/src/runtime/hybridScene.ts

@@ -202,9 +202,16 @@ export function compileHybridScene(
   // The per-RO eligibility is ANDed with the global `heapEnabled`
   // toggle — flipping that off forces every RO to legacy.
   const heapEnabled = opts.heapEnabled ?? AVal.constant(true);
+  // Producer-asserted ROs (`heapAsserted: true`) skip the per-RO
+  // predicate entirely — they all share these TWO scene-level avals
+  // instead of two live avals each (see RenderObject.heapAsserted).
+  const notHeapEnabled = heapEnabled.isConstant
+    ? AVal.constant(!heapEnabled.force(/* allow-force */))
+    : heapEnabled.map(b => !b);
   const eligCache = new WeakMap<RenderObject, aval<boolean>>();
   const notEligCache = new WeakMap<RenderObject, aval<boolean>>();
   const elig = (ro: RenderObject): aval<boolean> => {
+    if (ro.heapAsserted === true) return heapEnabled;
     let av = eligCache.get(ro);
     if (av === undefined) {
       const perRO = isHeapEligible(ro);
@@ -218,6 +225,7 @@ export function compileHybridScene(
     return av;
   };
   const notElig = (ro: RenderObject): aval<boolean> => {
+    if (ro.heapAsserted === true) return notHeapEnabled;
     let av = notEligCache.get(ro);
     if (av === undefined) {
       const e = elig(ro);