XR_ANDROID_eye_tracking OpenXR uzantısı

Ad dizesi

XR_ANDROID_eye_tracking

Uzantı Türü

Örnek uzatma

Kayıtlı Uzatma Numarası

457

Düzeltme

1

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

OpenXR 1.0

Son Değiştirilme Tarihi

2025-01-17

IP Durumu

Bilinen IP hak talepleri 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 izleme durumunu elde etmesine olanak tanır.

Göz izleme verileri kaba ve ince olmak üzere iki modda sağlanır. Kaba izleme, kullanıcının gözleri için kaba bir tahmin sağlarken hassas izleme daha doğru bir tahmin sağlar. Kaba izleme, temel bir avatar benzeri temsil sunmak isteyen uygulamalar içindir. İnce izleme ise daha hassas uygulamalar içindir.

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

Sistem kapasitesini 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'sidir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • supportsEyeTracking, mevcut sistemin göz izlemeyi destekleyip desteklemediğini belirten bir XrBool32 bağımsız değişkenidir.

Bir uygulama, xrGetSystemProperties çağrısı sırasında XrSystemEyeTrackingPropertiesANDROID yapısını XrSystemProperties ile zincirleyerek sistemin göz izleme yapıp yapamayacağını inceleyebilir. supportsEyeTracking XR_FALSE döndürürse uygulama, xrCreateEyeTrackerANDROID kaynağından XR_ERROR_FEATURE_UNSUPPORTED alır.

Geçerli Kullanım (Dolayı)

Göz izleme cihazı herkese açık kullanıcı adı oluşturma

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

XrEyeTrackerANDROID kolu, gözleri izlemek için kullanılan bir göz izleyiciyi temsil eder ve kullanıcının baktığı yeri doğru bir şekilde eşler.

Göz izleme verileri hassas kişisel bilgiler olabilir ve kişisel gizlilik ve dürüstlük ile yakından ilişkilidir. Göz izleme verilerini depolayan veya aktaran uygulamaların, bunu yapmak için her zaman kullanıcıdan etkin ve özel bir onay istemesi önemle tavsiye edilir.

Bu herkese açık kullanıcı adı, bu uzantıda bulunan diğer işlevleri kullanarak göz izleme verilerine erişmek için kullanılabilinir.

Göz izleme, sahnede göz duruşunu ve durumunu gösterir.

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 XrEyeTrackerANDROID herkese açık kullanıcı adı oluşturabilir.

Sistem göz izlemeyi desteklemiyorsa XR_ERROR_FEATURE_UNSUPPORTED, xrCreateEyeTrackerANDROID adresinden döndürülür.

Geçerli Kullanım (Dolayı)

İade Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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_FEATURE_UNSUPPORTED

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

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'sidir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.

XrEyeTrackerCreateInfoANDROID yapısı, XrEyeTrackerANDROID herkese açık kullanıcı adı oluşturmak için gereken bilgileri açıklar.

Geçerli Kullanım (Dolayı)

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

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Parametre Açıklamaları

xrDestroyEyeTrackerANDROID işlevi, göz izleme deneyimleri sona erdiğinde eyeTracker ve temel kaynakları serbest bırakır.

Geçerli Kullanım (Dolayı)

Thread Güvenliği

  • eyeTracker ve alt herkese açık kimliklere erişim, harici olarak senkronize edilmelidir.

İade Kodları

Başarılı

  • XR_SUCCESS

Hata

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Göz bilgilerini alma

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

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

Parametre Açıklamaları

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

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

Gözler bilgileri, XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace kullanılarak xrGetCoarseTrackingEyesInfoANDROID çağrısı sırasında çözülür ve temel alana göre ilişkilendirilir.

İstediğiniz zaman göz pozunun hem konumu hem de yönü izlenebilir veya izleme durdurulabilir. Bu, uygulamaların hem XR_SPACE_LOCATION_POSITION_TRACKED_BIT hem de XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT'ın sağlanan XrEyesANDROID::eyes üzerinde ayarlanmasını veya temizlenmesini ve XrEyesANDROID::mode'ın izleme durumlarını belirtmesini bekleyebileceği anlamına gelir.

Geçerli Kullanım (Dolayı)

İade Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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
  • XR_ERROR_PERMISSION_INSUFFICIENT

