@needle-tools/usd 0.0.1-1d6bd1e

package/src/hydra/consoleRenderDelegate.js

@@ -0,0 +1,47 @@
+// This is a complete Hydra render delegate.
+// It doesn't do anything useful, but it logs out all the calls and arguments it receives. 
+export const delegate = {
+    createSPrim: (...args) => {
+        console.log("createSPrim", args);
+        return {
+        updateNode: (...args) => {
+            console.log("updateNode", args);
+        },
+        updateFinished: (...args) => {
+            console.log("updateFinished", args);
+        },
+        }
+    },
+    createRPrim: (...args) => {
+        console.log("createRPrim", args);
+        return {
+        setMaterial(...args) {
+            console.log("setMaterial", args);
+        },
+        updatePoints(...args) {
+            console.log("updatePoints", args);
+        },
+        updateIndices(...args) {
+            console.log("updateIndices", args);
+        },
+        updateNormals(...args) {
+            console.log("updateNormals", args);
+        },
+        setTransform(...args) {
+            console.log("setTransform", args);
+        },
+        updatePrimvar(...args) {
+            console.log("updatePrimvar", args);
+        },
+        skelDetected(...args) {
+            console.log("skelDetected", args);
+        },
+        setGeomSubsetMaterial(...args) {
+            console.log("setGeomSubsetMaterial", args);
+        },
+        }
+    },
+    CommitResources(...args) {
+        console.log("CommitResources", args);
+    },
+}

package/src/hydra/index.js

@@ -0,0 +1,5 @@
+import { ThreeRenderDelegateInterface } from "./ThreeJsRenderDelegate.js";
+import { delegate as ConsoleDelegate } from "./consoleRenderDelegate.js";
+
+export { ThreeRenderDelegateInterface as threeJsRenderDelegate };
+export { ConsoleDelegate as consoleRenderDelegate }

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from "./types";

package/src/index.js

@@ -0,0 +1,5 @@
+export * from "./bindings/index.js";
+export * from "./hydra/index.js";
+export * from "./create.three.js";
+export * from "./vite/index.js";
+export { tryDetermineFileFormat } from "./utils.js"

package/src/plugins/index.js

@@ -0,0 +1,2 @@
+export { addPluginForNeedleEngine } from "./needle.js";
+

package/src/plugins/needle.js

@@ -0,0 +1,158 @@
+import { Loader, Object3D } from "three";
+import { createThreeHydra, getUsdModule } from "../index.js";
+
+
+/** @type {import("../types").addPluginForNeedleEngine} */
+export async function addPluginForNeedleEngine(options) {
+    if (options.debug) console.debug("🐉 Adding USDZ plugin to Needle Engine");
+    return import("@needle-tools/engine").then(module => {
+        return onAddNeedlePlugin(module, options);
+    })
+}
+
+
+/**
+ * @param {typeof import("@needle-tools/engine")} NEEDLE
+ * @param {import("../types").PluginContext} opts
+ */
+function onAddNeedlePlugin(NEEDLE, opts) {
+
+    class NeedleUSDZHHandler extends NEEDLE.Behaviour {
+        constructor() {
+            super();
+            /**
+             * @type {import("..").NeedleThreeHydraHandle | null}
+             */
+            this.handle = null;
+            this.root = new Object3D();
+        }
+
+        update() {
+            if (this.handle) {
+                this.handle.update(this.context.time.deltaTime);
+            }
+        }
+        onDestroy() {
+            if (this.handle) {
+                this.handle.dispose();
+                this.handle = null;
+            }
+        }
+    }
+
+
+    /**
+     * Needle USDZ Loader
+     * @extends {Loader<Object3D>}
+     */
+    class NeedleUSDZLoader extends Loader {
+
+        /**
+         * the usd module promise - initialized when the first loader is created
+         * @type {Promise<import("../types").USD> | null}
+         * @private
+         * @static
+         */
+        static usdModule = null;
+
+        // LOADER IMPL:
+
+        /**
+         * @param {NeedleUSDZHHandler} comp
+         */
+        constructor(comp) {
+            super();
+            this.comp = comp;
+        }
+
+        /**
+         * @type {Loader<Object3D>["loadAsync"]}
+         */
+        async loadAsync(url, onProgress) {
+
+            const debug = opts.debug || false;;
+
+            onProgress?.(new ProgressEvent("load", { lengthComputable: false, loaded: 0, total: 0 }));
+
+            // Get the files immediately (don't wait for the USD module to be loaded)
+            const files = opts.getFiles();
+
+            NeedleUSDZLoader.usdModule ??= getUsdModule({
+                debug
+                // setURLModifier: USDLoadingManager.urlModifier,
+            }).then(res => {
+                if (debug) console.debug("🐉 USD HYDRA IS READY");
+                return res;
+            })
+            const usd = await NeedleUSDZLoader.usdModule;
+
+            onProgress?.(new ProgressEvent("load", { lengthComputable: true, loaded: .5, total: 1 }));
+
+            // Load hydra
+            const handle = await createThreeHydra({
+                debug,
+                USD: usd,
+                scene: this.comp.root,
+                url: url,
+                files: files,
+            });
+            this.comp.handle = handle;
+
+            if (debug) console.debug("Loaded", this.comp);
+
+            onProgress?.(new ProgressEvent("load", { lengthComputable: true, loaded: 1, total: 1 }));
+
+            return this.comp.root;
+        }
+
+        parse() {
+            console.error("🐉 USDZ LOADER PARSE CALLED: Not implemented");
+            return this.comp.root;
+        }
+    }
+
+
+
+
+
+    const removeFiletype = NEEDLE.NeedleEngineModelLoader.onDetermineModelMimetype(cb => {
+
+        if (cb.contentType === "application/vnd.usd") {
+            return "model/vnd.usd";
+        }
+        const ext = cb.url.split('.').pop()?.toLowerCase();
+        switch (ext) {
+            case "usdz":
+                return "model/vnd.usdz+zip"
+            case "usda":
+                return "model/vnd.usda"
+            case "usdc":
+                return "model/vnd.usdc"
+            case "usd":
+                return "model/vnd.usd"
+        }
+        return null;
+    });
+
+    const handlers = new Array();
+    const removeCustomLoader = NEEDLE.NeedleEngineModelLoader.onCreateCustomModelLoader(cb => {
+        if (cb.mimetype.startsWith("model/vnd.usd")) {
+            const handler = new NeedleUSDZHHandler();
+            handlers.push(handler);
+            NEEDLE.addComponent(cb.context.scene, handler);
+            return new NeedleUSDZLoader(handler);
+        }
+        return null;
+    });
+
+
+    return () => {
+        removeFiletype();
+        removeCustomLoader();
+        for (const handler of handlers) {
+            handler.destroy();
+        }
+        handlers.length = 0;
+    }
+
+}

