Spatial Anchors OpenXR API Reference

• An application to create a spatial anchor.
• An application to enumerate an anchor’s supported components (spatial anchor or otherwise).
• An application to enable or disable a component.
  Note

  not all components are mutable
• An application to get the status of a component.

• Android manifest permission USE_ANCHOR_API. For more information, see the Developer Environment Setup page.

• xrEnumerateSpaceSupportedComponentsFB.
• xrSetSpaceComponentStatusFB.
• xrGetSpaceComponentStatusFB.

typedef enum XrSpaceComponentTypeFB {
    XR_SPACE_COMPONENT_TYPE_LOCATABLE_FB = 0,
    XR_SPACE_COMPONENT_TYPE_STORABLE_FB = 1,
    XR_SPACE_COMPONENT_TYPE_SHARABLE_FB = 2,
    XR_SPACE_COMPONENT_TYPE_BOUNDED_2D_FB = 3,
    XR_SPACE_COMPONENT_TYPE_BOUNDED_3D_FB = 4,
    XR_SPACE_COMPONENT_TYPE_SEMANTIC_LABELS_FB = 5,
    XR_SPACE_COMPONENT_TYPE_ROOM_LAYOUT_FB = 6,
    XR_SPACE_COMPONENT_TYPE_SPACE_CONTAINER_FB = 7,
    XR_SPACE_COMPONENT_TYPE_TRIANGLE_MESH_META = 1000269000,
    XR_SPACE_COMPONENT_TYPE_MAX_ENUM_FB = 0x7FFFFFFF
} XrSpaceComponentTypeFB;

• XR_SPACE_COMPONENT_TYPE_LOCATABLE_FB: Enables tracking the 6 DOF pose of the spatial anchor with xrLocateSpace.
• XR_SPACE_COMPONENT_TYPE_STORABLE_FB: Enables persistence operations: save and erase.
• XR_SPACE_COMPONENT_TYPE_SHARABLE_FB: Enables sharing operation: share.
• XR_SPACE_COMPONENT_TYPE_BOUNDED_2D_FB: 2D Plane component, see Scene documentation for more.
• XR_SPACE_COMPONENT_TYPE_BOUNDED_3D_FB: 3D Plane component, see Scene documentation for more.
• XR_SPACE_COMPONENT_TYPE_SEMANTIC_LABELS_FB: Label for an entity, see Scene documentation for more.
• XR_SPACE_COMPONENT_TYPE_ROOM_LAYOUT_FB: Room layout information, see Scene documentation for more.
• XR_SPACE_COMPONENT_TYPE_SPACE_CONTAINER_FB: Entity container, see Scene documentation for more.
• XR_SPACE_COMPONENT_TYPE_TRIANGLE_MESH_META: Mesh component, see Scene documentation for more.

XrResult xrEnumerateSpaceSupportedComponentsFB(
    XrSpace               space,
    uint32_t              componentTypesCapacityInput,
    uint32_t*             componentTypesCountOutput,
    XrComponentTypeFB*    componentTypes);

• space: The XrSpace handle to the anchor.
• componentTypesCapacityInput: The maximum number of component types expected by the caller. The caller uses this maximum value to ensure the array returned through the componentTypes out-parameter does not exceed the bounds of the array allocated by the caller.
• componentTypesCountOutput: An output parameter showing the number of enumerated component types.
• componentTypes: An output parameter providing an array of the component types supported by the specified anchor.

• XR_SUCCESS

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

XrResult xrSetSpaceComponentStatusFB(
    XrSpace                                space,
    const XrSpaceComponentStatusSetInfoFB* request,
    XrAsyncRequestIdFB*                    requestId);

• space: The XrSpace handle to the anchor.
• request: The pointer to an XrSpaceComponentStatusSetInfoFB structure containing information about the component to be enabled.
• requestID: The output parameter that points to the ID of this asynchronous request.

• XR_SUCCESS

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_SPACE_COMPONENT_NOT_SUPPORTED_FB
• XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB
• XR_ERROR_SPACE_COMPONENT_STATUS_PENDING_FB
• XR_ERROR_SPACE_COMPONENT_ALREADY_ENABLED_FB

XrResult xrGetSpaceComponentStatusFB(
    XrSpace                   space,
    XrSpaceComponentTypeFB    componentType,
    XrSpaceComponentStatusFB* status);

• space: A pointer to the returned XrSpace handle of the new spatial anchor.
• componentType: The component type you want to query.
• status: An output parameter showing information about the status of the component you queried.

• XR_SUCCESS

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

XrResult xrCreateSpatialAnchorFB(
    XrSession           session,
    const               XrSpatialAnchorCreateInfoFB* info,
    XrAsyncRequestIdFB* requestId);

• session: A handle to an XrSession.
• info: Pointer to an XrSpatialAnchorCreateInfoFB structure containing information about how to create the anchor.
• requestId: A pointer to the returned XrAsyncRequestIdFB handle of the operation that was started.

• XR_SUCCESS

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE

xrSpaceComponentStatusSetFB

typedef struct XrSpaceComponentStatusSetFB {
    XrStructureType        type;
    const void*            next;
    XrSpaceComponentTypeFB componentType;
    XrBool32               enable;
    XrDuration             timeout;
} XrSpaceComponentStatusSetFB;

• type: The XrStructureType of this structure.
• next: Is either NULL or a pointer to the next structure in a structure chain. Core OpenXR doesn’t define these structures.
• componentType: The component whose status you want to set.
• enable: The value to which you want to set the component.
• timeout: The number of nanoseconds before the operation should timeout. A value of 0.0 indicates no timeout.

xrSpatialAnchorCreateInfoFB

