Namensstring
XR_ANDROID_device_anchor_persistence
Erweiterungstyp
Instanzerweiterung
Registrierte Erweiterungsnummer
458
Revision
1
Erweiterungs- und Versionsabhängigkeiten
XR_EXT_uuid und XR_ANDROID_trackables
Datum der letzten Änderung
2024-10-10
IP-Status
Es sind keine Ansprüche aufgrund von Urheberrechten bekannt.
Mitwirkende
Nihav Jain, Google
Levana Chen, Google
Spencer Quin, Google
Kenny Vercaemer, Google
Übersicht
Mit dieser Erweiterung kann die Anwendung Anker auf dem aktuellen Gerät für den aktuellen Nutzer über Anwendungen und Gerätesitzungen hinweg speichern, abrufen und wieder löschen.
Systemkapazität prüfen
Die Struktur XrSystemDeviceAnchorPersistencePropertiesANDROID ist so definiert:
typedef struct XrSystemDeviceAnchorPersistencePropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAnchorPersistence;
} XrSystemDeviceAnchorPersistencePropertiesANDROID;
Beschreibungen von Mitgliedern
- typeist der XrStructureType dieser Struktur.
- nextist- NULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
- supportsAnchorPersistenceist ein- XrBool32, das angibt, ob das aktuelle System die Ankerspeicherung für räumliche Anker unterstützt.
Eine Anwendung kann prüfen, ob das System räumliche Anker speichern kann (siehe xrCreateAnchorSpaceANDROID), indem sie die Struktur XrSystemProperties beim Aufruf von xrGetSystemProperties um XrSystemDeviceAnchorPersistencePropertiesANDROID erweitert. Für die unterstützten trackbaren Anker kann eine Anwendung mit xrEnumerateSupportedPersistenceAnchorTypesANDROID die unterstützten Typen abfragen.
Wenn für supportsAnchorPersistence XR_FALSE zurückgegeben wird, wird XR_ERROR_FEATURE_UNSUPPORTED von Geräteanker-Persistenzfunktionen zurückgegeben, die auf einem räumlichen Anker basieren.
Gültige Verwendung (implizit)
- Die XR_ANDROID_device_anchor_persistence-Erweiterung muss aktiviert sein, bevor XrSystemDeviceAnchorPersistencePropertiesANDROID verwendet werden kann.
- typemuss- XR_TYPE_SYSTEM_DEVICE_ANCHOR_PERSISTENCE_PROPERTIES_ANDROIDsein.
- nextmuss- NULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
Die Funktion xrEnumerateSupportedPersistenceAnchorTypesANDROID ist so definiert:
XrResult xrEnumerateSupportedPersistenceAnchorTypesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    trackableTypeCapacityInput,
    uint32_t*                                   trackableTypeCountOutput,
    XrTrackableTypeANDROID*                     trackableTypes);
Parameterbeschreibungen
- sessionist die XrSession, die XrDeviceAnchorPersistenceANDROID erstellt.
- trackableTypeCapacityInputist die Kapazität der- trackableTypesoder 0, um die erforderliche Kapazität abzurufen.
- trackableTypeCountOutputist ein Verweis auf die Anzahl der Elemente im Array oder ein Verweis auf die erforderliche Kapazität, falls- trackableTypeCountOutputnicht ausreicht.- trackableTypeCapacityInput
- trackableTypesist ein Verweis auf ein Array von XrTrackableTypeANDROID, kann aber auch- NULLsein, wenn- trackableTypeCapacityInput- 0ist.
- Eine ausführliche Beschreibung zum Abrufen der erforderlichen trackableTypes-Größe findest du im Abschnitt Parameter für die Puffergröße.
Die Anwendung kann xrEnumerateSupportedPersistenceAnchorTypesANDROID verwenden, um die Unterstützung der Ankerspeicherung bei anderen XrTrackableTypeANDROID-Trackern zu prüfen.
Wenn ein bestimmter XrTrackableTypeANDROID nicht im Array trackableTypes zurückgegeben wird, wird XR_ERROR_FEATURE_UNSUPPORTED von Geräteanker-Persistenzfunktionen zurückgegeben, die auf einen Anker dieses Typs angewendet werden.
Gültige Verwendung (implizit)
- Die Erweiterung XR_ANDROID_device_anchor_persistencemuss aktiviert sein, bevor xrEnumerateSupportedPersistenceAnchorTypesANDROID aufgerufen wird.
- instancemuss ein gültiger XrInstance-Alias sein
- trackableTypeCountOutputmuss ein Verweis auf einen- uint32_t-Wert sein
- Wenn trackableTypeCapacityInputnicht0, trackableTypesist, muss es sich um einen Verweis auf ein Array vontrackableTypeCapacityInput-Werten vom Typ XrTrackableTypeANDROID handeln.
Rückgabecodes
- XR_SUCCESS
- 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
Persistenten Handle für Geräteanker erstellen
Ein XrDeviceAnchorPersistenceANDROID ist ein Handle, der die Ressourcen darstellt, die zum Speichern und Verfolgen gespeicherter Anker erforderlich sind.
XR_DEFINE_HANDLE(XrDeviceAnchorPersistenceANDROID)
Die Funktion xrCreateDeviceAnchorPersistenceANDROID ist so definiert:
XrResult xrCreateDeviceAnchorPersistenceANDROID(
    XrSession                                   session,
    const XrDeviceAnchorPersistenceCreateInfoANDROID* createInfo,
    XrDeviceAnchorPersistenceANDROID*           outHandle);
