XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

Type d'extension

Extension d'instance

Numéro d'extension enregistré

790

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

XR_EXT_future

Date de dernière modification

2025-12-18

É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 le suivi géospatial pour l'API Geospatial de Google, qui fournit une géolocalisation et une orientation précises, et permet à l'application de placer du contenu par rapport à la Terre. Pour ce faire, elle combine le suivi du mouvement, le GPS et d'autres capteurs, ainsi que le système de positionnement visuel (VPS) de Google. Le VPS compare les images de l'appareil photo d'un appareil aux images Street View afin de déterminer une position exacte et une orientation précises. L'API Geospatial fournit souvent une précision de positionnement inférieure au mètre (bien meilleure que le GPS) et une précision d'orientation inférieure au degré.

Pour utiliser correctement les API de cette extension (autrement que pour vérifier la compatibilité de l'extension), l'application doit avoir défini des identifiants d'authentification via un mécanisme tel que XR_ANDROID_google_cloud_auth . Pour en savoir plus sur la configuration et les résultats d'erreur, consultez la documentation de l'extension d'authentification.

Autorisations

Les applications Android doivent inclure l'autorisation android.permission.ACCESS_FINE_LOCATION dans leur fichier manifeste pour utiliser cette extension. L'autorisation android.permission.ACCESS_FINE_LOCATION est considérée comme dangereuse. L'application doit demander l'autorisation au moment de l'exécution pour utiliser ces fonctions :

(niveau de protection : dangereux)

Inspecter les capacités du système

La structure XrSystemGeospatialPropertiesANDROID est définie comme suit :

typedef struct XrSystemGeospatialPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGeospatial;
} XrSystemGeospatialPropertiesANDROID;

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.
  • supportsGeospatial est un XrBool32 qui indique si le système actuel est compatible avec les fonctionnalités géospatiales.

Une application peut vérifier si le système est compatible avec les fonctionnalités géospatiales en associant une structure XrSystemGeospatialPropertiesANDROID à XrSystemProperties lors de l'appel de xrGetSystemProperties .

Si un environnement d'exécution renvoie XR_FALSE pour supportsGeospatial, le système n'est pas compatible avec les fonctionnalités géospatiales et doit donc renvoyer XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateGeospatialTrackerANDROID . L'application doit éviter d'utiliser la fonctionnalité géospatiale lorsque supportsGeospatial est défini sur XR_FALSE .

Utilisation valide (implicite)

Créer un handle de suivi géospatial

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

La fonction xrCreateGeospatialTrackerANDROID est définie comme suit :

XrResult xrCreateGeospatialTrackerANDROID(
    XrSession                                   session,
    const XrGeospatialTrackerCreateInfoANDROID* createInfo,
    XrGeospatialTrackerANDROID*                 geospatialTrackerOutput);

Description des paramètres

Une application peut créer un handle XrGeospatialTrackerANDROID en appelant xrCreateGeospatialTrackerANDROID . Le handle XrGeospatialTrackerANDROID renvoyé peut ensuite être utilisé dans les appels d'API. Si l'application n'a pas obtenu les autorisations requises, l'environnement d'exécution doit renvoyer XR_ERROR_PERMISSION_INSUFFICIENT . Il ne peut exister qu'un seul XrGeospatialTrackerANDROID à la fois pour une XrSession donnée. L'application doit s'assurer que tous les objets XrGeospatialTrackerANDROID précédents ont été détruits avant d'appeler à nouveau cette fonction. Sinon, l'environnement d'exécution doit renvoyer XR_ERROR_LIMIT_REACHED . Si le traceur est bien créé, il passe initialement à l'état XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , et l'application doit attendre que l'état passe à XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID avant d'utiliser le traceur. Consultez XrEventDataGeospatialTrackerStateChangedANDROID . Si l'application transmet un XrGeospatialTrackerANDROID qui n'est pas à l'état XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID à une fonction qui l'exige, l'environnement d'exécution doit renvoyer XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

Le handle XrGeospatialTrackerANDROID doit être libéré via la fonction xrDestroyGeospatialTrackerANDROID.

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

