XR_ANDROID_geospatial_anchor

Chaîne de nom

XR_ANDROID_geospatial_anchor

Type d'extension

Extension d'instance

Numéro d'extension enregistré

798

Révision

1

État de 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 la propriété intellectuelle

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

Contributeurs

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 géospatiale 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, telles qu'elles sont connues par le service de positionnement visuel. À mesure que la précision de l'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 correspond au 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 le noyau OpenXR ni dans cette extension.
• maxSurfaceAnchorCount est un uint32_t indiquant le nombre maximal d'ancres de surface pouvant être créées.

Une application peut inspecter les capacités d’ancrage géospatial du système en chaînant 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 compatibles avec l'exécution. 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 correspond au XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• shouldTrackPlanes est un XrBool32 indiquant si le tracker géospatial suivra les plans pour améliorer le positionnement des ancres verrouillées en surface.

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

Si l'application souhaite activer le suivi des plans pour améliorer les positions des ancres de surface, elle peut chaîner 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);

Descriptions des paramètres

• spatialContext correspond au XrSpatialContextEXT dans lequel créer l'ancre. Le contexte doit être configuré pour XR_SPATIAL_CAPABILITY_ANCHOR_EXT. Sinon, l'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 d'entité d'ancre est renvoyé.

Si le XrGeospatialTrackerANDROID spécifié dans XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker n'est pas dans l'état XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, l'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 descripteur 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

L'é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_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 correspond au XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• geospatialTracker correspond au 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 descripteur XrGeospatialTrackerANDROID valide.
• geospatialPose doit être une structure XrGeospatialPoseANDROID valide.

Ancres de surface

Les ancres de surface sont des ancres placées 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 par rapport auquel une ancre est placée.

Les énumérants ont les valeurs suivantes :

Description de l'enum

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Type d'ancre placée par rapport au sol.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Type d'ancre placée par rapport au toit ou au sol en l'absence de bâtiment.

La fonction xrCreateSurfaceAnchorAsyncANDROID est définie comme suit :

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

Descriptions des paramètres

• spatialContext correspond au XrSpatialContextEXT dans lequel créer l'ancre.
• createInfo est un pointeur vers XrSurfaceAnchorCreateInfoANDROID contenant les paramètres de création de l'ancre.
• 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'exécution peut récupérer des données de terrain pour déterminer l'altitude correcte. L'exécution doit renvoyer XR_ERROR_LIMIT_REACHED si l'application tente de créer plus d'ancres de surface que XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount à la fois. Si le XrGeospatialTrackerANDROID spécifié dans XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker n'est pas dans l'état XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, l'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 si aucune donnée de surface n'est disponible pour l'emplacement donné. L'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 descripteur 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

L'é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_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 correspond au XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• geospatialTracker correspond au XrGeospatialTrackerANDROID à utiliser.
• surfaceAnchorType correspond au XrSurfaceAnchorTypeANDROID de l'ancre.
• eastUpSouthOrientation correspond à l'orientation par rapport à un système de coordonnées où +X=Est, +Y=Haut et +Z=Sud.
• latitude correspond à la latitude en degrés, entre -89,9 et +89,9.
• longitude correspond à la longitude en degrés, entre -180 et +180.
• altitudeRelativeToSurface correspond à 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 descripteur 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);

Descriptions des paramètres

• spatialContext correspond au XrSpatialContextEXT utilisé pour la création.
• future correspond au 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 descripteur XrSpatialContextEXT valide.
• completion doit être un pointeur vers une structure XrSurfaceAnchorCreateCompletionANDROID.

Codes renvoyés

Opération réussie

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

L'é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 asynchrone d'ancre de surface.

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

Descriptions des membres

• type correspond au XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• futureResult correspond au 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 correspond au XrSpatialEntityIdEXT de l'ancre créée, ou à XR_NULL_SPATIAL_ENTITY_ID_EXT si futureResult n'est pas XR_SUCCESS .

Codes renvoyés futurs

Valeurs futureResult :

Opération réussie

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

L'é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 enums

• XrSurfaceAnchorTypeANDROID

Nouvelles constantes d'enum

• 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

Historique des versions

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

  • Suggestion initiale.