افزونه XR_ANDROID_avatar_eyes OpenXR

رشته نام

XR_ANDROID_avatar_eyes

نوع پسوند

پسوند نمونه

شماره برنامه افزودنی ثبت شده

457

تجدید نظر

1

وابستگی های افزونه و نسخه

OpenXR 1.0

آخرین تاریخ اصلاح

30-09-2024

وضعیت IP

هیچ ادعای IP شناخته شده ای وجود ندارد.

مشارکت کنندگان

اسپنسر کوین، گوگل

جارد فایندر، گوگل

لوانا چن، گوگل

نمای کلی

این برنامه افزودنی به برنامه ها امکان می دهد موقعیت و جهت چشم های کاربر و همچنین وضعیت ردیابی چشم را بدست آورند.

این برنامه افزودنی برای واقعی‌تر کردن حالت چشم و نمایش وضعیت آواتارها در نظر گرفته شده است. برای این منظور:

  • این اجازه می دهد تا برای حالت های غیر قابل ردیابی مانند چشمک زدن.
  • امکان ردیابی تک چشمی یا دوچشمی را فراهم می کند.

این پسوند نباید برای اهداف دیگر ردیابی چشم استفاده شود. برای تعامل باید از XR_EXT_eye_gaze_interaction استفاده شود.

ردیاب چشم

ردیاب چشم یک دستگاه حسگر است که چشم ها را ردیابی می کند و به طور دقیق از جایی که کاربر به آن نگاه می کند نقشه می کشد. هدف اصلی این افزونه نگاشت نگاه کاربران به آواتارهای آنها در یک صحنه مجازی است.

داده های ردیابی چشم می تواند اطلاعات شخصی حساس باشد و ارتباط نزدیکی با حریم خصوصی و یکپارچگی شخصی دارد. اکیداً توصیه می‌شود که برنامه‌هایی که داده‌های ردیابی چشم را ذخیره یا انتقال می‌دهند همیشه از کاربر درخواست پذیرش فعال و خاص برای انجام این کار را داشته باشند.

  • یک برنامه در هنگام تلاش برای ایجاد یک ردیاب چشم فعال، XR_ERROR_PERMISSION_INSUFFICIENT دریافت می کند تا زمانی که برنامه اجازه دسترسی به ردیاب چشم را پیدا کند.

قابلیت سیستم را بررسی کنید

هنگام فراخوانی xrGetSystemProperties، یک برنامه کاربردی می تواند با زنجیر کردن ساختار XrSystemAvatarEyesPropertiesANDROID به XrSystemProperties، بررسی کند که آیا سیستم از چشم های آواتار پشتیبانی می کند یا خیر. اگر 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_DEFINE_HANDLE(XrEyeTrackerANDROID)

دسته XrEyeTrackerANDROID یک ردیاب چشم برای ردیابی چشم ها را نشان می دهد و به طور دقیق آنچه کاربر به آن نگاه می کند را ترسیم می کند.

از این دسته می توان برای دسترسی به داده های ردیابی چشم با استفاده از سایر عملکردهای این افزونه استفاده کرد.

ردیابی چشم وضعیت و وضعیت چشم را در صحنه نمایش می دهد.

تابع xrCreateEyeTrackerANDROID به صورت زیر تعریف می شود:

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

توضیحات پارامترها

یک برنامه می تواند با استفاده از تابع xrCreateEyeTrackerANDROID یک دسته XrEyeTrackerANDROID ایجاد کند.

اگر سیستم از ردیابی چشم پشتیبانی نمی کند، XR_ERROR_FEATURE_UNSUPPORTED از xrCreateEyeTrackerANDROID برگردانده می شود.

استفاده معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • 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 توصیف می کند.

استفاده معتبر (ضمنی)

تابع xrDestroyEyeTrackerANDROID به صورت زیر تعریف می شود:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

توضیحات پارامترها

تابع xrDestroyEyeTrackerANDROID پس از اتمام تجربه ردیابی چشم eyeTracker و منابع زیرین را آزاد می کند.

استفاده معتبر (ضمنی)

ایمنی نخ

  • دسترسی به 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:: وضعیت ردیابی را نشان می‌دهد.

استفاده معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • 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 خواهد بود.

استفاده معتبر (ضمنی)

ساختار 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 است که نشان می دهد آیا چشم ها در حال ردیابی هستند و کدام یک.

استفاده معتبر (ضمنی)

ساختار XrEyeANDROID وضعیت، موقعیت و جهت یک چشم را توصیف می کند.

typedef struct XrEyeANDROID {
    XrEyeStateANDROID    eyeState;
    XrPosef              eyePose;
} XrEyeANDROID;

توضیحات اعضا

  • eyeState XrEyeStateANDROID یک چشم است.
  • pose یک XrPosef است که موقعیت و جهت مبدا چشم را در چارچوب مرجع XrEyesGetInfoANDROID::baseSpace مربوطه تعریف می کند. جهت هویت در اینجا یک محور مختصات با +Z در چشم کاربر، +X در سمت راست و +Y به بالا را نشان می دهد.

استفاده معتبر (ضمنی)

شمارش XrEyeStateANDROID حالت های مختلف چشم های ردیابی شده را مشخص می کند. 

typedef enum XrEyeStateANDROID {
    XR_EYE_STATE_INVALID_ANDROID = 0,
    XR_EYE_STATE_GAZING_ANDROID = 1,
    XR_EYE_STATE_SHUT_ANDROID = 2
} XrEyeStateANDROID;

enum ها معانی زیر را دارند:

Enum

توضیحات

XR_EYE_STATE_INVALID_ANDROID

نشان می دهد که چشم در حالت خطا قرار دارد یا وجود ندارد.

XR_EYE_STATE_GAZING_ANDROID

نشان می دهد که چشم در حال خیره شدن است.

XR_EYE_STATE_SHUT_ANDROID

نشان دهنده بسته شدن چشم در اثر چشمک زدن یا پلک زدن است.

شمارش XrEyeIndexANDROID شاخص چشم چپ یا راست را مشخص می کند. 

typedef enum XrEyeIndexANDROID {
    XR_EYE_INDEX_LEFT_ANDROID = 0,
    XR_EYE_INDEX_RIGHT_ANDROID = 1
} XrEyeIndexANDROID;

enum ها معانی زیر را دارند:

Enum

توضیحات

XR_EYE_INDEX_LEFT_ANDROID

چشم چپ.

XR_EYE_INDEX_RIGHT_ANDROID

چشم راست

شمارش 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;

enum ها معانی زیر را دارند:

Enum

توضیحات

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

نشان می دهد که ردیابی چشم فعال نیست.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

نشان می دهد که فقط چشم راست در حال ردیابی است.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

نشان می دهد که فقط چشم چپ در حال ردیابی است.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

نشان می دهد که هر دو چشم چپ و راست در حال ردیابی هستند.

کد مثال برای ردیابی چشم

کد مثال زیر نحوه بدست آوردن اطلاعات چشم را نسبت به فضای دید نشان می دهد. 

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

انواع اشیاء جدید

ثابت های جدید 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

فهرست های جدید

ساختارهای جدید

توابع جدید

مسائل

تاریخچه نسخه

  • بازبینی 1، 04/09/2024 (لوانا چن)
    • توضیحات پسوند اولیه