Concepts

High-Level ARCore concepts.

Object ownership

ARCore objects fall into two categories:

  • Value types are owned by application. They are created and destroyed using the create / destroy functions, and are populated by ARCore using functions with get in the function name.
  • Reference types are owned by ARCore. A reference is acquired by one of the acquire functions. For each call to the acquire function, the application must call the matching release function. Note that even if the last reference is released, ARCore may continue to hold a reference to the object at ARCore's discretion.

Reference types are further split into:

  • Long-lived objects. These objects persist across frames, possibly for the life span of the application or session. Acquire may fail if ARCore is in an incorrect state, e.g. not tracking. Acquire from list always succeeds, as the object already exists.
  • Transient large data. These objects are usually acquired per-frame and are a limited resource. The acquire call may fail if the resource is exhausted (too many are currently held), deadline exceeded (the target of the acquire was already released), or the resource is not yet available.

Note: Lists are value types (owned by application), but can hold references to long-lived objects. This means that the references held by a list are not released until either the list is destroyed, or is re-populated by another api call.

For example, ArAnchorList, which is a value type, will hold references to anchors, which are long-lived objects.

Poses and coordinate spaces

An ArPose describes an rigid transformation from one coordinate space to another. As provided from all ARCore APIs, poses always describe the transformation from object's local coordinate space to the world coordinate space (see below). That is, poses from ARCore APIs can be thought of as equivalent to OpenGL model matrices.

The transformation is defined using a quaternion rotation about the origin followed by a translation.

The coordinate system is right-handed, like OpenGL conventions.

Translation units are meters.

World coordinate space

As ARCore's understanding of the environment changes, it adjusts its model of the world to keep things consistent. When this happens, the numerical location (coordinates) of the camera and anchors can change significantly to maintain appropriate relative positions of the physical locations they represent.

These changes mean that every frame should be considered to be in a completely unique world coordinate space. The numerical coordinates of anchors and the camera should never be used outside the rendering frame during which they were retrieved. If a position needs to be considered beyond the scope of a single rendering frame, either an anchor should be created or a position relative to a nearby existing anchor should be used.

Summary