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

XR_ANDROID_eye_tracking OpenXR 擴充功能

名稱字串

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 應使用。

檢查系統功能

XrSystemEyeTrackingPropertiesANDROID 結構定義如下：

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

成員說明

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

應用程式可以透過將 XrSystemEyeTrackingPropertiesANDROID 結構體鏈結至呼叫 xrGetSystemProperties 時的 XrSystemProperties，檢查系統是否支援眼球追蹤。如果 supportsEyeTracking 傳回 XR_FALSE，應用程式就會從 xrCreateEyeTrackerANDROID 收到 XR_ERROR_FEATURE_UNSUPPORTED。

有效使用 (隱含)

使用 XrSystemEyeTrackingPropertiesANDROID 前，XR_ANDROID_eye_tracking 擴充功能必須啟用
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。

有效使用 (隱含)

您必須先啟用 XR_ANDROID_eye_tracking 擴充功能，才能呼叫 xrCreateEyeTrackerANDROID
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
XR_ERROR_FEATURE_UNSUPPORTED

XrEyeTrackerCreateInfoANDROID 結構定義如下：

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

成員說明

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

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

有效使用 (隱含)

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

xrDestroyEyeTrackerANDROID 函式的定義如下：

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

參數說明

eyeTracker 是由 xrCreateEyeTrackerANDROID 先前建立的 XrEyeTrackerANDROID。

xrDestroyEyeTrackerANDROID 函式會在完成眼球追蹤體驗時釋放 eyeTracker 和基礎資源。

有效使用 (隱含)

您必須先啟用 XR_ANDROID_eye_tracking 擴充功能，才能呼叫 xrDestroyEyeTrackerANDROID
eyeTracker 必須是有效的 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 的指標，用於指定所需輸出內容。
infoOutput 是指向 XrEyesANDROID 的指標，其中包含傳回的眼睛資訊，包括姿勢和狀態。

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

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

眼睛資訊已解析，且與呼叫 xrGetCoarseTrackingEyesInfoANDROID 時的基準空間相關，使用 XrEyesGetInfoANDROID::timeXrEyesGetInfoANDROID::baseSpace。

系統會隨時追蹤或不追蹤眼部姿勢的位置和方向。也就是說，應用程式可以預期 XR_SPACE_LOCATION_POSITION_TRACKED_BIT 和 XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT 會在提供的 XrEyesANDROID::eyes 上設定或清除，而 XrEyesANDROID::mode 會指出追蹤狀態。

有效使用 (隱含)

您必須先啟用 XR_ANDROID_eye_tracking 擴充功能，才能呼叫 xrGetCoarseTrackingEyesInfoANDROID
eyeTracker 必須是有效的 XrEyeTrackerANDROID 控制代碼
getInfo 必須是指向有效 XrEyesGetInfoANDROID 結構體的指標
eyesOutput 必須是指向 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
XR_ERROR_PERMISSION_INSUFFICIENT

xrGetFineTrackingEyesInfoANDROID 函式定義如下：

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

參數說明

eyeTracker 是由 xrCreateEyeTrackerANDROID 先前建立的 XrEyeTrackerANDROID。
getInfo 是 XrEyesGetInfoANDROID 的指標，用於指定所需輸出內容。
infoOutput 是指向 XrEyesANDROID 的指標，其中包含傳回的眼睛資訊，包括姿勢和狀態。xrGetFineTrackingEyesInfoANDROID 函式可比 xrGetCoarseTrackingEyesInfoANDROID 更精確地取得眼睛狀態和姿勢資訊。

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

眼睛資訊已解析，且與呼叫 xrGetFineTrackingEyesInfoANDROID 時的基準空間相關，使用 XrEyesGetInfoANDROID::timeXrEyesGetInfoANDROID::baseSpace。

有效使用 (隱含)

您必須先啟用 XR_ANDROID_eye_tracking 擴充功能，才能呼叫 xrGetFineTrackingEyesInfoANDROID
eyeTracker 必須是有效的 XrEyeTrackerANDROID 控制代碼
getInfo 必須是指向有效 XrEyesGetInfoANDROID 結構體的指標
eyesOutput 必須是指向 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
XR_ERROR_PERMISSION_INSUFFICIENT

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_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 陣列，以 XrEyeIndexANDROID 為索引。
mode 是 XrEyeTrackingModeANDROID，用來指出眼睛是否正在追蹤，以及追蹤哪隻眼睛。

有效使用 (隱含)

使用 XrEyesANDROID 前，XR_ANDROID_eye_tracking 擴充功能必須啟用
type 必須為 XR_TYPE_EYES_ANDROID
next 必須是 NULL 或指向結構鏈中下一個結構的有效指標
eyes 必須是有效的 XrEyeANDROID 結構
mode 必須是有效的 XrEyeTrackingModeANDROID 值

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

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

成員說明

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

有效使用 (隱含)

使用 XrEyeANDROID 前，XR_ANDROID_eye_tracking 擴充功能必須啟用
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, 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

新的列舉常數

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_EYE_TRACKING_PROPERTIES_ANDROID

新列舉

XrEyeIndexANDROID
XrEyeStateANDROID
XrEyeTrackingModeANDROID

新結構

XrEyeANDROID
XrEyesANDROID
XrEyesGetInfoANDROID
XrEyeTrackerCreateInfoANDROID
XrSystemEyeTrackingPropertiesANDROID

新函式

xrCreateEyeTrackerANDROID
xrDestroyEyeTrackerANDROID
xrGetCoarseTrackingEyesInfoANDROID
xrGetFineTrackingEyesInfoANDROID

問題

版本記錄

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

OpenXR™ 和 OpenXR 標誌是 The Khronos Group Inc. 的商標，已在中國、歐盟、日本和英國註冊為商標。

XR_ANDROID_eye_tracking OpenXR 擴充功能 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

檢查系統功能

成員說明

有效使用 (隱含)

建立眼球追蹤器控制代碼

參數說明

有效使用 (隱含)

傳回代碼

成員說明

有效使用 (隱含)

參數說明

有效使用 (隱含)

執行緒安全

傳回代碼

取得眼睛資訊

參數說明

有效使用 (隱含)

傳回代碼

參數說明

有效使用 (隱含)

傳回代碼

成員說明

有效使用 (隱含)

成員說明

有效使用 (隱含)

成員說明

有效使用 (隱含)

眼動追蹤的範例程式碼

XR_ANDROID_eye_tracking OpenXR 擴充功能