@needle-tools/engine 4.4.6 → 4.5.0-alpha

package/lib/engine/webcomponents/needle-engine.ar-overlay.js

@@ -0,0 +1,167 @@
+import { DeviceUtilities, getParam } from "../engine_utils.js";
+const debug = getParam("debugoverlay");
+export const arContainerClassName = "ar";
+export const quitARClassName = "quit-ar";
+// https://developers.google.com/web/fundamentals/web-components/customelements
+/** @internal */
+export class AROverlayHandler {
+    get ARContainer() { return this.arContainer; }
+    arContainer = null;
+    currentSession = null;
+    _createdAROnlyElements = [];
+    _reparentedObjects = [];
+    contentElement = null;
+    originalDomOverlayParent = null;
+    requestEndAR = () => {
+        this.onRequestedEndAR();
+    };
+    onBegin(context, overlayContainer, session) {
+        this.currentSession = session;
+        this.arContainer = overlayContainer;
+        if (DeviceUtilities.isMozillaXR()) {
+            const arElements = context.domElement.children;
+            for (let i = 0; i < arElements?.length; i++) {
+                const el = arElements[i];
+                if (!el)
+                    return;
+                if (el === this.arContainer)
+                    return;
+                this._reparentedObjects.push({ el: el, previousParent: el.parentElement });
+                this.arContainer?.appendChild(el);
+            }
+            if (overlayContainer) {
+                this.originalDomOverlayParent = overlayContainer.parentNode;
+                if (this.originalDomOverlayParent) {
+                    console.log("Reparent DOM Overlay to body", overlayContainer, overlayContainer.style.display);
+                    // mozilla webxr does hide elements on session start
+                    // this is only necessary if we generated the overlay element
+                    overlayContainer.style.display = "";
+                    overlayContainer.style.visibility = "";
+                    document.body.appendChild(overlayContainer);
+                }
+            }
+            else {
+                console.warn("WebXRViewer: No DOM Overlay found");
+            }
+        }
+        this.ensureQuitARButton(this.arContainer);
+    }
+    onEnd(_context) {
+        // if (this.arContainer)
+        // this.arContainer.classList.remove("ar-session-active");
+        for (const created of this._createdAROnlyElements) {
+            if (created.remove) {
+                created.remove();
+            }
+        }
+        for (const prev of this._reparentedObjects) {
+            const el = prev.el;
+            prev.previousParent?.appendChild(el);
+        }
+        this._reparentedObjects.length = 0;
+        // mozilla XR exit AR fixes
+        if (DeviceUtilities.isMozillaXR()) {
+            // without the timeout we get errors in mozillas code and can not enter XR again
+            // not sure why we have to wait
+            setTimeout(() => {
+                // Canvas is not in DOM anymore after AR using Mozilla XR
+                const canvas = _context.renderer.domElement;
+                if (canvas) {
+                    _context.domElement.shadowRoot?.prepend(canvas);
+                }
+                // Fix visibility
+                const elements = document.querySelectorAll("*");
+                for (var i = 0; i < elements.length; i++) {
+                    const child = elements[i];
+                    if (child && child._displayChanged !== undefined && child._displayWas !== undefined) {
+                        child.style.display = child._displayWas;
+                    }
+                }
+            }, 10);
+        }
+    }
+    createOverlayContainer(needleEngineElement) {
+        if (this.contentElement)
+            return this.contentElement;
+        if (debug)
+            console.log("Setup overlay container");
+        const contentElement = needleEngineElement.shadowRoot.querySelector(".content");
+        this.contentElement = contentElement;
+        const overlaySlot = needleEngineElement.shadowRoot.querySelector(".overlay-content");
+        if (overlaySlot)
+            contentElement.appendChild(overlaySlot);
+        if (debug && !DeviceUtilities.isMobileDevice())
+            this.ensureQuitARButton(contentElement);
+        return contentElement;
+    }
+    onRequestedEndAR() {
+        if (!this.currentSession)
+            return;
+        this.currentSession.end();
+        this.currentSession = null;
+    }
+    ensureQuitARButton(element) {
+        const quitARSlot = document.createElement("slot");
+        quitARSlot.setAttribute("name", "quit-ar");
+        this.appendElement(quitARSlot, element);
+        this._createdAROnlyElements.push(quitARSlot);
+        // for mozilla XR reparenting we have to make sure the close button is clickable so we set it on the element directly
+        // it's in general perhaps more safe to set it on the element to ensure it's clickable
+        quitARSlot.style.pointerEvents = "auto";
+        // We want to search the document if there's a quit-ar button
+        // In which case we don't want to populate the default button (slot) with any content
+        const quitARElement = document.querySelector(`.${quitARClassName}`);
+        if (quitARElement) {
+            quitARElement.addEventListener('click', this.requestEndAR);
+            if (debug)
+                quitARElement.addEventListener('click', () => console.log("Clicked quit-ar button"));
+            // We found a explicit quit-ar element
+            return;
+        }
+        quitARSlot.addEventListener('click', this.requestEndAR);
+        if (debug)
+            quitARSlot.addEventListener('click', () => console.log("Clicked fallback close button"));
+        // we need another container to make sure the button is always on top
+        const fixedButtonContainer = document.createElement("div");
+        fixedButtonContainer.style.cssText = `
+            position: fixed;
+            top: 0;
+            right: 0;
+            z-index: 600;
+            pointer-events: all;
+        `;
+        this.appendElement(fixedButtonContainer, quitARSlot);
+        var svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+        svg.classList.add("quit-ar-button");
+        svg.setAttribute('width', "40px");
+        svg.setAttribute('height', "40px");
+        svg.style.cssText = `
+            background: rgba(255, 255, 255, .4);
+            -webkit-backdrop-filter: blur(8px);
+            backdrop-filter: blur(8px);
+            border-radius: 50%;
+            box-shadow: 0 0 5px rgba(0,0,0,.3);
+            outline: 1px solid rgba(255, 255, 255, .6);
+            display: flex;
+            justify-content: center;
+            align-items: center;
+        `;
+        fixedButtonContainer.appendChild(svg);
+        var path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+        path.setAttribute('d', 'M 12,12 L 28,28 M 28,12 12,28');
+        path.setAttribute('stroke', '#000000');
+        path.setAttribute('stroke-width', "2px");
+        path.style.cssText = `
+            /**filter: drop-shadow(0 0px 1.2px rgba(0,0,0,.7));**/
+        `;
+        svg.appendChild(path);
+        if (debug)
+            console.log("Created fallback close button", svg, element);
+    }
+    appendElement(element, parent) {
+        if (parent.shadowRoot)
+            return parent.shadowRoot.appendChild(element);
+        return parent.appendChild(element);
+    }
+}
+//# sourceMappingURL=needle-engine.ar-overlay.js.map

