XR_ANDROID_raycast OpenXR 扩展

名称字符串

XR_ANDROID_raycast

扩展程序类型

实例扩展

已注册的扩展号码

464

修订版本

1

扩展程序和版本依赖项

XR_ANDROID_trackables

上次修改日期

2024-10-02

IP 状态

没有已知的 IP 版权主张。

创作贡献者

Spencer Quin，Google

Nihav Jain，Google

John Pursey，Google

Jared Finder，Google

Levana Chen，Google

Kenny Vercaemer，Google

概览

借助此扩展程序，应用可以对环境中的可跟踪对象执行光线投射。光线投射对于检测环境中与光线相交的物体非常有用。例如：

  • 使用垂直射线投射来确定悬浮物体在掉落时会落在何处。
  • 使用正向光线投射来确定用户正在看向何处。

查询支持的光线投射功能

xrEnumerateRaycastSupportedTrackableTypesANDROID 函数的定义如下：

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

参数说明

  • instance 是检索 systemId 的 XrInstance。
  • systemId 是 XrSystemId，其支持的光线追踪可跟踪类型正在枚举。
  • trackableTypeCapacityInput 是 trackableTypes 的容量，或 0（用于检索所需的容量）。
  • trackableTypeCountOutput 是指向数组计数的指针，如果 trackableTypeCapacityInput 不足，则是指向所需容量的指针。
    • trackableTypes 是指向 XrTrackableTypeANDROID 数组的指针，但如果 trackableTypeCapacityInput 为 0，则可以为 NULL。
  • 如需详细了解如何检索所需的 trackableTypes 大小，请参阅缓冲区大小参数部分。

xrEnumerateRaycastSupportedTrackableTypesANDROID 会枚举当前会话支持射线投射的可跟踪类型。

有效用法（隐式）

返回代码

成功

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

参数说明

应用可以通过调用 xrRaycastANDROID 执行光线投射。

有效用法（隐式）

返回代码

成功

  • 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 是 trackers 数组的 uint32_t 计数。
  • trackers 是投射的光线应针对其进行测试的 XrTrackableTrackerANDROID 数组。
  • origin 是发射光线的 XrVector3f。
  • trajectory 是光线的目标 XrVector3f。
  • space 是发射光线的 XrSpace。
  • time 是发射光线的 XrTime。

XrRaycastInfoANDROID 结构描述了要投射的光线。

有效用法（隐式）

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 结构数组的指针。如果 resultsCapacityInput 为 0，则 可以为 NULL。
  • 如需详细了解如何检索所需的 results 大小，请参阅缓冲区大小参数部分。

XrRaycastHitResultsANDROID 包含射线的命中数组。

运行时必须将 resultsCountOutput 设置为小于或等于 XrRaycastInfoANDROID::maxResults。

有效用法（隐式）

XrRaycastHitResultANDROID 结构的定义如下： 

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

成员说明

  • type 是光线投射命中的可跟踪对象的 XrTrackableTypeANDROID。
  • trackable 是光线投射命中的 XrTrackableANDROID，如果可跟踪的 type 为 XR_TRACKABLE_TYPE_DEPTH_ANDROID，则为 XR_NULL_TRACKABLE_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，2024 年 10 月 2 日 (Kenny Vercaemer)
    • 初始扩展程序说明

OpenXR™ 和 OpenXR 徽标是 Khronos Group Inc. 拥有的商标，已在中国、欧盟、日本和英国注册为商标。