XR_ANDROID_geospatial

Chaîne de nom

XR_ANDROID_geospatial

Type d'extension

Extension d'instance

Numéro d'extension enregistré

790

Révision

1

État de ratification

Non ratifié

Dépendances des extensions et des versions

XR_EXT_future

Date de dernière modification

2025-12-18

État de l'adresse IP

Aucune réclamation connue pour atteinte à la propriété intellectuelle.

Contributeurs

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, il combine le suivi des mouvements, le GPS et d'autres capteurs, ainsi que le système de positionnement visuel (VPS) de Google. Le VPS compare les images de la caméra d'un appareil avec les images Street View afin de déterminer une position et une orientation précises. L'API Geospatial offre souvent une précision de positionnement inférieure au mètre (plusieurs ordres de grandeur mieux que le GPS) et une précision d'orientation inférieure au degré.

Pour utiliser correctement les API de cette extension (autre que la vérification de 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 disposer de 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 l'extension ni dans le cœur d'OpenXR.
  • supportsGeospatial est un XrBool32 , indiquant si le système actuel est compatible avec les fonctionnalités géospatiales.

Une application peut inspecter si le système prend en charge les fonctionnalités géospatiales en chaînant une structure XrSystemGeospatialPropertiesANDROID à XrSystemProperties lors de l'appel de xrGetSystemProperties .

Si un runtime renvoie XR_FALSE pour supportsGeospatial , cela signifie que le système n'est pas compatible avec les fonctionnalités géospatiales. Par conséquent, doit 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 identifiant Geospatial Tracker

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

La fonction xrCreateGeospatialTrackerANDROID est définie comme suit :

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

Descriptions 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, le runtime doit renvoyer XR_ERROR_PERMISSION_INSUFFICIENT . Une seule XrGeospatialTrackerANDROID peut exister à 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. Dans le cas contraire, l'environnement d'exécution doit renvoyer XR_ERROR_LIMIT_REACHED. Si le suivi est créé, il passe initialement à l'état XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID. L'application doit attendre que l'état passe à XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID avant d'utiliser le suivi. Consultez XrEventDataGeospatialTrackerStateChangedANDROID . Si l'application transmet un XrGeospatialTrackerANDROID qui n'est pas à l'état XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID à une fonction qui en a besoin, l'environnement d'exécution doit renvoyer XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

Le handle XrGeospatialTrackerANDROID doit être libéré à terme à l'aide de la fonction xrDestroyGeospatialTrackerANDROID.

Utilisation valide (implicite)

Codes de retour

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);

Descriptions 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)

Sécurité des threads

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

Codes de retour

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

État du suivi 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 tracker géospatial.

Les valeurs des énumérants sont les suivantes :

Description de l'enum

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Le Geospatial Tracker n'est pas en cours d'exécution.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

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

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Le Geospatial Tracker n'a pas pu être initialisé et 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 le XrGeospatialTrackerANDROID dont l'état a changé.
  • state est le nouveau XrGeospatialTrackerStateANDROID .
  • initializationResult est le résultat d'erreur si state est XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , sinon XR_SUCCESS .
  • time correspond à la XrTime à laquelle le changement d'état s'est produit.

La structure XrEventDataGeospatialTrackerStateChangedANDROID est envoyée lorsque l'état du suivi 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'exécution, l'état doit passer à XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID ou XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID . Cette transition prendra un temps arbitraire. Si state passe à XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID, il doit s'agir du dernier événement reçu pour ce traceur. Le champ initializationResult contiendra le code d'erreur. Il peut s'écouler plusieurs secondes avant qu'une erreur ne se produise. Dans ce cas, l'application doit détruire le traceur. Si state passe à XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , tous les ancres géospatiales précédemment créées doivent arrêter définitivement le suivi et doivent être détruites par l'application. L'état peut passer de XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID à XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID et inversement 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 qui définit 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, comprise entre -90 et +90.
  • longitude correspond à la longitude en degrés, comprise entre -180 et +180.
  • altitude correspond à 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 must être une valeur double valide
  • longitude must être une valeur double valide
  • altitude must ê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 indicateurs pour les poses géospatiales.

Les bits d'indicateur ont les significations suivantes :

Descriptions des indicateurs

  • 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 pose géospatiale

La fonction xrLocateGeospatialPoseFromPoseANDROID est définie comme suit :

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

Descriptions 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 , le runtime doit renvoyer XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Si la fonction renvoie XR_SUCCESS , le champ poseFlags de XrGeospatialPoseResultANDROID :: geospatialPoseResult détermine quels champs de sortie sont 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 ni 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 non plus être défini.

Si la précision est inférieure à ce qui est attendu, 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 de retour

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 correspond à XrPosef dans space à convertir en pose géospatiale.

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 XrGeospatialPoseFlagsANDROID indiquant la validité des composants de pose.
  • geospatialPose est l'XrGeospatialPoseANDROID résultant .
  • horizontalAccuracy correspond à la précision horizontale estimée de la position de la pose géospatiale. Elle est 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 correspond à la précision verticale estimée de la position de pose géospatiale, définie comme la distance en mètres du 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 correspond à la précision estimée du lacet de l'orientation de la pose géospatiale, définie comme le rayon en degrés du 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);

Descriptions des paramètres

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

Utilisation valide (implicite)

Codes de retour

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_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 le XrTime auquel localiser la pose.
  • geospatialPose est le XrGeospatialPoseANDROID à convertir.

Utilisation valide (implicite)

Disponibilité des 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 valeurs des énumérants sont les 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);

Descriptions des paramètres

  • session est la XrSession à utiliser pour la vérification.
  • latitude correspond à la latitude en degrés.
  • longitude correspond à 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 endroit 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 s'il faut en créer un. Si l'application n'a pas obtenu les autorisations requises, le runtime 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 must être une valeur double valide
  • longitude must être une valeur double valide
  • future must être un pointeur vers une valeur XrFutureEXT

Codes de retour

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);

Descriptions des paramètres

Utilisation valide (implicite)

Codes de retour

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 correspond à XrResult de l'opération de vérification. Si futureResult est défini sur 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 XrVPSAvailabilityANDROID obtenu . L'application ne doit pas lire ce champ, sauf si futureResult est défini sur XR_SUCCESS .

Codes de retour futurs

Valeurs 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 suivi 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

Nouveaux enums

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

Historique des versions

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

    • Description initiale de l'extension.