package/lib/engine/webcomponents/needle-engine.ar-overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"needle-engine.ar-overlay.js","sourceRoot":"","sources":["../../../src/engine/webcomponents/needle-engine.ar-overlay.ts"],"names":[],"mappings":"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"}

package/lib/engine/webcomponents/needle-engine.attributes.d.ts

@@ -0,0 +1,72 @@
+type MainAttributes = {
+    children?: HTMLElement[];
+    style?: Partial<CSSStyleDeclaration>;
+    /** src to one or multiple glb files to be loaded initially. Can be either "path/to/scene.glb" or "[./path/scene1.glb, myOtherScene.gltf]" */
+    src?: string | string[];
+    /** optional */
+    hash?: string;
+    /** set to automatically add OrbitControls to the loaded scene */
+    "camera-controls"?: boolean | "none";
+    /** event function name called when loading starts, use preventDefault to prevent the default loading overlay to show */
+    "loadstart"?: string;
+    /** event function name called when loading updates */
+    "progress"?: string;
+    /** event function name called when loading has finished */
+    "loadfinished"?: string;
+    /** override the default draco decoder path location */
+    "dracoDecoderPath"?: string;
+    /** override the default draco type */
+    "dracoDecoderType"?: string;
+    /** override the default ktx2 decoder path */
+    "ktx2DecoderPath"?: string;
+    /** Add to prevent Needle Engine context from being disposed when the element is removed from the DOM */
+    "keep-alive"?: boolean;
+    addEventListener?(event: "ready", callback: (event: CustomEvent) => void): void;
+    addEventListener?(event: "error", callback: (event: CustomEvent) => void): void;
+};
+type LoadingAttributes = {
+    "loading-style"?: "light" | "dark";
+    /** Pro feature */
+    "hide-loading-overlay"?: boolean;
+    /** Pro feature */
+    "loading-background-color"?: string;
+    /** Pro feature */
+    "loading-logo-src"?: string;
+    /** Pro feature */
+    "primary-color"?: string;
+    /** Pro feature */
+    "secondary-color"?: string;
+    /** Pro feature */
+    "loading-text-color"?: string;
+};
+type SkyboxAttributes = {
+    /** use background-image instead - URL to .exr, .hdr, .png, .jpg to be used as skybox */
+    "skybox-image"?: string;
+    /** URL to .exr, .hdr, .png, .jpg to be used as skybox */
+    "background-image"?: string;
+    /** Blurs the background image (if any) - value between 0 and 1
+     * 0: no blur
+     * 1: full blur
+     */
+    "background-blurriness"?: number;
+    /**
+     * Background color to be used if no skybox or background image is provided.
+     * For example: "skybox-color='#ff0000'" will set the background color to red.
+     */
+    "background-color"?: string;
+    /** URL to .exr, .hdr, .png, .jpg to be used for lighting */
+    "environment-image"?: string;
+};
+export type TonemappingAttributeOptions = "none" | "linear" | "neutral" | "agx";
+type RenderingAttributes = {
+    "transparent"?: boolean;
+    "contactshadows"?: boolean;
+    "tone-mapping"?: TonemappingAttributeOptions;
+    "tone-mapping-exposure"?: number;
+};
+/**
+ * Available attributes for the `<needle-engine>` web component
+ * @inheritdoc
+ */
+export type NeedleEngineAttributes = MainAttributes & Partial<Omit<HTMLElement, "style">> & LoadingAttributes & SkyboxAttributes & RenderingAttributes;
+export {};

