Develop

Spatial Anchors OpenXR Reference

This document describes the Spatial Anchors OpenXR API reference.

XR_FB_spatial_entity

Extension Type: Instance Extension

Extension and Version Dependencies: Requires OpenXR 1.0.

Overview

This extension enables applications to place Spatial Anchors that specify world-locked frames of reference. The extension also lets your applications persist real-world content locations over time and contains definitions for the Entity-Component System. All Meta spatial entity extensions are dependent on this extension.

You track a Spatial Anchor by its anchor handle, which generates all the data for the Spatial Anchor. We use OpenXR XrSpace⁠ handles to give applications access to Spatial Anchors. In other words, any operation which involves Spatial Anchors uses XrSpace⁠ handles to identify the affected Spatial Anchors.

This extension allows:

An application to create a Spatial Anchor.

An application to enumerate supported components.

An application to enable or disable a component.

An application to get the status of a component.

New Enum Constants

XrStructureType enumeration is extended with:

XR_TYPE_SPACE_COMPONENT_STATUS_SET_INFO_FB

XR_TYPE_SPACE_COMPONENT_STATUS_FB

XR_TYPE_EVENT_DATA_SPACE__SET_STATUS_COMPLETE_FB

XR_TYPE_EVENT_DATA_SPATIAL_ANCHOR_CREATE_COMPLETE_FB

XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_FB

XR_TYPE_SYSTEM_SPATIAL_ENTITY_PROPERTIES_FB

XrResult enumeration is extended with:

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_STATUS_ALREADY_SET_FB

New Enums

New Enums specify the component interfaces attached to the Spatial Anchor entity.

typedef enum XrSpaceComponentTypeFB {
    XR_SPACE_COMPONENT_TYPE_LOCATABLE_FB = 0,
    XR_SPACE_COMPONENT_TYPE_STORABLE_FB = 1,
    XR_SPACE_COMPONENT_TYPE_MAX_ENUM_FB = 0x7FFFFFFF
} XrSpaceComponentTypeFB;

Enumerant Descriptions

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.

New Structures

XR_FB_spatial_entity contains the following new structures in this release.

XrSystemSpacePropertiesFB

The XrSystemSpacePropertiesFB structure is defined as:

typedef struct XrSystemSpacePropertiesFB {
    XrStructureType             type;
    const void*                 next;
    XrBool32                    supportsSpace;
} XrSystemSpacePropertiesFB;

XrSystemSpatialEntityPropertiesFB describes a Spatial Entity system property (see XrSystemProperties⁠). When the XR_FB_spatial_entity extension is enabled, calling the xrGetSystemProperties⁠ will result in this struct being present in the next chain of the XrSystemProperties struct retrieved.

Member Descriptions

type: The XrStructureType⁠ of this structure.

next: A pointer to the next structure in a structure chain.

supportsSpatialEntity: A boolean value that lets you know if the system supports spatial entities.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity extension prior to using XrSystemSpatialEntityPropertiesFB.

type: Must be XR_TYPE_SYSTEM_SPATIAL_ENTITY_PROPERTIES_FB.

next: Must be NULL or a valid pointer to the next structure in a structure chain.

supportsSpatialEntity: Must be a valid XrBool32⁠ value.

Entity Component System

The entity/component system architectural pattern provides specialization by way of composition instead of inheritance. It thus avoids the type explosion that can occur when multiple entity types share some characteristics but differ in others.

Components represent the interfaces that are available to the anchor. Each anchor has a specific set of components it supports, and enabling these components allows access to the associated operations. Component support and state are unique to each anchor.

Anchors may support any subset of the components given in the XrComponentTypeFB enum. Operations supported on components are:

xrEnumerateSpaceSupportedComponentsFB.

xrSetSpaceComponentStatusFB.

xrGetSpaceComponentStatusFB.

xrEnumerateSpaceSupportedComponentsFB

The xrEnumerateSpaceSupportedComponentsFB function is defined as:

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

Parameter Descriptions

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.