typedef struct XrSpatialAnchorCreateInfoFB {
    XrStructureType    type;
    void*              next;
    XrSpace            space;
    XrPosef            poseInSpace;
    XrTime             time;
} XrSpatialAnchorCreateInfoFB;

• type: The XrStructureType of this structure.
• next: Must be NULL or a pointer to the next structure in a structure chain. Core OpenXR doesn’t define such structures.
• space: The XrSpace handle to the reference space defining the poseInSpace of the anchor you created.
• poseInSpace: The XrPosef location and orientation of the spatial anchor in the specified reference space.
• time: The XrTime timestamp associated with the specified pose.

• XR_ERROR_SPACE_COMPONENT_NOT_SUPPORTED_FB: This component is not supported for this XrSpace
• XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB: This component is not enabled for this XrSpace
• XR_ERROR_SPACE_COMPONENT_STATUS_PENDING_FB: There is an ongoing operation to enable this component for this XrSpace
• XR_ERROR_SPACE_COMPONENT_STATUS_ALREADY_SET_FB: This component has already been set for this XrSpace

• Long-Term Storage: Spatial entities are stored indefinitely until explicitly erased.
• Session Independence: The XR_META_spatial_entity_persistence extension allows spatial entities to persist across different user sessions. In other words, once a spatial entity is persisted, it remains available for retrieval, and should be unchanged in subsequent user sessions until it is explicitly erased.
• Implicit Storage Management: This extension does not require storage management/synchronization, it is handled on behalf of the developer by the system.

• XR_FB_spatial_entity_storage
• XR_FB_spatial_entity_storage_batch

• End user enabled local file system access for the application: End users need to have opted-in to let the application access the device’s file system.

XRAPI_ATTR XrResult XRAPI_CALL xrSaveSpacesMETA(
    XrSession session,
    const XrSpacesSaveInfoMETA* info,
    XrAsyncRequestIdFB* requestId);

• session: The XrSession object representing the current XR session.
• info: A pointer to the XrSpacesSaveInfoMETA struct containing the spatial entities to be saved.
• requestId: An XrAsyncRequestIdFB atom that represents the request ID for the save operation for async event handling.
• Synchronous Returns: The xrSaveSpacesMETA function returns an XrResult indicating the success or failure of triggering the async operation.
• Asynchronous Returns: The async event will be returned as a callback, and that struct contains another XrResult, indicating the success or failure of the operation as a whole.

XrResult result = xrSaveSpacesMETA(session, &info, &requestId);
if (XR_SUCCESS == result)
{
    // Save operation was successfully triggered.
} else {
    // Save operation failed to trigger.
}

XRAPI_ATTR XrResult XRAPI_CALL xrEraseSpacesMETA(
    XrSession session,
    const XrSpacesEraseInfoMETA* info,
    XrAsyncRequestIdFB* requestId);

• session: The XrSession object representing the current XR session.
• info: A pointer to the XrSpacesEraseInfoMETA struct containing the anchors to be erased (either via XrSpace handle or via UUID).
• requestId: An XrAsyncRequestIdFB atom that represents the request ID for the erase operation for async event handling.

XrResult result = xrEraseSpacesMETA(session, &info, &requestId);
if (XR_SUCCESS == result)
{
    // Erase operation was successfully triggered.
} else {
    // Erase operation failed to trigger.
}

/**
 * Structure representing the anchor information to be saved.
 */
struct XrSpacesSaveInfoMETA {
    XrStructureType type; // XR_TYPE_SPACES_SAVE_INFO_META
    const void* XR_MAY_ALIAS next;
    uint32_t spaceCount;
    XrSpace* spaces;
};

/**
 * Structure representing the result of a space save operation.
 */
struct XrEventDataSpacesSaveResultMETA {
    XrStructureType type; // XR_TYPE_EVENT_DATA_SPACES_SAVE_RESULT_META
    const void* XR_MAY_ALIAS next;
    XrAsyncRequestIdFB requestId;
    XrResult result;
};

/**
 * Structure representing the information for a spaces erase operation.
 */
struct XrSpacesEraseInfoMETA {
    XrStructureType type; // XR_TYPE_SPACES_ERASE_INFO_META
    const void* XR_MAY_ALIAS next;
    uint32_t spaceCount;
    XrSpace* spaces;
    uint32_t uuidCount;
    XrUuidEXT* uuids;
};

/**
 * Structure representing the result of a spaces erase operation.
 */
struct XrEventDataSpacesEraseResultMETA {
    XrStructureType type; // XR_TYPE_EVENT_DATA_SPACES_ERASE_RESULT_META
    const void* XR_MAY_ALIAS next;
    XrAsyncRequestIdFB requestId;
    XrResult result;
};

• XR_TYPE_EVENT_DATA_SPACES_SAVE_RESULT_META
• XR_TYPE_EVENT_DATA_SPACES_ERASE_RESULT_META

// Called per-frame
void handleOpenXrAnchorEvents() {
    XrEventDataBuffer eventDataBuffer = {};
    // Poll for events.
    while (true) {
        XrEventDataBaseHeader* baseEventHeader = (XrEventDataBaseHeader*)(&eventDataBuffer);
        baseEventHeader->type = XR_TYPE_EVENT_DATA_BUFFER;
        baseEventHeader->next = nullptr;
        XrResult result = xrPollEvent(instance, &eventDataBuffer);
        if (result != XR_SUCCESS) {
            break;
        }

        ...

        if (baseEventHeader->type == XR_TYPE_EVENT_DATA_SPACES_SAVE_RESULT_META) {
                const XrEventDataSpacesSaveResultMETA* saveAnchorResult =
                    (XrEventDataSpacesSaveResultMETA*)(baseEventHeader);

                // Find the requestId provided during the sync phase earlier and any associated data

                if (saveAnchorResult->result < XR_SUCCESS) {
                    ...
                } else {
                    ...
                }
        } else if (baseEventHeader->type == XR_TYPE_EVENT_DATA_SPACES_ERASE_RESULT_META) {
            const XrEventDataSpacesEraseResultMETA* eraseAnchorResult =
                (XrEventDataSpacesEraseResultMETA*)(baseEventHeader);

            // Find the requestId provided during the sync phase earlier and any associated data

            if (eraseAnchorResult->result < XR_SUCCESS) {
                ...
            } else {
                ...
            }
        }

        ...
    }
}

• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_SESSION_NOT_RUNNING
• XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB
• XR_ERROR_INITIALIZATION_FAILED
• XR_ERROR_SPACE_RATE_LIMITED_META
• XR_SUCCESS

• XR_ERROR_SPACE_INSUFFICIENT_RESOURCES_META: Resource limitation prevented this operation from executing. Recommend retrying, perhaps after a short delay and/or reducing memory consumption.
• XR_ERROR_SPACE_STORAGE_AT_CAPACITY_META: Operation could not be completed until resources used are reduced or storage expanded.
• XR_ERROR_SPACE_INSUFFICIENT_VIEW_META: Look around the environment more for sufficient space tracking to complete the operation.
• XR_ERROR_SPACE_PERMISSION_INSUFFICIENT_META: Space operation permission insufficient. Recommend confirming the status of the required permissions needed for using spatial anchor APIs.
• XR_ERROR_SPACE_RATE_LIMITED_META: Operation cancelled due to rate limiting. Recommend retrying after a short delay.
• XR_ERROR_SPACE_TOO_DARK_META: Environment too dark for tracking to complete operation.
• XR_ERROR_SPACE_TOO_BRIGHT_META: Environment too bright for tracking to complete operation.

• UUID Filter: The discovery mechanism can filter spatial entities based on their UUID (Universally Unique Identifier). This aids in targeted retrieval of specific spatial entities.
• Component Filter: The discovery mechanism can filter spatial entities based on certain immutable components. These components that anchors are discoverable by are as follows:
  • XR_SPACE_COMPONENT_TYPE_BOUNDED_2D_FB
  • XR_SPACE_COMPONENT_TYPE_BOUNDED_3D_FB
  • XR_SPACE_COMPONENT_TYPE_SEMANTIC_LABELS_FB
  • XR_SPACE_COMPONENT_TYPE_ROOM_LAYOUT_FB
  • XR_SPACE_COMPONENT_TYPE_SPACE_CONTAINER_FB
  • XR_SPACE_COMPONENT_TYPE_TRIANGLE_MESH_META
• No Filter: The discovery mechanism can also be used with no filters specified. This will return any and all spatial entities the device can find that are locatable in the user’s physical space.
• Support for Larger Spaces: The discovery operation is more efficient than the Query APIs, and is effective in larger spatial areas.

• End user enabled local file system access for the application: End users need to have opted-in to let the application access the device’s file system.
• [Optional] Enhanced Spatial Services: In order for discovery to retrieve non-local data (for example, anchors on Meta’s infrastructure), the discoverer would need to have enabled the Enhanced Spatial Services permission.

XRAPI_ATTR XrResult XRAPI_CALL xrDiscoverSpacesMETA(
    XrSession session,
    const XrSpaceDiscoveryInfoMETA* info,
    XrAsyncRequestIdFB* requestId
);

• session: An XrSession for the current application instance.
• info: A pointer to the discovery information, XrSpaceDiscoveryInfoMETA*.
• requestId: A pointer to the request ID, XrAsyncRequestIdFB*. This is an out parameter that will be populated by the API call.
• Synchronous Returns: The xrDiscoverSpacesMETA function returns an XrResult indicating the success or failure of triggering the async operation.
• Asynchronous Returns: The async event will be returned as a callback, and the Complete event struct contains another XrResult, indicating the success or failure of the operation as a whole.
• Filters: The xrDiscoverSpacesMETA API is designed to accept a list of filters, subject to certain constraints.
• Array Format: The filters are structured in the form of an array of a base type, to accommodate potential future filter enhancements. For reference, the filter will act as a pointer to struct pointers.
• Filter Types: The array of struct pointers may contain multiple instances of each of the following filter types:
  • XrSpaceUuidFilterInfoMETA
  • XrSpaceComponentFilterInfoMETA The behaviour of filter interaction can be thought of like distinct filter types behaving like AND and like filter types behaving like OR.
• Batched Operation Support: The XrSpaceUuidFilterInfoMETA is capable of accepting an array of UUIDs, enabling the API to perform batch operations effectively.
  Note

  There is a limit to the number of UUIDs the system can accept for any given call, 50. However the system is capable of providing any number of anchors. That is, a no-filter discovery call may return >50 anchors but a discovery call with UUID filter(s) specified can return at most 50.

std::vector<const XrSpaceFilterBaseHeaderMETA*> filters;

// Initialize UUID filter
const XrSpaceFilterUuidMETA uuidFilter = XrSpaceFilterUuidMETA{
    XR_TYPE_SPACE_FILTER_UUID_META,
    nullptr,
    static_cast<uint32_t>(uuids.size()),
    uuids.data()};
uuidFilterPtr = reinterpret_cast<const XrSpaceFilterBaseHeaderMETA*>(&uuidFilter);
filters.push_back(uuidFilterPtr);

// Initialize Component Filter
const XrSpaceFilterComponentMETA componentFilter = XrSpaceFilterComponentMETA{
    XR_TYPE_SPACE_FILTER_COMPONENT_META, nullptr, componentType};
componentFilterPtr =
    reinterpret_cast<const XrSpaceFilterBaseHeaderMETA*>(&componentFilter);
filters.push_back(componentFilterPtr);

