Extensión OpenXR XR_ANDROID_performance_metrics

Cadena de nombre

XR_ANDROID_performance_metrics

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

466

Fecha de última modificación

2024-09-06

Estado de la IP

No hay reclamos de IP conocidos.

Dependencias de extensiones y versiones

OpenXR 1.0

Colaboradores

Dmitry Kotov, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Descripción general

Esta extensión proporciona APIs para enumerar y consultar varios contadores de métricas de rendimiento del dispositivo XR, el compositor y la aplicación XR actuales. Los desarrolladores pueden realizar un análisis de rendimiento y realizar una optimización segmentada de la aplicación de XR con los contadores de métricas de rendimiento que se recopilan. La aplicación no debe cambiar su comportamiento en función de las lecturas del contador.

Los contadores de métricas de rendimiento se organizan en valores predefinidos de XrPath, en la ruta de acceso raíz /perfmetrics_android. Una aplicación puede consultar los contadores disponibles a través de xrEnumeratePerformanceMetricsCounterPathsANDROID. Esta es una lista de las rutas de acceso de los contadores de métricas de rendimiento que pueden proporcionarse en dispositivos Android:

• /perfmetrics_android/app/cpu_frametime (milisegundos, número de punto flotante): Es el tiempo real que el cliente dedicó a procesar un fotograma.
• /perfmetrics_android/app/gpu_frametime (milisegundos, número de punto flotante): Es el tiempo real que el cliente pasó esperando que se completara el trabajo de la GPU por fotograma. Notas:
  • Un tiempo de espera alto puede significar que la GPU estaba ocupada con otras tareas, no que este cliente esté realizando demasiado trabajo en la GPU.
  • El tiempo de espera de la GPU puede ser cero si la renderización ya se completó cuando el compositor la verificó.
• /perfmetrics_android/app/cpu_utilization (porcentaje, número de punto flotante): Es la tasa total de uso de CPU de la app promediada en el tiempo.
  • Puede ser superior al 100% en procesadores multinúcleo.
• /perfmetrics_android/app/gpu_utilization (porcentaje): Es la tasa de utilización total de la GPU de la app promediada en el tiempo.
• /perfmetrics_android/app/motion_to_photon_latency (milisegundos, número de punto flotante): Es el tiempo transcurrido desde el evento de movimiento iniciado por el usuario hasta la actualización de la imagen física correspondiente en la pantalla.
• /perfmetrics_android/compositor/cpu_frametime (milisegundos, número de punto flotante): Es el tiempo real que el compositor dedicó a procesar un fotograma.
• /perfmetrics_android/compositor/gpu_frametime (milisegundos, número de punto flotante): Es el tiempo real que el compositor pasó esperando que se completara el trabajo de la GPU por fotograma.
• /perfmetrics_android/compositor/dropped_frame_count (número entero): Es la cantidad total de fotogramas perdidos de todas las apps.
• /perfmetrics_android/compositor/frames_per_second (número de punto flotante): Es la cantidad de fotogramas del compositor que se dibujan en el dispositivo por segundo.
• /perfmetrics_android/device/cpu_utilization_average (porcentaje, número de punto flotante): Es la tasa de uso de CPU del dispositivo promediada en todos los núcleos y en el tiempo.
• /perfmetrics_android/device/cpu_utilization_worst (porcentaje, número de punto flotante): Es la tasa de uso de CPU del dispositivo del núcleo con el peor rendimiento promediado en el tiempo.
• /perfmetrics_android/device/cpu0_utilization a /perfmetrics_android/device/cpuX_utilization (porcentaje, número de punto flotante, X es la cantidad de núcleos de CPU menos uno): Es la tasa de utilización de la CPU del dispositivo por núcleo de CPU promediada en el tiempo.
• /perfmetrics_android/device/cpu_frequency (MHz, número de punto flotante): Es la frecuencia de la CPU del dispositivo promediada en todos los núcleos y en el tiempo.
• /perfmetrics_android/device/gpu_utilization (porcentaje, número de punto flotante): Es la tasa de utilización de la GPU del dispositivo promediada en el tiempo.