The xrEnumerateSpaceSupportedComponentsFB function discovers any component interfaces that an entity supports. The list of supported components does not change as long as the entity exists. The list of component interfaces available for an entity may depend on which extensions are enabled. Component interfaces are not enumerated unless the corresponding extension that defines them is also enabled.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity extension prior to calling xrEnumerateSpaceSupportedComponentsFB.

space: Must be a valid XrSpace⁠ handle.

Return Codes

Success

XR_SUCCESS

Failure

XR_ERROR_FUNCTION_UNSUPPORTED

XR_ERROR_HANDLE_INVALID

xrSetSpaceComponentStatusFB

The xrSetSpaceComponentStatusFB function is defined as:

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

Parameter Descriptions

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.

The xrSetSpaceComponentStatusFB function enables or disables the specified component for the specified anchor. This operation is asynchronous.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity extension prior to calling xrSetSpaceComponentStatusFB.

space: Must be a valid XrSpace⁠ handle.

XrSpaceComponentStatusSetInfoFB: Must be a pointer to a valid XrSpaceComponentStatusSetInfoFB structure.

Return Codes

Success

XR_SUCCESS

Failure

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

XrSpaceComponentStatusSetInfoFB

The XrSpaceComponentStatusSetInfoFB structure is defined as:

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

Member Descriptions

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.

Valid Usage (Implicit)

type: Must be XR_TYPE_SPACE_COMPONENT_STATUS_SET_INFO_FB.

next: Must be NULL or a valid pointer to the next structure in a structure chain.

componentType: must be a valid XrSpaceComponentTypeFB enumeration.

The xrGetSpaceComponentStatusFB function is defined as:

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

Parameter Descriptions

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.

The xrGetSpaceComponentStatusFB function gets the current status of the specified component for the specified anchor.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity extension prior to calling xrGetSpaceComponentStatusFB.

componentType: Must be a valid XrSpaceComponentTypeFB enumerable.

space: Must be a valid XrSpace⁠ handle.

Return Codes

Success

XR_SUCCESS

Failure

XR_ERROR_FUNCTION_UNSUPPORTED

XR_ERROR_HANDLE_INVALID

xrCreateSpatialAnchorFB

The xrCreateSpatialAnchorFB function is defined as:

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

Parameter Descriptions

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.

The xrCreateSpatialAnchorFB function asynchronously creates a Spatial Anchor using the specified tracking origin and pose, relative to the specified tracking origin. The anchor can be made locatable at creation time, and you can query the 6 DOF pose, relative to the tracking origin, using the LocateSpace method.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity extension prior to calling xrCreateSpatialAnchorFB.

session: Must be a valid XrSession⁠ handle.

info: Must be a pointer to a valid XrSpatialAnchorCreateInfoFB structure.

requestId: Must be a valid XrAsyncRequestIdFB pointer.

Return Codes

Success

XR_SUCCESS

Failure

XR_ERROR_FUNCTION_UNSUPPORTED

XR_ERROR_HANDLE_INVALID

XR_ERROR_VALIDATION_FAILURE

XR_ERROR_RUNTIME_FAILURE

XrSpatialAnchorCreateInfoFB

The XrSpatialAnchorCreateInfoFB structure is defined as:

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

Member Descriptions

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.

Valid Usage (Implicit)

type: Must be XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_FB.

next: Must be NULL or a valid pointer to the next structure in a structure chain.

space: Must be a valid XrSpace handle.

XR_FB_spatial_entity_storage

Extension Type: Instance Extension

Extension and Version Dependencies: Requires OpenXR 1.0 & XR_FB_spatial_entity

Overview

This extension enables Spatial Anchors to be stored and persisted across sessions. If the XR_COMPONENT_TYPE_STORABLE_FB component has been enabled on the spatial entity, application developers may save, load, and erase persisted XrSpaces.

New Enum Constants

XrStructureType⁠ enumeration is extended with:

XR_TYPE_SPACE_SAVE_INFO_FB.

XR_TYPE_SPACE_ERASE_INFO_FB.

