interface IARSession (Niantic.ARDK.AR.IARSession)

Overview

Main object for managing AR experiences. More…

interface IARSession: IDisposable {
    // properties

    IARConfiguration Configuration;
    IARFrame CurrentFrame;
    ARFrameDisposalPolicy DefaultFrameDisposalPolicy;
    HandTracker HandTracker;
    IARMesh Mesh;
    RuntimeEnvironment RuntimeEnvironment;
    Guid StageIdentifier;
    ARSessionState State;
    float WorldScale;

    // events

    event AnchorsAdded();
    event AnchorsMerged();
    event AnchorsRemoved();
    event AnchorsUpdated();
    event CameraTrackingStateChanged();
    event Deinitialized();
    event FrameUpdated();
    event MapsAdded();
    event MapsUpdated();
    event Paused();
    event QueryingShouldSessionAttemptRelocalization();
    event Ran();
    event SessionFailed();
    event SessionInterrupted();
    event SessionInterruptionEnded();

    // methods

    IARAnchor AddAnchor(Matrix4x4 transform);

    AwarenessInitializationStatus GetAwarenessInitializationStatus(
        out AwarenessInitializationError error,
        out string errorMessage
    );

    void Pause();
    void RemoveAnchor(IARAnchor anchor);

    void Run(
        IARConfiguration configuration,
        ARSessionRunOptions options = ARSessionRunOptions.None
    );

    void SetupLocationService(ILocationService locationService);
};

// direct descendants

interface IMockARSession;

Detailed Documentation

Main object for managing AR experiences.

Note

In order to release underlying native resources quickly, it is important to call Dispose when you’re done with an IARSession instance rather than leaving it for the garbage collector.

Properties

IARConfiguration Configuration

Object that defines what tracking, mapping, and depth processing behaviours are enabled in the session.

IARFrame CurrentFrame

AR interpretation of the world most recently surfaced by the session.

Note

May be null.

ARFrameDisposalPolicy DefaultFrameDisposalPolicy

Gets or sets the “Disposal Policy” of the frames. By default, all frames are fully disposed after a new frame is available. This can be changed to just release the image and textures (so other traits like Anchors can still be accessed) or to be completely keep them in memory. Assuming you change this value, you should also correctly dispose of the frames on your own after you finish reusing them.

HandTracker HandTracker

Getting hand tracker that will update when hands are detected.

Note

This is an experimental feature. Experimental features should not be used in production products as they are subject to breaking changes, not officially supported, and may be deprecated without notice

IARMesh Mesh

The mesh generated by the currently running session.

Note

Will never be null, but will only contain data when meshing is enabled.

RuntimeEnvironment RuntimeEnvironment

The runtime environment this ARSession is compatible with.

Guid StageIdentifier

An identifier used internally to relate different systems. This is the identifier for the AR system.

ARSessionState State

Current state of the session.

float WorldScale

World scale applied to all transforms.

Note

This factor scales what we internally represent as a meter. Set to 2 means that for every meter the device moves in the real world, the virtual camera will move 2 meters effectively scaling “down” the virtual world.

Events

event AnchorsAdded()

Alerts subscribers when one or more anchors have been added to the session.

event AnchorsMerged()

Alerts subscribers that anchors have been merged and the duplicates have been removed.

event AnchorsRemoved()

Alerts subscribers when one or more anchors have been removed from the session. After an Anchor is removed from the session, it is disposed of and can’t be used anymore.

event AnchorsUpdated()

Alerts subscribers when one or more anchors have been updated.

event CameraTrackingStateChanged()

Informs subscribers to changes in the quality of the position tracking.

event Deinitialized()

Called when the session is deinitialized.

event FrameUpdated()

Called when the session receives an updated ARFrame.

event MapsAdded()

Alerts subscribers when one or more maps have been added to the session.

event MapsUpdated()

Alerts subscribers when one or more maps have been updated.

event Paused()

Called when the session has just been paused.

event QueryingShouldSessionAttemptRelocalization()

Asks the event subscribers whether to attempt recovery of world-tracking peerState after an interruption. Defaults to return false. To tell that a recovery attempt should be made, set the args.ShouldSessionAttemptRelocalization to true.

In the event of multiple subscribers, values are aggregated via OR.

Note

This event will only fire on iOS.

Note

Not supported in Remote Debugging.

event Ran()

Called when the session has just been run.

event SessionFailed()

Informs subscribers when the session has stopped running due to an error.

event SessionInterrupted()

Informs subscribers when the session has temporarily stopped processing frames and tracking position.

Note

This event will only fire on iOS.

event SessionInterruptionEnded()

Informs subscribers when the session has resumed processing from an interrupted peerState.

Note

This event will only fire on iOS.

Methods

IARAnchor AddAnchor(Matrix4x4 transform)

Creates and adds an anchor to be tracked by the session.

Parameters:

transform

Position, rotation and scale of the anchor in the coordinate space of the AR session it will be tracked in.

Returns:

The created anchor.

AwarenessInitializationStatus GetAwarenessInitializationStatus(
    out AwarenessInitializationError error,
    out string errorMessage
)

Check the status of the initialization process required to run ContextAwareness features.

Note

On devices where LiDAR is available, the Awareness algorithm will not be automatically initialized when meshing is enabled.

Parameters:

error	When this method returns, contains an enum value describing the error status of initialization.
errorMessage	When this method returns, contains an error message if an error occured. Otherwise, an empty string.

Returns:

Enum value describing where in the ContextAwareness initialization process the session is currently at.

void Pause()

Pauses processing in the session.

Note

If the device moves while the session is paused and then the session restarts running, world tracking will be incorrect until the session is able to re-localize.

void RemoveAnchor(IARAnchor anchor)

Removes the specified anchor from being tracked by the session.

Parameters:

anchor

The anchor to remove.

void Run(
    IARConfiguration configuration,
    ARSessionRunOptions options = ARSessionRunOptions.None
)

Starts AR processing with the specified configuration and options.

Note

Run can safely be called at any point during the application’s run cycle, but if it has been called before, passing in a configuration of a different type than the current configuration may result in tracking being reset.

Parameters:

configuration	Object that defines what tracking, mapping, and depth processing behaviours are enabled in the session.
options	Options defining how to transition the session if you are changing its configuration. This parameter has no effect if running the session for the first time.

void SetupLocationService(ILocationService locationService)

Set up this session to listen to updates from the provided location service.

Parameters:

locationService

The location service to listen to updates from.