XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

Type d'extension

Extension d'instance

Numéro d'extension enregistré

798

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

XR_ANDROID_geospatial
et
XR_EXT_future
et
XR_EXT_spatial_entity
et
XR_EXT_spatial_anchor

Date de dernière modification

2025-10-30

État de l'adresse IP

Aucune réclamation de propriété intellectuelle connue.

Participants

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

Présentation

Cette extension fournit des ancres géospatiales et des ancres de surface qui s'appuient sur l'extension Geospatial de base. Les ancres géospatiales sont des ancres positionnées dans l'espace par rapport à la Terre à une latitude, une longitude et une altitude données. Les ancres de surface sont des ancres relatives à la Terre qui sont placées à une latitude, une longitude et une altitude données par rapport à une surface connue par le service de positionnement visuel. À mesure que la précision de la position de l'environnement d'exécution par rapport à la Terre s'améliore, la position de l'ancre s'ajuste en conséquence.

Capacité du système pour les ancres géospatiales

La structure XrSystemGeospatialAnchorPropertiesANDROID est définie comme suit :

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
• maxSurfaceAnchorCount est un uint32_t indiquant le nombre maximal d'ancres de surface qui peuvent être créées.

Une application peut inspecter les fonctionnalités d'ancrage géospatial du système en associant une structure XrSystemGeospatialAnchorPropertiesANDROID à XrSystemProperties lors de l'appel de xrGetSystemProperties .

Si XrSystemGeospatialPropertiesANDROID :: supportsGeospatial est XR_TRUE , alors maxSurfaceAnchorCount indique le nombre maximal d'ancres de surface que l'environnement d'exécution accepte. Dans ce cas, la limite doit être supérieure à 0.

Si XrSystemGeospatialPropertiesANDROID :: supportsGeospatial n'est pas XR_TRUE , alors maxSurfaceAnchorCount doit être égal à 0.

Utilisation valide (implicite)

•  L'extension XR_ANDROID_geospatial_anchor doit être activée avant d'utiliser XrSystemGeospatialAnchorPropertiesANDROID.
• type doit être XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures

Suivi des plans pour les ancres

La structure XrGeospatialTrackerAnchorTrackingInfoANDROID est définie comme suit :

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• shouldTrackPlanes est une valeur XrBool32 indiquant si le traceur géospatial suivra les plans pour améliorer le positionnement des ancres verrouillées sur la surface.

Le suivi des plans peut être activé pour améliorer le positionnement des ancres verrouillées sur une surface.

Si l'application souhaite activer le suivi des plans pour améliorer les positions des ancres de surface, elle peut associer une structure XrGeospatialTrackerAnchorTrackingInfoANDROID à XrGeospatialTrackerCreateInfoANDROID lors de l'appel de xrCreateGeospatialTrackerANDROID .

Utilisation valide (implicite)

• L'extension XR_ANDROID_geospatial_anchor doit être activée avant d'utiliser XrGeospatialTrackerAnchorTrackingInfoANDROID.
• type doit être XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures

Ancres géospatiales

La fonction xrCreateGeospatialAnchorANDROID est définie comme suit :

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

Description des paramètres

• spatialContext est le XrSpatialContextEXT dans lequel créer l'ancrage. Le contexte doit être configuré pour XR_SPATIAL_CAPABILITY_ANCHOR_EXT, sinon l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE .
• createInfo est un pointeur vers XrGeospatialAnchorCreateInfoANDROID contenant les paramètres de création de l'ancre.
• anchorEntityId est un pointeur vers XrSpatialEntityIdEXT dans lequel l'ID de l'entité d'ancrage est renvoyé.

Si l'XrGeospatialTrackerANDROID spécifié dans XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker n'est pas à l'état XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, l'environnement d'exécution doit renvoyer XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

Utilisation valide (implicite)

• L'extension XR_ANDROID_geospatial_anchor doit être activée avant d'appeler xrCreateGeospatialAnchorANDROID.
• spatialContext doit être un handle XrSpatialContextEXT valide
• createInfo doit être un pointeur vers une structure XrGeospatialAnchorCreateInfoANDROID valide
• anchorEntityId doit être un pointeur vers une valeur XrSpatialEntityIdEXT

Codes renvoyés

Opération réussie

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Échec

• 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_POSE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_VALIDATION_FAILURE

La structure XrGeospatialAnchorCreateInfoANDROID est définie comme suit :

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• geospatialTracker est l'élément XrGeospatialTrackerANDROID à utiliser pour créer l'ancre.
• geospatialPose est un pointeur vers XrGeospatialPoseANDROID définissant l'emplacement et l'orientation de l'ancre.

Utilisation valide (implicite)

• L'extension XR_ANDROID_geospatial_anchor doit être activée avant d'utiliser XrGeospatialAnchorCreateInfoANDROID.
• type doit être XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures
• geospatialTracker doit être un handle XrGeospatialTrackerANDROID valide
• geospatialPose doit être une structure XrGeospatialPoseANDROID valide

Ancres de surface

Les ancrages de surface sont des ancrages placés par rapport à une surface, comme un terrain ou un toit.

L'énumération XrSurfaceAnchorTypeANDROID est définie comme suit :

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;

L'énumération XrSurfaceAnchorTypeANDROID spécifie le type de surface auquel une ancre est associée.

Les énumérants ont les valeurs suivantes :

Description de l'enum

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Type d'ancrage placé par rapport au sol.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Type d'ancrage placé par rapport au toit ou au sol s'il n'y a pas de bâtiment.

La fonction xrCreateSurfaceAnchorAsyncANDROID est définie comme suit :

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

