Google is committed to advancing racial equity for Black communities. See how.

ArAnchor

Describes a fixed location and orientation in the real world, representing local and Cloud Anchors.

Summary

Enumerations

ArCloudAnchorMode{
  AR_CLOUD_ANCHOR_MODE_DISABLED = 0,
  AR_CLOUD_ANCHOR_MODE_ENABLED = 1
}
enum
Indicates the cloud configuration of the ArSession.
ArCloudAnchorState{
  AR_CLOUD_ANCHOR_STATE_NONE = 0,
  AR_CLOUD_ANCHOR_STATE_TASK_IN_PROGRESS = 1,
  AR_CLOUD_ANCHOR_STATE_SUCCESS = 2,
  AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL = -1,
  AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED = -2,
  AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED = -4,
  AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED = -5,
  AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND = -6,
  AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD = -8,
  AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW = -9,
  AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE = -10
}
enum
Describes the current cloud state of an ArAnchor.
ArFeatureMapQuality{
  AR_FEATURE_MAP_QUALITY_INSUFFICIENT = 0,
  AR_FEATURE_MAP_QUALITY_SUFFICIENT = 1,
  AR_FEATURE_MAP_QUALITY_GOOD = 2
}
enum
Describes the quality of the visual features seen by ARCore in the preceding few seconds and visible from a desired camera ArPose.

Typedefs

ArAnchor typedef
struct ArAnchor_
A position in space attached to a trackable (reference type, long-lived).
ArAnchorList typedef
struct ArAnchorList_
A list of anchors (value type).

Functions

ArAnchorList_acquireItem(const ArSession *session, const ArAnchorList *anchor_list, int32_t index, ArAnchor **out_anchor)
void
Acquires a reference to an indexed entry in the list.
ArAnchorList_create(const ArSession *session, ArAnchorList **out_anchor_list)
void
Creates an anchor list object.
ArAnchorList_destroy(ArAnchorList *anchor_list)
void
Releases the memory used by an anchor list object, along with all the anchor references it holds.
ArAnchorList_getSize(const ArSession *session, const ArAnchorList *anchor_list, int32_t *out_size)
void
Retrieves the number of anchors in this list.
ArAnchor_acquireCloudAnchorId(ArSession *session, ArAnchor *anchor, char **out_cloud_anchor_id)
void
Acquires the Cloud Anchor ID of the anchor.
ArAnchor_detach(ArSession *session, ArAnchor *anchor)
void
Tells ARCore to stop tracking and forget this anchor.
ArAnchor_getCloudAnchorState(const ArSession *session, const ArAnchor *anchor, ArCloudAnchorState *out_state)
void
Gets the current Cloud Anchor state of the anchor.
ArAnchor_getPose(const ArSession *session, const ArAnchor *anchor, ArPose *out_pose)
void
Retrieves the pose of the anchor in the world coordinate space.
ArAnchor_getTrackingState(const ArSession *session, const ArAnchor *anchor, ArTrackingState *out_tracking_state)
void
Retrieves the current state of the pose of this anchor.
ArAnchor_release(ArAnchor *anchor)
void
Releases a reference to an anchor.

Enumerations

ArCloudAnchorMode

 ArCloudAnchorMode

Indicates the cloud configuration of the ArSession.

Properties
AR_CLOUD_ANCHOR_MODE_DISABLED

Cloud Anchors are disabled.

This is the value set in the default ArConfig.

AR_CLOUD_ANCHOR_MODE_ENABLED

This mode will enable Cloud Anchors.

Setting this value and calling ArSession_configure will require the application to have the Android INTERNET permission.

ArCloudAnchorState

 ArCloudAnchorState

Describes the current cloud state of an ArAnchor.

Properties
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND

Resolving failed, because the ARCore Cloud Anchor service could not find the provided Cloud Anchor ID.

AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED

Hosting failed, because the server could not successfully process the dataset for the given anchor.

The developer should try again after the device has gathered more data from the environment.

AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE

The ARCore Cloud Anchor service was unreachable.

This can happen for a number of reasons. The device might be in airplane mode or does not have a working internet connection. The request sent to the server might have timed out with no response, or there might be a bad network connection, DNS unavailability, firewall issues, or anything else that might affect the device's ability to connect to the ARCore Cloud Anchor service.

AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL

A hosting/resolving task for this anchor finished with an internal error.

The app should not attempt to recover from this error.

AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED

The authorization provided by the application is not valid.

  • The Google Cloud project may not have enabled the ARCore Cloud Anchor API.
  • It may fail if the operation you are trying to perform is not allowed.
  • When using API key authentication, this will happen if the API key in the manifest is invalid, unauthorized or missing. It may also fail if the API key is restricted to a set of apps not including the current one.
  • When using keyless authentication, this will happen if the developer fails to create OAuth client. It may also fail if Google Play Services isn't installed, is too old, or is malfunctioning for some reason (e.g. services killed due to memory pressure).

AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW

The Cloud Anchor could not be resolved because the SDK version used to resolve the anchor is newer than and incompatible with the version used to host it.

AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD

The Cloud Anchor could not be resolved because the SDK version used to resolve the anchor is older than and incompatible with the version used to host it.

AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED

The application has exhausted the request quota allotted to the given API key.

The developer should request additional quota for the ARCore Cloud Anchor service for their API key from the Google Developers Console.

AR_CLOUD_ANCHOR_STATE_NONE

The anchor is purely local.

It has never been hosted using ArSession_hostAndAcquireNewCloudAnchor, and has not been resolved using ArSession_resolveAndAcquireNewCloudAnchor.

