Rozszerzenie OpenXR XR_ANDROID_device_anchor_persistence

Kody zwrotu

Gotowe

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Błąd

• 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

Struktura XrDeviceAnchorPersistenceCreateInfoANDROID jest zdefiniowana jako:

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

Opisy członków

• type to XrStructureType tej struktury.
• next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.

Struktura XrDeviceAnchorPersistenceCreateInfoANDROID udostępnia opcje tworzenia dla typu XrDeviceAnchorPersistenceANDROID, gdy zostanie przekazana do funkcji xrCreateDeviceAnchorPersistenceANDROID.

Prawidłowe użycie (domyślne)

• Zanim użyjesz rozszerzenia XrDeviceAnchorPersistenceCreateInfoANDROID, musisz je włączyć.XR_ANDROID_device_anchor_persistence
• type musi być XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID
• next musi być NULL lub prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktury.

Funkcja xrDestroyDeviceAnchorPersistenceANDROID jest zdefiniowana jako:

XrResult xrDestroyDeviceAnchorPersistenceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle);

Opisy parametrów

• handle to obiekt XrDeviceAnchorPersistenceANDROID utworzony wcześniej przez xrCreateDeviceAnchorPersistenceANDROID.

Funkcja xrDestroyDeviceAnchorPersistenceANDROID niszczy uchwyt trwałego odnośnika urządzenia.

Prawidłowe użycie (domyślne)

• Rozszerzenie XR_ANDROID_device_anchor_persistence musi być włączone przed wywołaniem funkcji xrDestroyDeviceAnchorPersistenceANDROID.
• handle musi być prawidłowym uchwytem XrDeviceAnchorPersistenceANDROID.

Bezpieczeństwo wątków

• Dostęp do handle i wszystkich jego obiektów potomnych musi być zsynchronizowany zewnętrznie.

Kody zwrotu

Gotowe

• XR_SUCCESS

Błąd

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

Zachowywanie kotwicy

Funkcja xrPersistAnchorANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

• handle to XrDeviceAnchorPersistenceANDROID.
• persistedInfo to XrPersistedAnchorSpaceInfoANDROID zawierający parametry trwałości kotwicy.
• anchorIdOutput to wskaźnik do atrybutu XrUuidEXT, w którym zwracany jest identyfikator UUID trwałej kotwicy.

Aplikacja może poprosić o zapisanie kotwic, wywołując funkcję xrPersistAnchorANDROID. Aplikacja nie może zakładać, że wartość zwracana przez metodę success oznacza, że kotwica została natychmiast zapisana. Aplikacja powinna użyć funkcji xrGetAnchorPersistStateANDROID, aby sprawdzić stan trwałości za pomocą zwróconego parametru XrUuidEXT. Aplikacja może użyć metody xrUnpersistAnchorANDROID, aby usunąć trwałość zakotwiczenia.

• Jeśli w momencie wywołania nie jest śledzona żadna pozycja, zwracana jest wartość XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID.
• XR_SUCCESS zostanie zwrócony, gdy kotwnik zostanie umieszczony w kolejce w celu zachowania.

Prawidłowe użycie (domyślne)

• Rozszerzenie XR_ANDROID_device_anchor_persistencemusi być włączone przed wywołaniem metody xrPersistAnchorANDROID.
• handle musi być prawidłowym uchwytem XrDeviceAnchorPersistenceANDROID.
• persistedInfo musi być wskaźnikiem do prawidłowej struktury XrPersistedAnchorSpaceInfoANDROID
• anchorIdOutput musi wskazywać strukturę XrUuidEXT.

Kody zwrotu

Gotowe

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Błąd

• 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

Struktura XrPersistedAnchorSpaceInfoANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

• type to XrStructureType tej struktury.
• next to NULL lub wskaźnik do następnej struktury w łańcuchu struktury. W podstawowym OpenXR ani w tym rozszerzeniu nie zdefiniowano żadnych takich struktur.
• anchor to zakotwiczony XrSpace utworzony wcześniej przez funkcję xrCreateAnchorSpaceANDROID w celu zachowania.

Prawidłowe użycie (domyślne)

