Skip to main content
Version: 14 Oct 2024

XR_ML_spatial_anchors_storage

Experimental API

This API is still an experimental extension not included in the official OpenXR registry and is subject to change.

12.110. XR_ML_spatial_anchors_storage

Name String

XR_ML_spatial_anchors_storage

Extension Type

Instance extension

Registered Extension Number

142

Revision

1

Extension and Version Dependencies
Last Modified Date

2023-08-24

Contributors

Ron Bessems, Magic Leap
Karthik Kadappan, Magic Leap

12.110.1. Overview

This extension allows spatial anchors created byXR_ML_spatial_anchors to be persisted beyond the head pose session.

Spatial Anchor management is closely tied to the selected mapping mode on the device. The modes are mutually exclusive and affect the functionality of these APIs. The available mapping modes are:

On-Device Mode A persistent mode in which anchors are persisted locally and will be available across multiple sessions when localized to the same localization map in which they were published.

AR Cloud Mode A persistent mode in which anchors are persisted in the cloud environment and will be available across multiple sessions and across multiple devices that are localized to the same localization map in which they were published.

For more details on mapping modes refer to the XR_ML_localization_mapextension.

Permissions

Android applications must have the com.magicleap.permission.SPATIAL_ANCHOR permission listed in their manifest to use this extension. (protection level: normal)

12.110.2. Storage

The XrSpatialAnchorsStorageML storage handle maintains the connection with the backend service. This can be on device or in cloud depending on the localization map that is active. Use the XR_ML_localization_map extension to deduce the current mode if the application needs to know this.

The xrCreateSpatialAnchorsStorageML function is defined as:

// Provided by XR_ML_spatial_anchors_storage
XrResult                                   xrCreateSpatialAnchorsStorageML(
    XrSession                                   session,
    const XrSpatialAnchorsCreateStorageInfoML*  createInfo,
    XrSpatialAnchorsStorageML*                  storage);
Parameter Descriptions
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_SPATIAL_ANCHORS_PERMISSION_DENIED_ML

The XrSpatialAnchorsCreateStorageInfoML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsCreateStorageInfoML {
    XrStructureType    type;
    const void*        next;
} XrSpatialAnchorsCreateStorageInfoML;

Currently no extra information is needed to create this structure.

Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

Valid Usage (Implicit)

// Provided by XR_ML_spatial_anchors_storage
XR_DEFINE_HANDLE(XrSpatialAnchorsStorageML)

The XrSpatialAnchorsStorageML handle represents the resources for storing spatial anchors.

The xrDestroySpatialAnchorsStorageML function is defined as:

// Provided by XR_ML_spatial_anchors_storage
XrResult                                                  xrDestroySpatialAnchorsStorageML(
    XrSpatialAnchorsStorageML                   storage);
Parameter Descriptions
Valid Usage (Implicit)
Thread Safety
  • Access to storage, and any child handles, must be externally synchronized

Return Codes
Success
  • XR_SUCCESS

Failure
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

12.110.3. Query Stored Anchors

To find out which Spatial Anchors are stored near a certain XrPosefthis extension provides a query system. This function is asynchronous and uses the XR_EXT_future extension.

The xrQuerySpatialAnchorsAsyncML function is defined as:

// Provided by XR_ML_spatial_anchors_storage
XrResult                                     xrQuerySpatialAnchorsAsyncML(
    XrSpatialAnchorsStorageML                   storage,
    const XrSpatialAnchorsQueryInfoBaseHeaderML* queryInfo,
    XrFutureEXT*                                future);
Parameter Descriptions

If the space was not locatable during the query the runtime must returnXR_ERROR_SPACE_NOT_LOCATABLE_EXT in futureResult ofXrSpatialAnchorsQueryCompletionML.

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_TIME_INVALID

  • XR_ERROR_SPATIAL_ANCHORS_SPACE_NOT_LOCATABLE_ML

The XrSpatialAnchorsQueryInfoRadiusML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsQueryInfoRadiusML {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrVector3f         center;
    XrTime             time;
    float              radius;
} XrSpatialAnchorsQueryInfoRadiusML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

  • baseSpace is the XrSpace to create the anchor relative to.

  • center is the center of the query relative to the baseSpace.

  • time is the time at which the pose should be resolved.

  • radius is the radius of the search area in meters.

Valid Usage (Implicit)

The XrSpatialAnchorsQueryInfoBaseHeaderML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsQueryInfoBaseHeaderML {
    XrStructureType    type;
    const void*        next;
} XrSpatialAnchorsQueryInfoBaseHeaderML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

Valid Usage (Implicit)

