Meta Developers

An OVRAnchor can represent either a "spatial anchor", which is created and managed by the app, or a "scene anchor", which is created and managed by the system and used to represent the Scene Model.

This is a low-level, lightweight interface to access anchors. For more Unity-friendly components, see OVRSpatialAnchor (for spatial anchors) or Access Scene data with OVRAnchor for Scene.

This API gives you access to all anchor functionality:

FetchAnchorsAsync(List<OVRAnchor>,OVRAnchor.FetchOptions,Action<List<OVRAnchor>,int>): Query for anchors by UUID or by component types.
CreateSpatialAnchorAsync(Pose): Create a new spatial anchor (app owned)
GetComponent<T>: Access a component (for example, plane or volume data) associated with an anchor.
ShareAsync(IEnumerable<OVRSpaceUser>): Shares an anchor with one or more users.
SaveAsync(): Saves the anchor to persistent storage.
EraseAsync(): Erases the anchor from persistent storage.
Dispose: Destroys the runtime instance of the anchor.

Member Enumerations

Enumeration SaveResult

Possible results of a save operation.

Saving an anchor is an asynchronous operation that can fail for a number of reasons, enumerated here.

SaveResult is used as the status for the OVRResult returned by OVRAnchor.SaveAsync(), OVRAnchor.SaveAsync(IEnumerable<OVRAnchor>), OVRSpatialAnchor.SaveAnchorAsync, and OVRSpatialAnchor.SaveAnchorsAsync(IEnumerable<OVRSpatialAnchor>).

Success	The operation succeeded.
Failure	The operation failed in an unexpected way.
FailureInvalidAnchor	At least one anchor is invalid.
FailureDataIsInvalid	Typically indicates an uninitialized OVRResult, or a pending OVRTask which expected to have internal result data of a specific type set.
FailureInsufficientResources	Resource limitation prevented this operation from executing.
FailureStorageAtCapacity	The amount of device storage available for anchor data is insufficient for the requested save operation.
FailureInsufficientView	Device's view of the physical space is insufficient.
FailurePermissionInsufficient	User has not granted all the required permissions for the app to use this API.
FailureRateLimited	Operation canceled due to rate limiting.
FailureTooDark	The environment is too dark to save the anchor.
FailureTooBright	The environment is too bright to save the anchor.
FailureUnsupported	Save is not supported on this version or platform.
FailurePersistenceNotEnabled	One or more anchors do not have the OVRStorable component enabled, causing the save operation to fail.

Enumeration EraseResult

Possible results of an erase operation.

Saving an anchor is an asynchronous operation that can fail for a number of reasons, enumerated here.

EraseResult is used as the status for the OVRResult returned by OVRAnchor.EraseAsync(), OVRAnchor.EraseAsync(IEnumerable<OVRAnchor>,IEnumerable<Guid>), OVRSpatialAnchor.EraseAnchorAsync, and OVRSpatialAnchor.EraseAnchorsAsync(IEnumerable<OVRSpatialAnchor>,IEnumerable<Guid>).

Success	The operation succeeded.
Failure	The operation failed in an unexpected way.
FailureInvalidAnchor	At least one anchor is invalid.
FailureDataIsInvalid	Typically indicates an uninitialized OVRResult, or a pending OVRTask which expected to have internal result data of a specific type set.
FailureInsufficientResources	Resource limitation prevented this operation from executing.
FailurePermissionInsufficient	User has not granted all the required permissions for the app to use this API.
FailureRateLimited	Operation canceled due to rate limiting.
FailureUnsupported	Erase is not supported on this version or platform.
FailurePersistenceNotEnabled	One or more anchors do not have the OVRStorable component enabled, causing the erase operation to fail.

Enumeration FetchResult

Possible results of a fetch operation.

Use OVRAnchor.FetchAnchorsAsync(System.Collections.Generic.List<OVRAnchor>,OVRAnchor.FetchOptions,System.Action<System.Collections.Generic.List<OVRAnchor>,int>) to query for anchors. When that operation completes, use the resulting status code to determine whether the operation succeeded, or why it failed.