package/src/types/bindings.d.ts

@@ -0,0 +1,82 @@
+
+declare type FSNode = {
+    contents: ArrayLike,
+    id: number,
+    mode: number,
+    name: string,
+    timestamp: number,
+    isFolder: boolean,
+    isDevice: boolean,
+    read: boolean,
+    write: boolean,
+}
+
+declare type USD = {
+    FS_createDataFile: (parent: string, filepath: string, data: Uint8Array, canRead: boolean, canWrite: boolean, canOwn: boolean) => FSNode,
+    FS_createPath: (parent: string, path: string, canRead: boolean, canWrite: boolean) => FSNode,
+    FS_unlink: (path: string) => void,
+    FS_readdir: (path: string) => string[],
+    FS_rmdir: (path: string) => void,
+    FS_analyzePath: (path: string) => FSNode,
+    HdWebSyncDriver: new (delegate: hydraDelegate, filepath: string) => HdWebSyncDriver,
+    flushPendingDeletes: () => void,
+    ready: Promise<any>,
+    debug: boolean;
+    calledRun: boolean;
+    stderr: any;
+    stdin: any;
+    stdout: any;
+};
+
+declare type USDStage = {
+    GetStartTimeCode(): number,
+    GetEndTimeCode(): number,
+    GetTimeCodesPerSecond(): number,
+    GetUpAxis(): number,
+}
+
+declare type HdWebSyncDriver = {
+    getFile: (path: string, cb: (loadedFile: ArrayBufferLike) => void) => void,
+    GetStage: () => USDStage,
+    SetTime(timecode: number): void,
+    GetTime(): number,
+    Draw(): void,
+
+    /** ??? */
+    clone(): HdWebSyncDriver,
+    /** ??? */
+    delete(): void,
+    /** ??? */
+    deleteLater(): void,
+    isDeleted(): boolean,
+    /** ??? */
+    isAliasOf(): boolean,
+}
+
+export type GetUsdModuleOptions = {
+    debug?: boolean,
+    mainScriptUrlOrBlob?: string,
+    wasmBinary?: ArrayBufferLike,
+    locateFile?: (path: string) => string,
+    getPreloadedPackage?: (file: string, size: number) => ArrayBuffer | null,
+    setStatus?: (status: string) => void,
+    onDownloadProgress?: (downloaded: number, total: number) => void,
+    /** Returns a transferable object that can be resolved to an ArrayBuffer, 
+     *  or an URL that can be fetched to get an ArrayBuffer.
+    */
+    urlModifier?: (url: string) =>
+        Promise<
+            ArrayBuffer | File | FileSystemFileHandle | FileSystemFileEntry | string
+        > | ArrayBuffer | File | FileSystemFileHandle | FileSystemFileEntry | string,
+}
+
+/**
+ * Loads the USD Module.
+ * @example
+ * ```javascript
+ * getUsdModule({ mainScriptUrlOrBlob: "/emHdBindings.js" }).then(USD => { ... })
+ * ```
+ */
+export function getUsdModule(opts?: GetUsdModuleOptions): Promise<USD>;
+
+export type USDRoot = {}

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

