revert "remove all deprecated code" for patch release

packages/core/src/Viewer.ts

@@ -29,6 +29,7 @@ import {
     AnimateOptions,
     CssSize,
     ExtendedPosition,
+    PanoData,
     PanoramaOptions,
     ParsedViewerConfig,
     Position,
@@ -38,6 +39,7 @@ import {
 } from './model';
 import type { AbstractPlugin, PluginConstructor } from './plugins/AbstractPlugin';
 import { pluginInterop } from './plugins/AbstractPlugin';
+import { PSVError } from './PSVError';
 import { DataHelper } from './services/DataHelper';
 import { EventsHandler } from './services/EventsHandler';
 import { Renderer } from './services/Renderer';
@@ -323,14 +325,24 @@ export class Viewer extends TypedEventTarget<ViewerEvents> {
 
         // apply default parameters on first load
         if (!this.state.ready) {
-            ['sphereCorrection', 'panoData'].forEach((opt) => {
+            ['sphereCorrection', 'panoData', 'overlay', 'overlayOpacity'].forEach((opt) => {
                 if (!(opt in options)) {
                     // @ts-ignore
                     options[opt] = this.config[opt];
                 }
             });
         }
 
+        if (isExtendedPosition(options)) {
+            logWarn(`PanoramaOptions.yaw and PanoramaOptions.pitch are deprecated, use PanoramaOptions.position instead`);
+            (options as PanoramaOptions).position = this.dataHelper.cleanPosition(options);
+        }
+        if (typeof options.transition === 'number') {
+            logWarn(`Use PanoramaOptions.speed to define the speed/duration of the transition`);
+            options.speed = options.transition;
+            options.transition = true;
+        }
+
         if (options.transition === undefined) {
             options.transition = true;
         }
@@ -378,6 +390,7 @@ export class Viewer extends TypedEventTarget<ViewerEvents> {
                 this.dispatchEvent(new PanoramaErrorEvent(path, err));
                 throw err;
             } else {
+                this.setOverlay(options.overlay, options.overlayOpacity);
                 this.navbar.setCaption(this.config.caption);
                 return true;
             }
@@ -449,6 +462,50 @@ export class Viewer extends TypedEventTarget<ViewerEvents> {
         return this.state.loadingPromise;
     }
 
+    /**
+     * @deprecated Use the `overlay` plugin instead
+     */
+    setOverlay(path: any, opacity = this.config.overlayOpacity): Promise<void> {
+        const supportsOverlay = (this.adapter.constructor as typeof AbstractAdapter).supportsOverlay;
+
+        if (!path) {
+            if (supportsOverlay) {
+                this.renderer.setOverlay(null, 0);
+            }
+
+            return Promise.resolve();
+        } else {
+            if (!supportsOverlay) {
+                return Promise.reject(new PSVError(`Current adapter does not supports overlay`));
+            }
+
+            return this.adapter
+                .loadTexture(
+                    path,
+                    (image) => {
+                        if ((this.state.textureData.panoData as PanoData).isEquirectangular) {
+                            const p = this.state.textureData.panoData as PanoData;
+                            const r = image.width / p.croppedWidth;
+                            return {
+                                isEquirectangular: true,
+                                fullWidth: r * p.fullWidth,
+                                fullHeight: r * p.fullHeight,
+                                croppedWidth: r * p.croppedWidth,
+                                croppedHeight: r * p.croppedHeight,
+                                croppedX: r * p.croppedX,
+                                croppedY: r * p.croppedY,
+                            };
+                        }
+                    },
+                    false,
+                    false
+                )
+                .then((textureData) => {
+                    this.renderer.setOverlay(textureData, opacity);
+                });
+        }
+    }
+
     /**
      * Update options
      * @throws {@link PSVError} if the configuration is invalid

packages/core/src/adapters/AbstractAdapter.ts

@@ -1,7 +1,7 @@
-import { Mesh } from 'three';
-import { PSVError } from '../PSVError';
-import type { Viewer } from '../Viewer';
+import { Mesh, ShaderMaterial, ShaderMaterialParameters } from 'three';
 import { PanoData, PanoDataProvider, PanoramaPosition, Position, TextureData } from '../model';
+import type { Viewer } from '../Viewer';
+import { PSVError } from '../PSVError';
 import { checkVersion } from '../utils';
 
 /**
@@ -26,6 +26,11 @@ export abstract class AbstractAdapter<TPanorama, TTexture, TData> {
      */
     static readonly supportsDownload: boolean = false;
 
+    /**
+     * @deprecated
+     */
+    static readonly supportsOverlay: boolean = false;
+
     constructor(protected readonly viewer: Viewer) {}
 
     /**
@@ -107,6 +112,73 @@ export abstract class AbstractAdapter<TPanorama, TTexture, TData> {
      * Clear a loaded texture from memory
      */
     abstract disposeTexture(textureData: TextureData<TTexture, TPanorama, TData>): void;
+
+    /**
+     * @deprecated
+     */
+    // @ts-ignore unused parameter
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    setOverlay(mesh: Mesh, textureData: TextureData<TTexture, TPanorama, TData>, opacity: number): void {
+        throw new PSVError('Current adapter does not support overlay');
+    }
+
+    /**
+     * @internal
+     */
+    static OVERLAY_UNIFORMS = {
+        panorama: 'panorama',
+        overlay: 'overlay',
+        globalOpacity: 'globalOpacity',
+        overlayOpacity: 'overlayOpacity',
+    };
+
+    /**
+     * @internal
+     */
+    static createOverlayMaterial({
+        additionalUniforms,
+        overrideVertexShader,
+    }: {
+        additionalUniforms?: ShaderMaterialParameters['uniforms'];
+        overrideVertexShader?: ShaderMaterialParameters['vertexShader'];
+    } = {}): ShaderMaterial {
+        return new ShaderMaterial({
+            uniforms: {
+                ...additionalUniforms,
+                [AbstractAdapter.OVERLAY_UNIFORMS.panorama]: { value: null },
+                [AbstractAdapter.OVERLAY_UNIFORMS.overlay]: { value: null },
+                [AbstractAdapter.OVERLAY_UNIFORMS.globalOpacity]: { value: 1.0 },
+                [AbstractAdapter.OVERLAY_UNIFORMS.overlayOpacity]: { value: 0.0 },
+            },
+
+            vertexShader:
+                overrideVertexShader ||
+                `
+varying vec2 vUv;
+
+void main() {
+  vUv = uv;
+  gl_Position = projectionMatrix *  modelViewMatrix * vec4( position, 1.0 );
+}`,
+
+            fragmentShader: `
+uniform sampler2D ${AbstractAdapter.OVERLAY_UNIFORMS.panorama};
+uniform sampler2D ${AbstractAdapter.OVERLAY_UNIFORMS.overlay};
+uniform float ${AbstractAdapter.OVERLAY_UNIFORMS.globalOpacity};
+uniform float ${AbstractAdapter.OVERLAY_UNIFORMS.overlayOpacity};
+
+varying vec2 vUv;
+
+void main() {
+  vec4 tColor1 = texture2D( ${AbstractAdapter.OVERLAY_UNIFORMS.panorama}, vUv );
+  vec4 tColor2 = texture2D( ${AbstractAdapter.OVERLAY_UNIFORMS.overlay}, vUv );
+  gl_FragColor = vec4(
+    mix( tColor1.rgb, tColor2.rgb, tColor2.a * ${AbstractAdapter.OVERLAY_UNIFORMS.overlayOpacity} ),
+    ${AbstractAdapter.OVERLAY_UNIFORMS.globalOpacity}
+  );
+}`,
+        });
+    }
 }
 
 // prettier-ignore

packages/core/src/adapters/EquirectangularAdapter.ts

@@ -1,4 +1,4 @@
-import { BufferGeometry, Material, MathUtils, Mesh, MeshBasicMaterial, SphereGeometry, Texture } from 'three';
+import { BufferGeometry, MathUtils, Mesh, ShaderMaterial, SphereGeometry, Texture } from 'three';
 import { PSVError } from '../PSVError';
 import type { Viewer } from '../Viewer';
 import { SPHERE_RADIUS } from '../data/constants';
@@ -38,7 +38,7 @@ export type EquirectangularAdapterConfig = {
     blur?: boolean;
 };
 
-type EquirectangularMesh = Mesh<BufferGeometry, Material>;
+type EquirectangularMesh = Mesh<BufferGeometry, ShaderMaterial>;
 type EquirectangularTexture = TextureData<Texture, string, PanoData>;
 
 const getConfig = getConfigParser<EquirectangularAdapterConfig>(
@@ -66,6 +66,7 @@ export class EquirectangularAdapter extends AbstractAdapter<string, Texture, Pan
     static override readonly id: string = 'equirectangular';
     static override readonly VERSION = PKG_VERSION;
     static override readonly supportsDownload: boolean = true;
+    static override readonly supportsOverlay: boolean = true;
 
     private readonly config: EquirectangularAdapterConfig;
 
@@ -78,6 +79,12 @@ export class EquirectangularAdapter extends AbstractAdapter<string, Texture, Pan
         super(viewer);
 
         this.config = getConfig(config);
+        if (!isNil(this.viewer.config.useXmpData)) {
+            this.config.useXmpData = this.viewer.config.useXmpData;
+        }
+        if (!isNil(this.viewer.config.canvasBackground)) {
+            this.config.backgroundColor = this.viewer.config.canvasBackground;
+        }
 
         if (this.config.interpolateBackground) {
             if (!window.Worker) {
@@ -320,22 +327,37 @@ export class EquirectangularAdapter extends AbstractAdapter<string, Texture, Pan
             -Math.PI / 2
         ).scale(-1, 1, 1);
 
-        return new Mesh(geometry, new MeshBasicMaterial());
+        const material = AbstractAdapter.createOverlayMaterial();
+
+        return new Mesh(geometry, material);
     }
 
     setTexture(mesh: EquirectangularMesh, textureData: EquirectangularTexture) {
-        (mesh.material as MeshBasicMaterial).map = textureData.texture;
+        this.__setUniform(mesh, AbstractAdapter.OVERLAY_UNIFORMS.panorama, textureData.texture);
+    }
+
+    override setOverlay(mesh: EquirectangularMesh, textureData: EquirectangularTexture, opacity: number) {
+        this.__setUniform(mesh, AbstractAdapter.OVERLAY_UNIFORMS.overlayOpacity, opacity);
+        if (!textureData) {
+            this.__setUniform(mesh, AbstractAdapter.OVERLAY_UNIFORMS.overlay, null);
+        } else {
+            this.__setUniform(mesh, AbstractAdapter.OVERLAY_UNIFORMS.overlay, textureData.texture);
+        }
     }
 
     setTextureOpacity(mesh: EquirectangularMesh, opacity: number) {
-        mesh.material.opacity = opacity;
+        this.__setUniform(mesh, AbstractAdapter.OVERLAY_UNIFORMS.globalOpacity, opacity);
         mesh.material.transparent = opacity < 1;
     }
 
     disposeTexture(textureData: EquirectangularTexture) {
         textureData.texture?.dispose();
     }
 
+    private __setUniform(mesh: EquirectangularMesh, uniform: string, value: any) {
+        mesh.material.uniforms[uniform].value = value;
+    }
+
     private __defaultPanoData(img: HTMLImageElement): PanoData {
         const fullWidth = Math.max(img.width, img.height * 2);
         const fullHeight = Math.round(fullWidth / 2);

packages/core/src/data/config.ts

@@ -12,6 +12,8 @@ import { ACTIONS, KEY_CODES } from './constants';
  */
 export const DEFAULTS: Required<ParsedViewerConfig> = {
     panorama: null,
+    overlay: null,
+    overlayOpacity: 1,
     container: null,
     adapter: [EquirectangularAdapter as any, null],
     plugins: [],
@@ -36,8 +38,10 @@ export const DEFAULTS: Required<ParsedViewerConfig> = {
     mousemove: true,
     mousewheelCtrlKey: false,
     touchmoveTwoFingers: false,
+    useXmpData: null,
     panoData: null,
     requestHeaders: null,
+    canvasBackground: null,
     rendererParameters: { alpha: true, antialias: true },
     withCredentials: false,
     // prettier-ignore
@@ -85,6 +89,8 @@ export const DEFAULTS: Required<ParsedViewerConfig> = {
 export const READONLY_OPTIONS: Record<ReadonlyViewerConfig, string> = {
     panorama: 'Use setPanorama method to change the panorama',
     panoData: 'Use setPanorama method to change the panorama',
+    overlay: 'Use setOverlay method to changer the overlay',
+    overlayOpacity: 'Use setOverlay method to changer the overlay',
     container: 'Cannot change viewer container',
     adapter: 'Cannot change adapter',
     plugins: 'Cannot change plugins',
@@ -117,6 +123,9 @@ export const CONFIG_PARSERS: ConfigParsers<ViewerConfig, ParsedViewerConfig> = {
         }
         return adapter;
     },
+    overlayOpacity: (overlayOpacity) => {
+        return MathUtils.clamp(overlayOpacity, 0, 1);
+    },
     defaultYaw: (defaultYaw) => {
         // defaultYaw is between 0 and PI
         return parseAngle(defaultYaw);
@@ -223,6 +232,24 @@ export const CONFIG_PARSERS: ConfigParsers<ViewerConfig, ParsedViewerConfig> = {
         }
         return navbar;
     },
+    useXmpData: (useXmpData) => {
+        if (useXmpData !== null) {
+            logWarn(`Global useXmpData is deprecated, it is now configured on the adapter.`);
+        }
+        return useXmpData;
+    },
+    canvasBackground: (canvasBackground) => {
+        if (canvasBackground !== null) {
+            logWarn(`Global canvasBackground is deprecated, it is now configured on the adapter.`);
+        }
+        return canvasBackground;
+    },
+    overlay: (overlay) => {
+        if (overlay !== null) {
+            logWarn(`"overlay" option is deprecated, use "@photo-sphere-viewer/overlay-plugin" instead.`);
+        }
+        return overlay;
+    },
 };
 
 /**