XR_ANDROID_face_tracking_data_source

Cadena de nombre

XR_ANDROID_face_tracking_data_source

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

707

Revisión

1

Estado de ratificación

No se ratificó

Dependencias de extensiones y versiones

XR_ANDROID_face_tracking

Fecha de la última modificación

2025-12-16

Estado de la IP

No hay reclamos conocidos por IP.

Colaboradores

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

Descripción general

Esta extensión permite que las aplicaciones obtengan datos de seguimiento facial de varias fuentes de datos.

Consulta fuentes de datos compatibles

Las aplicaciones deben llamar a xrEnumerateFaceTrackingDataSourcesANDROID para obtener la lista de fuentes de datos de seguimiento facial compatibles.

La función xrEnumerateFaceTrackingDataSourcesANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

  • instance es un identificador para un XrInstance .
  • systemId es el XrSystemId para el que se enumerarán las fuentes de datos de seguimiento facial.
  • supportedDataSourcesInputCapacity es la capacidad del array supportedDataSources o 0 para indicar una solicitud para recuperar la capacidad requerida.
  • supportedDataSourcesOutputCount es la cantidad de fuentes de datos admitidas o la capacidad requerida en caso de que supportedDataSourcesInputCapacity sea insuficiente.
  • supportedDataSources es un array de XrFaceTrackingDataSourceANDROID . Puede ser NULL si supportedDataSourcesInputCapacity es 0.
  • Consulta la sección Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño de supportedDataSources requerido.

La aplicación puede enumerar la lista de fuentes de datos compatibles con el sistema llamando a la función xrEnumerateFaceTrackingDataSourcesANDROID.

Si XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking es XR_TRUE, el tiempo de ejecución también debe devolver XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID de xrEnumerateFaceTrackingDataSourcesANDROID .

Si el tiempo de ejecución devuelve cero fuentes de datos, significa que no admite ningún tipo de seguimiento facial.

El tiempo de ejecución debe devolver las fuentes de datos en orden de calidad, de la más alta a la más baja.

Uso válido (implícito)

  • La extensión XR_ANDROID_face_tracking_data_source debe habilitarse antes de llamar a xrEnumerateFaceTrackingDataSourcesANDROID.
  • instance debe ser un identificador de XrInstance válido
  • supportedDataSourcesOutputCount debe ser un puntero a un valor uint32_t.
  • Si supportedDataSourcesInputCapacity no es 0 , supportedDataSources debe ser un puntero a un array de valores supportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID.

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • 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

La enumeración XrFaceTrackingDataSourceANDROID identifica las diferentes fuentes de datos que un tiempo de ejecución puede admitir.

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;

Los valores de enumeración tienen los siguientes significados:

Descripción de la enumeración

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

Indica que esta configuración usa datos de imágenes.

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

Indica que esta configuración usa datos de audio.

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

Indica que esta configuración usa datos de audio y de imágenes.

Configura fuentes de datos

La estructura XrFaceTrackingDataSourceInfoANDROID se describe de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • requestedDataSourceCount es la cantidad de fuentes de datos que solicitó la aplicación.
  • requestedDataSources es un array de valores de XrFaceTrackingDataSourceANDROID que especifica las fuentes de datos que solicitó la aplicación.

La estructura XrFaceTrackingDataSourceInfoANDROID describe las fuentes de datos para crear un identificador de XrFaceTrackerANDROID.

Una aplicación puede pasar una estructura XrFaceTrackingDataSourceInfoANDROID en la siguiente cadena de una estructura XrFaceTrackerCreateInfoANDROID para solicitar una o más fuentes de datos para el seguimiento facial cuando se llama a xrCreateFaceTrackerANDROID .

Si la aplicación pasa cero fuentes de datos o si xrEnumerateFaceTrackingDataSourcesANDROID no enumeró ninguna de las fuentes de datos, el tiempo de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .

Si el usuario no otorgó todos los permisos necesarios para todas las fuentes de datos solicitadas, el tiempo de ejecución debe devolver XR_ERROR_PERMISSION_INSUFFICIENT .

Los permisos necesarios para cada fuente de datos se definen de la siguiente manera:

  • XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID requiere el permiso android.permission.FACE_TRACKING.
  • XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID requiere el permiso android.permission.RECORD_AUDIO.
  • XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID requiere los permisos android.permission.FACE_TRACKING y android.permission.RECORD_AUDIO.

El tiempo de ejecución debe interpretar el array XrFaceTrackingDataSourceInfoANDROID : requestedDataSources como la preferencia más alta a la más baja por parte de la aplicación. El tiempo de ejecución debe generar datos de seguimiento con la primera fuente de datos solicitada que aún cumpla con los permisos requeridos. Si se revoca un permiso durante la vida útil del objeto de seguimiento, lo que provoca que una fuente de datos deje de ser utilizable, el tiempo de ejecución debe seguir intentando usar la siguiente fuente de datos con mayor preferencia. Si no se puede usar ninguna de las fuentes de datos solicitadas, el tiempo de ejecución debe establecer XrFaceStateANDROID :: isValid en XR_FALSE en las llamadas a xrGetFaceStateANDROID, y otros campos se consideran indefinidos.

Uso válido (implícito)

Permisos

Las aplicaciones para Android deben tener los permisos que pretenden solicitar enumerados en su manifiesto. El permiso android.permission.FACE_TRACKING se considera un permiso peligroso. El permiso android.permission.RECORD_AUDIO se considera un permiso peligroso. La aplicación debe solicitar los permisos durante el tiempo de ejecución para usar estas funciones:

(nivel de protección: peligroso)

La estructura XrFaceTrackingDataSourceStateANDROID se describe de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • dataSource es el XrFaceTrackingDataSourceANDROID que se usa para generar los datos de seguimiento facial.

Una aplicación puede encadenar una estructura XrFaceTrackingDataSourceStateANDROID a una estructura XrFaceStateANDROID que se pasa a xrGetFaceStateANDROID para consultar la fuente de datos que se usó para producir los datos de seguimiento facial de esa llamada.

Uso válido (implícito)

Código de ejemplo para el seguimiento facial con fuente de datos.

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

Problemas

Historial de versiones

  • Revisión 1, 2024-10-07 (Kenny Vercaemer)

    • Descripción inicial de la extensión