Document the babylon.js and the three.js plugins

docs/api/plugin-babylon.md

@@ -0,0 +1,298 @@
+# Babylon.js plugin
+
+Documentation of the [babylon.js](https://www.babylonjs.com){ ._blank } plugin. Study the [demos](../demos.md) for practical examples.
+
+*Since:* 0.3.0
+
+## Basics
+
+### Lifecycle
+
+The following diagram shows, in a simplified manner, the lifecycle of an AR experience. The rectangular blocks represent methods of your [ARDemo](#ardemo). Function [encantar](#encantar) starts the magic.
+
+![Lifecycle of an AR experience](/img/lifecycle-plugin.png)
+
+!!! tip
+
+    Use event listeners to detect events such as [finding an image](./image-tracker.md#events) in a camera feed.
+
+### encantar
+
+`encantar(demo: ARDemo): Promise<ARSystem>`
+
+The `encantar` function *enchants* a `demo`, meaning: it starts the [lifecycle](#lifecycle) of the AR experience.
+
+**Arguments**
+
+* `demo: ARDemo`. Your demo. See also: [ARDemo](#ardemo)
+
+**Returns**
+
+A promise that resolves to an [ARSystem](#arsystem) when the demo starts.
+
+**Example**
+
+```js
+function main()
+{
+    const demo = new MyDemo(); // class MyDemo extends ARDemo
+
+    encantar(demo).catch(error => {
+        alert(error.message);
+    });
+}
+
+document.addEventListener('DOMContentLoaded', main);
+```
+
+!!! note
+
+    You should **not** call [session.requestAnimationFrame()](./session.md#requestanimationframe) when using this plugin. The plugin already calls it.
+
+## ARDemo
+
+`ARDemo` is the base class for Augmented Reality experiences. It's an abstract class, meaning that you must extend it. It operates within the [lifecycle](#lifecycle) of your AR experience. The plugin will call its methods and control the flow of the program. Simply call [encantar](#encantar) to start the magic!
+
+### ar
+
+`demo.ar: ARSystem | null, read-only`
+
+A reference to the [ARSystem](#arsystem), or `null` if the demo hasn't been started yet. See also: [lifecycle](#lifecycle)
+
+*Since:* 0.4.0
+
+### startSession
+
+`demo.startSession(): Promise<Session> | SpeedyPromise<Session>`
+
+Start the AR [Session](session.md). This method receives no arguments. It's supposed to call [AR.startSession](session.md#instantiation) with the desired settings.
+
+**Returns**
+
+A promise that resolves to a Session.
+
+!!! warning "Important"
+
+    This is an abstract method. You **must** implement it.
+
+!!! info "Fact"
+
+    The tracking begins when the session is started.
+
+### init
+
+`demo.init(): void | Promise<void> | SpeedyPromise<void>`
+
+Use this method to initialize your 3D scene. See also: [ar](#ar), [preload](#preload)
+
+**Returns**
+
+`undefined`, or a promise that resolves to `undefined`.
+
+**Example**
+
+```js
+class MyDemo extends ARDemo
+{
+    // ...
+
+    init()
+    {
+        const ar = this.ar;
+        const scene = ar.scene;
+
+        // initialize the scene
+        // ...
+    }
+
+    // ...
+}
+```
+
+!!! tip
+
+    Load external assets in [preload](#preload). Method `init` shouldn't take too long to run because the session is already started. See also: [lifecycle](#lifecycle)
+
+### update
+
+`demo.update(): void`
+
+Animation step, called during the animation loop. You may want to do something with [ar.session](#session) or [ar.frame](#frame).
+
+**Example**
+
+```js
+class MyDemo extends ARDemo
+{
+    // ...
+
+    update()
+    {
+        const ar = this.ar;
+        const session = ar.session;
+        const deltaTime = session.time.delta; // given in seconds
+
+        // ...
+    }
+
+    // ...
+}
+```
+
+### release
+
+`release(): void`
+
+Release resources soon after the AR session is ended.
+
+### preload
+
+`preload(): Promise<void> | SpeedyPromise<void>`
+
+Preload resources before starting the AR session. See also: [init](#init), [startSession](#startsession)
+
+*Since:* 0.4.0
+
+**Returns**
+
+A promise that resolves to `undefined`.
+
+## ARSystem
+
+`ARSystem` is a helper for creating Augmented Reality experiences. Access it via [ARDemo.ar](#ar).
+
+### session
+
+`ar.session: Session, read-only`
+
+A reference to the AR [Session](session.md).
+
+### frame
+
+`ar.frame: Frame | null, read-only`
+
+A reference to the current [Frame](frame.md). This will be `null` if the demo hasn't been started yet, or if the session has been ended. See also: [lifecycle](#lifecycle)
+
+### viewer
+
+`ar.viewer: Viewer | null, read-only`
+
+A reference to the [Viewer](viewer.md). This will be `null` if the [frame](#frame) is `null`.
+
+*Since:* 0.4.0
+
+### pointers
+
+`ar.pointers: TrackablePointer[], read-only`
+
+An array of [TrackablePointers](trackable-pointer.md).
+
+*Since:* 0.4.0
+
+!!! tip
+
+    Make sure to add a [PointerTracker](pointer-tracker.md) to your session in order to use these.
+
+### root
+
+`ar.root: BABYLON.TransformNode, read-only`
+
+A node that is automatically aligned to the physical scene.
+
+!!! warning "Important"
+
+    In most cases, objects of your virtual scene should be descendants of this node!
+
+### camera
+
+`ar.camera: BABYLON.Camera, read-only`
+
+A camera that is automatically adjusted for AR.
+
+### scene
+
+`ar.scene: BABYLON.Scene, read-only`
+
+The babylon.js scene.
+
+### engine
+
+`ar.engine: BABYLON.Engine, read-only`
+
+The babylon.js engine.
+
+### utils
+
+`ar.utils: ARUtils, read-only`
+
+[Utilities](#arutils) object.
+
+*Since:* 0.4.0
+
+## ARUtils
+
+Utilities object.
+
+### convertVector2
+
+`ar.utils.convertVector2(v: Vector2): BABYLON.Vector2`
+
+Convert a [Vector2](./vector2.md) into a `BABYLON.Vector2`.
+
+*Since:* 0.4.0
+
+**Arguments**
+
+* `v: Vector2`. A 2D vector.
+
+**Returns**
+
+A corresponding `BABYLON.Vector2`.
+
+### convertVector3
+
+`ar.utils.convertVector3(v: Vector3): BABYLON.Vector3`
+
+Convert a [Vector3](./vector3.md) into a `BABYLON.Vector3`.
+
+*Since:* 0.4.0
+
+**Arguments**
+
+* `v: Vector3`. A 3D vector.
+
+**Returns**
+
+A corresponding `BABYLON.Vector3`.
+
+### convertQuaternion
+
+`ar.utils.convertQuaternion(q: Quaternion): BABYLON.Quaternion`
+
+Convert a [Quaternion](./quaternion.md) into a `BABYLON.Quaternion`.
+
+*Since:* 0.4.0
+
+**Arguments**
+
+* `q: Quaternion`. A quaternion.
+
+**Returns**
+
+A corresponding `BABYLON.Quaternion`.
+
+### convertRay
+
+`ar.utils.convertRay(r: Ray): BABYLON.Ray`
+
+Convert a [Ray](./ray.md) into a `BABYLON.Ray`.
+
+*Since:* 0.4.0
+
+**Arguments**
+
+* `r: Ray`. A ray.
+
+**Returns**
+
+A corresponding `BABYLON.Ray`.

docs/api/plugin-three.md

@@ -0,0 +1,311 @@
+# Three.js plugin
+
+Documentation of the [three.js](https://threejs.org){ ._blank } plugin. Study the [demos](../demos.md) for practical examples.
+
+## Basics
+
+### Lifecycle
+
+The following diagram shows, in a simplified manner, the lifecycle of an AR experience. The rectangular blocks represent methods of your [ARDemo](#ardemo). Function [encantar](#encantar) starts the magic.
+
+![Lifecycle of an AR experience](/img/lifecycle-plugin.png)
+
+<pre style="display:none">
+mermaid
+flowchart TD
+    _((start)) -->|encantar called| A[preload]
+    A --> B[startSession]
+    B -->|session started| C[init]
+    C -->|demo started| D[update]
+    ? -->|animation loop| D
+    D --> ?{{Session active?}}
+    ? -->|session ended| E[release]
+    E -->|demo ended| Z((end))
+</pre>
+
+!!! tip
+
+    Use event listeners to detect events such as [finding an image](./image-tracker.md#events) in a camera feed.
+
+### encantar
+
+`encantar(demo: ARDemo): Promise<ARSystem>`
+
+The `encantar` function *enchants* a `demo`, meaning: it starts the [lifecycle](#lifecycle) of the AR experience.
+
+*Since:* 0.3.0
+
+**Arguments**
+
+* `demo: ARDemo`. Your demo. See also: [ARDemo](#ardemo)
+
+**Returns**
+
+A promise that resolves to an [ARSystem](#arsystem) when the demo starts.
+
+**Example**
+
+```js
+function main()
+{
+    const demo = new MyDemo(); // class MyDemo extends ARDemo
+
+    encantar(demo).catch(error => {
+        alert(error.message);
+    });
+}
+
+document.addEventListener('DOMContentLoaded', main);
+```
+
+!!! note
+
+    You should **not** call [session.requestAnimationFrame()](./session.md#requestanimationframe) when using this plugin. The plugin already calls it.
+
+## ARDemo
+
+`ARDemo` is the base class for Augmented Reality experiences. It's an abstract class, meaning that you must extend it. It operates within the [lifecycle](#lifecycle) of your AR experience. The plugin will call its methods and control the flow of the program. Simply call [encantar](#encantar) to start the magic!
+
+### ar
+
+`demo.ar: ARSystem | null, read-only`
+
+A reference to the [ARSystem](#arsystem), or `null` if the demo hasn't been started yet. See also: [lifecycle](#lifecycle)
+
+*Since:* 0.4.0
+
+### startSession
+
+`demo.startSession(): Promise<Session> | SpeedyPromise<Session>`
+
+Start the AR [Session](session.md). This method receives no arguments. It's supposed to call [AR.startSession](session.md#instantiation) with the desired settings.
+
+**Returns**
+
+A promise that resolves to a Session.
+
+!!! warning "Important"
+
+    This is an abstract method. You **must** implement it.
+
+!!! info "Fact"
+
+    The tracking begins when the session is started.
+
+### init
+
+`demo.init(): void | Promise<void> | SpeedyPromise<void>`
+
+Use this method to initialize your 3D scene. See also: [ar](#ar), [preload](#preload)
+
+**Returns**
+
+`undefined`, or a promise that resolves to `undefined`.
+
+**Example**
+
+```js
+class MyDemo extends ARDemo
+{
+    // ...
+
+    init()
+    {
+        const ar = this.ar;
+        const scene = ar.scene;
+
+        // initialize the scene
+        // ...
+    }
+
+    // ...
+}
+```
+
+!!! tip
+
+    Load external assets in [preload](#preload). Method `init` shouldn't take too long to run because the session is already started. See also: [lifecycle](#lifecycle)
+
+### update
+
+`demo.update(): void`
+
+Animation step, called during the animation loop. You may want to do something with [ar.session](#session) or [ar.frame](#frame).
+
+**Example**
+
+```js
+class MyDemo extends ARDemo
+{
+    // ...
+
+    update()
+    {
+        const ar = this.ar;
+        const session = ar.session;
+        const deltaTime = session.time.delta; // given in seconds
+
+        // ...
+    }
+
+    // ...
+}
+```
+
+### release
+
+`release(): void`
+
+Release resources soon after the AR session is ended.
+
+### preload
+
+`preload(): Promise<void> | SpeedyPromise<void>`
+
+Preload resources before starting the AR session. See also: [init](#init), [startSession](#startsession)
+
+*Since:* 0.4.0
+
+**Returns**
+
+A promise that resolves to `undefined`.
+
+## ARSystem
+
+`ARSystem` is a helper for creating Augmented Reality experiences. Access it via [ARDemo.ar](#ar).
+
+### session
+
+`ar.session: Session, read-only`
+
+A reference to the AR [Session](session.md).
+
+### frame
+
+`ar.frame: Frame | null, read-only`
+
+A reference to the current [Frame](frame.md). This will be `null` if the demo hasn't been started yet, or if the session has been ended. See also: [lifecycle](#lifecycle)
+
+### viewer
+
+`ar.viewer: Viewer | null, read-only`
+
+A reference to the [Viewer](viewer.md). This will be `null` if the [frame](#frame) is `null`.
+
+*Since:* 0.4.0
+
+### pointers
+
+`ar.pointers: TrackablePointer[], read-only`
+
+An array of [TrackablePointers](trackable-pointer.md).
+
+*Since:* 0.4.0
+
+!!! tip
+
+    Make sure to add a [PointerTracker](pointer-tracker.md) to your session in order to use these.
+
+### root
+
+`ar.root: THREE.Group, read-only`
+
+A node that is automatically aligned to the physical scene.
+
+!!! warning "Important"
+
+    In most cases, objects of your virtual scene should be descendants of this node!
+
+### camera
+
+`ar.camera: THREE.Camera, read-only`
+
+A camera that is automatically adjusted for AR.
+
+### scene
+
+`ar.scene: THREE.Scene, read-only`
+
+The three.js scene.
+
+### renderer
+
+`ar.renderer: THREE.WebGLRenderer, read-only`
+
+The three.js renderer.
+
+### utils
+
+`ar.utils: ARUtils, read-only`
+
+[Utilities](#arutils) object.
+
+*Since:* 0.4.0
+
+## ARUtils
+
+Utilities object.
+
+### convertVector2
+
+`ar.utils.convertVector2(v: Vector2): THREE.Vector2`
+
+Convert a [Vector2](./vector2.md) into a `THREE.Vector2`.
+
+*Since:* 0.4.0
+
+**Arguments**
+
+* `v: Vector2`. A 2D vector.
+
+**Returns**
+
+A corresponding `THREE.Vector2`.
+
+### convertVector3
+
+`ar.utils.convertVector3(v: Vector3): THREE.Vector3`
+
+Convert a [Vector3](./vector3.md) into a `THREE.Vector3`.
+
+*Since:* 0.4.0
+
+**Arguments**
+
+* `v: Vector3`. A 3D vector.
+
+**Returns**
+
+A corresponding `THREE.Vector3`.
+
+### convertQuaternion
+
+`ar.utils.convertQuaternion(q: Quaternion): THREE.Quaternion`
+
+Convert a [Quaternion](./quaternion.md) into a `THREE.Quaternion`.
+
+*Since:* 0.4.0
+
+**Arguments**
+
+* `q: Quaternion`. A quaternion.
+
+**Returns**
+
+A corresponding `THREE.Quaternion`.
+
+### convertRay
+
+`ar.utils.convertRay(r: Ray): THREE.Ray`
+
+Convert a [Ray](./ray.md) into a `THREE.Ray`.
+
+*Since:* 0.4.0
+
+**Arguments**
+
+* `r: Ray`. A ray.
+
+**Returns**
+
+A corresponding `THREE.Ray`.

docs/tutorial/augment-the-scene.md

@@ -65,8 +65,12 @@ It's easy to construct a basic augmented scene, and no JavaScript is needed for
 
 Babylon.js has an amazing documentation with plenty of learning resources, as well as a helpful and friendly community! Even though it can be used by beginners, it's recommended to have experience with JavaScript before creating projects with it.
 
+[Tell me more!](../api/plugin-babylon.md){ .md-button ._blank }
+
 ### Three.js
 
 [Three.js](https://threejs.org){ ._blank } is a popular open-source JavaScript library used to render 3D graphics in web browsers. It has many features, including: scene graphs, cameras, animations, lights, materials, loading of 3D models, mathematical utilities, special effects, and more. It has an active and vibrant community. Many community-made extensions are available.
 
 Using Three.js requires more JavaScript experience than using A-Frame in most cases, but it's also a great choice if you're comfortable with coding. Compared to A-Frame, Three.js offers you additional freedom on how you can organize your code, because it's a library, not a framework.
+
+[Tell me more!](../api/plugin-three.md){ .md-button ._blank }

mkdocs.yml

@@ -121,6 +121,8 @@ nav:
       - 'AREventType': 'api/ar-event-type.md'
     - 'Plugins':
       - 'A-Frame': 'api/plugin-aframe.md'
+      - 'Babylon.js': 'api/plugin-babylon.md'
+      - 'Three.js': 'api/plugin-three.md'
     - 'Speedy':
       - 'Speedy': 'api/speedy.md'
       - 'SpeedySize': 'api/speedy-size.md'