Introduced a built-in fullscreen button

docs/api/viewport.md

@@ -17,7 +17,8 @@ Create a new viewport with the specified `settings`.
     * `hudContainer: HTMLDivElement, optional`. An overlay that will be displayed in front of the augmented scene. It must be a direct child of `container` in the DOM tree.
     * `resolution: Resolution, optional`. The [resolution](resolution.md) of the virtual scene.
     * `canvas: HTMLCanvasElement, optional`. An existing canvas on which the virtual scene will be drawn. The engine automatically creates a canvas. You should only specify an existing canvas if you must. Experimental.
-    * `style: string, optional.` The [viewport style](#style). *Since:* 0.3.0
+    * `style: string, optional`. The [viewport style](#style). *Since:* 0.3.0
+    * `fullscreenUI: boolean, optional`. Whether or not to include, as a convenience, the built-in fullscreen button on platforms in which the fullscreen mode is [available](#fullscreenavailable). Defaults to `true`. *Since:* 0.3.0
 
 **Returns**
 
@@ -82,7 +83,7 @@ The default style is `"best-fit"` in immersive mode, or `"inline"` in inline mod
 
 `viewport.fullscreen: boolean, read-only`
 
-Whether or not the viewport [container](#container) is being displayed in fullscreen mode.
+Whether or not the viewport [container](#container) is being displayed in fullscreen mode. See also: [requestFullscreen](#requestfullscreen).
 
 *Since:* 0.3.0
 
@@ -90,7 +91,7 @@ Whether or not the viewport [container](#container) is being displayed in fullsc
 
 `viewport.fullscreenAvailable: boolean, read-only`
 
-Checks the availability of the fullscreen mode on the current platform and page.
+Used to check the availability of the fullscreen mode on the current platform and page.
 
 *Since:* 0.3.0
 

plugins/aframe-with-encantar.js

@@ -854,6 +854,7 @@ AFRAME.registerComponent('ar-viewport', ARComponent({
     {
         const scene = this.el.sceneEl;
         const huds = [];
+        const fullscreenUI = this.el.components['ar-viewport-fullscreen-ui'];
 
         for(const child of this.el.children) {
             if(child.components !== undefined) {
@@ -870,13 +871,16 @@ AFRAME.registerComponent('ar-viewport', ARComponent({
         else if(huds.length == 0)
             huds.push(undefined);
 
-        return AR.Viewport({
-            container: this.el,
-            hudContainer: huds[0],
-            canvas: scene.canvas,
-            resolution: this.data.resolution,
-            style: this.data.style
-        });
+        return AR.Viewport(Object.assign(
+            {
+                container: this.el,
+                hudContainer: huds[0],
+                canvas: scene.canvas,
+                resolution: this.data.resolution,
+                style: this.data.style,
+            },
+            !fullscreenUI ? {} : { fullscreenUI: fullscreenUI.data.enabled }
+        ));
     },
 
 }));
@@ -887,10 +891,22 @@ AFRAME.registerPrimitive('ar-viewport', {
     },
     mappings: {
         'resolution': 'ar-viewport.resolution',
-        'style': 'ar-viewport.style'
+        'style': 'ar-viewport.style',
+        'fullscreen-ui': 'ar-viewport-fullscreen-ui'
     }
 });
 
+AFRAME.registerComponent('ar-viewport-fullscreen-ui', ARComponent({
+
+    schema: {
+
+        /** whether or not to include the built-in fullscreen button */
+        'enabled': { type: 'boolean', default: true },
+
+    }
+
+}));
+
 /**
  * AR Heads-Up Display
  */

src/core/viewport.ts

@@ -28,6 +28,7 @@ import { Nullable } from '../utils/utils';
 import { Resolution } from '../utils/resolution';
 import { Utils } from '../utils/utils';
 import { HUD, HUDContainer } from './hud';
+import { FullscreenButton } from '../ui/fullscreen-button';
 import { AREvent, AREventTarget, AREventListener } from '../utils/ar-events';
 import { IllegalArgumentError, IllegalOperationError, NotSupportedError, AccessDeniedError } from '../utils/errors';
 
@@ -74,6 +75,9 @@ export interface ViewportSettings
 
     /** An existing <canvas> on which the virtual scene will be drawn */
     canvas?: Nullable<HTMLCanvasElement>;
+
+    /** Whether or not to include the built-in fullscreen button */
+    fullscreenUI?: boolean;
 }
 
 /** Default viewport constructor settings */
@@ -83,6 +87,7 @@ const DEFAULT_VIEWPORT_SETTINGS: Readonly<Required<ViewportSettings>> = {
     resolution: 'lg',
     style: 'best-fit',
     canvas: null,
+    fullscreenUI: true,
 };
 
 
@@ -786,6 +791,9 @@ export class Viewport extends ViewportEventTarget
     /** Fullscreen utilities */
     private readonly _fullscreen: ViewportFullscreenHelper;
 
+    /** Built-in fullscreen button */
+    private readonly _fullscreenButton: Nullable<FullscreenButton>;
+
 
 
 
@@ -814,6 +822,10 @@ export class Viewport extends ViewportEventTarget
         this._resizer.setStrategyByName(this._style);
 
         this._fullscreen = new ViewportFullscreenHelper(this);
+        this._fullscreenButton = null;
+
+        if(settings.fullscreenUI && this.fullscreenAvailable)
+            this._fullscreenButton = new FullscreenButton(this);
     }
 
     /**
@@ -953,6 +965,7 @@ export class Viewport extends ViewportEventTarget
         this._hud._init(HUD_ZINDEX);
         this._canvases.init();
         this._resizer.init();
+        this._fullscreenButton?.init();
     }
 
     /**
@@ -965,5 +978,6 @@ export class Viewport extends ViewportEventTarget
         this._canvases.release();
         this._hud._release();
         this._containers.release();
+        this._fullscreenButton?.release();
     }
 }

src/ui/fullscreen-button.ts

@@ -0,0 +1,152 @@
+/*
+ * encantar.js
+ * GPU-accelerated Augmented Reality for the web
+ * Copyright (C) 2022-2024 Alexandre Martins <alemartf(at)gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * fullscreen-button.ts
+ * A built-in fullscreen button introduced as a convenience
+ */
+
+import { Viewport } from '../core/viewport';
+
+/** Button icon to be displayed when the fullscreen mode is disabled */
+const BUTTON_ICON_OFF = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAbUlEQVRYR+2WOQ4AIAgE5f+PVhobDZANBZAsraAwXMoqFil+f9GBj8BW8dIiKt45at/XgShStHgvmfdekwAdIIEyAmh1Z/U5ikmABPoRsLZWtt+5DUlgHgGr6qM1Pf9XnO131L7fJEQjyOqXEzjP1YAhNmUTrgAAAABJRU5ErkJggg==';
+
+/** Button icon to be displayed when the fullscreen mode is enabled */
+const BUTTON_ICON_ON = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAZElEQVRYR+2WwRIAEAhE9f8fTQ5OhtkLxbzOyc5rJSvBYcH3FwTIBKpHb5d57Nqm5o0aCIBAPgLDxSunq69APT8RCBdwezTLHjglDAEQgEC+QZR2EqqbjprHRgSB9wjwHX9LoAHP1YAhXF4Z/QAAAABJRU5ErkJggg==';
+
+/** Button size, in pixels */
+const BUTTON_SIZE = 64;
+
+/** Button margin, in pixels */
+const BUTTON_MARGIN = 24;
+
+
+
+/**
+ * Built-in fullscreen button
+ */
+export class FullscreenButton
+{
+    /** The viewport associated to this panel */
+    private readonly _viewport: Viewport;
+
+    /** The HTML element of the button */
+    private readonly _button: HTMLButtonElement;
+
+    /** Bound event handler */
+    private readonly _boundEventHandler: EventListener;
+
+
+
+    /**
+     * Constructor
+     * @param viewport Viewport
+     */
+    constructor(viewport: Viewport)
+    {
+        this._viewport = viewport;
+        this._button = this._createButton();
+        this._boundEventHandler = this._handleFullscreenEvent.bind(this);
+    }
+
+    /**
+     * Initialize
+     */
+    init(): void
+    {
+        this._viewport.hud.container.appendChild(this._button);
+        this._viewport.addEventListener('fullscreenchange', this._boundEventHandler);
+    }
+
+    /**
+     * Release
+     */
+    release(): void
+    {
+        this._viewport.removeEventListener('fullscreenchange', this._boundEventHandler);
+        this._button.remove();
+    }
+
+    /**
+     * Create the <button> element
+     */
+    private _createButton(): HTMLButtonElement
+    {
+        const button = document.createElement('button');
+        const icon = document.createElement('img');
+
+        button.style.display = 'inline-block';
+        button.style.position = 'absolute';
+        button.style.bottom = BUTTON_MARGIN + 'px';
+        button.style.right = BUTTON_MARGIN + 'px';
+        button.style.width = BUTTON_SIZE + 'px';
+        button.style.height = BUTTON_SIZE + 'px';
+        button.style.padding = '2px';
+
+        button.style.backgroundColor = '#7c5ec2';
+        button.style.borderColor = '#5c3ba3';
+        button.style.borderStyle = 'solid';
+        button.style.borderWidth = '2px';
+        button.style.borderRadius = '8px';
+        button.style.cursor = 'pointer';
+        button.draggable = false;
+
+        icon.src = BUTTON_ICON_OFF;
+        icon.draggable = false;
+        icon.style.display = 'inline';
+        icon.style.width = '100%';
+        icon.style.height = '100%';
+        icon.style.imageRendering = 'pixelated';
+        button.appendChild(icon);
+
+        const highlight = () => {
+            button.style.backgroundColor = '#ffd500';
+            button.style.borderColor = '#bb9100';
+        };
+
+        const dehighlight = () => {
+            button.style.backgroundColor = '#7e56c2';
+            button.style.borderColor = '#5c3ba3';
+        };
+
+        button.addEventListener('pointerdown', highlight);
+        button.addEventListener('pointerup', dehighlight);
+        button.addEventListener('pointermove', dehighlight);
+
+        button.addEventListener('click', () => {
+            if(!this._viewport.fullscreen) {
+                this._viewport.requestFullscreen().catch(err => {
+                    alert(`Can't enable the fullscreen mode. ` + err.toString());
+                });
+            }
+            else {
+                this._viewport.exitFullscreen();
+            }
+        });
+
+        return button;
+    }
+
+    /**
+     * Handle a fullscreenchange event
+     */
+    private _handleFullscreenEvent(event: Event): void
+    {
+        const icon = this._button.querySelector('img') as HTMLImageElement;
+        icon.src = this._viewport.fullscreen ? BUTTON_ICON_ON : BUTTON_ICON_OFF;
+    }
+}

src/ui/stats-panel.ts

@@ -240,39 +240,6 @@ export class StatsPanel
         print('<br>');
         print('OUT: <span class="_ar_out"></span>');
 
-        if(this._viewport.fullscreenAvailable) {
-            print('<br>');
-            content.appendChild(this._createFullscreenToggle());
-        }
-
         return content;
     }
-
-    /**
-     * Create a fullscreen toggle
-     * @returns a fullscreen toggle
-     */
-    private _createFullscreenToggle(): HTMLElement
-    {
-        const toggle = document.createElement('a');
-
-        Utils.assert(this._viewport != null);
-
-        toggle.href = 'javascript:void(0)';
-        toggle.innerText = 'Toggle fullscreen';
-        toggle.style.color = 'white';
-        toggle.setAttribute('role', 'button');
-        toggle.addEventListener('click', () => {
-            if(!this._viewport.fullscreen) {
-                this._viewport.requestFullscreen().catch(err => {
-                    alert(`Can't enable fullscreen mode. ` + err.toString());
-                });
-            }
-            else {
-                this._viewport.exitFullscreen();
-            }
-        });
-
-        return toggle;
-    }
 }