The xrQuerySpatialAnchorsCompleteML function is defined as:

// Provided by XR_ML_spatial_anchors_storage
XrResult                           xrQuerySpatialAnchorsCompleteML(
    XrSpatialAnchorsStorageML                   storage,
    XrFutureEXT                                 future,
    XrSpatialAnchorsQueryCompletionML*          completion);
Parameter Descriptions

Once the XrFutureEXT has completedxrQuerySpatialAnchorsCompleteML must be called to retrieve theXrUuidEXT values of the found anchors.

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_FUTURE_PENDING_EXT

  • XR_ERROR_FUTURE_INVALID_EXT

The XrSpatialAnchorsQueryCompletionML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsQueryCompletionML {
    XrStructureType    type;
    void*              next;
    XrResult           futureResult;
    uint32_t           uuidCapacityInput;
    uint32_t           uuidCountOutput;
    XrUuidEXT*         uuids;
} XrSpatialAnchorsQueryCompletionML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

  • futureResult is the XrResult of the asynchronous operation.

  • uuidCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.

  • uuidCountOutput is the number of anchors, or the required capacity in the case that uuidCapacityInput is insufficient.

  • uuids is an array of XrUuidEXT.

Future Return Codes

futureResult values:

Success
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

Failure
  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_SPACE_NOT_LOCATABLE_EXT

  • XR_ERROR_SPATIAL_ANCHORS_SPACE_NOT_LOCATABLE_ML

  • XR_ERROR_SPATIAL_ANCHORS_NOT_LOCALIZED_ML

Valid Usage (Implicit)

12.110.4. Publish Anchors

If the application needs to persist an anchor beyond the current head pose session it should publish the anchor. Publishing is an asynchronous operation and can publish multiple anchors at the same time.

The xrPublishSpatialAnchorsAsyncML function is defined as:

// Provided by XR_ML_spatial_anchors_storage
XrResult                             xrPublishSpatialAnchorsAsyncML(
    XrSpatialAnchorsStorageML                   storage,
    const XrSpatialAnchorsPublishInfoML*        publishInfo,
    XrFutureEXT*                                future);
Parameter Descriptions
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 XrSpatialAnchorsPublishInfoML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsPublishInfoML {
    XrStructureType    type;
    const void*        next;
    uint32_t           anchorCount;
    const XrSpace*     anchors;
    uint64_t           expiration;
} XrSpatialAnchorsPublishInfoML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

  • anchorCount is the number of anchors in the anchors array.

  • anchors is an array of XrSpace.

  • expiration is an uint64_t, is the time in seconds since epoch after which these anchors may expire. The system may retain the anchors longer but should retain the anchors at least until this timestamp. Use 0 or XR_INFINITE_DURATION to create an anchor that does not expire.

Valid Usage (Implicit)

Once the XrFutureEXT has completedxrPublishSpatialAnchorsCompleteML must be called to retrieve theXrUuidEXT values of the published anchors.

The xrPublishSpatialAnchorsCompleteML function is defined as:

// Provided by XR_ML_spatial_anchors_storage
XrResult                             xrPublishSpatialAnchorsCompleteML(
    XrSpatialAnchorsStorageML                   storage,
    XrFutureEXT                                 future,
    XrSpatialAnchorsPublishCompletionML*        completion);
Parameter Descriptions
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_FUTURE_PENDING_EXT

  • XR_ERROR_FUTURE_INVALID_EXT

The XrSpatialAnchorsPublishCompletionML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsPublishCompletionML {
    XrStructureType    type;
    void*              next;
    XrResult           futureResult;
    uint32_t           uuidCount;
    XrUuidEXT*         uuids;
} XrSpatialAnchorsPublishCompletionML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

  • futureResult is the XrResult of the asynchronous operation.

  • uuidCount is the capacity of the array and must match the number of anchors passed to xrPublishSpatialAnchorsAsyncML

  • uuids is an array of XrUuidEXT.

Future Return Codes

futureResult values:

Success
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

Failure
  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_SPATIAL_ANCHORS_NOT_LOCALIZED_ML

  • XR_ERROR_SPATIAL_ANCHORS_OUT_OF_MAP_BOUNDS_ML

Valid Usage (Implicit)

The XrSpatialAnchorsPublishCompletionDetailsML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsPublishCompletionDetailsML {
    XrStructureType                       type;
    void*                                 next;
    uint32_t                              resultCount;
    XrSpatialAnchorCompletionResultML*    results;
} XrSpatialAnchorsPublishCompletionDetailsML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

  • resultCount is the capacity of the results array and must match the number of anchors passed to xrPublishSpatialAnchorsAsyncML

  • results is the per uuid status of the publish operation. The order of anchors in this array must match the async request order.