AR_CLOUD_ANCHOR_STATE_SUCCESS

A hosting/resolving task for this anchor completed successfully.

AR_CLOUD_ANCHOR_STATE_TASK_IN_PROGRESS

A hosting/resolving task for the anchor is in progress.

Once the task completes in the background, the anchor will get a new cloud state after the next ArSession_update call.

ArFeatureMapQuality

 ArFeatureMapQuality

Describes the quality of the visual features seen by ARCore in the preceding few seconds and visible from a desired camera ArPose.

A higher quality indicates a Cloud Anchor hosted at the current time with the current set of recently seen features will generally be easier to resolve more accurately. For more details, see https://developers.google.com/ar/develop/c/cloud-anchors/overview-c

Properties
AR_FEATURE_MAP_QUALITY_GOOD

The quality of features seen from the pose in the preceding few seconds is likely sufficient for ARCore to successfully resolve (ArSession_resolveAndAcquireNewCloudAnchor) a Cloud Anchor with a high degree of accuracy.

AR_FEATURE_MAP_QUALITY_INSUFFICIENT

The quality of features seen from the pose in the preceding seconds is low.

This state indicates that ARCore will likely have more difficulty resolving (ArSession_resolveAndAcquireNewCloudAnchor) the Cloud Anchor. Encourage the user to move the device, so that the desired position of the Cloud Anchor to be hosted is seen from different angles.

AR_FEATURE_MAP_QUALITY_SUFFICIENT

The quality of features seen from the pose in the preceding few seconds is likely sufficient for ARCore to successfully resolve (ArSession_resolveAndAcquireNewCloudAnchor) a Cloud Anchor, although the accuracy of the resolved pose will likely be reduced.

Encourage the user to move the device, so that the desired position of the Cloud Anchor to be hosted is seen from different angles.

Typedefs

ArAnchor

struct ArAnchor_ ArAnchor

A position in space attached to a trackable (reference type, long-lived).

ArAnchorList

struct ArAnchorList_ ArAnchorList

A list of anchors (value type).

Functions

ArAnchorList_acquireItem

void ArAnchorList_acquireItem(
  const ArSession *session,
  const ArAnchorList *anchor_list,
  int32_t index,
  ArAnchor **out_anchor
)

Acquires a reference to an indexed entry in the list.

This call must eventually be matched with a call to ArAnchor_release.

ArAnchorList_create

void ArAnchorList_create(
  const ArSession *session,
  ArAnchorList **out_anchor_list
)

Creates an anchor list object.

ArAnchorList_destroy

void ArAnchorList_destroy(
  ArAnchorList *anchor_list
)

Releases the memory used by an anchor list object, along with all the anchor references it holds.

ArAnchorList_getSize

void ArAnchorList_getSize(
  const ArSession *session,
  const ArAnchorList *anchor_list,
  int32_t *out_size
)

Retrieves the number of anchors in this list.

ArAnchor_acquireCloudAnchorId

void ArAnchor_acquireCloudAnchorId(
  ArSession *session,
  ArAnchor *anchor,
  char **out_cloud_anchor_id
)

Acquires the Cloud Anchor ID of the anchor.

The ID acquired is an ASCII null-terminated string. The acquired ID must be released after use by the ArString_release function. For anchors with cloud state AR_CLOUD_ANCHOR_STATE_NONE or AR_CLOUD_ANCHOR_STATE_TASK_IN_PROGRESS, this will always be an empty string.

Details
Parameters
session
The ARCore session.
anchor
The anchor to retrieve the cloud ID of.
out_cloud_anchor_id
A pointer to the acquired ID string.

ArAnchor_detach

void ArAnchor_detach(
  ArSession *session,
  ArAnchor *anchor
)

Tells ARCore to stop tracking and forget this anchor.

This call does not release any references to the anchor - that must be done separately using ArAnchor_release.

ArAnchor_getCloudAnchorState

void ArAnchor_getCloudAnchorState(
  const ArSession *session,
  const ArAnchor *anchor,
  ArCloudAnchorState *out_state
)

Gets the current Cloud Anchor state of the anchor.

This state is guaranteed not to change until ArSession_update is called.

Details
Parameters
session
The ARCore session.
anchor
The anchor to retrieve the cloud state of.
out_state
The current cloud state of the anchor.

ArAnchor_getPose

void ArAnchor_getPose(
  const ArSession *session,
  const ArAnchor *anchor,
  ArPose *out_pose
)

Retrieves the pose of the anchor in the world coordinate space.

This pose produced by this call may change each time ArSession_update is called. This pose should only be used for rendering if ArAnchor_getTrackingState returns AR_TRACKING_STATE_TRACKING.

Details
Parameters
session
The ARCore session.
anchor
The anchor to retrieve the pose of.
out_pose
An already-allocated ArPose object into which the pose will be stored.

ArAnchor_getTrackingState

void ArAnchor_getTrackingState(
  const ArSession *session,
  const ArAnchor *anchor,
  ArTrackingState *out_tracking_state
)

Retrieves the current state of the pose of this anchor.

Note: Starting in ARCore 1.12, changing the active camera config using ArSession_setCameraConfig may cause the tracking state on certain devices to become permanently AR_TRACKING_STATE_PAUSED. For consistent behavior across all supported devices, release any previously created anchors and trackables when setting a new camera config.

ArAnchor_release

void ArAnchor_release(
  ArAnchor *anchor
)

Releases a reference to an anchor.

To stop tracking for this anchor, call ArAnchor_detach first.

This function may safely be called with NULL - it will do nothing.