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

Имя Строка

XR_ANDROID_trackables_object

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

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

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

467

Пересмотр

1

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

XR_ANDROID_trackables

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

2024-11-01

Статус ИС

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

Участники

Диего Типальди, Google

Дэвид Джозеф Тан, Google

Кристофер Доер, Google

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

Джаред Файндер, Google

Левана Чен, Google

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

Обзор

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

Отслеживать объекты

Это расширение добавляет XR_TRACKABLE_TYPE_OBJECT_ANDROID к XrTrackableTypeANDROID .

Приложение может создать XrTrackableTrackerANDROID , вызвав xrCreateTrackableTrackerANDROID и указав XR_TRACKABLE_TYPE_OBJECT_ANDROID в качестве отслеживаемого типа в XrTrackableTrackerCreateInfoANDROID::trackableType для отслеживания объектов.

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

typedef struct XrTrackableObjectConfigurationANDROID {
    XrStructureType                type;
    void*                          next;
    uint32_t                       labelCount;
    const XrObjectLabelANDROID*    activeLabels;
} XrTrackableObjectConfigurationANDROID;

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

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

Приложение может задать дополнительную конфигурацию, добавив XrTrackableObjectConfigurationANDROID к следующей цепочке XrTrackableTrackerCreateInfoANDROID . Выходные данные из xrGetAllTrackablesANDROID будут отфильтрованы для соответствия activeLabels .

Если приложение не устанавливает XrTrackableObjectConfigurationANDROID , то будут отслеживаться все объекты, которые идентифицировала система.

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

• Перед использованием XrTrackableObjectANDROID необходимо включить расширение XR_ANDROID_trackables_object
• type должен быть XR_TYPE_TRACKABLE_OBJECT_ANDROID
• next должен быть NULL или действительным указателем на следующую структуру в цепочке структур
• activeLabels должен быть указателем на массив из labelCount допустимых значений XrObjectLabelANDROID
• Параметр labelCount должен быть больше 0

Перечисление XrObjectLabelANDROID представляет собой метку для объекта XrTrackableANDROID .

typedef enum XrObjectLabelANDROID {
    XR_OBJECT_LABEL_UNKNOWN_ANDROID = 0,
    XR_OBJECT_LABEL_KEYBOARD_ANDROID = 1,
    XR_OBJECT_LABEL_MOUSE_ANDROID = 2,
    XR_OBJECT_LABEL_LAPTOP_ANDROID = 3,
    XR_OBJECT_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrObjectLabelANDROID;

Получить отслеживаемый объект

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

XrResult xrGetTrackableObjectANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableObjectANDROID*                   objectOutput);

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

• tracker — это XrTrackableTrackerANDROID для запроса.
• getInfo — это XrTrackableGetInfoANDROID с информацией, используемой для получения отслеживаемого объекта.
• objectOutput — указатель на структуру XrTrackableObjectANDROID , в которой возвращается отслеживаемый объект.

XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID будет возвращен, если отслеживаемый тип XrTrackableANDROID не является XR_TRACKABLE_TYPE_OBJECT_ANDROID или если отслеживаемый тип XrTrackableTrackerANDROID не является XR_TRACKABLE_TYPE_OBJECT_ANDROID .

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

• Расширение XR_ANDROID_trackables_object должно быть включено перед вызовом xrGetTrackableObjectANDROID
• tracker должен быть действительным дескриптором XrTrackableTrackerANDROID
• getInfo должен быть указателем на допустимую структуру XrTrackableGetInfoANDROID
• objectOutput должен быть указателем на структуру XrTrackableObjectANDROID

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

Успех

• 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_SESSION_NOT_RUNNING
• XR_ERROR_TIME_INVALID
• XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID

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

typedef struct XrTrackableObjectANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrPosef                   centerPose;
    XrExtent3DfEXT            extents;
    XrObjectLabelANDROID      objectLabel;
    XrTime                    lastUpdatedTime;
} XrTrackableObjectANDROID;

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

• type — XrStructureType этой структуры.
• next — NULL или указатель на следующую структуру в цепочке структур. Такие структуры не определены в ядре OpenXR или в этом расширении.
• trackingState — это XrTrackingStateANDROID объекта.
• centerPose — это XrPosef объекта, расположенного в XrTrackableGetInfoANDROID::baseSpace .
• extents — это размерность XrExtent3DfEXT объекта.
• objectLabel — это XrObjectLabelANDROID , который среда выполнения определила для этого объекта.
• lastUpdatedTime — это XrTime последнего обновления объекта.

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

• Перед использованием XrTrackableObjectANDROID необходимо включить расширение XR_ANDROID_trackables_object
• type должен быть XR_TYPE_TRACKABLE_OBJECT_ANDROID
• next должен быть NULL или действительным указателем на следующую структуру в цепочке структур
• trackingState должен быть допустимым значением XrTrackingStateANDROID
• objectLabel должен быть допустимым значением XrObjectLabelANDROID

Пример кода для получения отслеживаемых объектов

Следующий пример кода демонстрирует, как получить отслеживаемые объекты.

XrSession session; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // previously initialized
PFN_xrGetTrackableObjectANDROID xrGetTrackableObjectANDROID; // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.

XrTrackableTrackerCreateInfoANDROID
  createInfo{XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID};
createInfo.trackableType = XR_TRACKABLE_TYPE_OBJECT_ANDROID;
XrTrackableTrackerANDROID objectTrackableTracker;
XrResult result = xrCreateTrackableTrackerANDROID(
  session,
  &createInfo,
  &objectTrackableTracker);
if (result != XR_SUCCESS) { /* Handle failures. */ }

uint32_t trackableCountOutput = 0;
std::vector<XrTrackableANDROID> allObjectTrackables;

// Query the number of trackables available.
result = xrGetAllTrackablesANDROID(
  objectTrackableTracker,
  0,
  &trackableCountOutput,
  nullptr
);

if (result == XR_SUCCESS) {
  allObjectTrackables.resize(trackableCountOutput, XR_NULL_TRACKABLE_ANDROID);

  // Fetch the actual trackable handles in the appropriately resized array.
  result = xrGetAllTrackablesANDROID(
    objectTrackableTracker,
    trackableCountOutput,
    &trackableCountOutput,
    allObjectTrackables.data());

  if (result == XR_SUCCESS) {
    for (XrTrackableANDROID trackable : allObjectTrackables) {

      // Object trackable query information
      XrTrackableGetInfoANDROID objectGetInfo;
      objectGetInfo.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID;
      objectGetInfo.next = nullptr;
      objectGetInfo.trackable = trackable;
      objectGetInfo.baseSpace = appSpace;
      objectGetInfo.time = updateTime;

      // Get the object trackable. Note that the tracker only returns object types.
      XrTrackableObjectANDROID object = { XR_TYPE_TRACKABLE_OBJECT_ANDROID };
      result = xrGetTrackableObjectANDROID(
        objectTrackableTracker,
        &objectGetInfo,
        &object
      );

      if (result == XR_SUCCESS) {
        /** Do Stuff with the object */
      }
    }
  }
}

// Release trackable tracker.
result = xrDestroyTrackableTrackerANDROID(objectTrackableTracker);

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

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

• XR_TYPE_TRACKABLE_OBJECT_ANDROID
• XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

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

• XR_TRACKABLE_TYPE_OBJECT_ANDROID

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

• XrObjectLabelANDROID

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

• XrTrackableObjectANDROID
• XrTrackableObjectConfigurationANDROID

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

• xrGetTrackableObjectANDROID

Проблемы

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

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

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