@volter/blender-engine 0.1.79 → 0.1.81

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

@@ -0,0 +1,139 @@
+import * as THREE from 'three';
+import {instanceMatrixSupported, instanceObjectShown} from './blender-runtime-instances';
+
+const CAPACITY = 64;
+const MAX_DRAWS = 1024; // At most 4 MiB of instance matrices; no vertex copies.
+
+/** Opaque depth overrides discard authored color materials. Geometry-compatible
+ * objects can share a draw here even when their color draws cannot be reordered.
+ * Only the current pass changes; selection layers and canonical meshes survive. */
+export class BlenderDepthInstances {
+  private objects: THREE.Mesh[] = [];
+  private readonly pools = new Map<THREE.BufferGeometry, THREE.InstancedMesh[]>();
+  private readonly hidden: {mesh: THREE.Mesh; mask: number}[] = [];
+  private readonly active: THREE.InstancedMesh[] = [];
+  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 allocated = 0;
+  private statistics = {batches: 0, instances: 0, preparationMs: 0};
+
+  constructor(private readonly root: THREE.Group) {}
+
+  supports(material: THREE.MeshDepthMaterial): boolean {
+    return material.isMeshDepthMaterial && material.visible && !material.transparent &&
+      !material.map && !material.alphaMap && !material.displacementMap &&
+      !material.alphaHash && material.alphaTest === 0 && !material.wireframe &&
+      !material.stencilWrite && material.depthWrite && material.depthTest &&
+      !material.clippingPlanes?.length && !material.polygonOffset &&
+      (material.depthFunc === THREE.LessDepth || material.depthFunc === THREE.LessEqualDepth) &&
+      (material.blending === THREE.NormalBlending || material.blending === THREE.NoBlending) &&
+      material.onBeforeCompile === THREE.Material.prototype.onBeforeCompile &&
+      material.onBeforeRender === THREE.Material.prototype.onBeforeRender;
+  }
+
+  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, material: THREE.MeshDepthMaterial): void {
+    this.finish();
+    const start = performance.now();
+    this.statistics = {batches: 0, instances: 0, preparationMs: 0};
+    if (!camera.layers.isEnabled(0)) return;
+    this.inverse.copy(this.root.matrixWorld).invert();
+    this.projection.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+    this.frustum.setFromProjectionMatrix(this.projection);
+    const groups = new Map<THREE.BufferGeometry, THREE.Mesh[]>();
+    for (const mesh of this.objects) {
+      // A selected object has a separate mask layer, and the outline pass also
+      // disables its default layer. Never pull it into the occluder draw.
+      if (mesh.layers.mask !== 1 || !instanceObjectShown(mesh) ||
+          (mesh as THREE.SkinnedMesh).isSkinnedMesh ||
+          (mesh as THREE.InstancedMesh).isInstancedMesh ||
+          (mesh as THREE.BatchedMesh).isBatchedMesh || mesh.morphTargetInfluences ||
+          mesh.onBeforeRender !== THREE.Object3D.prototype.onBeforeRender ||
+          mesh.onAfterRender !== THREE.Object3D.prototype.onAfterRender) continue;
+      const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+      if (materials.length !== 1 || !materials[0]?.visible) continue;
+      const geometry = mesh.geometry;
+      const count = geometry.index?.count ?? geometry.getAttribute('position')?.count ?? 0;
+      if (!count || (Array.isArray(mesh.material) && !(geometry.groups.length === 1 &&
+          geometry.groups[0]!.start === 0 && geometry.groups[0]!.count === count &&
+          geometry.groups[0]!.materialIndex === 0))) continue;
+      if (mesh.frustumCulled && !this.frustum.intersectsObject(mesh)) continue;
+      this.matrix.multiplyMatrices(this.inverse, mesh.matrixWorld);
+      if (!instanceMatrixSupported(this.matrix)) continue;
+      const group = groups.get(geometry);
+      if (group) group.push(mesh); else groups.set(geometry, [mesh]);
+    }
+    // Do not retain pools for obsolete LOD/canonical geometry indefinitely.
+    for (const [geometry, pool] of this.pools) if (!groups.has(geometry)) {
+      for (const draw of pool) { draw.removeFromParent(); draw.dispose(); this.allocated--; }
+      this.pools.delete(geometry);
+    }
+    for (const [geometry, members] of groups) {
+      if (members.length < 2) continue;
+      let pool = this.pools.get(geometry);
+      if (!pool) { pool = []; this.pools.set(geometry, pool); }
+      for (let offset = 0; offset < members.length; offset += CAPACITY) {
+        const count = Math.min(CAPACITY, members.length - offset);
+        if (count < 2) continue;
+        const slot = offset / CAPACITY;
+        let draw = pool[slot];
+        if (!draw) {
+          if (this.allocated >= MAX_DRAWS) continue;
+          draw = new THREE.InstancedMesh(geometry, material, CAPACITY);
+          draw.name = 'Blender depth instances';
+          draw.userData['engineInternal'] = true;
+          draw.matrixAutoUpdate = false;
+          draw.frustumCulled = false; // Members were individually culled above.
+          draw.boundingSphere = new THREE.Sphere();
+          draw.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+          draw.raycast = () => {};
+          this.root.add(draw);
+          pool.push(draw);
+          this.allocated++;
+        }
+        draw.material = material;
+        draw.matrixWorld.copy(this.root.matrixWorld);
+        draw.count = count;
+        draw.visible = true;
+        this.active.push(draw);
+        for (let i = 0; i < count; i++) {
+          const mesh = members[offset + i]!;
+          this.matrix.multiplyMatrices(this.inverse, mesh.matrixWorld);
+          draw.setMatrixAt(i, this.matrix);
+          this.hidden.push({mesh, mask: mesh.layers.mask});
+          mesh.layers.disable(0);
+        }
+        draw.instanceMatrix.needsUpdate = true;
+        this.statistics.batches++;
+        this.statistics.instances += count;
+      }
+    }
+    this.statistics.preparationMs = performance.now() - start;
+  }
+
+  finish(): void {
+    for (const {mesh, mask} of this.hidden) mesh.layers.mask = mask;
+    this.hidden.length = 0;
+    for (const draw of this.active) draw.visible = false;
+    this.active.length = 0;
+  }
+
+  clear(): void {
+    this.finish();
+    for (const pool of this.pools.values()) for (const draw of pool) {
+      draw.removeFromParent();
+      draw.dispose(); // Shared geometry and override material belong to callers.
+    }
+    this.pools.clear();
+    this.objects = [];
+    this.allocated = 0;
+  }
+
+  inspect() { return {...this.statistics, allocated: this.allocated}; }
+}

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