• Przed użyciem rozszerzenia XrPersistedAnchorSpaceInfoANDROID musi być włączone rozszerzenie XR_ANDROID_device_anchor_persistence.
• type musi być XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID
• next musi być NULL lub prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktury.
• anchor musi być prawidłowym identyfikatorem XrSpace

Funkcja xrGetAnchorPersistStateANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

• handle to XrDeviceAnchorPersistenceANDROID.
• anchorId to XrUuidEXT kotwicy.
• persistState to wskaźnik do XrAnchorPersistStateANDROID, w którym zwracany jest stan kotwicy.
• Jeśli nie uda się znaleźć elementu zaczepu XrUuidEXT, zwrócona zostanie wartość XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID.
• Jeśli zapisane dane anchorId nie są gotowe, zwrócona zostanie wartość XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID.

Prawidłowe użycie (domyślne)

• Rozszerzenie XR_ANDROID_device_anchor_persistencemusi być włączone przed wywołaniem funkcji xrGetAnchorPersistStateANDROID.
• handle musi być prawidłowym uchwytem XrDeviceAnchorPersistenceANDROID.
• anchorId musi wskazywać prawidłową strukturę XrUuidEXT
• persistState musi być wskaźnikiem do wartości XrAnchorPersistStateANDROID.

Kody zwrotu

Gotowe

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Błąd

• 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

Wyliczenie XrAnchorPersistStateANDROID jest zdefiniowane w ten sposób:

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;

Tworzenie kotwicy na podstawie utrwalonych danych

Funkcja xrCreatePersistedAnchorSpaceANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

• handle to XrDeviceAnchorPersistenceANDROID.
• createInfo to XrPersistedAnchorSpaceCreateInfoANDROID zawierający parametry do tworzenia kotwicy.
• anchorOutput to wskaźnik do XrSpace, w którym zwracany jest nowy pokój kotwicy.

Aplikacja może utworzyć kotwicę XrSpace na podstawie wcześniej zapisanej kotwicy, wywołując funkcję xrCreatePersistedAnchorSpaceANDROID z tym samym parametrem XrUuidEXT. Jest to inny sposób tworzenia kotwic zgodnie z definicją w XR_ANDROID_trackables.

• Jeśli nie uda się znaleźć elementu zaczepu XrUuidEXT, zwrócona zostanie wartość XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID.

Prawidłowe użycie (domyślne)

• Przed wywołaniem funkcji xrCreatePersistedAnchorSpaceANDROID musi być włączone rozszerzenie XR_ANDROID_device_anchor_persistence.
• handle musi być prawidłowym uchwytem XrDeviceAnchorPersistenceANDROID.
• createInfo musi być wskaźnikiem do prawidłowej struktury XrPersistedAnchorSpaceCreateInfoANDROID
• anchorOutput musi wskazywać na nick w XrSpace.

Kody zwrotu

Gotowe

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Błąd

• 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

Struktura XrPersistedAnchorSpaceCreateInfoANDROID jest zdefiniowana jako:

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

Opisy członków

• type to XrStructureType tej struktury.
• next to NULL lub wskaźnik do następnej struktury w łańcuchu struktury. Nie ma żadnych takich struktur zdefiniowanych w podstawowym OpenXR ani w tym rozszerzeniu.
• anchorId to XrUuidEXT zapisanej kotwicy, na podstawie której można utworzyć kotwicę XrSpace.

Struktura XrPersistedAnchorSpaceCreateInfoANDROID udostępnia opcje tworzenia kotwicy, gdy jest ona przekazywana do funkcji xrCreateDeviceAnchorPersistenceANDROID.

Prawidłowe użycie (domyślne)

• Przed użyciem funkcji XrPersistedAnchorSpaceCreateInfoANDROID należy włączyć rozszerzenie XR_ANDROID_device_anchor_persistence.
• type musi być XR_TYPE_PERSISTED_ANCHOR_SPACE_CREATE_INFO_ANDROID
• next musi być NULL lub prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktury.

Wyliczanie trwałych kotwic

Funkcja xrEnumeratePersistedAnchorsANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

