plugin-babylon.md 5.9KB
Babylon.js plugin
Documentation of the babylon.js{ ._blank } plugin. Study the demos 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. Function encantar starts the magic.
!!! 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 of the AR experience.
Arguments
demo: ARDemo. Your demo. See also: ARDemo
Returns
A promise that resolves to an ARSystem when the demo starts.
Example
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 of your AR experience. The plugin will call its methods and control the flow of the program. Simply call encantar to start the magic!
ar
demo.ar: ARSystem | null, read-only
A reference to the ARSystem, or null if the demo hasn’t been started yet. See also: lifecycle
Since: 0.4.0
startSession
demo.startSession(): Promise<Session> | SpeedyPromise<Session>
Start the AR Session. This method receives no arguments. It’s supposed to call AR.startSession 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, preload
Returns
undefined, or a promise that resolves to undefined.
Example
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 or ar.frame.
Example
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, 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.
session
ar.session: Session, read-only
A reference to the AR Session.
frame
ar.frame: Frame | null, read-only
A reference to the current Frame. This will be null if the demo hasn’t been started yet, or if the session has been ended. See also: lifecycle
viewer
ar.viewer: Viewer | null, read-only
A reference to the Viewer. This will be null if the frame is null.
Since: 0.4.0
pointers
ar.pointers: TrackablePointer[], read-only
An array of TrackablePointers.
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 object.
Since: 0.4.0
ARUtils
Utilities object.
convertVector2
ar.utils.convertVector2(v: Vector2): BABYLON.Vector2
Convert a Vector2 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 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 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 into a BABYLON.Ray.
Since: 0.4.0
Arguments
r: Ray. A ray.
Returns
A corresponding BABYLON.Ray.