XR_ANDROID_eye_tracking

Name String

XR_ANDROID_eye_tracking

Loại tiện ích

Phần mở rộng thực thể

Số máy lẻ đã đăng ký

457

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa được phê chuẩn

Phần phụ thuộc của tiện ích và phiên bản

OpenXR 1.0

Ngày sửa đổi gần đây nhất

2025-01-17

Trạng thái IP

Không có tuyên bố nào về tài sản 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 thông tin về vị trí và hướng mắt của 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ế độ: sơ bộ và chi tiết. Tính năng theo dõi thô cung cấp thông tin ước tính sơ bộ về mắt của người dùng, còn tính năng theo dõi chính xác 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 các ứng dụng muốn cung cấp hình đại diện cơ bản, còn tính năng theo dõi chính xác dành cho các ứng dụng cần độ chính xác cao hơn.

Để tương tác, bạn nên sử dụng XR_EXT_eye_gaze_interaction.

Quyền

Ứng dụng Android phải có quyền android.permission.EYE_TRACKING_COARSE hoặc android.permission.EYE_TRACKING_FINE trong tệp kê khai. Các quyền này được coi là quyền nguy hiểm. Ứng dụng phải yêu cầu quyền trong thời gian chạy để sử dụng các hàm sau:

(mức độ bảo vệ: nguy hiểm)

Kiểm tra chức năng của hệ thống

Cấu trúc XrSystemEyeTrackingPropertiesANDROID được định nghĩa như sau:

typedef struct XrSystemEyeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsEyeTracking;
} XrSystemEyeTrackingPropertiesANDROID;

Nội dung mô tả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ 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.
  • supportsEyeTracking là một XrBool32 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.

Ứng dụng có thể kiểm tra xem hệ thống có khả năng theo dõi ánh mắt hay không bằng cách mở rộng XrSystemProperties bằng cấu trúc XrSystemEyeTrackingPropertiesANDROID khi gọi xrGetSystemProperties .

Nếu và chỉ khi thời gian chạy trả về XR_FALSE cho supportsEyeTracking , thì thời gian chạy phải trả về XR_ERROR_FEATURE_UNSUPPORTED từ xrCreateEyeTrackerANDROID .

Cách sử dụng hợp lệ (Ngầm ẩn)

Tạo trình xử lý theo dõi ánh mắt

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Tay điều khiển XrEyeTrackerANDROID đại diện cho một trình theo dõi ánh mắt để theo dõi ánh mắt và ánh xạ chính xác nơi người dùng đang nhìn.

Dữ liệu theo dõi ánh mắt là thông tin cá nhân nhạy cảm và có liên quan mật thiết đến quyền riêng tư và tính toàn vẹn của cá nhân. Bạn nên yêu cầu các ứng dụng lưu trữ hoặc chuyển dữ liệu theo dõi ánh mắt luôn yêu cầu người dùng chấp nhận một cách chủ động và cụ thể để làm việc đó.

Ứng dụng sử dụng tay điều khiển 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 định nghĩa như sau:

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

Nội dung mô tả về tham số

  • session là một tay điều khiển XrSession, trong đó tính năng theo dõi ánh mắt sẽ hoạt động.
  • createInfo là XrEyeTrackerCreateInfoANDROID dùng để chỉ định tính năng theo dõi ánh mắt.
  • eyeTracker là tên người dùng XrEyeTrackerANDROID được trả về.

Ứng dụng tạo một tay điều khiển XrEyeTrackerANDROID bằng hàm xrCreateEyeTrackerANDROID.

Nếu hệ thống không hỗ trợ tính năng theo dõi ánh mắt, thì thời gian chạy phải trả về XR_ERROR_FEATURE_UNSUPPORTED từ xrCreateEyeTrackerANDROID .

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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

Cấu trúc XrEyeTrackerCreateInfoANDROID được định nghĩa như sau:

typedef struct XrEyeTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrEyeTrackerCreateInfoANDROID;

Nội dung mô tả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ 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 tay điều khiển XrEyeTrackerANDROID.

Cách sử dụng hợp lệ (Ngầm ẩn)

Hàm xrDestroyEyeTrackerANDROID được định nghĩa như sau:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Nội dung mô tả về tham số

Hàm xrDestroyEyeTrackerANDROID giải phóng eyeTracker và các tài nguyên cơ bản khi hoàn tất trải nghiệm theo dõi ánh mắt.

Cách sử dụng hợp lệ (Ngầm ẩn)

Độ an toàn cho chuỗi

  • Quyền truy cập vào eyeTracker và mọi tay điều khiển con phải được đồng bộ hoá bên ngoài

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Đang lấy thông tin về mắt

Hàm xrGetCoarseTrackingEyesInfoANDROID được định nghĩa như sau:

XrResult xrGetCoarseTrackingEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              eyesOutput);

Nội dung mô tả về tham số

  • eyeTracker là XrEyeTrackerANDROID được tạo trước đó bằng xrCreateEyeTrackerANDROID .
  • getInfo là một con trỏ đến XrEyesGetInfoANDROID dùng để cung cấp thông tin cho việc truy vấn tư thế và trạng thái của mắt.
  • eyesOutput là con trỏ đến XrEyesANDROID chứ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ế của 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.