Success	The operation succeeded.
Failure	The operation failed in an unexpected way.
FailureDataIsInvalid	Typically indicates an uninitialized OVRResult, or a pending OVRTask which expected to have internal result data set.
FailureInvalidOption	One of the FetchOptions was invalid.
FailureInsufficientResources	Resource limitation prevented this operation from executing.
FailureInsufficientView	Device's view of the physical space is insufficient.
FailurePermissionInsufficient	User has not granted all the required permissions for the app to use this API.
FailureRateLimited	Operation canceled due to rate limiting.
FailureTooDark	The environment is too dark to load anchors.
FailureTooBright	The environment is too bright to load anchors.
FailureUnsupported	Fetch is not supported in this version or on this platform.

Enumeration ShareResult

Possible results of a share operation.

Sharing an anchor is an asynchronous operation that can fail for a number of reasons, enumerated here.

ShareResult is used as the status for the OVRResult returned by OVRAnchor.ShareAsync(IEnumerable<OVRSpaceUser>), OVRAnchor.ShareAsync(IEnumerable<OVRAnchor>,IEnumerable<OVRSpaceUser>), OVRSpatialAnchor.ShareAsync(Guid), OVRSpatialAnchor.ShareAsync(IEnumerable<OVRSpatialAnchor>, Guid), and OVRSpatialAnchor.ShareAsync(IEnumerable<OVRSpatialAnchor>, IEnumerable<Guid>)

Success	The operation succeeded.
Failure	The operation failed in an unexpected way.
FailureOperationFailed	The operation failed for unspecified reasons.
FailureInvalidParameter	API call was given an invalid parameter.
FailureHandleInvalid	One or more invalid handles were provided to the API.
FailureDataIsInvalid	Typically indicates an uninitialized OVRResult, or a pending OVRTask which expected to have internal result data of a specific type set.
FailureNetworkTimeout	A network timeout occurred.
FailureNetworkRequestFailed	Network request failed.
FailureMappingInsufficient	The device has not built a sufficient map of the environment to save the anchor(s).
FailureLocalizationFailed	The device was not able to localize the anchor(s) being shared.
FailureSharableComponentNotEnabled	Sharable component not enabled on the anchor(s) being shared.
FailureCloudStorageDisabled	Sharing failed because device has not enabled the "Share Point Cloud Data" setting.
FailurePermissionInsufficient	User has not granted all the required permissions for the app to use this API.
FailureUnsupported	Anchor Sharing is not supported with this version or on this platform.

Enumeration TrackableType

The type of trackable associated with an anchor, if applicable.

A "trackable" is an OVRAnchor that can be detected at runtime.

Use OVRAnchor.GetTrackableType to determine an anchor's trackable type.

None	The anchor is not a trackable.
Keyboard	The anchor is a tracked keyboard.

Enumeration ConfigureTrackerResult

The result of Tracker.ConfigureAsync.

Configuring an anchor tracker using Tracker.ConfigureAsync is an asynchronous operation that can fail for a number of reasons, enumerated here.

If any part of the requested TrackerConfiguration cannot be satisfied, then Tracker.ConfigureAsync will return something other than Success, even though some aspects may have succeeded.

See Also:

Tracker.ConfigureAsync

Success	The tracker was configured successfully.
Failure	Tracker configuration failed unexpectedly.
Invalid	The OVRResult does not represent a valid result.
NotSupported	A configuration is not supported.

Public Statics

static readonly OVRAnchor Null[Get]

Represents a null anchor.

Because OVRAnchor is a value-type, it is not C#-nullable. However, if you default-construct an OVRAnchor (instead of obtaining one from a query or creation method) then it will be equal to Null. You can test for null by comparing against Null:

async void CreateAnchor(Pose pose) {
  var anchor = await OVRAnchor.CreateSpatialAnchorAsync(pose);
if (anchor == OVRAnchor.Null) {
    Debug.LogError("Anchor creation failed!");
  } else {
// anchor is valid
  }
}

