Extension OpenXR XR_ANDROID_device_anchor_persistence

Chaîne de nom

XR_ANDROID_device_anchor_persistence

Type d'extension

Extension d'instance

Numéro d'extension enregistré

458

Révision

1

Dépendances d'extension et de version

XR_EXT_uuid et XR_ANDROID_trackables

Date de dernière modification

2024-10-10

État de l'adresse IP

Aucune revendication d'adresse IP connue.

Contributeurs

Nihav Jain, Google

Levana Chen, Google

Spencer Quin, Google

Kenny Vercaemer, Google

Présentation

Cette extension permet à l'application de conserver, de récupérer et de supprimer les ancrages sur l'appareil actuel pour l'utilisateur actuel, entre les applications et les sessions de l'appareil.

Inspecter les fonctionnalités du système

La structure XrSystemDeviceAnchorPersistencePropertiesANDROID est définie comme suit :

typedef struct XrSystemDeviceAnchorPersistencePropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAnchorPersistence;
} XrSystemDeviceAnchorPersistencePropertiesANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
  • supportsAnchorPersistence est un XrBool32 qui indique si le système actuel est compatible avec la persistance des ancrages pour les ancrages spatiaux.

Une application peut vérifier si le système est capable de conserver des ancrages spatiaux (voir xrCreateAnchorSpaceANDROID) en étendant XrSystemProperties avec la structure XrSystemDeviceAnchorPersistencePropertiesANDROID lors de l'appel de xrGetSystemProperties. Pour les ancrages traçables compatibles, une application peut utiliser xrEnumerateSupportedPersistenceAnchorTypesANDROID pour interroger les types compatibles.

Si XR_FALSE est renvoyé pour supportsAnchorPersistence, XR_ERROR_FEATURE_UNSUPPORTED est renvoyé à partir des fonctions de persistance d'ancrage d'appareil qui fonctionnent sur un ancrage spatial.

Utilisation valide (implicite)

La fonction xrEnumerateSupportedPersistenceAnchorTypesANDROID est définie comme suit : 

XrResult xrEnumerateSupportedPersistenceAnchorTypesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    trackableTypeCapacityInput,
    uint32_t*                                   trackableTypeCountOutput,
    XrTrackableTypeANDROID*                     trackableTypes);

Descriptions des paramètres

  • session est l'XrSession qui crée l'XrDeviceAnchorPersistenceANDROID.
  • trackableTypeCapacityInput correspond à la capacité de trackableTypes, ou à 0 pour récupérer la capacité requise.
  • trackableTypeCountOutput est un pointeur vers le nombre de l'array ou un pointeur vers la capacité requise si trackableTypeCapacityInput est insuffisant.
  • trackableTypes est un pointeur vers un tableau de XrTrackableTypeANDROID, mais peut être NULL si trackableTypeCapacityInput est 0.
  • Pour obtenir une description détaillée de la récupération de la taille trackableTypes requise, consultez la section Paramètres de taille de la mémoire tampon.

L'application peut utiliser xrEnumerateSupportedPersistenceAnchorTypesANDROID pour vérifier la prise en charge de la persistance des ancres sur d'autres éléments de suivi XrTrackableTypeANDROID.

Si un XrTrackableTypeANDROID donné n'est pas renvoyé dans le tableau trackableTypes, XR_ERROR_FEATURE_UNSUPPORTED est renvoyé à partir des fonctions de persistance d'ancrage de l'appareil qui fonctionnent sur un ancrage de ce type.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS

Échec

  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_FUNCTION_UNSUPPORTED

Créer un gestionnaire de persistance d'ancrage d'appareil

Un XrDeviceAnchorPersistenceANDROID est un gestionnaire qui représente les ressources requises pour persister et suivre les ancrages persistants. 

XR_DEFINE_HANDLE(XrDeviceAnchorPersistenceANDROID)

La fonction xrCreateDeviceAnchorPersistenceANDROID est définie comme suit : 

XrResult xrCreateDeviceAnchorPersistenceANDROID(
    XrSession                                   session,
    const XrDeviceAnchorPersistenceCreateInfoANDROID* createInfo,
    XrDeviceAnchorPersistenceANDROID*           outHandle);