XrSpaceDiscoveryInfoMETA info = {
    XR_TYPE_SPACE_DISCOVERY_INFO_META, nullptr, 2, filters.data()};
XrResult result = xrDiscoverSpacesMETA(session, &info, &requestId);
if (XR_SUCCESS == result)
{
    // Discover operation was successfully triggered.
} else {
    // Discover operation failed to trigger.
}

XRAPI_ATTR XrResult XRAPI_CALL xrRetrieveSpaceDiscoveryResultsMETA(
    XrSession session,
    XrAsyncRequestIdFB requestId,
    XrSpaceDiscoveryResultsMETA* results
);

• session: An XrSession for the current application instance.
• requestId: The XrAsyncRequestIdFB request ID for which results are being retrieved.
• results: A pointer to the XrSpaceDiscoveryResultsMETA struct where the discovery results will be stored.

XrSpaceDiscoveryInfoMETA

• XR_TYPE_SPACE_UUID_FILTER_INFO_META
• XR_TYPE_SPACE_COMPONENT_FILTER_INFO_META

static const XrStructureType XR_TYPE_SPACE_DISCOVERY_INFO_META = (XrStructureType) 1000247001;
typedef struct XrSpaceDiscoveryInfoMETA {
    XrStructureType                               type;
    const void* XR_MAY_ALIAS                      next;
    uint32_t                                      filterCount;
    const XrSpaceFilterBaseHeaderMETA* const *    filters;
} XrSpaceDiscoveryInfoMETA;

XrSpaceDiscoveryResultMETA

typedef struct XrSpaceDiscoveryResultMETA {
    XrSpace      space;
    XrUuidEXT    uuid;
} XrSpaceDiscoveryResultMETA;

XrSpaceDiscoveryResultsMETA

static const XrStructureType XR_TYPE_SPACE_DISCOVERY_RESULTS_META = (XrStructureType) 1000247006;
typedef struct XrSpaceDiscoveryResultsMETA {
    XrStructureType                type;
    const void* XR_MAY_ALIAS       next;
    uint32_t                       resultCapacityInput;
    uint32_t                       resultCountOutput;
    XrSpaceDiscoveryResultMETA*    results;
} XrSpaceDiscoveryResultsMETA;

static const XrStructureType XR_TYPE_EVENT_DATA_SPACE_DISCOVERY_RESULTS_AVAILABLE_META = (XrStructureType) 1000247007;
typedef struct XrEventDataSpaceDiscoveryResultsAvailableMETA {
    XrStructureType             type;
    const void* XR_MAY_ALIAS    next;
    XrAsyncRequestIdFB          requestId;
} XrEventDataSpaceDiscoveryResultsAvailableMETA;

static const XrStructureType XR_TYPE_EVENT_DATA_SPACE_DISCOVERY_COMPLETE_META = (XrStructureType) 1000247008;
typedef struct XrEventDataSpaceDiscoveryCompleteMETA {
    XrStructureType             type;
    const void* XR_MAY_ALIAS    next;
    XrAsyncRequestIdFB          requestId;
    XrResult                    result;
} XrEventDataSpaceDiscoveryCompleteMETA;

// Called per-frame
void handleOpenXrAnchorEvents() {
    XrEventDataBuffer eventDataBuffer = {};
    // Poll for events.
    while (true) {
        XrEventDataBaseHeader* baseEventHeader = (XrEventDataBaseHeader*)(&eventDataBuffer);
        baseEventHeader->type = XR_TYPE_EVENT_DATA_BUFFER;
        baseEventHeader->next = nullptr;
        XrResult result = xrPollEvent(instance, &eventDataBuffer);
        if (result != XR_SUCCESS) {
            // Handle any errors
        }
        ...
        if (baseEventHeader->type ==
            XR_TYPE_EVENT_DATA_SPACE_DISCOVERY_RESULTS_AVAILABLE_META) {
            const XrEventDataSpaceDiscoveryResultsAvailableMETA*
                discoverAnchorResultsAvailable = (XrEventDataSpaceDiscoveryResultsAvailableMETA*)(baseEventHeader);

            XrResult res = XR_SUCCESS;
            XrSpaceDiscoveryResultsMETA discoveryResults{XR_TYPE_SPACE_DISCOVERY_RESULTS_META};
            discoveryResults.resultCapacityInput = 0;
            discoveryResults.resultCountOutput = 0;
            discoveryResults.results = nullptr;

            // Call once to find the number of results (as resultCountOutput).
            res = xrRetrieveSpaceDiscoveryResultsMETA(
                xrSession, discoverAnchorResultsAvailable->requestId, &discoveryResults);
            if (res != XR_SUCCESS) {
                // Handle any errors
            }

            // Call it again to get the actual result objects.
            std::vector<XrSpaceDiscoveryResultMETA> results(discoveryResults.resultCountOutput);
            discoveryResults.resultCapacityInput = results.size();
            discoveryResults.results = results.data();
            res = xrRetrieveSpaceDiscoveryResultsMETA(
                xrSession, discoverAnchorResultsAvailable->requestId, &discoveryResults);
            if (res != XR_SUCCESS) {
                // Handle any errors
            }

            for (auto result : results) {
                // Use the results: App-specific magic
                ...
            }
        } else if (
            baseEventHeader->type == XR_TYPE_EVENT_DATA_SPACE_DISCOVERY_COMPLETE_META) {
            const XrEventDataSpaceDiscoveryCompleteMETA* discoverAnchorComplete =
                (XrEventDataSpaceDiscoveryCompleteMETA*)(baseEventHeader);
            if (discoverAnchorComplete->result < XR_SUCCESS) {
                // Handle any errors
            }
            ...
        }
        ...
    }
}

• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_SESSION_NOT_RUNNING
• XR_SUCCESS

