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

Имя Строка

XR_ANDROID_raycast

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

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

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

464

Пересмотр

1

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

XR_ANDROID_trackables

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

2024-10-02

Статус ИС

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

Участники

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

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

Джон Перси, Google

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

Левана Чен, Google

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

Обзор

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

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

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

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

• Расширение 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

Выполнить raycast

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

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

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

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

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

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

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

• Расширение XR_ANDROID_raycast должно быть включено перед вызовом xrRaycastANDROID
• session должен быть действительным дескриптором XrSession
• rayInfo должен быть указателем на допустимую структуру XrRaycastInfoANDROID
• results должны быть указателем на структуру XrRaycastHitResultsANDROID

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

Успех

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

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

• Перед использованием XrRaycastInfoANDROID необходимо включить расширение XR_ANDROID_raycast
• 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 .

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

• Расширение XR_ANDROID_raycast должно быть включено перед использованием XrRaycastHitResultsANDROID
• type должен быть XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID
• next должен быть NULL или действительным указателем на следующую структуру в цепочке структур
• results должен быть указателем на массив структур на основе resultsCapacityInput XrRaycastHitResultANDROID
• Параметр resultsCapacityInput должен быть больше 0

Структура 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 содержит сведения о попадании raycast.

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

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

• Расширение XR_ANDROID_raycast должно быть включено перед использованием XrRaycastHitResultANDROID
• type должен быть допустимым значением XrTrackableTypeANDROID

Пример кода для raycasting

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

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

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

• XrRaycastInfoANDROID
• XrRaycastHitResultANDROID
• XrRaycastHitResultsANDROID

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

• xrEnumerateRaycastПоддерживаемыеТрекируемыеТипыANDROID
• xrRaycastANDROID

Проблемы

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

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

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