Android XR SDK 现已推出开发者预览版。我们期望收到您的反馈！请访问我们的支持页面与我们联系。

此页面由 Cloud Translation API 翻译。

XR_ANDROID_raycast OpenXR 扩展

名称字符串

XR_ANDROID_raycast

扩展程序类型

实例扩展

已注册的扩展号码

464

修订版本

扩展程序和版本依赖项

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_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 的指针。

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

如果光线与的跟踪器数量超过 XrRaycastHitResultsANDROID::maxResults，则运行时必须返回与光线的 XrRaycastHitResultsANDROID::origin 最接近的命中结果。
如果光线投射与类型为 XR_TRACKABLE_TYPE_ANDROID_PLANE 且被另一个平面包含的可跟踪对象相交，则运行时必须仅返回包含该平面的平面的命中结果。
运行时必须按从 XrRaycastInfoANDROID::origin 沿 XrRaycastInfoANDROID::trajectory 矢量从最近到最远的顺序返回命中结果。
如果 xrEnumerateRaycastSupportedTrackableTypesANDROID 未枚举 XrRaycastInfoANDROID::trackers 中与 XrTrackableTrackerANDROID 句柄对应的可跟踪类型，则运行时必须返回 XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID。

有效用法（隐式）

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

XrRaycastHitResultsANDROID 包含射线的命中数组。

运行时必须将 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，如果可跟踪的 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`	使用整个场景的深度信息来确定点的正确深度和方向。

有效用法（隐式）

必须先启用 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

新结构

XrRaycastInfoANDROID
XrRaycastHitResultANDROID
XrRaycastHitResultsANDROID

新函数

xrEnumerateRaycastSupportedTrackableTypesANDROID
xrRaycastANDROID

问题

版本历史记录

修订版 1，2024 年 10 月 2 日 (Kenny Vercaemer)
- 初始扩展程序说明