XR_TYPE_SPACE_STORAGE_LOCATION_INFO_FB.

XR_TYPE_EVENT_DATA_SPACE_SAVE_COMPLETE_FB.

XR_TYPE_EVENT_DATA_SPACE_ERASE_COMPLETE_FB.

New Enums

The XrSpaceStorageLocationFB enumeration contains the storage locations used to store, load, erase, and query spatial entities.

typedef enum XrSpaceStorageLocationFB {
    XR_SPACE_STORAGE_LOCATION_INVALID_FB = 0,
    XR_SPACE_STORAGE_LOCATION_LOCAL_FB = 1, // local device storage
    XR_SPACE_STORAGE_LOCATION_MAX_ENUM_FB = 0x7FFFFFFF
} XrSpaceStorageLocationFB;

Enumerant Descriptions

XR_SPACE_STORAGE_LOCATION_LOCAL_FB is local device storage

The XrSpacePersistenceModeFB enumeration specifies the persistence mode for the save operation.

typedef enum XrSpacePersistenceModeFB {
    XR_SPACE_STORAGE_PERSISTENCE_MODE_INVALID_FB = 0,
    XR_SPACE_PERSISTENCE_MODE_INDEFINITE_FB = 1,
    XR_SPACE_STORAGE_PERSISTENCE_MODE_MAX_ENUM_FB = 0x7FFFFFFF
} XrSpacePersistenceModeFB;

Enumeration Descriptions

XR_SPACE_PERSISTENCE_MODE_INDEFINITE_FB is persistence with no definite expiration.

New Structures

XR_FB_spatial_entity_storage contains the following new structures in this release.

xrSaveSpaceFB

The xrSaveSpaceFB function persists the Spatial Anchor at the specified location with the specified mode. This operation is asynchronous.

XrResult xrSaveSpaceFB(
    XrSession                   session,
    const XrSpaceSaveInfoFB*    info,
    XrAsyncRequestIdFB*         requestId);

Parameter Descriptions

session: A handle to an XrSession⁠.

info: The location where you want to persist an anchor.

requestId: The output parameter that points to the ID of this asynchronous request.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity_storage extension prior to calling xrSaveSpaceFB.

session: Must be a valid XrSession⁠ handle.

info: Must be a pointer to a valid XrSpaceSaveInfoFB structure.

Events

XR_TYPE_EVENT_DATA_SPACE_SAVE_COMPLETE_FB

Return Codes

Success

XR_SUCCESS

Failure

XR_ERROR_FUNCTION_UNSUPPORTED

XR_ERROR_HANDLE_INVALID

XR_ERROR_VALIDATION_FAILURE

XR_ERROR_RUNTIME_FAILURE

XrSpaceSaveInfoFB

The XrSpaceSaveInfoFB structure contains information used to save the spatial entity.

typedef struct XrSpaceSaveInfoFB {
    XrStructureType                    type;
    const void*                        next;
    XrSpace                            space;
    XrSpaceStorageLocationFB           location;
    XrSpacePersistenceModeFB           persistenceMode;
} XrSpaceSaveInfoFB;

Member Descriptions

type: The XrStructureType⁠ of this structure.

next: Must be NULL or a pointer to the next structure in a structure chain. Core OpenXR does not define such structures.

space: The XrSpace⁠ handle to the reference space that specifies the poseInSpace of the anchor to be defined.

location: The storage location.

persistenceMode: The persistence mode.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity_storage extension prior to calling xrSaveSpaceFB.

XrStructureType: Must be XR_TYPE_SPACE_SAVE_INFO_FB.

next: Not used.

space: Must be a valid XrSpace handle.

location: Must be a valid XrSpaceStorageLocationFB⁠ enumerable.

persistenceMode: Must be a valid XrSpacePersistenceModeFB⁠ enumerable.

xrEraseSpaceFB

The function xrEraseSpaceFB erases a Spatial Anchor from storage at the specified location. This operation is asynchronous. The handle remains valid in memory after the erase operation until you destroy the anchor or the session ends.

