@volter/blender-engine 0.1.66 → 0.1.68

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> {

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

@@ -1,4 +1,5 @@
 import * as THREE from 'three';
+import { graphDrawAttributes } from './blender-graph-material';
 
 // Small spatial batches retain frustum rejection without duplicating geometry.
 const BATCH_SIZE = 64;
@@ -11,7 +12,7 @@ function sameMaterials(a: THREE.Material | THREE.Material[], b: THREE.Material |
     : a === b;
 }
 
-function shown(object: THREE.Object3D): boolean {
+export function instanceObjectShown(object: THREE.Object3D): boolean {
   for (let node: THREE.Object3D | null = object; node; node = node.parent)
     if (!node.visible) return false;
   return true;
@@ -19,7 +20,7 @@ function shown(object: THREE.Object3D): boolean {
 
 /** 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 {
+export function instanceMatrixSupported(matrix: THREE.Matrix4): boolean {
   if (matrix.determinant() <= 0) return false;
   const e = matrix.elements;
   const x = Math.hypot(e[0]!, e[1]!, e[2]!);
@@ -42,6 +43,8 @@ export class BlenderRuntimeInstances {
   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) {}
 
@@ -49,21 +52,24 @@ export class BlenderRuntimeInstances {
     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 || (mesh as THREE.SkinnedMesh).isSkinnedMesh ||
+      if (!mesh.isMesh) continue;
+      if ((mesh as THREE.SkinnedMesh).isSkinnedMesh ||
           (mesh as THREE.InstancedMesh).isInstancedMesh || mesh.morphTargetInfluences ||
-          mesh.layers.mask !== 1) continue;
-      // WebGL2 guarantees sixteen vertex attributes; the instance matrix uses
-      // four. Keep richly attributed meshes on the ordinary path rather than
-      // dropping UV/colour channels or risking a refused shader.
-      if (Object.values(mesh.geometry.attributes).reduce((count, attribute) => count + Math.ceil(attribute.itemSize / 4), 0) > 12) continue;
+          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)) continue;
+          (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)) continue;
+      if (!instanceMatrixSupported(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);
@@ -98,7 +104,7 @@ export class BlenderRuntimeInstances {
         // 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);
+            if (mesh.layers.mask === 0 && instanceObjectShown(mesh)) mesh.raycast(raycaster, hits);
         };
         this.root.add(draw);
         draw.updateMatrixWorld(true);
@@ -124,13 +130,13 @@ export class BlenderRuntimeInstances {
         // 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);
+          sameMaterials(mesh.material, draw.material) && instanceMatrixSupported(this.matrix);
         if (!compatible) {
           mesh.layers.mask |= member.layers;
           continue;
         }
         mesh.layers.mask &= ~member.layers;
-        if (!shown(mesh)) continue;
+        if (!instanceObjectShown(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);
@@ -155,9 +161,12 @@ export class BlenderRuntimeInstances {
       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)};
+    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

@@ -43,6 +43,7 @@ import {
 } from './blender-runtime-camera-view';
 import { DEFAULT_VIEWPORT_DISPLAY, workbenchMaterial } from './blender-workbench-material';
 import { BlenderRuntimeInstances } from './blender-runtime-instances';
+import { BlenderTransparentInstances } from './blender-transparent-instances';
 
 /** A saved `View3DShading.type` as the stage's draw mode: Material Preview is `preview`. */
 const SAVED_SHADING = {
@@ -642,6 +643,7 @@ export interface PhotographRecord {
 export class BlenderRuntimeView {
   readonly root = new THREE.Group();
   private readonly instances = new BlenderRuntimeInstances(this.root);
+  private readonly transparentInstances = new BlenderTransparentInstances(this.root);
   private readonly objects = new Map<string, THREE.Object3D>();
   private readonly meshes = new Map<
     string,
@@ -1036,7 +1038,7 @@ 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);
+        this.rebuildInstances();
         return;
       }
   }
@@ -1220,7 +1222,26 @@ export class BlenderRuntimeView {
       material.dispose();
       this.workbenchMaterials.delete(key);
     }
+    this.rebuildInstances();
+  }
+
+  private rebuildInstances(): void {
+    this.transparentInstances.clear();
     this.instances.rebuild(this.objects.values(), !this.rendered);
+    if (!this.rendered) this.transparentInstances.setObjects(this.objects.values());
+  }
+
+  /** 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): () => void {
+    this.root.updateMatrixWorld(true);
+    try {
+      this.transparentInstances.prepare(camera);
+    } catch (error) {
+      this.transparentInstances.finishDraw();
+      throw error;
+    }
+    return () => this.transparentInstances.finishDraw();
   }
 
   private workbenchFor(id: string | null, side: THREE.Side, used: Set<string>): THREE.Material {
@@ -2016,7 +2037,7 @@ export class BlenderRuntimeView {
       active: this.frame?.active,
       mode: this.frame?.mode,
       geometryBuilds: this.geometryBuilds,
-      instancing: this.instances.inspect(),
+      instancing: this.drawStatistics(),
       objects: [...this.objects].map(([id, object]) => ({
         id,
         name: object.name,
@@ -2027,6 +2048,10 @@ export class BlenderRuntimeView {
     };
   }
 
+  drawStatistics() {
+    return {opaque: this.instances.inspect(), transparent: this.transparentInstances.inspect()};
+  }
+
   snapshot() {
     return this.frame;
   }
@@ -2234,6 +2259,7 @@ export class BlenderRuntimeView {
   }
 
   private clear() {
+    this.transparentInstances.clear();
     this.instances.clear();
     for (const entry of this.staged?.meshes.values() ?? []) entry.geometry.dispose();
     this.staged = null;

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

@@ -0,0 +1,184 @@
+import * as THREE from 'three';
+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; z: number; centre: THREE.Vector3};
+type Draw = {mesh: THREE.InstancedMesh; members: THREE.Mesh[]};
+
+/** Preserve Three's transparent object order. An instance run may contain only
+ * consecutive, compatible, single-pass surfaces in that order. Incompatible
+ * surfaces remain barriers; ties at a run boundary stay ordinary draws because
+ * Three breaks equal-depth ties by object id, and an internal batch has a new id.
+ * This does not turn blended foliage into cutouts or change its opacity. */
+export class BlenderTransparentInstances {
+  private objects: THREE.Mesh[] = [];
+  private readonly pools = new Map<string, Draw[]>();
+  private readonly hidden: THREE.Mesh[] = [];
+  private readonly inverse = new THREE.Matrix4();
+  private readonly matrix = new THREE.Matrix4();
+  private readonly projection = new THREE.Matrix4();
+  private readonly frustum = new THREE.Frustum();
+  private readonly centre = new THREE.Vector3();
+  private readonly depth = new THREE.Vector4();
+  private batches = 0;
+  private instances = 0;
+
+  constructor(private readonly root: THREE.Group) {}
+
+  setObjects(objects: Iterable<THREE.Object3D>): void {
+    this.clear();
+    this.objects = [...objects].filter((object): object is THREE.Mesh => (object as THREE.Mesh).isMesh === true);
+  }
+
+  prepare(camera: THREE.Camera): void {
+    for (const mesh of this.hidden) mesh.layers.enable(0);
+    this.hidden.length = 0;
+    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;
+    if (!this.objects.length) return;
+    camera.updateMatrixWorld();
+    this.projection.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+    this.frustum.setFromProjectionMatrix(this.projection);
+    this.inverse.copy(this.root.matrixWorld).invert();
+    const entries: Entry[] = [];
+    const eligibility = new Map<string, boolean>();
+    for (const mesh of this.objects) {
+      const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+      if (!materials.some(m => m.visible && m.transparent)) continue;
+      if (!instanceObjectShown(mesh) || !mesh.layers.test(camera.layers)) continue;
+      if (mesh.frustumCulled && !this.frustum.intersectsObject(mesh)) continue;
+      // Match WebGLRenderer.projectObject's sorting centre, including a skin's
+      // own sphere. Positions alone are not the centre of off-origin geometry.
+      const bounded = mesh as THREE.Mesh & {boundingSphere?: THREE.Sphere | null; computeBoundingSphere?: () => void};
+      if (bounded.boundingSphere !== undefined) {
+        if (bounded.boundingSphere === null) bounded.computeBoundingSphere?.();
+        this.centre.copy(bounded.boundingSphere!.center);
+      } else {
+        if (!mesh.geometry.boundingSphere) mesh.geometry.computeBoundingSphere();
+        this.centre.copy(mesh.geometry.boundingSphere!.center);
+      }
+      this.centre.applyMatrix4(mesh.matrixWorld);
+      const centre = this.centre.clone();
+      // WebGLRenderer sorts homogeneous clip z, before the perspective divide.
+      const z = this.depth.set(centre.x, centre.y, centre.z, 1).applyMatrix4(this.projection).z;
+      let material: THREE.Material | null = null;
+      let key: string | null = null;
+      const candidate = materials.length === 1 ? materials[0]! : null;
+      if (candidate && candidate.visible && candidate.transparent &&
+          !(candidate as THREE.ShaderMaterial).isShaderMaterial &&
+          !((candidate as THREE.MeshPhysicalMaterial).transmission > 0) &&
+          (candidate.side !== THREE.DoubleSide || candidate.forceSinglePass) &&
+          !(mesh as THREE.SkinnedMesh).isSkinnedMesh && !mesh.morphTargetInfluences &&
+          !(mesh as THREE.InstancedMesh).isInstancedMesh && mesh.layers.mask === 1) {
+        const geometry = mesh.geometry;
+        // A single material draws the whole geometry. An array does so only
+        // when its sole group covers the same range; preserve all other cases.
+        const count = geometry.index?.count ?? geometry.getAttribute('position').count;
+        const whole = !Array.isArray(mesh.material) || (geometry.groups.length === 1 &&
+          geometry.groups[0]!.start === 0 && geometry.groups[0]!.count === count &&
+          geometry.groups[0]!.materialIndex === 0);
+        const groupKey = `${geometry.id}:${candidate.uuid}:${mesh.renderOrder}`;
+        let fits = eligibility.get(groupKey);
+        if (fits === undefined) {
+          fits = graphDrawAttributes(candidate, geometry).size <= 12;
+          eligibility.set(groupKey, fits);
+        }
+        this.matrix.multiplyMatrices(this.inverse, mesh.matrixWorld);
+        if (whole && fits && instanceMatrixSupported(this.matrix)) {
+          material = candidate;
+          key = groupKey;
+        }
+      }
+      entries.push({mesh, material, key, z, centre});
+    }
+    entries.sort((a, b) => 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;) {
+      const first = entries[begin]!;
+      let end = begin + 1;
+      if (first.key !== null) while (end < entries.length && entries[end]!.key === first.key) end++;
+      const previous = entries[begin - 1];
+      const following = entries[end];
+      const tied = (previous?.z === first.z && previous.mesh.renderOrder === first.mesh.renderOrder) ||
+        (following?.z === entries[end - 1]!.z && following.mesh.renderOrder === first.mesh.renderOrder);
+      if (first.key !== null && end - begin >= 2 && !tied) {
+        // Equal-depth members may not straddle separate batches: their new
+        // object ids must never become the tie breaker. Keep such a run whole
+        // on the ordinary path if a capacity boundary would split a tie.
+        let safe = true;
+        for (let i = begin + CAPACITY; i < end; i += CAPACITY)
+          if (entries[i - 1]!.z === entries[i]!.z) safe = false;
+        if (safe) for (let offset = begin; offset < end; offset += CAPACITY) {
+          const length = Math.min(CAPACITY, end - offset);
+          if (length < 2) continue;
+          const head = entries[offset]!;
+          const index = used.get(first.key) ?? 0;
+          used.set(first.key, index + 1);
+          let pool = this.pools.get(first.key);
+          if (!pool) { pool = []; this.pools.set(first.key, pool); }
+          let draw = pool[index];
+          if (!draw) {
+            const mesh = new THREE.InstancedMesh(first.mesh.geometry, first.material!, CAPACITY);
+            mesh.name = 'Blender ordered transparency';
+            mesh.userData['engineInternal'] = true;
+            mesh.matrixAutoUpdate = false;
+            // Each member was culled above. The sphere is a sorting anchor,
+            // deliberately not an aggregate sphere that changes draw order.
+            mesh.frustumCulled = false;
+            mesh.boundingSphere = new THREE.Sphere();
+            mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+            draw = {mesh, members: []};
+            const held = draw;
+            mesh.raycast = (raycaster, hits) => {
+              if (!mesh.visible) return;
+              for (const member of held.members)
+                if (instanceObjectShown(member)) member.raycast(raycaster, hits);
+            };
+            pool.push(draw);
+            this.root.add(mesh);
+          }
+          draw.mesh.visible = true;
+          draw.mesh.renderOrder = head.mesh.renderOrder;
+          draw.mesh.boundingSphere!.center.copy(head.centre).applyMatrix4(this.inverse);
+          draw.mesh.updateMatrixWorld(true);
+          for (let i = 0; i < length; i++) {
+            const member = entries[offset + i]!.mesh;
+            this.matrix.multiplyMatrices(this.inverse, member.matrixWorld);
+            draw.mesh.setMatrixAt(i, this.matrix);
+            draw.members.push(member);
+            member.layers.disable(0);
+            this.hidden.push(member);
+          }
+          draw.mesh.count = length;
+          draw.mesh.instanceMatrix.needsUpdate = true;
+          this.batches++;
+          this.instances += length;
+        }
+      }
+      begin = end;
+    }
+  }
+
+  inspect() { return {batches: this.batches, instances: this.instances}; }
+
+  finishDraw(): void {
+    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;
+  }
+
+  clear(): void {
+    this.finishDraw();
+    for (const pool of this.pools.values()) for (const {mesh} of pool) {
+      mesh.removeFromParent();
+      mesh.dispose();
+    }
+    this.pools.clear();
+    this.objects = [];
+    this.batches = this.instances = 0;
+  }
+}

package/package.json

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