• handle to XrDeviceAnchorPersistenceANDROID.
• anchorIdsCapacityInput to pojemność tablicy anchorIds, a 0 oznacza prośbę o pobranie wymaganej pojemności.
• anchorIdsCountOutput to wskaźnik liczby zapisanych elementów anchorIds lub wskaźnik wymaganej pojemności w przypadku, gdy anchorIdsCapacityInput jest niewystarczająca.
• anchorIds to wskaźnik do tablicy struktur XrUuidEXT. Może ona wynosić NULL, jeśli anchorIdsCapacityInput = 0.
• Szczegółowe informacje o pobieraniu wymaganego rozmiaru anchorIds znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może wyliczyć wszystkie bieżące trwałe odnośniki, wywołując funkcję xrEnumeratePersistedAnchorsANDROID. Tablica anchorIds będzie przechowywać identyfikatory UUID zapisane w pliku w ramach dostępnej pojemności tablicy. Jeśli pojemność jest niewystarczająca, aplikacje nie mają gwarancji, które kotwy zostaną zwrócone.

Prawidłowe użycie (domyślne)

• Rozszerzenie XR_ANDROID_device_anchor_persistencemusi być włączone przed wywołaniem funkcji xrEnumeratePersistedAnchorsANDROID.
• handle musi być prawidłowym uchwytem XrDeviceAnchorPersistenceANDROID.
• anchorIdsCountOutput musi być wskaźnikiem na wartość uint32_t
• Jeśli anchorIdsCapacityInput nie jest 0, anchorIds, musi być wskaźnikiem do tablicy anchorIdsCapacityInput struktur XrUuidEXT.

Kody zwrotu

Gotowe

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Błąd

• 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

Odzyskiwanie trwałego zakotwiczenia

Funkcja xrUnpersistAnchorANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

• handle to XrDeviceAnchorPersistenceANDROID.
• anchorId to XrUuidEXT kotwicy, której nie chcesz zachować.

Aplikacja może usunąć trwałą kotwicę, wywołując metodę xrUnpersistAnchorANDROID i przekazując XrUuidEXT kotwicy, którą ma usunąć.

• Jeśli zapisane dane nie są gotowe, zwracana jest wartość XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID.
• Jeśli nie uda się znaleźć elementu zaczepu XrUuidEXT, zwrócona zostanie wartość XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID.

Prawidłowe użycie (domyślne)

• Rozszerzenie XR_ANDROID_device_anchor_persistencemusi być włączone przed wywołaniem funkcji xrUnpersistAnchorANDROID.
• handle musi być prawidłowym uchwytem XrDeviceAnchorPersistenceANDROID.
• anchorId musi wskazywać prawidłową strukturę XrUuidEXT

Kody zwrotu

Gotowe

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Błąd

• 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

Przykładowy kod zapewniający trwałość kotwicy

Poniższy przykładowy kod pokazuje, jak sprawdzić możliwości systemu, zapisać, wyliczyć i usunąć z pamięci zapisane kotwy oraz utworzyć kotwę z zapisanej kotwy 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;
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));

Nowe typy obiektów

• XrDeviceAnchorPersistenceANDROID

Nowe stałe typu wyliczeniowego

Wyliczenie XrObjectType zostało rozszerzone o:

• XR_OBJECT_TYPE_DEVICE_ANCHOR_PERSISTENCE_ANDROID

Wyliczenie XrResult zostało rozszerzone o:

• 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

Wyliczenie XrStructureType zostało rozszerzone o:

• 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

Nowe wartości w polu enum

• XrAnchorPersistStateANDROID

Nowe struktury

• XrDeviceAnchorPersistenceCreateInfoANDROID
• XrPersistedAnchorSpaceCreateInfoANDROID
• XrPersistedAnchorSpaceInfoANDROID
• XrSystemDeviceAnchorPersistencePropertiesANDROID

Nowe funkcje

• xrEnumerateSupportedPersistenceAnchorTypesANDROID
• xrCreateDeviceAnchorPersistenceANDROID
• xrDestroyDeviceAnchorPersistenceANDROID
• xrPersistAnchorANDROID
• xrGetAnchorPersistStateANDROID
• xrCreatePersistedAnchorSpaceANDROID
• xrEnumeratePersistedAnchorsANDROID
• xrUnpersistAnchorANDROID

Problemy

Historia wersji

• Wersja 1, 10 października 2024 r. (Kenny Vercaemer)
  • Początkowy opis rozszerzenia