Descriptions des paramètres

Une application peut créer un gestionnaire XrDeviceAnchorPersistenceANDROID en appelant xrCreateDeviceAnchorPersistenceANDROID. XrDeviceAnchorPersistenceANDROID peut être utilisé dans les appels d'API ultérieurs pour conserver ou supprimer les ancres. Le doit être libéré à terme à l'aide de la fonction xrDestroyDeviceAnchorPersistenceANDROID.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

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

La structure XrDeviceAnchorPersistenceCreateInfoANDROID est définie comme suit : 

typedef struct XrDeviceAnchorPersistenceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrDeviceAnchorPersistenceCreateInfoANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.

La structure XrDeviceAnchorPersistenceCreateInfoANDROID fournit des options de création pour XrDeviceAnchorPersistenceANDROID lorsqu'elle est transmise à xrCreateDeviceAnchorPersistenceANDROID.

Utilisation valide (implicite)

La fonction xrDestroyDeviceAnchorPersistenceANDROID est définie comme suit : 

XrResult xrDestroyDeviceAnchorPersistenceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle);

Descriptions des paramètres

La fonction xrDestroyDeviceAnchorPersistenceANDROID détruit le gestionnaire de persistance de l'ancrage de l'appareil.

Utilisation valide (implicite)

Sécurité des threads

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

Codes de retour

Réussite

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Persister une ancre

La fonction xrPersistAnchorANDROID est définie comme suit :

XrResult xrPersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceInfoANDROID*    persistedInfo,
    XrUuidEXT*                                  anchorIdOutput);

Descriptions des paramètres

L'application peut demander la persistance des ancres en appelant xrPersistAnchorANDROID. L'application ne doit pas supposer qu'une valeur de retour de succès signifie que l'ancre est immédiatement conservée. L'application doit utiliser xrGetAnchorPersistStateANDROID pour vérifier l'état de persistance de l'ancre à l'aide de l'ancre XrUuidEXT renvoyée. L'application peut utiliser xrUnpersistAnchorANDROID pour supprimer la persistance de l'ancre.

  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID est renvoyé si l'ancre n'est pas suivie au moment de l'appel.
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID est renvoyé si les données persistantes ne sont pas prêtes.
  • XR_SUCCESS est renvoyé une fois que l'ancre a été mise en file d'attente pour la persistance.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

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

La structure XrPersistedAnchorSpaceInfoANDROID est définie comme suit : 

typedef struct XrPersistedAnchorSpaceInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            anchor;
} XrPersistedAnchorSpaceInfoANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
  • anchor est un XrSpace d'ancrage précédemment créé par xrCreateAnchorSpaceANDROID pour persister.

Utilisation valide (implicite)

La fonction xrGetAnchorPersistStateANDROID est définie comme suit : 

XrResult xrGetAnchorPersistStateANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId,
    XrAnchorPersistStateANDROID*                persistState);

Descriptions des paramètres

  • handle correspond à XrDeviceAnchorPersistenceANDROID.
  • anchorId correspond à l'XrUuidEXT de l'ancre.
  • persistState est un pointeur vers un XrAnchorPersistStateANDROID dans lequel l'état de l'ancre est renvoyé.
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID est renvoyé si l'ancre XrUuidEXT est introuvable.
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID est renvoyé si les données persistantes de anchorId ne sont pas prêtes.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID

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

typedef enum XrAnchorPersistStateANDROID {
    XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID = 0,
    XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID = 1,
    XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID = 2
} XrAnchorPersistStateANDROID;

Énumération

Description

XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID

L'application n'a pas demandé à conserver l'ancrage.

XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID

L'ancrage a été demandé à être persistant, mais il ne l'est pas encore.

XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID

L'ancre a bien été conservée par l'environnement d'exécution.

Créer une ancre à partir de données persistantes

La fonction xrCreatePersistedAnchorSpaceANDROID est définie comme suit : 

XrResult xrCreatePersistedAnchorSpaceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorOutput);

Descriptions des paramètres

