XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

Uzantı Türü

Örnek uzantısı

Kayıtlı Dahili Numara

707

Düzeltme

1

Onay Durumu

Onaylanmadı

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

XR_ANDROID_face_tracking

Son Değiştirilme Tarihi

2025-12-16

IP Durumu

Bilinen bir fikri mülkiyet hak talebi yok.

Katkıda bulunanlar

Kenny Vercaemer, Google
Yinglei Zhang, Google
Nihav Jain, Google
Spencer Quin, Google

Genel Bakış

Bu uzantı, uygulamaların birden fazla veri kaynağından yüz takibi verileri almasına olanak tanır.

Desteklenen veri kaynaklarını sorgulama

Uygulamalar, desteklenen yüz takibi veri kaynaklarının listesini almak için xrEnumerateFaceTrackingDataSourcesANDROID işlevini çağırmalıdır.

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

XrResult                                                                                 xrEnumerateFaceTrackingDataSourcesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedDataSourcesInputCapacity,
    uint32_t*                                   supportedDataSourcesOutputCount,
    XrFaceTrackingDataSourceANDROID*            supportedDataSources);

Parametre Açıklamaları

• instance, bir XrInstance için herkese açık kullanıcı adıdır.
• systemId, yüz takibi veri kaynaklarının numaralandırılacağı XrSystemId değeridir.
• supportedDataSourcesInputCapacity, supportedDataSources dizisinin kapasitesidir veya gerekli kapasiteyi alma isteğini belirtmek için 0'dır.
• supportedDataSourcesOutputCount, desteklenen veri kaynaklarının sayısı veya supportedDataSourcesInputCapacity'in yetersiz olması durumunda gereken kapasitedir.
• supportedDataSources, XrFaceTrackingDataSourceANDROID dizisidir. supportedDataSourcesInputCapacity 0 ise NULL olabilir.
• Gerekli supportedDataSources boyutunu alma hakkında ayrıntılı açıklama için Arabellek Boyutu Parametreleri bölümüne bakın.

Uygulama, xrEnumerateFaceTrackingDataSourcesANDROID işlevini çağırarak sistem tarafından desteklenen veri kaynaklarının listesini numaralandırabilir.

XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking, XR_TRUE ise çalışma zamanı, xrEnumerateFaceTrackingDataSourcesANDROID'den XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID değerini de döndürmelidir.

Çalışma zamanı sıfır veri kaynağı döndürürse hiçbir yüz takibi türünü desteklemiyor demektir.

Çalışma zamanı, veri kaynaklarını en yüksek kaliteden en düşük kaliteye doğru sıralayarak döndürmelidir.

Geçerli Kullanım (Dolaylı)

• xrEnumerateFaceTrackingDataSourcesANDROID çağrılmadan önce XR_ANDROID_face_tracking_data_source uzantısı etkinleştirilmelidir.
• instance geçerli bir XrInstance herkese açık kullanıcı adı olmalıdır
• supportedDataSourcesOutputCount, bir uint32_t değerine işaretçi olmalıdır
• supportedDataSourcesInputCapacity, 0 değilse supportedDataSources, supportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID değerlerinden oluşan bir diziye işaretçi olmalıdır.

Dönüş Kodları

Başarılı

• XR_SUCCESS

Hata

• XR_ERROR_FEATURE_UNSUPPORTED
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SYSTEM_INVALID
• XR_ERROR_VALIDATION_FAILURE

XrFaceTrackingDataSourceANDROID numaralandırması, çalışma zamanının destekleyebileceği farklı veri kaynaklarını tanımlar.

typedef enum XrFaceTrackingDataSourceANDROID {
    XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID = 1,
    XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID = 2,
    XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID = 3,
    XR_FACE_TRACKING_DATA_SOURCE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrFaceTrackingDataSourceANDROID;

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

Enum Açıklaması

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

Bu yapılandırmanın resim verilerini kullandığını gösterir.

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

Bu yapılandırmanın ses verilerini kullandığını gösterir.

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

Bu yapılandırmanın görüntü ve ses verilerini kullandığını gösterir.

Veri kaynaklarını yapılandırma

XrFaceTrackingDataSourceInfoANDROID yapısı aşağıdaki gibi açıklanır:

typedef struct XrFaceTrackingDataSourceInfoANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  requestedDataSourceCount;
    const XrFaceTrackingDataSourceANDROID*    requestedDataSources;
} XrFaceTrackingDataSourceInfoANDROID;

Ü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.
• requestedDataSourceCount, uygulama tarafından istenen veri kaynaklarının sayısıdır.
• requestedDataSources, uygulama tarafından istenen veri kaynaklarını belirten bir XrFaceTrackingDataSourceANDROID değerleri dizisidir.

