Document the A-Frame plugin in Markdown

docs/api/plugin-aframe.md

@@ -0,0 +1,442 @@
+# A-Frame plugin
+
+Documentation of the A-Frame plugin.
+
+We'll get to the details, but a basic augmented scene can be constructed as follows:
+
+```html
+<a-scene encantar="stats: true; gizmos: true">
+
+    <!-- Sources of data -->
+    <ar-sources>
+        <ar-camera-source></ar-camera-source> <!-- webcam -->
+    </ar-sources>
+
+    <!-- Trackers -->
+    <ar-trackers>
+        <ar-image-tracker>
+            <ar-reference-image name="mage" src="mage.png"></ar-reference-image>
+        </ar-image-tracker>
+    </ar-trackers>
+
+    <!-- AR Viewport -->
+    <ar-viewport></ar-viewport>
+
+    <!-- Virtual camera for AR -->
+    <ar-camera></ar-camera>
+
+    <!-- Root node: this will be displayed in AR -->
+    <ar-root reference-image="mage">
+        <a-box color="yellow" position="0 0 0.5"></a-box>
+    </ar-root>
+
+</a-scene>
+```
+
+*Since:* 0.3.0
+
+## Basics
+
+### encantar
+
+The `encantar` component *enchants* (augments) `<a-scene>`, so that it displays content in AR.
+
+**Properties**
+
+* `mode: string`. The [session mode](./session.md#mode). Defaults to `"immersive"`.
+* `stats: boolean`. Whether or not to display the built-in stats panel. It's useful during development. Defaults to `false`.
+* `gizmos: boolean`. Whether or not to display the [gizmos](./session.md#gizmos). Defaults to `false`.
+* `autoplay: boolean`. Whether or not to start the AR [session](./session.md) automatically. Defaults to `true`.
+
+**Example**
+
+```html
+<a-scene encantar="stats: true; gizmos: true">
+    ...
+</a-scene>
+```
+
+### ar-root
+
+The `<ar-root>` primitive sets up a node of the virtual scene that is automatically aligned to the physical scene. Simply put, children of this node will augment physical reality. `<ar-root>` must be a direct child of `<a-scene>`. It does not have to be unique. See also: [ar-camera](#ar-camera).
+
+**Properties**
+
+* `reference-image: string`. The name of a [reference image](./reference-image.md) or the empty string. This node will be matched to the specified reference image, or to any reference image if this property is the empty string. Defaults to the empty string. See also: [ar-reference-image](#ar-reference-image).
+
+**Example**
+
+```html
+<a-scene encantar>
+
+    ...
+
+    <!-- Matches only the specified reference image -->
+    <ar-root reference-image="mage">
+        ...
+    </ar-root>
+
+    <!-- Matches any reference image -->
+    <ar-root>
+        ...
+    </ar-root>
+
+    ...
+
+</a-scene>
+```
+
+## Visualization
+
+### ar-viewport
+
+The `<ar-viewport>` primitive sets up the [viewport](./viewport.md) that will be linked to the AR [session](./session.md). It must be unique and a direct child of `<a-scene>`. See also: [ar-hud](#ar-hud).
+
+**Properties**
+
+* `resolution: string`. The [resolution of the viewport](./viewport.md#resolution), which corresponds to the resolution of the virtual scene. See also: [Resolution](./resolution.md).
+* `style: string`. The [style of the viewport](./viewport.md#style).
+* `fullscreen-ui: component`. A component that controls the built-in fullscreen button. This button included as a convenience if the fullscreen mode is [available](./viewport.md#fullscreenavailable) on the target platform. The following properties are available:
+    * `enabled: boolean`. Whether or not to display the fullscreen button. Defaults to `true`.
+
+**Example**
+
+```html
+<a-scene encantar>
+
+    ...
+
+    <ar-viewport resolution="lg">
+        ...
+    </ar-viewport>
+
+    ...
+
+</a-scene>
+```
+
+### ar-hud
+
+The `<ar-hud>` primitive sets up a [Heads Up Display](./hud.md), a 2D overlay that is displayed in front of the augmented scene. It's meant to contain HTML elements. Additionally, it must be a direct child of `<ar-viewport>`. See also: [ar-viewport](#ar-viewport).
+
+**Example**
+
+```html
+<ar-viewport>
+    <ar-hud>
+
+        <!-- This will be displayed in front of the augmented scene -->
+        <button id="example-button">Tap me</button>
+
+    </ar-hud>
+</ar-viewport>
+```
+
+### ar-camera
+
+`<ar-camera>` sets up a virtual camera that is ready for AR. It should be unique and a direct child of `<a-scene>`. Do not confuse it with `<a-camera>`, the standard camera from A-Frame. See also: [ar-root](#ar-root).
+
+**Example**
+
+```html
+<a-scene encantar>
+
+    ...
+
+    <ar-camera></ar-camera>
+
+    ...
+
+</a-scene>
+```
+
+## Sources
+
+### ar-sources
+
+The `<ar-sources>` primitive is used to specify the [sources of data](./source.md) that will be linked to the AR [session](./session.md). It must be unique and a direct child of `<a-scene>`.
+
+**Example**
+
+```html
+<a-scene encantar>
+
+    ...
+
+    <ar-sources>
+        ...
+    </ar-sources>
+
+    ...
+
+</a-scene>
+```
+
+### ar-camera-source
+
+`<ar-camera-source>` sets up a [CameraSource](./camera-source.md), which is source of data linked to a webcam. It must be a direct child of `<ar-sources>`.
+
+**Properties**
+
+* `resolution: string`. The preferred [resolution of the camera](./camera-source.md#resolution). See also: [Resolution](./resolution.md).
+* `facing-mode: string`. The preferred camera on mobile devices. Typically `"environment"` (rear camera) or `"user"` (front camera). Defaults to `"environment"`.
+
+**Example**
+
+```html
+<ar-sources>
+    <ar-camera-source resolution="md"></ar-camera-source>
+</ar-sources>
+```
+
+### ar-video-source
+
+`<ar-video-source>` sets up a [VideoSource](./video-source.md), which is a source of data linked to a `<video>` element. It must be a direct child of `<ar-sources>`.
+
+**Properties**
+
+* `video: selector`. A selector of a `<video>` element.
+
+**Example**
+
+```html
+<ar-sources>
+    <ar-video-source video="#my-video"></ar-video-source>
+</ar-sources>
+
+...
+
+<!-- External assets -->
+<a-assets>
+    <video id="my-video" hidden muted loop playsinline autoplay>
+        <source src="my-video.webm" type="video/webm" />
+        <source src="my-video.mp4" type="video/mp4" />
+    </video>
+</a-assets>
+```
+
+### ar-pointer-source
+
+`<ar-pointer-source>` sets up a [PointerSource](./pointer-source.md), a source of pointer-based input. It must be a direct child of `<ar-sources>`. See also: [ar-pointer-tracker](#ar-pointer-tracker).
+
+*Since:* 0.4.0
+
+**Example**
+
+```html
+<ar-sources>
+    ...
+    <ar-pointer-source></ar-pointer-source>
+</ar-sources>
+```
+
+## Trackers
+
+### ar-trackers
+
+The `<ar-trackers>` primitive is used to specify the [trackers](./tracker.md) that will be linked to the AR [session](./session.md). It must be unique and a direct child of `<a-scene>`.
+
+**Example**
+
+```html
+<a-scene encantar>
+
+    ...
+
+    <ar-trackers>
+        ...
+    </ar-trackers>
+
+    ...
+
+</a-scene>
+```
+
+### ar-image-tracker
+
+`<ar-image-tracker>` sets up an [ImageTracker](./image-tracker.md), which is used to track images in a video. You must include at least one `<ar-reference-image>` as a direct child. See also: [ar-reference-image](#ar-reference-image), [ar-camera-source](#ar-camera-source), [ar-video-source](#ar-video-source).
+
+**Properties**
+
+* `resolution: string`. The [resolution of the tracker](./image-tracker.md#resolution). See also: [Resolution](./resolution.md).
+
+**Example**
+
+```html
+<ar-trackers>
+    <ar-image-tracker resolution="md">
+        <ar-reference-image name="mage" src="mage.png"></ar-reference-image>
+        <ar-reference-image name="magic" src="magic.png"></ar-reference-image>
+    </ar-image-tracker>
+</ar-trackers>
+```
+
+### ar-reference-image
+
+`<ar-reference-image>` defines a [ReferenceImage](./reference-image.md) to be used by an image tracker. It must be a direct child of `<ar-image-tracker>`. See also: [ar-image-tracker](#ar-image-tracker).
+
+**Properties**
+
+* `name: string`. The name of the reference image. You may link it with `<ar-root>`. Names must be unique. See also: [ar-root](#ar-root).
+* `src: string`. Path to the image.
+
+**Example**
+
+```html
+<ar-image-tracker>
+    <ar-reference-image name="mage" src="mage.png"></ar-reference-image>
+</ar-image-tracker>
+```
+
+### ar-pointer-tracker
+
+`<ar-pointer-tracker>` sets up a [PointerTracker](./pointer-tracker.md), which is used to track pointer-based input. It must be a direct child of `<ar-trackers>`. See also: [ar-pointer-source](#ar-pointer-source), [pointers](#pointers).
+
+*Since:* 0.4.0
+
+**Example**
+
+```html
+<ar-trackers>
+    ...
+    <ar-pointer-tracker></ar-pointer-tracker>
+</ar-trackers>
+```
+
+## AR System
+
+### ar
+
+The `ar` system conveniently exposes useful objects and methods in JavaScript. It may be accessed from any component by writing `this.el.sceneEl.systems.ar`.
+
+**Example**
+
+```js
+AFRAME.registerComponent('my-component', {
+
+    // ...
+
+    tick()
+    {
+        const ar = this.el.sceneEl.systems.ar;
+        const session = ar.session;
+
+        // ...
+    },
+
+    // ...
+
+});
+```
+
+### session
+
+`ar.session: Session | null`
+
+The AR [Session](./session.md). If the AR session hasn't been started, this will be `null`.
+
+### frame
+
+`ar.frame: Frame | null`
+
+The current [Frame](./frame.md). If the AR scene isn't initialized, this will be `null`.
+
+### viewer
+
+`ar.viewer: Viewer | null`
+
+A reference to the [Viewer](./viewer.md) of the current frame, if any.
+
+*Since:* 0.4.0
+
+### pointers
+
+`ar.pointers: TrackablePointer[]`
+
+The [TrackablePointers](./trackable-pointer.md) of the current frame, if any. Make sure to add a `<ar-pointer-tracker>` in order to use these. See also: [ar-pointer-tracker](#ar-pointer-tracker).
+
+*Since:* 0.4.0
+
+### utils
+
+`ar.utils: object`
+
+[Utilities](#utilities) for AR.
+
+*Since:* 0.4.0
+
+## Utilities
+
+### 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`.
+
+## Events
+
+### ar-started
+
+The `ar-started` event is emitted when the main loop of the AR scene is set up, just after the AR session starts.
+
+**Details**
+
+* `ar: object`. A reference to the [ar](#ar) system.

docs/tutorial/augment-the-scene.md

@@ -12,7 +12,7 @@ Once you pick a 3D rendering technology, you need to integrate it with encantar.
 
 Writing a plugin is a task of moderate complexity. It requires dealing with maths and with some idiosyncrasies of the 3D rendering technologies in order to make sure that it all works as intended. I provide easy-to-use plugins that work with different 3D rendering technologies, so that you don't need to deal with that complexity yourself. Plugins are shipped as JavaScript (.js) files. You just need to add a plugin to your web page, and then the integration will be done for you!
 
-[Get the plugins in the demos](/encantar-js/demos){ .md-button .md-button--primary ._blank }
+[Get the plugins in the demos](../../demos){ .md-button .md-button--primary ._blank }
 
 ## Create the virtual scene
 
@@ -26,6 +26,39 @@ Let me tell you more about the 3D rendering technologies I just mentioned.
 
 A-Frame is built on top of [Three.js](#threejs) and extends it in powerful ways. It introduces a HTML-based declarative approach for [scene graphs](https://en.wikipedia.org/wiki/Scene_graph){ ._blank }, empowering them with the [Entity-Component-System](https://en.wikipedia.org/wiki/Entity_component_system){ ._blank }, a software pattern commonly used in game development. A-Frame is easy for beginners and pleasing for experts. In many cases, writing JavaScript code is not needed.
 
+It's easy to construct a basic augmented scene, and no JavaScript is needed for that:
+
+```html
+<a-scene encantar="stats: true; gizmos: true">
+
+    <!-- Sources of data -->
+    <ar-sources>
+        <ar-camera-source></ar-camera-source> <!-- webcam -->
+    </ar-sources>
+
+    <!-- Trackers -->
+    <ar-trackers>
+        <ar-image-tracker>
+            <ar-reference-image name="mage" src="mage.png"></ar-reference-image>
+        </ar-image-tracker>
+    </ar-trackers>
+
+    <!-- AR Viewport -->
+    <ar-viewport></ar-viewport>
+
+    <!-- Virtual camera for AR -->
+    <ar-camera></ar-camera>
+
+    <!-- Root node: this will be displayed in AR -->
+    <ar-root reference-image="mage">
+        <a-box color="yellow" position="0 0 0.5"></a-box>
+    </ar-root>
+
+</a-scene>
+```
+
+[Tell me more!](../api/plugin-aframe.md){ .md-button ._blank }
+
 ### Babylon.js
 
 [Babylon.js](https://www.babylonjs.com){ ._blank } is a powerful open-source game and 3D rendering engine for the web. It includes pretty much all features you commonly find in 3D rendering engines (scene graphs, lights, materials, meshes, animations, etc.), plus systems that are specific to game engines (audio engine, collision system, physics system, support for sprites, etc.), plus all kinds of sophisticated features for various applications.

mkdocs.yml

@@ -70,6 +70,7 @@ nav:
     - 'Recommendations': 'recommendations.md'
     - 'Guidelines for Images': 'guidelines-for-images.md'
     - 'Questions & Answers': 'faq.md'
+    - 'API Reference': 'api/ar.md'
   - 'API':
     - 'General':
       - 'AR': 'api/ar.md'
@@ -118,6 +119,8 @@ nav:
       - 'AREventListener': 'api/ar-event-listener.md'
       - 'AREventTarget': 'api/ar-event-target.md'
       - 'AREventType': 'api/ar-event-type.md'
+    - 'Plugins':
+      - 'A-Frame': 'api/plugin-aframe.md'
     - 'Speedy':
       - 'Speedy': 'api/speedy.md'
       - 'SpeedySize': 'api/speedy-size.md'