• XR_ERROR_SPACE_INSUFFICIENT_RESOURCES_META: Resource limitation prevented this operation from executing. Recommend retrying, perhaps after a short delay and/or reducing memory consumption.
• XR_ERROR_SPACE_STORAGE_AT_CAPACITY_META: Operation could not be completed until resources used are reduced or storage expanded.
• XR_ERROR_SPACE_INSUFFICIENT_VIEW_META: Look around the environment more for space tracking to function.
• XR_ERROR_SPACE_PERMISSION_INSUFFICIENT_META: Space operation permission insufficient. Recommend confirming the status of the required permissions needed for using Space APIs.
• XR_ERROR_SPACE_RATE_LIMITED_META: Operation cancelled due to rate limiting. Recommend retrying after a short delay.
• XR_ERROR_SPACE_TOO_DARK_META: Environment too dark for tracking to complete operation.
• XR_ERROR_SPACE_TOO_BRIGHT_META: Environment too bright for tracking to complete operation.

• End user enabled local file system access for the application: End users need to have opted-in to let the application access the device’s file system.
• Enhanced Spatial Services: In order for query to retrieve non-local data (for example anchors on Meta’s infrastructure), the discoverer would need to have enabled the Enhanced Spatial Services system-wide permission.

XRAPI_ATTR XrResult XRAPI_CALL xrQuerySpacesFB(
    XrSession session,
    const XrSpaceQueryInfoBaseHeaderFB* info,
    XrAsyncRequestIdFB* requestId
);

• session: A XrSession for the current application instance.
• info: A pointer to the base type of the query information, XrSpaceQueryInfoBaseHeaderFB. See the XrSpaceQueryInfoFB struct.
• requestId: A pointer to the XrAsyncRequestIdFB request ID. This is an out parameter that will be populated by the API call.
• Synchronous Returns: The xrQuerySpacesFB function returns an XrResult indicating the success or failure of triggering the async operation.
• Asynchronous Returns: The async event will be returned as a callback, and the Complete event struct contains another XrResult, indicating the success or failure of the operation as a whole.
• Filters: The xrQuerySpacesFB API is designed to accept a list of filters, subject to certain constraints.
• Linked-List Format: The filters are structured in the form of a linked list of objects utilizing the next* for multi-filter chaining.
• Filter Types: The linked list may contain at most one instance of each of the following filter types:
  • XrSpaceStorageLocationFilterInfoFB the location to retrieve spatial entities from. (To retrieve shared entities, initialize this with the cloud storage location)
  • XrSpaceUuidFilterInfoFB an optional filter for indicating specific spatial entities to be retrieved.
  • XrSpaceGroupUuidFilterInfoMETA an optional filter for indicating specific sharing groups to query. (Please see the Sharing section below for more details on Group Sharing.). Note, if a Group UUID filter is provided with no Space UUID filter, all entities shared with the Group must be successfully retrieved for the Query to succeed.
  • XrSpaceComponentFilterInfoFB
• Batched Operation Support: The XrSpaceUuidFilterInfoFB accepts an array of UUIDs, enabling the API to perform batch operations effectively.
  Note

  To retrieve shared entities, apps must provide at least one `XrSpaceUuidFilterInfoFB` or `XrSpaceGroupUuidFilterInfoMETA`, in addition to an `XrSpaceStorageLocationFilterInfoFB` set to `XR_SPACE_STORAGE_LOCATION_CLOUD_FB`
  Note

  There is a limit to the number of UUIDs the system can accept for any given call, 50.

// Initialize the Storage Location filter to query from Cloud
XrSpaceStorageLocationFilterInfoFB storageLocationFilter = XrSpaceStorageLocationFilterInfoFB{
    XR_TYPE_SPACE_STORAGE_LOCATION_FILTER_INFO_FB, nullptr, XR_SPACE_STORAGE_LOCATION_CLOUD_FB};
XrSpaceFilterInfoBaseHeaderFB* storageLocationFilterPtr =
    reinterpret_cast<XrSpaceFilterInfoBaseHeaderFB*>(&storageLocationFilter);

// Initialize the UUID filter with the spatial entity UUIDs you'd like to query for
XrSpaceUuidFilterInfoFB uuidFilter = XrSpaceUuidFilterInfoFB{
    XR_TYPE_SPACE_UUID_FILTER_INFO_FB,
    nullptr,
    static_cast<uint32_t>(uuids.size()),
    uuids.data()};
XrSpaceFilterInfoBaseHeaderFB* uuidFilterPtr = reinterpret_cast<XrSpaceFilterInfoBaseHeaderFB*>(&uuidFilter);
storageLocationFilterPtr->next = uuidFilterPtr;

XrSpaceQueryInfoFB info = {
    XR_TYPE_SPACE_QUERY_INFO_FB,
    nullptr,
    XR_SPACE_QUERY_ACTION_LOAD_FB,
    maxResultCount,
    0,
    storageLocationFilterPtr,
    nullptr};

XrAsyncRequestIdFB requestId;
XrResult res = xrQuerySpacesFB(openXrSession_, (XrSpaceQueryInfoBaseHeaderFB*)&info, &requestId);
if (res < XrResult::XR_SUCCESS) {
    // Handle Query failed at input validation stage
} else {
    // Async Query operation successfully initiated
}

XRAPI_ATTR XrResult XRAPI_CALL xrRetrieveSpaceQueryResultsFB(
    XrSession session,
    XrAsyncRequestIdFB requestId,
    XrSpaceQueryResultsFB* results
);

• session: A XrSession for the current application instance.
• requestId: The XrAsyncRequestIdFB request ID for which results are being retrieved.
• results: A pointer to the XrSpaceQueryResultsFB struct where the query results will be stored.

XrSpaceQueryInfoFB

