名称字符串
XR_ANDROID_eye_tracking
扩展程序类型
实例扩展
已注册的扩展号码
457
修订版本
1
扩展程序和版本依赖项
上次修改日期
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
。
检查系统功能
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
的指针,其中包含返回的眼睛信息,包括姿势和状态。与xrGetCoarseTrackingEyesInfoANDROID
相比,xrGetFineTrackingEyesInfoANDROID
函数可获取眼部状态和姿势的更高精度信息。
如果应用没有 android.permission.EYE_TRACKING_FINE
权限,运行时必须返回 XR_ERROR_PERMISSION_INSUFFICIENT
。
使用 XrEyesGetInfoANDROID::time
, XrEyesGetInfoANDROID::baseSpace
调用 xrGetFineTrackingEyesInfoANDROID
时,眼睛信息会解析并相对于基准空间。
在任何时间点,系统都会跟踪或不跟踪眼睛姿势的位置和方向。这意味着,应用可以预期 XR_SPACE_LOCATION_POSITION_TRACKED_BIT
和 XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT
都会在提供的 XrEyesANDROID::eyes
上设置或清除,并且 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_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
的参考框架中的坐标和方向。此处的身份取向表示坐标轴,其中 +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;
枚举的含义如下:
枚举 |
说明 |
|
表示眼睛处于错误状态或不存在。 |
|
表示眼睛在凝视。 |
|
表示眼睛因眨眼或眨眼而闭合。 |
XrEyeIndexANDROID
枚举用于标识左眼或右眼的索引。
typedef enum XrEyeIndexANDROID {
XR_EYE_INDEX_LEFT_ANDROID = 0,
XR_EYE_INDEX_RIGHT_ANDROID = 1
} XrEyeIndexANDROID;
枚举的含义如下:
枚举 |
说明 |
|
左眼。 |
|
右眼。 |
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;
枚举的含义如下:
枚举 |
说明 |
|
表示眼动跟踪功能未启用。 |
|
表示仅跟踪右眼。 |
|
表示仅跟踪左眼。 |
|
表示左眼和右眼都在跟踪。 |
眼动跟踪代码示例
以下示例代码演示了如何获取相对于视图空间的眼睛信息。
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));
新的对象类型
新的枚举常量
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
新枚举
新结构
XrEyeANDROID
XrEyesANDROID
XrEyesGetInfoANDROID
XrEyeTrackerCreateInfoANDROID
XrSystemEyeTrackingPropertiesANDROID
新函数
xrCreateEyeTrackerANDROID
xrDestroyEyeTrackerANDROID
xrGetCoarseTrackingEyesInfoANDROID
xrGetFineTrackingEyesInfoANDROID
问题
版本历史记录
- 修订版 1,2025 年 1 月 17 日 (Kenny Vercaemer)
- 初始扩展程序说明