L'application peut créer un ancrage XrSpace à partir d'un ancrage précédemment persistant en appelant xrCreatePersistedAnchorSpaceANDROID avec le même XrUuidEXT. Il s'agit d'une autre façon de créer des ancres, comme défini dans XR_ANDROID_trackables.

  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID est renvoyé si l'ancre XrUuidEXT est introuvable.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

La structure XrPersistedAnchorSpaceCreateInfoANDROID est définie comme suit : 

typedef struct XrPersistedAnchorSpaceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrUuidEXT          anchorId;
} XrPersistedAnchorSpaceCreateInfoANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
  • anchorId correspond à l'XrUuidEXT de l'ancre persistante à partir de laquelle créer un XrSpace.

La structure XrPersistedAnchorSpaceCreateInfoANDROID fournit des options de création pour l'ancrage lorsqu'elle est transmise à xrCreateDeviceAnchorPersistenceANDROID.

Utilisation valide (implicite)

Énumérer les ancres persistantes

La fonction xrEnumeratePersistedAnchorsANDROID est définie comme suit : 

XrResult xrEnumeratePersistedAnchorsANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    uint32_t                                    anchorIdsCapacityInput,
    uint32_t*                                   anchorIdsCountOutput,
    XrUuidEXT*                                  anchorIds);

Descriptions des paramètres

  • handle correspond à XrDeviceAnchorPersistenceANDROID.
  • anchorIdsCapacityInput correspond à la capacité du tableau anchorIds, ou à 0 pour indiquer une requête visant à récupérer la capacité requise.
  • anchorIdsCountOutput est un pointeur vers le nombre d'anchorIds écrites ou un pointeur vers la capacité requise si anchorIdsCapacityInput est insuffisant.
  • anchorIds est un pointeur vers un tableau de structures XrUuidEXT. Il peut être NULL si anchorIdsCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille anchorIds requise, consultez la section Paramètres de taille de la mémoire tampon.

L'application peut énumérer tous les ancrages persistants actuels en appelant xrEnumeratePersistedAnchorsANDROID. anchorIds contiendra les UUID des ancrages persistants jusqu'à la capacité du tableau. Si la capacité est insuffisante, les applications n'ont aucune garantie sur les ancrages renvoyés.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT

Désactiver la persistance d'une ancre persistante

La fonction xrUnpersistAnchorANDROID est définie comme suit : 

XrResult xrUnpersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId);

Descriptions des paramètres

L'application peut supprimer la persistance d'un ancrage persistant en appelant xrUnpersistAnchorANDROID et en transmettant l'ancrage XrUuidEXT de l'ancrage à supprimer.

  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID est renvoyé si les données persistantes ne sont pas prêtes.
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID est renvoyé si l'ancre XrUuidEXT est introuvable.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

Exemple de code pour la persistance des ancres

L'exemple de code suivant montre comment inspecter les fonctionnalités du système, persister, énumérer et supprimer des ancres, ainsi que créer une ancre à partir de l'ancre persistante XrUuidEXT.

XrSession session; // previously initialized
XrSpace anchor; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedPersistenceAnchorTypesANDROID xrEnumerateSupportedPersistenceAnchorTypesANDROID; // previously initialized
PFN_xrCreateDeviceAnchorPersistenceANDROID xrCreateDeviceAnchorPersistenceANDROID; // previously initialized
PFN_xrDestroyDeviceAnchorPersistenceANDROID xrDestroyDeviceAnchorPersistenceANDROID; // previously initialized
PFN_xrPersistAnchorANDROID xrPersistAnchorANDROID; // previously initialized
PFN_xrGetAnchorPersistStateANDROID xrGetAnchorPersistStateANDROID; // previously initialized
PFN_xrCreatePersistedAnchorSpaceANDROID xrCreatePersistedAnchorSpaceANDROID; // previously initialized
PFN_xrEnumeratePersistedAnchorsANDROID xrEnumeratePersistedAnchorsANDROID; // previously initialized
PFN_xrUnpersistAnchorANDROID xrUnpersistAnchorANDROID; // previously initialized

// Create a device anchor persistence handle
XrDeviceAnchorPersistenceCreateInfoANDROID persistenceHandleCreateInfo;
persistenceHandleCreateInfo.type = XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID;
persistenceHandleCreateInfo.next = nullptr;

