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 は、現在のセッションによるレイキャスティングをサポートするトラッキング可能なタイプを列挙します。

有効な使用方法（暗黙的）

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

パラメータの説明

アプリは 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 構造体には、キャストするレイが記述されます。

  • 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 以下に設定する必要があります。

有効な使用方法（暗黙的）

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-02（Kenny Vercaemer）
    • 最初の拡張機能の説明