• XR_TYPE_SPACE_STORAGE_LOCATION_FILTER_INFO_FB
• XR_TYPE_SPACE_UUID_FILTER_INFO_FB

static const XrStructureType XR_TYPE_SPACE_QUERY_INFO_FB = (XrStructureType)1000156001;
typedef struct XrSpaceQueryInfoFB {
  XrStructureType type;
  const void* XR_MAY_ALIAS next;
  XrSpaceQueryActionFB queryAction;
  uint32_t maxResultCount;
  XrDuration timeout;
  const XrSpaceFilterInfoBaseHeaderFB* filter;
  const XrSpaceFilterInfoBaseHeaderFB* excludeFilter;
} XrSpaceQueryInfoFB;

XrSpaceQueryResultFB

typedef struct XrSpaceQueryResultFB {
  XrSpace space;
  XrUuidEXT uuid;
} XrSpaceQueryResultFB;

XrSpaceQueryResultsFB

static const XrStructureType XR_TYPE_SPACE_QUERY_RESULTS_FB = (XrStructureType)1000156002;
typedef struct XrSpaceQueryResultsFB {
  XrStructureType type;
  const void* XR_MAY_ALIAS next;
  uint32_t resultCapacityInput;
  uint32_t resultCountOutput;
  XrSpaceQueryResultFB* results;
} XrSpaceQueryResultsFB;

static const XrStructureType XR_TYPE_EVENT_DATA_SPACE_QUERY_RESULTS_AVAILABLE_FB =
    (XrStructureType)1000156103;
typedef struct XrEventDataSpaceQueryResultsAvailableFB {
  XrStructureType type;
  const void* XR_MAY_ALIAS next;
  XrAsyncRequestIdFB requestId;
} XrEventDataSpaceQueryResultsAvailableFB;

static const XrStructureType XR_TYPE_EVENT_DATA_SPACE_QUERY_COMPLETE_FB =
    (XrStructureType)1000156104;
typedef struct XrEventDataSpaceQueryCompleteFB {
  XrStructureType type;
  const void* XR_MAY_ALIAS next;
  XrAsyncRequestIdFB requestId;
  XrResult result;
} XrEventDataSpaceQueryCompleteFB;

// Called per-frame
void handleOpenXrAnchorEvents() {
    XrEventDataBuffer eventDataBuffer = {};
    // Poll for events.
    while (true) {
        XrEventDataBaseHeader* baseEventHeader = (XrEventDataBaseHeader*)(&eventDataBuffer);
        baseEventHeader->type = XR_TYPE_EVENT_DATA_BUFFER;
        baseEventHeader->next = nullptr;
        XrResult result = xrPollEvent(instance, &eventDataBuffer);
        if (result != XR_SUCCESS) {
            // Handle any errors
        }
        ...
        if (baseEventHeader->type == XR_TYPE_EVENT_DATA_SPACE_QUERY_COMPLETE_FB) {
            const XrEventDataSpaceQueryCompleteFB* completeEvent =
                (XrEventDataSpaceQueryCompleteFB*)(baseEventHeader);
            if (completeEvent->result < XR_SUCCESS) {
                // Handle any errors
            }
        } else if (baseEventHeader->type == XR_TYPE_EVENT_DATA_SPACE_QUERY_RESULTS_AVAILABLE_FB) {
            const XrEventDataSpaceQueryResultsAvailableFB* querySpacesResultsAvailable =
                (XrEventDataSpaceQueryResultsAvailableFB*)baseEventHeader;

            XrResult res = XR_SUCCESS;
            XrSpaceQueryResultsFB queryResults{XR_TYPE_SPACE_QUERY_RESULTS_FB};
            queryResults.resultCapacityInput = 0;
            queryResults.resultCountOutput = 0;
            queryResults.results = nullptr;

            // First call in the two-call idiom
            res = xrRetrieveSpaceQueryResultsFB(
                openXrSession, querySpacesResultsAvailable->requestId, &queryResults);
            if (res < XR_SUCCESS) {
                // Handle any errors
            }

            // Second call in the two-call idiom
            std::vector<XrSpaceQueryResultFB> results(queryResults.resultCountOutput);
            queryResults.resultCapacityInput = results.size();
            queryResults.results = results.data();
            res = xrRetrieveSpaceQueryResultsFB(
                openXrSession, querySpacesResultsAvailable->requestId, &queryResults);
            if (res < XR_SUCCESS || queryResults.resultCountOutput < results.size()) {
                // Handle any errors
            }

            // Do things with the anchor(s)! Insert App magic here
        }
        ...
    }
}

• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_SESSION_NOT_RUNNING
• XR_SUCCESS

• [Recommended] Group Sharing - Apps can share spatial entities with any app provided “Group UUID”. Other users running the same app can then query for spatial entities shared with the Group UUID. This option does not require integration with Oculus User IDs, and hence should be simpler for developers. This option is provided by the XR_META_spatial_entity_sharing and XR_META_spatial_entity_group_sharing extensions.
• User Sharing - Apps can share spatial entities with specific Oculus User IDs. This option is provided by the XR_FB_spatial_entity_sharing extension and xrShareSpacesFB. Given xrShareSpaceFB’s dependency on XrSpaceUserFB, apps will need to retreive Oculus User IDs and exchange them for this option. For more information on User Sharing, please see the XR_FB_spatial_entity_sharing section below.

• Android manifest permission IMPORT_EXPORT_IOT_MAP_DATA: For more information, see Developer Environment Setup.
• End user enabled Share Point Cloud Data permission: End users need to have opted-in to Share Point Cloud Data with Meta. This is a system-permission and a popup should appear for them.

XRAPI_ATTR XrResult XRAPI_CALL xrShareSpacesMETA(
    XrSession session,
    const XrShareSpacesInfoMETA* info,
    XrAsyncRequestIdFB* requestId
);

