XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

Uzantı Türü

Örnek uzantısı

Kayıtlı Uzantı Numarası

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 IP 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ını sağlar.

Desteklenen veri kaynaklarını sorgulama

Uygulamalar, desteklenen yüz takibi veri kaynaklarının listesini almak için xrEnumerateFaceTrackingDataSourcesANDROID'i ç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, XrInstance için bir tutamaktır .
• systemId, yüz takibi veri kaynaklarının numaralandırılacağı XrSystemId'dır.
• supportedDataSourcesInputCapacity, supportedDataSources dizisinin kapasitesidir veya gerekli kapasitenin alınması için istek olduğunu belirtmek üzere 0'dır.
• supportedDataSourcesOutputCount, desteklenen veri kaynaklarının sayısıdır veya supportedDataSourcesInputCapacity yetersizse gereken kapasitedir.
• supportedDataSources, XrFaceTrackingDataSourceANDROID dizisidir . supportedDataSourcesInputCapacity 0 ise sonuç NULL olabilir.
• Gerekli supportedDataSources boyutunun alınmasıyla ilgili 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 işlevinden de XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID döndürmelidir.

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

Ç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ı)

• XR_ANDROID_face_tracking_data_source uzantısı, xrEnumerateFaceTrackingDataSourcesANDROID çağrılmadan önce etkinleştirilmelidir.
• instance geçerli bir XrInstance işleyeni olmalıdır.
• supportedDataSourcesOutputCount, uint32_t değerine yönelik bir işaretçi olmalıdır.
• supportedDataSourcesInputCapacity, 0 değilse supportedDataSources, supportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID değerleri dizisine yönelik bir işaretçi olmalıdır.

Dönüş Kodları

Başarılı

• XR_SUCCESS

Başarısız

• 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ı, bir ç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ırılmış değerler şu anlamlara gelir:

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 resim ve ses verilerini kullandığını gösterir.

Veri kaynaklarını yapılandırma

XrFaceTrackingDataSourceInfoANDROID yapısı şu şekilde 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'ıdır.
• 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.
• requestedDataSourceCount, uygulama tarafından istenen veri kaynaklarının sayısıdır.
• requestedDataSources, uygulama tarafından istenen veri kaynaklarını belirten XrFaceTrackingDataSourceANDROID değerlerinden oluşan bir dizidir.

XrFaceTrackingDataSourceInfoANDROID yapısı, XrFaceTrackerANDROID tutacı oluşturmak için veri kaynaklarını açıklar.

Bir uygulama, xrCreateFaceTrackerANDROID çağrılırken yüz takibi için bir veya daha fazla veri kaynağı istemek üzere XrFaceTrackerCreateInfoANDROID yapısının sonraki zincirinde XrFaceTrackingDataSourceInfoANDROID yapısını geçirebilir .

Uygulama sıfır veri kaynağı geçiriyorsa veya veri kaynaklarından herhangi biri xrEnumerateFaceTrackingDataSourcesANDROID tarafından numaralandırılmamışsa çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir .

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

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

• XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID için android.permission.FACE_TRACKING izni gerekir.
• XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID için android.permission.RECORD_AUDIO izni gerekir.
• XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID hem android.permission.FACE_TRACKING hem de android.permission.RECORD_AUDIO izinlerini gerektirir.

Çalışma zamanı, XrFaceTrackingDataSourceInfoANDROID : requestedDataSources dizisini uygulamaya göre 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 üretmelidir. İzleyici kullanım ömrü boyunca bir izin iptal edilirse ve bu durum veri kaynağının artık kullanılamamasına neden olursa çalışma zamanı, bir sonraki en yüksek tercihe sahip 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 ve diğer alanlar tanımlanmamış olarak kabul edilir.

Geçerli Kullanım (Dolaylı)

• XR_ANDROID_face_tracking_data_source uzantısı, XrFaceTrackingDataSourceInfoANDROID kullanılmadan önce etkinleştirilmelidir.
• type XR_TYPE_FACE_TRACKING_DATA_SOURCE_INFO_ANDROID olmalıdır.
• next must be NULL or a valid pointer to the next structure in a structure chain
• requestedDataSources requestedDataSourceCount geçerli XrFaceTrackingDataSourceANDROID değerlerinden oluşan bir dizinin işaretçisi olmalıdır.
• requestedDataSourceCount parametresi 0 değerinden büyük olmalıdır.

İzinler

Android uygulamaları, manifest dosyalarında talep etmeyi planladıkları izinleri listelemelidir. 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 izinleri çalışma zamanında istemelidir:

• xrCreateFaceTrackerANDROID

(Koruma düzeyi: tehlikeli)

XrFaceTrackingDataSourceStateANDROID yapısı şu şekilde açıklanır:

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

Üye Açıklamaları

• type, bu yapının XrStructureType'ıdır.
• 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.
• dataSource, yüz takibi verilerini üretmek için kullanılan XrFaceTrackingDataSourceANDROID'dir.

Bir uygulama, bu çağrı için yüz takibi verilerini üretmek üzere kullanılan veri kaynağını sorgulamak amacıyla xrGetFaceStateANDROID'e iletilen bir XrFaceStateANDROID yapısına XrFaceTrackingDataSourceStateANDROID yapısını zincirleyebilir.

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 must be NULL or a valid pointer to the next structure in a structure chain
• 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ı