encantar-js/docs/api/session.md

Session

A central component of a WebAR experience. Read the concepts for more information.

Instantiation

Martins.startSession

Martins.startSession(options: object): SpeedyPromise<Session>

Start a new session.

Arguments

• options: object. Options object with the following keys:
  • trackers: Tracker[]. The trackers to be attached to the session.
  • sources: Source[]. The sources of data to be linked to the session.
  • viewport: Viewport. The viewport to be linked to the session.
  • mode: string, optional. Either "immersive" or "inline". Defaults to "immersive".
  • gizmos: boolean, optional. Whether or not to display the gizmos. Defaults to false.
  • stats: boolean, optional. Whether or not to display the stats panel. It’s useful during development. Defaults to false.

Returns

A promise that resolves to a new Session object.

Properties

mode

session.mode: string, read-only

Session mode: either "immersive" or "inline".

time

session.time: Time, read-only

A reference to the Time utilities of this session.

viewport

session.viewport: Viewport, read-only

A reference to the Viewport linked to this session.

gizmos

session.gizmos: Gizmos, read-only

A reference to the Gizmos object.

Methods

requestAnimationFrame

session.requestAnimationFrame(callback: function): SessionRequestAnimationFrameHandle

Schedules a call to the callback function, which is intended to update and render the virtual scene. Your callback function must itself call session.requestAnimationFrame() again in order to continue to update and render the virtual scene.

!!! info “Note”

`session.requestAnimationFrame()` is analogous to `window.requestAnimationFrame()`, but they are not the same! The former is a call to the WebAR engine, whereas the latter is a standard call to the web browser.

Arguments

• callback: function. A function that receives two parameters:
  • time: DOMHighResTimeStamp. Elapsed time, in milliseconds, since an arbitrary reference. This parameter is kept to mimic web standards, but its usage is discouraged. Prefer using frame.session.time.elapsed and frame.session.time.delta instead. These are especially useful for creating animations. See also: Time.
  • frame: Frame. A Frame holding the data you need to create the augmented scene.

Returns

A handle.

Example

function animate(time, frame)
{
    // update and render the virtual scene
    // ...

    // repeat the call
    session.requestAnimationFrame(animate);
}

session.requestAnimationFrame(animate);

cancelAnimationFrame

session.cancelAnimationFrame(handle: SessionRequestAnimationFrameHandle): void

Cancels an animation frame request.

Arguments

• handle: SessionRequestAnimationFrameHandle. A handle returned by session.requestAnimationFrame().

end

session.end(): SpeedyPromise<void>

Ends the session.

Returns

A promise that resolves as soon as the session is terminated.

Events

A session is an AREventTarget. You can listen to the following events:

end

The session has ended.

Example

session.addEventListener('end', event => {
    console.log('The session has ended.');
});