XR_ANDROID_avatar_eyes OpenXR 拡張機能

Name String

XR_ANDROID_avatar_eyes

拡張機能の種類

インスタンスの拡張

登録されている電話番号

457

リビジョン

1

拡張機能とバージョンの依存関係

OpenXR 1.0

最終更新日

2024-09-30

IP ステータス

既知の IP に関する申し立てはありません。

寄与者

Spencer Quin、Google

Jared Finder、Google

Levana Chen、Google

概要

この拡張機能により、アプリはユーザーの目の位置と向き、アイ トラッキング ステータスを取得できます。

この拡張機能は、アバターの目のポーズとステータスの表現をよりリアルにすることを目的としています。そのため、次の点にご注意ください。

  • 点滅など、トラッキングされていない状態を許可します。
  • 単眼または双眼のトラッキングが可能です。

この拡張機能は、他のアイトラッキング目的には使用しないでください。インタラクションには XR_EXT_eye_gaze_interaction を使用する必要があります。

アイ トラッカー

アイトラッカーは、目をトラッキングしてユーザーの視線を正確にマッピングするセンシング デバイスです。この拡張機能の主な目的は、ユーザーの視線を仮想シーン内のアバターにマッピングすることです。

アイトラッキング データは機密性の高い個人情報であり、個人のプライバシーと完全性と密接に関連しています。アイトラッキング データを保存または転送するアプリでは、常にユーザーにアクティブかつ明示的に同意を求めることを強くおすすめします。

  • アプリがアイトラッカーへのアクセスを許可されるまで、アプリがアクティブなアイトラッカーの作成を試みると、XR_ERROR_PERMISSION_INSUFFICIENT が返されます。

システムの機能を確認する

アプリは、xrGetSystemProperties を呼び出すときに XrSystemAvatarEyesPropertiesANDROID 構造を XrSystemProperties に連結することで、システムがアバターの目をサポートしているかどうかを検査できます。supportsAvatarEyes が XR_FALSE を返すと、アプリケーションは xrCreateEyeTrackerANDROID から XR_ERROR_FEATURE_UNSUPPORTED を受け取ります。

typedef struct XrSystemAvatarEyesPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAvatarEyes;
} XrSystemAvatarEyesPropertiesANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、そのような構造は定義されていません。
  • supportsAvatarEyes は XrBool32 で、現在のシステムがアバターの目をサポートしているかどうかを示します。

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

アイトラッカー ハンドルを作成する

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

XrEyeTrackerANDROID ハンドルは、目をトラッキングするためのアイトラッカーを表し、ユーザーが何を見ているかを正確にマッピングします。

このハンドルを使用すると、この拡張機能の他の関数を使用してアイトラッキング データにアクセスできます。

アイトラッキングは、シーン内の目の向きとステータスを表現します。

xrCreateEyeTrackerANDROID 関数は次のように定義されます。

XrResult xrCreateEyeTrackerANDROID(
    XrSession                                   session,
    const XrEyeTrackerCreateInfoANDROID*        createInfo,
    XrEyeTrackerANDROID*                        eyeTracker);

パラメータの説明

アプリケーションは、xrCreateEyeTrackerANDROID 関数を使用して XrEyeTrackerANDROID ハンドルを作成できます。

システムがアイトラッキングをサポートしていない場合、xrCreateEyeTrackerANDROID から XR_ERROR_FEATURE_UNSUPPORTED が返されます。

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

  • xrCreateEyeTrackerANDROID を呼び出す前に、XR_ANDROID_avatar_eyes 拡張機能を有効にする必要があります。
  • session は有効な XrSession ハンドルである必要があります。
  • createInfo は、有効な XrEyeTrackerCreateInfoANDROID 構造体へのポインタである必要があります。
  • eyeTracker は XrEyeTrackerANDROID ハンドルへのポインタである必要があります。

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • 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

XrEyeTrackerCreateInfoANDROID 構造体は次のように定義されます。

typedef struct XrEyeTrackerCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrEyeTrackerCreateInfoANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、そのような構造は定義されていません。

XrEyeTrackerCreateInfoANDROID 構造体には、XrEyeTrackerANDROID ハンドルを作成する情報が記述されています。

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

  • XrEyeTrackerCreateInfoANDROID を使用する前に、XR_ANDROID_avatar_eyes 拡張機能を有効にする必要があります。
  • type は XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID にする必要があります
  • next は NULL であるか、構造体チェーンの次の構造体を指す有効なポインタである必要があります。

xrDestroyEyeTrackerANDROID 関数は次のように定義されます。

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

パラメータの説明

