OpenXR-Erweiterung „XR_ANDROID_device_anchor_persistence“

Namensstring

XR_ANDROID_device_anchor_persistence

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

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.

Achtung:

Berechtigungen

Android-Apps müssen die Berechtigung „android.permission.SCENE_UNDERSTANDING“ in ihrem Manifest angeben, da diese Erweiterung davon abhängt und die Geometrie der Umgebung freigibt.XR_ANDROID_trackables Die Berechtigung „android.permission.SCENE_UNDERSTANDING“ gilt als gefährlich. Die Anwendung muss die Berechtigung zur Verwendung dieser Funktionen zur Laufzeit anfordern:
xrCreateDeviceAnchorPersistenceANDROID
(Schutzniveau: /dangerous)

Systemkapazität prüfen

Die Struktur XrSystemDeviceAnchorPersistencePropertiesANDROID ist so definiert:

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

Beschreibungen von Mitgliedern

• type ist der XrStructureType dieser Struktur.
• next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
• supportsAnchorPersistence ist 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 Erweiterung XR_ANDROID_device_anchor_persistence muss aktiviert sein, bevor XrSystemDeviceAnchorPersistencePropertiesANDROID verwendet werden kann.
• type muss XR_TYPE_SYSTEM_DEVICE_ANCHOR_PERSISTENCE_PROPERTIES_ANDROID sein.
• next muss NULL oder 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

• session ist die XrSession, die XrDeviceAnchorPersistenceANDROID erstellt.
• trackableTypeCapacityInput ist die Kapazität der trackableTypes oder 0, um die erforderliche Kapazität abzurufen.
• trackableTypeCountOutput ist ein Verweis auf die Anzahl der Elemente im Array oder ein Verweis auf die erforderliche Kapazität, falls trackableTypeCountOutput nicht ausreicht.trackableTypeCapacityInput
• trackableTypes ist ein Verweis auf ein Array von XrTrackableTypeANDROID, kann aber auch NULL sein, wenn trackableTypeCapacityInput 0 ist.
• 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_persistence muss aktiviert sein, bevor xrEnumerateSupportedPersistenceAnchorTypesANDROID aufgerufen wird.
• instance muss ein gültiger XrInstance-Alias sein
• trackableTypeCountOutput muss ein Verweis auf einen uint32_t-Wert sein
• Wenn trackableTypeCapacityInput nicht 0, trackableTypes ist, muss es sich um einen Verweis auf ein Array von trackableTypeCapacityInput-Werten vom Typ XrTrackableTypeANDROID handeln.

Rückgabecodes

Erfolg

• XR_SUCCESS

Fehler

• 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

• session ist die XrSession, die XrDeviceAnchorPersistenceANDROID erstellt.
• createInfo ist die XrDeviceAnchorPersistenceCreateInfoANDROID mit Parametern für die XrDeviceAnchorPersistenceANDROID.
• outHandle ist 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_persistence muss aktiviert sein, bevor xrCreateDeviceAnchorPersistenceANDROID aufgerufen wird.
• session muss ein gültiger XrSession-Alias sein.
• createInfo muss ein Zeiger auf eine gültige XrDeviceAnchorPersistenceCreateInfoANDROID-Struktur sein.
• outHandle muss ein Verweis auf einen XrDeviceAnchorPersistenceANDROID-Handle sein.

Rückgabecodes

Erfolg

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Fehler

• 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

• type ist der XrStructureType dieser Struktur.
• next ist NULL oder 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.
• type muss XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID sein.
• next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.

Die Funktion xrDestroyDeviceAnchorPersistenceANDROID ist so definiert:

XrResult xrDestroyDeviceAnchorPersistenceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle);

Parameterbeschreibungen

• handle ist ein XrDeviceAnchorPersistenceANDROID-Handle, der zuvor von xrCreateDeviceAnchorPersistenceANDROID erstellt wurde.

Die Funktion xrDestroyDeviceAnchorPersistenceANDROID löscht den Handle für die Geräteanker-Persistenz.

Gültige Verwendung (implizit)

• Die Erweiterung XR_ANDROID_device_anchor_persistence muss aktiviert sein, bevor xrDestroyDeviceAnchorPersistenceANDROID aufgerufen wird.
• handle muss ein gültiger XrDeviceAnchorPersistenceANDROID-Handle sein.

Threadsicherheit

• Der Zugriff auf handle und alle untergeordneten Handles muss extern synchronisiert werden.

Rückgabecodes

Erfolg

• XR_SUCCESS

Fehler

• 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

• handle ist die XrDeviceAnchorPersistenceANDROID.
• persistedInfo ist das XrPersistedAnchorSpaceInfoANDROID-Element, das Parameter für die Ankerspeicherung enthält.
• anchorIdOutput ist 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_ANDROID wird zurückgegeben, wenn der Anker zum Zeitpunkt des Aufrufs nicht erfasst wird.
• XR_SUCCESS wird zurückgegeben, sobald der Anker für die Persistenz in die Warteschlange gestellt wurde.

Gültige Verwendung (implizit)

