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 。

檢查系統能力

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;

這些列舉的意思如下：

XrEyeIndexANDROID 列舉會指出左眼或右眼的索引。

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

這些列舉的意思如下：

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;

這些列舉的意思如下：

眼睛追蹤程式碼範例

以下程式碼範例示範如何取得相對於檢視區域的眼睛資訊。

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. 擁有的商標，並已在中國、歐盟、日本和英國註冊為商標。