La structure XrGeospatialTrackerCreateInfoANDROID est définie comme suit :

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

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.

Utilisation valide (implicite)

La fonction xrDestroyGeospatialTrackerANDROID est définie comme suit :

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

Description des paramètres

Une application peut utiliser la fonction xrDestroyGeospatialTrackerANDROID pour libérer le tracker géospatial et les ressources sous-jacentes.

Utilisation valide (implicite)

Thread safety

  • L'accès à geospatialTracker et à tous les handles enfants doit être synchronisé en externe.

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

État du traceur géospatial

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

typedef enum XrGeospatialTrackerStateANDROID {
    XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID = 0,
    XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID = 1,
    XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID = 2,
    XR_GEOSPATIAL_TRACKER_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGeospatialTrackerStateANDROID;

L'énumération XrGeospatialTrackerStateANDROID identifie les différents états d'un outil de suivi géospatial.

Les énumérants ont les valeurs suivantes :

Description de l'enum

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Le traceur géospatial n'est pas en cours d'exécution.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Le traceur géospatial est en cours d'exécution et utilisable.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Échec de l'initialisation du traceur géospatial, qui ne pourra jamais être utilisé.

La structure XrEventDataGeospatialTrackerStateChangedANDROID est définie comme suit :

typedef struct XrEventDataGeospatialTrackerStateChangedANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrGeospatialTrackerANDROID         geospatialTracker;
    XrGeospatialTrackerStateANDROID    state;
    XrResult                           initializationResult;
    XrTime                             time;
} XrEventDataGeospatialTrackerStateChangedANDROID;

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'XrGeospatialTrackerANDROID dont l'état a changé.
  • state est le nouvel XrGeospatialTrackerStateANDROID .
  • initializationResult est le résultat d'erreur si state est XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , sinon XR_SUCCESS .
  • time est l'XrTime auquel le changement d'état s'est produit.

La structure XrEventDataGeospatialTrackerStateChangedANDROID est envoyée lorsque l'état du traceur géospatial change. Si l'application dispose d'un XrGeospatialTrackerANDROID valide, elle doit interroger cet événement. Le premier événement reçu pour un traceur aura state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . Après un certain temps déterminé par l'environnement d'exécution, l'état doit passer à XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID ou XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID . Cette transition prendra un certain temps. Si state passe à XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , il doit s'agir du dernier événement reçu pour ce traceur, et le champ initializationResult contiendra le code d'erreur. L'erreur peut mettre plusieurs secondes à se produire. Dans ce cas, l'application doit détruire le traceur. Si state passe à XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , toutes les ancres géospatiales précédemment créées doivent cesser définitivement d'être suivies et doivent être détruites par l'application. L'état peut basculer entre XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID et XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID un nombre arbitraire de fois.

Utilisation valide (implicite)

Pose géospatiale

La structure XrGeospatialPoseANDROID est définie comme suit :

typedef struct XrGeospatialPoseANDROID {
    XrQuaternionf    eastUpSouthOrientation;
    double           latitude;
    double           longitude;
    double           altitude;
} XrGeospatialPoseANDROID;

Descriptions des membres

  • eastUpSouthOrientation est un XrQuaternionf définissant 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 -90 et +90.
  • longitude est la longitude en degrés, comprise entre -180 et +180.
  • altitude est l'altitude en mètres au-dessus de l'ellipsoïde WGS84.

La structure XrGeospatialPoseANDROID représente une position et une orientation par rapport à la Terre à l'aide de l'ellipsoïde WGS84.

Utilisation valide (implicite)

  • L'extension XR_ANDROID_geospatial doit être activée avant d'utiliser XrGeospatialPoseANDROID.
  • latitude doit être une valeur double valide
  • longitude doit être une valeur double valide
  • altitude doit être une valeur double valide

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

// Flag bits for XrGeospatialPoseFlagsANDROID
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID = 0x00000001;
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID = 0x00000002;

L'énumération XrGeospatialPoseFlagBitsANDROID spécifie les options des poses géospatiales.

Les bits d'indicateur ont les significations suivantes :

