XR_ANDROID_face_tracking_data_source

이름 문자열

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

매개변수 설명

  • instanceXrInstance 의 핸들입니다 .
  • systemId는 얼굴 추적 데이터 소스가 열거될 XrSystemId입니다.
  • supportedDataSourcesInputCapacitysupportedDataSources 배열의 용량이거나 필요한 용량을 가져오는 요청을 나타내는 0입니다.
  • supportedDataSourcesOutputCount는 지원되는 데이터 소스의 수 또는 supportedDataSourcesInputCapacity가 부족한 경우 필요한 용량입니다.
  • supportedDataSourcesXrFaceTrackingDataSourceANDROID 배열입니다 . supportedDataSourcesInputCapacity가 0인 경우 NULL일 수 있습니다.
  • 필요한 supportedDataSources 크기 가져오기에 관한 자세한 설명은 버퍼 크기 매개변수 섹션을 참고하세요.

애플리케이션은 시스템에서 지원하는 데이터 소스 목록을 열거할 수 있습니다. xrEnumerateFaceTrackingDataSourcesANDROID 함수를 호출하여

XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTrackingXR_TRUE이면 런타임은 xrEnumerateFaceTrackingDataSourcesANDROID에서 XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID도 반환해야 합니다 .

런타임이 데이터 소스를 0개 반환하면 어떤 종류의 얼굴 추적도 지원하지 않습니다.

런타임은 최고 품질에서 최저 품질 순으로 데이터 소스를 반환해야 합니다.

유효한 사용 (암시적)

  • XR_ANDROID_face_tracking_data_source 확장 프로그램을 사용 설정해야 합니다. xrEnumerateFaceTrackingDataSourcesANDROID를 호출하기 전에
  • instance 는 유효한 XrInstance 핸들이어야 합니다.
  • supportedDataSourcesOutputCount uint32_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;

열거형의 의미는 다음과 같습니다.

enum 설명

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입니다.
  • nextNULL이거나 구조 체인의 다음 구조를 가리키는 포인터입니다. 이러한 구조는 핵심 OpenXR 또는 이 확장 프로그램에 정의되어 있지 않습니다.
  • requestedDataSourceCount는 애플리케이션에서 요청한 데이터 소스의 수입니다.
  • requestedDataSources는 애플리케이션에서 요청한 데이터 소스를 지정하는 XrFaceTrackingDataSourceANDROID 값 배열입니다.

XrFaceTrackingDataSourceInfoANDROID 구조는 XrFaceTrackerANDROID 핸들을 만드는 데이터 소스를 설명합니다.

애플리케이션은 xrCreateFaceTrackerANDROID를 호출할 때 얼굴 추적을 위한 데이터 소스를 하나 이상 요청하기 위해 XrFaceTrackerCreateInfoANDROID 구조의 다음 체인에서 XrFaceTrackingDataSourceInfoANDROID 구조를 전달할 수 있습니다 .

애플리케이션이 데이터 소스를 0개 전달하거나 데이터 소스가 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입니다.
  • nextNULL이거나 구조 체인의 다음 구조를 가리키는 포인터입니다. 이러한 구조는 핵심 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)

    • 초기 확장 프로그램 설명