package/lib/engine/webcomponents/needle-engine.attributes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=needle-engine.attributes.js.map

package/lib/engine/webcomponents/needle-engine.attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"needle-engine.attributes.js","sourceRoot":"","sources":["../../../src/engine/webcomponents/needle-engine.attributes.ts"],"names":[],"mappings":""}

package/lib/engine/webcomponents/needle-engine.d.ts

@@ -0,0 +1,113 @@
+/// <reference types="webxr" />
+import { Context } from "../engine_setup.js";
+import { type INeedleEngineComponent } from "../engine_types.js";
+/**
+ * <needle-engine> web component. See {@link NeedleEngineAttributes} attributes for supported attributes
+ * The needle engine web component creates and manages a needle engine context which is responsible for rendering a 3D scene using threejs.
+ * The needle engine context is created when the src attribute is set and disposed when the needle engine is removed from the document (you can prevent this by setting the keep-alive attribute to true).
+ * The needle engine context is accessible via the context property on the needle engine element (e.g. document.querySelector("needle-engine").context).
+ * @link https://engine.needle.tools/docs/reference/needle-engine-attributes
+ *
+ * @example
+ * <needle-engine src="https://example.com/scene.glb"></needle-engine>
+ * @example
+ * <needle-engine src="https://example.com/scene.glb" camera-controls="false"></needle-engine>
+*/
+export declare class NeedleEngineHTMLElement extends HTMLElement implements INeedleEngineComponent {
+    static get observedAttributes(): string[];
+    get loadingProgress01(): number;
+    get loadingFinished(): boolean;
+    /**
+     * If set to false the camera controls are disabled. Default is true.
+     * @type {boolean | null}
+     * @memberof NeedleEngineAttributes
+     * @example
+     * <needle-engine camera-controls="false"></needle-engine>
+     * @example
+     * <needle-engine camera-controls="true"></needle-engine>
+     * @example
+     * <needle-engine camera-controls></needle-engine>
+     * @example
+     * <needle-engine></needle-engine>
+     * @returns {boolean | null} if the attribute is not set it returns null
+     */
+    get cameraControls(): boolean | null;
+    /**
+     * Get the current context for this web component instance. The context is created when the src attribute is set and the loading has finished.
+     * The context is disposed when the needle engine is removed from the document (you can prevent this by setting the keep-alive attribute to true).
+     * @returns {Promise<Context>} a promise that resolves to the context when the loading has finished
+     */
+    getContext(): Promise<Context>;
+    /**
+     * Get the context that is created when the src attribute is set and the loading has finished.
+     */
+    get context(): Context;
+    private _context;
+    private _overlay_ar;
+    private _loadingProgress01;
+    private _loadingView?;
+    private _previousSrc;
+    /** set to true after <needle-engine> did load completely at least once. Set to false when <needle-engine> is removed from the document */
+    private _didFullyLoad;
+    constructor();
+    /**
+     * @internal
+     */
+    connectedCallback(): Promise<void>;
+    /**
+     * @internal
+     */
+    disconnectedCallback(): void;
+    /**
+     * @internal
+     */
+    attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+    private _loadId;
+    private _abortController;
+    private _lastSourceFiles;
+    private _createContextPromise;
+    private onLoad;
+    private applyAttributes;
+    private onXRSessionStarted;
+    /** called by the context when the first frame has been rendered */
+    private onReady;
+    private onError;
+    private internalSetLoadingMessage;
+    private getSourceFiles;
+    private checkIfSourceHasChanged;
+    private _previouslyRegisteredMap;
+    private ensureLoadStartIsRegistered;
+    private registerEventFromAttribute;
+    private setPublicKey;
+    private setVersion;
+    /**
+     * @internal
+     */
+    getAROverlayContainer(): HTMLElement;
+    /**
+     * @internal
+     */
+    getVROverlayContainer(): HTMLElement | null;
+    /**
+     * @internal
+     */
+    onEnterAR(session: XRSession): void;
+    /**
+     * @internal
+     */
+    onExitAR(session: XRSession): void;
+    /**
+     * @internal
+     */
+    onEnterVR(session: XRSession): void;
+    /**
+     * @internal
+     */
+    onExitVR(session: XRSession): void;
+    private onSetupAR;
+    private onSetupVR;
+    private onSetupDesktop;
+    private setupElementsForMode;
+    private foreachHtmlElement;
+    private onBeforeBeginLoading;
+}

