XR_ANDROID_device_anchor_persistence OpenXR extension

Name String

XR_ANDROID_device_anchor_persistence

Extension Type

Instance extension

Registered Extension Number

458

Revision

1

Extension and Version Dependencies

XR_EXT_uuid and XR_ANDROID_trackables

Last Modified Date

2024-10-10

IP Status

No known IP claims.

Contributors

Nihav Jain, Google

Levana Chen, Google

Spencer Quin, Google

Kenny Vercaemer, Google

Overview

This extension allows the application to persist, retrieve, and unpersist anchors on the current device for the current user, across applications and device sessions.

Inspect system capability

The XrSystemDeviceAnchorPersistencePropertiesANDROID structure is defined as:

typedef struct XrSystemDeviceAnchorPersistencePropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAnchorPersistence;
} XrSystemDeviceAnchorPersistencePropertiesANDROID;

Member Descriptions

  • type is the 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.
  • supportsAnchorPersistence is an XrBool32 indicating if the current system supports anchor persistence for spatial anchors.

An application can inspect whether the system is capable of persisting spatial anchors (see xrCreateAnchorSpaceANDROID) by extending the XrSystemProperties with XrSystemDeviceAnchorPersistencePropertiesANDROID structure when calling xrGetSystemProperties. For the supported trackable anchors, an application can use xrEnumerateSupportedPersistenceAnchorTypesANDROID to query the supported types.

If XR_FALSE is returned for supportsAnchorPersistence, then XR_ERROR_FEATURE_UNSUPPORTED will be returned from device anchor persistence functions that operate on a spatial anchor.

Valid Usage (Implicit)

The xrEnumerateSupportedPersistenceAnchorTypesANDROID function is defined as: 

XrResult xrEnumerateSupportedPersistenceAnchorTypesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    trackableTypeCapacityInput,
    uint32_t*                                   trackableTypeCountOutput,
    XrTrackableTypeANDROID*                     trackableTypes);

Parameter Descriptions

  • session is the XrSession that creates the XrDeviceAnchorPersistenceANDROID.
  • trackableTypeCapacityInput is the capacity of the trackableTypes, or 0 to retrieve the required capacity.
  • trackableTypeCountOutput is a pointer to the count of the array, or a pointer to the required capacity in the case that trackableTypeCapacityInput is insufficient.
  • trackableTypes is a pointer to an array of XrTrackableTypeANDROID, but can be NULL if trackableTypeCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required trackableTypes size.

The application can use xrEnumerateSupportedPersistenceAnchorTypesANDROID to check for support of anchor persistence on other XrTrackableTypeANDROID trackables.

If a given XrTrackableTypeANDROID is not returned in the trackableTypes array, then XR_ERROR_FEATURE_UNSUPPORTED will be returned from device anchor persistence functions that operate on an anchor of that type.

Valid Usage (Implicit)

Return Codes

Success

  • XR_SUCCESS

Failure

  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_FUNCTION_UNSUPPORTED

Create a device anchor persistence handle

An XrDeviceAnchorPersistenceANDROID is a handle that represents the resources required to persist and keep track of persisted anchors. 

XR_DEFINE_HANDLE(XrDeviceAnchorPersistenceANDROID)

The xrCreateDeviceAnchorPersistenceANDROID function is defined as: 

XrResult xrCreateDeviceAnchorPersistenceANDROID(
    XrSession                                   session,
    const XrDeviceAnchorPersistenceCreateInfoANDROID* createInfo,
    XrDeviceAnchorPersistenceANDROID*           outHandle);

Parameter Descriptions

An application can create an XrDeviceAnchorPersistenceANDROID handle by calling xrCreateDeviceAnchorPersistenceANDROID. The XrDeviceAnchorPersistenceANDROID can be used in subsequent API calls to persist or unpersist anchors. The XrDeviceAnchorPersistenceANDROID handle must be eventually freed using the xrDestroyDeviceAnchorPersistenceANDROID function.

Valid Usage (Implicit)

Return Codes

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • 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

The XrDeviceAnchorPersistenceCreateInfoANDROID structure is defined as: 

typedef struct XrDeviceAnchorPersistenceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrDeviceAnchorPersistenceCreateInfoANDROID;

Member Descriptions

  • type is the 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.

The XrDeviceAnchorPersistenceCreateInfoANDROID structure provides creation options for the XrDeviceAnchorPersistenceANDROID when passed to xrCreateDeviceAnchorPersistenceANDROID.

Valid Usage (Implicit)

The xrDestroyDeviceAnchorPersistenceANDROID function is defined as: 

XrResult xrDestroyDeviceAnchorPersistenceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle);

Parameter Descriptions

The xrDestroyDeviceAnchorPersistenceANDROID function destroys the device anchor persistence handle.

Valid Usage (Implicit)

Thread Safety

  • Access to handle, and any child handles, must be externally synchronized

Return Codes

Success

  • XR_SUCCESS

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Persist an anchor

The xrPersistAnchorANDROID function is defined as:

XrResult xrPersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceInfoANDROID*    persistedInfo,
    XrUuidEXT*                                  anchorIdOutput);

Parameter Descriptions

The application can request anchors to be persisted by calling xrPersistAnchorANDROID. The application must not assume a success return value means the anchor is immediately persisted. The application should use xrGetAnchorPersistStateANDROID to check the persist state of the anchor using the returned anchor XrUuidEXT. The application can use xrUnpersistAnchorANDROID to unpersist the anchor.

  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID will be returned if the anchor is not being tracked at the time of the call.
  • XR_SUCCESS will be returned once the anchor has been queued for persistence.

Valid Usage (Implicit)

Return Codes

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID
  • 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

The XrPersistedAnchorSpaceInfoANDROID structure is defined as: 

typedef struct XrPersistedAnchorSpaceInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            anchor;
} XrPersistedAnchorSpaceInfoANDROID;

Member Descriptions

  • type is the 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.
  • anchor is an anchor XrSpace previously created by xrCreateAnchorSpaceANDROID to persist.

Valid Usage (Implicit)

The xrGetAnchorPersistStateANDROID function is defined as: 

XrResult xrGetAnchorPersistStateANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId,
    XrAnchorPersistStateANDROID*                persistState);

Parameter Descriptions

  • handle is the XrDeviceAnchorPersistenceANDROID.
  • anchorId is the XrUuidEXT of the anchor.
  • persistState is a pointer to an XrAnchorPersistStateANDROID in which the state of the anchor is returned.
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID will be returned if the anchor XrUuidEXT is not found.
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID will be returned if the persisted data of anchorId is not ready.

Valid Usage (Implicit)

Return Codes

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • 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_ANCHOR_ID_NOT_FOUND_ANDROID

The XrAnchorPersistStateANDROID enum is defined as: 

typedef enum XrAnchorPersistStateANDROID {
    XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID = 0,
    XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID = 1,
    XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID = 2
} XrAnchorPersistStateANDROID;

Enum

Description

XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID

Anchor has not been requested to be persisted by the app.

XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID

Anchor has been requested to be persisted but not persisted yet.

XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID

Anchor has been successfully persisted by the runtime.

Create an anchor from persisted data

The xrCreatePersistedAnchorSpaceANDROID function is defined as: 

XrResult xrCreatePersistedAnchorSpaceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorOutput);

Parameter Descriptions

The application can create an XrSpace anchor from a previously persisted anchor by calling xrCreatePersistedAnchorSpaceANDROID with the same XrUuidEXT. This is another way of creating anchors as defined in XR_ANDROID_trackables.

  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID will be returned if the anchor XrUuidEXT is not found.

Valid Usage (Implicit)

Return Codes

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • 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_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

The XrPersistedAnchorSpaceCreateInfoANDROID structure is defined as: 

typedef struct XrPersistedAnchorSpaceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrUuidEXT          anchorId;
} XrPersistedAnchorSpaceCreateInfoANDROID;

Member Descriptions

  • type is the 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.
  • anchorId is the XrUuidEXT of the persisted anchor to create an anchor XrSpace from.

The XrPersistedAnchorSpaceCreateInfoANDROID structure provides creation options for the anchor when passed to xrCreateDeviceAnchorPersistenceANDROID.

Valid Usage (Implicit)

Enumerate persisted anchors

The xrEnumeratePersistedAnchorsANDROID function is defined as: 

XrResult xrEnumeratePersistedAnchorsANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    uint32_t                                    anchorIdsCapacityInput,
    uint32_t*                                   anchorIdsCountOutput,
    XrUuidEXT*                                  anchorIds);

Parameter Descriptions

  • handle is the XrDeviceAnchorPersistenceANDROID.
  • anchorIdsCapacityInput is the capacity of the anchorIds array, or 0 to indicate a request to retrieve the required capacity.
  • anchorIdsCountOutput is a pointer to the count of anchorIds written, or a pointer to the required capacity in the case that anchorIdsCapacityInput is insufficient.
  • anchorIds is a pointer to an array of XrUuidEXT structures. It can be NULL if anchorIdsCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required anchorIds size.

The application may enumerate all current persisted anchors by calling xrEnumeratePersistedAnchorsANDROID. anchorIds will hold the UUIDs of the persisted anchors up to the capacity of the array. If the capacity is insufficient, applications have no guarantees about which anchors are returned.

Valid Usage (Implicit)

Return Codes

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID
  • 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_SIZE_INSUFFICIENT

Unpersist a persisted anchor

The xrUnpersistAnchorANDROID function is defined as: 

XrResult xrUnpersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId);

Parameter Descriptions

The application may unpersist a persisted anchor by calling xrUnpersistAnchorANDROID and passing the anchor XrUuidEXT of the anchor to unpersist.

  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID will be returned if the persisted data is not ready.
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID will be returned if the anchor XrUuidEXT is not found.

