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

Строка имени

XR_ANDROID_raycast

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

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

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

464

Редакция

1

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

XR_ANDROID_trackables

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

2024-10-02

IP-статус

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

Авторы

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

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

Джон Пёрси, Google

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

Левана Чен, Google

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

Обзор

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

  • Определить, куда упадет плавающий объект при падении, с помощью вертикального рейкаста.
  • Чтобы определить, куда смотрит пользователь, с помощью направленного вперед рейкаста.

Возможности raycast, поддерживаемые запросами

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

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

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

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

xrEnumerateRaycastSupportedTrackableTypesANDROID перечисляет отслеживаемые типы, которые поддерживают рассылку лучей в текущем сеансе.

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

  • Расширение XR_ANDROID_raycast должно быть включено до вызова xrEnumerateRaycastSupportedTrackableTypesANDROID.
  • instance должен быть действительным дескриптором XrInstance
  • trackableTypeCountOutput должен быть указателем на значение uint32_t
  • Если trackableTypeCapacityInput не равен 0 , trackableTypes должен быть указателем на массив значений trackableTypeCapacityInput XrTrackableTypeANDROID.

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

Успех

  • XR_SUCCESS

Отказ

  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED

Выполнить рейкаст

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

XrResult xrRaycastANDROID(
    XrSession                                   session,
    const XrRaycastInfoANDROID*                 rayInfo,
    XrRaycastHitResultsANDROID*                 results);

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

  • session — это XrSession , который выполняет рейкаст.
  • rayInfo — это XrRaycastInfoANDROID , описывающий луч, который нужно передать.
  • results — это указатель на XrRaycastHitResultsANDROID , который получает результаты raycast.

Приложение может выполнять рассылку лучей, вызывая xrRaycastANDROID .

  • Если raycast пересекает больше отслеживаемых объектов, чем XrRaycastHitResultsANDROID::maxResults , среда выполнения должна вернуть результаты попадания, которые наиболее близки к XrRaycastHitResultsANDROID::origin луча.
  • Если raycast пересекает отслеживаемый объект типа XR_TRACKABLE_TYPE_ANDROID_PLANE , который включен в состав другой плоскости, среда выполнения должна вернуть результат попадания только для включающей плоскости.
  • Среда выполнения должна возвращать результаты попадания в порядке от ближайшего к дальнему от XrRaycastInfoANDROID::origin вдоль вектора траектории XrRaycastInfoANDROID::trajectory .
  • Среда выполнения должна вернуть XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID , если отслеживаемый тип, соответствующий дескрипторам XrTrackableTrackerANDROID в XrRaycastInfoANDROID::trackers, не перечисляется в xrEnumerateRaycastSupportedTrackableTypesANDROID .

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

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID
  • 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_POSE_INVALID
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_FEATURE_UNSUPPORTED

Структура XrRaycastInfoANDROID определяется как:

typedef struct XrRaycastInfoANDROID {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            maxResults;
    uint32_t                            trackerCount;
    const XrTrackableTrackerANDROID*    trackers;
    XrVector3f                          origin;
    XrVector3f                          trajectory;
    XrSpace                             space;
    XrTime                              time;
} XrRaycastInfoANDROID;

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

  • type — это XrStructureType этой структуры.
  • next имеет значение NULL или указатель на следующую структуру в цепочке структур. Такие структуры не определены в ядре OpenXR или этом расширении.
  • maxResults — это максимальное количество возвращаемых результатов uint32_t .
  • trackerCount — это счетчик uint32_t массива trackers .
  • trackers — это массив XrTrackableTrackerANDROID , на котором должен быть проверен приведенный луч.
  • origin — это XrVector3f , из которого создается луч.
  • trajectory — это XrVector3f , на который нацелен луч.
  • space — это XrSpace , в котором создается луч.
  • time — это XrTime в которое создается луч.

Структура XrRaycastInfoANDROID описывает луч, который необходимо передать.

  • Массив XrRaycastInfoANDROID::trackers может содержать трекеры разных типов.
  • Массив XrRaycastInfoANDROID::trackers не должен содержать несколько трекеров одного типа, иначе среда выполнения должна вернуть XR_ERROR_VALIDATION_FAILURE .

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

  • Расширение XR_ANDROID_raycast необходимо включить перед использованием XrRaycastInfoANDROID.
  • type должен быть XR_TYPE_RAYCAST_INFO_ANDROID
  • next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
  • trackers должны быть указателями на массив действительных trackerCount XrTrackableTrackerANDROID.
  • space должен быть действительным дескриптором XrSpace
  • Параметр trackerCount должен быть больше 0
  • И space , и элементы trackers должны быть созданы, выделены или получены из одного и того же сеанса XrSession.