XrResult xrEraseSpaceFB(
    XrSession                    session,
    const XrSpaceEraseInfoFB*    info,
    XrAsyncRequestIdFB*          requestId);

Parameter Descriptions

session: A handle to an XrSession⁠.

info: The location to where you want to persist an anchor.

requestId: The output parameter that shows the ID of this asynchronous request.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity_storage extension prior to calling xrEraseSpaceFB.

session: Must be a valid XrSession⁠ handle.

info: Must be a pointer to a valid XrSpaceEraseInfoFB structure.

Events

XR_TYPE_EVENT_DATA_SPACE_ERASE_COMPLETE_FB

Return Codes

Success

XR_SUCCESS

Failure

XR_ERROR_FUNCTION_UNSUPPORTED

XR_ERROR_HANDLE_INVALID

XR_ERROR_VALIDATION_FAILURE

XR_ERROR_RUNTIME_FAILURE

XrSpaceEraseInfoFB

The XrSpaceEraseInfoFB structure contains information used to erase the spatial entity.

typedef struct XrSpaceEraseInfoFB {
    XrStructureType                     type;
    const void*                         next;
    XrSpace                             space;
    XrSpaceStorageLocationFB    location;
} XrSpaceEraseInfoFB;

Member Descriptions

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 that specifies the poseInSpace of the anchor to be defined.

location: is the storage location.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity_storage extension prior to calling xrSaveSpaceFB.

XrStructureType: Must be XR_TYPE_SPACE_ERASE_INFO_FB.

next: Not used.

space: Must be a valid XrSpace handle.

location: Must be a valid XrSpaceStorageLocationFB⁠ enumerable.

XR_FB_spatial_entity_query

Extension Type: Instance Extension

Extension and Version Dependencies: Requires OpenXR 1.0 & XR_FB_spatial_entity

Overview

The XR_FB_spatial_entity_query extension enables an application to discover and restore persistent Spatial Anchors in the area. The application retrieves persistent Spatial Anchors from storage using the query system. The query system consists of filters that define the Spatial Anchor search query and the operation you want to perform on the search results.

New Enum Constants

XrStructureType⁠ enumeration is extended with:

XR_TYPE_SPACE_QUERY_INFO_FB

XR_TYPE_SPACE_QUERY_FILTER_IDS_FB

XR_TYPE_EVENT_DATA_SPACE_QUERY_RESULTS_AVAILABLE_FB

XR_TYPE_EVENT_DATA_SPACE_QUERY_COMPLETE_FB

New Enums

Specify the type of query being performed.

typedef enum XrSpaceQueryActionFB {
    XR_SPACE_QUERY_ACTION_LOAD_FB = 0,
    XR_SPACE_QUERY_ACTION_MAX_ENUM_FB = 0x7FFFFFFF
} XrSpaceQueryActionFB;

Enumerant Descriptions

XR_SPACE_QUERY_ACTION_LOAD_FB — Tells the query to perform a load operation on the XrSpaces returned by the query.

New Structures

XR_FB_spatial_entity_query contains the following new structures in this release.

XrSpaceQueryInfoFB

The XrSpaceQueryInfoFB structure is defined as:

typedef struct XrSpaceQueryInfoFB {
    XrStructureType                       type;
    const void*                           next;
    int32_t                               maxResultCount;
    XrDuration                            timeout;
    XrSpaceQueryActionFB                  queryAction;
    const XrSpaceQueryFilterBaseHeaderFB* filter;
    const XrSpaceQueryFilterBaseHeaderFB* excludeFilter;
} XrSpaceQueryInfoFB;

Member Descriptions

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.

maxResultCount: The maximum number of anchors to be found.

timeout: The number of nanoseconds before the operation should timeout. A value of 0.0 indicates no timeout.

queryAction: The type of query to perform.

filter: Must be NULL or a pointer to a valid XrSpaceQueryFilterBaseHeaderFB structure.

excludeFilter: Must be NULL or a pointer to a valid XrSpaceQueryFilterBaseHeaderFB structure.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity_query extension prior to using XrSpaceQueryInfoFB.

