XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

拡張機能のタイプ

インスタンス拡張機能

Registered Extension Number

707

リビジョン

1

Ratification Status(批准ステータス)

未批准

拡張機能とバージョンの依存関係

XR_ANDROID_face_tracking

最終更新日

2025-12-16

IP ステータス

既知の IP 申し立てはありません。

寄与者

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

概要

この拡張機能により、アプリは複数のデータソースから顔追跡データを取得できます。

サポートされているデータソースのクエリを実行する

アプリケーションは、サポートされている顔追跡 データソースのリストを取得するために xrEnumerateFaceTrackingDataSourcesANDROID を呼び出すべきです。

xrEnumerateFaceTrackingDataSourcesANDROID 関数は次のように定義されます。

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

パラメータの説明

  • instanceXrInstance のハンドルです。
  • systemId は、顔追跡データソースが列挙される XrSystemId です。
  • supportedDataSourcesInputCapacitysupportedDataSources 配列の容量です。必要な容量を取得するリクエストを示す場合は 0 です。
  • supportedDataSourcesOutputCount は、サポートされているデータソースの数、または supportedDataSourcesInputCapacity が不十分な場合に必要な容量です。
  • supportedDataSourcesXrFaceTrackingDataSourceANDROID の配列です。supportedDataSourcesInputCapacity が 0 の場合、NULL になることがあります。
  • 必要な supportedDataSources サイズの取得の詳細については、バッファサイズ パラメータのセクションをご覧ください。

アプリは、xrEnumerateFaceTrackingDataSourcesANDROID 関数を呼び出すことで、システムがサポートするデータソースのリストを列挙できます。

XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTrackingXR_TRUE の場合、ランタイムは xrEnumerateFaceTrackingDataSourcesANDROID から XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID も返さなければなりません。

ランタイムがゼロのデータソースを返した場合、顔追跡はサポートされていません。

ランタイムは、データソースを品質の高い順に返す必要があります

有効な使用方法(暗黙的)

  • xrEnumerateFaceTrackingDataSourcesANDROID を呼び出す前に、XR_ANDROID_face_tracking_data_source 拡張機能を有効にする必要があります
  • instance は、有効な XrInstance ハンドルでなければなりません。
  • supportedDataSourcesOutputCountuint32_t 値へのポインタでなければなりません。
  • supportedDataSourcesInputCapacity0 でない場合、supportedDataSourcessupportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID 値の配列へのポインタでなければなりません。

戻りコード

成功

  • XR_SUCCESS

失敗

  • 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 列挙型は、ランタイムがサポートする可能性のあるさまざまなデータソースを識別します。

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;

列挙子の意味は次のとおりです。

列挙型の説明

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

この構成で画像データを使用することを示します

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

この構成が音声データを使用することを示します

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

この構成が画像データと音声データを使用することを示します

データソースの構成

XrFaceTrackingDataSourceInfoANDROID 構造は次のように記述されます。

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

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、このような構造は定義されていません。
  • requestedDataSourceCount は、アプリケーションがリクエストしたデータソースの数です。
  • requestedDataSourcesXrFaceTrackingDataSourceANDROID 値の配列で、アプリがリクエストするデータソースを指定します。

XrFaceTrackingDataSourceInfoANDROID 構造体は、XrFaceTrackerANDROID ハンドルを作成するためのデータソースを記述します。

アプリは、xrCreateFaceTrackerANDROID を呼び出す際に、XrFaceTrackerCreateInfoANDROID 構造体の次のチェーンで XrFaceTrackingDataSourceInfoANDROID 構造体を渡して、顔追跡用の 1 つ以上のデータソースをリクエストできます。

アプリケーションがデータソースを 1 つも渡さない場合、または xrEnumerateFaceTrackingDataSourcesANDROID によって列挙されなかったデータソースがある場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

ユーザーがリクエストされたすべてのデータソースに対して必要な権限をすべて付与していない場合、ランタイムは XR_ERROR_PERMISSION_INSUFFICIENT を返さなければなりません。

各データソースに必要な権限は次のように定義されています。

  • XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID には android.permission.FACE_TRACKING 権限が必要です。
  • XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID には android.permission.RECORD_AUDIO 権限が必要です。
  • XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID には android.permission.FACE_TRACKING 権限と android.permission.RECORD_AUDIO 権限の両方が必要です。

ランタイムは、XrFaceTrackingDataSourceInfoANDROID : requestedDataSources 配列を、アプリによる優先度が高い順から低い順に解釈しなければなりません。ランタイムは、必要な権限に準拠している最初のデータソースを使用してトラッキング データを生成しなければなりません。トラッカーの有効期間中に権限が取り消され、データソースが使用できなくなった場合、ランタイムは、次に優先順位の高いデータソースの使用を試み続けなければなりません。リクエストされたデータソースのいずれも使用できない場合、ランタイムは xrGetFaceStateANDROID の呼び出しで XrFaceStateANDROID :: isValidXR_FALSE に設定しなければならず、他のフィールドは未定義とみなされます。

有効な使用方法(暗黙的)

権限

Android アプリは、リクエストする権限をマニフェストに記載しなければなりません。android.permission.FACE_TRACKING 権限は危険な権限とみなされます。android.permission.RECORD_AUDIO 権限は危険な権限とみなされます。これらの関数を使用するには、実行時に権限をリクエストする必要があります

(保護レベル: 危険)

XrFaceTrackingDataSourceStateANDROID 構造は次のように記述されます。

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

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、このような構造は定義されていません。
  • dataSource は、顔追跡 データの生成に使用される XrFaceTrackingDataSourceANDROID です。

アプリは、XrFaceTrackingDataSourceStateANDROID 構造体を xrGetFaceStateANDROID に渡される XrFaceStateANDROID 構造体にチェーンして、その呼び出しの顔追跡データの生成に使用されるデータソースをクエリできます。

有効な使用方法(暗黙的)

データソースを使用した顔追跡のサンプルコード。

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

問題

変更履歴

  • リビジョン 1、2024-10-07(Kenny Vercaemer)

    • 拡張機能の最初の説明