XrDeviceAnchorPersistenceANDROID persistenceHandle;
CHK_XR(xrCreateDeviceAnchorPersistenceANDROID(session, &persistenceHandleCreateInfo, &persistenceHandle));

/// Persist an anchor
XrPersistedAnchorSpaceInfo anchorSpaceInfo;
anchorSpaceInfo.type = XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID;
anchorSpaceInfo.next = nullptr;
anchorSpaceInfo.anchor = anchor;

XrUuidEXT anchorId;
do {
  XrResult result = xrPersistAnchorANDROID(
    persistenceHandle, &anchorSpaceInfo, &anchorId);
} while (result == XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID ||
         result == XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID);
if (result != XR_SUCCESS) {
  // Handle errors
}


// ... Update loop ...
// Poll for anchor persist state to confirm if it was successfully persisted
XrAnchorPersistStateANDROID persistState;
CHK_XR(xrGetAnchorPersistStateANDROID(persistenceHandle, &anchorId, &persistState));
if (persistState == XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID)  {
  // The anchor was persisted successfully
}

// Enumerate all persisted anchors
uint32_t anchorCountOutput = 0;
std::vector<XrUuidEXT> allAnchors;

CHK_XR(xrEnumeratePersistedAnchorsANDROID(
  persistenceHandle,
  anchorCountOutput,
  &anchorCountOutput,
  nullptr
));
allAnchors.resize(anchorCountOutput, XR_NULL_HANDLE);

// Fetch the actual anchors in an appropriately resized array.
CHK_XR(xrEnumeratePersistedAnchorsANDROID(
  persistenceHandle,
  anchorCountOutput,
  &anchorCountOutput,
  allAnchors.data()
));

// Creating an anchor from a previously persisted anchor using its UUID
XrTime updateTime; // Time used for the current frame's simulation update.
XrUuidEXT anchorId = allAnchors[0];

XrPersistedAnchorSpaceCreateInfo createInfo;
createInfo.type = XR_TYPE_PERSISTED_ANCHOR_CREATE_INFO_ANDROID;
createInfo.next = nullptr;
createInfo.anchorId = anchorId;

XrSpace anchorSpace = XR_NULL_HANDLE;
CHK_XR(xrCreatePersistedAnchorSpaceANDROID(
  persistenceHandle,
  &createInfo,
  &anchorSpace
));

// The anchor was found and retrieved from the local device successfully.
XrSpaceLocation anchorLocation = { XR_TYPE_SPACE_LOCATION };
CHK_XR(xrLocateSpace(anchorSpace, appSpace, updateTime, &anchorLocation));
XrPosef pose = anchorLocation.pose;

// Unpersist the anchor
do {
  XrResult result = xrUnpersistAnchorANDROID(persistenceHandle, &anchorId);
} while (result == XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID);
if (result != XR_SUCCESS) {
  // Handle errors
}

// Once app is done with all persistence related tasks
CHK_XR(xrDestroySpace(anchorSpace));
CHK_XR(xrDestroyDeviceAnchorPersistenceANDROID(persistenceHandle));

Nouveaux types d'objets

Nouvelles constantes d'énumération

L'énumération XrObjectType est étendue avec :

  • XR_OBJECT_TYPE_DEVICE_ANCHOR_PERSISTENCE_ANDROID

L'énumération XrResult est étendue avec :

  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_ANCHOR_ALREADY_PERSISTED_ANDROID
  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

L'énumération XrStructureType est étendue avec :

  • XR_TYPE_PERSISTED_ANCHOR_ANDROID
  • XR_TYPE_PERSISTED_ANCHOR_SPACE_CREATE_INFO_ANDROID
  • XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID
  • XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID

Nouvelles énumérations

Nouvelles structures

Nouvelles fonctions

Problèmes

Historique des versions

  • Révision 1, 10/10/2024 (Kenny Vercaemer)
    • Description initiale de l'extension

OpenXR™ et le logo OpenXR sont des marques appartenant à The Khronos Group Inc. et sont enregistrés en tant que marques en Chine, dans l'Union européenne, au Japon et au Royaume-Uni.