@needle-tools/usd 1.0.0-next.d536d99 → 1.0.0

package/src/bindings/openusd-build-info.json

@@ -3,7 +3,7 @@
   "openusd": {
     "version": "0.26.5",
     "pxrVersion": 2605,
-    "gitSha": "091e1c02196d7bbda8b536ec745b36824da71589",
+    "gitSha": "9f211a656877c26b39e8170f9ed53810094254d5",
     "gitDirty": false
   },
   "toolchain": {

package/src/create.three.js

@@ -349,6 +349,9 @@ export async function createThreeHydra(config) {
 
     /** Draw once, after stage metadata has been applied to the root scene. */
     const initialDrawPromise = draw();
+    const readyPromise = config.waitForMaterials
+        ? initialDrawPromise.then(() => renderInterface.waitForMaterialsReady())
+        : initialDrawPromise;
 
     let time = 0;
     let currentTimeCode = stageStartTimeCode;
@@ -383,7 +386,7 @@ export async function createThreeHydra(config) {
 
     return {
         driver: /** @type {import(".").HdWebSyncDriver} */ (driverOrPromise),
-        ready: () => initialDrawPromise,
+        ready: () => readyPromise,
         update: (dt) => {
             // ensure we're not dead
             if (driver.isDeleted()) {
@@ -394,6 +397,9 @@ export async function createThreeHydra(config) {
                 }
                 return;
             }
+            if (drawInFlight || editInFlight) {
+                return;
+            }
             if (playing) {
                 time += dt;
                 const startTimeCode = stageStartTimeCode;

package/src/hydra/ThreeJsRenderDelegate.js

@@ -6,6 +6,8 @@ const {
   TextureLoader,
   BufferGeometry,
   MeshPhysicalMaterial,
+  FrontSide,
+  BackSide,
   DoubleSide,
   Color,
   Mesh,
@@ -80,6 +82,31 @@ function disposeObjectResources(object) {
   object.parent?.remove(object);
 }
 
+function isFiniteArray(values, dimension = 3) {
+  if (!values || values.length === 0 || values.length % dimension !== 0) return false;
+  for (let i = 0; i < values.length; i++) {
+    if (!Number.isFinite(values[i])) return false;
+  }
+  return true;
+}
+
+function cullStyleToThreeSide(doubleSided, cullStyle) {
+  switch (cullStyle) {
+    case "nothing":
+      return DoubleSide;
+    case "back":
+      return FrontSide;
+    case "front":
+      return BackSide;
+    case "frontUnlessDoubleSided":
+      return doubleSided ? DoubleSide : BackSide;
+    case "backUnlessDoubleSided":
+    case "dontCare":
+    default:
+      return doubleSided ? DoubleSide : FrontSide;
+  }
+}
+
 function primNameFromPath(id, fallback) {
   const path = String(id || "");
   const slash = path.lastIndexOf("/");
@@ -258,8 +285,6 @@ class TextureRegistry {
     } else if (extension === 'jpeg') {
       filetype = 'image/jpeg';
     } else if (extension === 'exr') {
-      console.warn("EXR textures are not fully supported yet", resourcePath);
-      // using EXRLoader explicitly
       filetype = 'image/x-exr';
     } else if (extension === 'tga') {
       console.warn("TGA textures are not fully supported yet", resourcePath);
@@ -527,6 +552,8 @@ class HydraMesh {
     this._uvs = undefined;
     this._indices = undefined;
     this._materials = [];
+    this._materialSideClones = new Map();
+    this._side = DoubleSide;
     this._visible = false;
     this._renderTag = 'geometry';
     this._instancedMesh = null;
@@ -540,6 +567,7 @@ class HydraMesh {
     this._ownedMaterial = material;
     this._materials.push(material);
     this._mesh = new Mesh(this._geometry, material);
+    this._installMeshHooks(this._mesh);
     this._mesh.visible = false;
     this._mesh.castShadow = true;
     this._mesh.receiveShadow = true;
@@ -561,6 +589,7 @@ class HydraMesh {
     if (!this._mesh) return;
     this._interface.unassignMeshFromMaterials(this._mesh);
     this._disposeInstancedMesh();
+    this._disposeMaterialSideClones();
     if (this._mesh.parent) {
       this._mesh.parent.remove(this._mesh);
     }
@@ -573,13 +602,25 @@ class HydraMesh {
   updateOrder(attribute, attributeName, dimension = 3) {
     if (debugMeshes) console.log("updateOrder", attribute, attributeName, dimension);
     if (attribute && this._indices) {
+      if (!isFiniteArray(attribute, dimension)) {
+        this._geometry.deleteAttribute(attributeName);
+        return;
+      }
       let values = [];
       for (let i = 0; i < this._indices.length; i++) {
         let index = this._indices[i]
+        if (!Number.isInteger(index) || index < 0 || (dimension * index + dimension) > attribute.length) {
+          this._geometry.deleteAttribute(attributeName);
+          return;
+        }
         for (let j = 0; j < dimension; ++j) {
           values.push(attribute[dimension * index + j]);
         }
       }
+      if (!isFiniteArray(values, dimension)) {
+        this._geometry.deleteAttribute(attributeName);
+        return;
+      }
       this._geometry.setAttribute(attributeName, new Float32BufferAttribute(values, dimension));
       if (attributeName === 'position') {
         this._geometry.computeBoundingBox();
@@ -628,6 +669,7 @@ class HydraMesh {
     if (!this._instancedMesh || this._instancedMesh.count !== instanceCount) {
       this._disposeInstancedMesh();
       this._instancedMesh = new InstancedMesh(this._geometry, this._mesh.material, instanceCount);
+      this._installMeshHooks(this._instancedMesh);
       this._instancedMesh.name = `${this._mesh.name}_instances`;
       this._instancedMesh.castShadow = this._mesh.castShadow;
       this._instancedMesh.receiveShadow = this._mesh.receiveShadow;
@@ -662,6 +704,78 @@ class HydraMesh {
     this._instancedMesh = null;
   }
 
+  _installMeshHooks(mesh) {
+    mesh.userData.usdPath = this._id;
+    mesh.userData.usdHydraMaterialSide = this._side;
+    mesh.userData.usdHydraApplyMaterialSide = (material, hydraMaterial) => this._applyMaterialSide(material, hydraMaterial);
+  }
+
+  _disposeMaterialSideClones() {
+    for (const material of this._materialSideClones.values()) {
+      material.dispose?.();
+    }
+    this._materialSideClones.clear();
+  }
+
+  _updateMeshSideState() {
+    if (this._mesh) {
+      this._mesh.userData.usdHydraMaterialSide = this._side;
+    }
+    if (this._instancedMesh) {
+      this._instancedMesh.userData.usdHydraMaterialSide = this._side;
+    }
+  }
+
+  _applyMaterialSide(material, hydraMaterial = null) {
+    if (!material) return material;
+    if (Array.isArray(material)) {
+      return material.map(entry => this._applyMaterialSide(entry, hydraMaterial));
+    }
+    if (material === this._ownedMaterial || material.userData?.usdHydraMeshOwner === this._id) {
+      material.side = this._side;
+      material.needsUpdate = true;
+      return material;
+    }
+
+    if (!hydraMaterial?.requiresMaterialSideVariants?.()) {
+      material.side = this._side;
+      material.needsUpdate = true;
+      return material;
+    }
+
+    let clone = this._materialSideClones.get(material);
+    if (!clone) {
+      clone = material.clone();
+      clone.userData.usdHydraSideCloneOf = material.uuid;
+      this._materialSideClones.set(material, clone);
+    } else {
+      clone.copy(material);
+      clone.userData.usdHydraSideCloneOf = material.uuid;
+    }
+    clone.side = this._side;
+    clone.needsUpdate = true;
+    return clone;
+  }
+
+  _applyCullSideToMeshes() {
+    this._updateMeshSideState();
+    let refreshedMaterialAssignments = false;
+    if (this._mesh) {
+      refreshedMaterialAssignments = this._interface.refreshMeshMaterialAssignments(this._mesh);
+      if (!refreshedMaterialAssignments) {
+        this._mesh.material = this._applyMaterialSide(this._mesh.material);
+      }
+    }
+    if (this._instancedMesh) {
+      this._instancedMesh.material = this._mesh?.material;
+    }
+  }
+
+  setCullStyle(doubleSided, cullStyle) {
+    this._side = cullStyleToThreeSide(Boolean(doubleSided), String(cullStyle || "dontCare"));
+    this._applyCullSideToMeshes();
+  }
+
   setVisibilityState(visible, renderTag = 'geometry') {
     this._visible = Boolean(visible);
     this._renderTag = String(renderTag || 'geometry');
@@ -687,12 +801,20 @@ class HydraMesh {
     this.updateOrder(this._normals, 'normal');
   }
 
+  updateOrderedNormals(normals) {
+    // don't apply automatically generated normals if there are already authored normals.
+    if (this._geometry.hasAttribute('normal')) return;
+
+    this._normals = normals.slice(0);
+    this._geometry.setAttribute('normal', new Float32BufferAttribute(this._normals, 3));
+  }
+
   setNormals(data, interpolation) {
     if (interpolation === 'facevarying') {
       // The UV buffer has already been prepared on the C++ side, so we just set it
       this._geometry.setAttribute('normal', new Float32BufferAttribute(data, 3));
-    } else if (interpolation === 'vertex') {
-      // We have per-vertex UVs, so we need to sort them accordingly
+    } else if (interpolation === 'vertex' || interpolation === 'varying') {
+      // Per-point data is sorted into the expanded triangle order.
       this._normals = data.slice(0);
       this.updateOrder(this._normals, 'normal');
     }
@@ -701,7 +823,7 @@ class HydraMesh {
   setTangents(data, dimension, interpolation) {
     if (interpolation === 'facevarying') {
       this._geometry.setAttribute('tangent', new Float32BufferAttribute(data, dimension));
-    } else if (interpolation === 'vertex') {
+    } else if (interpolation === 'vertex' || interpolation === 'varying') {
       this._tangents = data.slice(0);
       this.updateOrder(this._tangents, 'tangent', dimension);
     }
@@ -735,7 +857,9 @@ class HydraMesh {
       this._mesh.parent.remove(this._mesh);
     }
     this._mesh = new Mesh(this._geometry, this._materials);
+    this._installMeshHooks(this._mesh);
     this.setVisibilityState(this._visible, this._renderTag);
+    this._applyCullSideToMeshes();
     this._interface.config.usdRoot.add(this._mesh);
 
     for (let i = 0; i < sections.length; i++) {
@@ -750,14 +874,16 @@ class HydraMesh {
     let wasDefaultMaterial = false;
     if (this._mesh.material === defaultMaterial) {
       this._mesh.material = this._mesh.material.clone();
+      this._mesh.material.userData.usdHydraMeshOwner = this._id;
       wasDefaultMaterial = true;
     }
+    this._mesh.material = this._applyMaterialSide(this._mesh.material);
 
     this._colors = null;
 
     if (interpolation === 'constant') {
       this._mesh.material.color = new Color().fromArray(data);
-    } else if (interpolation === 'vertex') {
+    } else if (interpolation === 'vertex' || interpolation === 'varying') {
       // Per-vertex buffer attribute
       this._mesh.material.vertexColors = true;
       if (wasDefaultMaterial) {
@@ -784,8 +910,8 @@ class HydraMesh {
     if (interpolation === 'facevarying') {
       // The UV buffer has already been prepared on the C++ side, so we just set it
       this._geometry.setAttribute('uv', new Float32BufferAttribute(data, dimension));
-    } else if (interpolation === 'vertex') {
-      // We have per-vertex UVs, so we need to sort them accordingly
+    } else if (interpolation === 'vertex' || interpolation === 'varying') {
+      // Per-point data is sorted into the expanded triangle order.
       this._uvs = data.slice(0);
       this.updateOrder(this._uvs, 'uv', 2);
     }
@@ -937,11 +1063,15 @@ class HydraMaterial {
     if (!existing) {
       this._assignments.push({ mesh, materialIndex });
     }
-    this._applyMaterialToMesh(mesh, materialIndex);
+    this._applyMaterialToAssignedMeshes();
   }
 
   unassignMesh(mesh) {
+    const previousLength = this._assignments.length;
     this._assignments = this._assignments.filter(assignment => assignment.mesh !== mesh);
+    if (this._assignments.length !== previousLength) {
+      this._applyMaterialToAssignedMeshes();
+    }
   }
 
   dispose() {
@@ -951,17 +1081,22 @@ class HydraMaterial {
   }
 
   _applyMaterialToMesh(mesh, materialIndex) {
+    const applyMaterialSide = mesh.userData?.usdHydraApplyMaterialSide;
+    const material = typeof applyMaterialSide === 'function'
+      ? applyMaterialSide(this._material, this)
+      : this._material;
+
     if (materialIndex === null || materialIndex === undefined) {
-      mesh.material = this._material;
+      mesh.material = material;
       return;
     }
 
     if (Array.isArray(mesh.material)) {
-      mesh.material[materialIndex] = this._material;
+      mesh.material[materialIndex] = material;
       return;
     }
 
-    mesh.material = this._material;
+    mesh.material = material;
   }
 
   _applyMaterialToAssignedMeshes() {
@@ -970,6 +1105,28 @@ class HydraMaterial {
     }
   }
 
+  hasMeshAssignment(mesh) {
+    return this._assignments.some(assignment => assignment.mesh === mesh);
+  }
+
+  requiresMaterialSideVariants() {
+    const sides = new Set();
+    for (const assignment of this._assignments) {
+      const side = assignment.mesh?.userData?.usdHydraMaterialSide;
+      if (typeof side === 'number') {
+        sides.add(side);
+      }
+      if (sides.size > 1) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  refreshAssignments() {
+    this._applyMaterialToAssignedMeshes();
+  }
+
   beginMaterialSync() {
     this._nodes = {};
     this._resolvedAssetPaths.clear();
@@ -1749,6 +1906,16 @@ export class ThreeRenderDelegateInterface {
     }
   }
 
+  refreshMeshMaterialAssignments(mesh) {
+    let refreshed = false;
+    for (const material of Object.values(this.materials)) {
+      if (!material.hasMeshAssignment(mesh)) continue;
+      material.refreshAssignments();
+      refreshed = true;
+    }
+    return refreshed;
+  }
+
   CommitResources() {
     for (const id in this.meshes) {
       const hydraMesh = this.meshes[id]

package/src/plugins/needle.js

@@ -129,6 +129,7 @@ function onAddNeedlePlugin(NEEDLE, opts) {
                 scene: this.comp.root,
                 url: url,
                 files: files,
+                waitForMaterials: opts.waitForMaterials,
             });
             this.comp.handle = handle;
             hydraHandlesByRoot.set(this.comp.root, handle);

package/src/types/create.three.d.ts

@@ -71,6 +71,13 @@ export declare type createThreeHydraConfig = {
      * only controls the helper/demo Three light brightness.
      */
     scenePrimitiveLightIntensityScale?: number,
+
+    /**
+     * Include asynchronous material generation and texture assignment in ready().
+     * Defaults to false so stage loading and first draw are not blocked by materials.
+     * Call handle.materialsReady() when you need an explicit material barrier.
+     */
+    waitForMaterials?: boolean,
 }
 
 /**
@@ -109,6 +116,8 @@ export declare type NeedleThreeHydraHandle = {
      */
     editStage: <T>(callback: (stage: USDStage, driver: HdWebSyncDriver) => T | Promise<T>) => Promise<T | undefined>,
     /** Resolves after the initial Hydra draw has settled.
+     * If createThreeHydra was called with waitForMaterials, also waits for
+     * asynchronous material generation and texture assignment.
      */
     ready: () => Promise<void>,
     /** Resolves when asynchronous material generation and texture assignment have settled.

package/src/types/plugins.d.ts

@@ -2,6 +2,11 @@
 
 export type PluginContext = {
     debug?: boolean,
+    /**
+     * Include asynchronous material generation and texture assignment in the
+     * Hydra handle's ready() promise. Defaults to false.
+     */
+    waitForMaterials?: boolean,
     getFiles: () => Array<import("../types").HydraFile>
 }
 

package/src/vite/index.js

@@ -1,7 +1,19 @@
+const packageRoot = decodeURIComponent(new URL('../..', import.meta.url).pathname);
 
 /** @type {import('vite').Plugin} */
 const crossOriginIsolatedPlugin = {
     name: 'needle:usd-crossoriginisolated',
+    config: (config) => {
+        const cwd = typeof process !== 'undefined' && process.cwd ? process.cwd() : '/';
+        const allow = config.server?.fs?.allow ?? [cwd];
+        return {
+            server: {
+                fs: {
+                    allow: [...new Set([...allow, packageRoot])],
+                },
+            },
+        };
+    },
     configureServer: (server) => {
         server.middlewares.use((_req, res, next) => {
             res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
@@ -19,4 +31,4 @@ const crossOriginIsolatedPlugin = {
  */
 export function needleUSD() {
     return [crossOriginIsolatedPlugin]
-}
+}