Introduce viewport styles. Improvements to the code

docs/api/viewport.md

     * `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.2.1
 
 **Returns**
 
 
 The [resolution](resolution.md) of the virtual scene.
 
+### virtualSize
+
+`viewport.virtualSize: SpeedySize, read-only`
+
+The size in pixels that matches the [resolution](#resolution) of the virtual scene.
+
 ### canvas
 
 `viewport.canvas: HTMLCanvasElement, read-only`
 
 A `<canvas>` on which the virtual scene is drawn.
 
-### virtualSize
+### style
 
-`viewport.virtualSize: SpeedySize, read-only`
+`viewport.style: string`
 
-The size in pixels that matches the [resolution](#resolution) of the virtual scene.
+The style determines the way the viewport appears on the screen. Different styles are applicable to different [session modes](session.md#mode). The following are valid styles:
+
+* `"best-fit"`: an immersive viewport that is scaled in a way that covers the page while preserving the aspect ratio of the augmented scene.
+* `"stretch"`: an immersive viewport that is scaled in a way that covers the entire page, stretching the augmented scene if necessary.
+* `"inline"`: an inline viewport that follows the typical flow of a web page.
+
+The default style is `"best-fit"` in immersive mode, or `"inline"` in inline mode.
+
+*Since:* 0.2.1
 
 ## Events
 
 
 ### resize
 
-The viewport has been resized. This may happen when the user resizes the window of the web browser or when the mobile device is flipped.
+The viewport has been resized. This will happen when the user resizes the window of the web browser or when the mobile device is flipped.
 
 **Example**
 

src/core/gizmos.ts

             return;
 
         // viewport
-        const viewportSize = viewport._size;
-        const canvas = viewport._background;
+        const viewportSize = viewport._realSize;
+        const canvas = viewport._backgroundCanvas;
         const ctx = canvas.getContext('2d', { alpha: false });
         if(!ctx)
             throw new IllegalOperationError();

src/core/session.ts

 import { Nullable, Utils } from '../utils/utils';
 import { AREvent, AREventTarget } from '../utils/ar-events';
 import { IllegalArgumentError, IllegalOperationError, NotSupportedError } from '../utils/errors';
-import { Viewport, ImmersiveViewport, InlineViewport } from './viewport';
+import { Viewport, BaseViewport, ImmersiveViewport, InlineViewport } from './viewport';
 import { Settings } from './settings';
 import { Stats } from './stats';
 import { StatsPanel } from './stats-panel';
     sources: Source[];
 
     /** viewport */
-    viewport: Nullable<Viewport>;
+    viewport: Nullable<BaseViewport>;
 
     /** show stats? */
     stats?: boolean;
      * @param stats render stats panel?
      * @param gizmos render gizmos?
      */
-    private constructor(sources: Source[], mode: SessionMode, viewport: Viewport, stats: boolean, gizmos: boolean)
+    private constructor(sources: Source[], mode: SessionMode, viewport: BaseViewport, stats: boolean, gizmos: boolean)
     {
         super();
 
      */
     private _renderUserMedia(): void
     {
-        const canvas = this._viewport._background;
+        const canvas = this._viewport._backgroundCanvas;
         const ctx = canvas.getContext('2d', { alpha: false });
         
         if(ctx && this.media.type != 'data') {

src/core/viewport.ts

 import { AREvent, AREventTarget, AREventListener } from '../utils/ar-events';
 
 
+
 /** Viewport container */
 export type ViewportContainer = HTMLDivElement;
 
 /** An event emitted by a Viewport */
 class ViewportEvent extends AREvent<ViewportEventType> { }
 
+/** Viewport event target */
+class ViewportEventTarget extends AREventTarget<ViewportEventType> { }
+
+/** Viewport style (immersive mode) */
+type ViewportStyle = 'best-fit' | 'stretch' | 'inline';
+
+
+
 /**
  * Viewport interface
  */
-export interface Viewport extends AREventTarget<ViewportEventType>
+export interface Viewport extends ViewportEventTarget
 {
     /** Resolution of the virtual scene */
     readonly resolution: Resolution;
     /** Viewport container */
     readonly container: ViewportContainer;
 
+    /** Viewport style */
+    style: ViewportStyle;
+
     /** HUD */
     readonly hud: HUD;
 
-    /** Size of the drawing buffer of the foreground canvas */
-    readonly virtualSize: SpeedySize;
-
     /** Canvas on which the virtual scene will be drawn */
     readonly canvas: HTMLCanvasElement;
 
+    /** Size of the drawing buffer of the foreground canvas */
+    readonly virtualSize: SpeedySize;
+
     /** Canvas on which the physical scene will be drawn @internal */
-    readonly _background: HTMLCanvasElement;
+    readonly _backgroundCanvas: HTMLCanvasElement;
 
     /** Size of the drawing buffer of the background canvas @internal */
-    readonly _size: SpeedySize;
+    readonly _realSize: SpeedySize;
 
     /** Initialize the viewport @internal */
     _init(): void;
 
     /** Release the viewport @internal */
     _release(): void;
-
-    /** Function to be called when the viewport is resized @internal */
-    _onResize(): void;
 }
 
 /**
     /** Resolution of the canvas on which the virtual scene will be drawn */
     resolution?: Resolution;
 
+    /** Viewport style */
+    style?: ViewportStyle;
+
     /** An existing <canvas> on which the virtual scene will be drawn */
     canvas?: Nullable<HTMLCanvasElement>;
 }
     container: null,
     hudContainer: null,
     resolution: 'lg',
+    style: 'best-fit',
     canvas: null,
 };
 
+/** Z-index of the viewport container */
+const CONTAINER_ZINDEX = 1000000000;
+
 /** Base z-index of the children of the viewport container */
 const BASE_ZINDEX = 0;
 
+/** Z-index of the background canvas */
+const BACKGROUND_ZINDEX = BASE_ZINDEX + 0;
+
+/** Z-index of the foreground canvas */
+const FOREGROUND_ZINDEX = BASE_ZINDEX + 1;
+
+/** Z-index of the HUD */
+const HUD_ZINDEX = BASE_ZINDEX + 2;
+
 /** Default viewport width, in pixels */
 const DEFAULT_VIEWPORT_WIDTH = 300;
 
 /**
  * Viewport
  */
-export class BaseViewport extends AREventTarget<ViewportEventType> implements Viewport
+export class BaseViewport extends ViewportEventTarget implements Viewport
 {
     /** Viewport resolution (controls the size of the drawing buffer of the foreground canvas) */
     private readonly _resolution: Resolution;
     /** An overlay displayed in front of the augmented scene */
     protected readonly _hud: HUD;
 
+    /** Viewport style */
+    protected _style: ViewportStyle;
+
     /** Internal canvas used to render the physical scene */
-    protected readonly _backgroundCanvas: HTMLCanvasElement;
+    private readonly __backgroundCanvas: HTMLCanvasElement;
 
     /** A canvas used to render the virtual scene */
     protected readonly _foregroundCanvas: HTMLCanvasElement;
     {
         super();
 
-        // validate settings
         const settings = Object.assign({}, DEFAULT_VIEWPORT_SETTINGS, viewportSettings);
+        const size = Speedy.Size(DEFAULT_VIEWPORT_WIDTH, DEFAULT_VIEWPORT_HEIGHT);
+
+        // validate settings
         if(settings.container == null)
             throw new IllegalArgumentError('Unspecified viewport container');
+        else if(!(settings.container instanceof HTMLElement))
+            throw new IllegalArgumentError('Invalid viewport container');
 
         // initialize attributes
         this._resolution = settings.resolution;
         this._container = settings.container;
         this._hud = new HUD(settings.container, settings.hudContainer);
-        this._parentOfImportedForegroundCanvas = settings.canvas ? settings.canvas.parentNode : null;
 
-        // create canvas elements
-        const size = Speedy.Size(DEFAULT_VIEWPORT_WIDTH, DEFAULT_VIEWPORT_HEIGHT);
-        this._backgroundCanvas = this._createBackgroundCanvas(this._container, size);
-        this._foregroundCanvas = settings.canvas == null ?
-            this._createForegroundCanvas(this._container, size) :
-            this._foregroundCanvas = this._importForegroundCanvas(settings.canvas, this._container, size);
+        // make this more elegant?
+        // need to initialize this._style and validate settings.style
+        this._style = DEFAULT_VIEWPORT_SETTINGS.style;
+        this.style = settings.style;
+
+        // create the background canvas
+        this.__backgroundCanvas = this._createBackgroundCanvas(this._container, size);
+
+        // create the foreground canvas
+        if(settings.canvas == null) {
+            this._foregroundCanvas = this._createForegroundCanvas(this._container, size);
+            this._parentOfImportedForegroundCanvas = null;
+        }
+        else {
+            this._foregroundCanvas = settings.canvas;
+            this._parentOfImportedForegroundCanvas = settings.canvas.parentNode;
+        }
     }
 
     /**
     }
 
     /**
+     * Viewport style
+     */
+    get style(): ViewportStyle
+    {
+        return this._style;
+    }
+
+    /**
+     * Set viewport style
+     */
+    set style(value: ViewportStyle)
+    {
+        if(value != 'best-fit' && value != 'stretch' && value != 'inline')
+            throw new IllegalArgumentError('Invalid viewport style: ' + value);
+
+        this._style = value;
+    }
+
+    /**
      * HUD
      */
     get hud(): HUD
     }
 
     /**
-     * Background canvas
+     * The canvas on which the physical scene will be drawn
      * @internal
      */
-    get _background(): HTMLCanvasElement
+    get _backgroundCanvas(): HTMLCanvasElement
     {
-        return this._backgroundCanvas;
+        return this.__backgroundCanvas;
     }
 
     /**
      * Size of the drawing buffer of the background canvas, in pixels
      * @internal
      */
-    get _size(): SpeedySize
+    get _realSize(): SpeedySize
     {
         throw new IllegalOperationError();
     }
      */
     _init(): void
     {
+        // import foreground canvas
+        if(this._parentOfImportedForegroundCanvas != null) {
+            const size = Speedy.Size(DEFAULT_VIEWPORT_WIDTH, DEFAULT_VIEWPORT_HEIGHT);
+            this._importForegroundCanvas(this._foregroundCanvas, this._container, size);
+        }
+
+        // setup CSS
         this._container.style.touchAction = 'none';
-        this._hud._init(BASE_ZINDEX + 2);
+
+        // initialize the HUD
+        this._hud._init(HUD_ZINDEX);
         this._hud.visible = true;
     }
 
      */
     _release(): void
     {
-        //this._hud.visible = false; // depends on the type of the viewport
+        // release the HUD
         this._hud._release();
-        this._restoreImportedForegroundCanvas();
+
+        // reset the CSS
         this._container.style.touchAction = 'auto';
+
+        // restore imported canvas
+        if(this._parentOfImportedForegroundCanvas != null)
+            this._restoreImportedForegroundCanvas();
     }
 
     /**
-     * Function to be called when the viewport is resized
-     * @internal
+     * Create a canvas and attach it to another HTML element
+     * @param parent parent container
+     * @param size size of the drawing buffer
+     * @returns a new canvas as a child of parent
      */
-    _onResize(): void
+    private _createCanvas(parent: HTMLElement, size: SpeedySize): HTMLCanvasElement
     {
-        // Resize the drawing buffer of the foreground canvas, so that it
-        // matches the desired resolution and the aspect ratio of the
-        // background canvas
-        const virtualSize = this.virtualSize;
-        this._foregroundCanvas.width = virtualSize.width;
-        this._foregroundCanvas.height = virtualSize.height;
-        this._styleCanvas(this._foregroundCanvas, 'foreground');
+        const canvas = document.createElement('canvas') as HTMLCanvasElement;
 
-        // dispatch event
-        const event = new ViewportEvent('resize');
-        this.dispatchEvent(event);
+        canvas.width = size.width;
+        canvas.height = size.height;
+        parent.appendChild(canvas);
+
+        return canvas;
     }
 
     /**
     private _createBackgroundCanvas(parent: ViewportContainer, size: SpeedySize): HTMLCanvasElement
     {
         const canvas = this._createCanvas(parent, size);
-        return this._styleCanvas(canvas, 'background');
+        return this._styleCanvas(canvas, BACKGROUND_ZINDEX);
     }
 
     /**
     private _createForegroundCanvas(parent: ViewportContainer, size: SpeedySize): HTMLCanvasElement
     {
         const canvas = this._createCanvas(parent, size);
-        return this._styleCanvas(canvas, 'foreground');
-    }
-
-    /**
-     * Create a canvas and attach it to another HTML element
-     * @param parent parent container
-     * @param size size of the drawing buffer
-     * @returns a new canvas as a child of parent
-     */
-    private _createCanvas(parent: HTMLElement, size: SpeedySize): HTMLCanvasElement
-    {
-        const canvas = document.createElement('canvas') as HTMLCanvasElement;
-
-        canvas.width = size.width;
-        canvas.height = size.height;
-        parent.appendChild(canvas);
-
-        return canvas;
-    }
-
-    /**
-     * Add suitable CSS rules to a canvas
-     * @param canvas
-     * @param canvasType
-     * @returns canvas
-     */
-    private _styleCanvas(canvas: HTMLCanvasElement, canvasType: 'foreground' | 'background'): HTMLCanvasElement
-    {
-        const offset = (canvasType == 'foreground') ? 1 : 0;
-        const zIndex = BASE_ZINDEX + offset;
-
-        canvas.setAttribute('style', [
-            'position: absolute',
-            'left: 0px',
-            'top: 0px',
-
-            'z-index: ' + String(zIndex),
-
-            'width: 100% !important',
-            'height: 100% !important',
-        ].join('; '));
-
-        return canvas;
+        return this._styleCanvas(canvas, FOREGROUND_ZINDEX);
     }
 
     /**
     private _importForegroundCanvas(canvas: HTMLCanvasElement, parent: ViewportContainer, size: SpeedySize): HTMLCanvasElement
     {
         if(!(canvas instanceof HTMLCanvasElement))
-            throw new IllegalArgumentError(`Not a <canvas>: ${canvas}`);
+            throw new IllegalArgumentError('Not a canvas: ' + canvas);
 
         // borrow the canvas; add it as a child of the viewport container
         canvas.remove();
 
         canvas.dataset.cssText = canvas.style.cssText; // save CSS
         canvas.style.cssText = ''; // clear CSS
-        this._styleCanvas(canvas, 'foreground');
+        this._styleCanvas(canvas, FOREGROUND_ZINDEX);
 
         return canvas;
     }
     {
         // not an imported canvas; nothing to do
         if(this._parentOfImportedForegroundCanvas == null)
-            return;
+            throw new IllegalOperationError();
 
         const canvas = this._foregroundCanvas;
         canvas.style.cssText = canvas.dataset.cssText || ''; // restore CSS
         canvas.remove();
         this._parentOfImportedForegroundCanvas.appendChild(canvas);
     }
+
+    /**
+     * Add suitable CSS rules to a canvas
+     * @param canvas
+     * @param canvasType
+     * @returns canvas
+     */
+    private _styleCanvas(canvas: HTMLCanvasElement, zIndex: number): HTMLCanvasElement
+    {
+        canvas.style.position = 'absolute';
+        canvas.style.left = '0px';
+        canvas.style.top = '0px';
+        canvas.style.width = '100%';
+        canvas.style.height = '100%';
+        canvas.style.zIndex = String(zIndex);
+
+        return canvas;
+    }
 }
 
 /**
  * Viewport decorator
  */
-abstract class ViewportDecorator extends AREventTarget<ViewportEventType> implements Viewport
+abstract class ViewportDecorator extends ViewportEventTarget implements Viewport
 {
     /** The decorated viewport */
     private _base: Viewport;
     }
 
     /**
+     * Viewport style
+     */
+    get style(): ViewportStyle
+    {
+        return this._base.style;
+    }
+
+    /**
+     * Set viewport style
+     */
+    set style(value: ViewportStyle)
+    {
+        this._base.style = value;
+    }
+
+    /**
      * HUD
      */
     get hud(): HUD
      * Background canvas
      * @internal
      */
-    get _background(): HTMLCanvasElement
+    get _backgroundCanvas(): HTMLCanvasElement
     {
-        return this._base._background;
+        return this._base._backgroundCanvas;
     }
 
     /**
      * Size of the drawing buffer of the background canvas, in pixels
      * @internal
      */
-    get _size(): SpeedySize
+    get _realSize(): SpeedySize
     {
         return this._getSize();
     }
     }
 
     /**
-     * Function to be called when the viewport is resized
-     * @internal
-     */
-    _onResize(): void
-    {
-        this._base._onResize();
-    }
-
-    /**
      * Add event listener
      * @param type event type
      * @param callback
     /** is this viewport subject to being resized? */
     private _active: boolean;
 
+    /** a bound _onResize */
+    private _resize: () => void;
+
 
 
     /**
      * @param base to be decorated
      * @param getSize size getter
      */
-    constructor(base: Viewport, getSize: ViewportSizeGetter)
+    constructor(base: BaseViewport, getSize: ViewportSizeGetter)
     {
         super(base, getSize);
         this._active = false;
+        this._resize = this._onResize.bind(this);
     }
 
     /**
-     * Resize the viewport
-     */
-    protected abstract _resize(): void;
-
-    /**
      * Initialize the viewport
      * @internal
      */
 
             timeout = setTimeout(() => {
                 timeout = null;
-                this._resize.call(this);
-                this._onResize.call(this);
+                this._resize();
             }, 100);
         };
-
         window.addEventListener('resize', onresize);
-        this._resize();
-        this._onResize();
+
+        // handle changes of orientation
+        // (is this needed? we already listen to resize events)
+        if(screen.orientation !== undefined)
+            screen.orientation.addEventListener('change', this._resize);
+        else
+            window.addEventListener('orientationchange', this._resize); // deprecated
+
+        // trigger a resize to setup the sizes / the CSS
+        setTimeout(this._resize, 0);
     }
 
     /**
      */
     _release(): void
     {
+        if(screen.orientation !== undefined)
+            screen.orientation.removeEventListener('change', this._resize);
+        else
+            window.removeEventListener('orientationchange', this._resize); // deprecated
+
         this._active = false;
         super._release();
     }
+
+    /**
+     * Function to be called when the viewport is resized
+     */
+    protected _onResize(): void
+    {
+        // Resize the drawing buffer of the foreground canvas, so that it
+        // matches the desired resolution, as well as the aspect ratio of the
+        // background canvas
+        const foregroundCanvas = this.canvas;
+        const virtualSize = this.virtualSize;
+        foregroundCanvas.width = virtualSize.width;
+        foregroundCanvas.height = virtualSize.height;
+
+        // Resize the drawing buffer of the background canvas
+        const backgroundCanvas = this._backgroundCanvas;
+        const realSize = this._realSize;
+        backgroundCanvas.width = realSize.width;
+        backgroundCanvas.height = realSize.height;
+
+        // dispatch event
+        const event = new ViewportEvent('resize');
+        this.dispatchEvent(event);
+    }
 }
 
 /**
 export class ImmersiveViewport extends ResizableViewport
 {
     /**
+     * Initialize the viewport
+     * @internal
+     */
+    _init(): void
+    {
+        super._init();
+
+        this.container.style.zIndex = String(CONTAINER_ZINDEX);
+        this.container.style.backgroundColor = 'black';
+    }
+
+    /**
      * Release the viewport
      * @internal
      */
     _release(): void
     {
         this.canvas.remove();
-        this._background.remove();
+        this._backgroundCanvas.remove();
         this.hud.visible = false;
         this.container.style.cssText = ''; // reset CSS
 
      * Resize the immersive viewport, so that it occupies the entire page.
      * We respect the aspect ratio of the source media
      */
-    protected _resize(): void
+    protected _onResize(): void
     {
-        const { width, height } = this._size;
-        const viewportSize = Speedy.Size(0, 0);
-        const viewportAspectRatio = width / height;
-        const windowSize = Speedy.Size(window.innerWidth, window.innerHeight);
-        const windowAspectRatio = windowSize.width / windowSize.height;
-
-        // figure out the viewport size
-        if(viewportAspectRatio <= windowAspectRatio) {
-            viewportSize.height = windowSize.height;
-            viewportSize.width = (viewportSize.height * viewportAspectRatio) | 0;
-        }
-        else {
-            viewportSize.width = windowSize.width;
-            viewportSize.height = (viewportSize.width / viewportAspectRatio) | 0;
-        }
+        super._onResize();
 
-        // position the viewport and set its size
         const container = this.container;
         container.style.position = 'fixed';
-        container.style.left = `calc(50% - ${viewportSize.width >>> 1}px)`;
-        container.style.top = `calc(50% - ${viewportSize.height >>> 1}px)`;
-        container.style.zIndex = '1000000000'; // 1B //String(2147483647);
-        container.style.width = viewportSize.width + 'px';
-        container.style.height = viewportSize.height + 'px';
-        container.style.backgroundColor = '#000';
-
-        // set the size of the drawing buffer of the background canvas
-        const backgroundCanvas = this._background;
-        const backgroundCanvasAspectRatio = viewportAspectRatio;
-        const referenceHeight = height;
-        backgroundCanvas.height = referenceHeight;
-        backgroundCanvas.width = (backgroundCanvas.height * backgroundCanvasAspectRatio) | 0;
+
+        if(this.style == 'best-fit') {
+            // cover the page while maintaining the aspect ratio
+            let viewportWidth = 0, viewportHeight = 0;
+            const windowAspectRatio = window.innerWidth / window.innerHeight;
+            const viewportAspectRatio = this._realSize.width / this._realSize.height;
+
+            if(viewportAspectRatio <= windowAspectRatio) {
+                viewportHeight = window.innerHeight;
+                viewportWidth = (viewportHeight * viewportAspectRatio) | 0;
+            }
+            else {
+                viewportWidth = window.innerWidth;
+                viewportHeight = (viewportWidth / viewportAspectRatio) | 0;
+            }
+
+            container.style.left = `calc(50% - ${viewportWidth >>> 1}px)`;
+            container.style.top = `calc(50% - ${viewportHeight >>> 1}px)`;
+            container.style.width = viewportWidth + 'px';
+            container.style.height = viewportHeight + 'px';
+        }
+        else if(this.style == 'stretch') {
+            // stretch to cover the entire page
+            container.style.left = '0px';
+            container.style.top = '0px';
+            container.style.width = window.innerWidth + 'px';
+            container.style.height = window.innerHeight + 'px';
+        }
+        else
+            throw new IllegalOperationError('Invalid immersive viewport style: ' + this.style);
     }
 }
 
 export class InlineViewport extends ResizableViewport
 {
     /**
+     * Initialize the viewport
+     * @internal
+     */
+    _init(): void
+    {
+        super._init();
+        this.style = 'inline';
+
+        this.container.style.zIndex = String(CONTAINER_ZINDEX);
+        this.container.style.backgroundColor = 'black';
+    }
+
+    /**
+     * Release the viewport
+     * @internal
+     */
+    _release(): void
+    {
+        this.container.style.cssText = ''; // reset CSS
+        super._release();
+    }
+
+    /**
      * Resize the inline viewport
+     * (we still take into account orientation changes)
      */
-    protected _resize(): void
+    protected _onResize(): void
     {
-        const { width, height } = this._size;
+        super._onResize();
 
-        this.container.style.position = 'relative';
-        this.container.style.width = width + 'px';
-        this.container.style.height = height + 'px';
-        //this.container.style.display = 'inline-block';
+        const container = this.container;
+        container.style.position = 'relative';
 
-        this._background.width = width;
-        this._background.height = height;
+        if(this.style == 'inline') {
+            container.style.left = '0px';
+            container.style.top = '0px';
+            container.style.width = this._realSize.width + 'px';
+            container.style.height = this._realSize.height + 'px';
+        }
+        else
+            throw new IllegalOperationError('Invalid inline viewport style: ' + this.style);
     }
 }