Valid Usage (Implicit)

The XrSpatialAnchorCompletionResultML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorCompletionResultML {
    XrUuidEXT    uuid;
    XrResult     result;
} XrSpatialAnchorCompletionResultML;
Member Descriptions
  • uuid is the uuid of the anchor.

  • result is the result of the operation.

Anchor Operation Result Codes

result values:

Success
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

Failure
  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_SPATIAL_ANCHORS_NOT_LOCALIZED_ML

  • XR_ERROR_SPATIAL_ANCHORS_OUT_OF_MAP_BOUNDS_ML

Valid Usage (Implicit)

12.110.5. Delete Published Anchors

To delete anchors from the storage, xrDeleteSpatialAnchorsAsyncML canbe used.

The xrDeleteSpatialAnchorsAsyncML function is defined as:

// Provided by XR_ML_spatial_anchors_storage
XrResult                            xrDeleteSpatialAnchorsAsyncML(
    XrSpatialAnchorsStorageML                   storage,
    const XrSpatialAnchorsDeleteInfoML*         deleteInfo,
    XrFutureEXT*                                future);
Parameter Descriptions
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 XrSpatialAnchorsDeleteInfoML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsDeleteInfoML {
    XrStructureType     type;
    const void*         next;
    uint32_t            uuidCount;
    const XrUuidEXT*    uuids;
} XrSpatialAnchorsDeleteInfoML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

  • uuidCount is the number of anchors in the anchors array.

  • uuids is an array of XrUuidEXT.

Valid Usage (Implicit)

Once the XrFutureEXT has completedxrPublishSpatialAnchorsCompleteML must be called to retrieve the status of the delete operation.

The xrDeleteSpatialAnchorsCompleteML function is defined as:

// Provided by XR_ML_spatial_anchors_storage
XrResult                            xrDeleteSpatialAnchorsCompleteML(
    XrSpatialAnchorsStorageML                   storage,
    XrFutureEXT                                 future,
    XrSpatialAnchorsDeleteCompletionML*         completion);
Member Descriptions
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_FUTURE_PENDING_EXT

  • XR_ERROR_FUTURE_INVALID_EXT

The XrSpatialAnchorsDeleteCompletionML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsDeleteCompletionML {
    XrStructureType    type;
    void*              next;
    XrResult           futureResult;
} XrSpatialAnchorsDeleteCompletionML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

  • futureResult is the XrResult of the asynchronous operation.

Future Return Codes

futureResult values:

Success
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

Failure
  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_SPATIAL_ANCHORS_ANCHOR_NOT_FOUND_ML

  • XR_ERROR_SPATIAL_ANCHORS_NOT_LOCALIZED_ML

Valid Usage (Implicit)

The XrSpatialAnchorsDeleteCompletionDetailsML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsDeleteCompletionDetailsML {
    XrStructureType                       type;
    void*                                 next;
    uint32_t                              resultCount;
    XrSpatialAnchorCompletionResultML*    results;
} XrSpatialAnchorsDeleteCompletionDetailsML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

  • resultCount is the capacity of the results array and must match the number of anchors passed to xrDeleteSpatialAnchorsAsyncML

  • results is the per uuid status of the delete operation. The order of anchors in this array must match the async request order.

Valid Usage (Implicit)

12.110.6. Update published Anchors expiration

To update the expiration time on anchorsxrUpdateSpatialAnchorsExpirationAsyncML can be used.

The xrUpdateSpatialAnchorsExpirationAsyncML function is defined as:

// Provided by XR_ML_spatial_anchors_storage
XrResult                                      xrUpdateSpatialAnchorsExpirationAsyncML(
    XrSpatialAnchorsStorageML                   storage,
    const XrSpatialAnchorsUpdateExpirationInfoML* updateInfo,
    XrFutureEXT*                                future);
Parameter Descriptions
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

The XrSpatialAnchorsUpdateExpirationInfoML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsUpdateExpirationInfoML {
    XrStructureType     type;
    const void*         next;
    uint32_t            uuidCount;
    const XrUuidEXT*    uuids;
    uint64_t            expiration;
} XrSpatialAnchorsUpdateExpirationInfoML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

  • uuidCount is the number of anchors in the anchors array.

  • uuids is an array of XrUuidEXT.

  • expiration is an uint64_t, is the time in seconds since epoch after which these anchors may expire.

Valid Usage (Implicit)

Once the XrFutureEXT has completedxrUpdateSpatialAnchorsExpirationCompleteML must be called to retrieve the status of the publish operation.

The xrUpdateSpatialAnchorsExpirationCompleteML function is defined as:

// Provided by XR_ML_spatial_anchors_storage
XrResult                                      xrUpdateSpatialAnchorsExpirationCompleteML(
    XrSpatialAnchorsStorageML                   storage,
    XrFutureEXT                                 future,
    XrSpatialAnchorsUpdateExpirationCompletionML* completion);
Member Descriptions
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_FUTURE_PENDING_EXT

  • XR_ERROR_FUTURE_INVALID_EXT

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsUpdateExpirationCompletionML {
    XrStructureType    type;
    void*              next;
    XrResult           futureResult;
} XrSpatialAnchorsUpdateExpirationCompletionML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

  • futureResult is the XrResult of the asynchronous operation.

Future Return Codes

futureResult values:

Success
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

Failure
  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_SPATIAL_ANCHORS_ANCHOR_NOT_FOUND_ML

  • XR_ERROR_SPATIAL_ANCHORS_NOT_LOCALIZED_ML

Valid Usage (Implicit)

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsUpdateExpirationCompletionDetailsML {
    XrStructureType                       type;
    void*                                 next;
    uint32_t                              resultCount;
    XrSpatialAnchorCompletionResultML*    results;
} XrSpatialAnchorsUpdateExpirationCompletionDetailsML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

  • resultCount is the capacity of the results array and must match the number of anchors passed to xrUpdateSpatialAnchorsExpirationAsyncML

  • results is the per uuid status of the update operation. The order of anchors in this array must match the async request order.

Valid Usage (Implicit)

12.110.7. Create Spatial Anchors from Storage

Spatial Anchors can be created from the storage XrUuidEXT by passing the XrSpatialAnchorsCreateInfoFromUuidsML structure toxrCreateSpatialAnchorsAsyncML.

The XrSpatialAnchorsCreateInfoFromUuidsML structure is defined as:

// Provided by XR_ML_spatial_anchors_storage
typedef struct XrSpatialAnchorsCreateInfoFromUuidsML {
    XrStructureType              type;
    const void*                  next;
    XrSpatialAnchorsStorageML    storage;
    uint32_t                     uuidCount;
    const XrUuidEXT*             uuids;
} XrSpatialAnchorsCreateInfoFromUuidsML;
Member Descriptions
  • type is the XrStructureType of this structure.

  • next is NULL or a pointer to the next structure in a structure chain.

  • storage is the XrSpatialAnchorsStorageML to use.

  • uuidCount is the number of elements in the uuids array.

  • uuids is pointer to an array of XrUuidEXT.

Valid Usage (Implicit)

The XrSpace handle or handles returned viaXrCreateSpatialAnchorsCompletionML::spaces must be in the same order as uuids.

The XrCreateSpatialAnchorsCompletionML::spaceCount field mustmatch uuidCount. If not the runtime must return XR_ERROR_VALIDATION_FAILURE inXrCreateSpatialAnchorsCompletionML::futureResult.

If an anchor with a given UUID is not found, the runtime must returnXR_NULL_HANDLE for the corresponding XrSpace handle(s) and return XR_SUCCESS inXrCreateSpatialAnchorsCompletionML::futureResult.

12.110.8. Examples

This example shows how to persist a list of anchors.

XrInstance instance;                // previously initialized
XrSession session;                  // previously initialized

XrSpace anchor1; // previously initialized
XrSpace anchor2; // previously initialized

std::vector<XrSpace> anchors{anchor1, anchor2};

XrSpatialAnchorsCreateStorageInfoML storageCreateInfo{XR_TYPE_SPATIAL_ANCHORS_CREATE_STORAGE_INFO_ML};
XrSpatialAnchorsStorageML storage;

CHK_XR(xrCreateSpatialAnchorsStorageML(session, &storageCreateInfo, &storage));

XrSpatialAnchorsPublishInfoML publishInfo{XR_TYPE_SPATIAL_ANCHORS_PUBLISH_INFO_ML};
publishInfo.anchorCount = static_cast<uint32_t>(anchors.size());
publishInfo.anchors = anchors.data();
publishInfo.expiration = 0;

XrFutureEXT future;
CHK_XR(xrPublishSpatialAnchorsAsyncML(storage, &publishInfo, &future));

XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
pollInfo.future = future;
pollResult.state = XR_FUTURE_STATE_PENDING_EXT;

// Ideally this should be done once in your
// game loop instead of a busy wait.
while(pollResult.state==XR_FUTURE_STATE_PENDING_EXT) {
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
}

