XR_ANDROID_eye_tracking OpenXR uzantısı

Name String

XR_ANDROID_eye_tracking

Uzantı Türü

Örnek uzantısı

Kayıtlı Uzantı 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 bir IP 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 elde etmesini sağlar.

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

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.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'de 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'dir.

Bir uygulama, xrGetSystemProperties çağrılırken XrSystemEyeTrackingPropertiesANDROID yapısını XrSystemProperties'e zincirleyerek sistemin göz izleme özelliğine sahip olup olmadığını kontrol edebilir. supportsEyeTracking, XR_FALSE değerini döndürürse uygulama, xrCreateEyeTrackerANDROID kaynağından XR_ERROR_FEATURE_UNSUPPORTED değerini alır.

Geçerli Kullanım (Dolaylı)

Göz takip cihazı tutma yeri 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 şekilde eşler.

Göz izleme verileri hassas kişisel bilgiler olabilir ve kişisel gizlilik ile bütünlükle yakından bağlantılıdır. Göz izleme verilerini depolayan veya aktaran uygulamaların, bunu yapabilmek için her zaman kullanıcıdan aktif ve spesifik kabul istemesi önemle tavsiye edilir.

Bu tutma noktası, bu uzantıdaki diğer işlevler kullanılarak göz izleme verilerine erişmek için kullanılabilir.

Göz takibi, sahnedeki göz pozunu ve durumunu gösterir.

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

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

Parametre Açıklamaları

Bir uygulama, xrCreateEyeTrackerANDROID işlevini kullanarak XrEyeTrackerANDROID kullanıcı adı oluşturabilir.

Sistem göz takibini desteklemiyorsa XR_ERROR_FEATURE_UNSUPPORTED xrCreateEyeTrackerANDROID tarafından döndürülür.

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Başarısız

  • 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.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'de veya bu uzantıda bu tür yapılar tanımlanmamıştır.

XrEyeTrackerCreateInfoANDROID yapısı, XrEyeTrackerANDROID kullanıcı adı oluşturmak için gereken bilgileri 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 izleme deneyimleri tamamlandığında eyeTracker ve temel kaynakları serbest bırakır.

Geçerli Kullanım (Dolaylı)

İş parçacığı güvenliği

  • eyeTracker ve tüm alt tanıtıcılarına erişim, harici olarak senkronize edilmelidir.

Dönüş Kodları

Başarılı

  • XR_SUCCESS

Başarısız

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Gözler hakkında bilgi edinme

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 pozisyonlarıyla ilgili bilgileri kullanıcı gizliliğini koruyacak şekilde alır.

Çalışma zamanı, uygulamanın android.permission.EYE_TRACKING_COARSE izni yoksa XR_ERROR_PERMISSION_INSUFFICIENT değerini döndürmelidir.

Gözlerle ilgili bilgiler, xrGetCoarseTrackingEyesInfoANDROID çağrısı sırasında XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace kullanılarak çözülür ve temel alana göre belirlenir.

Göz pozunun hem konumu hem de yönü herhangi bir zamanda izlenebilir veya izlenemez. Bu, uygulamaların hem XR_SPACE_LOCATION_POSITION_TRACKED_BIT hem de XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT'nin sağlanan XrEyesANDROID::eyes üzerinde ayarlanmasını veya temizlenmesini bekleyebileceği ve XrEyesANDROID::mode'nin izleme durumlarını göstereceği anlamına gelir.

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Başarısız

  • 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 fonksiyonu şu şekilde tanımlanır: 

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

Parametre Açıklamaları

Çalışma zamanı, uygulamanın android.permission.EYE_TRACKING_FINE izni yoksa XR_ERROR_PERMISSION_INSUFFICIENT değerini döndürmelidir.

Gözlerle ilgili bilgiler, xrGetFineTrackingEyesInfoANDROID çağrısı sırasında XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace kullanılarak çözülür ve temel alana göre belirlenir.

Göz pozunun hem konumu hem de yönü herhangi bir zamanda izlenebilir veya izlenemez. Bu, uygulamaların hem XR_SPACE_LOCATION_POSITION_TRACKED_BIT hem de XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT'nin sağlanan XrEyesANDROID::eyes üzerinde ayarlanmasını veya temizlenmesini bekleyebileceği ve XrEyesANDROID::mode'nin izleme durumlarını göstereceği anlamına gelir.

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Başarısız

  • 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.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'de veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • time, baseSpace'e göre koordinatların değerlendirileceği XrTime'dır.
  • baseSpace göz pozu, time konumundaki bu XrSpace ile ilgili olacaktır.

Geçerli Kullanım (Dolaylı)

  • XrEyesGetInfoANDROID kullanılmadan önce XR_ANDROID_eye_tracking uzantısı etkinleştirilmelidir.
  • type kesinlikle XR_TYPE_EYES_GET_INFO_ANDROID olmalıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya yönelik 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ı, 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.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'de veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • eyes, XrEyeIndexANDROID ile dizine eklenmiş sol ve sağ gözler için XrEyeANDROID dizisidir.
  • mode, gözlerin takip edip etmediğini ve hangilerinin takip ettiğini belirten 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, gözün XrEyeStateANDROID kısmıdır.
  • pose, ilgili XrEyesGetInfoANDROID::baseSpace referans çerçevesi içinde bir gözün başlangıç noktasının konumunu ve yönünü tanımlayan bir XrPosef'dir. Buradaki kimlik yönü, +Z kullanıcının gözlerine, +X sağa ve +Y yukarı bakacak şekilde koordinat eksenlerini 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ı, 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;

Numaralandırılmış değerler aşağıdaki anlamlara gelir:

Enum

Açıklama

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 baktığını gösterir.

XR_EYE_STATE_SHUT_ANDROID

Gözün, göz kırpma veya göz kapama 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
} XrEyeIndexANDROID;

Numaralandırılmış değerler aşağıdaki anlamlara gelir:

Enum

Açıklama

XR_EYE_INDEX_LEFT_ANDROID

Sol göz.

XR_EYE_INDEX_RIGHT_ANDROID

Sağ göz.

XrEyeTrackingModeANDROID numaralandırması, 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;

Numaralandırılmış değerler aşağıdaki anlamlara gelir:

Enum

Açıklama

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Göz takibinin 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ğini gösterir.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

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

Göz takibi için örnek kod

Aşağıdaki örnek kodda, bir görünüm 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 Sabitleri

  • XR_EYE_MAX_ANDROID

XrObjectType numaralandırması şu öğelerle genişletilir:

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

XrStructureType numaralandırması şu öğelerle genişletilir:

  • 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, 2025-01-17 (Kenny Vercaemer)
    • İlk uzantı açıklaması

OpenXR™ ve OpenXR logosu, The Khronos Group Inc. şirketinin ticari markalarıdır ve Çin, Avrupa Birliği, Japonya ve Birleşik Krallık'ta ticari marka olarak tescillidir.