# ArEarth

A `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable` implementation representing the Earth.

Provides localization ability in geospatial coordinates.

To access `https://developers.google.com/ar/reference/c/group/ar-earth#arearth`, configure the session with an appropriate `https://developers.google.com/ar/reference/c/group/ar-config#argeospatialmode` and use `https://developers.google.com/ar/reference/c/group/ar-session#arsession_acquireearth`.

Not all devices support `https://developers.google.com/ar/reference/c/group/ar-config#ar_geospatial_mode_enabled`, use `https://developers.google.com/ar/reference/c/group/ar-session#arsession_isgeospatialmodesupported` to check if the current device and selected camera support enabling this mode.

`https://developers.google.com/ar/reference/c/group/ar-earth#arearth` should only be used when its `https://developers.google.com/ar/reference/c/group/shared-types#artrackingstate` is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`, and otherwise should not be used. Use `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_gettrackingstate` to obtain the current `https://developers.google.com/ar/reference/c/group/shared-types#artrackingstate`. If the `https://developers.google.com/ar/reference/c/group/shared-types#artrackingstate` does not become `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`, then `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_getearthstate` may contain more information as `https://developers.google.com/ar/reference/c/group/ar-earth#arearthstate`.

Use `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_getcamerageospatialpose` to obtain the Earth-relative virtual camera pose for the latest frame.

Use `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_acquirenewanchor` to attach anchors to Earth. Calling `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_acquirenewanchor` with an `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` instance will fail to create a new anchor and will return the `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_invalid_argument` error code.

`https://developers.google.com/ar/reference/c/group/ar-earth#arearth` does not support hit testing. Because `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` is a type of `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable`, the singleton `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` instance may also be returned by `https://developers.google.com/ar/reference/c/group/ar-session#arsession_getalltrackables` when enabled.

## Summary

| ### Enumerations ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-earth#arearthstate{ https://developers.google.com/ar/reference/c/group/ar-earth#ar_earth_state_enabled = 0, https://developers.google.com/ar/reference/c/group/ar-earth#ar_earth_state_error_internal = -1, https://developers.google.com/ar/reference/c/group/ar-earth#ar_earth_state_error_geospatial_mode_disabled = -2, https://developers.google.com/ar/reference/c/group/ar-earth#ar_earth_state_error_not_authorized = -3, https://developers.google.com/ar/reference/c/group/ar-earth#ar_earth_state_error_resource_exhausted = -4, https://developers.google.com/ar/reference/c/group/ar-earth#ar_earth_state_error_apk_version_too_old = -5 }` | enumDescribes the current state of `https://developers.google.com/ar/reference/c/group/ar-earth#arearth`. |

| ### Typedefs ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` | typedef `struct ArEarth_` The Earth trackable ([reference type, long-lived](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)). |