Descriptions des flags

  • XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID : indique que le membre d'orientation contient des données valides.
  • XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID : indique que le membre de position contient des données valides.

Le type XrGeospatialPoseFlagsANDROID est un masque de bits de XrGeospatialPoseFlagBitsANDROID .

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

Convertir XrPosef en objet "pose" géospatial

La fonction xrLocateGeospatialPoseFromPoseANDROID est définie comme suit :

XrResult xrLocateGeospatialPoseFromPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseFromPoseLocateInfoANDROID* locateInfo,
    XrGeospatialPoseResultANDROID*              geospatialPoseResult);

Description des paramètres

La fonction xrLocateGeospatialPoseFromPoseANDROID convertit une pose dans XrGeospatialPoseFromPoseLocateInfoANDROID :: space en pose géospatiale. Si l'état de geospatialTracker n'est pas XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , l'environnement d'exécution doit renvoyer XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Si la fonction renvoie XR_SUCCESS , le champ poseFlags de XrGeospatialPoseResultANDROID :: geospatialPoseResult détermine les champs de sortie valides. Si XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID n'est pas défini dans XrGeospatialPoseResultANDROID :: poseFlags , l'application ne doit pas lire les champs XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy ou XrGeospatialPoseResultANDROID :: verticalAccuracy dans XrGeospatialPoseResultANDROID . Si XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID n'est pas défini dans XrGeospatialPoseResultANDROID :: poseFlags , l'application ne doit pas lire XrGeospatialPoseANDROID :: eastUpSouthOrientation ou XrGeospatialPoseResultANDROID :: orientationYawAccuracy . Si XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID n'est pas défini, XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID ne doit pas être défini non plus.

Si la précision est inférieure à celle attendue, cela peut indiquer que l'appareil n'utilise pas la localisation VPS. L'application peut demander à l'utilisateur de pointer son appareil vers des panneaux et des bâtiments pour améliorer la localisation.

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La structure XrGeospatialPoseFromPoseLocateInfoANDROID est définie comme suit :

typedef struct XrGeospatialPoseFromPoseLocateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrPosef            pose;
} XrGeospatialPoseFromPoseLocateInfoANDROID;

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.
  • space est l'XrSpace dans lequel pose est défini.
  • time est le XrTime auquel évaluer pose .
  • pose est l'objet XrPosef dans space à convertir en objet "pose" géospatial.

Utilisation valide (implicite)

La structure XrGeospatialPoseResultANDROID est définie comme suit :

typedef struct XrGeospatialPoseResultANDROID {
    XrStructureType                 type;
    void*                           next;
    XrGeospatialPoseFlagsANDROID    poseFlags;
    XrGeospatialPoseANDROID         geospatialPose;
    double                          horizontalAccuracy;
    double                          verticalAccuracy;
    double                          orientationYawAccuracy;
} XrGeospatialPoseResultANDROID;

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.
  • poseFlags est un masque de bits de XrGeospatialPoseFlagsANDROID indiquant la validité des composants de la pose.
  • geospatialPose est le XrGeospatialPoseANDROID obtenu.
  • horizontalAccuracy est la précision horizontale estimée de la position de la pose géospatiale, définie comme le rayon en mètres du cercle de niveau de confiance de 68 % autour de la latitude et de la longitude données.
  • verticalAccuracy est la précision verticale estimée de la position de la pose géospatiale, définie comme la distance en mètres d'un niveau de confiance de 68 % autour de l'altitude donnée. En d'autres termes, il y a 68 % de chances que l'altitude réelle se situe dans la plage [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ].
  • orientationYawAccuracy est la précision estimée du lacet de l'orientation de la pose géospatiale, définie comme le rayon en degrés d'un niveau de confiance de 68 % autour de l'orientation donnée.

Utilisation valide (implicite)

Convertir une pose géospatiale en XrPosef

La fonction xrLocateGeospatialPoseANDROID est définie comme suit :

XrResult xrLocateGeospatialPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseLocateInfoANDROID*    locateInfo,
    XrSpaceLocation*                            location);

Description des paramètres

