@babylonjs/viewer 7.22.3 → 7.22.4-alpha

package/lib/index.d.ts

@@ -0,0 +1,237 @@
+import { Nullable, AssetContainer, IDisposable, AbstractEngine, LoadAssetContainerOptions } from '@babylonjs/core/index.js';
+import { Color4 } from '@babylonjs/core/Maths/math.color.js';
+import { Observable } from '@babylonjs/core/Misc/observable.js';
+import { Scene } from '@babylonjs/core/scene.js';
+import * as lit_html from 'lit-html';
+import * as lit from 'lit';
+import { LitElement, PropertyValues } from 'lit';
+import { EngineOptions } from '@babylonjs/core/Engines.js';
+
+declare const defaultViewerOptions: {
+    readonly backgroundColor: Color4;
+};
+type ViewerDetails = {
+    /**
+     * Provides access to the Scene managed by the Viewer.
+     */
+    scene: Scene;
+    /**
+     * Provides access to the currently loaded model.
+     */
+    model: Nullable<AssetContainer>;
+};
+type ViewerOptions = Partial<typeof defaultViewerOptions & Readonly<{
+    /**
+     * Called once when the viewer is initialized and provides viewer details that can be used for advanced customization.
+     */
+    onInitialized: (details: Readonly<ViewerDetails>) => void;
+}>>;
+/**
+ * Provides an experience for viewing a single 3D model.
+ * @remarks
+ * The Viewer is not tied to a specific UI framework and can be used with Babylon.js in a browser or with Babylon Native.
+ * Includes (or will include) support for common model viewing requirements such as:
+ * - Loading different model formats.
+ * - Setting up a camera and providing default behaviors like auto orbit and pose interpolation.
+ * - Framing the loaded model in the camera's view.
+ * - Setting up the environment, lighting, and tone mapping.
+ * - Enumerating and playing (or auto playing) animations.
+ * - Enumerating and switching between material variants.
+ * - Full screen and XR modes.
+ */
+declare class Viewer implements IDisposable {
+    private readonly _engine;
+    /**
+     * Fired when a model is loaded into the viewer.
+     */
+    readonly onModelLoaded: Observable<void>;
+    /**
+     * Fired when an error occurs while loading a model.
+     */
+    readonly onModelError: Observable<unknown>;
+    /**
+     * Fired when the selected animation changes.
+     */
+    readonly onSelectedAnimationChanged: Observable<void>;
+    /**
+     * Fired when the animation speed changes.
+     */
+    readonly onAnimationSpeedChanged: Observable<void>;
+    /**
+     * Fired when the selected animation is playing or paused.
+     */
+    readonly onIsAnimationPlayingChanged: Observable<void>;
+    /**
+     * Fired when the current point on the selected animation timeline changes.
+     */
+    readonly onAnimationProgressChanged: Observable<void>;
+    private readonly _details;
+    private readonly _camera;
+    private readonly _autoRotationBehavior;
+    private readonly _renderLoopController;
+    private _skybox;
+    private _isDisposed;
+    private readonly _loadModelLock;
+    private _loadModelAbortController;
+    private readonly _loadEnvironmentLock;
+    private _environment;
+    private _loadEnvironmentAbortController;
+    private _selectedAnimation;
+    private _activeAnimationObservers;
+    private _animationSpeed;
+    constructor(_engine: AbstractEngine, options?: ViewerOptions);
+    /**
+     * The list of animation names for the currently loaded model.
+     */
+    get animations(): readonly string[];
+    /**
+     * The currently selected animation index.
+     */
+    get selectedAnimation(): number;
+    set selectedAnimation(value: number);
+    /**
+     * True if an animation is currently playing.
+     */
+    get isAnimationPlaying(): boolean;
+    /**
+     * The speed scale at which animations are played.
+     */
+    get animationSpeed(): number;
+    set animationSpeed(value: number);
+    /**
+     * The current point on the selected animation timeline, normalized between 0 and 1.
+     */
+    get animationProgress(): number;
+    set animationProgress(value: number);
+    private get _activeAnimation();
+    /**
+     * Loads a 3D model from the specified URL.
+     * @remarks
+     * If a model is already loaded, it will be unloaded before loading the new model.
+     * @param source A url or File or ArrayBufferView that points to the model to load.
+     * @param options The options to use when loading the model.
+     * @param abortSignal An optional signal that can be used to abort the loading process.
+     */
+    loadModelAsync(source: string | File | ArrayBufferView, options?: LoadAssetContainerOptions, abortSignal?: AbortSignal): Promise<void>;
+    /**
+     * Loads an environment texture from the specified url and sets up a corresponding skybox.
+     * @remarks
+     * If no url is provided, a default hemispheric light will be created.
+     * If an environment is already loaded, it will be unloaded before loading the new environment.
+     * @param url The url of the environment texture to load.
+     * @param options The options to use when loading the environment.
+     * @param abortSignal An optional signal that can be used to abort the loading process.
+     */
+    loadEnvironmentAsync(url: Nullable<string | undefined>, options?: {}, abortSignal?: AbortSignal): Promise<void>;
+    /**
+     * Toggles the play/pause animation state if there is a selected animation.
+     */
+    toggleAnimation(): void;
+    /**
+     * Plays the selected animation if there is one.
+     */
+    playAnimation(): void;
+    /**
+     * Pauses the selected animation if there is one.
+     */
+    pauseAnimation(): Promise<void>;
+    /**
+     * Disposes of the resources held by the Viewer.
+     */
+    dispose(): void;
+    private _updateCamera;
+    private _applyAnimationSpeed;
+    /**
+     * Check for disposed or aborted state (basically everything that can interrupt an async operation).
+     * @param abortSignals A set of optional AbortSignals to also check.
+     */
+    private _throwIfDisposedOrAborted;
+}
+
+interface HTML3DElementEventMap extends HTMLElementEventMap {
+    modelchange: Event;
+    modelerror: Event;
+    selectedanimationchange: Event;
+    animationspeedchange: Event;
+    animationplayingchange: Event;
+    animationprogresschange: Event;
+}
+/**
+ * Represents a custom element that displays a 3D model using the Babylon.js Viewer.
+ */
+declare class HTML3DElement extends LitElement {
+    /**
+     * Gets the underlying Viewer object. It will be undefined when the element is not connected to the DOM.
+     */
+    viewer?: Viewer;
+    static styles: lit.CSSResult;
+    /**
+     * The model URL.
+     */
+    src: string;
+    /**
+     * The environment URL.
+     */
+    env: string;
+    /**
+     * The list of animation names for the currently loaded model.
+     */
+    get animations(): readonly string[];
+    /**
+     * The currently selected animation index.
+     */
+    get selectedAnimation(): number;
+    /**
+     * True if an animation is currently playing.
+     */
+    get isAnimationPlaying(): boolean;
+    /**
+     * The speed scale at which animations are played.
+     */
+    animationSpeed: number;
+    /**
+     * The current point on the selected animation timeline, normalized between 0 and 1.
+     */
+    animationProgress: number;
+    private _animations;
+    private _selectedAnimation;
+    private _isAnimationPlaying;
+    private _canvas;
+    /**
+     * Toggles the play/pause animation state if there is a selected animation.
+     */
+    toggleAnimation(): void;
+    connectedCallback(): void;
+    firstUpdated(_changedProperties: PropertyValues): void;
+    disconnectedCallback(): void;
+    update(changedProperties: PropertyValues): void;
+    render(): lit_html.TemplateResult<1>;
+    addEventListener<K extends keyof HTML3DElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTML3DElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    private _dispatchCustomEvent;
+    private _onSelectedAnimationChanged;
+    private _onAnimationSpeedChanged;
+    private _onProgressChanged;
+    private _onProgressPointerDown;
+    private _setupViewer;
+    private _tearDownViewer;
+    private _updateAnimationSpeed;
+    private _updateSelectedAnimation;
+    private _updateModel;
+    private _updateEnv;
+}
+
+type CanvasViewerOptions = ViewerOptions & ({
+    engine: "WebGL";
+} & EngineOptions);
+/**
+ * Creates a Viewer instance that is bound to an HTML canvas.
+ * @remarks
+ * This function can be shared across multiple UI integrations (e.g. Web Components, React, etc.).
+ * @param canvas The canvas element to bind the Viewer to.
+ * @param options The options to use when creating the Viewer and binding it to the specified canvas.
+ * @returns A Viewer instance that is bound to the specified canvas.
+ */
+declare function createViewerForCanvas(canvas: HTMLCanvasElement, options?: CanvasViewerOptions): Viewer;
+
+export { HTML3DElement, Viewer, type ViewerDetails, type ViewerOptions, createViewerForCanvas };