XR_ANDROID_eye_tracking

Name String

XR_ANDROID_eye_tracking

Uzantı Türü

Örnek uzantısı

Kayıtlı Dahili Numara

457

Düzeltme

1

Onay Durumu

Onaylanmadı

Uzantı ve Sürüm Bağımlılıkları

OpenXR 1.0

Son Değiştirilme Tarihi

2025-01-17

IP Durumu

Bilinen bir fikri mülkiyet hak talebi yok.

Katkıda bulunanlar

Spencer Quin, Google
Jared Finder, Google
Levana Chen, Google
Kenny Vercaemer, Google
Prasanthi Gurumurthy, Google
Nihav Jain, Google

Genel Bakış

Bu uzantı, uygulamaların kullanıcının gözlerinin konumunu ve yönünü, ayrıca göz takibi durumunu öğrenmesini sağlar.

Göz takibi verileri iki modda sağlanır: kaba ve hassas. Kaba izleme, kullanıcının gözlerinin kaba bir tahminini sağlarken hassas izleme daha doğru bir tahmin sağlar. Kaba izleme, avatar benzeri temel bir temsil sağlamak isteyen uygulamalar için, hassas izleme ise daha hassas uygulamalar için tasarlanmıştır.

Etkileşim için XR_EXT_eye_gaze_interaction kullanılmalıdır.

İzinler

Android uygulamalarının manifest dosyasında android.permission.EYE_TRACKING_COARSE veya android.permission.EYE_TRACKING_FINE izni bulunmalıdır. Bu izinler tehlikeli izinler olarak kabul edilir. Uygulama, aşağıdaki işlevleri kullanmak için çalışma zamanında izin istemelidir:

(koruma düzeyi: tehlikeli)

Sistem özelliğini inceleme

XrSystemEyeTrackingPropertiesANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir. Temel OpenXR'da veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • supportsEyeTracking, mevcut sistemin göz takibini destekleyip desteklemediğini gösteren bir XrBool32 değeridir.

Bir uygulama, xrGetSystemProperties çağrısı yaparken XrSystemProperties'i XrSystemEyeTrackingPropertiesANDROID yapısıyla genişleterek sistemin göz takibi yapıp yapamayacağını inceleyebilir.

Yalnızca bir çalışma zamanı supportsEyeTracking için XR_FALSE döndürürse çalışma zamanı xrCreateEyeTrackerANDROID'den XR_ERROR_FEATURE_UNSUPPORTED döndürmelidir .

Geçerli Kullanım (Dolaylı)

Göz izleme tutma yeri oluşturma

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

XrEyeTrackerANDROID herkese açık kullanıcı adı, gözleri takip etmek için bir göz takip cihazını temsil eder ve kullanıcının baktığı yeri doğru bir şekilde eşler.

Göz izleme verileri, hassas kişisel bilgilerdir ve kişisel gizlilik ve bütünlükle yakından bağlantılıdır. Göz izleme verilerini depolayan veya aktaran uygulamaların, bu işlemi yapmak için her zaman kullanıcıdan aktif ve özel bir kabul istemesi önemle tavsiye edilir.

Uygulama, bu uzantıdaki diğer işlevleri kullanarak göz izleme verilerine erişmek için bu tutma noktasını kullanır.

Göz takibi, sahnede göz duruşu ve durum gösterimi sağlar.

xrCreateEyeTrackerANDROID işlevi şu şekilde tanımlanır:

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

Parametre Açıklamaları

Uygulamalar, xrCreateEyeTrackerANDROID işlevini kullanarak bir XrEyeTrackerANDROID herkese açık anahtarı oluşturur.

Sistem göz takibini desteklemiyorsa çalışma zamanı, xrCreateEyeTrackerANDROID'den XR_ERROR_FEATURE_UNSUPPORTED değerini döndürmelidir.

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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

XrEyeTrackerCreateInfoANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir. Temel OpenXR'da veya bu uzantıda bu tür yapılar tanımlanmamıştır.

XrEyeTrackerCreateInfoANDROID yapısı, XrEyeTrackerANDROID herkese açık kullanıcı adı oluşturma bilgilerini açıklar.

