XR_ANDROID_avatar_eyes OpenXR uzantısı

Ad dizesi

XR_ANDROID_avatar_eyes

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

2024-09-30

IP Durumu

Bilinen IP hak talepleri yok.

Katkıda bulunanlar

Spencer Quin, Google

Jared Finder, Google

Levana Chen, 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.

Bu uzantı, avatarların göz pozunu ve durum temsilini daha gerçekçi hale getirmeyi amaçlar. Bu amaçla:

  • Göz kırpma gibi izlenmeyen durumlara izin verir.
  • Tek veya çift gözlü izlemeye olanak tanır.

Bu uzantı, göz izlemeyle ilgili başka amaçlarla kullanılmamalıdır. Etkileşim için XR_EXT_eye_gaze_interaction kullanılmalıdır.

Göz İzleyici

Göz izleyici, gözleri izleyen ve kullanıcının nereye baktığını doğru bir şekilde haritalayan bir algılama cihazıdır. Bu uzantının asıl amacı, kullanıcıların bakışlarını sanal bir sahnedeki avatarlarıyla eşleştirmektir.

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.

  • Bir uygulama, göz izleyiciye erişmesine izin verilene kadar etkin bir göz izleyici oluşturmaya çalışırken XR_ERROR_PERMISSION_INSUFFICIENT alır.

Sistem kapasitesini inceleme

Bir uygulama, xrGetSystemProperties çağrısında XrSystemAvatarEyesPropertiesANDROID yapısını XrSystemProperties ile zincirleyerek sistemin avatar gözlerini destekleyip desteklemediğini inceleyebilir. supportsAvatarEyes XR_FALSE döndürürse uygulama, xrCreateEyeTrackerANDROID işlevinden XR_ERROR_FEATURE_UNSUPPORTED alır.

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • 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.
  • supportsAvatarEyes, mevcut sistemin avatar gözlerini destekleyip desteklemediğini belirten bir XrBool32 değeridir.

Geçerli Kullanım (Dolayı)

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

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

XrEyeTrackerANDROID herkese açık kullanıcı adı, gözleri izlemek için kullanılan bir göz izleyiciyi temsil eder ve kullanıcının nereye baktığını doğru bir şekilde haritalandırır.

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ı

Bir uygulama, xrCreateEyeTrackerANDROID işlevini kullanarak XrEyeTrackerANDROID işleyicisi oluşturabilir.

Sistem göz izlemeyi desteklemiyorsa XR_ERROR_FEATURE_UNSUPPORTED, xrCreateEyeTrackerANDROID işlevinden 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

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 değeridir.
  • 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 işleyicisi 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

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

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

Parametre Açıklamaları

xrGetEyesInfoANDROID işlevi, göz durumları ve duruşlarıyla ilgili bilgileri alır.

Göz bilgileri, XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace kullanılarak xrGetEyesInfoANDROID ç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'nin sağlanan XrEyesANDROID::eyes üzerinde ayarlanmasını veya temizlenmesini ve XrEyesANDROID::mode'in 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

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 değeridir.
  • 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'a göre olur.

Geçerli Kullanım (Dolayı)

  • XrEyesGetInfoANDROID işlevi kullanılmadan önce XR_ANDROID_avatar_eyes 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 değeridir.
  • 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 edilip edilmediğini ve hangilerinin takip edildiğini belirten XrEyeTrackingModeANDROID parametresidir.

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 değeridir.
  • pose, bir gözün orijininin ilgili XrEyesGetInfoANDROID::baseSpace referans çerçevesindeki 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_avatar_eyes uzantısı etkinleştirilmelidir.
  • eyeState geçerli bir XrEyeStateANDROID değeri olmalıdır.

XrEyeStateANDROID dizini, 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 dizini, 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;

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

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_AVATAR_EYES_PROPERTIES_ANDROID

Yeni Sıralamalar

Yeni Yapılar

Yeni İşlevler

Sorunlar

Sürüm Geçmişi

  • Düzeltme 1, 04.09.2024 (Levana Chen)
    • İlk uzantı açıklaması