Parameterbeschreibungen
- sessionist die XrSession, die XrDeviceAnchorPersistenceANDROID erstellt.
- createInfoist die XrDeviceAnchorPersistenceCreateInfoANDROID mit Parametern für die XrDeviceAnchorPersistenceANDROID.
- outHandleist ein Verweis auf einen Handle, über den die erstellte XrDeviceAnchorPersistenceANDROID zurückgegeben wird.
Eine Anwendung kann einen XrDeviceAnchorPersistenceANDROID-Handle erstellen, indem sie xrCreateDeviceAnchorPersistenceANDROID aufruft. XrDeviceAnchorPersistenceANDROID kann in nachfolgenden API-Aufrufen verwendet werden, um Anker zu speichern oder aufzuheben. Der Handle XrDeviceAnchorPersistenceANDROID muss mit der Funktion xrDestroyDeviceAnchorPersistenceANDROID freigegeben werden.
Gültige Verwendung (implizit)
- Die Erweiterung XR_ANDROID_device_anchor_persistencemuss aktiviert sein, bevor xrCreateDeviceAnchorPersistenceANDROID aufgerufen wird.
- sessionmuss ein gültiger XrSession-Alias sein.
- createInfomuss ein Zeiger auf eine gültige XrDeviceAnchorPersistenceCreateInfoANDROID-Struktur sein.
- outHandlemuss ein Verweis auf einen XrDeviceAnchorPersistenceANDROID-Handle sein.
Rückgabecodes
- XR_SUCCESS
- XR_SESSION_LOSS_PENDING
- 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
Die Struktur XrDeviceAnchorPersistenceCreateInfoANDROID ist so definiert:
typedef struct XrDeviceAnchorPersistenceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrDeviceAnchorPersistenceCreateInfoANDROID;
Beschreibungen von Mitgliedern
- typeist der XrStructureType dieser Struktur.
- nextist- NULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
Die Struktur XrDeviceAnchorPersistenceCreateInfoANDROID bietet Erstellungsoptionen für die XrDeviceAnchorPersistenceANDROID, wenn sie an xrCreateDeviceAnchorPersistenceANDROID übergeben wird.
Gültige Verwendung (implizit)
- Die XR_ANDROID_device_anchor_persistence-Erweiterung muss aktiviert sein, bevor XrDeviceAnchorPersistenceCreateInfoANDROID verwendet werden kann.
- typemuss- XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROIDsein.
- nextmuss- NULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
Die Funktion xrDestroyDeviceAnchorPersistenceANDROID ist so definiert:
XrResult xrDestroyDeviceAnchorPersistenceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle);
Parameterbeschreibungen
- handleist ein XrDeviceAnchorPersistenceANDROID-Handle, der zuvor von- xrCreateDeviceAnchorPersistenceANDROIDerstellt wurde.
Die Funktion xrDestroyDeviceAnchorPersistenceANDROID löscht den Handle für die Geräteanker-Persistenz.
Gültige Verwendung (implizit)
- Die Erweiterung XR_ANDROID_device_anchor_persistencemuss aktiviert sein, bevor xrDestroyDeviceAnchorPersistenceANDROID aufgerufen wird.
- handlemuss ein gültiger XrDeviceAnchorPersistenceANDROID-Handle sein.
Threadsicherheit
- Der Zugriff auf handleund alle untergeordneten Handles muss extern synchronisiert werden.
Rückgabecodes
- XR_SUCCESS
- XR_ERROR_FUNCTION_UNSUPPORTED
- XR_ERROR_HANDLE_INVALID
Anker beibehalten
Die Funktion xrPersistAnchorANDROID ist so definiert:
XrResult xrPersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceInfoANDROID*    persistedInfo,
    XrUuidEXT*                                  anchorIdOutput);