Geçerli Kullanım (Dolaylı)

xrDestroyEyeTrackerANDROID işlevi şu şekilde tanımlanır:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Parametre Açıklamaları

xrDestroyEyeTrackerANDROID işlevi, göz takibi deneyimleri tamamlandığında eyeTracker ve temel kaynakları serbest bırakır.

Geçerli Kullanım (Dolaylı)

İleti Dizisi Güvenliği

  • eyeTracker ve tüm alt herkese açık kullanıcı adlarına erişim harici olarak senkronize edilmelidir.

Dönüş Kodları

Başarılı

  • XR_SUCCESS

Hata

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Göz bilgileri alınıyor

xrGetCoarseTrackingEyesInfoANDROID işlevi şu şekilde tanımlanır:

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

Parametre Açıklamaları

  • eyeTracker, daha önce xrCreateEyeTrackerANDROID tarafından oluşturulmuş bir XrEyeTrackerANDROID'dir.
  • getInfo, göz pozlarını ve durumlarını sorgulamak için bilgi sağlamak amacıyla kullanılan XrEyesGetInfoANDROID'e yönelik bir işaretçidir.
  • eyesOutput, pozlar ve durumlar dahil olmak üzere döndürülen göz bilgilerini içeren XrEyesANDROID'e işaret eden bir göstergedir.

xrGetCoarseTrackingEyesInfoANDROID işlevi, göz durumları ve pozları hakkındaki bilgileri kullanıcı gizliliğini koruyacak şekilde alır.

Uygulamada android.permission.EYE_TRACKING_COARSE izni yoksa çalışma zamanı XR_ERROR_PERMISSION_INSUFFICIENT değerini döndürmelidir.

Göz pozları, XrEyesGetInfoANDROID :: time adresindeki XrEyesGetInfoANDROID :: baseSpace ile ifade edilir.

Göz pozunun hem konumu hem de yönü her zaman takip edilir veya takip edilmez. Bu, çalışma zamanının sağlanan XrEyesANDROID :: eyes üzerinde hem XR_SPACE_LOCATION_POSITION_TRACKED_BIT hem de XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT değerlerini ayarlaması veya hem XR_SPACE_LOCATION_POSITION_TRACKED_BIT hem de XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT değerlerini temizlemesi ve izleme durumlarını belirtmek için XrEyesANDROID :: mode değerini ayarlaması gerektiği anlamına gelir.

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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

xrGetFineTrackingEyesInfoANDROID işlevi şu şekilde tanımlanır:

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

Parametre Açıklamaları

xrGetFineTrackingEyesInfoANDROID işlevi, göz durumları ve pozları hakkında xrGetCoarseTrackingEyesInfoANDROID işlevine kıyasla daha hassas bilgi alır.

Uygulamada android.permission.EYE_TRACKING_FINE izni yoksa çalışma zamanı XR_ERROR_PERMISSION_INSUFFICIENT değerini döndürmelidir

Göz bilgileri, XrEyesGetInfoANDROID :: time , XrEyesGetInfoANDROID :: baseSpace kullanılarak xrGetFineTrackingEyesInfoANDROID çağrısı yapıldığı sırada çözümlenir ve temel alanla ilgilidir. Çalışma zamanı, çağrı sırasında XrEyesGetInfoANDROID :: baseSpace tarafından tanımlanan konumu çözmelidir.

Göz pozunun hem konumu hem de yönü her zaman takip edilir veya takip edilmez. Bu, çalışma zamanının sağlanan XrEyesANDROID :: eyes üzerinde hem XR_SPACE_LOCATION_POSITION_TRACKED_BIT hem de XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT değerlerini ayarlaması veya hem XR_SPACE_LOCATION_POSITION_TRACKED_BIT hem de XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT değerlerini temizlemesi ve izleme durumlarını belirtmek için XrEyesANDROID :: mode değerini ayarlaması gerektiği anlamına gelir.

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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

XrEyesGetInfoANDROID yapısı, göz pozlarını ve durumlarını almak için gereken bilgileri içerir.

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir. Temel OpenXR'da veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • time, koordinatların baseSpace ile ilişkili olarak değerlendirileceği XrTime değeridir.
  • baseSpace, göz pozlarının döndürüleceği XrSpace'tir.

