XR_ANDROID_avatar_eyes OpenXR 扩展

名称字符串

XR_ANDROID_avatar_eyes（已废弃）注意：XR_ANDROID_avatar_eyes 已废弃，并将在未来版本中移除。请改用 XR_ANDROID_eye_tracking。

扩展类型

实例扩展

注册的扩展编号

457

修订版

1

扩展和版本依赖项

OpenXR 1.0

最后修改日期

2024-09-30

IP 状态

无已知 IP 声明。

贡献者

Spencer Quin, Google

Jared Finder, Google

Levana Chen, Google

概览

此扩展使应用程序能够获取用户眼睛的位置和方向，以及眼睛跟踪状态。

此扩展旨在使头像的眼睛姿势和状态表示更加逼真。为此，

  • 它允许非跟踪状态，例如眨眼。
  • 它允许单眼或双眼跟踪。

此扩展不应用于其他眼动追踪目的。对于交互，应使用 XR_EXT_eye_gaze_interaction。

眼动追踪器

眼动追踪器是一种传感设备，用于跟踪眼睛并准确映射用户所看的位置。此扩展的主要目的是将用户的凝视映射到虚拟场景中的头像。

眼动追踪数据可能是敏感的个人信息，与个人隐私和完整性密切相关。强烈建议存储或传输眼动追踪数据的应用程序始终请求用户主动和明确地接受。

  • 当应用程序尝试创建活动的眼动追踪器时，如果尚未允许应用程序访问眼动追踪器，它将收到 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 函数获取眼睛状态和姿势的信息。

眼睛信息在调用 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 是 XrTime，在此时间评估相对于 baseSpace 的坐标。
  • baseSpace 眼睛姿势将相对于此 XrSpace 在 time 时刻。

有效用法（隐式）

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;

这些枚举具有以下含义：

枚举

描述

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;

这些枚举具有以下含义：

枚举

描述

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;

这些枚举具有以下含义：

枚举

描述

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-09-04 (Levana Chen)
    • 初始扩展描述

OpenXR™ 和 OpenXR 徽标是 The Khronos Group Inc. 拥有的商标，并在中国、欧盟、日本和英国注册为商标。