Properties

ulong Handle[Get]

Guid Uuid[Get]

The unique identifier of this anchor.

UUIDs persist across sessions. If you load a persisted anchor, you can use the UUID to identify it.

Static Member Functions

static OVRTask< TaskResult > FetchAnchorsAsync

( List< OVRAnchor > anchors,

FetchOptions options,

Action< List< OVRAnchor >, int > incrementalResultsCallback )

Fetch anchors matching a query.

This method queries for anchors that match the corresponding options . This method is asynchronous; use the returned OVRTask to check for completion.Anchors may be returned in batches. If incrementalResultsCallback is not null, then this delegate is invoked whenever results become available prior to the completion of the entire operation. New anchors are appended to anchors . The delegate receives a reference to anchors and the starting index of the anchors that have been added. The parameters are:

anchors: The same List provided by anchors .
index: The starting index of the newly available anchors

Parameters

anchors

A buffer to store the results. This container is cleared before any async requests are made.

options

Options describing which anchors to fetch.

incrementalResultsCallback

(Optional) A callback invoked when incremental results are available.

Returns

Returns an OVRTask that can be used to track the asynchronous fetch.

Exceptions

ArgumentNullException

Thrown if anchors is null.

static async OVRTask< TaskResult > FetchSharedAnchorsAsync

( Guid groupUuid,

List< OVRAnchor > anchors )

Loads all anchors shared with a group by its UUID.

This method is asynchronous. The returned OVRTask wrapper completes when all results are available. In order to be loaded, the anchor must have previously been shared with the group, e.g., with ShareAsync(IEnumerable<OVRAnchor>, Guid) or ShareAsync(Guid).

See Also:

OVRSpatialAnchor.LoadUnboundSharedAnchorsAsync(Guid,List<OVRSpatialAnchor.UnboundAnchor>)

Parameters

groupUuid

The group UUID from which to load any associated shared anchors.

See Also:

ShareAsync(IEnumerable<OVRAnchor>,Guid)

anchors

A non-null buffer to store the loaded anchors. This container is cleared before being populated.

Returns

Returns an OVRResult<List<OVRAnchor>,FetchResult>, which indicates the status of the load operation, as well as returning a now-populated reference to the anchors buffer list originally provided to this call. This result's Status will be FetchResult.FailureInvalidOption if groupUuid is Guid.Empty.

Exceptions

ArgumentNullException

Thrown if anchors is null.

static async OVRTask< TaskResult > FetchSharedAnchorsAsync

( Guid groupUuid,

IEnumerable< Guid > allowedAnchorUuids,

List< OVRAnchor > anchors )

Loads all anchors shared with a group by its UUID.

See Also:

OVRSpatialAnchor.LoadUnboundSharedAnchorsAsync(Guid,IEnumerable<Guid>,List<OVRSpatialAnchor.UnboundAnchor>)

Parameters

groupUuid

The group UUID from which to load any associated shared anchors.

See Also:

ShareAsync(IEnumerable<OVRAnchor>,Guid)

allowedAnchorUuids

A non-null, non-empty set of known anchor UUIDs to load from the group. They will not be loaded if:

they never existed
they've been erased from cloud storage
they were never shared to the given groupUuid Any anchor not specified will be omitted from the results in anchors . The elements in this set will NOT be individually validated; you should be sure that none of them are Guid.Empty before calling this API.

anchors

A non-null buffer to store the loaded anchors. This container is always cleared unless an exception is thrown.

Returns

Exceptions

ArgumentNullException

Thrown if either allowedAnchorUuids or anchors is null.

static OVRTask< OVRAnchor > CreateSpatialAnchorAsync

( Pose trackingSpacePose )

Creates a new spatial anchor.

Spatial anchor creation is asynchronous. This method initiates a request to create a spatial anchor at trackingSpacePose . The returned OVRTask<OVRAnchor> can be awaited or used to track the completion of the request.If spatial anchor creation fails, the resulting OVRAnchor will be OVRAnchor.Null.

Parameters

trackingSpacePose