Parameterbeschreibungen
- handleist die XrDeviceAnchorPersistenceANDROID.
- persistedInfoist das XrPersistedAnchorSpaceInfoANDROID-Element, das Parameter für die Ankerspeicherung enthält.
- anchorIdOutputist ein Verweis auf eine XrUuidEXT, in der die UUID des gespeicherten Ankers zurückgegeben wird.
Die Anwendung kann anfordern, dass Anker beibehalten werden, indem xrPersistAnchorANDROID aufgerufen wird. Die Anwendung darf nicht davon ausgehen, dass ein erfolgreicher Rückgabewert bedeutet, dass der Anker sofort gespeichert wird. Die Anwendung sollte xrGetAnchorPersistStateANDROID verwenden, um den dauerhaften Status des Ankers anhand der zurückgegebenen Anker-XrUuidEXT zu prüfen. Die Anwendung kann xrUnpersistAnchorANDROID verwenden, um den Anker aufzuheben.
- XR_ERROR_ANCHOR_NOT_TRACKING_ANDROIDwird zurückgegeben, wenn der Anker zum Zeitpunkt des Aufrufs nicht erfasst wird.
- XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROIDwird zurückgegeben, wenn die gespeicherten Daten noch nicht bereit sind.
- XR_SUCCESSwird zurückgegeben, sobald der Anker für die Persistenz in die Warteschlange gestellt wurde.
Gültige Verwendung (implizit)
- Die Erweiterung XR_ANDROID_device_anchor_persistencemuss aktiviert sein, bevor xrPersistAnchorANDROID aufgerufen wird.
- handlemuss ein gültiger XrDeviceAnchorPersistenceANDROID-Handle sein.
- persistedInfomuss ein Zeiger auf eine gültige XrPersistedAnchorSpaceInfoANDROID-Struktur sein.
- anchorIdOutputmuss ein Verweis auf eine XrUuidEXT-Struktur sein.
Rückgabecodes
- XR_SUCCESS
- XR_SESSION_LOSS_PENDING
- 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
Die Struktur XrPersistedAnchorSpaceInfoANDROID ist so definiert:
typedef struct XrPersistedAnchorSpaceInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            anchor;
} XrPersistedAnchorSpaceInfoANDROID;
Beschreibungen von Mitgliedern
- typeist der XrStructureType dieser Struktur.
- nextist- NULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
- anchorist ein Anker XrSpace, der zuvor mit xrCreateAnchorSpaceANDROID erstellt wurde, um dauerhaft zu bleiben.
Gültige Verwendung (implizit)
- Die XR_ANDROID_device_anchor_persistence-Erweiterung muss aktiviert sein, bevor XrPersistedAnchorSpaceInfoANDROID verwendet werden kann.
- typemuss- XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROIDsein.
- nextmuss- NULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
- anchormuss ein gültiger XrSpace-Handle sein
Die Funktion xrGetAnchorPersistStateANDROID ist so definiert:
XrResult xrGetAnchorPersistStateANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId,
    XrAnchorPersistStateANDROID*                persistState);
Parameterbeschreibungen
- handleist die XrDeviceAnchorPersistenceANDROID.
- anchorIdist die XrUuidEXT des Ankers.
- persistStateist ein Verweis auf einen XrAnchorPersistStateANDROID, in dem der Status des Ankers zurückgegeben wird.
- XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROIDwird zurückgegeben, wenn der Anker XrUuidEXT nicht gefunden wird.
- XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROIDwird zurückgegeben, wenn die gespeicherten Daten von- anchorIdnoch nicht verfügbar sind.
Gültige Verwendung (implizit)
- Die XR_ANDROID_device_anchor_persistence-Erweiterung muss aktiviert sein, bevor xrGetAnchorPersistStateANDROID aufgerufen wird.
- handlemuss ein gültiger XrDeviceAnchorPersistenceANDROID-Handle sein.
- anchorIdmuss ein Verweis auf eine gültige XrUuidEXT-Struktur sein.
- persistStatemuss ein Verweis auf einen XrAnchorPersistStateANDROID-Wert sein.
Rückgabecodes
- XR_SUCCESS
- XR_SESSION_LOSS_PENDING
- 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
Das XrAnchorPersistStateANDROID-Enum ist so definiert:
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;
| Enum | Beschreibung | 
| 
 | Der Anker wurde nicht von der App angefordert, dauerhaft gespeichert zu werden. | 
