Table of Contents

Class ARSession

Switch to guide

Namespace
easyar
Assembly
EasyAR.Sense.dll

Control the AR session in the scene MonoBehaviour. A session contains a set of components assembled into ARAssembly and controls the data flow throughout the lifecycle. This component is the entry point of AR. Multiple active instances are not allowed at the same time.

All functions of the EasyAR component must be used after StartSession().

The relative transform between Camera and some AR components is controlled by the session. One of the objects is called CenterObject, which does not move in the scene, and other objects move relative to this CenterObject. This object is selected according to the value of CenterMode. For more detailed instructions, refer to the description of ARSession.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 start the session when MonoBehaviour.Start. If set to false, you need to manually call StartSession() to start the session.

[SerializeField]
[HideInInspector]
public bool AutoStart

Field Value

CenterMode

AR center mode. Can be modified at any time and takes effect immediately. If the specified mode is not available, it will be automatically modified to an available mode.

[SerializeField]
[HideInInspector]
public ARSession.ARCenterMode CenterMode

Field Value

HorizontalFlip

Horizontal mirror rendering mode. Can be modified at any time and takes effect immediately. Only available when using image or object tracking.

[SerializeField]
[HideInInspector]
public ARSession.FlipOptions HorizontalFlip

Field Value

Properties

AssembleOptions

Assembly options for the Session, which need to be set before Assemble() (if not called before, StartSession() will be implicitly called).

public AssembleOptions AssembleOptions { get; }

Property Value

Assembly

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 in the current frame.

This object represents a non-moving object in the Unity space or the parent node of this object. It may be Origin, Camera or a certain `target`. The `Target` can be an object containing TargetController or BlockRootController components. When using sparse spatial maps and EasyAR Mega, the actual center GameObject is the map or block object specifically located under the root node, and CenterObject is the parent node of this object. For more detailed instructions, refer to the description of ARSession.ARCenterMode.

public GameObject CenterObject { get; }

Property Value

Diagnostics

Session diagnostic component.

public DiagnosticsController Diagnostics { get; }

Property Value

Origin

Session origin during the operation of any motion tracking function.

It will be automatically selected from the scene, and if it does not exist, it will be created by EasyAR or a third-party frame source extension. When using the built-in frame source, if the XROrigin of the Unity XR framework exists, it will be selected. If the AR Foundation package does not exist, the XR Origin that maintains the default tree structure will be selected.

public GameObject Origin { get; }

Property Value

Report

Session report. It is available for viewing after assembly is completed and will be updated when the session state changes. It is used to view detailed information such as session corruption and component availability.

public SessionReport Report { get; }

Property Value

SpecificTargetCenter

Manually specified center object. When CenterMode == SpecificTarget, CenterObject will be set to this object. Can be modified at any time and takes effect immediately.

This object must contain TargetController or BlockRootController components.

public GameObject SpecificTargetCenter { get; set; }

Property Value

State

Current session state.

public ARSession.SessionState State { get; }

Property Value

TrackingStatus

Motion tracking state during the operation of any motion tracking function.

public Optional<MotionTrackingStatus> TrackingStatus { get; }

Property Value

Methods

Assemble()

Assemble the session using AssembleOptions. If called, it will be automatically called in StartSession().

public IEnumerator Assemble()

Returns

ImageCoordinatesFromScreenCoordinates(Vector2)

Transform from screen coordinate system ([0, 1]^2) to image coordinate system ([0, 1]^2). The pointInView needs to be normalized to [0, 1]^2. Not available on headsets.

public Optional<Vector2> ImageCoordinatesFromScreenCoordinates(Vector2 pointInView)

Parameters

pointInView

Returns

StartSession()

Start the session. If AutoStart is true, it will be automatically called in MonoBehaviour.Start.

public void StartSession()

StopSession(bool)

Stop starting the session. All transform updates and image rendering updates will stop. You can use rotation to keep the last frame image when stopping, but it is only effective when EasyAR controls image rendering (AR Foundation and headsets are invalid).

public void StopSession(bool keepLastFrame)

Parameters

keepLastFrame

Events

AssembleUpdate

Session Assemble() update event. This event will be triggered 1-2 times in one Assemble() (if not called before, StartSession() will be implicitly called). The first time is when Assembly is completed. If the device list update is completed when Assembly is completed, there will be no second call. Otherwise, the second call will occur when the device list update is completed.

public event Action<SessionReport.AvailabilityReport> AssembleUpdate

Event Type

InputFrameUpdate

Input frame update event, triggered only when the InputFrame displayed by the session changes. This event will not be received on headsets, and if there is a perspective image, its rendering is done by the device.

public event Action<InputFrame> InputFrameUpdate

Event Type

PostSessionUpdate

Session update completion event, the frequency of this event is the same as MonoBehaviour.Update (needs to be correctly implemented by the extension author on headsets). When this event is triggered, all transform changes controlled by EasyAR in this frame have been completed.

public event Action PostSessionUpdate

Event Type

StateChanged

Event for session State change.

public event Action<ARSession.SessionState> StateChanged

Event Type