XR_ANDROID_device_anchor_persistence Расширение OpenXR

Имя Строка

XR_ANDROID_device_anchor_persistence

Тип расширения

Расширение экземпляра

Зарегистрированный добавочный номер

458

Пересмотр

1

Зависимости расширений и версий

XR_EXT_uuid и XR_ANDROID_trackables

Дата последнего изменения

2024-10-10

Статус ИС

Нет известных претензий на права интеллектуальной собственности.

Участники

Нихав Джайн, Google

Левана Чен, Google

Спенсер Куин, Google

Кенни Веркемер, Google

Обзор

Это расширение позволяет приложению сохранять, извлекать и отменять привязки на текущем устройстве для текущего пользователя в разных приложениях и сеансах работы с устройством.

Проверить возможности системы

Структура XrSystemDeviceAnchorPersistencePropertiesANDROID определяется следующим образом:

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

Описания участников

  • type — XrStructureType этой структуры.
  • next — NULL или указатель на следующую структуру в цепочке структур. Такие структуры не определены в ядре OpenXR или в этом расширении.
  • supportsAnchorPersistence — это XrBool32 указывающий, поддерживает ли текущая система сохранение якорей для пространственных якорей.

Приложение может проверить, способна ли система сохранять пространственные якоря (см. xrCreateAnchorSpaceANDROID ), расширив XrSystemProperties с помощью структуры XrSystemDeviceAnchorPersistencePropertiesANDROID при вызове xrGetSystemProperties . Для поддерживаемых отслеживаемых якорей приложение может использовать xrEnumerateSupportedPersistenceAnchorTypesANDROID для запроса поддерживаемых типов.

Если для supportsAnchorPersistence возвращается XR_FALSE , то из функций сохранения привязки устройства, работающих с пространственной привязкой, будет возвращено XR_ERROR_FEATURE_UNSUPPORTED

Допустимое использование (подразумеваемое)

Функция xrEnumerateSupportedPersistenceAnchorTypesANDROID определяется следующим образом:

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

Описание параметров

  • session — это XrSession , который создает XrDeviceAnchorPersistenceANDROID .
  • trackableTypeCapacityInput — это емкость trackableTypes или 0 для получения требуемой емкости.
  • trackableTypeCountOutput — указатель на количество элементов массива или указатель на требуемую емкость в случае, если trackableTypeCapacityInput недостаточно.
  • trackableTypes — это указатель на массив XrTrackableTypeANDROID , но может быть NULL , если trackableTypeCapacityInput равен 0 .
  • Подробное описание получения требуемого размера trackableTypes см. в разделе «Параметры размера буфера».

Приложение может использовать xrEnumerateSupportedPersistenceAnchorTypesANDROID для проверки поддержки сохранения якорей в других отслеживаемых объектах XrTrackableTypeANDROID .

Если заданный XrTrackableTypeANDROID не возвращается в массиве trackableTypes , то из функций сохранения привязки устройства, которые работают с привязкой этого типа, будет возвращено XR_ERROR_FEATURE_UNSUPPORTED

Допустимое использование (подразумеваемое)

Коды возврата

Успех

  • 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

Создать дескриптор сохранения привязки устройства

XrDeviceAnchorPersistenceANDROID — это дескриптор, который представляет ресурсы, необходимые для сохранения и отслеживания сохраненных якорей.

XR_DEFINE_HANDLE(XrDeviceAnchorPersistenceANDROID)

Функция xrCreateDeviceAnchorPersistenceANDROID определяется следующим образом:

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

Описание параметров

Приложение может создать дескриптор XrDeviceAnchorPersistenceANDROID , вызвав xrCreateDeviceAnchorPersistenceANDROID . XrDeviceAnchorPersistenceANDROID может использоваться в последующих вызовах API для сохранения или отмены сохранения якорей. Дескриптор XrDeviceAnchorPersistenceANDROID должен быть в конечном итоге освобожден с помощью функции xrDestroyDeviceAnchorPersistenceANDROID .

Допустимое использование (подразумеваемое)

Коды возврата

Успех

  • 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

Структура XrDeviceAnchorPersistenceCreateInfoANDROID определяется следующим образом:

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

Описания участников

  • type — XrStructureType этой структуры.
  • next — NULL или указатель на следующую структуру в цепочке структур. Такие структуры не определены в ядре OpenXR или в этом расширении.

Структура XrDeviceAnchorPersistenceCreateInfoANDROID предоставляет параметры создания для XrDeviceAnchorPersistenceANDROID при передаче в xrCreateDeviceAnchorPersistenceANDROID .

Допустимое использование (подразумеваемое)

Функция xrDestroyDeviceAnchorPersistenceANDROID определяется следующим образом:

XrResult xrDestroyDeviceAnchorPersistenceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle);

Описание параметров

Функция xrDestroyDeviceAnchorPersistenceANDROID уничтожает дескриптор сохранения привязки устройства.

Допустимое использование (подразумеваемое)

Безопасность потока

  • Доступ к handle и любым дочерним handle должен быть внешне синхронизирован.

Коды возврата

Успех

  • XR_SUCCESS

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Сохраняйте якорь

Функция xrPersistAnchorANDROID определяется как:

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

Описание параметров

