XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

Extension Type

Instance extension

Registered Extension Number

798

Revision

1

Ratification Status

Not ratified

Extension and Version Dependencies

XR_ANDROID_geospatial
and
XR_EXT_future
and
XR_EXT_spatial_entity
and
XR_EXT_spatial_anchor

Last Modified Date

2025-10-30

IP Status

No known IP claims.

Contributors

John Ullman, Google
Ben King, Google
Nihav Jain, Google
Jared Finder, Google

Overview

This extension provides Geospatial Anchors and Surface Anchors that build on the base Geospatial extension. Geospatial Anchors are anchors that are positioned in space relative to the Earth at a given latitude, longitude and altitude. Surface Anchors are Earth-relative anchors which are placed at a given latitude, longitude, and altitude relative to a surface as known by the Visual Positioning Service. As the runtime’s accuracy of its position relative to the Earth improves, the Anchor’s pose will adjust accordingly.

System Capability for Geospatial Anchors

The XrSystemGeospatialAnchorPropertiesANDROID structure is defined as:

typedef struct XrSystemGeospatialAnchorPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSurfaceAnchorCount;
} XrSystemGeospatialAnchorPropertiesANDROID;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • maxSurfaceAnchorCount is a uint32_t indicating the maximum number of surface anchors that can be created.

An application can inspect geospatial anchor capabilities of the system by chaining an XrSystemGeospatialAnchorPropertiesANDROID structure to the XrSystemProperties when calling xrGetSystemProperties .

If XrSystemGeospatialPropertiesANDROID :: supportsGeospatial is XR_TRUE , then maxSurfaceAnchorCount indicates the maximum number of surface anchors the runtime supports. The limit must be greater than 0 in this case.

If XrSystemGeospatialPropertiesANDROID :: supportsGeospatial is not XR_TRUE , then maxSurfaceAnchorCount must be 0.

Valid Usage (Implicit)

Plane Tracking for Anchors

The XrGeospatialTrackerAnchorTrackingInfoANDROID structure is defined as:

typedef struct XrGeospatialTrackerAnchorTrackingInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrBool32           shouldTrackPlanes;
} XrGeospatialTrackerAnchorTrackingInfoANDROID;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • shouldTrackPlanes is an XrBool32 indicating if the geospatial tracker will track planes to improve positioning of surface-locked anchors.

Plane tracking can be enabled to improve positioning of surface-locked anchors.

If the application wants to enable plane tracking to improve surface anchor poses, it can chain an XrGeospatialTrackerAnchorTrackingInfoANDROID structure to XrGeospatialTrackerCreateInfoANDROID when calling xrCreateGeospatialTrackerANDROID .

Valid Usage (Implicit)

Geospatial Anchors

The xrCreateGeospatialAnchorANDROID function is defined as:

XrResult xrCreateGeospatialAnchorANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrGeospatialAnchorCreateInfoANDROID*  createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId);

Parameter Descriptions

  • spatialContext is the XrSpatialContextEXT to create the anchor in. The context must be configured for XR_SPATIAL_CAPABILITY_ANCHOR_EXT otherwise the runtime must return XR_ERROR_VALIDATION_FAILURE .
  • createInfo is a pointer to XrGeospatialAnchorCreateInfoANDROID containing anchor creation parameters.
  • anchorEntityId is a pointer to XrSpatialEntityIdEXT in which the anchor entity ID is returned.

If the XrGeospatialTrackerANDROID specified in XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker is not in the XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID state, the runtime must return XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

Valid Usage (Implicit)

Return Codes

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

The XrGeospatialAnchorCreateInfoANDROID structure is defined as:

typedef struct XrGeospatialAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrGeospatialPoseANDROID       geospatialPose;
} XrGeospatialAnchorCreateInfoANDROID;

Member Descriptions

Valid Usage (Implicit)

Surface Anchors

Surface anchors are anchors placed relative to a surface, such as terrain or rooftops.

The XrSurfaceAnchorTypeANDROID enumeration is defined as:

typedef enum XrSurfaceAnchorTypeANDROID {
    XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID = 1,
    XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID = 2,
    XR_SURFACE_ANCHOR_TYPE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSurfaceAnchorTypeANDROID;

The XrSurfaceAnchorTypeANDROID enumeration specifies the type of surface an anchor is relative to.

The enumerants have the following values:

Enum Description

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Type of an anchor placed relative to the ground.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Type of an anchor placed relative to the rooftop, or ground where there is no building.

The xrCreateSurfaceAnchorAsyncANDROID function is defined as:

XrResult xrCreateSurfaceAnchorAsyncANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSurfaceAnchorCreateInfoANDROID*     createInfo,
    XrFutureEXT*                                future);

Parameter Descriptions

  • spatialContext is the XrSpatialContextEXT to create the anchor in.
  • createInfo is a pointer to XrSurfaceAnchorCreateInfoANDROID containing anchor creation parameters.
  • future is a pointer to XrFutureEXT that will hold the result of the asynchronous operation.

