ArAnchor

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

Summary

Enumerations

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
Result of a Cloud Anchor hosting or resolving operation.
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.
ArRooftopAnchorState{
  AR_ROOFTOP_ANCHOR_STATE_NONE = 0,
  AR_ROOFTOP_ANCHOR_STATE_SUCCESS = 1,
  AR_ROOFTOP_ANCHOR_STATE_ERROR_INTERNAL = -1,
  AR_ROOFTOP_ANCHOR_STATE_ERROR_NOT_AUTHORIZED = -2,
  AR_ROOFTOP_ANCHOR_STATE_ERROR_UNSUPPORTED_LOCATION = -3
}
enum
Describes the current Rooftop anchor state of an ArAnchor.
ArTerrainAnchorState{
  AR_TERRAIN_ANCHOR_STATE_NONE = 0,
  AR_TERRAIN_ANCHOR_STATE_TASK_IN_PROGRESS = 1,
  AR_TERRAIN_ANCHOR_STATE_SUCCESS = 2,
  AR_TERRAIN_ANCHOR_STATE_ERROR_INTERNAL = -1,
  AR_TERRAIN_ANCHOR_STATE_ERROR_NOT_AUTHORIZED = -2,
  AR_TERRAIN_ANCHOR_STATE_ERROR_UNSUPPORTED_LOCATION = -3
}
enum
Describes the result of a Terrain anchor resolving operation.

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
Deprecated. Use ArHostCloudAnchorFuture_acquireResultCloudAnchorId instead.
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
Deprecated. Use ArHostCloudAnchorFuture_getResultCloudAnchorState or ArResolveCloudAnchorFuture_getResultCloudAnchorState instead.
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_getTerrainAnchorState(const ArSession *session, const ArAnchor *anchor, ArTerrainAnchorState *out_state)
void
Deprecated. Use ArResolveAnchorOnTerrainFuture_getResultTerrainAnchorState.
Gets the current Terrain anchor state of the anchor.
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

ArCloudAnchorState

 ArCloudAnchorState

Result of a Cloud Anchor hosting or resolving operation.

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 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 API for their API key from the Google Developers Console.

AR_CLOUD_ANCHOR_STATE_NONE

Not a valid value for a Cloud Anchor operation.

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. See the Cloud Anchors developer guide for more information.

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 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 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 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.

ArRooftopAnchorState

 ArRooftopAnchorState

Describes the current Rooftop anchor state of an ArAnchor.

Obtained by ArResolveAnchorOnRooftopFuture_getResultRooftopAnchorState or as a parameter to the callback.

Properties
AR_ROOFTOP_ANCHOR_STATE_ERROR_INTERNAL

Resolving task for this anchor finished with an internal error.

The app should not attempt to recover from this error.

AR_ROOFTOP_ANCHOR_STATE_ERROR_NOT_AUTHORIZED

The authorization provided by the application is not valid.

  • The Google Cloud project may not have enabled the ARCore API.
  • When using API key authentication, this will happen if the API key in the manifest is invalid or unauthorized. 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 may happen when no OAuth client has been created, or when the signing key and package name combination does not match the values used in the Google Cloud project. It may also fail if Google Play Services isn't installed, is too old, or is malfunctioning for some reason (e.g. killed due to memory pressure).

AR_ROOFTOP_ANCHOR_STATE_ERROR_UNSUPPORTED_LOCATION

There is no rooftop or terrain info at this location, such as the center of the ocean.

AR_ROOFTOP_ANCHOR_STATE_NONE

Not a valid value for a Rooftop anchor operation.

AR_ROOFTOP_ANCHOR_STATE_SUCCESS

A resolving task for this anchor has been successfully resolved.

ArTerrainAnchorState

 ArTerrainAnchorState

Describes the result of a Terrain anchor resolving operation.

Properties
AR_TERRAIN_ANCHOR_STATE_ERROR_INTERNAL

Resolving task for this anchor finished with an internal error.

The app should not attempt to recover from this error.

AR_TERRAIN_ANCHOR_STATE_ERROR_NOT_AUTHORIZED

The authorization provided by the application is not valid.

  • The Google Cloud project may not have enabled the ARCore API.
  • When using API key authentication, this will happen if the API key in the manifest is invalid or unauthorized. 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 may happen when no OAuth client has been created, or when the signing key and package name combination does not match the values used in the Google Cloud project. It may also fail if Google Play Services isn't installed, is too old, or is malfunctioning for some reason (e.g. killed due to memory pressure).

AR_TERRAIN_ANCHOR_STATE_ERROR_UNSUPPORTED_LOCATION

There is no terrain info at this location, such as the center of the ocean.

AR_TERRAIN_ANCHOR_STATE_NONE

Not a valid value for a terrain anchor operation.

AR_TERRAIN_ANCHOR_STATE_SUCCESS

A resolving task for this anchor has been successfully resolved.

AR_TERRAIN_ANCHOR_STATE_TASK_IN_PROGRESS

Resolving the Terrain anchor is in progress.

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

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.

Deprecated. Use ArHostCloudAnchorFuture_acquireResultCloudAnchorId instead.

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.

Deprecated. Use ArHostCloudAnchorFuture_getResultCloudAnchorState or ArResolveCloudAnchorFuture_getResultCloudAnchorState instead.

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_getTerrainAnchorState

void ArAnchor_getTerrainAnchorState(
  const ArSession *session,
  const ArAnchor *anchor,
  ArTerrainAnchorState *out_state
)

Gets the current Terrain anchor state of the anchor.

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

Deprecated. Use ArResolveAnchorOnTerrainFuture_getResultTerrainAnchorState.

Details
Parameters
session
The ARCore session.
anchor
The anchor to retrieve the terrain anchor state of.
out_state
The current terrain anchor state of the anchor. Non-terrain anchors will always be in AR_TERRAIN_ANCHOR_STATE_NONE state.

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.