The pose, in tracking space, at which you wish to create the spatial anchor.

Returns

A task which can be used to track completion of the request.

static OVRTask< OVRAnchor > CreateSpatialAnchorAsync

( Transform transform,

Camera centerEyeCamera )

Creates a new spatial anchor.

Spatial anchor creation is asynchronous. This method initiates a request to create a spatial anchor at transform . The returned OVRTask<OVRAnchor> can be awaited or used to track the completion of the request.If spatial anchor creation fails, the resulting OVRAnchor will be OVRAnchor.Null.

Parameters

transform

The transform at which you wish to create the spatial anchor.

centerEyeCamera

The Camera associated with the Meta Quest's center eye.

Returns

A task which can be used to track completion of the request.

Exceptions

ArgumentNullException

Thrown when transform is null.

ArgumentNullException

Thrown when centerEyeCamera is null.

static OVRTask< OVRResult< SaveResult > > SaveAsync

( IEnumerable< OVRAnchor > anchors )

Save a collection of anchors.

This method persists anchors so that they may be retrieved later.This operation is asynchronous. Use the returned OVRTask to track the result of the asynchronous operation.

Parameters

anchors

A collection of anchors to persist.

Returns

Returns an awaitable OVRTask representing the asynchronous request.

static OVRTask< OVRResult< EraseResult > > EraseAsync

( IEnumerable< OVRAnchor > anchors,

IEnumerable< Guid > uuids )

Erase a collection of anchors.

This method removes anchors from persistent storage.This operation is asynchronous. Use the returned OVRTask to track the result of the asynchronous operation.

Parameters

anchors

(Optional) A collection of anchors to remove from persistent storage.

uuids

(Optional) A collection of uuids to remove from persistent storage.

Returns

Returns an awaitable OVRTask representing the asynchronous request.

Exceptions

ArgumentException

Thrown if both anchors and uuids are null.

See Also:

SaveAsync(IEnumerable<OVRAnchor>)

static OVRTask< OVRResult< ShareResult > > ShareAsync

( IEnumerable< OVRAnchor > anchors,

IEnumerable< OVRSpaceUser > users )

Share a collection of anchors with a collection of users.

This method shares a collection of anchors with a collection of users.This operation is asynchronous. Use the returned OVRTask to track the result of the asynchronous operation.

Parameters

anchors

A collection of anchors to share.

users

A collection of users with whom anchors will be shared.

Returns

Returns an awaitable OVRTask representing the asynchronous request.

Exceptions

ArgumentNullException

Thrown if anchors or users are null.

ArgumentException

Thrown if users count is less than one.

See Also:

ShareAsync(IEnumerable<OVRSpaceUser>)

static OVRTask< OVRResult< ShareResult > > ShareAsync

( IEnumerable< OVRAnchor > anchors,

Guid groupUuid )

Shares a collection of anchors to a group.

This method is asynchronous; use the returned OVRTask wrapper to be notified of completion. The groupUuid parameter can be any valid Guid, which excludes the default value Guid, AKA Guid.Empty.

Parameters

anchors

The collection of anchors to share.

groupUuid

A UUID of a group to share the anchors with. Anchors shared to this groupUuid can be loaded by other clients via LoadUnboundSharedAnchorsAsync(Guid,List<UnboundAnchor>). NOTE: You may arbitrarily generate your own UUIDs (e.g. with System.Guid.NewGuid), or you may use UUIDs provided by colocation APIs such as in OVRColocationSession.

Returns

Returns an OVRResult<OVRAnchor.ShareResult> indicating the status of the share operation.

Exceptions

ArgumentNullException

Thrown if anchors is null.

static bool operator==

( OVRAnchor lhs,

OVRAnchor rhs )

Compares two anchors for equality.

This is the same equality test as Equals(OVRAnchor).

Parameters

lhs

The anchor to compare with rhs .

rhs

The anchor to compare with lhs .

Returns

Returns true if lhs is equal to rhs , otherwise false.

static bool operator!=

( OVRAnchor lhs,

OVRAnchor rhs )

