XRGeospatialManager

Controls the lifecycle and configuration for a Geospatial Tracker.

There is only one active tracker. Adding multiple XRGeospatialManager components is not allowed.

You may enable or disable the XRGeospatialManager component to start or stop the tracker, the underlying resources will be released on stopped.

Summary

Inheritance

Inherits from: MonoBehaviour

Public static attributes
InitializationResult => _initializationResult
OpenXRResultStatus
The result returned from initialization.
OnStateChanged
The event fired whenever the State changes.

Properties
MaxNumberOfSurfaceAnchors = 0
uint
Gets the maximum number of surface anchors supported by the system.
PlaneTrackingInUse
bool
Gets a value indicating whether plane tracking is currently in use for surface anchors.
RequestedPlaneTracking
bool
Gets or sets a value indicating whether to request to use plane tracking for anchors if available.
State
Gets the state that represents the geospatial services.

Public attributes
Running => _state == XRGeospatialState.Running
bool
Gets a value indicating whether the Geospatial tracker is running.

Public functions
TryAttachGeospatialAnchor(XRGeospatialPose geospatialPose)
Result< ARShareableAnchor >
Attempts to create a shareable anchor "attached" to the given geospatial pose.
TryAttachSurfaceAnchorAsync(XRGeospatialSurfaceType type, XRGeospatialPose geospatialPose, System.Threading.CancellationToken cancellationToken)
Awaitable< Result< ARShareableAnchor > >
Attempts to create a shareable anchor "attached" to the given geospatial pose relative to the location's surface.
TryCheckVPSAvailabilityAsync(double latitude, double longitude)
async Awaitable< Result< XRVPSAvailability > >
Try to check the availability of VPS near a given location asynchronously.
TryLocate(Pose pose, out XRGeospatialPoseResult result)
bool
Try to locate the geospatial pose for the given reference frame, expressed as a pose related to Unity world space.
TryLocate(XRGeospatialPose geospatialPose, out XRPoseResult result)
bool
Try to locate the pose in Unity world space from a geospatial pose.

Public static attributes

InitializationResult

OpenXRResultStatus InitializationResult => _initializationResult

The result returned from initialization.

Check OpenXRResultStatus.nativeStatusCode for the failure reason. It can be XrResult.PermissionInsufficient, XrResultAndroid.GeospatialCloudAuthFailed or common OpenXR errors from XrResult. Once it's resolved, you may disable and re-enable the manager to retry initialization.

OnStateChanged

Action< XRGeospatialStateChangedEventArgs > OnStateChanged

The event fired whenever the State changes.

Properties

MaxNumberOfSurfaceAnchors

uint MaxNumberOfSurfaceAnchors = 0

Gets the maximum number of surface anchors supported by the system.

PlaneTrackingInUse

bool PlaneTrackingInUse

Gets a value indicating whether plane tracking is currently in use for surface anchors.

RequestedPlaneTracking

bool RequestedPlaneTracking

Gets or sets a value indicating whether to request to use plane tracking for anchors if available.

Must be called before enabling XRGeospatialManager.

State

static XRGeospatialState State

Gets the state that represents the geospatial services.

Used to determine the status of geospatial capability and tracker state.

Public attributes

Running

bool Running => _state == XRGeospatialState.Running

Gets a value indicating whether the Geospatial tracker is running.

  • Returns true after OnEnable() has been called and the initialization succeeded.
  • Returns false after OnDisable() is called or the initialization failed. Accessing geospatial API under this state may result in XrResultAndroid.GeospatialTrackerNotRunning error, check individual API for its requirement.

Public functions

TryAttachGeospatialAnchor

Result< ARShareableAnchor > TryAttachGeospatialAnchor(
  XRGeospatialPose geospatialPose
)

Attempts to create a shareable anchor "attached" to the given geospatial pose.

Details
Parameters
geospatialPose
The geospatial pose of the target location.
Returns
The result of the operation, containing the newly added shareable anchor if the operation succeeded.

TryAttachSurfaceAnchorAsync

Awaitable< Result< ARShareableAnchor > > TryAttachSurfaceAnchorAsync(
  XRGeospatialSurfaceType type,
  XRGeospatialPose geospatialPose,
  System.Threading.CancellationToken cancellationToken
)

Attempts to create a shareable anchor "attached" to the given geospatial pose relative to the location's surface.

Details
Parameters
type
The surface type of the geospatial anchor.
geospatialPose
The geospatial pose of the target location where XRGeospatialPose.Altitude represents the altitude in meters relative to the surface.
cancellationToken
An optional CancellationToken.
Exceptions
OperationCanceledException
Thrown if the operation has been canceled either by the caller or the Unity main thread.
Returns
The result of the operation, containing the newly added shareable anchor if the operation succeeded.

TryCheckVPSAvailabilityAsync

async Awaitable< Result< XRVPSAvailability > > TryCheckVPSAvailabilityAsync(
  double latitude,
  double longitude
)

Try to check the availability of VPS near a given location asynchronously.

A XRGeospatialState.Running tracker is not required, as long as Geospatial is supported and enabled by the current session.

Details
Parameters
latitude
The latitude of the location.
longitude
The longitude of the location.
Returns
The result of the asynchronous operation. It can fail with XrResult.PermissionInsufficient, XrResultAndroid.GeospatialCoordinateInvalid, and other common OpenXR errors from XrResult.

TryLocate

bool TryLocate(
  Pose pose,
  out XRGeospatialPoseResult result
)

Try to locate the geospatial pose for the given reference frame, expressed as a pose related to Unity world space.

A XRGeospatialState.Running tracker is required.

Details
Parameters
pose
The pose in Unity world space to be converted.
result
The result of geospatial pose.
Returns
True if the calculation succeeded, and use XRGeospatialPoseResult.LocationFlags to determine which fields are valid.

TryLocate

bool TryLocate(
  XRGeospatialPose geospatialPose,
  out XRPoseResult result
)

Try to locate the pose in Unity world space from a geospatial pose.

A XRGeospatialState.Running tracker is required.

Details
Parameters
geospatialPose
The geospatial pose to be converted.
result
The result of the pose in Unity world space.
Returns
True if the calculation succeeded, and use XRPoseResult.LocationFlags to determine which fields are valid. Otherwise, returns false. You may retry later with a different geospatial pose.