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

XR_ANDROID_raycast OpenXR 扩展

名称字符串

XR_ANDROID_raycast

扩展类型

实例扩展

已注册扩展编号

464

修订版

扩展和版本依赖项

XR_ANDROID_trackables

上次修改日期

2024-10-02

知识产权状态

无已知知识产权主张。

贡献者

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 枚举当前会话支持射线投射的可跟踪类型。

有效用法（隐式）

在调用 xrEnumerateRaycastSupportedTrackableTypesANDROID 之前，**必须**启用 XR_ANDROID_raycast 扩展。
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 向量从近到远的顺序返回命中结果。
如果 XrRaycastInfoANDROID::trackers 中的 XrTrackableTrackerANDROID 句柄对应的可跟踪类型未被 xrEnumerateRaycastSupportedTrackableTypesANDROID 枚举，则运行时**必须**返回 XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID。

有效用法（隐式）

在调用 xrRaycastANDROID 之前，**必须**启用 XR_ANDROID_raycast 扩展。
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。

有效用法（隐式）

在使用 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 结构数组的指针。如果 resultsCapacityInput 为 0，则**可以**为 NULL。
有关检索所需 results 大小的详细说明，请参阅“缓冲区大小参数”部分。

XrRaycastHitResultsANDROID 包含射线投射的命中数组。

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

有效用法（隐式）

在使用 XrRaycastHitResultsANDROID 之前，**必须**启用 XR_ANDROID_raycast 扩展。
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`	使用整个场景的深度信息来确定点的正确深度和方向。

有效用法（隐式）

在使用 XrRaycastHitResultANDROID 之前，**必须**启用 XR_ANDROID_raycast 扩展。
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-02 (Kenny Vercaemer)
- 初始扩展描述

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

XR_ANDROID_raycast OpenXR 扩展 使用收藏夹保持井然有序 根据您的偏好保存和分类内容。

概览

查询支持的射线投射功能

参数说明

有效用法（隐式）

返回代码

执行射线投射

参数说明

有效用法（隐式）

返回代码

成员说明

有效用法（隐式）

成员说明

有效用法（隐式）

成员说明

有效用法（隐式）

射线投射示例代码

XR_ANDROID_raycast OpenXR 扩展