Android XR SDK 現已在開發人員預覽版中推出。敬請提供意見回饋！請前往支援頁面與我們聯絡。

本頁面由 Cloud Translation API 翻譯而成。

XR_ANDROID_eye_tracking OpenXR 擴充功能

名稱字串

XR_ANDROID_eye_tracking

擴充功能類型

執行個體擴充功能

已註冊的擴充號碼

457

修訂版本

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2025-01-17

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

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

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

總覽

檢查系統能力

成員說明

有效用法 (隱含)

建立眼球追蹤器手柄

參數說明

有效用法 (隱含)

傳回代碼

成員說明

有效用法 (隱含)

參數說明

有效用法 (隱含)

執行緒安全性

傳回代碼

取得眼睛資訊

參數說明

有效用法 (隱含)

傳回代碼

參數說明

有效用法 (隱含)

傳回代碼

成員說明

有效用法 (隱含)

成員說明

有效用法 (隱含)

成員說明

有效用法 (隱含)

眼睛追蹤程式碼範例

XR_ANDROID_eye_tracking OpenXR 擴充功能