Tiện ích OpenXR XR_ANDROID_avatar_eyes

Chuỗi tên

XR_ANDROID_avatar_eyes

Loại phần mở rộng

Tiện ích thực thể

Số điện thoại mở rộng đã đăng ký

457

Bản sửa đổi

1

Phần mở rộng và phần phụ thuộc phiên bản

OpenXR 1.0

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

2024-09-30

Trạng thái IP

Không có thông báo xác nhận quyền sở hữu đối với tài sản trí tuệ nào.

Cộng tác viên

Spencer Quin, Google

Jared Finder, Google

Levana Chen, 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 mắt.

Tiện ích này nhằm giúp biểu thị tư thế mắt và trạng thái của hình đại diện một cách chân thực hơn. Vì mục đích đó:

  • Chế độ này cho phép các trạng thái không được theo dõi, chẳng hạn như trạng thái nhấp nháy.
  • Cho phép theo dõi bằng một mắt hoặc hai mắt.

Bạn không được sử dụng tiện ích này cho các mục đích theo dõi chuyển động mắt khác. Để tương tác, bạn nên sử dụng XR_EXT_eye_gaze_interaction.

Thiết bị theo dõi ánh mắt

Trình theo dõi mắt là một thiết bị cảm biến theo dõi mắt và lập bản đồ chính xác vị trí người dùng đang nhìn. Mục đích chính của tiện ích này là liên kết ánh mắt của người dùng với hình đại diện của họ trong một cảnh ảo.

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

  • Ứng dụng sẽ nhận được XR_ERROR_PERMISSION_INSUFFICIENT khi cố gắng tạo một thiết bị theo dõi mắt đang hoạt động cho đến khi ứng dụng được cấp quyền truy cập vào thiết bị theo dõi mắt.

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

Ứng dụng có thể kiểm tra xem hệ thống có hỗ trợ mắt hình đại diện hay không bằng cách tạo chuỗi cấu trúc XrSystemAvatarEyesPropertiesANDROID với XrSystemProperties khi gọi xrGetSystemProperties. Nếu supportsAvatarEyes trả về XR_FALSE, thì ứng dụng sẽ nhận được XR_ERROR_FEATURE_UNSUPPORTED từ xrCreateEyeTrackerANDROID.

typedef struct XrSystemAvatarEyesPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAvatarEyes;
} XrSystemAvatarEyesPropertiesANDROID;

Nội dung mô tả 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.
  • supportsAvatarEyes là một XrBool32, cho biết liệu hệ thống hiện tại có hỗ trợ mắt hình đại diện hay không.

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

Tạo tên người dùng cho thiết bị theo dõi mắt

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Tay điều khiển XrEyeTrackerANDROID đại diện cho một trình 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.

Bạn có thể sử dụng tay điều khiển này để truy cập dữ liệu theo dõi mắt bằng các hàm khác trong tiện ích này.

Tính năng theo dõi 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ả tham số

Ứng dụng có thể tạo một tay điều khiển 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 chuyển động mắt, thì XR_ERROR_FEATURE_UNSUPPORTED sẽ được trả về 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_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

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

  • 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 xác định là: 

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Nội dung mô tả tham số

Hàm xrDestroyEyeTrackerANDROID sẽ 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 mắt.

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

Độ an toàn cho luồng

  • 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

Lấy thông tin về mắt

Hàm xrGetEyesInfoANDROID được xác định là:

XrResult xrGetEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              infoOutput);

Nội dung mô tả tham số

Hàm xrGetEyesInfoANDROID lấy thông tin về trạng thái mắt và tư thế.

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 xrGetEyesInfoANDROID bằng cách sử dụ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 rằng 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.

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_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

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

  • 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 tại đó để đánh giá toạ độ tương ứng với baseSpace.
  • baseSpace tư thế mắt sẽ tương ứng với XrSpace này tại time.

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ả 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 cho mắt trái và phải được lập chỉ mục bằng XrEyeIndexANDROID.
  • mode là XrEyeTrackingModeANDROID để cho biết liệu mắt có đang theo dõi hay không và theo dõi mắt nào.

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

  • eyeState là XrEyeStateANDROID của một mắt.
  • pose là một XrPosef xác định vị trí và hướng của gốc 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 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 ẩn)

Biến 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ả

XR_EYE_STATE_INVALID_ANDROID

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

XR_EYE_STATE_GAZING_ANDROID

Cho biết mắt đang nhìn chăm chú.

XR_EYE_STATE_SHUT_ANDROID

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

Biến 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ả

XR_EYE_INDEX_LEFT_ANDROID

Mắt trái.

XR_EYE_INDEX_RIGHT_ANDROID

Mắt phải.

Biến liệt kê XrEyeTrackingModeANDROID xác định các chế độ 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ả

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

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

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

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

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Cho biết chỉ 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.

Mã ví dụ cho tính năng theo dõi chuyển động mắt

Mã ví dụ sau đây minh hoạ cách lấy thông tin về mắt tương ứng với một không gian xem.

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));

Các loại đối tượng mới

Hằng số enum mới

  • XR_EYE_MAX_ANDROID

Bổ sung enum XrObjectType bằng:

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

Bổ sung enum 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

Enum mới

Cấu trúc mới

Hàm mới

Vấn đề

Nhật ký phiên bản

  • Bản sửa đổi 1, ngày 4 tháng 9 năm 2024 (Levana Chen)
    • Nội dung mô tả ban đầu của tiện ích