Android XR for OpenXR | Android Developers

Android XR SDK 已推出開發人員預覽版 3，歡迎提供意見！歡迎試用，如有任何問題，請前往支援頁面與我們聯絡。

XR_ANDROID_eye_tracking

名稱字串

XR_ANDROID_eye_tracking

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

457

修訂版本

批准狀態

未批准

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2025-01-17

IP 狀態

未發現任何智慧財產權聲明。

著作人

Google 的 Spencer Quin
Google 的 Jared Finder
Google 的 Levana Chen
Google 的 Kenny Vercaemer
Google 的 Prasanthi Gurumurthy
Google 的 Nihav Jain

總覽

這項擴充功能可讓應用程式取得使用者眼睛的位置和方向，以及眼動追蹤狀態。

眼動追蹤資料分為粗略和精細兩種模式。粗略追蹤功能會粗略估算使用者的眼睛位置，精細追蹤功能則會提供更準確的估算結果。粗略追蹤適用於想提供基本虛擬人偶呈現方式的應用程式，精細追蹤則適用於更精確的應用程式。

如要互動，XR_EXT_eye_gaze_interaction 應使用。

權限

Android 應用程式必須在資訊清單中列出 android.permission.EYE_TRACKING_COARSE 或 android.permission.EYE_TRACKING_FINE 權限。這些權限視為危險權限。應用程式必須在執行階段要求權限，才能使用下列函式：

xrCreateEyeTrackerANDROID (至少一項權限)
xrGetCoarseTrackingEyesInfoANDROID (android.permission.EYE_TRACKING_COARSE)
xrGetFineTrackingEyesInfoANDROID (android.permission.EYE_TRACKING_FINE)

(防護等級：危險)

檢查系統功能

XrSystemEyeTrackingPropertiesANDROID 結構體的定義如下：

typedef struct XrSystemEyeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsEyeTracking;
} XrSystemEyeTrackingPropertiesANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
supportsEyeTracking 是 XrBool32，指出目前系統是否支援眼動追蹤。

應用程式可以在呼叫 xrGetSystemProperties 時，使用 XrSystemEyeTrackingPropertiesANDROID 結構體擴充 XrSystemProperties，檢查系統是否支援眼動追蹤。

只有在執行階段為 supportsEyeTracking 傳回 XR_FALSE 時，執行階段必須從 xrCreateEyeTrackerANDROID 傳回 XR_ERROR_FEATURE_UNSUPPORTED。

有效用量 (隱含)

XR_ANDROID_eye_tracking 擴充功能必須先啟用，才能使用 XrSystemEyeTrackingPropertiesANDROID
 type 必須為 XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID
next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標

建立眼球追蹤器控制代碼

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

XrEyeTrackerANDROID 控制代碼代表眼球追蹤器，可追蹤眼球並準確對應使用者視線。

眼動追蹤資料屬於敏感個人資訊，與個人隱私權和完整性息息相關。強烈建議儲存或轉移眼動追蹤資料的應用程式，一律要求使用者主動且明確接受這項操作。

應用程式會使用這個控制代碼，透過這個擴充功能中的其他函式存取眼動追蹤資料。

眼動追蹤功能會在場景中顯示眼球姿勢和狀態。

xrCreateEyeTrackerANDROID 函式定義如下：

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

參數說明

session 是眼動追蹤功能啟用的 XrSession 控制代碼。
createInfo 是用來指定眼動追蹤的 XrEyeTrackerCreateInfoANDROID。
eyeTracker 是傳回的 XrEyeTrackerANDROID 控制代碼。

應用程式會使用 xrCreateEyeTrackerANDROID 函式建立 XrEyeTrackerANDROID 控制代碼。

如果系統不支援眼動追蹤，執行階段必須從 xrCreateEyeTrackerANDROID 傳回 XR_ERROR_FEATURE_UNSUPPORTED。

有效用量 (隱含)

呼叫 xrCreateEyeTrackerANDROID 前，XR_ANDROID_eye_tracking 擴充功能必須啟用
session must 為有效的 XrSession 控制代碼
createInfo 必須是指向有效 XrEyeTrackerCreateInfoANDROID 結構體的指標
eyeTracker must 是 XrEyeTrackerANDROID 控制代碼的指標

傳回代碼

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

XR_ERROR_FEATURE_UNSUPPORTED
XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

XrEyeTrackerCreateInfoANDROID 結構體的定義如下：

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

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。