package/lib/engine/webcomponents/needle-engine.extras.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Call with the name of an attribute that you want to receive change events for
+ * This is useful for example if you want to add custom attributes to <needle-engine>
+ * Use the addAttributeChangeCallback utility methods to register callback events
+ */
+export declare function registerObservableAttribute(name: string): Promise<void>;

package/lib/engine/webcomponents/needle-engine.extras.js

@@ -0,0 +1,14 @@
+/*
+DO NOT IMPORT ENGINE_ELEMENT FROM HERE
+*/
+/**
+ * Call with the name of an attribute that you want to receive change events for
+ * This is useful for example if you want to add custom attributes to <needle-engine>
+ * Use the addAttributeChangeCallback utility methods to register callback events
+ */
+export async function registerObservableAttribute(name) {
+    const { NeedleEngineHTMLElement } = await import("./needle-engine.js");
+    if (!NeedleEngineHTMLElement.observedAttributes.includes(name))
+        NeedleEngineHTMLElement.observedAttributes.push(name);
+}
+//# sourceMappingURL=needle-engine.extras.js.map

package/lib/engine/webcomponents/needle-engine.extras.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"needle-engine.extras.js","sourceRoot":"","sources":["../../../src/engine/webcomponents/needle-engine.extras.ts"],"names":[],"mappings":"AAEA;;EAEE;AAEF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,IAAY;IAC1D,MAAM,EAAE,uBAAuB,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACvE,IAAI,CAAC,uBAAuB,CAAC,kBAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC1D,uBAAuB,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC9D,CAAC"}