Строка имени
XR_ANDROID_raycast
Тип расширения
Расширение экземпляра
Зарегистрированный внутренний номер
464
Редакция
1
Зависимости расширений и версий
Дата последнего изменения
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_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
.
Допустимое использование (неявное)
- Расширение
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 .
Допустимое использование (неявное)
- Расширение
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 содержит сведения о попадании лучей.
XrRaycastHitResultANDROID::pose для удара по плоскости должен быть таким, чтобы X и Z были параллельны плоскости, а ось Y была перпендикулярна плоскости.
Тип отслеживаемого обращения | Описание |
| Ударяется по горизонтальным и/или вертикальным поверхностям, чтобы определить правильную глубину и ориентацию точки. |
| Использует информацию о глубине всей сцены для определения правильной глубины и ориентации точки. |
Допустимое использование (неявное)
- Расширение
XR_ANDROID_raycast
необходимо включить перед использованием XrRaycastHitResultANDROID. -
type
должен быть допустимым значением XrTrackableTypeANDROID.
Пример кода для рейкастинга
В следующем примере кода показано, как выполнять рассылку лучей.
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 г. (Кенни Веркамер)
- Первоначальное описание расширения