• session: The XrSession object representing the current XR session.
• info: A pointer to the XrShareSpacesInfoMETA struct containing the spatial entities to be shared and the recipient to share them with.
• requestId: An XrAsyncRequestIdFB atom that represents the request ID for the share operation for async event handling.
• Synchronous Returns: The xrShareSpacesMETA function returns an XrResult indicating the success or failure of triggering the async operation.
• Asynchronous Returns: The async event will be returned as a callback, and that struct contains another XrResult, indicating the success or failure of the operation as a whole.

XrResult result = xrShareSpacesMETA(session, &info, &requestId);
if (XR_SUCCESS == result) {
    // Share operation was successfully triggered.
} else {
    // Share operation failed to trigger.
}

/**
 * Structure representing the anchor and recipient information used for sharing.
 */
typedef struct XrShareSpacesInfoMETA {
  XrStructureType type; // XR_TYPE_SHARE_SPACES_INFO_META
  const void* XR_MAY_ALIAS next;
  uint32_t spaceCount;
  XrSpace* spaces;
  const XrShareSpacesRecipientBaseHeaderMETA* recipientInfo;
} XrShareSpacesInfoMETA;

/**
 * Group Sharing structure which extends the
 * XrShareSpacesRecipientBaseHeaderMETA base type
 */
typedef struct XrShareSpacesRecipientGroupsMETA {
    XrStructureType type; // XR_TYPE_SHARE_SPACES_RECIPIENT_GROUPS_META
    const void* XR_MAY_ALIAS next;
    uint32_t groupCount;
    XrUuid* groups;
} XrShareSpacesRecipientGroupsMETA;

/**
 * Structure representing the asynchronous event returned by the share operation including an XrResult.
 */
typedef struct XrEventDataShareSpacesCompleteMETA {
  XrStructureType type; // XR_TYPE_EVENT_DATA_SHARE_SPACES_COMPLETE_META
  const void* XR_MAY_ALIAS next;
  XrAsyncRequestIdFB requestId;
  XrResult result;
} XrEventDataShareSpacesCompleteMETA;

• XR_TYPE_EVENT_DATA_SHARE_SPACES_COMPLETE_META

// Called per-frame
void handleOpenXrAnchorEvents() {
    XrEventDataBuffer eventDataBuffer = {};
    // Poll for events.
    while (true) {
        XrEventDataBaseHeader* baseEventHeader = (XrEventDataBaseHeader*)(&eventDataBuffer);
        baseEventHeader->type = XR_TYPE_EVENT_DATA_BUFFER;
        baseEventHeader->next = nullptr;
        XrResult result = xrPollEvent(instance, &eventDataBuffer);
        if (result != XR_SUCCESS) {
            break;
        }
        ...
        if (baseEventHeader->type == XR_TYPE_EVENT_DATA_SHARE_SPACES_COMPLETE_META) {
            const XrEventDataShareSpacesCompleteMETA* shareResult =
                (XrEventDataShareSpacesCompleteMETA*)(baseEventHeader);
            if (shareResult->result < XR_SUCCESS) {
                // Handle errors
            }
            // Optionally communicate the UUID of the shared anchors to the recipients
        }
        ...
    }
}

• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_SESSION_NOT_RUNNING
• XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB
• XR_ERROR_SESSION_LOST
• XR_ERROR_INITIALIZATION_FAILED
• XR_SUCCESS

• XR_SUCCESS
• XR_ERROR_SPACE_CLOUD_STORAGE_DISABLED_FB: Cloud storage is required for this operation but is currently disabled. Ensure that the end-user has Share Point Cloud Data with Meta permission enabled.
• XR_ERROR_SPACE_NETWORK_TIMEOUT_FB: Timeout occurred while waiting for network request to complete.
• XR_ERROR_SPACE_NETWORK_REQUEST_FAILED_FB: The network request failed.
• XR_ERROR_SPACE_MAPPING_INSUFFICIENT_FB: Anchor export from device failed.
• XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB: The required component is not enabled for this space. If the Sharing component is not enabled on an entity and Share is attempted for that entity, this will be returned.

  XR_META_spatial_entity_group_sharing overview

/**
 * Group Sharing structure which extends the
 * XrShareSpacesRecipientBaseHeaderMETA base type
 */
typedef struct XrShareSpacesRecipientGroupsMETA {
    XrStructureType type; // XR_TYPE_SHARE_SPACES_RECIPIENT_GROUPS_META
    const void* XR_MAY_ALIAS next;
    uint32_t groupCount;
    XrUuid* groups;
} XrShareSpacesRecipientGroupsMETA;

XrUuidEXT groupuuid = GenerateRandomGroupUUID();

XrShareSpacesRecipientGroupsMETA recipientGroupInfo = {
    XR_TYPE_SHARE_SPACES_RECIPIENT_GROUPS_META, nullptr};
recipientGroupInfo.groupCount = 1;
recipientGroupInfo.groups = &groupuuid;

XrShareSpacesInfoMETA info = {XR_TYPE_SHARE_SPACES_INFO_META};
info.spaceCount = 1;
info.spaces = &anchor;

info.recipientInfo = (const XrShareSpacesRecipientBaseHeaderMETA*)&recipientGroupInfo;

XrAsyncRequestIdFB requestId;
XrResult res = xrShareSpacesMETA(openXrSession_, &info, &requestId);

• Android manifest permission IMPORT_EXPORT_IOT_MAP_DATA: For more information, see Developer Environment Setup.
• End user enabled Enhanced Spatial Services permission: End users need to have opted into the Enhanced Spatial Services permission when prompted.

