add docs

docs/docs.md

@@ -0,0 +1,29 @@
+---
+slug: '/'
+sidebar_class_name: hidden
+title: Docs
+description: Documentation
+---
+
+# Documentation
+
+8th Wall provides the complete solution to create WebAR, WebVR experiences and 3D games that run directly in a web browser.
+
+## 8th Wall Studio {#studio}
+
+8th Wall Studio is a real-time visual editor and game engine that combines the speed and power of the web with the tools needed to create hyper-immersive 3D and XR experiences. Studio has a visual 3D editor interface to create XR and web games across devices.
+
+[Studio Manual](/docs/studio)
+
+[Studio API](/docs/studio/api)
+
+## 8th Wall Engine {#engine}
+
+The 8th Wall AR Engine is a complete implementation of 8th Wall's Simultaneous Localization and Mapping (SLAM) engine, hyper-optimized for real-time WebAR on browsers. AR features include World Tracking, Image Targets, Face Effects,
+and Sky Segmentation.
+
+The engine is built-in to Studio projects, and is also easily integrated into modern 3D JavaScript frameworks such as [A-Frame](<https://aframe.io/>), [three.js](<https://threejs.org/>), [PlayCanvas](<https://www.playcanvas.com>), and [Babylon.js](<https://www.babylonjs.com/>).
+
+[Engine Manual](/docs/engine)
+
+[Engine API](/docs/engine/api)

docs/engine/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "8th Wall Engine",
+  "position": 4
+}

docs/engine/api/_category_.json

@@ -0,0 +1,4 @@
+{
+    "label": "API Reference",
+    "position": 3
+}

docs/engine/api/aframe/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "AFrame",
+  "position": 3
+}

docs/engine/api/aframe/aframe.md