xrDestroyEyeTrackerANDROID 関数は、アイトラッキング エクスペリエンスの終了時に eyeTracker と基盤となるリソースを解放します。

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

スレッドセーフ

  • eyeTracker と子ハンドルへのアクセスは、外部で同期する必要があります。

戻りコード

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

目の情報を取得する

xrGetEyesInfoANDROID 関数は次のように定義されます。

XrResult xrGetEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              infoOutput);

パラメータの説明

xrGetEyesInfoANDROID 関数は、目の状態とポーズに関する情報を取得します。

目の情報は、XrEyesGetInfoANDROID::time、XrEyesGetInfoANDROID::baseSpace を使用して xrGetEyesInfoANDROID を呼び出した時点で、ベース空間を基準に解決されます。

任意の時点で、目のポーズの位置と方向の両方がトラッキングまたはトラッキング解除されます。つまり、アプリケーションは、指定された XrEyesANDROID::eyes で XR_SPACE_LOCATION_POSITION_TRACKED_BIT と XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT の両方が設定またはクリアされること、および XrEyesANDROID::mode がトラッキング状態を示すことを確認できます。

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

  • xrGetEyesInfoANDROID を呼び出す前に、XR_ANDROID_avatar_eyes 拡張機能を有効にする必要があります。
  • eyeTracker は有効な XrEyeTrackerANDROID ハンドルである必要があります。
  • getInfo は、有効な XrEyesGetInfoANDROID 構造体へのポインタである必要があります。
  • infoOutput は XrEyesANDROID 構造体へのポインタである必要があります。

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • 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_TIME_INVALID

XrEyesGetInfoANDROID 構造体には、目のポーズと状態を取得するために必要な情報が含まれています。

typedef struct XrEyesGetInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrTime             time;
    XrSpace            baseSpace;
} XrEyesGetInfoANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、そのような構造は定義されていません。
  • time は、baseSpace を基準として座標を評価する XrTime です。
  • baseSpace 目のポーズは、time のこの XrSpace を基準とします。

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

  • XrEyesGetInfoANDROID を使用する前に、XR_ANDROID_avatar_eyes 拡張機能を有効にする必要があります。
  • type は XR_TYPE_EYES_GET_INFO_ANDROID にする必要があります
  • next は NULL であるか、構造体チェーンの次の構造体を指す有効なポインタである必要があります。
  • baseSpace は有効な XrSpace ハンドルである必要があります。

XrEyesANDROID 構造体には、トラッキングされた目の情報が含まれます。

typedef struct XrEyesANDROID {
    XrStructureType             type;
    void*                       next;
    XrEyeANDROID                eyes[XR_EYE_MAX_ANDROID];
    XrEyeTrackingModeANDROID    mode;
} XrEyesANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、そのような構造は定義されていません。
  • eyes は、XrEyeIndexANDROID でインデックス付けされた左目と右目の XrEyeANDROID の配列です。
  • mode は XrEyeTrackingModeANDROID で、目がトラッキングされているかどうかと、どの目がトラッキングされているかを指定します。

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

  • XrEyesANDROID を使用する前に、XR_ANDROID_avatar_eyes 拡張機能を有効にする必要があります。
  • type は XR_TYPE_EYES_ANDROID にする必要があります
  • next は NULL であるか、構造体チェーンの次の構造体を指す有効なポインタである必要があります。
  • eyes の任意の要素は、有効な XrEyeANDROID 構造体である必要があります。
  • mode は有効な XrEyeTrackingModeANDROID 値である必要があります。

XrEyeANDROID 構造は、目の状態、位置、向きを記述します。

typedef struct XrEyeANDROID {
    XrEyeStateANDROID    eyeState;
    XrPosef              eyePose;
} XrEyeANDROID;

メンバーの説明

  • eyeState は、目の XrEyeStateANDROID です。
  • pose は、対応する XrEyesGetInfoANDROID::baseSpace の参照フレーム内の目の原点の位置と向きを定義する XrPosef です。ここでの ID の向きは、+Z がユーザーの眼、+X が右、+Y が上になる座標軸を表します。

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

  • XrEyeANDROID を使用する前に、XR_ANDROID_avatar_eyes 拡張機能を有効にする必要があります。
  • eyeState は有効な XrEyeStateANDROID 値である必要があります。

XrEyeStateANDROID 列挙型は、トラッキングされた目のさまざまな状態を識別します。

typedef enum XrEyeStateANDROID {
    XR_EYE_STATE_INVALID_ANDROID = 0,
    XR_EYE_STATE_GAZING_ANDROID = 1,
    XR_EYE_STATE_SHUT_ANDROID = 2
} XrEyeStateANDROID;