Description des paramètres

• spatialContext est le XrSpatialContextEXT dans lequel créer l'ancrage.
• createInfo est un pointeur vers XrSurfaceAnchorCreateInfoANDROID contenant les paramètres de création de l'ancrage.
• future est un pointeur vers XrFutureEXT qui contiendra le résultat de l'opération asynchrone.

La fonction xrCreateSurfaceAnchorAsyncANDROID lance une opération asynchrone pour créer une ancre de surface. Contrairement aux ancres géospatiales standards, l'environnement d'exécution peut récupérer des données de terrain pour déterminer l'altitude correcte. L'environnement d'exécution doit renvoyer XR_ERROR_LIMIT_REACHED si l'application tente de créer plus de XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount ancres de surface à la fois. Si l'élément XrGeospatialTrackerANDROID spécifié dans XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker n'est pas à l'état XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, l'environnement d'exécution doit renvoyer XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . L'opération peut échouer de manière asynchrone avec le résultat XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID s'il n'existe aucune donnée de surface pour l'emplacement donné. L'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE si XR_SPATIAL_CAPABILITY_ANCHOR_EXT n'a pas été configuré pour spatialContext .

Utilisation valide (implicite)

• L'extension XR_ANDROID_geospatial_anchor doit être activée avant d'appeler xrCreateSurfaceAnchorAsyncANDROID.
• spatialContext doit être un handle XrSpatialContextEXT valide
• createInfo doit être un pointeur vers une structure XrSurfaceAnchorCreateInfoANDROID valide.
• future doit être un pointeur vers une valeur XrFutureEXT

Codes renvoyés

Opération réussie

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Échec

• 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_POSE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_VALIDATION_FAILURE

La structure XrSurfaceAnchorCreateInfoANDROID est définie comme suit :

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• geospatialTracker est le XrGeospatialTrackerANDROID à utiliser.
• surfaceAnchorType est le XrSurfaceAnchorTypeANDROID de l'ancre.
• eastUpSouthOrientation est l'orientation par rapport à un système de coordonnées où +X=Est, +Y=Haut et +Z=Sud.
• latitude est la latitude en degrés, comprise entre -89,9 et +89,9.
• longitude est la longitude en degrés, comprise entre -180 et +180.
• altitudeRelativeToSurface est l'altitude en mètres par rapport à la surface spécifiée par surfaceAnchorType .

Utilisation valide (implicite)

• L'extension XR_ANDROID_geospatial_anchor doit être activée avant d'utiliser XrSurfaceAnchorCreateInfoANDROID.
• type doit être XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures
• geospatialTracker doit être un handle XrGeospatialTrackerANDROID valide
• surfaceAnchorType doit être une valeur XrSurfaceAnchorTypeANDROID valide
• latitude doit être une valeur double valide
• longitude doit être une valeur double valide
• altitudeRelativeToSurface doit être une valeur double valide

La fonction xrCreateSurfaceAnchorCompleteANDROID est définie comme suit :

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

Description des paramètres

• spatialContext est le XrSpatialContextEXT utilisé pour la création.
• future est le XrFutureEXT renvoyé par xrCreateSurfaceAnchorAsyncANDROID .
• completion est un pointeur vers XrSurfaceAnchorCreateCompletionANDROID qui reçoit le résultat.

Utilisation valide (implicite)

•  L'extension XR_ANDROID_geospatial_anchor doit être activée avant d'appeler xrCreateSurfaceAnchorCompleteANDROID.
• spatialContext doit être un handle XrSpatialContextEXT valide
• completion doit être un pointeur vers une structure XrSurfaceAnchorCreateCompletionANDROID.

Codes renvoyés

Opération réussie

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Échec

• 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

La structure XrSurfaceAnchorCreateCompletionANDROID contient le résultat d'une création d'ancrage de surface asynchrone.

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• futureResult est le XrResult de l'opération de création. Si futureResult est XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , une structure de la chaîne next peut fournir plus d'informations sur l'échec.
• anchorEntityId est l'XrSpatialEntityIdEXT de l'ancre créée, ou XR_NULL_SPATIAL_ENTITY_ID_EXT si futureResult n'est pas XR_SUCCESS .

Codes de retour futurs

Valeurs de futureResult :

Opération réussie

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Échec

• 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

Utilisation valide (implicite)

• L'extension XR_ANDROID_geospatial_anchor doit être activée avant d'utiliser XrSurfaceAnchorCreateCompletionANDROID.
• type doit être XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures
• futureResult doit être une valeur XrResult valide

Exemple

Créer une ancre de terrain

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.
}

Nouvelles commandes

• xrCreateGeospatialAnchorANDROID
• xrCreateSurfaceAnchorAsyncANDROID
• xrCreateSurfaceAnchorCompleteANDROID

Nouvelles structures

• XrGeospatialAnchorCreateInfoANDROID
• XrSurfaceAnchorCreateCompletionANDROID
• XrSurfaceAnchorCreateInfoANDROID

• Extension de XrGeospatialTrackerCreateInfoANDROID :

  • XrGeospatialTrackerAnchorTrackingInfoANDROID

• Extension de XrSystemProperties :

  • XrSystemGeospatialAnchorPropertiesANDROID

Nouvelles énumérations

• XrSurfaceAnchorTypeANDROID

Nouvelles constantes d'énumération

• XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
• XR_ANDROID_geospatial_anchor_SPEC_VERSION

• Extension de XrResult :

  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID

• Extension de 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

Problèmes

L'historique des versions

• Révision 1, 30/10/2025 (Ben King)

  • Suggestion initiale.