| 
 | Der Anker wurde angefordert, aber noch nicht gespeichert. | 
| 
 | Der Anker wurde von der Laufzeit erfolgreich beibehalten. | 
Anker aus gespeicherten Daten erstellen
Die Funktion xrCreatePersistedAnchorSpaceANDROID ist so definiert:
XrResult xrCreatePersistedAnchorSpaceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorOutput);
Parameterbeschreibungen
- handleist die XrDeviceAnchorPersistenceANDROID.
- createInfoist die XrPersistedAnchorSpaceCreateInfoANDROID mit Parametern für die Erstellung von Ankern.
- anchorOutputist ein Verweis auf einen XrSpace, in dem der neue Ankerbereich zurückgegeben wird.
Die Anwendung kann einen XrSpace-Anker aus einem zuvor gespeicherten Anker erstellen, indem sie xrCreatePersistedAnchorSpaceANDROID mit derselben XrUuidEXT aufruft. Dies ist eine weitere Möglichkeit, Anker gemäß XR_ANDROID_trackables zu erstellen.
- XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROIDwird zurückgegeben, wenn der Anker XrUuidEXT nicht gefunden wird.
Gültige Verwendung (implizit)
- Die XR_ANDROID_device_anchor_persistence-Erweiterung muss aktiviert sein, bevor xrCreatePersistedAnchorSpaceANDROID aufgerufen wird.
- handlemuss ein gültiger XrDeviceAnchorPersistenceANDROID-Handle sein.
- createInfomuss ein Zeiger auf eine gültige XrPersistedAnchorSpaceCreateInfoANDROID-Struktur sein.
- anchorOutputmuss ein Zeiger auf einen XrSpace-Handle sein.
Rückgabecodes
- XR_SUCCESS
- XR_SESSION_LOSS_PENDING
- 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
Die Struktur XrPersistedAnchorSpaceCreateInfoANDROID ist so definiert:
typedef struct XrPersistedAnchorSpaceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrUuidEXT          anchorId;
} XrPersistedAnchorSpaceCreateInfoANDROID;
Beschreibungen von Mitgliedern
- typeist der XrStructureType dieser Struktur.
- nextist- NULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
- anchorIdist die XrUuidEXT des gespeicherten Ankers, aus dem ein Anker XrSpace erstellt werden soll.
Die Struktur XrPersistedAnchorSpaceCreateInfoANDROID bietet Erstellungsoptionen für die Markierung, wenn sie an xrCreateDeviceAnchorPersistenceANDROID übergeben wird.
Gültige Verwendung (implizit)
- Die XR_ANDROID_device_anchor_persistence-Erweiterung muss aktiviert sein, bevor XrPersistedAnchorSpaceCreateInfoANDROID verwendet werden kann.
- typemuss- XR_TYPE_PERSISTED_ANCHOR_SPACE_CREATE_INFO_ANDROIDsein.
- nextmuss- NULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
Persistente Anker aufzählen
Die Funktion xrEnumeratePersistedAnchorsANDROID ist so definiert:
XrResult xrEnumeratePersistedAnchorsANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    uint32_t                                    anchorIdsCapacityInput,
    uint32_t*                                   anchorIdsCountOutput,
    XrUuidEXT*                                  anchorIds);
