Android XR for OpenXR | Android Developers

Android 開發人員高峰會再度登場，並專為 Android XR 規劃一系列議程。歡迎試用，並提供意見！

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

XR_ANDROID_eye_tracking

Name String

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。

有效用途 (隱含)

必須先啟用 XR_ANDROID_eye_tracking 擴充功能，才能呼叫 xrCreateEyeTrackerANDROID
session「必須」是有效的 XrSession 控制代碼
createInfo「必須」是指向有效 XrEyeTrackerCreateInfoANDROID 結構的指標
eyeTracker「必須」指向 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 和基礎資源。

有效用途 (隱含)

必須先啟用 XR_ANDROID_eye_tracking 擴充功能，才能呼叫 xrDestroyEyeTrackerANDROID
eyeTracker「必須」是有效的 XrEyeTrackerANDROID 控制代碼

執行緒安全

存取 eyeTracker 和任何子項控制代碼時，必須從外部同步

傳回代碼

成功

XR_SUCCESS

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_RUNTIME_FAILURE

取得眼睛資訊

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 表示，時間為 XrEyesGetInfoANDROID :: time。

在任何時間點，系統都會追蹤或不追蹤眼睛姿勢的位置和方向。也就是說，執行階段必須在提供的 XrEyesANDROID :: eyes 上，同時設定 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 來表示追蹤狀態。

有效用途 (隱含)

必須先啟用 XR_ANDROID_eye_tracking 擴充功能，才能呼叫 xrGetCoarseTrackingEyesInfoANDROID
eyeTracker「必須」是有效的 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 定義的位置。

有效用途 (隱含)

必須先啟用 XR_ANDROID_eye_tracking 擴充功能，才能呼叫 xrGetFineTrackingEyesInfoANDROID
eyeTracker「必須」是有效的 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 是 XrTime，用於評估相對於 baseSpace 的座標。
baseSpace 是要傳回眼睛姿勢的 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 陣列，大小為 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

表示正在追蹤左右眼。

#define XR_EYE_MAX_ANDROID                2

XR_EYE_MAX_ANDROID 是 XrEyeANDROID 資料回報的眼睛數量上限。

眼動追蹤程式碼範例

下列程式碼範例示範如何取得與檢視空間相關的眼睛資訊。

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