Introduce Viewport.convertToPixels()

docs/api/trackable-pointer.md

@@ -4,7 +4,7 @@ A [trackable](trackable.md) that represents a pointer tracked by a [PointerTrack
 
 A pointer is an abstraction that represents an instance of user input that targets one or more coordinates on a screen. For example, each point of contact between fingers and a multitouch screen generate a pointer. Devices such as a mouse and a pen/stylus also generate pointers.
 
-Pointers are positioned in the [viewport](viewport.md). Their positions are given in normalized units, which range from -1 to +1. The center of the viewport is at (0,0). The top-right corner is at (1,1). The bottom-left corner is at (-1,-1).
+Pointers are positioned in the [viewport](viewport.md). Their positions are given in normalized units, which range from -1 to +1. The center of the viewport is at (0,0). The top right corner is at (1,1). The bottom left corner is at (-1,-1).
 
 *Since:* 0.4.0
 
@@ -32,7 +32,7 @@ The phase of the pointer. It's one of the following strings:
 
 `pointer.position: Vector2, read-only`
 
-The current position of the pointer, given in normalized units.
+The current position of the pointer, given in normalized units. See also: [Viewport.convertToPixels](viewport.md#converttopixels).
 
 ### initialPosition
 

docs/api/viewport.md

@@ -63,7 +63,7 @@ The size in pixels that matches the [resolution](#resolution) of the virtual sce
 
 `viewport.canvas: HTMLCanvasElement, read-only`
 
-A `<canvas>` on which the virtual scene is drawn.
+The `<canvas>` on which the virtual scene is drawn.
 
 ### style
 
@@ -146,6 +146,22 @@ Exit fullscreen mode.
 
 A promise that is resolved once the fullscreen mode is no longer active, or rejected on error. The promise will be rejected if the method is called when not in fullscreen mode.
 
+### convertToPixels
+
+`viewport.convertToPixels(position: Vector2): Vector2`
+
+Convert a `position` given in normalized units to a corresponding pixel position in [canvas](#canvas) space. Normalized units range from -1 to +1. The center of the canvas is at (0,0). The top right corner is at (1,1). The bottom left corner is at (-1,-1).
+
+*Since:* 0.4.0
+
+**Arguments**
+
+`position: Vector2`. A position in normalized units.
+
+**Returns**
+
+An equivalent pixel position in canvas space.
+
 ## Events
 
 A viewport is an [AREventTarget](ar-event-target.md). You can listen to the following events:
@@ -164,7 +180,7 @@ viewport.addEventListener('resize', () => {
 
 ### fullscreenchange
 
-The viewport has been switched into or out of fullscreen mode.
+The viewport has been switched to or out of fullscreen mode.
 
 *Since:* 0.3.0
 
@@ -173,7 +189,7 @@ The viewport has been switched into or out of fullscreen mode.
 ```js
 viewport.addEventListener('fullscreenchange', () => {
     if(viewport.fullscreen)
-        console.log('Switched into fullscreen mode');
+        console.log('Switched to fullscreen mode');
     else
         console.log('Switched out of fullscreen mode');
 });

src/core/viewport.ts

@@ -24,12 +24,13 @@ import AR from '../main';
 import Speedy from 'speedy-vision';
 import { SpeedySize } from 'speedy-vision/types/core/speedy-size';
 import { SpeedyPromise } from 'speedy-vision/types/core/speedy-promise';
-import { Nullable } from '../utils/utils';
-import { Resolution } from '../utils/resolution';
-import { Utils } from '../utils/utils';
 import { SessionMode } from './session';
 import { HUD, HUDContainer } from './hud';
 import { FullscreenButton } from '../ui/fullscreen-button';
+import { Vector2 } from '../geometry/vector2';
+import { Resolution } from '../utils/resolution';
+import { Nullable } from '../utils/utils';
+import { Utils } from '../utils/utils';
 import { AREvent, AREventTarget, AREventListener } from '../utils/ar-events';
 import { IllegalArgumentError, IllegalOperationError, NotSupportedError, AccessDeniedError } from '../utils/errors';
 
@@ -979,6 +980,23 @@ export class Viewport extends ViewportEventTarget
     }
 
     /**
+     * Convert a position given in normalized units to a corresponding pixel
+     * position in canvas space. Normalized units range from -1 to +1. The
+     * center of the canvas is at (0,0). The top right corner is at (1,1).
+     * The bottom left corner is at (-1,-1).
+     * @param position in normalized units
+     * @returns an equivalent pixel position in canvas space
+     */
+    convertToPixels(position: Vector2): Vector2
+    {
+        const canvas = this.canvas;
+        const x = 0.5 * (1 + position.x) * canvas.width;
+        const y = -0.5 * (1 + position.y) * canvas.height;
+
+        return new Vector2(x, y);
+    }
+
+    /**
      * Initialize the viewport (when the session starts)
      * @param getMediaSize
      * @param sessionMode