@@ -0,0 +1,65 @@
+import { Scene } from "three"
+import { HdWebSyncDriver, USD } from ".."
+
+export declare type HydraFile = File & { path: string };
+
+export declare type createThreeHydraConfig = {
+
+    debug?: boolean,
+
+    /**
+     *  USD Module
+     * @example 
+     * ```javascript
+     * getUsdModule({
+     *  mainScriptUrlOrBlob: "/emHdBindings.js"
+     * }).then(USD => { ... })
+     * ```
+     */
+    USD: USD,
+
+    /**
+     * Optional buffer of the usdz file
+     */
+    buffer?: ArrayBuffer,
+
+    url?: string,
+
+    /**
+     * The scene to be loaded as the root of the USD stage.
+     */
+    scene: Object3D,
+
+    /**
+     * Files to be loaded into the virtual file system.
+     * The first file will be loaded as the root file, others will be loaded as dependencies.
+     */
+    files: Array<HydraFile>,
+}
+
+/**
+ * Use the hydra handle to update the usd scene periodically.
+ */
+export declare type NeedleThreeHydraHandle = {
+    /** The hydra driver
+    */
+    driver: HdWebSyncDriver,
+    /** Call update periodically to update the usd scene.
+     * @param dt The delta time since the last update.
+     */
+    update: (dt: number) => void,
+    /** Call this to update the usd scene immediately.
+     * @param dt The delta time since the last update.
+     */
+    dispose: () => void,
+}
+
+export declare class USDLoadingManager {
+    static setURLModifier(callback: (url: string) => string): void;
+    static urlModifier: (url: string) => string;
+}
+
+/**
+ * Creates a new three.js hydra handle.
+ */
+export function createThreeHydra(config: createThreeHydraConfig): Promise<NeedleThreeHydraHandle>

package/src/types/hydra.d.ts

@@ -0,0 +1,32 @@
+import { Object3D, Texture } from 'three';
+import { HdWebSyncDriver } from './bindings';
+
+export class hydraDelegate { }
+
+
+
+
+
+
+export const consoleRenderDelegate: hydraDelegate = {}
+
+
+
+
+
+
+export type threeJsRenderDelegateConfig = {
+    driver: () => HdWebSyncDriver,
+    usdRoot: Object3D,
+    /** Paths for resolving textures */
+    paths?: string[],
+    /** @deprecated */
+    envMap?: Texture,
+}
+export class threeJsRenderDelegate extends hydraDelegate {
+    constructor(path: string, config: threeJsRenderDelegateConfig)
+}
+
+
+
+

package/src/types/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./bindings"
+export * from "./hydra"
+export * from "./create.three"
+export * from "./vite";
+export * from "./plugins"

package/src/types/plugins.d.ts

@@ -0,0 +1,9 @@
+
+
+export type PluginContext = {
+    debug?: boolean,
+    getFiles: () => Array<import("../types").HydraFile>
+}
+
+
+export declare function addPluginForNeedleEngine(options: PluginContext): Promise<(() => void)>;

package/src/types/vite.d.ts

@@ -0,0 +1,19 @@
+import { Plugin } from "vite";
+
+
+/**
+ * Enable USD WASM support for vite based applications.
+ * @example sveltekit
+ * ```ts
+ * import { needleUSD } from '@needle-tools/usd';
+ * export default defineConfig(async ({ command }) => {
+ *     return {
+ *        plugins: [
+ *           ...needleUSD(),
+ *           sveltekit(),
+ *       ],
+ *    }
+ * });
+ * ```
+ */
+export declare function needleUSD(): Array<Plugin>;

package/src/utils.js

@@ -0,0 +1,24 @@
+
+
+/**
+ * @param {ArrayBuffer} buffer
+ * @returns {"usdz" | "usd" | "usda" | "unknown"}
+ */
+export function tryDetermineFileFormat(buffer) {
+
+    const bytes = new Uint8Array(buffer, 0, 16);
+
+    // USDZ
+    if (bytes[0] == 80 && bytes[1] == 75 && bytes[2] == 3 && bytes[3] == 4) {
+        return "usdz";
+    }
+    // USD
+    if (bytes[0] == 80 && bytes[1] == 88 && bytes[2] == 82 && bytes[3] == 45 && bytes[4] == 85 && bytes[5] == 83 && bytes[6] == 68 && bytes[7] == 67) {
+        return "usd";
+    }
+    if (bytes[0] === 35 && bytes[1] === 117 && bytes[2] === 115 && bytes[3] === 100) {
+        return "usda";
+    }
+
+    return "unknown";
+}

package/src/vite/index.js

@@ -0,0 +1,22 @@
+
+/** @type {import('vite').Plugin} */
+const crossOriginIsolatedPlugin = {
+    name: 'needle:usd-crossoriginisolated',
+    configureServer: (server) => {
+        server.middlewares.use((_req, res, next) => {
+            res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+            res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+            next();
+        });
+    }
+};
+
+
+/**
+ * Needle USD plugin for vite. 
+ * This plugin sets the Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers
+ * @returns {Array<import('vite').Plugin>} plugins
+ */
+export function needleUSD() {
+    return [crossOriginIsolatedPlugin]
+}