XR_ANDROID_face_tracking_data_source
Name String
XR_ANDROID_face_tracking_data_source
拡張機能の種類
インスタンス拡張
登録済みの内線番号
707
リビジョン
1
承認ステータス
未批准
拡張機能とバージョンの依存関係
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);
パラメータの説明
instanceは XrInstance のハンドルです。systemIdは、顔追跡データソースが列挙されるXrSystemIdです。supportedDataSourcesInputCapacityはsupportedDataSources配列の容量です。0 の場合は、必要な容量を取得するリクエストであることを示します。supportedDataSourcesOutputCountは、サポートされているデータソースの数、またはsupportedDataSourcesInputCapacityが不十分な場合に必要となる容量です。supportedDataSourcesは XrFaceTrackingDataSourceANDROID の配列です。supportedDataSourcesInputCapacityが 0 の場合、NULLになることがあります。- 必要な
supportedDataSourcesサイズの取得の詳細については、バッファサイズ パラメータのセクションをご覧ください。
アプリは、xrEnumerateFaceTrackingDataSourcesANDROID 関数を呼び出すことで、システムがサポートするデータソースのリストを列挙できます。
XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking が XR_TRUE の場合、ランタイムは xrEnumerateFaceTrackingDataSourcesANDROID から XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID も返さなければなりません。
ランタイムがゼロ個のデータソースを返す場合、いかなる種類の顔追跡もサポートしていません。
ランタイムは、品質の高い順にデータソースを返す必要があります。
有効な使用方法（暗黙的）
-
XR_ANDROID_face_tracking_data_source拡張機能は、xrEnumerateFaceTrackingDataSourcesANDROID を呼び出す前に有効にする必要があります。 -
instanceは、有効な XrInstance ハンドルでなければなりません。 -
supportedDataSourcesOutputCountはuint32_t値へのポインタでなければなりません -
supportedDataSourcesInputCapacityが0でない場合、supportedDataSourcesはsupportedDataSourcesInputCapacityXrFaceTrackingDataSourceANDROID 値の配列へのポインタでなければなりません。
戻りコード
XR_SUCCESS
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SYSTEM_INVALIDXR_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は、アプリケーションによってリクエストされたデータソースの数です。requestedDataSourcesは XrFaceTrackingDataSourceANDROID 値の配列で、アプリがリクエストするデータソースを指定します。
XrFaceTrackingDataSourceInfoANDROID 構造体は、XrFaceTrackerANDROID ハンドルを作成するデータソースを記述します。
アプリは、xrCreateFaceTrackerANDROID を呼び出すときに、XrFaceTrackerCreateInfoANDROID 構造体の次のチェーンで XrFaceTrackingDataSourceInfoANDROID 構造体を渡して、顔追跡用の 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 :: isValid を XR_FALSE に設定しなければなりません。他のフィールドは未定義と見なされます。
有効な使用方法（暗黙的）
- XrFaceTrackingDataSourceInfoANDROID を使用する前に、
XR_ANDROID_face_tracking_data_source拡張機能を有効にする必要があります。 -
typeはXR_TYPE_FACE_TRACKING_DATA_SOURCE_INFO_ANDROIDにする必要があります。 -
nextは、NULLまたは構造体チェーン内の次の構造体への有効なポインタでなければなりません。 -
requestedDataSourcesは、requestedDataSourceCount個の有効な XrFaceTrackingDataSourceANDROID 値の配列へのポインタでなければ -
requestedDataSourceCountパラメータは0より大きい値にする必要があります。
権限
Android アプリは、リクエストする権限をマニフェストに記載する必要があります。android.permission.FACE_TRACKING 権限は危険な権限と見なされます。android.permission.RECORD_AUDIO 権限は危険な権限と見なされます。アプリは、これらの機能を使用するために、実行時に権限をリクエストしなければなりません。
（保護レベル: dangerous）
XrFaceTrackingDataSourceStateANDROID 構造体は次のように記述されます。
typedef struct XrFaceTrackingDataSourceStateANDROID {
XrStructureType type;
void* next;
XrFaceTrackingDataSourceANDROID dataSource;
} XrFaceTrackingDataSourceStateANDROID;
メンバーの説明
typeは、この構造の XrStructureType です。nextは、NULLまたは構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。dataSourceは、顔追跡データの生成に使用される XrFaceTrackingDataSourceANDROID です。
アプリケーションは、xrGetFaceStateANDROID に渡された XrFaceStateANDROID 構造体に XrFaceTrackingDataSourceStateANDROID 構造体をチェーンして、その呼び出しの顔追跡データの生成に使用されたデータソースをクエリしても構いません。
有効な使用方法（暗黙的）
-
XR_ANDROID_face_tracking_data_source拡張機能は、XrFaceTrackingDataSourceStateANDROID を使用する前に有効にする必要があります。 -
typeはXR_TYPE_FACE_TRACKING_DATA_SOURCE_STATE_ANDROIDにする必要があります。 -
nextは、NULLまたは構造体チェーン内の次の構造体への有効なポインタでなければなりません。 -
dataSourceは、有効な XrFaceTrackingDataSourceANDROID 値でなければ
データソースを使用した顔追跡のサンプルコード。
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）
- 拡張機能の初期説明