ส่วนขยาย XR_ANDROID_avatar_eyes OpenXR

สตริงชื่อ

XR_ANDROID_avatar_eyes

ประเภทชิ้นงาน

การขยายเวลาอินสแตนซ์

หมายเลขต่อที่จดทะเบียน

457

การแก้ไข

1

การพึ่งพาส่วนขยายและเวอร์ชัน

OpenXR 1.0

วันที่แก้ไขล่าสุด

2024-09-30

สถานะ IP

ไม่มีการอ้างสิทธิ์ IP ที่รู้จัก

ผู้เขียน

Spencer Quin จาก Google

Jared Finder จาก Google

Levana Chen จาก Google

ภาพรวม

ส่วนขยายนี้ช่วยให้แอปพลิเคชันทราบตําแหน่งและการวางแนวของดวงตาผู้ใช้ รวมถึงสถานะการติดตามสายตา

ส่วนขยายนี้มีไว้เพื่อทำให้การแสดงท่าทางของดวงตาและสถานะสำหรับรูปโปรไฟล์สมจริงยิ่งขึ้น ด้วยเหตุนี้ เราจึงดำเนินการต่อไปนี้

• ซึ่งจะอนุญาตให้มีสถานะที่ไม่มีการติดตาม เช่น การกะพริบ
• ซึ่งช่วยให้ติดตามด้วยกล้องแบบโมโนคูลาร์หรือแบบดูคู่ได้

ไม่ควรใช้ส่วนขยายนี้เพื่อวัตถุประสงค์ในการติดตามสายตาอื่นๆ สําหรับการโต้ตอบ ควรใช้ XR_EXT_eye_gaze_interaction

Eye Tracker

เครื่องมือติดตามสายตาเป็นอุปกรณ์ตรวจจับที่ติดตามการเคลื่อนไหวของดวงตาและจับภาพจุดที่ผู้ใช้กําลังมองอยู่อย่างแม่นยำ วัตถุประสงค์หลักของส่วนขยายนี้คือจับคู่การจ้องมองของผู้ใช้กับภาพแทนของตนในฉากเสมือนจริง

ข้อมูลการติดตามสายตาอาจเป็นข้อมูลส่วนบุคคลที่ละเอียดอ่อนและเชื่อมโยงกับความเป็นส่วนตัวและความเป็นธรรมส่วนบุคคลอย่างใกล้ชิด ขอแนะนําอย่างยิ่งว่าแอปพลิเคชันที่จัดเก็บหรือโอนข้อมูลการติดตามสายตาควรขอความยินยอมที่ชัดเจนและใช้งานอยู่เสมอจากผู้ใช้

• แอปพลิเคชันจะได้รับ XR_ERROR_PERMISSION_INSUFFICIENT เมื่อพยายามสร้างอุปกรณ์ติดตามสายตาที่ทำงานอยู่จนกว่าแอปพลิเคชันจะได้รับอนุญาตให้เข้าถึงอุปกรณ์ติดตามสายตา

ตรวจสอบความสามารถของระบบ

แอปพลิเคชันสามารถตรวจสอบว่าระบบรองรับดวงตาของรูปโปรไฟล์หรือไม่โดยเชื่อมโยงโครงสร้าง XrSystemAvatarEyesPropertiesANDROID กับ XrSystemProperties เมื่อเรียกใช้ xrGetSystemProperties หาก supportsAvatarEyes แสดงผลเป็น XR_FALSE แอปพลิเคชันจะได้รับ XR_ERROR_FEATURE_UNSUPPORTED จาก xrCreateEyeTrackerANDROID

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

คำอธิบายสมาชิก

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• supportsAvatarEyes คือ XrBool32 ซึ่งระบุว่าระบบปัจจุบันรองรับดวงตาของรูปโปรไฟล์หรือไม่

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_avatar_eyes ก่อนใช้ XrSystemAvatarEyesPropertiesANDROID
• type ต้องเป็น XR_TYPE_SYSTEM_AVATAR_EYES_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 ที่แสดงผล

แอปพลิเคชันสามารถสร้างแฮนเดิล XrEyeTrackerANDROID โดยใช้ฟังก์ชัน xrCreateEyeTrackerANDROID

หากระบบไม่รองรับการติดตามการเคลื่อนไหวของตา ระบบจะแสดงผล XR_ERROR_FEATURE_UNSUPPORTED จาก xrCreateEyeTrackerANDROID

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_avatar_eyes ก่อนเรียกใช้ 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

โครงสร้าง XrEyeTrackerCreateInfoANDROID กำหนดไว้ดังนี้

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

คำอธิบายสมาชิก

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้