XrFaceTrackingDataSourceInfoANDROID yapısı, XrFaceTrackerANDROID herkese açık kullanıcı adı oluşturmak için veri kaynaklarını açıklar.

Uygulamalar, xrCreateFaceTrackerANDROID işlevini çağırırken yüz takibi için bir veya daha fazla veri kaynağı istemek üzere XrFaceTrackerCreateInfoANDROID yapısının sonraki zincirinde bir XrFaceTrackingDataSourceInfoANDROID yapısı iletebilir.

Uygulama sıfır veri kaynağı iletir veya veri kaynaklarından herhangi biri xrEnumerateFaceTrackingDataSourcesANDROID tarafından listelenmezse çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir (must).

Kullanıcı, istenen tüm veri kaynakları için gerekli tüm izinleri vermediyse çalışma zamanı XR_ERROR_PERMISSION_INSUFFICIENT değerini döndürmelidir (must).

Her bir veri kaynağı için gerekli izinler şu şekilde tanımlanır:

• XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID, android.permission.FACE_TRACKING iznini gerektirir.
• XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID, android.permission.RECORD_AUDIO iznini gerektirir.
• XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID için hem android.permission.FACE_TRACKING hem de android.permission.RECORD_AUDIO izinleri gerekir.

Çalışma zamanı, XrFaceTrackingDataSourceInfoANDROID : requestedDataSources dizisini uygulama tarafından en yüksek tercihten en düşük tercihe doğru yorumlamalıdır. Çalışma zamanı, gerekli izinlere uymaya devam eden ilk istenen veri kaynağını kullanarak izleme verileri oluşturmalıdır. İzleyicinin kullanım ömrü sırasında bir iznin iptal edilmesi nedeniyle bir veri kaynağı artık kullanılamaz hale gelirse çalışma zamanı, bir sonraki en yüksek tercih edilen veri kaynağını kullanmaya çalışmaya devam etmelidir. İstenen veri kaynaklarından hiçbiri kullanılamıyorsa çalışma zamanı, xrGetFaceStateANDROID çağrılarında XrFaceStateANDROID :: isValid değerini XR_FALSE olarak ayarlamalıdır. Diğer alanlar ise tanımsız olarak kabul edilir.

Geçerli Kullanım (Dolaylı)

• XrFaceTrackingDataSourceInfoANDROID kullanılmadan önce XR_ANDROID_face_tracking_data_source uzantısı etkinleştirilmelidir.
• type XR_TYPE_FACE_TRACKING_DATA_SOURCE_INFO_ANDROID olmalıdır
• next, NULL veya yapı zincirindeki bir sonraki yapıya geçerli bir işaretçi olmalıdır.
• requestedDataSources, requestedDataSourceCount geçerli XrFaceTrackingDataSourceANDROID değerinden oluşan bir diziye işaretçi olmalıdır.
• requestedDataSourceCount parametresi 0 değerinden büyük olmalıdır.

İzinler

Android uygulamalarının, istemeyi planladıkları izinleri manifest dosyalarında listelemeleri gerekir. android.permission.FACE_TRACKING izni tehlikeli bir izin olarak kabul edilir. android.permission.RECORD_AUDIO izni tehlikeli bir izin olarak kabul edilir. Uygulama, bu işlevleri kullanmak için çalışma zamanında izinleri istemelidir:

• xrCreateFaceTrackerANDROID

(koruma düzeyi: tehlikeli)

XrFaceTrackingDataSourceStateANDROID yapısı aşağıdaki gibi açıklanır:

typedef struct XrFaceTrackingDataSourceStateANDROID {
    XrStructureType                    type;
    void*                              next;
    XrFaceTrackingDataSourceANDROID    dataSource;
} XrFaceTrackingDataSourceStateANDROID;

Ü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.
• dataSource, yüz takibi verilerini oluşturmak için kullanılan XrFaceTrackingDataSourceANDROID'dir.

Bir uygulama, xrGetFaceStateANDROID'e iletilen bir XrFaceStateANDROID yapısına XrFaceTrackingDataSourceStateANDROID yapısını zincirleyerek ilgili çağrı için yüz takibi verilerini oluşturmak üzere kullanılan veri kaynağını sorgulayabilir.

Geçerli Kullanım (Dolaylı)

• XrFaceTrackingDataSourceStateANDROID kullanılmadan önce XR_ANDROID_face_tracking_data_source uzantısı etkinleştirilmelidir.
• type XR_TYPE_FACE_TRACKING_DATA_SOURCE_STATE_ANDROID olmalıdır
• next, NULL veya yapı zincirindeki bir sonraki yapıya geçerli bir işaretçi olmalıdır.
• dataSource geçerli bir XrFaceTrackingDataSourceANDROID değeri olmalıdır.