Compares two anchors for inequality.

This is the logical negation of Equals(OVRAnchor).

Parameters

lhs

The anchor to compare with rhs .

rhs

The anchor to compare with lhs .

Returns

Returns true if lhs is not equal to rhs , otherwise false.

static OVRTask< bool > FetchAnchorsAsync< T >

( IList< OVRAnchor > anchors,

OVRSpace.StorageLocation location,

int maxResults,

double timeout )

(Obsolete) Asynchronous method that fetches anchors with a specific component.

Dispose of the returned OVRTask<bool> if you don't use the results

Others

The type of component the fetched anchor must have.

Parameters

anchors

IList that will get cleared and populated with the requested anchors.

Parameters

location

Storage location to query

maxResults

The maximum number of results the query can return

timeout

Timeout in seconds for the query.

Deprecated

This method is obsolete. Use FetchAnchorsAsync(List<OVRAnchor>,FetchOptions,Action<List<OVRAnchor>, int>) instead.

Returns

Returns an OVRTask<bool> that will eventually let you test if the fetch was successful or not. If the result is true, then the anchors parameter has been populated with the requested anchors.

Exceptions

System.ArgumentNullException

Thrown if anchors is null.

static OVRTask< bool > FetchAnchorsAsync

( IEnumerable< Guid > uuids,

IList< OVRAnchor > anchors,

OVRSpace.StorageLocation location,

double timeout )

(Obsolete) Asynchronous method that fetches anchors with specifics uuids.

Parameters

uuids

Enumerable of uuids that anchors fetched must verify

anchors

IList that will get cleared and populated with the requested anchors.

Parameters

location

Storage location to query

timeout

Timeout in seconds for the query.

Dispose of the returned OVRTask<bool> if you don't use the results Deprecated

This method is obsolete. Use FetchAnchorsAsync(List<OVRAnchor>,FetchOptions,Action<List<OVRAnchor>, int>) instead.

Returns

Returns an OVRTask<bool> that will eventually let you test if the fetch was successful or not. If the result is true, then the anchors parameter has been populated with the requested anchors.

Exceptions

System.ArgumentNullException

Thrown if uuids is null.

System.ArgumentNullException

Thrown if anchors is null.

static async OVRTask< OVRResult< List< OVRAnchor >, FetchResult > > FetchTrackablesAsync

( List< OVRAnchor > anchors,

IEnumerable< TrackableType > trackableTypes,

Action< List< OVRAnchor >, int > incrementalResultsCallback )

Fetch anchors by TrackableType.

This method queries for anchors of the given trackableTypes . This method is asynchronous; use the returned OVRTask to check for completion.Anchors may be returned in batches. If incrementalResultsCallback is not null, then this delegate is invoked whenever results become available prior to the completion of the entire operation. New anchors are appended to anchors . The delegate receives a reference to anchors and the starting index of the anchors that have been added. The parameters are:

anchors: The same List provided by anchors .
index: The starting index of the newly available anchors

Parameters

anchors

Container to store the results. The list is cleared before adding any anchors.

trackableTypes

The type of trackables to fetch.

incrementalResultsCallback

(Optional) A callback invoked when incremental results are available.

Returns

Returns an OVRTask that can be used to track the asynchronous fetch.

Exceptions

ArgumentNullException

Thrown if anchors is null.

ArgumentNullException

Thrown if trackableTypes is null.

Member Functions

OVRTask< OVRResult< SaveResult > > SaveAsync ( )

Save this anchor.

This method persists the anchor so that it may be retrieved later, e.g., by using FetchAnchorsAsync(List<OVRAnchor>,FetchOptions,Action<List<OVRAnchor>,int>).This operation is asynchronous. Use the returned OVRTask to track the result of the asynchronous operation.NOTE: When saving multiple anchors, it is more efficient to save them in a batch using SaveAsync(IEnumerable<OVRAnchor>).

Returns

An awaitable OVRTask representing the asynchronous request.

OVRTask< OVRResult< EraseResult > > EraseAsync ( )

