Class ARSession
Controls the lifecycle and configuration options for an AR session. There is only one active session. If you have multiple ARSession components, they all communicate to the same session and will conflict with each other.
Enabling or disabling the ARSession starts or stops the session, respectively.
Inheritance
Inherited Members
Namespace: UnityEngine.XR.ARFoundation
Syntax
[DisallowMultipleComponent]
[DefaultExecutionOrder(-2147483648)]
public sealed class ARSession : SubsystemLifecycleManager<XRSessionSubsystem, XRSessionSubsystemDescriptor, XRSessionSubsystem.Provider>Properties
attemptUpdate
If the device supports XR but does not have the necessary software, some platforms
allow prompting the user to install or update the software. If attemptUpdate
is true, a software update will be attempted. If the appropriate software is not installed
or out of date, and attemptUpdate is false, then AR will not be available.
Declaration
public bool attemptUpdate { get; set; }Property Value
| Type | Description |
|---|---|
| Boolean |
currentTrackingMode
Get the current TrackingMode in use by the session.
Declaration
public TrackingMode currentTrackingMode { get; }Property Value
| Type | Description |
|---|---|
| TrackingMode |
frameRate
Get the number of AR frames produced per second, or null if the frame rate cannot be determined.
Declaration
public int? frameRate { get; }Property Value
| Type | Description |
|---|---|
| Nullable<Int32> |
matchFrameRate
If true, the session will block execution until a new AR frame is available.
This property is obsolete. Use matchFrameRateRequested or matchFrameRateEnabled instead.
Declaration
[Obsolete("Use matchFrameRateRequested or matchFrameRateEnabled instead. (2020-01-28)")]
public bool matchFrameRate { get; set; }Property Value
| Type | Description |
|---|---|
| Boolean |
matchFrameRateEnabled
If true, the underlying subsystem will attempt to synchronize the AR frame rate with Unity's.
Declaration
public bool matchFrameRateEnabled { get; }Property Value
| Type | Description |
|---|---|
| Boolean |
See Also
matchFrameRateRequested
If true, the session will block execution until a new AR frame is available and set
Application.targetFrameRate
to match the native update frequency of the AR session.
Otherwise, the AR session is updated independently of the Unity frame.
Declaration
public bool matchFrameRateRequested { get; set; }Property Value
| Type | Description |
|---|---|
| Boolean |
Remarks
If enabled with a simple scene, the ARSession.Update might appear to take a long time.
This is because your application is waiting for the next AR frame, similar to the way Unity will WaitForTargetFPS at the
end of a frame. If the rest of the Unity frame takes non-trivial time, then the next ARSession.Update
will take a proportionally smaller amount of time.
This option does three things:
- Enables a setting on the XRSessionSubsystem which causes the update to block until the next AR frame is ready.
- Sets Application.targetFrameRate to the session's preferred update rate.
- Sets QualitySettings.vSyncCount to zero.
These settings are not reverted when the AR Session is disabled.
notTrackingReason
The reason AR tracking was lost.
Declaration
public static NotTrackingReason notTrackingReason { get; }Property Value
| Type | Description |
|---|---|
| NotTrackingReason |
requestedTrackingMode
Get or set the TrackingMode for the session.
Declaration
public TrackingMode requestedTrackingMode { get; set; }Property Value
| Type | Description |
|---|---|
| TrackingMode |
state
The state of the entire system. Use this to determine the status of AR availability and installation.
Declaration
public static ARSessionState state { get; }Property Value
| Type | Description |
|---|---|
| ARSessionState |
Methods
CheckAvailability()
Start checking the availability of XR on the current device.
Declaration
public static IEnumerator CheckAvailability()Returns
| Type | Description |
|---|---|
| IEnumerator | An |
Remarks
The availability check can be asynchronous, so this is implemented as a coroutine. It is safe to call this multiple times; if called a second time while an availability check is being made, it returns a new coroutine which waits on the first.
Install()
Begin installing AR software on the current device (if supported).
Declaration
public static IEnumerator Install()Returns
| Type | Description |
|---|---|
| IEnumerator | An |
Remarks
Installation can be asynchronous, so this is implemented as a coroutine. It is safe to call this multiple times, but you must first call CheckAvailability().
You must call CheckAvailability() before trying to start the installation, and the state must not be Unsupported or this method will throw InvalidOperationException.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Thrown if state is None or Unsupported. |
OnDestroy()
Invoked when this MonoBehaviour is destroyed. Affects the state.
Declaration
protected override void OnDestroy()Overrides
OnDisable()
Invoked when this MonoBehaviour is disabled. Affects the state.
Declaration
protected override void OnDisable()Overrides
OnEnable()
Creates and initializes the session subsystem. Begins checking for availability.
Declaration
protected override void OnEnable()Overrides
Reset()
Resets the AR Session.
Declaration
public void Reset()Remarks
Resetting the session destroys all trackables and resets device tracking (for example, the position of the session is reset to the origin).
Events
stateChanged
This event is invoked whenever the state changes.
Declaration
public static event Action<ARSessionStateChangedEventArgs> stateChangedEvent Type
| Type | Description |
|---|---|
| Action<ARSessionStateChangedEventArgs> |