โครงสร้าง XrEyeTrackerCreateInfoANDROID อธิบายข้อมูลในการสร้างตัวแฮนเดิล XrEyeTrackerANDROID

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_avatar_eyes ก่อนใช้ XrEyeTrackerCreateInfoANDROID
• type ต้องเป็น XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง

ฟังก์ชัน xrDestroyEyeTrackerANDROID มีคำจำกัดความดังนี้

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

คําอธิบายพารามิเตอร์

• eyeTracker คือ XrEyeTrackerANDROID ที่สร้างก่อนหน้านี้โดย xrCreateEyeTrackerANDROID

ฟังก์ชัน xrDestroyEyeTrackerANDROID จะปล่อยeyeTrackerและทรัพยากรพื้นฐานเมื่อประสบการณ์การติดตามสายตาสิ้นสุดลง

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_avatar_eyes ก่อนเรียกใช้ xrDestroyEyeTrackerANDROID
• eyeTracker ต้องเป็นแฮนเดิล XrEyeTrackerANDROID ที่ถูกต้อง

ความปลอดภัยของชุดข้อความ

• การเข้าถึง eyeTracker และตัวแฮนเดิลย่อยต้องได้รับการซิงค์จากภายนอก

รหัสการคืนสินค้า

สำเร็จ

• XR_SUCCESS

ไม่สำเร็จ

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

กำลังรับข้อมูลดวงตา

ฟังก์ชัน xrGetEyesInfoANDROID มีคำจำกัดความดังนี้

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

คําอธิบายพารามิเตอร์

• eyeTracker คือ XrEyeTrackerANDROID ที่สร้างก่อนหน้านี้โดย xrCreateEyeTrackerANDROID
• getInfo คือพอยน์เตอร์ไปยัง XrEyesGetInfoANDROID ที่ใช้เพื่อระบุเอาต์พุตที่ต้องการ
• infoOutput เป็นพอยน์เตอร์ไปยัง XrEyesANDROID ที่มีข้อมูลดวงตาที่แสดงผล ซึ่งรวมถึงท่าทางและสถานะ

ฟังก์ชัน xrGetEyesInfoANDROID จะรับข้อมูลสถานะและท่าทางของดวงตา

ระบบจะแก้ไขข้อมูลดวงตาและสัมพันธ์กับพื้นที่ฐาน ณ เวลาเรียกใช้ xrGetEyesInfoANDROID โดยใช้ XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace

ระบบจะติดตามหรือยกเลิกการติดตามทั้งตำแหน่งและทิศทางของท่าทางของตา ซึ่งหมายความว่าแอปพลิเคชันจะตั้งค่าหรือล้างค่าทั้ง XR_SPACE_LOCATION_POSITION_TRACKED_BIT และ XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT ใน XrEyesANDROID::eyes ที่ระบุ และ XrEyesANDROID::mode จะระบุสถานะการติดตาม

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_avatar_eyes ก่อนเรียกใช้ xrGetEyesInfoANDROID
• eyeTracker ต้องเป็นแฮนเดิล XrEyeTrackerANDROID ที่ถูกต้อง
• getInfo ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrEyesGetInfoANDROID ที่ถูกต้อง
• infoOutput ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง 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

โครงสร้าง XrEyesGetInfoANDROID มีข้อมูลที่จําเป็นในการดึงข้อมูลท่าทางและสถานะของดวงตา

typedef struct XrEyesGetInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrTime             time;
    XrSpace            baseSpace;
} XrEyesGetInfoANDROID;

คำอธิบายสมาชิก

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• time คือ XrTime ที่จะใช้ประเมินพิกัดซึ่งสัมพันธ์กับ baseSpace
• baseSpace การวางตำแหน่งดวงตาจะสัมพันธ์กับ XrSpace นี้ที่ time

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_avatar_eyes ก่อนใช้ 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_avatar_eyes ก่อนใช้ 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_avatar_eyes ก่อนใช้ 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, 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));

ประเภทออบเจ็กต์ใหม่

• XrEyeTrackerANDROID

ค่าคงที่ Enum ใหม่

• 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

Enum ใหม่

• XrEyeIndexANDROID
• XrEyeStateANDROID
• XrEyeTrackingModeANDROID

โครงสร้างใหม่

• XrEyeANDROID
• XrEyesANDROID
• XrEyesGetInfoANDROID
• XrEyeTrackerCreateInfoANDROID
• XrSystemAvatarEyesPropertiesANDROID

ฟังก์ชันใหม่

• xrCreateEyeTrackerANDROID
• xrDestroyEyeTrackerANDROID
• xrGetEyesInfoANDROID

ปัญหา

ประวัติเวอร์ชัน

• การแก้ไข 1, 04-09-2024 (Levana Chen)
  • คำอธิบายส่วนขยายเริ่มต้น