Valid Usage (Implicit)

Return Codes

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • 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_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

Example code for anchor persistence

The following example code demonstrates how to inspect system capability, persist, enumerate and unpersist anchors, as well as creating an anchor from persisted anchor XrUuidEXT.

XrSession session; // previously initialized
XrSpace anchor; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedPersistenceAnchorTypesANDROID xrEnumerateSupportedPersistenceAnchorTypesANDROID; // previously initialized
PFN_xrCreateDeviceAnchorPersistenceANDROID xrCreateDeviceAnchorPersistenceANDROID; // previously initialized
PFN_xrDestroyDeviceAnchorPersistenceANDROID xrDestroyDeviceAnchorPersistenceANDROID; // previously initialized
PFN_xrPersistAnchorANDROID xrPersistAnchorANDROID; // previously initialized
PFN_xrGetAnchorPersistStateANDROID xrGetAnchorPersistStateANDROID; // previously initialized
PFN_xrCreatePersistedAnchorSpaceANDROID xrCreatePersistedAnchorSpaceANDROID; // previously initialized
PFN_xrEnumeratePersistedAnchorsANDROID xrEnumeratePersistedAnchorsANDROID; // previously initialized
PFN_xrUnpersistAnchorANDROID xrUnpersistAnchorANDROID; // previously initialized

// Create a device anchor persistence handle
XrDeviceAnchorPersistenceCreateInfoANDROID persistenceHandleCreateInfo;
persistenceHandleCreateInfo.type = XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID;
persistenceHandleCreateInfo.next = nullptr;

XrDeviceAnchorPersistenceANDROID persistenceHandle;
CHK_XR(xrCreateDeviceAnchorPersistenceANDROID(session, &persistenceHandleCreateInfo, &persistenceHandle));

/// Persist an anchor
XrPersistedAnchorSpaceInfo anchorSpaceInfo;
anchorSpaceInfo.type = XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID;
anchorSpaceInfo.next = nullptr;
anchorSpaceInfo.anchor = anchor;

XrUuidEXT anchorId;
CHK_XR(xrPersistAnchorANDROID(persistenceHandle, &anchorSpaceInfo, &anchorId));

// ... Update loop ...
// Poll for anchor persist state to confirm if it was successfully persisted
XrAnchorPersistStateANDROID persistState;
CHK_XR(xrGetAnchorPersistStateANDROID(persistenceHandle, &anchorId, &persistState));
if (persistState == XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID)  {
  // The anchor was persisted successfully
}

// Enumerate all persisted anchors
uint32_t anchorCountOutput = 0;
std::vector<XrUuidEXT> allAnchors;

CHK_XR(xrEnumeratePersistedAnchorsANDROID(
  persistenceHandle,
  anchorCountOutput,
  &anchorCountOutput,
  nullptr
));
allAnchors.resize(anchorCountOutput, XR_NULL_HANDLE);

// Fetch the actual anchors in an appropriately resized array.
CHK_XR(xrEnumeratePersistedAnchorsANDROID(
  persistenceHandle,
  anchorCountOutput,
  &anchorCountOutput,
  allAnchors.data()
));

// Creating an anchor from a previously persisted anchor using its UUID
XrTime updateTime; // Time used for the current frame's simulation update.
XrUuidEXT anchorId = allAnchors[0];

XrPersistedAnchorSpaceCreateInfo createInfo;
createInfo.type = XR_TYPE_PERSISTED_ANCHOR_CREATE_INFO_ANDROID;
createInfo.next = nullptr;
createInfo.anchorId = anchorId;

XrSpace anchorSpace = XR_NULL_HANDLE;
CHK_XR(xrCreatePersistedAnchorSpaceANDROID(
  persistenceHandle,
  &createInfo,
  &anchorSpace
));

// The anchor was found and retrieved from the local device successfully.
XrSpaceLocation anchorLocation = { XR_TYPE_SPACE_LOCATION };
CHK_XR(xrLocateSpace(anchorSpace, appSpace, updateTime, &anchorLocation));
XrPosef pose = anchorLocation.pose;

// Once app is done with all persistence related tasks
CHK_XR(xrDestroySpace(anchorSpace));
CHK_XR(xrDestroyDeviceAnchorPersistenceANDROID(persistenceHandle));

New Object Types

New Enum Constants

XrObjectType enumeration is extended with:

  • XR_OBJECT_TYPE_DEVICE_ANCHOR_PERSISTENCE_ANDROID

XrResult enumeration is extended with:

  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_ANCHOR_ALREADY_PERSISTED_ANDROID
  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

XrStructureType enumeration is extended with:

  • XR_TYPE_PERSISTED_ANCHOR_ANDROID
  • XR_TYPE_PERSISTED_ANCHOR_SPACE_CREATE_INFO_ANDROID
  • XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID
  • XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID

New Enums

New Structures

New Functions

Issues

Version History

  • Revision 1, 2024-10-10 (Kenny Vercaemer)
    • Initial extension description