Tư thế mắt được thể hiện trong XrEyesGetInfoANDROID :: baseSpace tại XrEyesGetInfoANDROID :: time .

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à thời gian chạy phải đặt cả XR_SPACE_LOCATION_POSITION_TRACKED_BIT và XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT hoặc xoá cả XR_SPACE_LOCATION_POSITION_TRACKED_BIT và XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT trên XrEyesANDROID :: eyes được cung cấp, đồng thời đặt XrEyesANDROID :: mode để cho biết trạng thái theo dõi.

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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

Hàm xrGetFineTrackingEyesInfoANDROID được định nghĩa như sau:

XrResult xrGetFineTrackingEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              eyesOutput);

Nội dung mô tả về tham số

Hàm xrGetFineTrackingEyesInfoANDROID lấy thông tin về trạng thái và tư thế của mắt với độ chính xác cao hơn xrGetCoarseTrackingEyesInfoANDROID .

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à liên quan đến không gian cơ sở tại thời điểm gọi xrGetFineTrackingEyesInfoANDROID bằng XrEyesGetInfoANDROID :: time , XrEyesGetInfoANDROID :: baseSpace . Thời gian chạy phải phân giải vị trí do XrEyesGetInfoANDROID :: baseSpace xác định tại thời điểm gọi.

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à thời gian chạy phải đặt cả XR_SPACE_LOCATION_POSITION_TRACKED_BIT và XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT hoặc xoá cả XR_SPACE_LOCATION_POSITION_TRACKED_BIT và XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT trên XrEyesANDROID :: eyes được cung cấp, đồng thời đặt XrEyesANDROID :: mode để cho biết trạng thái theo dõi.

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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

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;
    const void*        next;
    XrTime             time;
    XrSpace            baseSpace;
} XrEyesGetInfoANDROID;

Nội dung mô tả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ 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.
  • time là XrTime để đánh giá toạ độ tương ứng với baseSpace .
  • baseSpace là XrSpace để trả về tư thế mắt.

Cách sử dụng hợp lệ (Ngầm ẩn)

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ả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ 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.
  • eyes là một mảng XrEyeANDROID , có kích thước XR_EYE_MAX_ANDROID , cho mắt trái và mắt phải được lập chỉ mục theo XrEyeIndexANDROID .
  • mode là XrEyeTrackingModeANDROID cho biết mắt nào hiện đang theo dõi.

Cách sử dụng hợp lệ (Ngầm ẩn)

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ả về thành viên

  • eyeState là XrEyeStateANDROID của mắt.
  • eyePose là một XrPosef xác định vị trí và hướng của đồng tử mắt trong khung tham chiếu của XrEyesGetInfoANDROID :: baseSpace tương ứng. Hướng nhận dạng ở đây đại diện cho một trục toạ độ với +Z hướng vào mắt người dùng, +X hướng sang phải và +Y hướng lên trên.

Cách sử dụng hợp lệ (Ngầm ẩn)

  • Tiện ích XR_ANDROID_eye_tracking phải được bật trước khi sử dụng XrEyeANDROID
  • eyeState phải là một giá trị XrEyeStateANDROID hợp lệ

Bảng 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,
    XR_EYE_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeStateANDROID;

Các enum có ý nghĩa như sau:

Nội dung mô tả enum

XR_EYE_STATE_INVALID_ANDROID

Cho biết mắt đang ở trạng thái lỗi hoặc không có mắt.

XR_EYE_STATE_GAZING_ANDROID

Cho biết mắt hiện đang nhìn.

XR_EYE_STATE_SHUT_ANDROID

Cho biết mắt hiện đang nhắm do nháy mắt hoặc chớp mắt.

Bảng 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,
    XR_EYE_INDEX_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeIndexANDROID;

Các enum có ý nghĩa như sau:

Nội dung mô tả enum

XR_EYE_INDEX_LEFT_ANDROID

Mắt trái.

XR_EYE_INDEX_RIGHT_ANDROID

Mắt phải.

Bảng liệt kê XrEyeTrackingModeANDROID xác định các trạng thái 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,
    XR_EYE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeTrackingModeANDROID;

Các enum có ý nghĩa như sau:

Nội dung mô tả enum

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Cho biết tính năng theo dõi ánh mắt hiện không hoạt động.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Cho biết chỉ theo dõi mắt phải.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Cho biết chỉ có mắt trái đang theo dõi.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Cho biết cả mắt trái và mắt phải đều đang theo dõi.

#define XR_EYE_MAX_ANDROID                2

XR_EYE_MAX_ANDROID là số lượng mắt tối đa mà dữ liệu XrEyeANDROID được báo cáo.

Mã ví dụ về tính năng theo dõi ánh mắt

Mã ví dụ sau đây minh hoạ cách lấy thông tin về mắt liên quan đến 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

Lệnh mới

Cấu trúc mới

Enum mới

Hằng số enum mới

  • XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
  • XR_ANDROID_eye_tracking_SPEC_VERSION
  • XR_EYE_MAX_ANDROID

  • Mở rộng XrObjectType :

    • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

  • Mở rộng 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

Vấn đề

Danh sách phiên bản

  • Bản sửa đổi 1, 17/1/2025 (Kenny Vercaemer)

    • Nội dung mô tả ban đầu về tiện ích