XrEyeTrackerCreateInfoANDROID 結構體說明建立 XrEyeTrackerANDROID 控制代碼的資訊。

有效用量 (隱含)

XR_ANDROID_eye_tracking 擴充功能必須先啟用，才能使用 XrEyeTrackerCreateInfoANDROID
 type 必須為 XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標

xrDestroyEyeTrackerANDROID 函式定義如下：

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

參數說明

eyeTracker 是先前由 xrCreateEyeTrackerANDROID 建立的 XrEyeTrackerANDROID。

xrDestroyEyeTrackerANDROID 函式會在眼動追蹤體驗結束時，釋放 eyeTracker 和基礎資源。

有效用量 (隱含)

呼叫 xrDestroyEyeTrackerANDROID 前，XR_ANDROID_eye_tracking 擴充功能必須啟用
eyeTracker must 是有效的 XrEyeTrackerANDROID 控制代碼

執行緒安全

eyeTracker 和任何子項控制代碼的存取權必須從外部同步處理

傳回代碼

成功

XR_SUCCESS

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID

取得眼睛資訊

xrGetCoarseTrackingEyesInfoANDROID 函式定義如下：

XrResult xrGetCoarseTrackingEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              eyesOutput);

參數說明

eyeTracker 是先前由 xrCreateEyeTrackerANDROID 建立的 XrEyeTrackerANDROID。
getInfo 是 XrEyesGetInfoANDROID 的指標，用於提供查詢眼部姿勢和狀態的資訊。
eyesOutput 是 XrEyesANDROID 的指標，其中包含傳回的眼睛資訊，包括姿勢和狀態。

xrGetCoarseTrackingEyesInfoANDROID 函式會以保護使用者隱私權的方式，取得眼睛狀態和姿勢的資訊。

如果應用程式沒有 android.permission.EYE_TRACKING_COARSE 權限，執行階段必須傳回 XR_ERROR_PERMISSION_INSUFFICIENT。

眼部姿勢以 XrEyesGetInfoANDROID :: baseSpace at XrEyesGetInfoANDROID :: time 表示。

系統會隨時追蹤或取消追蹤眼部姿勢的位置和方向。也就是說，執行階段「必須」在提供的 XrEyesANDROID 上設定 XR_SPACE_LOCATION_POSITION_TRACKED_BIT 和 XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT，或清除 XR_SPACE_LOCATION_POSITION_TRACKED_BIT 和 XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT，並設定 XrEyesANDROID :: mode 來指出追蹤狀態。eyes

有效用量 (隱含)

呼叫 xrGetCoarseTrackingEyesInfoANDROID 前，XR_ANDROID_eye_tracking 擴充功能必須啟用
eyeTracker must 是有效的 XrEyeTrackerANDROID 控制代碼
getInfo 必須是指向有效 XrEyesGetInfoANDROID 結構體的指標
eyesOutput 必須是指向 XrEyesANDROID 結構體的指標

傳回代碼

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_PERMISSION_INSUFFICIENT
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_TIME_INVALID
XR_ERROR_VALIDATION_FAILURE

xrGetFineTrackingEyesInfoANDROID 函式定義如下：

XrResult xrGetFineTrackingEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              eyesOutput);

參數說明

eyeTracker 是先前由 xrCreateEyeTrackerANDROID 建立的 XrEyeTrackerANDROID。
getInfo 是 XrEyesGetInfoANDROID 的指標，用於指定所需輸出內容。
eyesOutput 是 XrEyesANDROID 的指標，其中包含傳回的眼睛資訊，包括姿勢和狀態。

xrGetFineTrackingEyesInfoANDROID 函式可取得眼睛狀態和姿勢的資訊，精確度比 xrGetCoarseTrackingEyesInfoANDROID 更高。

如果應用程式沒有 android.permission.EYE_TRACKING_FINE 權限，執行階段必須傳回 XR_ERROR_PERMISSION_INSUFFICIENT。

眼睛資訊會在呼叫 xrGetFineTrackingEyesInfoANDROID 時解析，並與基礎空間相關，方法是使用 XrEyesGetInfoANDROID :: time 和 XrEyesGetInfoANDROID :: baseSpace。執行階段「必須」在呼叫時解析 XrEyesGetInfoANDROID :: baseSpace 定義的位置。

有效用量 (隱含)