Приложение может запросить сохранение якорей, вызвав xrPersistAnchorANDROID . Приложение не должно предполагать, что возвращаемое значение успеха означает, что якорь немедленно сохраняется. Приложение должно использовать xrGetAnchorPersistStateANDROID для проверки состояния сохранения якоря с помощью возвращенного якоря XrUuidEXT . Приложение может использовать xrUnpersistAnchorANDROID для отмены сохранения якоря.

  • Если якорь не отслеживается во время вызова, будет возвращено сообщение XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID
  • Если сохраненные данные не готовы, будет возвращено XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID .
  • XR_SUCCESS будет возвращен после того, как якорь будет поставлен в очередь на сохранение.

Допустимое использование (подразумеваемое)

Коды возврата

Успех

  • 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

Структура XrPersistedAnchorSpaceInfoANDROID определяется следующим образом:

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

Описания участников

  • type — XrStructureType этой структуры.
  • next — NULL или указатель на следующую структуру в цепочке структур. Такие структуры не определены в ядре OpenXR или в этом расширении.
  • anchor — это якорь XrSpace , ранее созданный xrCreateAnchorSpaceANDROID для сохранения.

Допустимое использование (подразумеваемое)

Функция xrGetAnchorPersistStateANDROID определяется следующим образом:

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

Описание параметров

  • handle — XrDeviceAnchorPersistenceANDROID .
  • anchorId — это XrUuidEXT якоря.
  • persistState — это указатель на XrAnchorPersistStateANDROID , в котором возвращается состояние якоря.
  • Если якорь XrUuidEXT не найден, будет возвращено XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID .
  • Если сохраненные данные anchorId не готовы, будет возвращено XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

Допустимое использование (подразумеваемое)

Коды возврата

Успех

  • 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

Перечисление XrAnchorPersistStateANDROID определяется как: 

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;

Перечисление

Описание

XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID

Приложение не запросило сохранение якоря.

XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID

Якорь был запрошен на сохранение, но пока не сохранен.

XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID

Якорь успешно сохранен средой выполнения.

Создать якорь из сохраненных данных

Функция xrCreatePersistedAnchorSpaceANDROID определяется следующим образом: 

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

Описание параметров

Приложение может создать якорь XrSpace из ранее сохраненного якоря, вызвав xrCreatePersistedAnchorSpaceANDROID с тем же XrUuidEXT . Это еще один способ создания якорей, как определено в XR_ANDROID_trackables .

  • Если якорь XrUuidEXT не найден, будет возвращено XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID .

Допустимое использование (подразумеваемое)

Коды возврата

Успех

  • 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

Структура XrPersistedAnchorSpaceCreateInfoANDROID определяется следующим образом: 

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

Описания участников

  • type — XrStructureType этой структуры.
  • next — NULL или указатель на следующую структуру в цепочке структур. Такие структуры не определены в ядре OpenXR или в этом расширении.
  • anchorId — это XrUuidEXT сохраненного якоря, из которого создается якорь XrSpace .

Структура XrPersistedAnchorSpaceCreateInfoANDROID предоставляет параметры создания якоря при передаче в xrCreateDeviceAnchorPersistenceANDROID .

Допустимое использование (подразумеваемое)

Перечислить постоянные якоря

Функция xrEnumeratePersistedAnchorsANDROID определяется следующим образом: 

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

Описание параметров

  • handle — XrDeviceAnchorPersistenceANDROID .
  • anchorIdsCapacityInput — емкость массива anchorIds или 0 для указания запроса на извлечение требуемой емкости.
  • anchorIdsCountOutput — указатель на количество записанных anchorIds или указатель на требуемую емкость в случае, если anchorIdsCapacityInput недостаточно.
  • anchorIds — указатель на массив структур XrUuidEXT . Может быть NULL , если anchorIdsCapacityInput равен 0.
  • Подробное описание получения требуемого размера anchorIds см. в разделе «Параметры размера буфера».

Приложение может перечислить все текущие сохраненные якоря, вызвав xrEnumeratePersistedAnchorsANDROID . anchorIds будет хранить UUID сохраненных якорей до емкости массива. Если емкости недостаточно, у приложений нет никаких гарантий относительно того, какие якоря будут возвращены.

Допустимое использование (подразумеваемое)

Коды возврата

Успех

  • 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

Удалить сохраняющийся якорь

Функция xrUnpersistAnchorANDROID определяется как: 

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

Описание параметров

Приложение может отменить сохранение сохраненного якоря, вызвав xrUnpersistAnchorANDROID и передав якорь XrUuidEXT для отмены сохранения.

  • Если сохраненные данные не готовы, будет возвращено XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID .
  • Если якорь XrUuidEXT не найден, будет возвращено XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID .

Допустимое использование (подразумеваемое)

Коды возврата

Успех

  • 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

Пример кода для сохранения якоря

В следующем примере кода показано, как проверять возможности системы, сохранять, перечислять и отменять сохранение якорей, а также создавать якорь из сохраненного якоря 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));

Новые типы объектов

Новые константы перечисления

Перечисление XrObjectType расширено с помощью:

  • XR_OBJECT_TYPE_DEVICE_ANCHOR_PERSISTENCE_ANDROID

Перечисление XrResult расширено:

  • 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

Перечисление XrStructureType расширено:

  • 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

Новые перечисления

Новые структуры

Новые функции

Проблемы

История версий

  • Редакция 1, 10.10.2024 (Кенни Веркемер)
    • Первоначальное описание расширения

OpenXR™ и логотип OpenXR являются товарными знаками компании Khronos Group Inc. и зарегистрированы в качестве товарного знака в Китае, Европейском Союзе, Японии и Великобритании.