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

Строка имени

XR_ANDROID_device_anchor_persistence

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

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

Зарегистрированный внутренний номер

458

Редакция

1

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

XR_EXT_uuid и XR_ANDROID_trackables

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

2024-10-10

IP-статус

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

Авторы

Нихав Джайн, 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 для запроса поддерживаемых типов.

Если XR_FALSE возвращается для supportsAnchorPersistence , то 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);

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

  • handle — это дескриптор XrDeviceAnchorPersistenceANDROID , ранее созданный с помощью xrCreateDeviceAnchorPersistenceANDROID .

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

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

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

  • Доступ к 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_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 , в котором возвращается состояние привязки.
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID будет возвращен, если привязка XrUuidEXT не найдена.
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID будет возвращен, если сохраненные anchorId не готовы.

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

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

Успех

  • 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 .

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

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

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

Успех

  • 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 будет возвращен, если сохраненные данные не готовы.
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID будет возвращен, если привязка XrUuidEXT не найдена.

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

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

Успех

  • 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;
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));

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

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

Перечисление 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 октября 2024 г. (Кенни Веркамер)
    • Первоначальное описание расширения