列挙型の意味は次のとおりです。

列挙型

説明

XR_EYE_STATE_INVALID_ANDROID

目がエラー状態であるか、存在しないことを示します。

XR_EYE_STATE_GAZING_ANDROID

目を凝らしていることを示します。

XR_EYE_STATE_SHUT_ANDROID

ウィンクや瞬きによって目が閉じていることを示します。

XrEyeIndexANDROID 列挙型は、左目または右目のインデックスを識別します。

typedef enum XrEyeIndexANDROID {
    XR_EYE_INDEX_LEFT_ANDROID = 0,
    XR_EYE_INDEX_RIGHT_ANDROID = 1
} XrEyeIndexANDROID;

列挙型の意味は次のとおりです。

列挙型

説明

XR_EYE_INDEX_LEFT_ANDROID

左目。

XR_EYE_INDEX_RIGHT_ANDROID

右目。

XrEyeTrackingModeANDROID 列挙型は、トラッキングされた目のさまざまなモードを識別します。

typedef enum XrEyeTrackingModeANDROID {
    XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID = 0,
    XR_EYE_TRACKING_MODE_RIGHT_ANDROID = 1,
    XR_EYE_TRACKING_MODE_LEFT_ANDROID = 2,
    XR_EYE_TRACKING_MODE_BOTH_ANDROID = 3
} XrEyeTrackingModeANDROID;

列挙型の意味は次のとおりです。

列挙型

説明

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

アイトラッキングが有効になっていないことを示します。

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

右目のみがトラッキングされていることを示します。

XR_EYE_TRACKING_MODE_LEFT_ANDROID

左目のみがトラッキングされていることを示します。

XR_EYE_TRACKING_MODE_BOTH_ANDROID

左目と右目の両方がトラッキングされていることを示します。

アイトラッキングのサンプルコード

次のサンプルコードは、ビュー空間を基準とした目の情報を取得する方法を示しています。

XrSession session; // previously initialized, for example, created at app startup.
XrSpace viewSpace; // space created for XR_REFERENCE_SPACE_TYPE_VIEW.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateEyeTrackerANDROID xrCreateEyeTrackerANDROID; // previously initialized
PFN_xrDestroyEyeTrackerANDROID xrDestroyEyeTrackerANDROID; // previously initialized
PFN_xrGetEyesInfoANDROID xrGetEyesInfoANDROID; // previously initialized

// This will use the XrSession that is bound to the eye tracker done at time of creation.
XrEyeTrackerANDROID eyeTracker;
XrEyeTrackerCreateInfoANDROID createInfo{
    .type = XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID,
    .next = nullptr};
CHK_XR(xrCreateEyeTrackerANDROID(session, &createInfo, &eyeTracker));

while (1) {
    // ...
    // For every frame in frame loop
    // ...

    XrFrameState frameState;  // previously returned from xrWaitFrame
    const XrTime time = frameState.predictedDisplayTime;
    XrEyesANDROID eyesInfo{.type = XR_TYPE_EYES_ANDROID,
                           .next = nullptr,
                           .mode = XR_EYE_TRACKING_MODE_BOTH_ANDROID};
    XrEyesGetInfoANDROID eyesGetInfo{.type = XR_TYPE_EYES_GET_INFO_ANDROID,
                                     .next = nullptr,
                                     .time = time,
                                     .baseSpace = viewSpace};
    CHK_XR(xrGetEyesInfoANDROID(eyeTracker, &eyesGetInfo, &eyesInfo));

    // eyes tracking information is now available:
    // drawLeftEye(eyesInfo.eyes[XR_EYE_INDEX_LEFT_ANDROID].eyePose);
    // drawRightEye(eyesInfo.eyes[XR_EYE_INDEX_RIGHT_ANDROID].eyePose);

    // ...
    // Finish frame loop
    // ...
}

// after usage
CHK_XR(xrDestroyEyeTrackerANDROID(eyeTracker));

新しいオブジェクト タイプ

新しい列挙型定数

  • XR_EYE_MAX_ANDROID

XrObjectType 列挙型が拡張され、次のように変更されました。

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

XrStructureType 列挙型が拡張され、次のように変更されました。

  • XR_TYPE_EYES_ANDROID
  • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_EYES_GET_INFO_ANDROID
  • XR_TYPE_SYSTEM_AVATAR_EYES_PROPERTIES_ANDROID

新しい列挙型

新しい構造

新機能

問題

変更履歴

  • リビジョン 1、2024-09-04（Levana Chen）
    • 最初の拡張機能の説明