# ArTrackable

Something that can be tracked and that anchors can be attached to.

## Summary

| ### Enumerations ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackabletype{ https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_base_trackable = 0x41520100, https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_plane = 0x41520101, https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_point = 0x41520102, https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_augmented_image = 0x41520104, https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_face = 0x41520105, https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_streetscape_geometry = 0x41520103, https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_earth = 0x41520109, https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_depth_point = 0x41520111, https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_instant_placement_point = 0x41520112, https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_not_valid = 0 }` | enumObject types for heterogeneous query/update lists. |

| ### Typedefs ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable` | typedef `struct ArTrackable_` Trackable base type ([reference type, long-lived](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)). |
| `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackablelist` | typedef `struct ArTrackableList_` A list of `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable's` ([value type](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)). |

| ### Functions ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackablelist_acquireitem(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-trackable#artrackablelist *trackable_list, int32_t index, https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable **out_trackable)` | `void` Acquires a reference to an indexed entry in the list. |
| `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackablelist_create(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-trackable#artrackablelist **out_trackable_list)` | `void` Creates a trackable list object. |
| `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackablelist_destroy(https://developers.google.com/ar/reference/c/group/ar-trackable#artrackablelist *trackable_list)` | `void` Releases the memory used by a trackable list object, along with all the anchor references it holds. |
| `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackablelist_getsize(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-trackable#artrackablelist *trackable_list, int32_t *out_size)` | `void` Retrieves the number of trackables in this list. |
| `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_acquirenewanchor(https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable *trackable, https://developers.google.com/ar/reference/c/group/ar-pose#arpose *pose, 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 an Anchor at the given pose in the world coordinate space, attached to this Trackable, and acquires a reference to it. |
| `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_getanchors(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable *trackable, https://developers.google.com/ar/reference/c/group/ar-anchor#aranchorlist *out_anchor_list)` | `void` Gets the set of anchors attached to this trackable. |
| `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_gettrackingstate(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable *trackable, https://developers.google.com/ar/reference/c/group/shared-types#artrackingstate *out_tracking_state)` | `void` Retrieves the current state of ARCore's knowledge of the pose of this trackable. |
| `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_gettype(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable *trackable, https://developers.google.com/ar/reference/c/group/ar-trackable#artrackabletype *out_trackable_type)` | `void` Retrieves the type of the trackable. |
| `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_release(https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable *trackable)` | `void` Releases a reference to a trackable. |

## Enumerations

### ArTrackableType

```
 ArTrackableType
```
Object types for heterogeneous query/update lists.

| Properties ||
|---|---|
| `AR_TRACKABLE_AUGMENTED_IMAGE` | The `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage` subtype of Trackable. |
| `AR_TRACKABLE_BASE_TRACKABLE` | The base Trackable type. Can be passed to `https://developers.google.com/ar/reference/c/group/ar-session#arsession_getalltrackables` and `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_getupdatedtrackables` as the `filter_type` to get all/updated Trackables of all types. |
| `AR_TRACKABLE_DEPTH_POINT` | On supported devices, trackable type for depth image based hit results returned by `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_hittest` when `https://developers.google.com/ar/reference/c/group/ar-config#arconfig_setdepthmode` has been set to `https://developers.google.com/ar/reference/c/group/ar-config#ar_depth_mode_automatic`. |
| `AR_TRACKABLE_EARTH` | Trackable type for `https://developers.google.com/ar/reference/c/group/ar-earth#arearth`. |
| `AR_TRACKABLE_FACE` | Trackable type for faces. |
| `AR_TRACKABLE_INSTANT_PLACEMENT_POINT` | Trackable type for results retrieved from `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_hittestinstantplacement`. This trackable type is only available when when `https://developers.google.com/ar/reference/c/group/ar-config#arconfig_setinstantplacementmode` is `https://developers.google.com/ar/reference/c/group/ar-instant-placement-point#ar_instant_placement_mode_local_y_up`. |
| `AR_TRACKABLE_NOT_VALID` | An invalid Trackable type. |
| `AR_TRACKABLE_PLANE` | The `https://developers.google.com/ar/reference/c/group/ar-plane#arplane` subtype of Trackable. |
| `AR_TRACKABLE_POINT` | The `https://developers.google.com/ar/reference/c/group/ar-point#arpoint` subtype of Trackable. |
| `AR_TRACKABLE_STREETSCAPE_GEOMETRY` | Trackable type for Streetscape Geometry. |

## Typedefs

### ArTrackable

```
struct ArTrackable_ ArTrackable
```
Trackable base type ([reference type, long-lived](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).

### ArTrackableList

```
struct ArTrackableList_ ArTrackableList
```
A list of `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable's` ([value type](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).


- Create with: `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackablelist_create`
- Release with: `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackablelist_destroy`

<br />

## Functions

### ArTrackableList_acquireItem

```
void ArTrackableList_acquireItem(
  const ArSession *session,
  const ArTrackableList *trackable_list,
  int32_t index,
  ArTrackable **out_trackable
)
```
Acquires a reference to an indexed entry in the list.

This call must eventually be matched with a call to `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_release`.

### ArTrackableList_create

```
void ArTrackableList_create(
  const ArSession *session,
  ArTrackableList **out_trackable_list
)
```
Creates a trackable list object.

### ArTrackableList_destroy

```
void ArTrackableList_destroy(
  ArTrackableList *trackable_list
)
```
Releases the memory used by a trackable list object, along with all the anchor references it holds.

### ArTrackableList_getSize

```
void ArTrackableList_getSize(
  const ArSession *session,
  const ArTrackableList *trackable_list,
  int32_t *out_size
)
```
Retrieves the number of trackables in this list.

### ArTrackable_acquireNewAnchor

```
ArStatus ArTrackable_acquireNewAnchor(
  ArSession *session,
  ArTrackable *trackable,
  ArPose *pose,
  https://developers.google.com/ar/reference/c/group/ar-anchor#aranchor **out_anchor
)
```
Creates an Anchor at the given pose in the world coordinate space, attached to this Trackable, and acquires a reference to it.

The type of Trackable will determine the semantics of attachment and how the Anchor's pose will be updated to maintain this relationship. Note that the relative offset between the pose of multiple Anchors attached to a Trackable may adjust slightly over time as ARCore updates its model of the world.


| Details ||
|---|---|
| **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 trackable's tracking state was 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_session_paused` if the session was paused - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_resource_exhausted` if too many anchors exist - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_illegal_state` if this trackable doesn't support anchors |

### ArTrackable_getAnchors

```
void ArTrackable_getAnchors(
  const ArSession *session,
  const ArTrackable *trackable,
  ArAnchorList *out_anchor_list
)
```
Gets the set of anchors attached to this trackable.


Details Parameters `session` The ARCore session `trackable` The trackable to query the anchors of. `out_anchor_list` The list to fill. This list must have already been allocated with `https://developers.google.com/ar/reference/c/group/ar-anchor#aranchorlist_create`. If previously used, the list will first be cleared.

### ArTrackable_getTrackingState

```
void ArTrackable_getTrackingState(
  const ArSession *session,
  const ArTrackable *trackable,
  ArTrackingState *out_tracking_state
)
```
Retrieves the current state of ARCore's knowledge of the pose of this trackable.

Note: Starting in ARCore 1.12, changing the active camera config using `https://developers.google.com/ar/reference/c/group/ar-session#arsession_setcameraconfig` may cause the tracking state on certain devices to become permanently `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_paused`. For consistent behavior across all supported devices, release any previously created trackables when setting a new camera config.

### ArTrackable_getType

```
void ArTrackable_getType(
  const ArSession *session,
  const ArTrackable *trackable,
  ArTrackableType *out_trackable_type
)
```
Retrieves the type of the trackable.

See `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackabletype` for valid types.

### ArTrackable_release

```
void ArTrackable_release(
  ArTrackable *trackable
)
```
Releases a reference to a trackable.

This does not mean that the trackable will necessarily stop tracking. The same trackable may still be included in from other calls, for example `https://developers.google.com/ar/reference/c/group/ar-session#arsession_getalltrackables`.

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