Después de crear una sesión, una aplicación puede usar xrSetPerformanceMetricsStateANDROID para habilitar el sistema de métricas de rendimiento de esa sesión. Una aplicación puede usar xrQueryPerformanceMetricsCounterANDROID para consultar un contador de métricas de rendimiento en una sesión que tiene habilitado el sistema de métricas de rendimiento, o bien usar xrGetPerformanceMetricsStateANDROID para consultar si el sistema de métricas de rendimiento está habilitado.

Para habilitar la funcionalidad de esta extensión, la aplicación debe pasar el nombre de la extensión a xrCreateInstance con el parámetro XrInstanceCreateInfo::enabledExtensionNames, como se indica en la sección Extensiones.

Nuevos tipos de marcas

typedef XrFlags64 XrPerformanceMetricsCounterFlagsANDROID;

// Flag bits for XrPerformanceMetricsCounterFlagsANDROID
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_ANY_VALUE_VALID_BIT_ANDROID = 0x00000001;
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID = 0x00000002;
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID = 0x00000004;

Nuevas constantes de enum

La enumeración XrStructureType se extiende con lo siguiente:

• XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
• XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

Nuevas enumeraciones

typedef enum XrPerformanceMetricsCounterUnitANDROID {
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_GENERIC_ANDROID = 0,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_PERCENTAGE_ANDROID = 1,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_MILLISECONDS_ANDROID = 2,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_BYTES_ANDROID = 3,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_HERTZ_ANDROID = 4
} XrPerformanceMetricsCounterUnitANDROID;

Nuevas estructuras

La estructura XrPerformanceMetricsStateANDROID se define de la siguiente manera:

typedef struct XrPerformanceMetricsStateANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           enabled;
} XrPerformanceMetricsStateANDROID;

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.
• enabled se establece en XR_TRUE para indicar que el sistema de métricas de rendimiento está habilitado, XR_FALSE de lo contrario, cuando se obtiene el estado. Cuando configures el estado, configúralo en XR_TRUE para habilitar el sistema de métricas de rendimiento y en XR_FALSE para inhabilitarlo.

XrPerformanceMetricsStateANDROID se proporciona como entrada cuando se llama a xrSetPerformanceMetricsStateANDROID para habilitar o inhabilitar el sistema de métricas de rendimiento. XrPerformanceMetricsStateANDROID se propaga como un parámetro de salida cuando se llama a xrGetPerformanceMetricsStateANDROID para consultar si el sistema de métricas de rendimiento está habilitado.

Uso válido (implícito)

• La extensión XR_ANDROID_performance_metrics debe estar habilitada antes de usar XrPerformanceMetricsStateANDROID.
• type debe ser XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID.
• next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructuras.

La estructura XrPerformanceMetricsCounterANDROID se define de la siguiente manera:

typedef struct XrPerformanceMetricsCounterANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrPerformanceMetricsCounterFlagsANDROID    counterFlags;
    XrPerformanceMetricsCounterUnitANDROID     counterUnit;
    uint32_t                                   uintValue;
    float                                      floatValue;
} XrPerformanceMetricsCounterANDROID;

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.
• counterFlags es una máscara de bits de XrPerformanceMetricsCounterFlagsANDROID que describe la validez de los miembros de valor.
• counterUnit es una enumeración de XrPerformanceMetricsCounterUnitANDROID que describe la unidad de medida.
• uintValue es el valor del contador en formato uint32_t. Es válido si counterFlags contiene XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID.
• floatValue es el valor del contador en formato float. Es válido si counterFlags contiene XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID.

Para propagar XrPerformanceMetricsCounterANDROID, se llama a xrQueryPerformanceMetricsCounterANDROID para consultar la información del contador de métricas de rendimiento en tiempo real.

Uso válido (implícito)

• La extensión XR_ANDROID_performance_metrics debe estar habilitada antes de usar XrPerformanceMetricsCounterANDROID.
• type debe ser XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID.
• next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructuras.
• counterFlags debe ser 0 o una combinación válida de valores de XrPerformanceMetricsCounterFlagsANDROID.
• counterUnit debe ser un valor válido de XrPerformanceMetricsCounterUnitANDROID.

Funciones nuevas