La fonction xrLocateGeospatialPoseANDROID convertit une pose géospatiale en XrSpaceLocation . Si XrGeospatialTrackerANDROID n'est pas en cours d'exécution, l'environnement d'exécution doit renvoyer XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Si la fonction renvoie XR_SUCCESS , le champ locationFlags de location (XrSpaceLocation) détermine les champs de sortie valides.

Utilisation valide (implicite)

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

La structure XrGeospatialPoseLocateInfoANDROID est définie comme suit :

typedef struct XrGeospatialPoseLocateInfoANDROID {
    XrStructureType            type;
    const void*                next;
    XrSpace                    space;
    XrTime                     time;
    XrGeospatialPoseANDROID    geospatialPose;
} XrGeospatialPoseLocateInfoANDROID;

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.
  • space est l'XrSpace dans lequel la pose résultante sera représentée.
  • time est l'XrTime où localiser la pose.
  • geospatialPose est l'élément XrGeospatialPoseANDROID à convertir.

Utilisation valide (implicite)

Disponibilité de VPS

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

typedef enum XrVPSAvailabilityANDROID {
    XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID = 1,
    XR_VPS_AVAILABILITY_AVAILABLE_ANDROID = 2,
    XR_VPSAVAILABILITY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrVPSAvailabilityANDROID;

L'énumération XrVPSAvailabilityANDROID indique la disponibilité du VPS.

Les énumérants ont les valeurs suivantes :

Description de l'enum

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

Le VPS n'est pas disponible à proximité de l'emplacement indiqué.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

Le VPS est disponible à proximité de l'emplacement indiqué.

La fonction xrCheckVpsAvailabilityAsyncANDROID est définie comme suit :

XrResult xrCheckVpsAvailabilityAsyncANDROID(
    XrSession                                   session,
    double                                      latitude,
    double                                      longitude,
    XrFutureEXT*                                future);

Description des paramètres

  • session est la XrSession à utiliser pour la vérification.
  • latitude est la latitude en degrés.
  • longitude est la longitude en degrés.
  • future est un pointeur vers XrFutureEXT qui contiendra le résultat de l'opération asynchrone.

La disponibilité du service de positionnement visuel (VPS) indique si le VPS peut être utilisé pour améliorer la précision géospatiale à un emplacement donné.

La fonction xrCheckVpsAvailabilityAsyncANDROID lance une vérification asynchrone de la disponibilité du VPS à un emplacement donné. L'application n'a pas besoin d'un XrGeospatialTrackerANDROID pour appeler cette fonction et peut utiliser le résultat de cette opération pour décider d'en créer un ou non. Si l'application n'a pas obtenu les autorisations requises, l'environnement d'exécution doit renvoyer XR_ERROR_PERMISSION_INSUFFICIENT .

Utilisation valide (implicite)

  • L'extension XR_ANDROID_geospatial doit être activée avant d'appeler xrCheckVpsAvailabilityAsyncANDROID.
  • session doit être un handle XrSession valide
  • latitude doit être une valeur double valide
  • longitude doit être une valeur double 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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

La fonction xrCheckVpsAvailabilityCompleteANDROID est définie comme suit :

XrResult xrCheckVpsAvailabilityCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrVPSAvailabilityCheckCompletionANDROID*    completion);

Description des paramètres

Utilisation valide (implicite)

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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

La structure XrVPSAvailabilityCheckCompletionANDROID est définie comme suit :

typedef struct XrVPSAvailabilityCheckCompletionANDROID {
    XrStructureType             type;
    void*                       next;
    XrResult                    futureResult;
    XrVPSAvailabilityANDROID    availability;
} XrVPSAvailabilityCheckCompletionANDROID;

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 vérification. 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.
  • availability est le résultat XrVPSAvailabilityANDROID . L'application ne doit pas lire ce champ, sauf si futureResult est défini sur 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_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Utilisation valide (implicite)

Exemple

Configurer le traceur géospatial

PFN_xrCheckVpsAvailabilityAsyncANDROID xrCheckVpsAvailabilityAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCheckVpsAvailabilityCompleteANDROID xrCheckVpsAvailabilityCompleteANDROID;
PFN_xrCreateGeospatialTrackerANDROID xrCreateGeospatialTrackerANDROID;
XrInstance instance = XR_NULL_HANDLE;
XrSystemId systemId = XR_NULL_SYSTEM_ID;
XrSession session = XR_NULL_HANDLE;
double lat = 37.422, lng = -122.084;