XrStructureType: Must be XR_TYPE_SPACE_QUERY_INFO_FB.

next: Must be NULL or a pointer to the next structure in a structure chain⁠.

maxResultCount: Must be less than or equal to 1024.

queryAction: Must be a valid XrSpaceQueryActionFB.

filter: Must be NULL or a pointer to a valid XrSpaceQueryFilterBaseHeaderFB structure.

excludeFilter: Must be NULL or a pointer to a valid XrSpaceQueryFilterBaseHeaderFB structure.

Example Query for All Available Spatial Anchors

XrSpaceQueryInfoFB queryInfo = {
    XR_TYPE_SPACE_QUERY_INFO_FB,
    nullptr,
    MAX_PERSISTENT_SPACES,
    0,
    XR_SPACE_QUERY_ACTION_LOAD_FB,
    nullptr,
    nullptr};

XrAsyncRequestIdFB requestId;
xrQuerySpacesFB(
    app.Session, (XrSpaceQueryInfoBaseHeaderFB*)&queryInfo, &requestId));

The XrSpaceQueryFilterBaseHeaderFB structure is defined as:

typedef struct XrSpaceQueryFilterBaseHeaderFB {
    XrStructureType    type;
    const void*        next;
} XrSpaceQueryFilterBaseHeaderFB;

XrSpaceQueryFilterBaseHeaderFB

XrSpaceQueryFilterBaseHeaderFB is the base filter struct used with the xrQuerySpacesFB function. Cast the queryInfo param of type XrSpaceQueryInfoFB* to XrSpaceQueryFilterBaseHeaderFB* when passing it to the xrQuerySpacesFB function.

Member Descriptions

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.

XrSpaceUuidFilterInfoFB

The XrSpaceUuidFilterInfoFB structure is a filter you can use to find XrSpaces that match specified UUIDs.

typedef struct XrSpaceUuidFilterInfoFB {
    XrStructureType   type;
    const void*       next;
    uint32_t          uuidCount;
    XrUuidEXT*        uuids;
} XrSpaceUuidFilterInfoFB;

Member Descriptions

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.

uuidCount: The number of UUIDs you want to match.

uuids: A pointer to XrUuidEXT that contains the UUIDs you want to match.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity_query extension prior to using XrSpaceUuidFilterInfoFB.

XrStructureType: Must be XR_TYPE_SPACE_QUERY_FILTER_IDS_FB.

next: Must be NULL or a pointer to the next structure in a structure chain⁠.

XrSpaceQueryInfoBaseHeaderFB

The XrSpaceQueryInfoBaseHeaderFB structure is defined as:

typedef struct XrSpaceQueryInfoBaseHeaderFB {
    XrStructureType    type;
    const void*        next;
} XrSpaceQueryInfoBaseHeaderFB;

XrSpaceQueryInfoBaseHeaderFB is the base filter struct used with the xrQuerySpacesFB function. Cast the queryInfo param of type XrSpaceQueryInfoFB* to XrSpaceQueryFilterBaseHeaderFB* when passing it to the xrQuerySpacesFB function.

Member Descriptions

type: is 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.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity_query extension prior to using XrSpaceQueryInfoBaseHeaderFB.

XrStructureType: Must be XR_TYPE_SPACE_QUERY_INFO_FB.

next: Must be NULL or a pointer to the next structure in a structure chain⁠.

xrQuerySpacesFB

The function xrQuerySpacesFB enables your application to find and retrieve Spatial Anchors from storage. Cast a reference to an instance of the XrSpaceQueryInfoFB structure to XrSpaceQueryInfoBaseHeaderFB* when passing into the query function and structuring the query filters. This operation is asynchronous.

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

Parameter Descriptions

session: A handle to an XrSession⁠.

info: A pointer to the XrSpaceQueryInfoBaseHeaderFB structure.

requestId: The output parameter that points to the ID of this asynchronous request.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity_query extension prior to calling xrQuerySpacesFB.

session: Must be a valid XrSession⁠ handle.