Parameterbeschreibungen
- handleist die XrDeviceAnchorPersistenceANDROID.
- anchorIdsCapacityInputist die Kapazität des- anchorIds-Arrays oder 0, um eine Anfrage zum Abrufen der erforderlichen Kapazität anzugeben.
- anchorIdsCountOutputist ein Verweis auf die Anzahl der geschriebenen- anchorIdsoder ein Verweis auf die erforderliche Kapazität, falls- anchorIdsCapacityInputnicht ausreicht.
- anchorIdsist ein Verweis auf ein Array von XrUuidEXT-Strukturen. Es kann- NULLsein, wenn- anchorIdsCapacityInput0 ist.
- Eine ausführliche Beschreibung zum Abrufen der erforderlichen anchorIds-Größe findest du im Abschnitt Parameter für die Puffergröße.
Die Anwendung kann alle aktuellen persistenten Anker auflisten, indem sie xrEnumeratePersistedAnchorsANDROID aufruft. anchorIds enthält die UUIDs der gespeicherten Anker bis zur Kapazität des Arrays. Wenn die Kapazität nicht ausreicht, können Anwendungen nicht sicher sein, welche Anker zurückgegeben werden.
Gültige Verwendung (implizit)
- Die Erweiterung XR_ANDROID_device_anchor_persistencemuss aktiviert sein, bevor xrEnumeratePersistedAnchorsANDROID aufgerufen wird.
- handlemuss ein gültiger XrDeviceAnchorPersistenceANDROID-Handle sein.
- anchorIdsCountOutputmuss ein Verweis auf einen- uint32_t-Wert sein
- Wenn anchorIdsCapacityInputnicht0, anchorIdsist, muss es sich um einen Verweis auf ein Array vonanchorIdsCapacityInputXrUuidEXT-Strukturen handeln.
Rückgabecodes
- XR_SUCCESS
- XR_SESSION_LOSS_PENDING
- 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
Persistenten Anker aufheben
Die Funktion xrUnpersistAnchorANDROID ist so definiert:
XrResult xrUnpersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId);
Parameterbeschreibungen
- handleist die XrDeviceAnchorPersistenceANDROID.
- anchorIdist die XrUuidEXT des Ankers, dessen Persistenz aufgehoben werden soll.
Die Anwendung kann einen persistenten Anker aufrufen, indem sie xrUnpersistAnchorANDROID aufruft und die XrUuidEXT des Ankers übergibt, der nicht mehr persistent sein soll.
- XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROIDwird zurückgegeben, wenn die gespeicherten Daten noch nicht bereit sind.
- XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROIDwird zurückgegeben, wenn der Anker XrUuidEXT nicht gefunden wird.
Gültige Verwendung (implizit)
- Die Erweiterung XR_ANDROID_device_anchor_persistencemuss aktiviert sein, bevor xrUnpersistAnchorANDROID aufgerufen wird.
- handlemuss ein gültiger XrDeviceAnchorPersistenceANDROID-Handle sein.
- anchorIdmuss ein Verweis auf eine gültige XrUuidEXT-Struktur sein.
Rückgabecodes
- XR_SUCCESS
- XR_SESSION_LOSS_PENDING
- 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
Beispielcode für die Ankerspeicherung
Im folgenden Beispielcode wird gezeigt, wie Sie die Systemfunktionen prüfen, Anker speichern, auflisten und wieder löschen sowie einen Anker aus dem gespeicherten Anker XrUuidEXT erstellen.
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));
Neue Objekttypen
Neue Enum-Konstanten
Die Aufzählung XrObjectType wurde um Folgendes erweitert:
- XR_OBJECT_TYPE_DEVICE_ANCHOR_PERSISTENCE_ANDROID
Die Aufzählung XrResult wurde um folgende Elemente erweitert:
- 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
Die Aufzählung XrStructureType wurde um folgende Elemente erweitert:
- 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
Neue Enums
Neue Strukturen
- XrDeviceAnchorPersistenceCreateInfoANDROID
- XrPersistedAnchorSpaceCreateInfoANDROID
- XrPersistedAnchorSpaceInfoANDROID
- XrSystemDeviceAnchorPersistencePropertiesANDROID
Neue Funktionen
- xrEnumerateSupportedPersistenceAnchorTypesANDROID
- xrCreateDeviceAnchorPersistenceANDROID
- xrDestroyDeviceAnchorPersistenceANDROID
- xrPersistAnchorANDROID
- xrGetAnchorPersistStateANDROID
- xrCreatePersistedAnchorSpaceANDROID
- xrEnumeratePersistedAnchorsANDROID
- xrUnpersistAnchorANDROID
Probleme
Versionsverlauf
- Revision 1, 10.10.2024 (Kenny Vercaemer)
- Erste Beschreibung der Erweiterung
 
OpenXR™ und das OpenXR-Logo sind Marken der Khronos Group Inc. und sind als Marke in China, der Europäischen Union, Japan und dem Vereinigten Königreich eingetragen.