xrGetFineTrackingEyesInfoANDROID işlevi şu şekilde tanımlanır: {:#xrGetFineTrackingEyesInfoANDROID} C++ XrResult xrGetFineTrackingEyesInfoANDROID( XrEyeTrackerANDROID eyeTracker, const XrEyesGetInfoANDROID* getInfo, XrEyesANDROID* eyesOutput);

Parametre Açıklamaları

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

Gözler bilgileri, XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace kullanılarak xrGetFineTrackingEyesInfoANDROID çağrısı sırasında çözülür ve temel alana göre ilişkilendirilir.

İstediğiniz zaman göz pozunun hem konumu hem de yönü izlenebilir veya izleme durdurulabilir. Bu, uygulamaların hem XR_SPACE_LOCATION_POSITION_TRACKED_BIT hem de XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT'ın sağlanan XrEyesANDROID::eyes üzerinde ayarlanmasını veya temizlenmesini ve XrEyesANDROID::mode'ın izleme durumlarını belirtmesini bekleyebileceği anlamına gelir.

Geçerli Kullanım (Dolayı)

İade Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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
  • XR_ERROR_PERMISSION_INSUFFICIENT

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

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'sidir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • time, koordinatların baseSpace'e göre değerlendirileceği XrTime bağımsız değişkenidir.
  • baseSpace göz pozu, time'daki bu XrSpace'e göre belirlenir.

Geçerli Kullanım (Dolayı)

  • XrEyesGetInfoANDROID kullanılmadan önce XR_ANDROID_eye_tracking uzantısı etkinleştirilmelidir.
  • type XR_TYPE_EYES_GET_INFO_ANDROID olmalıdır
  • next NULL veya yapı zincirindeki sonraki yapıya işaret eden geçerli bir işaretçi olmalıdır.
  • baseSpace, geçerli bir XrSpace herkese açık kullanıcı adı olmalıdır.

XrEyesANDROID yapısı, izlenen 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'sidir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • eyes, XrEyeIndexANDROID tarafından dizine eklenen sol ve sağ gözler için bir XrEyeANDROID dizisidir.
  • mode, gözlerin takip edip etmediğini ve hangilerini takip ettiğini belirten XrEyeTrackingModeANDROID değeridir.

Geçerli Kullanım (Dolayı)

XrEyeANDROID yapısı, bir gözün durumunu, konumunu ve yönünü tanımlar. 

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

Üye Açıklamaları

  • eyeState, bir gözün XrEyeStateANDROID'sidir.
  • pose, bir gözün orijininin ilgili XrEyesGetInfoANDROID::baseSpace referans çerçevesi içindeki konumunu ve yönünü tanımlayan bir XrPosef bağımsız değişkenidir. Buradaki kimlik yönelimi, +Z kullanıcının gözlerine, +X sağa ve +Y yukarı bakacak şekilde bir koordinat eksenini temsil eder.

Geçerli Kullanım (Dolayı)

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

XrEyeStateANDROID dizilimi, izlenen 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
} XrEyeStateANDROID;

Listeler aşağıdaki anlamlara sahiptir:

Enum

Açıklama

XR_EYE_STATE_INVALID_ANDROID

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

XR_EYE_STATE_GAZING_ANDROID

Gözün baktığını gösterir.

XR_EYE_STATE_SHUT_ANDROID

Göz kırpma veya göz kırpma nedeniyle göz kapalıdır.

XrEyeIndexANDROID dizili listesi, sol veya sağ gözün dizini tanımlar. 

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

Listeler aşağıdaki anlamlara sahiptir:

Enum

Açıklama

XR_EYE_INDEX_LEFT_ANDROID

Sol göz.

XR_EYE_INDEX_RIGHT_ANDROID

Sağ göz.

XrEyeTrackingModeANDROID dizilimi, izlenen gözlerin farklı modları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
} XrEyeTrackingModeANDROID;

Listeler aşağıdaki anlamlara sahiptir:

Enum

Açıklama

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Göz izlemenin etkin olmadığını gösterir.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

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

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Yalnızca sol gözün izlendiği anlamına gelir.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Hem sol hem de sağ gözle izleme yapıldığını gösterir.

Göz izleme 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 Enum Constants

  • XR_EYE_MAX_ANDROID

XrObjectType dizini aşağıdakilerle genişletildi:

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

XrStructureType dizini aşağıdakilerle genişletildi:

  • XR_TYPE_EYES_ANDROID
  • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_EYES_GET_INFO_ANDROID
  • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

Yeni Sıralamalar

Yeni Yapılar

Yeni İşlevler

Sorunlar

Sürüm Geçmişi

  • Düzeltme 1, 17.01.2025 (Kenny Vercaemer)
    • İlk uzantı açıklaması