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

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

XR_ANDROID_avatar_eyes OpenXR 擴充功能

名稱字串

XR_ANDROID_avatar_eyes

擴充功能類型

執行個體擴充功能

已註冊的擴充號碼

457

修訂版本

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2024-09-30

IP 狀態

著作人

Spencer Quin，Google

Jared Finder，Google

Levana Chen，Google

總覽

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

這個擴充功能可讓虛擬人物的眼睛姿勢和狀態呈現更為真實。為此目的：

可用於不追蹤的狀態，例如閃爍。
可進行單眼或雙眼追蹤。

這項擴充功能不應用於其他眼球追蹤用途。如要進行互動，應使用 XR_EXT_eye_gaze_interaction 。

Eye Tracker

眼球追蹤器是感應裝置，可追蹤眼睛並準確繪製使用者正在注視的位置。這個擴充功能的主要目的，是將使用者的目光對應至虛擬場景中的自訂圖示。

眼球追蹤資料可能屬於敏感的個人資訊，與個人隱私權和完整性息息相關。強烈建議儲存或傳輸眼球追蹤資料的應用程式，一律要求使用者主動且明確接受這項操作。

應用程式嘗試建立主動式眼動追蹤器時，會收到 XR_ERROR_PERMISSION_INSUFFICIENT，直到應用程式獲得存取眼動追蹤器的權限為止。

檢查系統能力

應用程式可以在呼叫 xrGetSystemProperties 時，將 XrSystemAvatarEyesPropertiesANDROID 結構體連結至 XrSystemProperties，藉此檢查系統是否支援虛擬人物眼睛。如果 supportsAvatarEyes 傳回 XR_FALSE，應用程式就會從 xrCreateEyeTrackerANDROID 收到 XR_ERROR_FEATURE_UNSUPPORTED。

typedef struct XrSystemAvatarEyesPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAvatarEyes;
} XrSystemAvatarEyesPropertiesANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL 或結構鏈結中下一個結構的指標。核心 OpenXR 或這個擴充功能中並未定義這類結構。
supportsAvatarEyes 是 XrBool32，表示目前系統是否支援虛擬人物眼睛。

有效用法 (隱含)

您必須先啟用 XR_ANDROID_avatar_eyes 擴充功能，才能使用 XrSystemAvatarEyesPropertiesANDROID
type 必須為 XR_TYPE_SYSTEM_AVATAR_EYES_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_avatar_eyes 擴充功能，才能呼叫 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

XrEyeTrackerCreateInfoANDROID 結構的定義如下：

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

成員說明

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

XrEyeTrackerCreateInfoANDROID 結構體會說明建立 XrEyeTrackerANDROID 句柄所需的資訊。

有效用法 (隱含)

您必須先啟用 XR_ANDROID_avatar_eyes 擴充功能，才能使用 XrEyeTrackerCreateInfoANDROID
type 必須為 XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
next 必須為 NULL，或指向結構體鏈結中下一個結構體的有效指標

xrDestroyEyeTrackerANDROID 函式的定義如下：

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

參數說明

eyeTracker 是先前由 xrCreateEyeTrackerANDROID 建立的 XrEyeTrackerANDROID。

xrDestroyEyeTrackerANDROID 函式會在完成眼動追蹤體驗後釋放 eyeTracker 和底層資源。

有效用法 (隱含)

您必須先啟用 XR_ANDROID_avatar_eyes 擴充功能，才能呼叫 xrDestroyEyeTrackerANDROID
eyeTracker 必須是有效的 XrEyeTrackerANDROID 句柄

執行緒安全性

eyeTracker 和任何子系句柄的存取權必須在外部同步

傳回代碼

成功

XR_SUCCESS

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID

取得眼睛資訊

xrGetEyesInfoANDROID 函式定義如下：

XrResult xrGetEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              infoOutput);

參數說明

eyeTracker 是先前由 xrCreateEyeTrackerANDROID 建立的 XrEyeTrackerANDROID。
getInfo 是指向 XrEyesGetInfoANDROID 的指標，用於指定所需的輸出內容。
infoOutput 是 XrEyesANDROID 的索引，其中包含傳回的眼睛資訊，包括姿勢和狀態。

xrGetEyesInfoANDROID 函式可取得眼睛狀態和姿勢的資訊。

使用 XrEyesGetInfoANDROID::time、XrEyesGetInfoANDROID::baseSpace 時，系統會解析眼睛資訊，並與基本空間相關。

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

有效用法 (隱含)

您必須先啟用 XR_ANDROID_avatar_eyes 擴充功能，才能呼叫 xrGetEyesInfoANDROID
eyeTracker 必須是有效的 XrEyeTrackerANDROID 句柄
getInfo 必須是有效 XrEyesGetInfoANDROID 結構體的指標
infoOutput 必須是 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

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_avatar_eyes 擴充功能必須啟用
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_avatar_eyes 擴充功能必須啟用
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 是向上。

有效用法 (隱含)

使用 XrEyeANDROID 前，必須先啟用 XR_ANDROID_avatar_eyes 擴充功能
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, for example, 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_xrGetEyesInfoANDROID xrGetEyesInfoANDROID; // 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 eyesInfo{.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(xrGetEyesInfoANDROID(eyeTracker, &eyesGetInfo, &eyesInfo));

    // 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_AVATAR_EYES_PROPERTIES_ANDROID

新列舉項目

XrEyeIndexANDROID
XrEyeStateANDROID
XrEyeTrackingModeANDROID

新結構體

XrEyeANDROID
XrEyesANDROID
XrEyesGetInfoANDROID
XrEyeTrackerCreateInfoANDROID
XrSystemAvatarEyesPropertiesANDROID

新函式

xrCreateEyeTrackerANDROID
xrDestroyEyeTrackerANDROID
xrGetEyesInfoANDROID

問題

版本記錄

修訂版本 1，2024-09-04 (Levana Chen)
- 初始擴充功能說明