| ### Functions ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_acquirenewanchor(https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-earth#arearth *earth, double latitude, double longitude, double altitude, const float *eus_quaternion_4, https://developers.google.com/ar/reference/c/group/ar-anchor#aranchor **out_anchor)` | `https://developers.google.com/ar/reference/c/group/shared-types#arstatus` Creates a new `https://developers.google.com/ar/reference/c/group/ar-anchor#aranchor` at the specified geodetic location and orientation relative to the Earth. |
| `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_getcamerageospatialpose(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-earth#arearth *earth, https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose *out_camera_geospatial_pose)` | `void` Returns the Earth-relative camera pose for the latest frame. |
| `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_getearthstate(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-earth#arearth *earth, https://developers.google.com/ar/reference/c/group/ar-earth#arearthstate *out_state)` | `void` Gets the current `https://developers.google.com/ar/reference/c/group/ar-earth#arearthstate` of the `https://developers.google.com/ar/reference/c/group/ar-earth#arearth`. |
| `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_getgeospatialpose(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-earth#arearth *earth, const https://developers.google.com/ar/reference/c/group/ar-pose#arpose *pose, https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose *out_geospatial_pose)` | `https://developers.google.com/ar/reference/c/group/shared-types#arstatus` Converts the provided `pose` to a `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose` with respect to the Earth. |
| `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_getpose(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-earth#arearth *earth, double latitude, double longitude, double altitude, const float *eus_quaternion_4, https://developers.google.com/ar/reference/c/group/ar-pose#arpose *out_pose)` | `https://developers.google.com/ar/reference/c/group/shared-types#arstatus` Converts the provided Earth specified horizontal position, altitude and rotation with respect to an east-up-south coordinate frame to a pose with respect to GL world coordinates. |
| `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_resolveanchoronrooftopasync(https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-earth#arearth *earth, double latitude, double longitude, double altitude_above_rooftop, const float *eus_quaternion_4, void *context, https://developers.google.com/ar/reference/c/group/ar-resolve-anchor-on-rooftop-future#arresolveanchoronrooftopcallback callback, https://developers.google.com/ar/reference/c/group/ar-resolve-anchor-on-rooftop-future#arresolveanchoronrooftopfuture **out_future)` | `https://developers.google.com/ar/reference/c/group/shared-types#arstatus` Asynchronously creates an anchor at a specified horizontal position and altitude relative to the horizontal position's rooftop. |
| `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_resolveanchoronterrainasync(https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-earth#arearth *earth, double latitude, double longitude, double altitude_above_terrain, const float *eus_quaternion_4, void *context, https://developers.google.com/ar/reference/c/group/ar-resolve-anchor-on-terrain-future#arresolveanchoronterraincallback callback, https://developers.google.com/ar/reference/c/group/ar-resolve-anchor-on-terrain-future#arresolveanchoronterrainfuture **out_future)` | `https://developers.google.com/ar/reference/c/group/shared-types#arstatus` Asynchronously creates an anchor at a specified horizontal position and altitude relative to the horizontal position's terrain. |
| `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_resolveandacquirenewanchoronterrain(https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-earth#arearth *earth, double latitude, double longitude, double altitude_above_terrain, const float *eus_quaternion_4, https://developers.google.com/ar/reference/c/group/ar-anchor#aranchor **out_anchor)` | `https://developers.google.com/ar/reference/c/group/shared-types#arstatus` **[Deprecated.](https://developers.google.com/ar/reference/c/deprecated/deprecated)** Use `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_resolveanchoronterrainasync` instead. Creates an anchor at a specified horizontal position and altitude relative to the horizontal position's terrain. |

## Enumerations

### ArEarthState

```
 ArEarthState
```
Describes the current state of `https://developers.google.com/ar/reference/c/group/ar-earth#arearth`.

When `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_gettrackingstate` does not become `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`, `https://developers.google.com/ar/reference/c/group/ar-earth#arearthstate` may contain the cause of this failure.

Obtain using `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_getearthstate`.

| Properties ||
|---|---|
| `AR_EARTH_STATE_ENABLED` | `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` is enabled, and has not encountered any problems. Check `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_gettrackingstate` to determine if it can be used. |
| `AR_EARTH_STATE_ERROR_APK_VERSION_TOO_OLD` | The APK is older than the supported version. |
| `AR_EARTH_STATE_ERROR_GEOSPATIAL_MODE_DISABLED` | The given `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` is no longer valid and has `https://developers.google.com/ar/reference/c/group/shared-types#artrackingstate``https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_stopped` due to `https://developers.google.com/ar/reference/c/group/ar-config#ar_geospatial_mode_disabled` being set on the `https://developers.google.com/ar/reference/c/group/ar-session#arsession`. The given `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` object should be released by calling `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_release`. |
| `AR_EARTH_STATE_ERROR_INTERNAL` | Earth localization has encountered an internal error. The app should not attempt to recover from this error. Please see the Android logs for additional information. |
| `AR_EARTH_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). <br /> |
| `AR_EARTH_STATE_ERROR_RESOURCE_EXHAUSTED` | The application has exhausted the quota allotted to the given Google Cloud project. The developer should [request additional quota](https://cloud.google.com/docs/quota#requesting_higher_quota) for the ARCore API for their project from the Google Cloud Console. |

## Typedefs

### ArEarth

```
struct ArEarth_ ArEarth
```
The Earth trackable ([reference type, long-lived](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).


- Trackable type: `https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_earth`
- Acquire with: `https://developers.google.com/ar/reference/c/group/ar-session#arsession_acquireearth`
- Release with: `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_release`

<br />

## Functions

### ArEarth_acquireNewAnchor

```
ArStatus ArEarth_acquireNewAnchor(
  ArSession *session,
  ArEarth *earth,
  double latitude,
  double longitude,
  double altitude,
  const float *eus_quaternion_4,
  ArAnchor **out_anchor
)
```
Creates a new `https://developers.google.com/ar/reference/c/group/ar-anchor#aranchor` at the specified geodetic location and orientation relative to the Earth.

Latitude and longitude are defined by the [WGS84 specification](https://en.wikipedia.org/wiki/World_Geodetic_System), and altitude values are defined as the elevation above the WGS84 ellipsoid in meters.

The rotation provided by `eus_quaternion_4` is a rotation with respect to an east-up-south coordinate frame. An identity rotation will have the anchor oriented such that X+ points to the east, Y+ points up away from the center of the earth, and Z+ points to the south.

An anchor's `https://developers.google.com/ar/reference/c/group/shared-types#artrackingstate` will be `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_paused` while `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_paused`. The tracking state will permanently become `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_stopped` if the `https://developers.google.com/ar/reference/c/group/ar-session#arsession` configuration is set to `https://developers.google.com/ar/reference/c/group/ar-config#ar_geospatial_mode_disabled`.

Creating anchors near the north pole or south pole is not supported. If the latitude is within 0.1 degrees of the north pole or south pole (90 degrees or -90 degrees), this function will return `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_invalid_argument` and the anchor will fail to be created.


| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `earth` | The `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` handle. | | `latitude` | The latitude of the anchor relative to the WGS84 ellipsoid. | | `longitude` | The longitude of the anchor relative to the WGS84 ellipsoid. | | `altitude` | The altitude of the anchor relative to the WGS84 ellipsoid, in meters. | | `eus_quaternion_4` | The rotation quaternion as {qx, qy, qx, qw}. | | `out_anchor` | The newly-created `https://developers.google.com/ar/reference/c/group/ar-anchor#aranchor`. This will be set to `NULL` if no anchor was created. | |
| **Returns** | `https://developers.google.com/ar/reference/c/group/shared-types#ar_success` or any of: - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_illegal_state` if `earth` is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_stopped` due to `https://developers.google.com/ar/reference/c/group/ar-config#ar_geospatial_mode_disabled` configured on the `https://developers.google.com/ar/reference/c/group/ar-session#arsession`. Reacquire `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` if earth mode was reenabled. - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_invalid_argument` if `latitude` is outside the allowable range, or if either `session`, `earth`, or `eus_quaternion_4` is `NULL`. |

### ArEarth_getCameraGeospatialPose

```
void ArEarth_getCameraGeospatialPose(
  const ArSession *session,
  const ArEarth *earth,
  ArGeospatialPose *out_camera_geospatial_pose
)
```
Returns the Earth-relative camera pose for the latest frame.

The orientation of the obtained `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose` approximates the direction the user is facing in the EUS coordinate system. The EUS coordinate system has X+ pointing east, Y+ pointing up, and Z+ pointing south.

Note: This pose is only valid when `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_gettrackingstate` is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`. Otherwise, the resulting `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose` will contain default values.


| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `earth` | The `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` object. | | `out_camera_geospatial_pose` | Pointer to a `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose` to receive the Geospatial pose. | |

### ArEarth_getEarthState

```
void ArEarth_getEarthState(
  const ArSession *session,
  const ArEarth *earth,
  ArEarthState *out_state
)
```
Gets the current `https://developers.google.com/ar/reference/c/group/ar-earth#arearthstate` of the `https://developers.google.com/ar/reference/c/group/ar-earth#arearth`.

This state is guaranteed not to change until `https://developers.google.com/ar/reference/c/group/ar-session#arsession_update` is called.


| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `earth` | The earth object. | | `out_state` | The current state of `https://developers.google.com/ar/reference/c/group/ar-earth#arearth`. | |

### ArEarth_getGeospatialPose

```
ArStatus ArEarth_getGeospatialPose(
  const ArSession *session,
  const ArEarth *earth,
  const ArPose *pose,
  ArGeospatialPose *out_geospatial_pose
)
```
Converts the provided `pose` to a `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose` with respect to the Earth.

The `out_geospatial_pose's` rotation quaternion is a rotation with respect to an East-Up-South coordinate frame. An identity quaternion will have the anchor oriented such that X+ points to the east, Y+ points up away from the center of the earth, and Z+ points to the south.

The heading value for a `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose` obtained by this function will be 0. See `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose_geteastupsouthquaternion` for an orientation in 3D space.


| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `earth` | The `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` handle. | | `pose` | The local pose to translate to an Earth pose. | | `out_geospatial_pose` | Pointer to a `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose` that receives the Geospatial pose. | |
| **Returns** | `https://developers.google.com/ar/reference/c/group/shared-types#ar_success`, or any of: - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_not_tracking` if the Earth's tracking state is not `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`. - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_invalid_argument` if any of the parameters are null. |

### ArEarth_getPose

```
ArStatus ArEarth_getPose(
  const ArSession *session,
  const ArEarth *earth,
  double latitude,
  double longitude,
  double altitude,
  const float *eus_quaternion_4,
  ArPose *out_pose
)
```
Converts the provided Earth specified horizontal position, altitude and rotation with respect to an east-up-south coordinate frame to a pose with respect to GL world coordinates.

Position near the north pole or south pole is not supported. If the latitude is within 0.1 degrees of the north pole or south pole (90 degrees or -90 degrees), this function will return `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_invalid_argument`.


| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `earth` | The `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` handle. | | `latitude` | The latitude of the anchor relative to the WGS84 ellipsoid. | | `longitude` | The longitude of the anchor relative to the WGS84 ellipsoid. | | `altitude` | The altitude of the anchor relative to the WGS84 ellipsoid, in meters. | | `eus_quaternion_4` | The rotation quaternion as {qx, qy, qx, qw}. | | `out_pose` | A pointer to `https://developers.google.com/ar/reference/c/group/ar-pose#arpose` of the local pose with the latest frame. | |
| **Returns** | `https://developers.google.com/ar/reference/c/group/shared-types#ar_success`, or any of: - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_not_tracking` if the Earth's tracking state is not `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`. - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_invalid_argument`, if any of the parameters are null or `latitude` is outside the allowable range. |

### ArEarth_resolveAnchorOnRooftopAsync

```
ArStatus ArEarth_resolveAnchorOnRooftopAsync(
  ArSession *session,
  ArEarth *earth,
  double latitude,
  double longitude,
  double altitude_above_rooftop,
  const float *eus_quaternion_4,
  void *context,
  ArResolveAnchorOnRooftopCallback callback,
  ArResolveAnchorOnRooftopFuture **out_future
)
```
Asynchronously creates an anchor at a specified horizontal position and altitude relative to the horizontal position's rooftop.

See the [Rooftop anchors developer guide](https://developers.google.com/ar/develop/geospatial/c/anchors#rooftop-anchors) for more information.

The specified `altitude_above_rooftop` is interpreted to be relative to the top of a building at the given horizontal location, rather than relative to the WGS84 ellipsoid. If there is no building at the given location, then the altitude is interpreted to be relative to the terrain instead. Specifying an altitude of 0 will position the anchor directly on the rooftop whereas specifying a positive altitude will position the anchor above the rooftop, against the direction of gravity.

This launches an asynchronous operation used to query the Google Cloud ARCore API. See `https://developers.google.com/ar/reference/c/group/ar-future#arfuture` for information on obtaining results and cancelling the operation.

You may resolve multiple anchors at a time, but a session cannot be tracking more than 100 Terrain and Rooftop anchors at time. Attempting to resolve more than 100 Terrain or Rooftop anchors will result in resolve calls returning status `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_resource_exhausted`.

Creating a Rooftop anchor requires an active `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` for which the `https://developers.google.com/ar/reference/c/group/ar-earth#arearthstate` is `https://developers.google.com/ar/reference/c/group/ar-earth#ar_earth_state_enabled` and `https://developers.google.com/ar/reference/c/group/shared-types#artrackingstate` is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`. If it is not, then this function returns `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_illegal_state`. This call also requires a working internet connection to communicate with the ARCore API on Google Cloud. ARCore will continue to retry if it is unable to establish a connection to the ARCore service.

Latitude and longitude are defined by the [WGS84 specification](https://en.wikipedia.org/wiki/World_Geodetic_System).

The rotation provided by `eus_quaternion_4` is a rotation with respect to an east-up-south coordinate frame. An identity rotation will have the anchor oriented such that X+ points to the east, Y+ points up away from the center of the earth, and Z+ points to the south.

To create an anchor that has the +Z axis pointing in the same direction as heading obtained from `https://developers.google.com/ar/reference/c/group/ar-geospatial-pose#argeospatialpose`, use the following formula:


```
{qx, qy, qz, qw} = {0, sin((pi - heading * M_PI / 180.0) / 2), 0, cos((pi -
heading * M_PI / 180.0) / 2)}}.
```

<br />


| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `earth` | The `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` handle. | | `latitude` | The latitude of the anchor relative to the WGS-84 ellipsoid. | | `longitude` | The longitude of the anchor relative to the WGS-84 ellipsoid. | | `altitude_above_rooftop` | The altitude of the anchor above the Earth's rooftop. | | `eus_quaternion_4` | The rotation quaternion as {qx, qy, qx, qw}. | | `context` | An optional void pointer passed when using a [callback](https://developers.google.com/ar/reference/c/group/ar-future-1future#using-a-callback-to-obtain-future-results). | | `callback` | A [callback function](https://developers.google.com/ar/reference/c/group/ar-future-1future#using-a-callback-to-obtain-future-results). | | `out_future` | An optional `https://developers.google.com/ar/reference/c/group/ar-future#arfuture` which can be [polled](https://developers.google.com/ar/reference/c/group/ar-future-1future#polling-a-future). | |
| **Returns** | `https://developers.google.com/ar/reference/c/group/shared-types#ar_success` or any of: - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_illegal_state` if `earth` is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_stopped` and `https://developers.google.com/ar/reference/c/group/ar-earth#arearthstate` is not AR_EARTH_STATE_ENABLED due to `https://developers.google.com/ar/reference/c/group/ar-config#ar_geospatial_mode_disabled` configured on the `https://developers.google.com/ar/reference/c/group/ar-session#arsession`. Reacquire `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` if geospatial mode was reenabled. - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_invalid_argument` if `latitude` is outside the allowable range, or if either `session`, `earth`, or `eus_quaternion_4` is `NULL`, or both `callback` and `out_future` are null. - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_resource_exhausted` if too many Rooftop and Terrain anchors are currently held. |

### ArEarth_resolveAnchorOnTerrainAsync

```
ArStatus ArEarth_resolveAnchorOnTerrainAsync(
  ArSession *session,
  ArEarth *earth,
  double latitude,
  double longitude,
  double altitude_above_terrain,
  const float *eus_quaternion_4,
  void *context,
  ArResolveAnchorOnTerrainCallback callback,
  ArResolveAnchorOnTerrainFuture **out_future
)
```
Asynchronously creates an anchor at a specified horizontal position and altitude relative to the horizontal position's terrain.

See the [Terrain anchors developer guide](https://developers.google.com/ar/develop/geospatial/c/anchors#terrain-anchors) for more information.

The specified altitude is interpreted to be relative to the Earth's terrain (or floor) at the specified latitude/longitude geodetic coordinates, rather than relative to the WGS-84 ellipsoid. Specifying an altitude of 0 will position the anchor directly on the terrain (or floor) whereas specifying a positive altitude will position the anchor above the terrain (or floor), against the direction of gravity.

This launches an asynchronous operation used to query the Google Cloud ARCore API. See `https://developers.google.com/ar/reference/c/group/ar-future#arfuture` for information on obtaining results and cancelling the operation.

You may resolve multiple anchors at a time, but a session cannot be tracking more than 100 Terrain and Rooftop anchors at time. Attempting to resolve more than 100 Terrain or Rooftop anchors will result in resolve calls returning status `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_resource_exhausted`.

Creating a terrain anchor requires an active `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` for which the `https://developers.google.com/ar/reference/c/group/ar-earth#arearthstate` is `https://developers.google.com/ar/reference/c/group/ar-earth#ar_earth_state_enabled` and `https://developers.google.com/ar/reference/c/group/shared-types#artrackingstate` is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`. If it is not, then this function returns `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_illegal_state`. This call also requires a working internet connection to communicate with the ARCore API on Google Cloud. ARCore will continue to retry if it is unable to establish a connection to the ARCore service.

Latitude and longitude are defined by the [WGS84 specification](https://en.wikipedia.org/wiki/World_Geodetic_System).

The rotation provided by `eus_quaternion_4` is a rotation with respect to an east-up-south coordinate frame. An identity rotation will have the anchor oriented such that X+ points to the east, Y+ points up away from the center of the earth, and Z+ points to the south.


| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `earth` | The `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` handle. | | `latitude` | The latitude of the anchor relative to the WGS-84 ellipsoid. | | `longitude` | The longitude of the anchor relative to the WGS-84 ellipsoid. | | `altitude_above_terrain` | The altitude of the anchor above the Earth's terrain (or floor). | | `eus_quaternion_4` | The rotation quaternion as {qx, qy, qx, qw}. | | `context` | An optional void pointer passed when using a [callback](https://developers.google.com/ar/reference/c/group/ar-future-1future#using-a-callback-to-obtain-future-results). | | `callback` | A [callback function](https://developers.google.com/ar/reference/c/group/ar-future-1future#using-a-callback-to-obtain-future-results). | | `out_future` | An optional `https://developers.google.com/ar/reference/c/group/ar-future#arfuture` which can be [polled](https://developers.google.com/ar/reference/c/group/ar-future-1future#polling-a-future). | |
| **Returns** | `https://developers.google.com/ar/reference/c/group/shared-types#ar_success` or any of: - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_illegal_state` if `https://developers.google.com/ar/reference/c/group/ar-earth#arearthstate` is not `https://developers.google.com/ar/reference/c/group/ar-earth#ar_earth_state_enabled`. - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_invalid_argument` if `latitude` is outside the allowable range, or if either `session`, `earth`, or `eus_quaternion_4` is `NULL`, or both `callback` and `out_future` are `NULL`. - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_resource_exhausted` if too many anchors (counting both Terrain and Rooftop anchors) are currently held or are being resolved. |

### ArEarth_resolveAndAcquireNewAnchorOnTerrain

```
ArStatus ArEarth_resolveAndAcquireNewAnchorOnTerrain(
  ArSession *session,
  ArEarth *earth,
  double latitude,
  double longitude,
  double altitude_above_terrain,
  const float *eus_quaternion_4,
  ArAnchor **out_anchor
)
```
Creates an anchor at a specified horizontal position and altitude relative to the horizontal position's terrain.

Terrain means the ground, or ground floor inside a building with VPS coverage. For areas not covered by VPS, consider using `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_acquirenewanchor` to attach anchors to Earth.

The specified altitude is interpreted to be relative to the Earth's terrain (or floor) at the specified latitude/longitude geodetic coordinates, rather than relative to the WGS-84 ellipsoid. Specifying an altitude of 0 will position the anchor directly on the terrain (or floor) whereas specifying a positive altitude will position the anchor above the terrain (or floor), against the direction of gravity.

This creates a new `https://developers.google.com/ar/reference/c/group/ar-anchor#aranchor` and schedules a task to resolve the anchor's pose using the given parameters. You may resolve multiple anchors at a time, but a session cannot be tracking more than 100 Terrain anchors at time. Attempting to resolve more than 100 Terrain anchors will result in resolve calls returning status `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_resource_exhausted`.

If this function returns `https://developers.google.com/ar/reference/c/group/shared-types#ar_success`, the terrain anchor state of `out_terrain_anchor` will be `https://developers.google.com/ar/reference/c/group/ar-anchor#ar_terrain_anchor_state_task_in_progress`, and its tracking state will be `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_paused`. This anchor remains in this state until its pose has been successfully resolved. If the resolving task results in an error, the tracking state will be set to `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_stopped`. If the return value is not `https://developers.google.com/ar/reference/c/group/shared-types#ar_success`, then `out_cloud_anchor` will be set to `NULL`.

Creating a terrain anchor requires an active `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` for which the `https://developers.google.com/ar/reference/c/group/ar-earth#arearthstate` is `https://developers.google.com/ar/reference/c/group/ar-earth#ar_earth_state_enabled` and `https://developers.google.com/ar/reference/c/group/shared-types#artrackingstate` is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`. If it is not, then this function returns `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_illegal_state`. This call also requires a working internet connection to communicate with the ARCore API on Google Cloud. ARCore will continue to retry if it is unable to establish a connection to the ARCore service.

Latitude and longitude are defined by the [WGS84 specification](https://en.wikipedia.org/wiki/World_Geodetic_System).

The rotation provided by `eus_quaternion_4` is a rotation with respect to an east-up-south coordinate frame. An identity rotation will have the anchor oriented such that X+ points to the east, Y+ points up away from the center of the earth, and Z+ points to the south.

**[Deprecated.](https://developers.google.com/ar/reference/c/deprecated/deprecated)** Use `https://developers.google.com/ar/reference/c/group/ar-earth#arearth_resolveanchoronterrainasync` instead.

| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `earth` | The `https://developers.google.com/ar/reference/c/group/ar-earth#arearth` handle. | | `latitude` | The latitude of the anchor relative to the WGS-84 ellipsoid. | | `longitude` | The longitude of the anchor relative to the WGS-84 ellipsoid. | | `altitude_above_terrain` | The altitude of the anchor above the Earth's terrain (or floor). | | `eus_quaternion_4` | The rotation quaternion as {qx, qy, qx, qw}. | | `out_anchor` | The newly-created anchor. | |
| **Returns** | `https://developers.google.com/ar/reference/c/group/shared-types#ar_success` or any of: - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_illegal_state` if `https://developers.google.com/ar/reference/c/group/ar-earth#arearthstate` is not `https://developers.google.com/ar/reference/c/group/ar-earth#ar_earth_state_enabled`. - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_invalid_argument` if `latitude` is outside the allowable range, or if either `session`, `earth`, or `eus_quaternion_4` is `NULL`. - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_resource_exhausted` if too many terrain anchors are currently held. |