@@ -0,0 +1,72 @@
+# XR8.AFrame
+
+A-Frame (<https://aframe.io>) is a web framework designed for building virtual reality experiences.
+By adding 8th Wall Web to your A-Frame project, you can now easily build **augmented reality**
+experiences for the web.
+
+## Components
+Component | Description
+--------- | -----------
+[xrconfig](/docs/engine/api/aframe/xrconfig) | Used to configure the camera feed
+[xrweb](/docs/engine/api/aframe/xrweb) | Used to configure world tracking
+[xrface](/docs/engine/api/aframe/xrface) | Used to configure face effects
+[xrlayers](/docs/engine/api/aframe/xrlayers) | Used to configure sky effects
+[xrlayerscene](/docs/engine/api/aframe/xrlayers) | Used to configure sky effects
+
+## Functions
+
+Function | Description
+-------- | -----------
+[xrconfigComponent](/docs/engine/api/aframe/xrconfig#xrconfigcomponent) | Creates an A-Frame component for configuring the camera which can be registered with `AFRAME.registerComponent()`. Generally won't need to be called directly.
+[xrwebComponent](/docs/engine/api/aframe/xrweb#xrwebcomponent) | Creates an A-Frame component for World Tracking and/or Image Target tracking which can be registered with `AFRAME.registerComponent()`. Generally won't need to be called directly.
+[xrfaceComponent](/docs/engine/api/aframe/xrface#xrfacecomponent) | Creates an A-Frame component for Face Effects tracking which can be registered with `AFRAME.registerComponent()`. Generally won't need to be called directly.
+[xrlayersComponent](/docs/engine/api/aframe/xrlayers#xrlayerscomponent) | Creates an A-Frame component for Layers tracking which can be registered with `AFRAME.registerComponent()`. Generally won't need to be called directly.
+[xrlayersceneComponent](/docs/engine/api/aframe/xrlayers#xrlayerscenecomponent) | Creates an A-Frame component for a Layer scene which can be registered with `AFRAME.registerComponent()`. Generally won't need to be called directly.
+
+## Examples
+
+#### Example - SLAM enabled (default) {#example---slam-enabled-default}
+
+```html
+<a-scene xrconfig xrweb>
+```
+
+#### Example - SLAM disabled (image tracking only) {#example---slam-disabled-image-tracking-only}
+
+```html
+<a-scene xrconfig xrweb="disableWorldTracking: true">
+```
+
+#### Example - Front camera (image tracking only) {#example---front-camera-image-tracking-only}
+
+```html
+<a-scene xrconfig="cameraDirection: front" xrweb="disableWorldTracking: true">
+```
+
+#### Example - Front camera Sky Effects {#example---front-camera-sky-effects}
+
+```html
+<a-scene xrconfig="cameraDirection: front" xrlayers>
+```
+
+#### Example - Sky + SLAM {#example---sky--slam}
+
+```html
+<a-scene xrconfig xrweb xrlayers>
+  <a-entity xrlayerscene="name: sky; edgeSmoothness:0.6; invertLayerMask: true;">
+    <!-- Add your Sky Effects content here. -->
+  </a-entity>
+</a-scene>
+```
+
+#### Example - Face Effects {#example---face-effects}
+
+```html
+<a-scene xrconfig xrface>
+```
+
+#### Example - Face Effects with Ears {#example---face-effects-ears}
+
+```html
+<a-scene xrconfig xrface="enableEars:true">
+```

docs/engine/api/aframe/xrconfig.md

@@ -0,0 +1,46 @@
+# Camera Configuration
+
+To configure the camera feed, add the `xrconfig` component to your `a-scene`:
+
+`<a-scene xrconfig>`
+
+## xrconfig Attributes (all optional) {#xrconfig-attributes}
+
+Component | Type | Default | Description
+--------- | ---- | ------- | -----------
+cameraDirection | `String` | `'back'` | Desired camera to use. Choose from: `back` or `front`. Use `cameraDirection: front;` with `mirroredDisplay: true;` for selfie mode. Note that world tracking is only supported with `cameraDirection: back;`.`
+allowedDevices | `String` | `'mobile-and-headsets'` | Supported device classes. Choose from: `'mobile-and-headsets'` , `'mobile'` or `'any'`. Use `'any'` to enable laptop or desktop-type devices with built-in or attached webcams. Note that world tracking is only supported on `'mobile-and-headsets'` or `mobile`.
+mirroredDisplay | `Boolean` | `false` | If true, flip left and right in the output geometry and reverse the direction of the camera feed. Use `'mirroredDisplay: true;'` with `'cameraDirection: front;'` for selfie mode. Should not be enabled if World Tracking (SLAM) is enabled.
+disableXrTablet | `Boolean` | `false` | Disable the tablet visible in immersive sessions.
+xrTabletStartsMinimized | `Boolean` | `false` | The tablet will start minimized.
+disableDefaultEnvironment | `Boolean` | `false` | Disable the default "void space" background.
+disableDesktopCameraControls | `Boolean` | `false` | Disable WASD and mouse look for camera.
+disableDesktopTouchEmulation | `Boolean` | `false` | Disable desktop fake touches.
+disableXrTouchEmulation | `Boolean` | `false` | Don’t emit touch events based on controller raycasts with the scene.
+disableCameraReparenting | `Boolean` | `false` | Disable camera -> controller object move
+defaultEnvironmentFloorScale | `Number` | `1` | Shrink or grow the floor texture.
+defaultEnvironmentFloorTexture | Asset | | Specify an alternative texture asset or URL for the tiled floor.
+defaultEnvironmentFloorColor | Hex Color | `#1A1C2A` | Set the floor color.
+defaultEnvironmentFogIntensity | `Number` | `1` | Increase or decrease fog density.
+defaultEnvironmentSkyTopColor | Hex Color | `#BDC0D6` | Set the color of the sky directly above the user.
+defaultEnvironmentSkyBottomColor | Hex Color | `#1A1C2A` | Set the color of the sky at the horizon.
+defaultEnvironmentSkyGradientStrength | `Number` | `1` | Control how sharply the sky gradient transitions.
+
+Notes:
+
+* `cameraDirection`: When using `xrweb` to provide world tracking (SLAM), only the `back` camera is
+supported. If you are using the `front` camera, you must disable world tracking by setting
+`disableWorldTracking: true` on `xrweb`.
+
+## xrconfigComponent()
+
+`XR8.AFrame.xrconfigComponent()`
+
+Creates an A-Frame component which can be registered with `AFRAME.registerComponent()`. This,
+however, generally won't need to be called directly. On 8th Wall Web script load, this component
+will be registered automatically if it is detected that A-Frame has loaded (i.e if `window.AFRAME`
+exists).
+
+```javascript
+window.AFRAME.registerComponent('xrconfig', XR8.AFrame.xrconfigComponent())
+```

docs/engine/api/aframe/xrface.md

@@ -0,0 +1,34 @@
+# Face Effects
+
+If you want Face Effects tracking, add the `xrface` component to your `a-scene`:
+
+`<a-scene xrconfig xrface>`
+
+## xrface Attributes {#xrface-attributes}
+
+Component | Type | Default | Description
+--------- | ---- | ------- | -----------
+meshGeometry | `Array` | `['face']` | Comma separated strings that configures which portions of the face mesh will have returned triangle indices. Can be any combination of `'face'`, `'eyes'`, `'iris'` and/or `'mouth'`.
+maxDetections [Optional] | `Number` | `1` | The maximum number of faces to detect. The available choices are 1, 2, or 3.
+uvType [Optional] | `String` | `[XR8.FaceController.UvType.STANDARD]` | Specifies which uvs are returned in the facescanning and faceloading event. Options are: `[XR8.FaceController.UvType.STANDARD, XR8.FaceController.UvType.PROJECTED]`
+enableEars [Optional] | `Boolean` | `false` | If true, runs ear detection simultaneosly with Face Effects and returns ear attachment points.
+
+
+Notes:
+
+* `xrface` and `xrweb` cannot be used at the same time.
+* `xrface` and `xrlayers` cannot be used at the same time.
+* Best practice is to always use `xrconfig`; however, if you use `xrface` without `xrconfig` then `xrconfig` will be added automatically. When that happens all attributes which were set on `xrface` will be passed along to `xrconfig`.
+
+## xrfaceComponent()
+
+`XR8.AFrame.xrfaceComponent()`
+
+Creates an A-Frame component which can be registered with `AFRAME.registerComponent()`. This,
+however, generally won't need to be called directly. On 8th Wall Web script load, this component
+will be registered automatically if it is detected that A-Frame has loaded (i.e if `window.AFRAME`
+exists).
+
+```javascript
+window.AFRAME.registerComponent('xrface', XR8.AFrame.xrfaceComponent())
+```

docs/engine/api/aframe/xrlayers.md

@@ -0,0 +1,58 @@
+# Sky Effects
+
+If you want Sky Effects:
+
+1. Add the `xrlayers` component to your `a-scene`
+2. Add the `xrlayerscene` component to an `a-entity` and add content you want to be in the sky under that `a-entity`.
+
+```html
+<a-scene xrconfig xrlayers>
+  <a-entity xrlayerscene="name: sky; edgeSmoothness:0.6; invertLayerMask: true;">
+    <!-- Add your Sky Effects content here. -->
+  </a-entity>
+</a-scene>
+```
+
+## xrlayers Attributes {#xrlayers-attributes}
+
+None
+
+Notes:
+
+* `xrlayers` and `xrface` cannot be used at the same time.
+* `xrlayers` and `xrweb` can be used at the same time. You must use `xrconfig` when doing so.
+  * Best practice is to always use `xrconfig`; however, if you use `xrlayers` without `xrface` or `xrweb` or `xrconfig`, then `xrconfig` will be added automatically. When that happens all attributes which were set on `xrweb` will be passed along to `xrconfig`.
+
+## xrlayerscene Attributes {#xrlayerscene-attributes}
+
+Component | Type | Default | Description
+--------- | ---- | ------- | -----------
+name | `String` | `''` | The layer name. Should correspond to a layer from [`XR8.LayersController`](../layerscontroller/layerscontroller.md). Only supported layer at this time is `sky`.
+invertLayerMask | `Boolean` | `false` | If true, content you place in your scene will occlude non-sky areas. If false, content you place in your scene will occlude sky areas.
+edgeSmoothness | `Number` | `0` | Amount to smooth the edges of the layer. Valid values between 0-1.
+
+## xrlayersceneComponent()
+
+`XR8.AFrame.xrlayersceneComponent()`
+
+Creates an A-Frame component which can be registered with `AFRAME.registerComponent()`. This,
+however, generally won't need to be called directly. On 8th Wall Web script load, this component
+will be registered automatically if it is detected that A-Frame has loaded (i.e if `window.AFRAME`
+exists).
+
+```javascript
+window.AFRAME.registerComponent('xrlayersceneComponent', XR8.AFrame.xrlayersceneComponent())
+```
+
+## xrlayersComponent()
+
+`XR8.AFrame.xrlayersComponent()`
+
+Creates an A-Frame component which can be registered with `AFRAME.registerComponent()`. This,
+however, generally won't need to be called directly. On 8th Wall Web script load, this component
+will be registered automatically if it is detected that A-Frame has loaded (i.e if `window.AFRAME`
+exists).
+
+```javascript
+window.AFRAME.registerComponent('xrlayers', XR8.AFrame.xrlayersComponent())
+```

docs/engine/api/aframe/xrweb.md

@@ -0,0 +1,36 @@
+# World Tracking & Image Targets
+
+If you want World Tracking or Image Targets, add the `xrweb` component to your `a-scene`:
+
+`<a-scene xrconfig xrweb>`
+
+## xrweb Attributes (all optional) {#xrweb-attributes}
+
+Component | Type | Default | Description
+--------- | ---- | ------- | -----------
+scale | `String` | `'responsive'` | Either `'responsive'` or `'absolute'`. `'responsive'` will return values so that the camera on frame 1 is at the origin defined via [`XR8.XrController.updateCameraProjectionMatrix()`](../xrcontroller/updatecameraprojectionmatrix). `'absolute'` will return the camera, image targets, etc in meters. The default is `'responsive'`. When using `'absolute'` the x-position, z-position, and rotation of the starting pose will respect the parameters set in [`XR8.XrController.updateCameraProjectionMatrix()`](../xrcontroller/updatecameraprojectionmatrix) once scale has been estimated. The y-position will depend on the camera's physical height from the ground plane.
+disableWorldTracking | `Boolean` | `false` | If true, turn off SLAM tracking for efficiency.
+
+Notes:
+
+* `xrweb` and `xrface` cannot be used at the same time.
+* `xrweb` and `xrlayers` can be used at the same time. You must use `xrconfig` when doing so.
+  * Best practice is to always use `xrconfig`; however, if you use `xrweb` without `xrface` or
+  `xrlayers` or `xrconfig`, then `xrconfig` will be added automatically. When that happens all
+  attributes which were set on `xrweb` will be passed along to `xrconfig`.
+* `cameraDirection`: World tracking (SLAM) is only supported on the `back` camera. If you are using
+  the `front` camera, you must disable world tracking by setting `disableWorldTracking: true`.
+* World tracking (SLAM) is only supported on mobile devices.
+
+## xrwebComponent()
+
+`XR8.AFrame.xrwebComponent()`
+
+Creates an A-Frame component which can be registered with `AFRAME.registerComponent()`. This,
+however, generally won't need to be called directly. On 8th Wall Web script load, this component
+will be registered automatically if it is detected that A-Frame has loaded (i.e if `window.AFRAME`
+exists).
+
+```javascript
+window.AFRAME.registerComponent('xrweb', XR8.AFrame.xrwebComponent())
+```

docs/engine/api/aframeeventlisenters/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "AFrame Event Listeners",
+  "position": 5
+}

docs/engine/api/aframeeventlisenters/aframeeventlisenters.md

@@ -0,0 +1,13 @@
+# AFrame Event Listeners
+
+This section describes the events that are listened for by the "xrweb" A-Frame component
+
+You can emit these events in your web application to perform various actions:
+
+Event Listener | Description
+-------------- | -----------
+[hidecamerafeed](hidecamerafeed.md) | Hides the camera feed. Tracking does not stop.
+[recenter](recenter.md) | Recenters the camera feed to its origin. If a new origin is provided as an argument, the camera's origin will be reset to that, then it will recenter.
+[screenshotrequest](screenshotrequest.md) | Emits a request to the engine to capture a screenshot of the AFrame canvas. The engine will emit a [`screenshotready`](/docs/engine/api/aframeevents/screenshotready) event with the JPEG compressed image or [`screenshoterror`](/docs/engine/api/aframeevents/screenshoterror) if an error has occured.
+[showcamerafeed](showcamerafeed.md) | Shows the camera feed.
+[stopxr](stopxr.md) | Stop the current XR session. While stopped, the camera feed is stopped and device motion is not tracked.

docs/engine/api/aframeeventlisenters/hidecamerafeed.md

@@ -0,0 +1,18 @@
+# hidecamerafeed
+
+`scene.emit('hidecamerafeed')`
+
+## Description {#description}
+
+Hides the camera feed. Tracking does not stop.
+
+## Parameters {#parameters}
+
+None
+
+## Example {#example}
+
+```javascript
+let scene = this.el.sceneEl
+scene.emit('hidecamerafeed')
+```

docs/engine/api/aframeeventlisenters/recenter.md

@@ -0,0 +1,35 @@
+# recenter
+
+`scene.emit('recenter', {origin, facing})`
+
+## Description {#description}
+
+Recenters the camera feed to its origin. If a new origin is provided as an argument, the camera's origin will be reset to that, then it will recenter.
+
+If origin and facing are not provided, camera is reset to origin previously specified by a call to `recenter` or the last call to `XR8.XrController.updateCameraProjectionMatrix()` when using `xrweb` or `XR8.FaceController.configure({coordinates: {origin, scale, axes}})` / `XR8.LayersController.configure({coordinates: {origin, scale, axes}})` when using `xrface` or `xrlayers`.
+
+**IMPORTANT:** With A-Frame, `updateCameraProjectionMatrix()` and / or `configure()` is initially called based on initial camera position in the scene.
+
+## Parameters {#parameters}
+
+Parameter | Description
+--------- | -----------
+origin: {x, y, z} [Optional] | The location of the new origin.
+facing: {w, x, y, z} [Optional] | A quaternion representing direction the camera should face at the origin.
+
+## Example - Recenter the scene {#example}
+
+```javascript
+let scene = this.el.sceneEl
+scene.emit('recenter')
+```
+
+## Example - Recenter the scene and update the origin {#example---update-origin}
+
+```javascript
+let scene = this.el.sceneEl
+scene.emit('recenter', {
+  origin: {x: 1, y: 4, z: 0},
+  facing: {w: 0.9856, x:0, y:0.169, z:0}
+})
+```