La función xrEnumeratePerformanceMetricsCounterPathsANDROID enumera todas las instrucciones de contador de métricas de rendimiento que admite el entorno de ejecución y se define de la siguiente manera:

XrResult xrEnumeratePerformanceMetricsCounterPathsANDROID(
    XrInstance                                  instance,
    uint32_t                                    counterPathCapacityInput,
    uint32_t*                                   counterPathCountOutput,
    XrPath*                                     counterPaths);

Descripciones de los parámetros

• instance es un control XrInstance creado anteriormente con xrCreateInstance.
• counterPathCapacityInput es la capacidad del array counterPaths o 0 para indicar una solicitud para recuperar la capacidad requerida.
• El entorno de ejecución completa counterPathCountOutput con el recuento de counterPaths escrito o la capacidad requerida en caso de que counterPathCapacityInput sea insuficiente.
• counterPaths es un array de XrPath que completa el tiempo de ejecución y que contiene todos los contadores de métricas de rendimiento disponibles, pero puede ser NULL si counterPathCapacityInput 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 counterPaths requerido.

Uso válido (implícito)

• La extensión XR_ANDROID_performance_metrics debe estar habilitada antes de llamar a xrEnumeratePerformanceMetricsCounterPathsANDROID.
• instance debe ser un identificador XrInstance válido.
• counterPathCountOutput debe ser un puntero a un valor uint32_t.
• Si counterPathCapacityInput no es 0, counterPaths debe ser un puntero a un array de counterPathCapacityInput valores XrPath.

Códigos de retorno

Correcto

• XR_SUCCESS

Error

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SIZE_INSUFFICIENT

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

XrResult xrSetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    const XrPerformanceMetricsStateANDROID*     state);

Descripciones de los parámetros

• session es un control XrSession creado anteriormente con xrCreateSession.
• state es un puntero a una estructura XrPerformanceMetricsStateANDROID.

La función xrSetPerformanceMetricsStateANDROID habilita o inhabilita el sistema de métricas de rendimiento.

Uso válido (implícito)

• La extensión XR_ANDROID_performance_metrics debe estar habilitada antes de llamar a xrSetPerformanceMetricsStateANDROID.
• session debe ser un identificador XrSession válido.
• state debe ser un puntero a una estructura XrPerformanceMetricsStateANDROID válida.

Códigos de retorno

Correcto

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Error

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST

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

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

Descripciones de los parámetros

• session es un control XrSession creado anteriormente con xrCreateSession.
• state es un puntero a una estructura XrPerformanceMetricsStateANDROID.

La función xrGetPerformanceMetricsStateANDROID obtiene el estado actual del sistema de métricas de rendimiento.

Uso válido (implícito)

• La extensión XR_ANDROID_performance_metrics debe estar habilitada antes de llamar a xrGetPerformanceMetricsStateANDROID.
• session debe ser un identificador XrSession válido.
• state debe ser un puntero a una estructura XrPerformanceMetricsStateANDROID.

Códigos de retorno

Correcto

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Error

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST

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

XrResult xrQueryPerformanceMetricsCounterANDROID(
    XrSession                                   session,
    XrPath                                      counterPath,
    XrPerformanceMetricsCounterANDROID*         counter);

Descripciones de los parámetros

• session es un control XrSession creado anteriormente con xrCreateSession.
• counterPath es una ruta de acceso válida del contador de métricas de rendimiento.
• counter es un puntero a una estructura XrPerformanceMetricsCounterANDROID.

La función xrQueryPerformanceMetricsCounterANDROID consulta un contador de métricas de rendimiento.

La aplicación debe habilitar el sistema de métricas de rendimiento llamando a xrSetPerformanceMetricsStateANDROID antes de consultar las métricas con xrQueryPerformanceMetricsCounterANDROID.

Uso válido (implícito)

• La extensión XR_ANDROID_performance_metrics debe estar habilitada antes de llamar a xrQueryPerformanceMetricsCounterANDROID.
• session debe ser un identificador XrSession válido.
• counter debe ser un puntero a una estructura XrPerformanceMetricsCounterANDROID.

Códigos de retorno

Correcto

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Error

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_PATH_UNSUPPORTED
• XR_ERROR_PATH_INVALID