**Name String**

`XR_ANDROID_trackables`

**Extension Type**

Instance extension

**Registered Extension Number**

456

**Revision**

1

**Extension and Version Dependencies**

[OpenXR 1.0](https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#versions-1.0)

**Last Modified Date**

2024-09-30

**IP Status**

No known IP claims.

**Contributors**

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

## Overview

This extension allows the application to access trackables from the physical environment, and create anchors attached to a trackable.

This extension defines plane trackables. Other extensions**may** add additional trackable types. For example`XR_ANDROID_trackables_object`adds object trackables, and[`XR_ANDROID_depth_texture`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_depth_texture)adds depth buffers that allow raycasting to arbitrary points in the environment.

A trackable is something that is tracked in the physical environment (see[XrTrackableTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTypeANDROID)):

- a plane (e.g. wall, floor, ceiling, table)
- an object (e.g. keyboard, mouse, laptop)

| **Caution:**   
|
| **Permissions**   
|
| Android applications**must** have the`android.permission.SCENE_UNDERSTANDING_COARSE`permission listed in their manifest as this extension exposes the geometry of the environment. The`android.permission.SCENE_UNDERSTANDING_COARSE`permission is considered a dangerous permission. The application**must** request the permission at runtime to use these functions:  
| `xrCreateTrackableTrackerANDROID`  
| (protection level: dangerous)

## Create a trackable tracker

An[XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID)is a handle that represents the resources required to discover and update trackables of a given[XrTrackableTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTypeANDROID)in the environment.  

    XR_DEFINE_HANDLE(XrTrackableTrackerANDROID)

The[xrCreateTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrCreateTrackableTrackerANDROID)function is defined as:  

    XrResult xrCreateTrackableTrackerANDROID(
        XrSession                                   session,
        const XrTrackableTrackerCreateInfoANDROID*  createInfo,
        XrTrackableTrackerANDROID*                  trackableTracker);

### Parameter Descriptions

- `session`is the[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)that creates the tracker.
- `createInfo`is a pointer to an[XrTrackableTrackerCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerCreateInfoANDROID)structure containing parameters to be used to create the tracker.
- `trackableTracker`is a pointer to a handle in which the created[XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID)is returned.

The application**can** use the[xrCreateTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrCreateTrackableTrackerANDROID)function to create a trackable tracker.

- `XR_ERROR_FEATURE_UNSUPPORTED`will be returned if the system does not support trackables of the specified type.
- `XR_ERROR_PERMISSION_INSUFFICIENT`will be returned if the required permissions have not been granted to the calling app.

The application**can** use the returned tracker handle in subsequent API calls. The[XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID)handle**must** be eventually freed using the[xrDestroyTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrDestroyTrackableTrackerANDROID)function.

### Valid Usage (Implicit)

- The[`XR_ANDROID_trackables`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XR_ANDROID_trackables)extension**must** be enabled prior to calling[xrCreateTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrCreateTrackableTrackerANDROID)
- `session`**must** be a valid[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)handle
- `createInfo`**must** be a pointer to a valid[XrTrackableTrackerCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerCreateInfoANDROID)structure
- `trackableTracker`**must** be a pointer to an[XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID)handle

### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`
- `XR_SESSION_LOSS_PENDING`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `XR_ERROR_FUNCTION_UNSUPPORTED`
- `XR_ERROR_VALIDATION_FAILURE`
- `XR_ERROR_RUNTIME_FAILURE`
- `XR_ERROR_HANDLE_INVALID`
- `XR_ERROR_INSTANCE_LOST`
- `XR_ERROR_SESSION_LOST`
- `XR_ERROR_OUT_OF_MEMORY`
- `XR_ERROR_LIMIT_REACHED`
- `XR_ERROR_FEATURE_UNSUPPORTED`

The[XrTrackableTrackerCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerCreateInfoANDROID)structure is defined as:  

    typedef struct XrTrackableTrackerCreateInfoANDROID {
        XrStructureType           type;
        void*                     next;
        XrTrackableTypeANDROID    trackableType;
    } XrTrackableTrackerCreateInfoANDROID;

### Member Descriptions

- `type`is the[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)of this structure.
- `next`is`NULL`or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
- `trackableType`is the[XrTrackableTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTypeANDROID)that the tracker will track.

The[XrTrackableTrackerCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerCreateInfoANDROID)structure provides creation options for the[XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID)when passed to[xrCreateTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrCreateTrackableTrackerANDROID).

Extensions**may** define structures that can be attached to`next`to allow additional configuration for the trackable trackers.

### Valid Usage (Implicit)

- The[`XR_ANDROID_trackables`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XR_ANDROID_trackables)extension**must** be enabled prior to using[XrTrackableTrackerCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerCreateInfoANDROID)
- `type`**must** be`XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID`
- `next`**must** be`NULL`or a valid pointer to the[next structure in a structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains). See also: XrTrackableObjectConfigurationANDROID
- `trackableType`**must** be a valid[XrTrackableTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTypeANDROID)value

The[XrTrackableTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTypeANDROID)enum is defined as:  

    typedef enum XrTrackableTypeANDROID {
        XR_TRACKABLE_TYPE_NOT_VALID_ANDROID = 0,
        XR_TRACKABLE_TYPE_PLANE_ANDROID = 1,
        XR_TRACKABLE_TYPE_DEPTH_ANDROID = 1000463000,
        XR_TRACKABLE_TYPE_OBJECT_ANDROID = 1000466000
    } XrTrackableTypeANDROID;

The[xrDestroyTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrDestroyTrackableTrackerANDROID)function is defined as:  

    XrResult xrDestroyTrackableTrackerANDROID(
        XrTrackableTrackerANDROID                   trackableTracker);

### Parameter Descriptions

- `trackableTracker`is an[XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID)handle previously created by[xrCreateTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrCreateTrackableTrackerANDROID).

The[xrDestroyTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrDestroyTrackableTrackerANDROID)function destroys the trackable tracker.

If there is no other valid[XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID)that was created with the same[XrTrackableTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTypeANDROID), the system**may**disable the tracking services required for that trackable type to save system resources.

### Valid Usage (Implicit)

- The[`XR_ANDROID_trackables`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XR_ANDROID_trackables)extension**must** be enabled prior to calling[xrDestroyTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrDestroyTrackableTrackerANDROID)
- `trackableTracker`**must** be a valid[XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID)handle

### Thread Safety

- Access to`trackableTracker`, and any child handles,**must**be externally synchronized

### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `XR_ERROR_FUNCTION_UNSUPPORTED`
- `XR_ERROR_HANDLE_INVALID`

## Get all trackables

The[`XrTrackableANDROID`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableANDROID)atom is defined as:  

    XR_DEFINE_ATOM(XrTrackableANDROID)

[`XrTrackableANDROID`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableANDROID)is used to represent a single trackable and is valid only within the lifecycle of its associated[XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID).

The[xrGetAllTrackablesANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrGetAllTrackablesANDROID)function is defined as:  

    XrResult xrGetAllTrackablesANDROID(
        XrTrackableTrackerANDROID                   trackableTracker,
        uint32_t                                    trackableCapacityInput,
        uint32_t*                                   trackableCountOutput,
        XrTrackableANDROID*                         trackables);

### Parameter Descriptions

- `trackableTracker`is the[XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID)to query.

- `trackableCapacityInput`is the capacity of the`trackables`array, or 0 to indicate a request to retrieve the required capacity.

- `trackableCountOutput`is a pointer to the count of`trackables`written, or a pointer to the required capacity in the case that`trackables`is insufficient.

- `trackables`is a pointer to an array of[`XrTrackableANDROID`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableANDROID). It**can** be`NULL`if`trackableCapacityInput`is 0.

- See the[Buffer Size Parameters](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-buffer-size-parameters)section for a detailed description of retrieving the required`trackables`size.

[xrGetAllTrackablesANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrGetAllTrackablesANDROID)fills an array of[`XrTrackableANDROID`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableANDROID)representing the trackables found in the environment. The[XrTrackableTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTypeANDROID)of the returned`trackables`**must** match the[XrTrackableTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTypeANDROID)of the`trackableTracker`.

## Get trackable plane

The[xrGetTrackablePlaneANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrGetTrackablePlaneANDROID)function is defined as:  

    XrResult xrGetTrackablePlaneANDROID(
        XrTrackableTrackerANDROID                   trackableTracker,
        const XrTrackableGetInfoANDROID*            getInfo,
        XrTrackablePlaneANDROID*                    planeOutput);

### Parameter Descriptions

- `trackableTracker`is the[XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID)to query.

- `getInfo`is the[XrTrackableGetInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableGetInfoANDROID)with the information used to get the trackable plane.

- `planeOutput`is a pointer to the[XrTrackablePlaneANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackablePlaneANDROID)structure in which the trackable plane is returned.

The[xrGetTrackablePlaneANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrGetTrackablePlaneANDROID)function returns details about the trackable plane, such as its geometry, orientation, and tracking state.

The plane information is resolved and relative to the base space at the time of the call to[xrGetTrackablePlaneANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrGetTrackablePlaneANDROID)using[XrTrackableGetInfoANDROID::time, XrTrackableGetInfoANDROID::baseSpace](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableGetInfoANDROID).

### Valid Usage (Implicit)

- The[`XR_ANDROID_trackables`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XR_ANDROID_trackables)extension**must** be enabled prior to calling[xrGetTrackablePlaneANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrGetTrackablePlaneANDROID)
- `trackableTracker`**must** be a valid[XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID)handle
- `getInfo`**must** be a pointer to a valid[XrTrackableGetInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableGetInfoANDROID)structure
- `planeOutput`**must** be a pointer to an[XrTrackablePlaneANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackablePlaneANDROID)structure

### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`
- `XR_SESSION_LOSS_PENDING`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `XR_ERROR_FUNCTION_UNSUPPORTED`
- `XR_ERROR_VALIDATION_FAILURE`
- `XR_ERROR_RUNTIME_FAILURE`
- `XR_ERROR_HANDLE_INVALID`
- `XR_ERROR_INSTANCE_LOST`
- `XR_ERROR_SESSION_LOST`
- `XR_ERROR_LIMIT_REACHED`
- `XR_ERROR_TIME_INVALID`

The[XrTrackableGetInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableGetInfoANDROID)structure is defined as:  

    typedef struct XrTrackableGetInfoANDROID {
        XrStructureType       type;
        void*                 next;
        XrTrackableANDROID    trackable;
        XrSpace               baseSpace;
        XrTime                time;
    } XrTrackableGetInfoANDROID;

### Member Descriptions

- `type`is the[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)of this structure.
- `next`is`NULL`or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
- `trackable`is the[`XrTrackableANDROID`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableANDROID)plane to query.
- `baseSpace`the plane pose will be relative to this[XrSpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSpace)at`time`.
- `time`is the[`XrTime`](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrTime)at which to evaluate the coordinates relative to the`baseSpace`.

The[XrTrackableGetInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableGetInfoANDROID)structure provides query options when passed to[xrGetTrackablePlaneANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrGetTrackablePlaneANDROID). The`trackable`**must** correspond to the`trackableTracker`used in[xrGetTrackablePlaneANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrGetTrackablePlaneANDROID).

`XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID`will be returned if the trackable type of the`trackable`is not`XR_TRACKABLE_TYPE_PLANE_ANDROID`.

### Valid Usage (Implicit)

- The[`XR_ANDROID_trackables`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XR_ANDROID_trackables)extension**must** be enabled prior to using[XrTrackableGetInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableGetInfoANDROID)
- `type`**must** be`XR_TYPE_TRACKABLE_GET_INFO_ANDROID`
- `next`**must** be`NULL`or a valid pointer to the[next structure in a structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)
- `baseSpace`**must** be a valid[XrSpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSpace)handle

The[XrTrackablePlaneANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackablePlaneANDROID)structure is defined as:  

    typedef struct XrTrackablePlaneANDROID {
        XrStructureType           type;
        void*                     next;
        XrTrackingStateANDROID    trackingState;
        XrPosef                   centerPose;
        XrExtent2Df               extents;
        XrPlaneTypeANDROID        planeType;
        XrPlaneLabelANDROID       planeLabel;
        XrTrackableANDROID        subsumedByPlane;
        XrTime                    lastUpdatedTime;
        uint32_t                  vertexCapacityInput;
        uint32_t*                 vertexCountOutput;
        XrVector2f*               vertices;
    } XrTrackablePlaneANDROID;

### Member Descriptions

- `type`is the[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)of this structure.
- `next`is`NULL`or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
- `trackingState`is the[XrTrackingStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackingStateANDROID)of the plane.
- `centerPose`is an[XrPosef](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrPosef)defining the position and orientation of the plane within the reference frame of the corresponding[XrTrackableGetInfoANDROID::baseSpace](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableGetInfoANDROID). An identity orientation here represents a coordinate axes with +Y parallel to the plane's normal.
- `extents`is the[XrExtent2Df](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrExtent2Df)dimension of the plane.
- `planeType`is the[XrPlaneTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrPlaneTypeANDROID)that the runtime has determined for this plane.
- `planeLabel`is the[XrPlaneLabelANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrPlaneLabelANDROID)that the runtime has determined for this plane.
- `subsumedByPlane`is the[`XrTrackableANDROID`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableANDROID)of the plane that subsumes this plane (`XR_NULL_TRACKABLE_ANDROID`if none exists).
- `lastUpdatedTime`is the[`XrTime`](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrTime)of the last update of the plane.
- `vertexCapacityInput`is the capacity of the`vertices`array, or 0 to indicate a request to retrieve the required capacity.
- `vertexCountOutput`is a pointer to the count of`vertices`written, or a pointer to the required capacity in the case that`vertices`is insufficient.
- `vertices`is a pointer to an array of[XrVector2f](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrVector2f). It**can** be`NULL`if`vertexCapacityInput`is 0. The vertices are in counter-clockwise order. The polygon**may** be concave and**must**not be self-intersecting.
- See the[Buffer Size Parameters](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-buffer-size-parameters)section for a detailed description of retrieving the required`vertices`size.

### Valid Usage (Implicit)

- The[`XR_ANDROID_trackables`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XR_ANDROID_trackables)extension**must** be enabled prior to using[XrTrackablePlaneANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackablePlaneANDROID)
- `type`**must** be`XR_TYPE_TRACKABLE_PLANE_ANDROID`
- `next`**must** be`NULL`or a valid pointer to the[next structure in a structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)
- `trackingState`**must** be a valid[XrTrackingStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackingStateANDROID)value
- `planeType`**must** be a valid[XrPlaneTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrPlaneTypeANDROID)value
- `planeLabel`**must** be a valid[XrPlaneLabelANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrPlaneLabelANDROID)value
- `vertexCountOutput`**must** be a pointer to a`uint32_t`value
- `vertices`**must** be a pointer to an array of`vertexCapacityInput`[XrVector2f](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrVector2f)structures
- The`vertexCapacityInput`parameter**must** be greater than`0`

The[XrTrackingStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackingStateANDROID)enum describes the tracking state of an[`XrTrackableANDROID`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableANDROID).  

    typedef enum XrTrackingStateANDROID {
        XR_TRACKING_STATE_PAUSED_ANDROID = 0,
        XR_TRACKING_STATE_STOPPED_ANDROID = 1,
        XR_TRACKING_STATE_TRACKING_ANDROID = 2
    } XrTrackingStateANDROID;

|---------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| [**XrTrackingStateANDROID**](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackingStateANDROID) | **Description**                                                                             |
| `XR_TRACKING_STATE_PAUSED_ANDROID`                                                                                                    | Indicates that the trackable or anchor tracking is paused but may be resumed in the future. |
| `XR_TRACKING_STATE_STOPPED_ANDROID`                                                                                                   | Tracking has stopped on this Trackable and will never be resumed.                           |
| `XR_TRACKING_STATE_TRACKING_ANDROID`                                                                                                  | The object is tracked and its pose is current.                                              |

The[XrPlaneTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrPlaneTypeANDROID)enum is the type of an[`XrTrackableANDROID`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableANDROID)plane.  

    typedef enum XrPlaneTypeANDROID {
        XR_PLANE_TYPE_HORIZONTAL_DOWNWARD_FACING_ANDROID = 0,
        XR_PLANE_TYPE_HORIZONTAL_UPWARD_FACING_ANDROID = 1,
        XR_PLANE_TYPE_VERTICAL_ANDROID = 2,
        XR_PLANE_TYPE_ARBITRARY_ANDROID = 3
    } XrPlaneTypeANDROID;

The[XrPlaneLabelANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrPlaneLabelANDROID)enum is a label for a[`XrTrackableANDROID`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableANDROID)plane.  

    typedef enum XrPlaneLabelANDROID {
        XR_PLANE_LABEL_UNKNOWN_ANDROID = 0,
        XR_PLANE_LABEL_WALL_ANDROID = 1,
        XR_PLANE_LABEL_FLOOR_ANDROID = 2,
        XR_PLANE_LABEL_CEILING_ANDROID = 3,
        XR_PLANE_LABEL_TABLE_ANDROID = 4
    } XrPlaneLabelANDROID;

## Create anchor space

    XrResult xrCreateAnchorSpaceANDROID(
        XrSession                                   session,
        const XrAnchorSpaceCreateInfoANDROID*       createInfo,
        XrSpace*                                    anchorOutput);

### Parameter Descriptions

- `session`is the[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)that creates the anchor space.
- `createInfo`is a pointer to an[XrAnchorSpaceCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrAnchorSpaceCreateInfoANDROID)structure containing parameters to be used to create the anchor space.
- `anchorOutput`is a pointer to a handle in which the created[XrSpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSpace)is returned.

At any point of time both the position and direction of the anchor is tracked or untracked. This means that both`XR_SPACE_LOCATION_POSITION_TRACKED_BIT`and`XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT`must be set or both must be cleared when the application calls[xrLocateSpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrLocateSpace)or[xrLocateSpaces](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrLocateSpaces)for`anchorOutput`.

The application**must** eventually free the returned[XrSpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSpace)using[xrDestroySpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrDestroySpace).

- `XR_ERROR_FEATURE_UNSUPPORTED`must be returned if the system does not support anchors.
- `XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID`must be returned if the specific anchor attachment is not supported.

### Valid Usage (Implicit)

- The[`XR_ANDROID_trackables`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XR_ANDROID_trackables)extension**must** be enabled prior to calling[xrCreateAnchorSpaceANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrCreateAnchorSpaceANDROID)
- `session`**must** be a valid[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)handle
- `createInfo`**must** be a pointer to a valid[XrAnchorSpaceCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrAnchorSpaceCreateInfoANDROID)structure
- `anchorOutput`**must** be a pointer to an[XrSpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSpace)handle

### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`
- `XR_SESSION_LOSS_PENDING`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `XR_ERROR_FUNCTION_UNSUPPORTED`
- `XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID`
- `XR_ERROR_VALIDATION_FAILURE`
- `XR_ERROR_RUNTIME_FAILURE`
- `XR_ERROR_HANDLE_INVALID`
- `XR_ERROR_INSTANCE_LOST`
- `XR_ERROR_SESSION_LOST`
- `XR_ERROR_LIMIT_REACHED`
- `XR_ERROR_POSE_INVALID`
- `XR_ERROR_TIME_INVALID`
- `XR_ERROR_OUT_OF_MEMORY`

The[XrAnchorSpaceCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrAnchorSpaceCreateInfoANDROID)structure is defined as:  

    typedef struct XrAnchorSpaceCreateInfoANDROID {
        XrStructureType       type;
        void*                 next;
        XrSpace               space;
        XrTime                time;
        XrPosef               pose;
        XrTrackableANDROID    trackable;
    } XrAnchorSpaceCreateInfoANDROID;

### Member Descriptions

- `type`is the[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)of this structure.
- `next`is`NULL`or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
- `space`is the[XrSpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSpace)on which the anchor will be created.
- `time`is the[`XrTime`](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrTime)of the anchor creation.
- `pose`is the[XrPosef](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrPosef)of the anchor.
- `trackable`is the[`XrTrackableANDROID`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableANDROID)on which the anchor will be attached. It**may** be`XR_NULL_TRACKABLE_ANDROID`to create an spatial anchor.

### Valid Usage (Implicit)

- The[`XR_ANDROID_trackables`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XR_ANDROID_trackables)extension**must** be enabled prior to using[XrAnchorSpaceCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrAnchorSpaceCreateInfoANDROID)
- `type`**must** be`XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID`
- `next`**must** be`NULL`or a valid pointer to the[next structure in a structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)
- `space`**must** be a valid[XrSpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSpace)handle

## Example code for getting all trackables

The following example code demonstrates how to get all trackables of a given type.  

    XrSession session; // previously initialized

    // The function pointers are previously initialized using xrGetInstanceProcAddr.
    PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // previously initialized
    PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // previously initialized
    PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized

    XrTrackableTrackerCreateInfoANDROID createInfo{XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID};
    createInfo.trackableType = XR_TRACKABLE_TYPE_PLANE_ANDROID;
    XrTrackableTrackerANDROID planeTrackableTracker;
    XrResult result = xrCreateTrackableTrackerANDROID(
      session,
      &createInfo,
      &planeTrackableTracker);
    if (result != XR_SUCCESS) { /* Handle failures. */ }

    uint32_t trackableCountOutput = 0;
    std::vector<XrTrackableANDROID> allPlaneTrackables;

    // Query the number of trackables available.
    result = xrGetAllTrackablesANDROID(
      planeTrackableTracker,
      0,
      &trackableCountOutput,
      nullptr
    );

    if (result == XR_SUCCESS) {
      allPlaneTrackables.resize(trackableCountOutput, XR_NULL_HANDLE);

      // Fetch the actual trackable handles in the appropriately resized array.
      result = xrGetAllTrackablesANDROID(
        planeTrackableTracker,
        trackableCountOutput,
        &trackableCountOutput,
        allPlaneTrackables.data());

      if (result == XR_SUCCESS) {
        for (XrTrackableANDROID trackable : allPlaneTrackables) {
          // You now have all trackables of the specified type.
        }
      }
    }

    // Release trackable tracker.
    result = xrDestroyTrackableTrackerANDROID(planeTrackableTracker);

## Example code for getting trackable plane

The following example code demonstrates how to get a trackable plane from an existing[`XrTrackableANDROID`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableANDROID), obtained from a hit result[`XR_ANDROID_raycast`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_raycast)or`xrGetTrackablesANDROID`.  

    XrTrackableTrackerANDROID planeTracker; // previously created

    // The function pointers are previously initialized using xrGetInstanceProcAddr.
    PFN_xrGetTrackablePlaneANDROID xrGetTrackablePlaneANDROID; // previously initialized

    XrTime updateTime; // Time used for the current frame's simulation update.
    XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
    XrTrackableANDROID planeTrackable; // Acquired from a hit result or getTrackables().

    XrTrackableGetInfoANDROID planeGetInfo;
    planeGetInfo.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID;
    planeGetInfo.next = nullptr;
    planeGetInfo.trackable = planeTrackable;
    planeGetInfo.space = appSpace;
    planeGetInfo.time = updateTime;

    XrTrackablePlaneANDROID plane = { XR_TYPE_TRACKABLE_PLANE_ANDROID };
    result = xrGetTrackablePlaneANDROID(
      planeTracker,
      &planeGetInfo,
      &plane
    );

    if (result == XR_SUCCESS) {
      // Plane tracking state, center pose, extents, type now available in plane.
    }

## Example code for creating anchor space

The following example code demonstrates how to create an anchor space attached to a trackable.  

    XrSession session; // Created at app startup.
    XrTime updateTime; // Time used for the current frame's simulation update.
    XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
    XrTrackableANDROID planeTrackable; // Acquired from a hit result or getTrackables().

    // Create an anchor at (2, 2, 2) world-coordinates.
    XrAnchorSpaceCreateInfoANDROID spatialAnchorCreateInfo;
    spatialAnchorCreateInfo.type = XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID;
    spatialAnchorCreateInfo.next = nullptr;
    spatialAnchorCreateInfo.space = appSpace;
    spatialAnchorCreateInfo.time = updateTime;
    spatialAnchorCreateInfo.pose = { { 0, 0, 0, 1 }, { 2, 2, 2 } };

    XrSpace spatialAnchor = XR_NULL_HANDLE;
    XrResult result = xrCreateAnchorSpaceANDROID(
      session,
      &spatialAnchorCreateInfo,
      &spatialAnchor
    );

    // Create an anchor attached to a trackable.
    XrTrackablePlane plane = ...;
    XrAnchorSpaceCreateInfoANDROID trackableAnchorCreateInfo;
    trackableAnchorCreateInfo.type = XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID;
    trackableAnchorCreateInfo.next = nullptr;
    trackableAnchorCreateInfo.space = appState;
    trackableAnchorCreateInfo.pose = plane.centerPose;
    trackableAnchorCreateInfo.trackable = planeTrackable;

    XrSpace trackableAnchor = XR_NULL_HANDLE;
    XrResult result = xrCreateAnchorSpaceANDROID(
      session,
      &trackableAnchorCreateInfo,
      &trackableAnchor
    );
    while (true) {
      // app update loop
      // ...

      // Get the current location of the anchor's space w.r.t the world.
      XrSpaceLocation anchorLocation = { XR_TYPE_SPACE_LOCATION };
      result = xrLocateSpace(trackableAnchor, appSpace, updateTime, &anchorLocation);

      if (anchor.trackingState == XR_TRACKING_STATE_TRACKING_ANDROID) {
        // Update anchor pose.
        doDrawingForAnchor(anchorLocation.pose);
      } else {
        // ...
      }
    }

    // Cleanup - destroy the space, detatch the anchor so its no longer tracked by the
    // runtime and then release all resources held by it.
    xrDestroySpace(spatialAnchor);
    xrDestroySpace(trackableAnchor);

**New Base Types**

- [`XrTrackableANDROID`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableANDROID)

**New Object Types**

- [XrTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerANDROID)

**New Enum Constants**

[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)enumeration is extended with:

- `XR_TYPE_TRACKABLE_GET_INFO_ANDROID`
- `XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID`
- `XR_TYPE_TRACKABLE_PLANE_ANDROID`
- `XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID`

[XrObjectType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrObjectType)enumeration is extended with:

- `XR_OBJECT_TYPE_TRACKABLE_TRACKER_ANDROID`

[XrResult](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrResult)enumeration is extended with:

- `XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID`
- `XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID`

**New Enums**

- [XrTrackingStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackingStateANDROID)
- [XrTrackableTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTypeANDROID)
- [XrPlaneTypeANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrPlaneTypeANDROID)
- [XrPlaneLabelANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrPlaneLabelANDROID)

**New Structures**

- [XrTrackableTrackerCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableTrackerCreateInfoANDROID)
- [XrTrackableGetInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackableGetInfoANDROID)
- [XrTrackablePlaneANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrTrackablePlaneANDROID)
- [XrAnchorSpaceCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#XrAnchorSpaceCreateInfoANDROID)

**New Functions**

- [xrCreateTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrCreateTrackableTrackerANDROID)
- [xrDestroyTrackableTrackerANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrDestroyTrackableTrackerANDROID)
- [xrGetAllTrackablesANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrGetAllTrackablesANDROID)
- [xrGetTrackablePlaneANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrGetTrackablePlaneANDROID)
- [xrCreateAnchorSpaceANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_trackables#xrCreateAnchorSpaceANDROID)

**Issues**

**Version History**

- Revision 1, 2024-09-27 (Kenny Vercaemer)
  - Initial extension description.

*** ** * ** ***

OpenXR™ and the OpenXR logo are trademarks owned by The Khronos Group Inc. and are registered as a trademark in China, the European Union, Japan and the United Kingdom.