@@ -38,6 +38,9 @@ export class BlenderMotionGeometry {
   private readonly projection = new THREE.Matrix4();
   private readonly frustum = new THREE.Frustum();
   private readonly centre = new THREE.Vector3();
+  private readonly boxCentre = new THREE.Vector3();
+  private readonly halfExtent = new THREE.Vector3();
+  private readonly viewWorld = new THREE.Matrix4();
   private drawnMeshes = 0;
   private fullTriangles = 0;
   private motionTriangles = 0;
@@ -304,13 +307,19 @@ export class BlenderMotionGeometry {
     this.frustum.setFromProjectionMatrix(this.projection);
     let tooClose = 0;
     for (const [source, entry] of this.cache) {
+      // The copy carries the ORIGINAL bounds derived during its yielding
+      // build. Do not scan vertices or use the smaller simplified bounds.
+      const bounds = entry.geometry.boundingBox!;
+      bounds.getSize(this.halfExtent).multiplyScalar(0.5);
       for (const mesh of this.groups.get(source) ?? []) {
         if (!instanceObjectShown(mesh) || (mesh.frustumCulled && !this.frustum.intersectsObject(mesh))) continue;
         // 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;
+        // Bound in view space, also accounting for an explicitly scaled camera.
+        this.viewWorld.multiplyMatrices(camera.matrixWorldInverse, mesh.matrixWorld);
+        const e = this.viewWorld.elements;
         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;
@@ -319,9 +328,20 @@ export class BlenderMotionGeometry {
         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
-          ? -this.centre.z - sphere.radius * scale : 1;
+        this.centre.copy(sphere.center).applyMatrix4(this.viewWorld);
+        let depth = 1;
+        if ((camera as THREE.PerspectiveCamera).isPerspectiveCamera) {
+          const sphereDepth = -this.centre.z - sphere.radius * scale;
+          bounds.getCenter(this.boxCentre).applyMatrix4(this.viewWorld);
+          const v = this.viewWorld.elements;
+          const radiusZ = Math.abs(v[2]!) * this.halfExtent.x +
+            Math.abs(v[6]!) * this.halfExtent.y + Math.abs(v[10]!) * this.halfExtent.z;
+          // Both enclosures contain every original vertex. Their nearest
+          // depths are lower bounds, so the larger remains a lower bound.
+          // A tall shape's height need not inflate its radius toward a level
+          // camera. This tightens the bound without relaxing the pixel gate.
+          depth = Math.max(sphereDepth, -this.boxCentre.z - radiusZ);
+        }
         const pixels = entry.error * scale * Math.abs(camera.projectionMatrix.elements[5]!) * height / (2 * depth);
         if (!(depth > 0) || pixels > 1) { tooClose++; continue; }
         // Decide per placement: one near-camera blade must not veto thousands

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 { BlenderDepthInstances } from './blender-depth-instances';
 import { BlenderTransparentInstances } from './blender-transparent-instances';
 import { BlenderMaterialRanges } from './blender-material-ranges';
 import { BlenderMotionGeometry } from './blender-motion-geometry';
@@ -645,6 +646,7 @@ export interface PhotographRecord {
 export class BlenderRuntimeView {
   readonly root = new THREE.Group();
   private readonly instances = new BlenderRuntimeInstances(this.root);
+  private readonly depthInstances = new BlenderDepthInstances(this.root);
   private readonly materialRanges = new BlenderMaterialRanges();
   private readonly transparentInstances = new BlenderTransparentInstances(this.root);
   private readonly motionGeometry = new BlenderMotionGeometry(presenterChanged);
@@ -1231,6 +1233,7 @@ export class BlenderRuntimeView {
   }
 
   private rebuildInstances(): void {
+    this.depthInstances.setObjects(this.drawBatching && !this.rendered ? this.objects.values() : []);
     this.transparentInstances.clear();
     this.instances.rebuild(this.objects.values(), this.drawBatching && !this.rendered);
     if (this.drawBatching && !this.rendered) this.transparentInstances.setObjects(this.objects.values());
@@ -1289,6 +1292,15 @@ export class BlenderRuntimeView {
     };
   }
 
+  prepareDepthDraw(camera: THREE.Camera, material: THREE.MeshDepthMaterial): void | (() => void) {
+    if (!this.drawBatching || this.rendered || !this.depthInstances.supports(material)) return;
+    const resumeColor = this.transparentInstances.suspendDraw();
+    const restore = () => { try { this.depthInstances.finish(); } finally { resumeColor(); } };
+    try { this.depthInstances.prepare(camera, material); }
+    catch (error) { restore(); throw error; }
+    return restore;
+  }
+
   private workbenchFor(id: string | null, side: THREE.Side, used: Set<string>): THREE.Material {
     const display = (id !== null ? this.frame?.materials[id]?.viewport : undefined) ?? DEFAULT_VIEWPORT_DISPLAY;
     const key = `${display.color.join(',')}|${display.roughness}|${display.metallic}|${side}`;
@@ -2094,7 +2106,7 @@ export class BlenderRuntimeView {
   }
 
   drawStatistics() {
-    return {enabled: this.drawBatching, preparation: {...this.drawPreparation}, materialRanges: this.materialRanges.inspect(), opaque: this.instances.inspect(), transparent: this.transparentInstances.inspect(), motion: this.motionGeometry.inspect()};
+    return {enabled: this.drawBatching, preparation: {...this.drawPreparation}, depth: this.depthInstances.inspect(), materialRanges: this.materialRanges.inspect(), opaque: this.instances.inspect(), transparent: this.transparentInstances.inspect(), motion: this.motionGeometry.inspect()};
   }
 
   snapshot() {
@@ -2304,6 +2316,7 @@ export class BlenderRuntimeView {
   }
 
   private clear() {
+    this.depthInstances.clear();
     this.materialRanges.clear();
     this.motionGeometry.clear();
     this.transparentInstances.clear();

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

@@ -263,6 +263,11 @@ export class BlenderTransparentInstances {
     for (const n of this.root.matrixWorld.elements) this.observe(n);
     const observedGeometry = new Set<THREE.BufferGeometry>();
     for (const mesh of this.objects) {
+      // Check eligibility every frame, including opaque -> transparent
+      // transitions, but opaque geometry/attribute versions cannot affect a
+      // transparent draw plan. Large solid-only scenes need no such census.
+      const currentMaterials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+      if (!currentMaterials.some(material => material.visible && material.transparent)) continue;
       this.observe(mesh.parent?.id ?? -1);
       this.observe(instanceObjectShown(mesh) ? 1 : 0);
       this.observe(mesh.layers.mask);
@@ -313,6 +318,19 @@ export class BlenderTransparentInstances {
     this.observe((material as THREE.MeshPhysicalMaterial).transmission ?? 0);
   }
 
+  /** A plain depth override does not need color transparency ordering. Reveal
+   * only this plan's canonical members, retaining exact masks for restoration. */
+  suspendDraw(): () => void {
+    const members = this.hidden.map(mesh => ({mesh, mask: mesh.layers.mask}));
+    const draws = this.planned.map(({mesh}) => ({mesh, visible: mesh.visible}));
+    for (const {mesh} of members) mesh.layers.enable(0);
+    for (const {mesh} of draws) mesh.visible = false;
+    return () => {
+      for (const {mesh, mask} of members) mesh.layers.mask = mask;
+      for (const {mesh, visible} of draws) mesh.visible = visible;
+    };
+  }
+
   finishDraw(): void {
     for (const mesh of this.hidden) mesh.layers.enable(0);
     this.hidden.length = 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.79",
+  "version": "0.1.81",
   "publishConfig": {
     "access": "public"
   },