XR_ANDROID_avatar_eyes OpenXR 擴充功能

名稱字串

XR_ANDROID_avatar_eyes

擴充功能類型

執行個體擴充功能

已註冊的擴充號碼

457

修訂版本

1

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2024-09-30

IP 狀態

沒有已知的 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_DEFINE_HANDLE(XrEyeTrackerANDROID)

XrEyeTrackerANDROID 句柄代表追蹤眼睛的眼球追蹤器，可準確對應使用者正在看的內容。

這個句柄可用於透過這個擴充功能中的其他函式存取眼球追蹤資料。

眼球追蹤會在場景中提供眼睛姿勢和狀態的呈現方式。

xrCreateEyeTrackerANDROID 函式定義如下：

XrResult xrCreateEyeTrackerANDROID(
    XrSession                                   session,
    const XrEyeTrackerCreateInfoANDROID*        createInfo,
    XrEyeTrackerANDROID*                        eyeTracker);

參數說明

應用程式可以使用 xrCreateEyeTrackerANDROID 函式建立 XrEyeTrackerANDROID 句柄。

如果系統不支援眼球追蹤，則 xrCreateEyeTrackerANDROID 會傳回 XR_ERROR_FEATURE_UNSUPPORTED。

有效用法 (隱含)

傳回代碼

成功

  • 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 句柄所需的資訊。

有效用法 (隱含)

xrDestroyEyeTrackerANDROID 函式的定義如下：

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

參數說明

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

有效用法 (隱含)

執行緒安全性

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

傳回代碼

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

取得眼睛資訊

xrGetEyesInfoANDROID 函式定義如下：

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

參數說明

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

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

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

有效用法 (隱含)

傳回代碼

成功

  • 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。

有效用法 (隱含)

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，用於指出是否追蹤眼睛，以及追蹤哪些眼睛。

有效用法 (隱含)

XrEyeANDROID 結構體會說明眼睛的狀態、位置和方向。

typedef struct XrEyeANDROID {
    XrEyeStateANDROID    eyeState;
    XrPosef              eyePose;
} XrEyeANDROID;

成員說明

有效用法 (隱含)

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));

新物件類型

新列舉常數

  • 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

新列舉項目

新結構體

新函式

問題

版本記錄

  • 修訂版本 1，2024 年 9 月 4 日 (Levana Chen)
    • 初始擴充功能說明