XRAPI_ATTR XrResult XRAPI_CALL xrShareSpacesFB(
    XrSession session,
    const XrSpaceShareInfoFB* info,
    XrAsyncRequestIdFB* requestId
);

• session: The XrSession object representing the current XR session.
• info: A pointer to the XrSpaceShareInfoFB struct containing the spatial entities to be shared and the users to share them with.
• requestId: An XrAsyncRequestIdFB atom that represents the request ID for the share operation for async event handling.
• Synchronous Returns: The xrShareSpacesFB function returns an XrResult indicating the success or failure of triggering the async operation.
• Asynchronous Returns: The async event will be returned as a callback, and that struct contains another XrResult, indicating the success or failure of the operation as a whole.

XrResult result = xrShareSpacesFB(session, &info, &requestId);
if (XR_SUCCESS == result)
{
    // Share operation was successfully triggered.
} else {
    // Share operation failed to trigger.
}

/**
 * Structure representing the anchor and user information used for sharing.
 */
typedef struct XrSpaceShareInfoFB {
  XrStructureType type; // XR_TYPE_SPACE_SHARE_INFO_FB
  const void* XR_MAY_ALIAS next;
  uint32_t spaceCount;
  XrSpace* spaces;
  uint32_t userCount;
  XrSpaceUserFB* users;
} XrSpaceShareInfoFB;

/**
 * Structure representing the asynchronous event returned by the share operation including an XrResult.
 */
typedef struct XrEventDataSpaceShareCompleteFB {
  XrStructureType type; // XR_TYPE_EVENT_DATA_SPACE_SHARE_COMPLETE_FB
  const void* XR_MAY_ALIAS next;
  XrAsyncRequestIdFB requestId;
  XrResult result;
} XrEventDataSpaceShareCompleteFB;

• XR_TYPE_EVENT_DATA_SPACE_SHARE_COMPLETE_FB

// Called per-frame
void handleOpenXrAnchorEvents() {
    XrEventDataBuffer eventDataBuffer = {};
    // Poll for events.
    while (true) {
        XrEventDataBaseHeader* baseEventHeader = (XrEventDataBaseHeader*)(&eventDataBuffer);
        baseEventHeader->type = XR_TYPE_EVENT_DATA_BUFFER;
        baseEventHeader->next = nullptr;
        XrResult result = xrPollEvent(instance, &eventDataBuffer);
        if (result != XR_SUCCESS) {
            break;
        }
        ...
        if (baseEventHeader->type == XR_TYPE_EVENT_DATA_SPACE_SHARE_COMPLETE_FB) {
            const XrEventDataSpaceShareCompleteFB* shareResult =
                (XrEventDataSpaceShareCompleteFB*)(baseEventHeader);
            if (shareResult->result < XR_SUCCESS) {
                // Handle errors
            }
            // Optionally communicate the UUID of the shared anchors to the recipients
        }
        ...
    }
}

• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_SESSION_NOT_RUNNING
• XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB
• XR_ERROR_SESSION_LOST
• XR_ERROR_INITIALIZATION_FAILED
• XR_SUCCESS

• XR_ERROR_SPACE_CLOUD_STORAGE_DISABLED_FB: Cloud storage is required for this operation but is currently disabled. Ensure that the end-user has Enhanced Spatial Services permission enabled.
• XR_ERROR_SPACE_NETWORK_TIMEOUT_FB: Timeout occurred while waiting for network request to complete.
• XR_ERROR_SPACE_NETWORK_REQUEST_FAILED_FB: The network request failed.
• XR_ERROR_SPACE_MAPPING_INSUFFICIENT_FB: Anchor export from device failed.
• XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB: The required component is not enabled for this space. If the Sharing component is not enabled on an entity and Share is attempted for that entity, this will be returned.
• XR_SUCCESS

• Initial Synchronous XrResult: This is the XrResult returned directly from the function signature. This XrResult informs whether the API call was initiated successfully or if an issue with the session or input occurred.
• Final Asynchronous XrResult: This is found in the returned struct and indicates the internal operational status. Ideally it should provide informative, actionable details, such as whether the API call needs to be retried.

• Repro Steps
  • Host device: Calls xrShareSpacesMETA to share an Spatial Anchor to a group, or calls xrShareSpacesFB to share an Spatial Anchor to a user.
  • Guest device: Calls xrQuerySpacesFB to query the shared Spatial Anchor.
  • Guest device: May observe that xrQuerySpacesFB does not return the Spatial Anchor shared from the host
• Mitigation To increase the chances of the guest device being able to query the shared Spatial Anchor, follow these steps:
  • On the host device, before calling xrShareSpacesMETA or xrShareSpacesFB, try to have the device move around more in the area where the Spatial Anchor is created.
  • On the guest device, before calling xrQuerySpacesFB, also try to have the device move around more in the area where the host device created the Spatial Anchor.
  By doing so, both devices will map a more complete and accurate spatial data around the same physical area where the Spatial Anchor is created, which can improve the chances of successful Spatial Anchor querying.

• Repro Steps
  • Host device: Calls xrShareSpacesMETA to share an Spatial Anchor to a group, or calls xrShareSpacesFB to share an Spatial Anchor to a user.
  • Guest device: Calls xrQuerySpacesFB to query the shared Spatial Anchor.
  • Guest device: Observes that the orinetation or location of the Spatial Anchor is shifted compared to the one created by the host.
• Mitigation To resolve the misalignment issue, follow these steps on the guest device:
  • On the guest device, go to Settings > Privacy > Device Permissions > Clear Physical Space History
  • On the guest device, restart the app and call xrQuerySpacesFB again. If the Spatial Anchor cannot be queryed in this step, try to restart the guest device, start the app and call xrQuerySpacesFB again.
  By clearing the physical space history and restarting device, you can ensure that the guest device reloads the shared Spatial Anchor with the correct alignment.