XR_ANDROID_eye_tracking OpenXR 擴充功能

名稱字串

XR_ANDROID_eye_tracking

擴充功能類型

執行個體擴充功能

已註冊的擴充號碼

457

修訂版本

1

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2025-01-17

IP 狀態

沒有已知的 IP 版權聲明。

著作人

Spencer Quin，Google

Jared Finder，Google

Levana Chen，Google

Google 的 Kenny Vercaemer

Prasanthi Gurumurthy，Google

Nihav Jain，Google

總覽

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

眼動追蹤資料提供兩種模式：粗略和精細。粗略追蹤可粗略估算使用者的眼睛，精細追蹤則可提供更準確的估算值。粗略追蹤適用於想要提供基本化身類似表示的應用程式，而精細追蹤則適用於更精確的應用程式。

如要進行互動，應使用 XR_EXT_eye_gaze_interaction 。

注意： <br <br="" /> 權限

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。

有效用法 (隱含)

• 您必須先啟用 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 句柄所需的資訊。

有效用法 (隱含)

• 您必須先啟用 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 和基礎資源。

有效用法 (隱含)

• 您必須先啟用 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。

使用 XrEyesGetInfoANDROID::time 時，眼睛資訊會以 XrEyesGetInfoANDROID::baseSpace 為基準空間，並在呼叫 xrGetCoarseTrackingEyesInfoANDROID 時解析。

在任何時間點，眼睛姿勢的位置和方向都會受到追蹤或取消追蹤。也就是說，應用程式可以預期 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 函式定義如下：{:#xrGetFineTrackingEyesInfoANDROID} C++ 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。

使用 XrEyesGetInfoANDROID::time 時，眼睛資訊會以 XrEyesGetInfoANDROID::baseSpace 為基準空間，並在呼叫 xrGetFineTrackingEyesInfoANDROID 時解析。

在任何時間點，眼睛姿勢的位置和方向都會受到追蹤或取消追蹤。也就是說，應用程式可以預期 XR_SPACE_LOCATION_POSITION_TRACKED_BIT 和 XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT 會在提供的 XrEyesANDROID::eyes 上設定或清除，而 XrEyesANDROID::mode 會指出追蹤狀態。

有效用法 (隱含)

• 您必須先啟用 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。

有效用法 (隱含)

• 您必須先啟用 XR_ANDROID_eye_tracking 擴充功能，才能使用 XrEyesGetInfoANDROID
• 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，用於指出眼睛是否正在追蹤，以及追蹤哪一隻眼睛。

有效用法 (隱含)

• 您必須先啟用 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。
• pose 是 XrPosef，定義了在對應 XrEyesGetInfoANDROID::baseSpace 參考架構中，眼睛原點的位置和方向。這裡的 ID 方向代表座標軸，其中 +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
} XrEyeStateANDROID;

這些列舉的意思如下：

Enum	說明
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;

這些列舉的意思如下：

Enum	說明
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;

這些列舉的意思如下：

Enum	說明
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)
  • 初始擴充功能說明