@volter/blender-engine 0.1.76 → 0.1.78

package/browser/three/blender-graph-material.ts

@@ -347,8 +347,11 @@ ${compiled.uvs.map(n => `varying vec2 ${uvVarying(n)};`).join('\n')}`;
     `vBlenderObjectPosition = transformed;
 vBlenderObjectNormal = objectNormal;
 mat4 blenderWorldMatrix = modelMatrix;
+#ifdef USE_BATCHING
+blenderWorldMatrix = blenderWorldMatrix * batchingMatrix;
+#endif
 #ifdef USE_INSTANCING
-blenderWorldMatrix = modelMatrix * instanceMatrix;
+blenderWorldMatrix = blenderWorldMatrix * instanceMatrix;
 #endif
 vBlenderWorldPosition = (blenderWorldMatrix * vec4(transformed, 1.0)).xyz;
 vBlenderWorldNormal = normalize(transpose(inverse(mat3(blenderWorldMatrix))) * objectNormal);

package/browser/three/blender-motion-geometry.ts

@@ -306,10 +306,18 @@ export class BlenderMotionGeometry {
     for (const [source, entry] of this.cache) {
       for (const mesh of this.groups.get(source) ?? []) {
         if (!instanceObjectShown(mesh) || (mesh.frustumCulled && !this.frustum.intersectsObject(mesh))) continue;
-        // Frobenius norm bounds the linear transform even under shear; the
-        // longest axis alone can understate the projected simplifier error.
+        // Bound the largest singular value by the maximum absolute row sum
+        // of AᵀA. Unlike Frobenius this is tight for orthogonal TRS columns,
+        // while still bounding shear. A uniform rotation must not inflate
+        // both error and radius by sqrt(3) and veto nearby placements.
         const e = mesh.matrixWorld.elements;
-        const scale = Math.hypot(e[0]!, e[1]!, e[2]!, e[4]!, e[5]!, e[6]!, e[8]!, e[9]!, e[10]!);
+        const x2 = e[0]! ** 2 + e[1]! ** 2 + e[2]! ** 2;
+        const y2 = e[4]! ** 2 + e[5]! ** 2 + e[6]! ** 2;
+        const z2 = e[8]! ** 2 + e[9]! ** 2 + e[10]! ** 2;
+        const xy = Math.abs(e[0]! * e[4]! + e[1]! * e[5]! + e[2]! * e[6]!);
+        const xz = Math.abs(e[0]! * e[8]! + e[1]! * e[9]! + e[2]! * e[10]!);
+        const yz = Math.abs(e[4]! * e[8]! + e[5]! * e[9]! + e[6]! * e[10]!);
+        const scale = Math.sqrt(Math.max(x2 + xy + xz, y2 + xy + yz, z2 + xz + yz));
         const sphere = source.boundingSphere!;
         this.centre.copy(sphere.center).applyMatrix4(mesh.matrixWorld).applyMatrix4(camera.matrixWorldInverse);
         const depth = (camera as THREE.PerspectiveCamera).isPerspectiveCamera

package/browser/three/blender-ordered-batches.ts

@@ -0,0 +1,156 @@
+import * as THREE from 'three';
+
+export const ORDERED_BATCH_CAPACITY = 64;
+const FAMILY_BYTES = 4 * 1024 * 1024;
+const CACHE_BYTES = 32 * 1024 * 1024;
+const MAX_DRAWS = 1024;
+type Shape = {geometry: THREE.BufferGeometry; stamp: string};
+type Family = {material: THREE.Material; shapes: Map<number, Shape>; template: THREE.BatchedMesh | null;
+  ids: Map<number, number>; draws: THREE.BatchedMesh[]; dirty: boolean; bytes: number; refused: boolean};
+
+/** Immutable packed attributes are shared between ordered draw runs. Only the
+ * matrix/indirection textures and command lists belong to an individual run.
+ * All interaction and authored geometry remain on the canonical meshes. */
+export class BlenderOrderedBatches {
+  private readonly families = new Map<string, Family>();
+  private readonly registrations = new Map<string, string | null>();
+  private bytes = 0;
+  private drawCount = 0;
+  private created = 0;
+  pending = false;
+
+  begin(): void { this.created = 0; this.pending = false; this.registrations.clear(); }
+
+  register(geometry: THREE.BufferGeometry, material: THREE.Material, order: number): string | null {
+    const registration = `${geometry.id}:${material.uuid}:${order}`;
+    if (this.registrations.has(registration)) return this.registrations.get(registration)!;
+    this.registrations.set(registration, null);
+    const position = geometry.getAttribute('position');
+    const count = geometry.index?.count ?? position?.count ?? 0;
+    if (!position || geometry.drawRange.start !== 0 || geometry.drawRange.count < count ||
+        Object.keys(geometry.morphAttributes).length) return null;
+    const layout: unknown[] = [!!geometry.index, geometry.userData['blenderUvChannels'] ?? null];
+    const versions: unknown[] = [geometry.index?.id, geometry.index?.version];
+    let bytes = (geometry.index?.count ?? 0) * 4;
+    for (const name of Object.keys(geometry.attributes).sort()) {
+      const attribute = geometry.getAttribute(name);
+      if (!(attribute instanceof THREE.BufferAttribute) ||
+          (attribute as THREE.InstancedBufferAttribute).isInstancedBufferAttribute ||
+          attribute instanceof THREE.Float16BufferAttribute ||
+          attribute.count !== position.count) return null;
+      layout.push([name, attribute.array.constructor.name, attribute.itemSize, attribute.normalized, attribute.gpuType]);
+      versions.push(name, attribute.id, attribute.version);
+      bytes += attribute.array.byteLength;
+    }
+    if (bytes > FAMILY_BYTES) return null;
+    const key = `multi:${material.uuid}:${order}:${JSON.stringify(layout)}`;
+    let family = this.families.get(key);
+    if (!family) {
+      family = {material, shapes: new Map(), template: null, ids: new Map(), draws: [], dirty: true, bytes: 0, refused: false};
+      this.families.set(key, family);
+    }
+    const stamp = JSON.stringify(versions);
+    const held = family.shapes.get(geometry.id);
+    if (!held || held.stamp !== stamp) {
+      family.shapes.set(geometry.id, {geometry, stamp});
+      family.dirty = true;
+    }
+    this.registrations.set(registration, key);
+    return key;
+  }
+
+  pack(): void {
+    for (const family of this.families.values()) {
+      if (!family.dirty) continue;
+      this.release(family);
+      family.dirty = false;
+      let vertices = 0, indices = 0, bytes = 0;
+      for (const {geometry} of family.shapes.values()) {
+        vertices += geometry.getAttribute('position').count;
+        indices += geometry.index?.count ?? 0;
+        for (const attribute of Object.values(geometry.attributes)) bytes += attribute.array.byteLength;
+      }
+      bytes += indices * (vertices > 65535 ? 4 : 2);
+      family.refused = bytes > FAMILY_BYTES || this.bytes + bytes > CACHE_BYTES;
+      if (family.refused) continue;
+      const template = new THREE.BatchedMesh(ORDERED_BATCH_CAPACITY, vertices, indices, family.material);
+      template.sortObjects = false;
+      template.perObjectFrustumCulled = false;
+      template.frustumCulled = false;
+      template.matrixAutoUpdate = false;
+      template.boundingSphere = new THREE.Sphere();
+      template.name = 'Blender ordered multi-draw';
+      template.userData['engineInternal'] = true;
+      for (const {geometry} of family.shapes.values()) family.ids.set(geometry.id, template.addGeometry(geometry));
+      // Named UV selection is a geometry-level material input. The family key
+      // requires identical maps; every per-vertex graph attribute is copied.
+      const first = family.shapes.values().next().value!.geometry;
+      template.geometry.userData['blenderUvChannels'] = first.userData['blenderUvChannels'];
+      for (const name of Object.keys(first.attributes))
+        (template.geometry.getAttribute(name) as THREE.BufferAttribute).gpuType = (first.getAttribute(name) as THREE.BufferAttribute).gpuType;
+      family.template = template;
+      family.bytes = bytes;
+      this.bytes += bytes;
+    }
+  }
+
+  available(key: string): boolean { return !!this.families.get(key)?.template; }
+
+  get(key: string, index: number): THREE.BatchedMesh | null {
+    const family = this.families.get(key)!;
+    const template = family.template;
+    if (!template) return null;
+    let draw = family.draws[index];
+    if (!draw) {
+      if (this.drawCount >= MAX_DRAWS) return null;
+      // copy() uses public Three APIs and briefly copies the packed arrays.
+      // Bound that transient work per frame; ordinary meshes fill every gap.
+      if (this.created >= 4) { this.pending = true; return null; }
+      draw = new THREE.BatchedMesh(1, 0, 0, family.material);
+      draw.dispose();
+      draw.copy(template);
+      for (const name of Object.keys(template.geometry.attributes))
+        draw.geometry.setAttribute(name, template.geometry.getAttribute(name));
+      draw.geometry.setIndex(template.geometry.index);
+      const firstId = family.ids.values().next().value!;
+      for (let i = 0; i < ORDERED_BATCH_CAPACITY; i++) {
+        draw.addInstance(firstId);
+        draw.setVisibleAt(i, false);
+      }
+      family.draws.push(draw);
+      this.created++;
+      this.drawCount++;
+    }
+    return draw;
+  }
+
+  geometryId(key: string, geometry: THREE.BufferGeometry): number { return this.families.get(key)!.ids.get(geometry.id)!; }
+
+  inspect() { return {bytes: this.bytes, draws: this.drawCount, pending: this.pending,
+    refusedFamilies: [...this.families.values()].filter(f => f.refused).length}; }
+
+  private release(family: Family): void {
+    for (const draw of family.draws) {
+      draw.removeFromParent();
+      // BatchedMesh.dispose owns its geometry. Detach shared buffer attributes
+      // first, so retiring one run cannot delete another run's GPU buffers.
+      for (const name of Object.keys(draw.geometry.attributes)) draw.geometry.deleteAttribute(name);
+      draw.geometry.setIndex(null);
+      draw.dispose();
+      this.drawCount--;
+    }
+    family.draws.length = 0;
+    family.template?.dispose();
+    family.template = null;
+    family.ids.clear();
+    this.bytes -= family.bytes;
+    family.bytes = 0;
+  }
+
+  clear(): void {
+    for (const family of this.families.values()) this.release(family);
+    this.families.clear();
+    this.registrations.clear();
+    this.pending = false;
+  }
+}

package/browser/three/blender-runtime-view.ts

@@ -1243,12 +1243,19 @@ export class BlenderRuntimeView {
     presenterChanged();
   }
 
+  private drawPreparation: {
+    last: {opaqueMs: number; motionMs: number; transparentMs: number} | null;
+    navigation: {opaqueMs: number; motionMs: number; transparentMs: number} | null;
+  } = {last: null, navigation: null};
+
   /** Before the renderer uploads attributes/builds its queues, for this area's
    * actual camera. Transparent instance runs are camera-order dependent. */
-  prepareDraw(camera: THREE.Camera, options?: {interactive: boolean; height: number}): () => void {
+  prepareDraw(camera: THREE.Camera, options?: {interactive: boolean; height: number; multiDraw?: boolean}): () => void {
     try {
+      const start = performance.now();
       this.instances.prepareDraw(camera);
       this.root.updateMatrixWorld(true);
+      const opaqueDone = performance.now();
       const motion = this.motionGeometry.prepare(camera, !this.rendered && (this.mode ?? this.frame?.mode) === 'OBJECT' &&
         options?.interactive === true, options?.height ?? 0);
       // A changed navigation geometry is an ordinary-draw fallback for an
@@ -1256,7 +1263,12 @@ export class BlenderRuntimeView {
       // runs are planned AFTER per-placement geometry selection, preserving
       // their sorting barriers and compatible geometry grouping.
       if (motion) this.instances.sync();
-      this.transparentInstances.prepare(camera);
+      const motionDone = performance.now();
+      this.transparentInstances.prepare(camera, options?.multiDraw === true);
+      const timing = {opaqueMs: opaqueDone - start, motionMs: motionDone - opaqueDone,
+        transparentMs: performance.now() - motionDone};
+      this.drawPreparation.last = timing;
+      if (motion) this.drawPreparation.navigation = timing;
     } catch (error) {
       this.motionGeometry.finish();
       this.instances.finishDraw();
@@ -2075,7 +2087,7 @@ export class BlenderRuntimeView {
   }
 
   drawStatistics() {
-    return {enabled: this.drawBatching, opaque: this.instances.inspect(), transparent: this.transparentInstances.inspect(), motion: this.motionGeometry.inspect()};
+    return {enabled: this.drawBatching, preparation: {...this.drawPreparation}, opaque: this.instances.inspect(), transparent: this.transparentInstances.inspect(), motion: this.motionGeometry.inspect()};
   }
 
   snapshot() {

package/browser/three/blender-transparent-instances.ts

@@ -1,10 +1,12 @@
 import * as THREE from 'three';
+import {BlenderOrderedBatches, ORDERED_BATCH_CAPACITY} from './blender-ordered-batches';
+import {presenterChanged} from './blender-presenter-change';
 import {graphDrawAttributes} from './blender-graph-material';
 import {instanceMatrixSupported, instanceObjectShown} from './blender-runtime-instances';
 
-const CAPACITY = 64;
-type Entry = {mesh: THREE.Mesh; material: THREE.Material | null; key: string | null; groupOrder: number; z: number; centre: THREE.Vector3};
-type Draw = {mesh: THREE.InstancedMesh; members: THREE.Mesh[]};
+const CAPACITY = ORDERED_BATCH_CAPACITY;
+type Entry = {mesh: THREE.Mesh; material: THREE.Material | null; key: string | null; batchKey: string | null; groupOrder: number; z: number; centre: THREE.Vector3};
+type Draw = {mesh: THREE.InstancedMesh | THREE.BatchedMesh; members: THREE.Mesh[]};
 
 function groupOrder(mesh: THREE.Object3D): number {
   for (let parent = mesh.parent; parent; parent = parent.parent)
@@ -19,6 +21,9 @@ function groupOrder(mesh: THREE.Object3D): number {
  * This does not turn blended foliage into cutouts or change its opacity. */
 export class BlenderTransparentInstances {
   private objects: THREE.Mesh[] = [];
+  private readonly ordered = new BlenderOrderedBatches();
+  private readonly mixedDraws = new Map<THREE.BatchedMesh, Draw>();
+  private multiDraw = false;
   private readonly pools = new Map<string, Draw[]>();
   private readonly hidden: THREE.Mesh[] = [];
   private readonly inverse = new THREE.Matrix4();
@@ -29,6 +34,7 @@ export class BlenderTransparentInstances {
   private readonly depth = new THREE.Vector4();
   private batches = 0;
   private instances = 0;
+  private excluded: Record<string, number> = {};
   private readonly planState: (number | string)[] = [];
   private readonly planned: Draw[] = [];
   private stateIndex = 0;
@@ -41,12 +47,15 @@ export class BlenderTransparentInstances {
     this.objects = [...objects].filter((object): object is THREE.Mesh => (object as THREE.Mesh).isMesh === true);
   }
 
-  prepare(camera: THREE.Camera): void {
+  prepare(camera: THREE.Camera, multiDraw = false): void {
     this.finishDraw();
     if (!this.objects.length) return;
     camera.updateMatrixWorld();
     this.projection.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
-    if (!this.planChanged(camera)) {
+    const capabilityChanged = this.multiDraw !== multiDraw;
+    this.multiDraw = multiDraw;
+    const inputsChanged = this.planChanged(camera);
+    if (!inputsChanged && !capabilityChanged && !this.ordered.pending) {
       // The draw plan is a disposable presentation, not evaluated scene data.
       // Reuse only after exact comparison of every input to culling/ordering;
       // a camera move, drag, visibility or material change rebuilds it below.
@@ -60,11 +69,14 @@ export class BlenderTransparentInstances {
       return;
     }
     this.planned.length = 0;
+    for (const draw of this.mixedDraws.values()) draw.members.length = 0;
+    this.ordered.begin();
     for (const pool of this.pools.values()) for (const draw of pool) {
       draw.mesh.visible = false;
       draw.members.length = 0;
     }
     this.batches = this.instances = 0;
+    this.excluded = {};
     this.frustum.setFromProjectionMatrix(this.projection);
     this.inverse.copy(this.root.matrixWorld).invert();
     const entries: Entry[] = [];
@@ -118,8 +130,22 @@ export class BlenderTransparentInstances {
           key = groupKey;
         }
       }
-      entries.push({mesh, material, key, groupOrder: order, z, centre});
+      if (key === null) {
+        const reason = !candidate ? 'multipleMaterials'
+          : (candidate as THREE.ShaderMaterial).isShaderMaterial ? 'customShader'
+          : (candidate as THREE.MeshPhysicalMaterial).transmission > 0 ? 'transmission'
+          : candidate.side === THREE.DoubleSide && !candidate.forceSinglePass ? 'twoPass'
+          : 'geometryLayersOrTransform';
+        this.excluded[reason] = (this.excluded[reason] ?? 0) + 1;
+      }
+      const batchKey = multiDraw && key && material ? this.ordered.register(mesh.geometry, material, mesh.renderOrder) : null;
+      entries.push({mesh, material, key, batchKey, groupOrder: order, z, centre});
     }
+    this.ordered.pack();
+    // A family may exceed the bounded cache. Retain its original instancing
+    // key rather than merging incompatible geometries on the fallback path.
+    for (const entry of entries) if (entry.batchKey && this.ordered.available(entry.batchKey)) entry.key = entry.batchKey;
+    for (const [mesh] of this.mixedDraws) if (!mesh.parent) this.mixedDraws.delete(mesh);
     entries.sort((a, b) => a.groupOrder - b.groupOrder || a.mesh.renderOrder - b.mesh.renderOrder || b.z - a.z || a.mesh.id - b.mesh.id);
     const used = new Map<string, number>();
     for (let begin = 0; begin < entries.length;) {
@@ -143,9 +169,26 @@ export class BlenderTransparentInstances {
           const head = entries[offset]!;
           const index = used.get(first.key) ?? 0;
           used.set(first.key, index + 1);
+          const mixed = first.key.startsWith('multi:');
+          let draw: Draw | undefined;
+          if (mixed) {
+            const mesh = this.ordered.get(first.key, index);
+            if (!mesh) continue;
+            draw = this.mixedDraws.get(mesh);
+            if (!draw) {
+              draw = {mesh, members: []};
+              this.mixedDraws.set(mesh, draw);
+              const held = draw;
+              mesh.raycast = (raycaster, hits) => {
+                if (mesh.visible) for (const member of held.members)
+                  if (instanceObjectShown(member)) member.raycast(raycaster, hits);
+              };
+              this.root.add(mesh);
+            }
+          }
           let pool = this.pools.get(first.key);
           if (!pool) { pool = []; this.pools.set(first.key, pool); }
-          let draw = pool[index];
+          if (!mixed) draw = pool[index];
           if (!draw) {
             const mesh = new THREE.InstancedMesh(first.mesh.geometry, first.material!, CAPACITY);
             mesh.name = 'Blender ordered transparency';
@@ -174,12 +217,20 @@ export class BlenderTransparentInstances {
             const member = entries[offset + i]!.mesh;
             this.matrix.multiplyMatrices(this.inverse, member.matrixWorld);
             draw.mesh.setMatrixAt(i, this.matrix);
+            if (draw.mesh instanceof THREE.BatchedMesh) {
+              draw.mesh.setGeometryIdAt(i, this.ordered.geometryId(first.key, member.geometry));
+              draw.mesh.setVisibleAt(i, true);
+            }
             draw.members.push(member);
             member.layers.disable(0);
             this.hidden.push(member);
           }
-          draw.mesh.count = length;
-          draw.mesh.instanceMatrix.needsUpdate = true;
+          if (draw.mesh instanceof THREE.BatchedMesh) {
+            for (let i = length; i < CAPACITY; i++) draw.mesh.setVisibleAt(i, false);
+          } else {
+            draw.mesh.count = length;
+            draw.mesh.instanceMatrix.needsUpdate = true;
+          }
           this.planned.push(draw);
           this.batches++;
           this.instances += length;
@@ -187,9 +238,12 @@ export class BlenderTransparentInstances {
       }
       begin = end;
     }
+    // A quiet viewport must also finish bounded pool construction. Notify only
+    // after this draw's temporary layer/geometry swaps have been restored.
+    if (this.ordered.pending) queueMicrotask(presenterChanged);
   }
 
-  inspect() { return {batches: this.batches, instances: this.instances}; }
+  inspect() { return {batches: this.batches, instances: this.instances, excluded: {...this.excluded}, multiDraw: this.ordered.inspect()}; }
 
   private observe(value: number | string): void {
     if (this.planState[this.stateIndex] !== value) {
@@ -207,6 +261,7 @@ export class BlenderTransparentInstances {
     this.observe(camera.layers.mask);
     for (const n of this.projection.elements) this.observe(n);
     for (const n of this.root.matrixWorld.elements) this.observe(n);
+    const observedGeometry = new Set<THREE.BufferGeometry>();
     for (const mesh of this.objects) {
       this.observe(mesh.parent?.id ?? -1);
       this.observe(instanceObjectShown(mesh) ? 1 : 0);
@@ -218,6 +273,19 @@ export class BlenderTransparentInstances {
       for (const n of mesh.matrixWorld.elements) this.observe(n);
       const geometry = mesh.geometry;
       this.observe(geometry.id);
+      if (!observedGeometry.has(geometry)) {
+        observedGeometry.add(geometry);
+        this.observe(geometry.index?.id ?? -1);
+        this.observe(geometry.index?.version ?? -1);
+        this.observe(JSON.stringify(geometry.userData['blenderUvChannels'] ?? null));
+        for (const name of Object.keys(geometry.attributes).sort()) {
+          const attribute = geometry.getAttribute(name);
+          this.observe(name);
+          if (attribute instanceof THREE.BufferAttribute) {
+            this.observe(attribute.id); this.observe(attribute.version);
+          }
+        }
+      }
       this.observe(geometry.drawRange.start);
       this.observe(geometry.drawRange.count);
       this.observe(geometry.index?.count ?? geometry.getAttribute('position').count);
@@ -249,6 +317,7 @@ export class BlenderTransparentInstances {
     for (const mesh of this.hidden) mesh.layers.enable(0);
     this.hidden.length = 0;
     for (const pool of this.pools.values()) for (const {mesh} of pool) mesh.visible = false;
+    for (const {mesh} of this.mixedDraws.values()) mesh.visible = false;
   }
 
   clear(): void {
@@ -258,6 +327,8 @@ export class BlenderTransparentInstances {
       mesh.dispose();
     }
     this.pools.clear();
+    this.ordered.clear();
+    this.mixedDraws.clear();
     this.planned.length = 0;
     this.planState.length = 0;
     this.objects = [];

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/blender-engine",
   "author": "Volter AI, Inc.",
   "license": "GPL-3.0-or-later",
-  "version": "0.1.76",
+  "version": "0.1.78",
   "publishConfig": {
     "access": "public"
   },