Структура XrRaycastHitResultsANDROID определяется как:

typedef struct XrRaycastHitResultsANDROID {
    XrStructureType               type;
    void*                         next;
    uint32_t                      resultsCapacityInput;
    uint32_t                      resultsCountOutput;
    XrRaycastHitResultANDROID*    results;
} XrRaycastHitResultsANDROID;

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

  • type — это XrStructureType этой структуры.
  • next имеет значение NULL или указатель на следующую структуру в цепочке структур. Такие структуры не определены в ядре OpenXR или этом расширении.
  • resultsCapacityInput — это емкость массива results или 0, чтобы указать запрос на получение необходимой емкости.
  • resultsCountOutput — это указатель на количество записанных results или указатель на требуемую емкость в случае, если resultsCapacityInput недостаточен.
  • results — это указатель на массив структур XrRaycastHitResultANDROID . Оно может быть NULL если resultsCapacityInput равен 0.
  • См. раздел «Параметры размера буфера» для подробного описания получения требуемого размера results .

XrRaycastHitResultsANDROID содержит массив попаданий raycast.

Среда выполнения должна установить значение resultsCountOutput меньшее или равное XrRaycastInfoANDROID::maxResults .

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

Структура XrRaycastHitResultANDROID определяется как:

typedef struct XrRaycastHitResultANDROID {
    XrTrackableTypeANDROID    type;
    XrTrackableANDROID        trackable;
    XrPosef                   pose;
} XrRaycastHitResultANDROID;

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

  • type — это XrTrackableTypeANDROID отслеживаемого объекта, на который попал луч.
  • trackable — это XrTrackableANDROID , на который попал луч, или XR_NULL_TRACKABLE_ANDROID если отслеживаемый type был XR_TRACKABLE_TYPE_DEPTH_ANDROID .
  • pose — это XrPosef , на который попал луч.

XrRaycastHitResultANDROID содержит сведения о попадании лучей.

XrRaycastHitResultANDROID::pose для удара по плоскости должен быть таким, чтобы X и Z были параллельны плоскости, а ось Y была перпендикулярна плоскости.

Тип отслеживаемого обращения

Описание

XR_TRACKABLE_TYPE_PLANE_ANDROID

Ударяется по горизонтальным и/или вертикальным поверхностям, чтобы определить правильную глубину и ориентацию точки.

XR_TRACKABLE_TYPE_DEPTH_ANDROID

Использует информацию о глубине всей сцены для определения правильной глубины и ориентации точки.

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

Пример кода для рейкастинга

В следующем примере кода показано, как выполнять рассылку лучей.

XrSession session; // previously initialized
XrTime updateTime; // previously initialized
XrSpace appSpace;  // space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrPosef headPose;  // latest pose of the HMD.
XrTrackableTrackerANDROID planeTracker; // tracker for plane trackables.
XrTrackableTrackerANDROID depthTracker; // tracker for depth trackables.

// Perform a raycast against multiple trackers.
XrTrackableTrackerANDROID trackers[] = {
  &planeTracker,
  &depthTracker,
};
XrRaycastInfoANDROID rayInfo = {XR_TYPE_RAYCAST_INFO_ANDROID};
rayInfo.trackerCount = sizeof(trackers) / sizeof(XrTrackableTrackerANDROID);
rayInfo.trackers = trackers;
rayInfo.origin = headPose.position;
rayInfo.trajectory = CalculateForwardDirectionFromHeadPose(headPose);
rayInfo.space = appSpace;
rayInfo.time = updateTime;

uint32_t totalHitResults = 0;
constexpr uint32 NUM_DESIRED_RESULTS = 2;
XrRaycastHitResultANDROID hitResult[NUM_DESIRED_RESULTS];
XrRaycastHitResultsANDROID hitResults = {XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID};
hitResults.maxResults = NUM_DESIRED_RESULTS;
hitResults.resultsCapacityInput = NUM_DESIRED_RESULTS;
hitResults.results = hitResult;
XrResult result = xrRaycastANDROID(session, &rayInfo, &hitResults);

if (result == XR_SUCCESS && hitResults.resultsCountOutput >= 1) {
  // Hit results are returned in closest-to-farthest order in
  // hitResults.results[0] .. hitResults.results[hitResults.resultsCountOutput - 1]
}

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

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

  • XR_TYPE_RAYCAST_INFO_ANDROID
  • XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

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

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

Проблемы

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

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