Table of Contents

Class ARSession

Switch to guide

Namespace
easyar
Assembly
EasyAR.Sense.dll

AMonoBehaviour that controls the AR session in the scene. A session contains a set of components assembled into anARAssembly and controls the data flow throughout its lifecycle. This component is the entry point for AR. Only one active instance is allowed at a time.

All features of EasyAR components requireStartSession() to be called before use.

The relative transform between theCamera and some AR components is controlled by the session. One object, known as theCenterObject, remains stationary in the scene, while other objects move relative to it. This object is selected based on the value ofCenterMode. For more details, refer to the description ofARSession.ARCenterMode.

[DefaultExecutionOrder(-2147483648)]
[DisallowMultipleComponent]
[RequireComponent(typeof(EasyARController), typeof(DiagnosticsController))]
[RequireComponent(typeof(FrameRecorder), typeof(FramePlayer), typeof(CameraImageRenderer))]
public class ARSession : MonoBehaviour
Inheritance
ARSession

Fields

AutoStart

Automatically starts the session duringMonoBehaviour.Start. If set to false, you must manually callStartSession() to start the session.

[SerializeField]
[HideInInspector]
public bool AutoStart

Field Value

CenterMode

AR center mode. Can be modified at any time, taking effect immediately. If the specified mode is unavailable, it will be automatically changed to an available mode.

[SerializeField]
[HideInInspector]
public ARSession.ARCenterMode CenterMode

Field Value

HorizontalFlip

Horizontal flip rendering mode. Can be modified at any time, taking effect immediately. Only available when using image or object tracking.

[SerializeField]
[HideInInspector]
public ARSession.FlipOptions HorizontalFlip

Field Value

Properties

AssembleOptions

Session assemble options. Must be set before callingAssemble() (StartSession() implicitly calls it if not done before).

public AssembleOptions AssembleOptions { get; }

Property Value

Assembly

The assembly of AR components.

public ARAssembly Assembly { get; }

Property Value

AvailableCenterMode

Available center modes for the current session.

public IReadOnlyList<ARSession.ARCenterMode> AvailableCenterMode { get; }

Property Value

CenterObject

The center object used by this session for the current frame.

This object represents the stationary object in Unity space, or its parent. It could be theOrigin, theCamera, or a `target`. A `Target` is an object containing aTargetController orBlockRootController component. When using sparse spatial maps or EasyAR Mega, the actual centerGameObject is the located map or block object under the root node;CenterObject is this object's parent. For more details, refer to the description ofARSession.ARCenterMode.

public GameObject CenterObject { get; }

Property Value

Diagnostics

Session diagnostics component.

public DiagnosticsController Diagnostics { get; }

Property Value

Origin

The session origin when any motion tracking feature is active.

It is selected automatically from the scene. If none exists, it is created by EasyAR or a third-party frame source extension. When using the built-in frame source, if Unity XR Framework's XROrigin exists, it is selected. If the AR Foundation package is absent, only an XR Origin with the default hierarchy structure will be chosen.

public GameObject Origin { get; }

Property Value

Report

Session report. Available for viewing after assemble completes and updates when session state changes. Used to view details like session failure reasons or component availability.

public SessionReport Report { get; }

Property Value

SpecificTargetCenter

Manually specified center object. WhenCenterMode == SpecificTarget,CenterObject will be set to this object. Can be modified at any time, taking effect immediately.

This object must contain aTargetController orBlockRootController component.

public GameObject SpecificTargetCenter { get; set; }

Property Value

State

Current state of the session.

public ARSession.SessionState State { get; }

Property Value

TrackingStatus

Motion tracking status when any motion tracking feature is active.

public Optional<MotionTrackingStatus> TrackingStatus { get; }

Property Value

Methods

Assemble()

Assembles the session usingAssembleOptions. If called, this is done automatically inStartSession().

public IEnumerator Assemble()

Returns

ImageCoordinatesFromScreenCoordinates(Vector2)

Transforms from screen coordinates ([0, 1]^2) to image coordinates ([0, 1]^2).pointInView must be normalized to [0, 1]^2. Not available on head-mounted displays.

public Optional<Vector2> ImageCoordinatesFromScreenCoordinates(Vector2 pointInView)

Parameters

pointInView

Returns

StartSession()

Starts the session. IfAutoStart is true, this is called automatically duringMonoBehaviour.Start.

public void StartSession()

StopSession(bool)

Stops the session. All transform updates and image rendering updates cease. You can choose to retain the last frame's image when stopping, but this only works when EasyAR controls image rendering (invalid for AR Foundation, head-mounted displays, etc.).

public void StopSession(bool keepLastFrame)

Parameters

keepLastFrame

Events

AssembleUpdate

SessionAssemble() update event. This event fires 1-2 times during anAssemble() call (StartSession() implicitly calls it if not done before). The first occurs when Assemble completes. If device list updating finishes at the same time as Assemble, there will be no second call; otherwise, the second call happens when device list updating completes.

public event Action<SessionReport.AvailabilityReport> AssembleUpdate

Event Type

InputFrameUpdate

Input frame update event, triggered only when the displayedInputFrame changes. Not received on head-mounted displays. If a passthrough image exists, its rendering is handled by the device.

public event Action<InputFrame> InputFrameUpdate

Event Type

PostSessionUpdate

Session update completion event, firing at the same frequency asMonoBehaviour.Update (requires correct implementation by the extension author on head-mounted displays). When this event fires, all EasyAR-controlled transform updates for the frame are complete.

public event Action PostSessionUpdate

Event Type

StateChanged

Event triggered when the session'sState changes.

public event Action<ARSession.SessionState> StateChanged

Event Type