@volter/blender-engine 0.1.65 → 0.1.67

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

@@ -148,6 +148,30 @@ export function graphUvChannels(material: THREE.MeshPhysicalMaterial): number[]
   return Object.values(bindings.get(material)?.channels ?? {});
 }
 
+/** Attributes a physical graph draw can read, including its pending program.
+ * Resident geometry retains many more authored layers than a shader consumes;
+ * only shader inputs count toward WebGL's vertex attribute limit. */
+export function graphDrawAttributes(material: THREE.Material, geometry: THREE.BufferGeometry): Set<string> {
+  const names = new Set(['position', 'normal', 'uv']);
+  if (geometry.hasAttribute('tangent')) names.add('tangent');
+  if (material.vertexColors) names.add('color');
+  if (!(material instanceof THREE.MeshPhysicalMaterial)) return names;
+  const channels = geometry.userData['blenderUvChannels'] as Record<string, number> | undefined;
+  const uv = (name: string) => {
+    const channel = name === '' ? 0 : (channels?.[name] ?? 9);
+    names.add(channel === 0 ? 'uv' : `uv${channel}`);
+  };
+  for (const texture of [material.map, material.roughnessMap, material.normalMap])
+    if (texture) uv((texture.userData['blenderUvName'] as string | undefined) ?? '');
+  for (const binding of [bindings.get(material), pendings.get(material)?.binding]) {
+    if (!binding) continue;
+    names.add('blenderOrco');
+    for (const name of binding.compiled.uvs) uv(name);
+    for (const name of binding.compiled.attributes) names.add(graphAttributeName(name));
+  }
+  return names;
+}
+
 /** The channel each named UV layer is in on `geometry` (a layer the mesh
  *  lacks reads zeros from channel 9, Blender's missing attribute). */
 function channelsFor(compiled: CompiledGraph, geometry: THREE.BufferGeometry): Record<string, number> {
@@ -322,8 +346,12 @@ ${compiled.uvs.map(n => `varying vec2 ${uvVarying(n)};`).join('\n')}`;
     '#include <project_vertex>',
     `vBlenderObjectPosition = transformed;
 vBlenderObjectNormal = objectNormal;
-vBlenderWorldPosition = (modelMatrix * vec4(transformed, 1.0)).xyz;
-vBlenderWorldNormal = normalize(transpose(inverse(mat3(modelMatrix))) * objectNormal);
+mat4 blenderWorldMatrix = modelMatrix;
+#ifdef USE_INSTANCING
+blenderWorldMatrix = modelMatrix * instanceMatrix;
+#endif
+vBlenderWorldPosition = (blenderWorldMatrix * vec4(transformed, 1.0)).xyz;
+vBlenderWorldNormal = normalize(transpose(inverse(mat3(blenderWorldMatrix))) * objectNormal);
 vBlenderOrco = blenderOrco;
 ${compiled.attributes.map(n => `${attributeVarying(n)} = ${graphAttributeName(n)};`).join('\n')}
 ${compiled.uvs.map(n => `${uvVarying(n)} = ${attribute(channels[n] ?? 0)};`).join('\n')}

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

@@ -0,0 +1,172 @@
+import * as THREE from 'three';
+import { graphDrawAttributes } from './blender-graph-material';
+
+// Small spatial batches retain frustum rejection without duplicating geometry.
+const BATCH_SIZE = 64;
+type Member = { mesh: THREE.Mesh; layers: number };
+type Batch = { draw: THREE.InstancedMesh; members: Member[] };
+
+function sameMaterials(a: THREE.Material | THREE.Material[], b: THREE.Material | THREE.Material[]): boolean {
+  return Array.isArray(a) && Array.isArray(b)
+    ? a.length === b.length && a.every((material, i) => material === b[i])
+    : a === b;
+}
+
+function shown(object: THREE.Object3D): boolean {
+  for (let node: THREE.Object3D | null = object; node; node = node.parent)
+    if (!node.visible) return false;
+  return true;
+}
+
+/** Three's instance normal transform supports positive, orthogonal scale axes.
+ * Mirrored, singular and sheared placements keep the ordinary Mesh draw. */
+function supported(matrix: THREE.Matrix4): boolean {
+  if (matrix.determinant() <= 0) return false;
+  const e = matrix.elements;
+  const x = Math.hypot(e[0]!, e[1]!, e[2]!);
+  const y = Math.hypot(e[4]!, e[5]!, e[6]!);
+  const z = Math.hypot(e[8]!, e[9]!, e[10]!);
+  const dot = (a: number, b: number) => e[a]! * e[b]! + e[a + 1]! * e[b + 1]! + e[a + 2]! * e[b + 2]!;
+  return Number.isFinite(x + y + z) && Math.min(x, y, z) > 0 &&
+    Math.abs(dot(0, 4)) <= 1e-7 * x * y &&
+    Math.abs(dot(0, 8)) <= 1e-7 * x * z &&
+    Math.abs(dot(4, 8)) <= 1e-7 * y * z;
+}
+
+/** Disposable draws only. The original objects, geometry, material slots and
+ * parent graph remain the authority for hierarchy, bounds, editing and picking.
+ * Layer zero-mask suppresses their ordinary draw; batch raycasts return those
+ * same original objects. Selection passes can still temporarily add their mask
+ * layer to an original. No vertices or authored data are reduced or replaced. */
+export class BlenderRuntimeInstances {
+  private readonly batches: Batch[] = [];
+  private readonly inverse = new THREE.Matrix4();
+  private readonly matrix = new THREE.Matrix4();
+  private readonly box = new THREE.Box3();
+  private eligible = 0;
+  private excluded: Record<string, number> = {};
+
+  constructor(private readonly root: THREE.Group) {}
+
+  rebuild(objects: Iterable<THREE.Object3D>, enabled: boolean): void {
+    this.clear();
+    if (!enabled) return;
+    const groups = new Map<string, THREE.Mesh[]>();
+    const exclude = (reason: string) => { this.excluded[reason] = (this.excluded[reason] ?? 0) + 1; };
+    this.inverse.copy(this.root.matrixWorld).invert();
+    for (const object of objects) {
+      const mesh = object as THREE.Mesh;
+      if (!mesh.isMesh) continue;
+      if ((mesh as THREE.SkinnedMesh).isSkinnedMesh ||
+          (mesh as THREE.InstancedMesh).isInstancedMesh || mesh.morphTargetInfluences ||
+          mesh.layers.mask !== 1) { exclude('deformationOrLayers'); continue; }
+      const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+      if (materials.some(m => m.transparent || (m as THREE.MeshPhysicalMaterial).transmission > 0 ||
+          (m as THREE.ShaderMaterial).isShaderMaterial)) { exclude('material'); continue; }
+      // Four slots for instanceMatrix, at most twelve for each actual program.
+      // Count active inputs, NOT every stored authored layer: retaining unused
+      // UVs/colours must not disable batching. No channel is deleted to fit.
+      if (materials.some(m => graphDrawAttributes(m, mesh.geometry).size > 12)) { exclude('attributeBudget'); continue; }
+      this.matrix.multiplyMatrices(this.inverse, mesh.matrixWorld);
+      if (!supported(this.matrix)) { exclude('transform'); continue; }
+      this.eligible++;
+      const key = `${mesh.geometry.id}:${Array.isArray(mesh.material) ? 'slots' : 'single'}:` +
+        materials.map(m => m.uuid).join(',') + `:${mesh.renderOrder}`;
+      const group = groups.get(key);
+      if (group) group.push(mesh);
+      else groups.set(key, [mesh]);
+    }
+    for (const group of groups.values()) {
+      if (group.length < 2) continue;
+      // Partition along the widest centre axis, recursively. Adjacent authored
+      // names need not be adjacent in space (linked trees span the whole Bridge).
+      const partition = (members: THREE.Mesh[]): void => {
+        if (members.length > BATCH_SIZE) {
+          this.box.makeEmpty();
+          for (const mesh of members) this.box.expandByPoint(new THREE.Vector3().setFromMatrixPosition(mesh.matrixWorld));
+          const size = this.box.getSize(new THREE.Vector3());
+          const axis = size.x >= size.y && size.x >= size.z ? 12 : size.y >= size.z ? 13 : 14;
+          members.sort((a, b) => a.matrixWorld.elements[axis]! - b.matrixWorld.elements[axis]!);
+          const middle = Math.floor(members.length / 2);
+          partition(members.slice(0, middle));
+          partition(members.slice(middle));
+          return;
+        }
+        if (members.length < 2) return;
+        const first = members[0]!;
+        const draw = new THREE.InstancedMesh(first.geometry, first.material, members.length);
+        draw.name = 'Blender repeated geometry';
+        draw.userData['engineInternal'] = true;
+        draw.matrixAutoUpdate = false;
+        draw.renderOrder = first.renderOrder;
+        draw.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+        const batch: Batch = {draw, members: members.map(mesh => ({mesh, layers: mesh.layers.mask}))};
+        // Return the canonical mesh, not the internal batch or an unstable slot.
+        draw.raycast = (raycaster, hits) => {
+          for (const {mesh} of batch.members)
+            if (mesh.layers.mask === 0 && shown(mesh)) mesh.raycast(raycaster, hits);
+        };
+        this.root.add(draw);
+        draw.updateMatrixWorld(true);
+        this.batches.push(batch);
+      };
+      partition(group);
+    }
+    this.sync();
+  }
+
+  /** Called after the root updates its descendants, before Three builds its
+   * render list/uploads attributes. Live gizmo transforms therefore appear on
+   * the very next draw, including parent transforms and visibility changes. */
+  sync(): void {
+    if (!this.batches.length) return;
+    this.inverse.copy(this.root.matrixWorld).invert();
+    for (const {draw, members} of this.batches) {
+      let count = 0;
+      let changed = false;
+      for (const member of members) {
+        const {mesh} = member;
+        this.matrix.multiplyMatrices(this.inverse, mesh.matrixWorld);
+        // A drag can introduce negative scale/shear, or a skin can replace a
+        // mesh between frames. Fall back immediately without touching its data.
+        const compatible = mesh.parent !== null && mesh.geometry === draw.geometry &&
+          sameMaterials(mesh.material, draw.material) && supported(this.matrix);
+        if (!compatible) {
+          mesh.layers.mask |= member.layers;
+          continue;
+        }
+        mesh.layers.mask &= ~member.layers;
+        if (!shown(mesh)) continue;
+        const offset = count * 16;
+        if (this.matrix.elements.some((value, i) => Math.fround(value) !== draw.instanceMatrix.array[offset + i])) {
+          draw.setMatrixAt(count, this.matrix);
+          changed = true;
+        }
+        count++;
+      }
+      changed ||= draw.count !== count || draw.boundingSphere === null;
+      draw.count = count;
+      if (changed) {
+        draw.instanceMatrix.needsUpdate = true;
+        draw.computeBoundingBox();
+        draw.computeBoundingSphere();
+      }
+    }
+  }
+
+  clear(): void {
+    for (const {draw, members} of this.batches) {
+      for (const {mesh, layers} of members) mesh.layers.mask |= layers;
+      draw.removeFromParent();
+      draw.dispose(); // releases instance attributes, never shared geometry/material
+    }
+    this.batches.length = 0;
+    this.eligible = 0;
+    this.excluded = {};
+  }
+
+  inspect() {
+    return {batches: this.batches.length, instances: this.batches.reduce((count, {draw}) => count + draw.count, 0),
+      eligible: this.eligible, excluded: {...this.excluded}};
+  }
+}

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

@@ -42,6 +42,7 @@ import {
   panCameraView,
 } from './blender-runtime-camera-view';
 import { DEFAULT_VIEWPORT_DISPLAY, workbenchMaterial } from './blender-workbench-material';
+import { BlenderRuntimeInstances } from './blender-runtime-instances';
 
 /** A saved `View3DShading.type` as the stage's draw mode: Material Preview is `preview`. */
 const SAVED_SHADING = {
@@ -640,6 +641,7 @@ export interface PhotographRecord {
 
 export class BlenderRuntimeView {
   readonly root = new THREE.Group();
+  private readonly instances = new BlenderRuntimeInstances(this.root);
   private readonly objects = new Map<string, THREE.Object3D>();
   private readonly meshes = new Map<
     string,
@@ -1034,11 +1036,17 @@ export class BlenderRuntimeView {
         for (const child of children) next.add(child);
         parent?.add(next);
         this.objects.set(id, next);
+        this.instances.rebuild(this.objects.values(), !this.rendered);
         return;
       }
   }
 
   constructor() {
+    const updateMatrixWorld = this.root.updateMatrixWorld.bind(this.root);
+    this.root.updateMatrixWorld = (force?: boolean) => {
+      updateMatrixWorld(force);
+      this.instances.sync();
+    };
     this.root.name = 'Model';
     // BLENDER IS Z-UP, THREE IS Y-UP: (x, y, z) -> (x, z, -y). Written as the
     // matrix rather than `rotation.x = -Math.PI / 2`, because that Euler is a
@@ -1212,6 +1220,7 @@ export class BlenderRuntimeView {
       material.dispose();
       this.workbenchMaterials.delete(key);
     }
+    this.instances.rebuild(this.objects.values(), !this.rendered);
   }
 
   private workbenchFor(id: string | null, side: THREE.Side, used: Set<string>): THREE.Material {
@@ -2007,6 +2016,7 @@ export class BlenderRuntimeView {
       active: this.frame?.active,
       mode: this.frame?.mode,
       geometryBuilds: this.geometryBuilds,
+      instancing: this.instances.inspect(),
       objects: [...this.objects].map(([id, object]) => ({
         id,
         name: object.name,
@@ -2017,6 +2027,10 @@ export class BlenderRuntimeView {
     };
   }
 
+  drawStatistics() {
+    return this.instances.inspect();
+  }
+
   snapshot() {
     return this.frame;
   }
@@ -2224,6 +2238,7 @@ export class BlenderRuntimeView {
   }
 
   private clear() {
+    this.instances.clear();
     for (const entry of this.staged?.meshes.values() ?? []) entry.geometry.dispose();
     this.staged = null;
     for (const light of this.lights.values()) {

package/package.json

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