Veri kaynağıyla yüz takibi için örnek kod.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized, e.g. created at app startup.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateFaceTrackerANDROID xrCreateFaceTrackerANDROID; // previously initialized
PFN_xrDestroyFaceTrackerANDROID xrDestroyFaceTrackerANDROID; // previously initialized
PFN_xrGetFaceStateANDROID xrGetFaceStateANDROID; // previously initialized
PFN_xrEnumerateFaceTrackingDataSourcesANDROID xrEnumerateFaceTrackingDataSourcesANDROID; // previously initialized
bool (*requestPermission)(const char* permission);

// Inspect data sources supported by the system.
uint32_t dataSourcesCount = 0;
CHK_XR(xrEnumerateFaceTrackingDataSourcesANDROID(instance, systemId, dataSourcesCount,
       &dataSourcesCount, nullptr));
std::vector<XrFaceTrackingDataSourceANDROID> dataSources(dataSourcesCount);
CHK_XR(xrEnumerateFaceTrackingDataSourcesANDROID(instance, systemId, dataSourcesCount,
       &dataSourcesCount, dataSources.data()));

if (dataSources.size() == 0) {
  // System does not support face tracking at all ...
  return;
}

auto requestDataSourcePermissions = [requestPermission](XrFaceTrackingDataSourceANDROID dataSource) {
  switch (dataSource) {
    case XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID:
      return requestPermission("android.permission.FACE_TRACKING");
    case XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID:
      return requestPermission("android.permission.RECORD_AUDIO");
    case XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID:
      return requestPermission("android.permission.FACE_TRACKING") &&
             requestPermission("android.permission.RECORD_AUDIO");
    default:
      return false;
  }
};

// Request permissions and remove data sources that are not granted.
for (uint32_t i = 0; i < dataSources.size();) {
  if (requestDataSourcePermissions(dataSources[i])) {
    ++i;
    continue;
  }

  dataSources.erase(dataSources.begin() + i);
}

if (dataSources.size() == 0) {
  // User denied all permissions, cannot create face tracker.
  return;
}

// Create face tracker with requested data sources.
XrFaceTrackerANDROID faceTracker;
XrFaceTrackingDataSourceInfoANDROID
        faceTrackerModeInfo{.type = XR_TYPE_FACE_TRACKING_DATA_SOURCE_INFO_ANDROID,
                       .next = nullptr,
                       .requestedDataSourceCount = static_cast<uint32_t>(
                           dataSources.size()),
                       .requestedDataSources = dataSources.data()};
XrFaceTrackerCreateInfoANDROID
        createInfo{.type = XR_TYPE_FACE_TRACKER_CREATE_INFO_ANDROID,
                    .next = &faceTrackerModeInfo};
CHK_XR(xrCreateFaceTrackerANDROID(session, &createInfo, &faceTracker));

XrFaceTrackingDataSourceStateANDROID dataSourceState{
  .type = XR_TYPE_FACE_TRACKING_DATA_SOURCE_STATE_ANDROID,
  .next = nullptr};
XrFaceStateANDROID faceState;
float faceExpressionParameters[XR_FACE_PARAMETER_COUNT_ANDROID];
faceState.type = XR_TYPE_FACE_STATE_ANDROID;
faceState.next = &dataSourceState;
faceState.parametersCapacityInput = XR_FACE_PARAMETER_COUNT_ANDROID;
faceState.parameters = faceExpressionParameters;

while (1) {
    // ...
    // For every frame in the frame loop
    // ...
    XrFrameState frameState; // previously returned from xrWaitFrame

    XrFaceStateGetInfoANDROID faceGetInfo{
            .type = XR_TYPE_FACE_STATE_GET_INFO_ANDROID,
            .next = nullptr,
            .time = frameState.predictedDisplayTime,
    };

    CHK_XR(xrGetFaceStateANDROID(faceTracker, &faceGetInfo, &faceState));
    if (faceState.isValid) {
        for (uint32_t i = 0; i < XR_FACE_PARAMETER_COUNT_ANDROID; ++i) {
            // parameters[i] contains a weight of specific blend shape
        }

        // If the system changes data source because of permission changes,
        // handle the new data source ...
        switch (dataSourceState.dataSource) {
          default:
            break;
        }
    }
}

// after usage
CHK_XR(xrDestroyFaceTrackerANDROID(faceTracker));

Sorunlar

Sürüm Geçmişi

• 1. düzeltme, 07.10.2024 (Kenny Vercaemer)

  • İlk uzantı açıklaması