XrSpatialAnchorsPublishCompletionML completion{XR_TYPE_SPATIAL_ANCHORS_PUBLISH_COMPLETION_ML};
std::vector<XrUuidEXT> uuids(anchors.size());
completion.uuidCount = static_cast<uint32_t>(uuids.size());
completion.uuids = uuids.data();
CHK_XR(xrPublishSpatialAnchorsCompleteML(storage, future, &completion));
CHK_XR(completion.futureResult);

// completion.uuid will now contain the UUID of the corresponding Spatial Anchors.

CHK_XR(xrDestroySpatialAnchorsStorageML(storage));

This example shows how to query for anchors.

XrTime currentTime;                 // previously initialized
XrVector3f center;                       // previously initialized

XrSpatialAnchorsCreateStorageInfoML storageCreateInfo{XR_TYPE_SPATIAL_ANCHORS_CREATE_STORAGE_INFO_ML};
XrSpatialAnchorsStorageML storage;

CHK_XR(xrCreateSpatialAnchorsStorageML(session, &storageCreateInfo, &storage));

// set up a query around a previously initialized center position with a radius of 10 meters.
XrSpatialAnchorsQueryInfoRadiusML queryInfo{XR_TYPE_SPATIAL_ANCHORS_QUERY_INFO_RADIUS_ML};
queryInfo.baseSpace = viewSpace; // using viewspace, but can: be any space.
queryInfo.center = center;
queryInfo.time = currentTime;
queryInfo.radius = 10.0f;

XrFutureEXT future;
CHK_XR(xrQuerySpatialAnchorsAsyncML(storage, reinterpret_cast<XrSpatialAnchorsQueryInfoBaseHeaderML*>(&queryInfo), &future));

XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
pollInfo.future = future;
pollResult.state = XR_FUTURE_STATE_PENDING_EXT;

// Ideally this should be done once in your
// frame loop instead of a busy wait.
while(pollResult.state==XR_FUTURE_STATE_PENDING_EXT) {
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
}

XrSpatialAnchorsQueryCompletionML completion{XR_TYPE_SPATIAL_ANCHORS_QUERY_COMPLETION_ML};
CHK_XR(xrQuerySpatialAnchorsCompleteML(storage, future, &completion));
CHK_XR(completion.futureResult);

std::vector<XrUuidEXT> uuids(completion.uuidCountOutput);
completion.uuidCapacityInput = static_cast<uint32_t>(uuids.size());
completion.uuids = uuids.data();

CHK_XR(xrQuerySpatialAnchorsCompleteML(storage, future, &completion));

// completion.uuid will now contain the UUID of the corresponding Spatial Anchors.

CHK_XR(xrDestroySpatialAnchorsStorageML(storage));

12.110.9. New Object Types

12.110.12. New Enum Constants

  • XR_ML_SPATIAL_ANCHORS_STORAGE_EXTENSION_NAME

  • XR_ML_spatial_anchors_storage_SPEC_VERSION

  • Extending XrObjectType:

    • XR_OBJECT_TYPE_SPATIAL_ANCHORS_STORAGE_ML

  • Extending XrResult:

    • XR_ERROR_SPATIAL_ANCHORS_ANCHOR_NOT_FOUND_ML

  • Extending XrStructureType:

    • XR_TYPE_SPATIAL_ANCHORS_CREATE_INFO_FROM_UUIDS_ML

    • XR_TYPE_SPATIAL_ANCHORS_CREATE_STORAGE_INFO_ML

    • XR_TYPE_SPATIAL_ANCHORS_DELETE_COMPLETION_DETAILS_ML

    • XR_TYPE_SPATIAL_ANCHORS_DELETE_COMPLETION_ML

    • XR_TYPE_SPATIAL_ANCHORS_DELETE_INFO_ML

    • XR_TYPE_SPATIAL_ANCHORS_PUBLISH_COMPLETION_DETAILS_ML

    • XR_TYPE_SPATIAL_ANCHORS_PUBLISH_COMPLETION_ML

    • XR_TYPE_SPATIAL_ANCHORS_PUBLISH_INFO_ML

    • XR_TYPE_SPATIAL_ANCHORS_QUERY_COMPLETION_ML

    • XR_TYPE_SPATIAL_ANCHORS_QUERY_INFO_RADIUS_ML

    • XR_TYPE_SPATIAL_ANCHORS_UPDATE_EXPIRATION_COMPLETION_DETAILS_ML

    • XR_TYPE_SPATIAL_ANCHORS_UPDATE_EXPIRATION_COMPLETION_ML

    • XR_TYPE_SPATIAL_ANCHORS_UPDATE_EXPIRATION_INFO_ML

Version History

  • Revision 1, 2023-06-22 (Ron Bessems)

    • Initial extension description