Geçerli Kullanım (Dolaylı)

XrEyesANDROID yapısı, takip edilen gözlerle ilgili bilgileri içerir.

typedef struct XrEyesANDROID {
    XrStructureType             type;
    void*                       next;
    XrEyeANDROID                eyes[XR_EYE_MAX_ANDROID];
    XrEyeTrackingModeANDROID    mode;
} XrEyesANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir. Temel OpenXR'da veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • eyes, XrEyeIndexANDROID tarafından dizine eklenen sol ve sağ gözler için XR_EYE_MAX_ANDROID boyutunda bir XrEyeANDROID dizisidir.
  • mode, şu anda hangi gözlerin takip edildiğini gösteren XrEyeTrackingModeANDROID değeridir.

Geçerli Kullanım (Dolaylı)

XrEyeANDROID yapısı, bir gözün durumunu, konumunu ve yönünü açıklar.

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

Üye Açıklamaları

  • eyeState, bir gözün XrEyeStateANDROID değeridir.
  • eyePose, ilgili XrEyesGetInfoANDROID :: baseSpace referans çerçevesi içinde bir gözün göz bebeğinin konumunu ve yönünü tanımlayan bir XrPosef değeridir. Buradaki kimlik yönü, kullanıcının gözlerine doğru +Z, sağa doğru +X ve yukarı doğru +Y olan bir koordinat eksenini temsil eder.

Geçerli Kullanım (Dolaylı)

  • XrEyeANDROID kullanılmadan önce XR_ANDROID_eye_tracking uzantısı etkinleştirilmelidir.
  • eyeState, geçerli bir XrEyeStateANDROID değeri olmalıdır.

XrEyeStateANDROID numaralandırması, takip edilen gözlerin farklı durumlarını tanımlar.

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;

Numaralandırmalar aşağıdaki anlamlara sahiptir:

Enum Açıklaması

XR_EYE_STATE_INVALID_ANDROID

Gözün hata durumunda olduğunu veya mevcut olmadığını gösterir.

XR_EYE_STATE_GAZING_ANDROID

Gözün şu anda baktığını gösterir.

XR_EYE_STATE_SHUT_ANDROID

Gözün göz kırpma nedeniyle kapalı olduğunu gösterir.

XrEyeIndexANDROID numaralandırması, sol veya sağ gözün dizinini tanımlar.

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

Numaralandırmalar aşağıdaki anlamlara sahiptir:

Enum Açıklaması

XR_EYE_INDEX_LEFT_ANDROID

Sol göz.

XR_EYE_INDEX_RIGHT_ANDROID

Sağ göz.

XrEyeTrackingModeANDROID numaralandırması, takip edilen gözlerin farklı durumlarını tanımlar.

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;

Numaralandırmalar aşağıdaki anlamlara sahiptir:

Enum Açıklaması

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Göz takibinin şu anda etkin olmadığını gösterir.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Yalnızca sağ gözün takip edildiğini gösterir.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Yalnızca sol gözün takip edildiğini gösterir.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Hem sol hem de sağ gözün takip edildiğini gösterir.

#define XR_EYE_MAX_ANDROID                2

XR_EYE_MAX_ANDROID, XrEyeANDROID verilerinin raporlandığı maksimum göz sayısıdır.

Göz takibi için örnek kod

Aşağıdaki örnek kodda, bir görüntüleme alanına göre göz bilgilerinin nasıl alınacağı gösterilmektedir.

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

Yeni nesne türleri

Yeni Komutlar

Yeni Yapılar

Yeni Enum Veri Türleri

Yeni Enum Sabitleri

  • XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
  • XR_ANDROID_eye_tracking_SPEC_VERSION
  • XR_EYE_MAX_ANDROID

  • XrObjectType'i genişletme:

    • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

  • XrStructureType'ı genişletme:

    • XR_TYPE_EYES_ANDROID
    • XR_TYPE_EYES_GET_INFO_ANDROID
    • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

Sayılar

Sürüm Geçmişi

  • Düzeltme 1, 17.01.2025 (Kenny Vercaemer)

    • İlk uzantı açıklaması