// Check for support.
XrSystemGeospatialPropertiesANDROID geospatialSystemProperties{
    XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{XR_TYPE_SYSTEM_PROPERTIES,
                                    &geospatialSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!geospatialSystemProperties.supportsGeospatial) {
  return;
}

// Check VPS Availability.
XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCheckVpsAvailabilityAsyncANDROID(session, lat, lng, &future));

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

XrVPSAvailabilityCheckCompletionANDROID vpsCompletion{
    XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID};
CHK_XR(xrCheckVpsAvailabilityCompleteANDROID(session, future, &vpsCompletion));
if (vpsCompletion.futureResult == XR_SUCCESS) {
  if (vpsCompletion.availability == XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID) {
    // Visual Positioning Service is not available. Accuracy of positions and
    // orientations from Geospatial APIs are expected to be lower at this location.
  } else {
    // Visual Positioning Service is available. Higher accuracy of position and
    // orientation is achievable at this location.
  }
}

// Create Geospatial Tracker.
XrGeospatialTrackerCreateInfoANDROID createInfo{
    XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID};
XrGeospatialTrackerANDROID geospatialTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateGeospatialTrackerANDROID(session, &createInfo, &geospatialTracker));

// In application main event loop:
while (true) {
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  if (xrPollEvent(instance, &event) != XR_SUCCESS) {
    continue;
  }
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID:
      const XrEventDataGeospatialTrackerStateChangedANDROID& eventData =
          *reinterpret_cast<XrEventDataGeospatialTrackerStateChangedANDROID*>(&event);
      switch (eventData.state) {
        case XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID:
          // Destroy existing anchors, if any.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID:
          // Start adding content.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID:
          // Handle eventData.initializationResult error result.
          break;
      }
  }
}

Appeler les API Geospatial Pose

PFN_xrLocateGeospatialPoseFromPoseANDROID xrLocateGeospatialPoseFromPoseANDROID;
PFN_xrLocateGeospatialPoseANDROID xrLocateGeospatialPoseANDROID;

XrGeospatialTrackerANDROID geospatialTracker;

// Get pose from view space.
XrSpace viewSpace;
XrPosef identityPose = {{0,0,0,1},{0,0,0}};
XrGeospatialPoseFromPoseLocateInfoANDROID poseGetInfo{
    XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID};
XrGeospatialPoseResultANDROID poseResult{
    XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID};
poseGetInfo.space = viewSpace;
poseGetInfo.pose = identityPose;
poseGetInfo.time = 0;  // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseFromPoseANDROID(geospatialTracker, &poseGetInfo, &poseResult));
if ((poseResult.poseFlags & XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID) &&
    (poseResult.poseFlags & XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID)) {
  // poseResult.geospatialPose is valid.
}

// Convert Geospatial pose to an XrSpaceLocation.
XrGeospatialPoseLocateInfoANDROID poseLocateInfo{
    XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID};
XrSpaceLocation location{XR_TYPE_SPACE_LOCATION};
poseLocateInfo.space = viewSpace;
poseLocateInfo.geospatialPose = poseResult.geospatialPose;
poseLocateInfo.time = 0; // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseANDROID(geospatialTracker, &poseLocateInfo, &location));
if ((location.locationFlags & XR_SPACE_LOCATION_ORIENTATION_VALID_BIT) &&
    (location.locationFlags & XR_SPACE_LOCATION_POSITION_VALID_BIT)) {
  // location.pose is valid.
}

Nouveaux types d'objets

Nouvelles commandes

Nouvelles structures

Nouvelles énumérations

Nouveaux masques de bits

Nouvelles constantes d'énumération

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • Extension de XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • Extension de XrResult :

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • Extension de XrStructureType :

    • XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID
    • XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID

Problèmes

L'historique des versions

  • Révision 1, 18/12/2025 (Ben King)

    • Description initiale de l'extension.