info: Must be a pointer to a valid XrSpaceQueryInfoBaseHeaderFB structure.

Events

XR_TYPE_EVENT_DATA_SPACE_QUERY_RESULTS_AVAILABLE_FB contains the requestId of the query and triggers once results are available for the query.

XR_TYPE_EVENT_DATA_SPACE_QUERY_COMPLETE_FB contains the requestId of the query and triggers when the query is complete.

Return Codes

Success

XR_SUCCESS

Failure

XR_ERROR_FUNCTION_UNSUPPORTED

XR_ERROR_VALIDATION_FAILURE

XR_ERROR_HANDLE_INVALID

xrRetrieveSpaceQueryResultsFB

The xrRetrieveSpaceQueryResultsFB function allows an application to retrieve all available results for a specified query. This function must only retrieve each query result once. After the application has used this function to retrieve a query result, the runtime frees its copy. Call this function once to get the number of results found and then once more to copy the results into a buffer provided by the application.

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

Parameter Descriptions

session: A handle to an XrSession⁠.

requestId: The output parameter that points to the ID of this asynchronous request.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity_query extension prior to calling xrRetrieveSpaceQueryResultsFB.

session: Must be a valid XrSession⁠ handle.

**results: **Must be a valid XrSpaceQueryResultsFB struct.

XrSpaceQueryResultsFB

The XrSpaceQueryResultsFB structure is defined as:

typedef struct XrSpaceQueryResultsFB {
    XrStructureType                type;
    const void*                    next;
    uint32_t                       requestId;
    uint32_t                       resultCountOutput;
    XrSpaceQueryResultFB*          results;
} XrSpaceQueryResultsFB;

Member Descriptions

type: The XrStructureType of this structure.

next: Must be NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.

resultCapacityInput: The capacity of the results array, or 0 to indicate a request to retrieve the required capacity.

resultCountOutput: An output parameter containing the count of results retrieved, or returns the required capacity in the case that resultCapacityInput is 0.

results: A pointer to an array of results, but can be NULL if resultCapacityInput is 0.

See the <<buffer-size-parameters, Buffer Size Parameters>> chapter for a detailed description of retrieving the required results size.

XrEventDataSpaceQueryResultsAvailableFB

The XrEventDataSpaceQueryResultsAvailableFB structure indicates results are available for the requestId associated with the xrQuerySpacesFB request:

typedef struct XrEventDataSpaceQueryResultsAvailableFB {
    XrStructureType                type;
    const void*                    next;
    XrAsyncRequestIdFB             requestId;
} XrEventDataSpaceQueryResultsAvailableFB;

Member Descriptions

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.

requestId: The ID of this asynchronous request.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity_query extension prior to using XrEventDataSpaceQueryResultsAvailableFB.

XrStructureType must be XR_TYPE_EVENT_DATA_SPACE_QUERY_RESULTS_AVAILABLE_FB.

next: Must be NULL or a pointer to the next structure in a structure chain⁠.

XrSpaceQueryResultFB

The XrSpaceQueryResultFB structure is used by the **xrRetrieveSpaceQueryResultsFB **function to retrieve query results.

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

Member Descriptions

space: The XrSpace⁠ handle to the anchor found by the query.

uuid: The UUID that identifies the space.

Valid Usage (Implicit)

You must enable the XR_FB_spatial_entity_query extension prior to using XrSpaceQueryResultFB.

About us

Virtual reality / Meta Horizon

Meta Horizon Creator Program

Discover

Why Meta Quest?

What is mixed reality?

Platforms and tools

2D apps for Meta Horizon OS

Support and legal

About us

Virtual reality / Meta Horizon

Meta Horizon Creator Program

Discover

Why Meta Quest?

What is mixed reality?

Platforms and tools

2D apps for Meta Horizon OS

Support and legal

About us

Virtual reality / Meta Horizon

Meta Horizon Creator Program

Discover

Why Meta Quest?

What is mixed reality?

Platforms and tools

2D apps for Meta Horizon OS

Support and legal

English (US)