Android XR SDK 現已在開發人員預覽版中推出。敬請提供意見回饋！請前往支援頁面與我們聯絡。

本頁面由 Cloud Translation API 翻譯而成。

XR_ANDROID_raycast OpenXR 擴充功能

名稱字串

XR_ANDROID_raycast

擴充功能類型

執行個體擴充功能

已註冊的擴充號碼

464

修訂版本

擴充功能和版本依附元件

XR_ANDROID_trackables

上次修改日期

2024-10-02

IP 狀態

著作人

Spencer Quin，Google

Nihav Jain，Google

Google 的 John Pursey

Jared Finder，Google

Levana Chen，Google

Google 的 Kenny Vercaemer

總覽

這項擴充功能可讓應用程式針對環境中的可追蹤項目執行光線投射。如要偵測光線會與其交會的環境中的物體，可使用光線投射。例如：

使用垂直的光線投射，判斷浮動物體掉落時會落在哪裡。
使用前向光線投射，判斷使用者正在看哪裡。

查詢支援的光線投射功能

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::trajectory 向量從 XrRaycastInfoANDROID::origin 傳回命中結果。
如果 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 陣列，系統會針對經過轉換的 ray 應測試這個陣列。
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 陣列的指標，該陣列包含 XrRaycastHitResult 以 ANDROID 為基礎的結構體
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-02 (Kenny Vercaemer)
- 初始擴充功能說明