呼叫 xrGetFineTrackingEyesInfoANDROID 前，XR_ANDROID_eye_tracking 擴充功能必須啟用
eyeTracker must 是有效的 XrEyeTrackerANDROID 控制代碼
getInfo 必須是指向有效 XrEyesGetInfoANDROID 結構體的指標
eyesOutput 必須是指向 XrEyesANDROID 結構體的指標

傳回代碼

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_PERMISSION_INSUFFICIENT
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_TIME_INVALID
XR_ERROR_VALIDATION_FAILURE

XrEyesGetInfoANDROID 結構包含擷取眼部姿勢和狀態所需的資訊。

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

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
time 是用來評估相對於 baseSpace 的座標。XrTime
baseSpace 是 XrSpace，眼部姿勢會相對於 time。

有效用量 (隱含)

XrEyesGetInfoANDROID XR_ANDROID_eye_tracking 擴充功能必須先啟用，才能使用
 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 是 XrEyeANDROID 的陣列，大小為 XR_EYE_MAX_ANDROID，適用於左眼和右眼，並以 XrEyeIndexANDROID 做為索引。
mode 是 XrEyeTrackingModeANDROID，表示目前追蹤的眼睛。

有效用量 (隱含)

XR_ANDROID_eye_tracking 擴充功能必須先啟用，才能使用 XrEyesANDROID
 type 必須為 XR_TYPE_EYES_ANDROID
next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標
eyes 的任何指定元素必須是有效的 XrEyeANDROID 結構
mode 必須是有效的 XrEyeTrackingModeANDROID 值

XrEyeANDROID 結構體會說明眼睛的狀態、位置和方向。

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

成員說明

eyeState 是眼睛的 XrEyeStateANDROID。
eyePose 是 XrPosef，用於定義相應 XrEyesGetInfoANDROID :: baseSpace 參考影格中眼球瞳孔的位置和方向。此處的身分方向代表座標軸，其中 +Z 指向使用者的眼睛，+X 指向右方，+Y 指向上方。

有效用量 (隱含)

XR_ANDROID_eye_tracking 擴充功能必須先啟用，才能使用 XrEyeANDROID
eyeState 必須是有效的 XrEyeStateANDROID 值

XrEyeStateANDROID 列舉會識別追蹤眼睛的不同狀態。

typedef enum XrEyeStateANDROID {
    XR_EYE_STATE_INVALID_ANDROID = 0,
    XR_EYE_STATE_GAZING_ANDROID = 1,
    XR_EYE_STATE_SHUT_ANDROID = 2,
    XR_EYE_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} 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,
    XR_EYE_INDEX_MAX_ENUM_ANDROID = 0x7FFFFFFF
} 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,
    XR_EYE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} 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, e.g. 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_xrGetCoarseTrackingEyesInfoANDROID xrGetCoarseTrackingEyesInfoANDROID; // previously initialized
PFN_xrGetFineTrackingEyesInfoANDROID xrGetFineTrackingEyesInfoANDROID; // 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 fineEyesInfo{.type = XR_TYPE_EYES_ANDROID,
                               .next = nullptr,
                               .mode = XR_EYE_TRACKING_MODE_BOTH_ANDROID};
    XrEyesANDROID coarseEyesInfo{.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(xrGetCoarseTrackingEyesInfoANDROID(eyeTracker, &eyesGetInfo, &coarseEyesInfo));
    CHK_XR(xrGetFineTrackingEyesInfoANDROID(eyeTracker, &eyesGetInfo, &fineEyesInfo));

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

新物件類型

XrEyeTrackerANDROID

新結構

XrEyeANDROID
XrEyeTrackerCreateInfoANDROID
XrEyesANDROID
XrEyesGetInfoANDROID
擴充 XrSystemProperties：
- XrSystemEyeTrackingPropertiesANDROID

新列舉

XrEyeIndexANDROID
XrEyeStateANDROID
XrEyeTrackingModeANDROID

新增列舉常數

XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
XR_ANDROID_eye_tracking_SPEC_VERSION
XR_EYE_MAX_ANDROID
擴充 XrObjectType：
- XR_OBJECT_TYPE_EYE_TRACKER_ANDROID
擴充 XrStructureType：
- XR_TYPE_EYES_ANDROID
- XR_TYPE_EYES_GET_INFO_ANDROID
- XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
- XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

問題

版本記錄

修訂版本 1，2025-01-17 (Kenny Vercaemer)
- 擴充功能初始說明