XR_ANDROID_eye_tracking

名称字符串

XR_ANDROID_eye_tracking

扩展程序类型

实例扩展程序

已注册的扩展程序编号

457

修订版本

1

批准状态

未批准

扩展程序和版本依赖项

OpenXR 1.0

上次修改日期

2025-01-17

IP 状态

没有已知的 IP 权利主张。

创作贡献者

Spencer Quin，Google
Jared Finder，Google
Levana Chen，Google
Kenny Vercaemer，Google
Prasanthi Gurumurthy，Google
Nihav Jain，Google

概览

此扩展程序可让应用获取用户眼睛的位置和方向，以及眼动追踪状态。

眼动追踪数据有两种模式：粗略和精细。粗略跟踪可提供用户眼球的粗略估计，而精细跟踪可提供更准确的估计。粗略跟踪适用于想要提供基本头像式表示的应用，而精细跟踪适用于更精确的应用。

对于互动，应使用 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 :: time 处以 XrEyesGetInfoANDROID :: baseSpace 表示。

在任何时间点，眼部姿势的位置和方向要么同时处于被跟踪状态，要么同时处于未被跟踪状态。这意味着，运行时必须在提供的 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 定义的位置。

在任何时间点，眼部姿势的位置和方向要么同时处于被跟踪状态，要么同时处于未被跟踪状态。这意味着，运行时必须在提供的 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 扩展程序，然后才能调用 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 是相对于 baseSpace 评估坐标的 XrTime。
• 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

新增命令

• xrCreateEyeTrackerANDROID
• xrDestroyEyeTrackerANDROID
• xrGetCoarseTrackingEyesInfoANDROID
• xrGetFineTrackingEyesInfoANDROID

新结构

• 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 年 1 月 17 日 (Kenny Vercaemer)

  • 初始扩展程序说明