• Die Erweiterung XR_ANDROID_device_anchor_persistence muss aktiviert sein, bevor xrPersistAnchorANDROID aufgerufen wird.
• handle muss ein gültiger XrDeviceAnchorPersistenceANDROID-Handle sein.
• persistedInfo muss ein Zeiger auf eine gültige XrPersistedAnchorSpaceInfoANDROID-Struktur sein.
• anchorIdOutput muss ein Verweis auf eine XrUuidEXT-Struktur sein.

Rückgabecodes

Erfolg

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Fehler

• 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

• type ist der XrStructureType dieser Struktur.
• next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
• anchor ist 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.
• type muss XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID sein.
• next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
• anchor muss ein gültiger XrSpace-Handle sein

Die Funktion xrGetAnchorPersistStateANDROID ist so definiert:

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

Parameterbeschreibungen

• handle ist die XrDeviceAnchorPersistenceANDROID.
• anchorId ist die XrUuidEXT des Ankers.
• persistState ist ein Verweis auf einen XrAnchorPersistStateANDROID, in dem der Status des Ankers zurückgegeben wird.
• XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID wird zurückgegeben, wenn der Anker XrUuidEXT nicht gefunden wird.
• XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID wird zurückgegeben, wenn die gespeicherten Daten von anchorId noch nicht verfügbar sind.

Gültige Verwendung (implizit)

• Die XR_ANDROID_device_anchor_persistence-Erweiterung muss aktiviert sein, bevor xrGetAnchorPersistStateANDROID aufgerufen wird.
• handle muss ein gültiger XrDeviceAnchorPersistenceANDROID-Handle sein.
• anchorId muss ein Verweis auf eine gültige XrUuidEXT-Struktur sein
• persistState muss ein Verweis auf einen XrAnchorPersistStateANDROID-Wert sein.

Rückgabecodes

Erfolg

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Fehler

• 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
XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID	Der Anker wurde nicht von der App angefordert, dauerhaft gespeichert zu werden.
XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID	Der Anker wurde angefordert, aber noch nicht gespeichert.
XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID	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

• handle ist die XrDeviceAnchorPersistenceANDROID.
• createInfo ist die XrPersistedAnchorSpaceCreateInfoANDROID mit Parametern für die Erstellung der Markierung.
• anchorOutput ist 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_ANDROID wird 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.
• handle muss ein gültiger XrDeviceAnchorPersistenceANDROID-Handle sein.
• createInfo muss ein Zeiger auf eine gültige XrPersistedAnchorSpaceCreateInfoANDROID-Struktur sein.
• anchorOutput muss ein Zeiger auf einen XrSpace-Handle sein.

Rückgabecodes

Erfolg

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Fehler

• 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

• type ist der XrStructureType dieser Struktur.
• next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
• anchorId ist 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.
• type muss XR_TYPE_PERSISTED_ANCHOR_SPACE_CREATE_INFO_ANDROID sein.
• next muss NULL oder 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

• handle ist die XrDeviceAnchorPersistenceANDROID.
• anchorIdsCapacityInput ist die Kapazität des anchorIds-Arrays oder 0, um eine Anfrage zum Abrufen der erforderlichen Kapazität anzugeben.
• anchorIdsCountOutput ist ein Verweis auf die Anzahl der geschriebenen anchorIds oder ein Verweis auf die erforderliche Kapazität, falls anchorIdsCapacityInput nicht ausreicht.
• anchorIds ist ein Verweis auf ein Array von XrUuidEXT-Strukturen. Es kann NULL sein, wenn anchorIdsCapacityInput 0 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_persistence muss aktiviert sein, bevor xrEnumeratePersistedAnchorsANDROID aufgerufen wird.
• handle muss ein gültiger XrDeviceAnchorPersistenceANDROID-Handle sein.
• anchorIdsCountOutput muss ein Verweis auf einen uint32_t-Wert sein
• Wenn anchorIdsCapacityInput nicht 0, anchorIds ist, muss es sich um einen Verweis auf ein Array von anchorIdsCapacityInput-Strukturen vom Typ XrUuidEXT handeln.

Rückgabecodes

Erfolg

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Fehler

• 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

• handle ist die XrDeviceAnchorPersistenceANDROID.
• anchorId ist die XrUuidEXT des Ankers, dessen Persistenz aufgehoben werden soll.

Die Anwendung kann einen persistenten Anker durch Aufrufen von xrUnpersistAnchorANDROID und Übergeben der XrUuidEXT des Ankers aufheben.

• XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID wird zurückgegeben, wenn die gespeicherten Daten noch nicht bereit sind.
• XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID wird zurückgegeben, wenn der Anker XrUuidEXT nicht gefunden wird.

Gültige Verwendung (implizit)

• Die Erweiterung XR_ANDROID_device_anchor_persistence muss aktiviert sein, bevor xrUnpersistAnchorANDROID aufgerufen wird.
• handle muss ein gültiger XrDeviceAnchorPersistenceANDROID-Handle sein.
• anchorId muss ein Verweis auf eine gültige XrUuidEXT-Struktur sein

Rückgabecodes

Erfolg

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Fehler

• 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;
CHK_XR(xrPersistAnchorANDROID(persistenceHandle, &anchorSpaceInfo, &anchorId));

// ... 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;

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

Neue Objekttypen

• XrDeviceAnchorPersistenceANDROID

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

• XrAnchorPersistStateANDROID

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