Name String
XR_ANDROID_eye_tracking
Loại phần mở rộng
Tiện ích Instance
Số máy nhánh đã đăng ký
457
Bản sửa đổi
1
Phần mở rộng và các phần phụ thuộc của phiên bản
Ngày sửa đổi gần đây nhất
2025-01-17
Trạng thái IP
Không có thông báo xác nhận quyền sở hữu nào đã biết về quyền sở hữu trí tuệ.
Cộng tác viên
Spencer Quin, Google
Jared Finder, Google
Levana Chen, Google
Kenny Vercaemer, Google
Prasanthi Gurumurthy, Google
Nihav Jain, Google
Tổng quan
Tiện ích này cho phép các ứng dụng lấy vị trí và hướng của mắt người dùng, cũng như trạng thái theo dõi ánh mắt.
Dữ liệu theo dõi ánh mắt được cung cấp ở hai chế độ: thô và chi tiết. Tính năng theo dõi thô cung cấp thông tin ước tính thô về mắt của người dùng, trong khi tính năng theo dõi chi tiết cung cấp thông tin ước tính chính xác hơn. Tính năng theo dõi thô dành cho những ứng dụng muốn cung cấp một hình ảnh đại diện cơ bản, trong khi tính năng theo dõi chi tiết dành cho những ứng dụng chính xác hơn.
Đối với hoạt động tương tác, bạn nên dùng XR_EXT_eye_gaze_interaction .
Kiểm tra khả năng của hệ thống
Cấu trúc XrSystemEyeTrackingPropertiesANDROID được xác định là:
typedef struct XrSystemEyeTrackingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsEyeTracking;
} XrSystemEyeTrackingPropertiesANDROID;
Nội dung mô tả thành viên
typelàXrStructureTypecủa cấu trúc này.nextlàNULLhoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.supportsEyeTrackinglà mộtXrBool32, cho biết liệu hệ thống hiện tại có hỗ trợ tính năng theo dõi ánh mắt hay không.
Một ứng dụng có thể kiểm tra xem hệ thống có khả năng theo dõi bằng mắt hay không bằng cách liên kết một cấu trúc XrSystemEyeTrackingPropertiesANDROID với XrSystemProperties khi gọi xrGetSystemProperties. Nếu supportsEyeTracking trả về XR_FALSE, thì ứng dụng sẽ nhận được XR_ERROR_FEATURE_UNSUPPORTED từ xrCreateEyeTrackerANDROID.
Sử dụng hợp lệ (ngầm)
- Bạn phải bật tiện ích
XR_ANDROID_eye_trackingtrước khi sử dụngXrSystemEyeTrackingPropertiesANDROID typephải làXR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROIDnextphải làNULLhoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
Tạo một đối tượng xử lý thiết bị theo dõi mắt
XR_DEFINE_HANDLE(XrEyeTrackerANDROID)
Xử lý XrEyeTrackerANDROID đại diện cho một thiết bị theo dõi mắt để theo dõi mắt và ánh xạ chính xác những gì người dùng đang nhìn.
Dữ liệu theo dõi mắt có thể là thông tin cá nhân nhạy cảm và có liên kết chặt chẽ với quyền riêng tư và tính toàn vẹn của cá nhân. Các ứng dụng lưu trữ hoặc chuyển dữ liệu theo dõi bằng mắt luôn phải yêu cầu người dùng chấp nhận một cách chủ động và cụ thể để làm như vậy.
Bạn có thể dùng đối tượng này để truy cập vào dữ liệu theo dõi ánh mắt bằng các hàm khác trong tiện ích này.
Tính năng theo dõi ánh mắt cung cấp thông tin về tư thế và trạng thái của mắt trong cảnh.
Hàm xrCreateEyeTrackerANDROID được xác định như sau:
XrResult xrCreateEyeTrackerANDROID(
XrSession session,
const XrEyeTrackerCreateInfoANDROID* createInfo,
XrEyeTrackerANDROID* eyeTracker);
Nội dung mô tả về tham số
sessionlà một đối tượngXrSessionmà tính năng theo dõi ánh mắt sẽ hoạt động.createInfolàXrEyeTrackerCreateInfoANDROIDdùng để chỉ định tính năng theo dõi ánh mắt.eyeTrackerlà ô điều khiểnXrEyeTrackerANDROIDđược trả về.
Ứng dụng có thể tạo một đối tượng xử lý XrEyeTrackerANDROID bằng cách sử dụng hàm xrCreateEyeTrackerANDROID.
Nếu hệ thống không hỗ trợ tính năng theo dõi bằng mắt, thì XR_ERROR_FEATURE_UNSUPPORTED sẽ được trả về từ xrCreateEyeTrackerANDROID.
Cách sử dụng hợp lệ (Ngầm)
- Bạn phải bật tiện ích
XR_ANDROID_eye_trackingtrước khi gọixrCreateEyeTrackerANDROID sessionphải là một mã nhận dạngXrSessionhợp lệcreateInfophải là con trỏ đến một cấu trúcXrEyeTrackerCreateInfoANDROIDhợp lệeyeTrackerphải là con trỏ đến một đối tượngXrEyeTrackerANDROID
Mã trả về
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_VALIDATION_FAILUREXR_ERROR_RUNTIME_FAILUREXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHEDXR_ERROR_FEATURE_UNSUPPORTED
Cấu trúc XrEyeTrackerCreateInfoANDROID được xác định là:
typedef struct XrEyeTrackerCreateInfoANDROID {
XrStructureType type;
void* next;
} XrEyeTrackerCreateInfoANDROID;
Nội dung mô tả thành viên
typelàXrStructureTypecủa cấu trúc này.nextlàNULLhoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
Cấu trúc XrEyeTrackerCreateInfoANDROID mô tả thông tin để tạo một giá trị nhận dạng XrEyeTrackerANDROID.
Cách sử dụng hợp lệ (Ngầm)
- Bạn phải bật tiện ích
XR_ANDROID_eye_trackingtrước khi sử dụngXrEyeTrackerCreateInfoANDROID typephải làXR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROIDnextphải làNULLhoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
Hàm xrDestroyEyeTrackerANDROID được xác định như sau:
XrResult xrDestroyEyeTrackerANDROID(
XrEyeTrackerANDROID eyeTracker);
Nội dung mô tả về tham số
eyeTrackerlà mộtXrEyeTrackerANDROIDdoxrCreateEyeTrackerANDROIDtạo trước đó.
Hàm xrDestroyEyeTrackerANDROID sẽ giải phóng eyeTracker và các tài nguyên cơ bản khi hoàn tất các trải nghiệm theo dõi mắt.
Sử dụng hợp lệ (ngầm)
- Bạn phải bật tiện ích
XR_ANDROID_eye_trackingtrước khi gọixrDestroyEyeTrackerANDROID eyeTrackerphải là một giá trị nhận dạngXrEyeTrackerANDROIDhợp lệ.
Độ an toàn cho luồng
- Quyền truy cập vào
eyeTrackervà mọi đối tượng con phải được đồng bộ hoá bên ngoài
Mã trả về
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALID
Lấy thông tin về mắt
Hàm xrGetCoarseTrackingEyesInfoANDROID được xác định như sau:
XrResult xrGetCoarseTrackingEyesInfoANDROID(
XrEyeTrackerANDROID eyeTracker,
const XrEyesGetInfoANDROID* getInfo,
XrEyesANDROID* eyesOutput);
Nội dung mô tả về tham số
eyeTrackerlà mộtXrEyeTrackerANDROIDdoxrCreateEyeTrackerANDROIDtạo trước đó.getInfolà một con trỏ đếnXrEyesGetInfoANDROIDdùng để chỉ định đầu ra cần thiết.infoOutputlà một con trỏ đếnXrEyesANDROIDchứa thông tin về mắt được trả về, bao gồm cả tư thế và trạng thái.
Hàm xrGetCoarseTrackingEyesInfoANDROID lấy thông tin về trạng thái và tư thế mắt theo cách bảo vệ quyền riêng tư của người dùng.
Thời gian chạy phải trả về XR_ERROR_PERMISSION_INSUFFICIENT nếu ứng dụng không có quyền android.permission.EYE_TRACKING_COARSE.
Thông tin về mắt được phân giải và tương ứng với không gian cơ sở tại thời điểm gọi đến xrGetCoarseTrackingEyesInfoANDROID bằng XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.
Tại bất kỳ thời điểm nào, cả vị trí và hướng của tư thế mắt đều được theo dõi hoặc không được theo dõi. Điều này có nghĩa là các ứng dụng có thể dự kiến cả XR_SPACE_LOCATION_POSITION_TRACKED_BIT và XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT sẽ được đặt hoặc xoá trên XrEyesANDROID::eyes được cung cấp và XrEyesANDROID::mode sẽ cho biết trạng thái theo dõi.
Sử dụng hợp lệ (ngầm)
- Bạn phải bật tiện ích
XR_ANDROID_eye_trackingtrước khi gọixrGetCoarseTrackingEyesInfoANDROID eyeTrackerphải là một mã nhận dạngXrEyeTrackerANDROIDhợp lệgetInfophải là con trỏ đến một cấu trúcXrEyesGetInfoANDROIDhợp lệeyesOutputphải là con trỏ đến cấu trúcXrEyesANDROID
Mã trả về
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_VALIDATION_FAILUREXR_ERROR_RUNTIME_FAILUREXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHEDXR_ERROR_TIME_INVALIDXR_ERROR_PERMISSION_INSUFFICIENT
Hàm xrGetFineTrackingEyesInfoANDROID được xác định như sau:
XrResult xrGetFineTrackingEyesInfoANDROID(
XrEyeTrackerANDROID eyeTracker,
const XrEyesGetInfoANDROID* getInfo,
XrEyesANDROID* eyesOutput);
Nội dung mô tả về tham số
eyeTrackerlà mộtXrEyeTrackerANDROIDdoxrCreateEyeTrackerANDROIDtạo trước đó.getInfolà một con trỏ đếnXrEyesGetInfoANDROIDdùng để chỉ định đầu ra cần thiết.infoOutputlà một con trỏ đếnXrEyesANDROIDchứa thông tin về mắt được trả về, bao gồm cả tư thế và trạng thái. HàmxrGetFineTrackingEyesInfoANDROIDlấy thông tin về trạng thái và tư thế của mắt với độ chính xác cao hơnxrGetCoarseTrackingEyesInfoANDROID.
Thời gian chạy phải trả về XR_ERROR_PERMISSION_INSUFFICIENT nếu ứng dụng không có quyền android.permission.EYE_TRACKING_FINE.
Thông tin về mắt được phân giải và tương ứng với không gian cơ sở tại thời điểm gọi đến xrGetFineTrackingEyesInfoANDROID bằng XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.
Tại bất kỳ thời điểm nào, cả vị trí và hướng của tư thế mắt đều được theo dõi hoặc không được theo dõi. Điều này có nghĩa là các ứng dụng có thể dự kiến cả XR_SPACE_LOCATION_POSITION_TRACKED_BIT và XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT sẽ được đặt hoặc xoá trên XrEyesANDROID::eyes được cung cấp và XrEyesANDROID::mode sẽ cho biết trạng thái theo dõi.
Sử dụng hợp lệ (ngầm)
- Bạn phải bật tiện ích
XR_ANDROID_eye_trackingtrước khi gọixrGetFineTrackingEyesInfoANDROID eyeTrackerphải là một mã nhận dạngXrEyeTrackerANDROIDhợp lệgetInfophải là con trỏ đến một cấu trúcXrEyesGetInfoANDROIDhợp lệeyesOutputphải là con trỏ đến cấu trúcXrEyesANDROID
Mã trả về
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_VALIDATION_FAILUREXR_ERROR_RUNTIME_FAILUREXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHEDXR_ERROR_TIME_INVALIDXR_ERROR_PERMISSION_INSUFFICIENT
Cấu trúc XrEyesGetInfoANDROID chứa thông tin cần thiết để truy xuất tư thế và trạng thái của mắt.
typedef struct XrEyesGetInfoANDROID {
XrStructureType type;
void* next;
XrTime time;
XrSpace baseSpace;
} XrEyesGetInfoANDROID;
Nội dung mô tả thành viên
typelàXrStructureTypecủa cấu trúc này.nextlàNULLhoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.timelàXrTimemà tại đó đánh giá các toạ độ tương ứng vớibaseSpace.baseSpacetư thế mắt sẽ tương ứng vớiXrSpacenày tạitime.
Cách sử dụng hợp lệ (Ngầm)
- Bạn phải bật tiện ích
XR_ANDROID_eye_trackingtrước khi sử dụngXrEyesGetInfoANDROID typephải làXR_TYPE_EYES_GET_INFO_ANDROIDnextphải làNULLhoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúcbaseSpacephải là một mã nhận dạngXrSpacehợp lệ
Cấu trúc XrEyesANDROID chứa thông tin về mắt được theo dõi.
typedef struct XrEyesANDROID {
XrStructureType type;
void* next;
XrEyeANDROID eyes[XR_EYE_MAX_ANDROID];
XrEyeTrackingModeANDROID mode;
} XrEyesANDROID;
Nội dung mô tả thành viên
typelàXrStructureTypecủa cấu trúc này.nextlàNULLhoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.eyeslà một mảngXrEyeANDROIDcho mắt trái và mắt phải được lập chỉ mục theoXrEyeIndexANDROID.modelàXrEyeTrackingModeANDROIDđể cho biết mắt có đang theo dõi hay không và mắt nào đang theo dõi.
Cách sử dụng hợp lệ (Ngầm)
- Bạn phải bật tiện ích
XR_ANDROID_eye_trackingtrước khi sử dụngXrEyesANDROID typephải làXR_TYPE_EYES_ANDROIDnextphải làNULLhoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc- Mọi phần tử nhất định của
eyesphải là một cấu trúcXrEyeANDROIDhợp lệ modephải là một giá trịXrEyeTrackingModeANDROIDhợp lệ
Cấu trúc XrEyeANDROID mô tả trạng thái, vị trí và hướng của mắt.
typedef struct XrEyeANDROID {
XrEyeStateANDROID eyeState;
XrPosef eyePose;
} XrEyeANDROID;
Nội dung mô tả thành viên
eyeStatelàXrEyeStateANDROIDcủa mắt.poselà mộtXrPosefxác định vị trí và hướng của nguồn gốc của mắt trong khung tham chiếu củaXrEyesGetInfoANDROID::baseSpacetương ứng. Hướng nhận dạng ở đây biểu thị một trục toạ độ với +Z vào mắt người dùng, +X sang phải và +Y lên trên.
Cách sử dụng hợp lệ (Ngầm)
- Bạn phải bật tiện ích
XR_ANDROID_eye_trackingtrước khi sử dụngXrEyeANDROID eyeStatephải là một giá trịXrEyeStateANDROIDhợp lệ
Liệt kê XrEyeStateANDROID xác định các trạng thái khác nhau của mắt được theo dõi.
typedef enum XrEyeStateANDROID {
XR_EYE_STATE_INVALID_ANDROID = 0,
XR_EYE_STATE_GAZING_ANDROID = 1,
XR_EYE_STATE_SHUT_ANDROID = 2
} XrEyeStateANDROID;
Các enum có ý nghĩa như sau:
Enum |
Nội dung mô tả |
|
Cho biết mắt đang ở trạng thái lỗi hoặc không xuất hiện. |
|
Cho biết mắt đang nhìn chằm chằm. |
|
Cho biết mắt đang nhắm do nháy mắt hoặc chớp mắt. |
Liệt kê XrEyeIndexANDROID để xác định chỉ mục của mắt trái hoặc mắt phải.
typedef enum XrEyeIndexANDROID {
XR_EYE_INDEX_LEFT_ANDROID = 0,
XR_EYE_INDEX_RIGHT_ANDROID = 1
} XrEyeIndexANDROID;
Các enum có ý nghĩa như sau:
Enum |
Nội dung mô tả |
|
Mắt trái. |
|
Mắt phải. |
Liệt kê XrEyeTrackingModeANDROID xác định các chế độ khác nhau của mắt được theo dõi.
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;
Các enum có ý nghĩa như sau:
Enum |
Nội dung mô tả |
|
Cho biết tính năng theo dõi bằng mắt không hoạt động. |
|
Cho biết chỉ mắt phải đang theo dõi. |
|
Cho biết chỉ mắt trái đang theo dõi. |
|
Cho biết cả mắt trái và mắt phải đều đang theo dõi. |
Mã ví dụ để theo dõi ánh mắt
Đoạn mã ví dụ sau đây minh hoạ cách lấy thông tin về mắt so với một không gian xem.
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));
Các loại đối tượng mới
Hằng số Enum mới
XR_EYE_MAX_ANDROID
Liệt kê XrObjectType được mở rộng bằng:
XR_OBJECT_TYPE_EYE_TRACKER_ANDROID
Liệt kê XrStructureType được mở rộng bằng:
XR_TYPE_EYES_ANDROIDXR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROIDXR_TYPE_EYES_GET_INFO_ANDROIDXR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID
Enum mới
Cấu trúc mới
XrEyeANDROIDXrEyesANDROIDXrEyesGetInfoANDROIDXrEyeTrackerCreateInfoANDROIDXrSystemEyeTrackingPropertiesANDROID
Hàm mới
xrCreateEyeTrackerANDROIDxrDestroyEyeTrackerANDROIDxrGetCoarseTrackingEyesInfoANDROIDxrGetFineTrackingEyesInfoANDROID
Vấn đề
Nhật ký phiên bản
- Bản sửa đổi 1, ngày 17/1/2025 (Kenny Vercaemer)
- Nội dung mô tả ban đầu của tiện ích
OpenXR™ và biểu trưng OpenXR là các nhãn hiệu thuộc sở hữu của The Khronos Group Inc. và được đăng ký làm nhãn hiệu ở Trung Quốc, Liên minh Châu Âu, Nhật Bản và Vương quốc Anh.