Erases this anchor.

This method removes the anchor from persistent storage. Note this does not destroy the current instance.This operation is asynchronous. Use the returned OVRTask to track the result of the asynchronous operation.NOTE: When erasing multiple anchors, it is more efficient to erase them in a batch using EraseAsync(IEnumerable<OVRAnchor>,IEnumerable<Guid>).

Returns

An awaitable OVRTask representing the asynchronous request.

OVRTask< OVRResult< ShareResult > > ShareAsync

( IEnumerable< OVRSpaceUser > users )

Share this anchor with the specified users.

This method shares the anchor with a collection of OVRSpaceUser.This operation is asynchronous. Use the returned OVRTask to track the result of the asynchronous operation.

Parameters

users

A collection of users with whom anchors will be shared.

Returns

An awaitable OVRTask representing the asynchronous request.

Exceptions

ArgumentNullException

Thrown if users is null.

ArgumentException

Thrown if users count is less than one.

OVRTask< OVRResult< ShareResult > > ShareAsync

( Guid groupUuid )

Shares this anchor with the group associated with the given UUID.

This method is asynchronous; use the returned OVRTask wrapper to be notified of completion.The groupUuid parameter can be any valid Guid, which excludes the default value Guid, AKA Guid.Empty.

Parameters

groupUuid

A UUID of a group to share the anchor with. Anchors shared to this groupUuid can be loaded by other clients via LoadUnboundSharedAnchorsAsync(Guid,List<UnboundAnchor>). NOTE: You may arbitrarily generate your own UUIDs (e.g. with System.Guid.NewGuid), or you may use UUIDs provided by colocation APIs such as in OVRColocationSession.

Returns

Returns an OVRResult<OVRAnchor.ShareResult> indicating the status of the share operation.

T GetComponent< T > ( )

Gets the anchor's component of a specific type.

Make sure the anchor supports the specified type of component using SupportsComponent<T>

Others

The type of the component.

Returns

The requested component.

Exceptions

InvalidOperationException

Thrown if the anchor doesn't support the specified type of component.

bool TryGetComponent< T >

( out T component )

Tries to get the anchor's component of a specific type.

Parameters

component

The requested component, as an out parameter.

Others

The type of the component.

Returns

Whether or not the request succeeded. It may fail if the anchor doesn't support this type of component.

See Also:

GetComponent<T>

bool SupportsComponent< T > ( )

Tests whether or not the anchor supports a specific type of component.

For performance reasons, we use xrGetSpaceComponentStatusFB, which can result in an error in the logs when the component is not available.This error does not have impact on the control flow. The alternative method,

avoids this error reporting, but does have performance constraints.

Others

The type of the component.

Returns

Whether or not the specified type of component is supported.

bool GetSupportedComponents

( List< SpaceComponentType > components )

Get all the supported components of an anchor.

Parameters

components

The list to populate with the supported components. The list is cleared first.

Returns

true if the supported components could be retrieved, otherwise false.

bool Equals

( OVRAnchor other )

Compares two anchors for equality.

Parameters

other

The anchor to compare with this one.

Returns

Returns true if both anchor UUIDs are the same and they are the same runtime instance. That is, they are the same instance of the same anchor.

override bool Equals

( object obj )

Compares this anchor with an object for equality.

Parameters

obj

The object to compare with this anchor.

Returns

Returns true if obj is an OVRAnchor and Equals(OVRAnchor) is also true, otherwise false.

override int GetHashCode ( )

Generates a hash code suitable for use in a Dictionary or HashSet

Returns

Returns a hash code suitable for use in a Dictionary or HashSet

override string ToString ( )

Generates a string representation of this anchor, based on its Uuid.

Returns

Returns the stringification of this anchor's Uuid.

void Dispose ( )

Disposes of an anchor.

Calling this method will destroy the anchor so that it won't be managed by internal systems until the next time it is fetched again.

TrackableType GetTrackableType ( )

Gets the type of trackable this anchor represents, or TrackableType.None.

Returns

Returns the type of trackable this anchor represents.