The xrCreateSurfaceAnchorAsyncANDROID function begins an asynchronous operation to create a surface anchor. Unlike standard geospatial anchors, the runtime may fetch terrain data to determine the correct altitude. The runtime must return XR_ERROR_LIMIT_REACHED if the application attempts to create more than XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount surface anchors at a time. If the XrGeospatialTrackerANDROID specified in XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker is not in the XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID state, the runtime must return XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . The operation may fail asynchronously with result XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID if there is no surface data for the given location. The runtime must return XR_ERROR_VALIDATION_FAILURE if XR_SPATIAL_CAPABILITY_ANCHOR_EXT was not configured for spatialContext .

Valid Usage (Implicit)

Return Codes

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

The XrSurfaceAnchorCreateInfoANDROID structure is defined as:

typedef struct XrSurfaceAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrSurfaceAnchorTypeANDROID    surfaceAnchorType;
    XrQuaternionf                 eastUpSouthOrientation;
    double                        latitude;
    double                        longitude;
    double                        altitudeRelativeToSurface;
} XrSurfaceAnchorCreateInfoANDROID;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • geospatialTracker is the XrGeospatialTrackerANDROID to use.
  • surfaceAnchorType is the XrSurfaceAnchorTypeANDROID for the anchor.
  • eastUpSouthOrientation is the orientation with respect to a coordinate system where +X=East, +Y=Up and +Z=South.
  • latitude is the latitude in degrees, between -89.9 and +89.9.
  • longitude is the longitude in degrees, between -180 and +180.
  • altitudeRelativeToSurface is the altitude in meters relative to the surface specified by surfaceAnchorType .

Valid Usage (Implicit)

The xrCreateSurfaceAnchorCompleteANDROID function is defined as:

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     completion);

Parameter Descriptions

Valid Usage (Implicit)

Return Codes

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

The XrSurfaceAnchorCreateCompletionANDROID structure holds the result of an asynchronous surface anchor creation.

typedef struct XrSurfaceAnchorCreateCompletionANDROID {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSurfaceAnchorCreateCompletionANDROID;

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 creation operation. If futureResult is XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , a structure in the next chain may provide more information about the failure.
  • anchorEntityId is the XrSpatialEntityIdEXT of the created anchor, or XR_NULL_SPATIAL_ENTITY_ID_EXT if futureResult is not XR_SUCCESS .

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_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Valid Usage (Implicit)

Example

Create Terrain Anchor

PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
PFN_xrCreateSurfaceAnchorAsyncANDROID xrCreateSurfaceAnchorAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCreateSurfaceAnchorCompleteANDROID xrCreateSurfaceAnchorCompleteANDROID;
XrInstance instance;
XrSession session;
XrGeospatialTrackerANDROID geospatialTracker;

// Create a spatial context
XrSpatialContextEXT spatialContext{};
{
  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  XrSpatialCapabilityConfigurationAnchorEXT
       anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  // ... wait until future is ready ...

  XrCreateSpatialContextCompletionEXT contextCompletion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &contextCompletion));
  if (contextCompletion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = contextCompletion.spatialContext;
}

XrSurfaceAnchorCreateInfoANDROID anchorCreateInfo{
    XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID};
anchorCreateInfo.surfaceAnchorType = XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID;
anchorCreateInfo.eastUpSouthOrientation = {0, 0, 0, 1};
anchorCreateInfo.latitude = 37.7749;
anchorCreateInfo.longitude = -122.4194;
anchorCreateInfo.altitudeRelativeToSurface = 0;
anchorCreateInfo.geospatialTracker = geospatialTracker;
XrFutureEXT anchorFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSurfaceAnchorAsyncANDROID(spatialContext, &anchorCreateInfo, &anchorFuture));

XrFuturePollInfoEXT anchorPollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT anchorPollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
anchorPollInfo.future = anchorFuture;
anchorPollResult.state = XR_FUTURE_STATE_PENDING_EXT;
while (anchorPollResult.state == XR_FUTURE_STATE_PENDING_EXT) {
  // Do in render loop/state loop.
  CHK_XR(xrPollFutureEXT(instance, &anchorPollInfo, &anchorPollResult));
}

XrSurfaceAnchorCreateCompletionANDROID anchorCompletion{
    XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID};
CHK_XR(xrCreateSurfaceAnchorCompleteANDROID(spatialContext, anchorFuture, &anchorCompletion));
if (anchorCompletion.futureResult == XR_SUCCESS) {
  // Use completion.anchorEntityId.
  XrSpatialEntityIdEXT anchorId = anchorCompletion.anchorEntityId;

  // Query in UpdateSnapshot.
}

New Commands

New Structures

New Enums

New Enum Constants

  • XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_geospatial_anchor_SPEC_VERSION

  • Extending XrResult :

    • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID

  • Extending XrStructureType :

    • XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID

Issues

Version History

  • Revision 1, 2025-10-30 (Ben King)

    • Initial draft.