Extensão OpenXR XR_ANDROID_performance_metrics

String de nome

XR_ANDROID_performance_metrics

Tipo de extensão

Extensão de instância

Número de extensão registrado

466

Data da última modificação

2024-09-06

Status do IP

Nenhuma reivindicação de IP conhecida.

Dependências de extensão e versão

OpenXR 1.0

Colaboradores

Dmitry Kotov, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Visão geral

Essa extensão oferece APIs para enumerar e consultar vários contadores de métricas de desempenho do dispositivo XR, compositor e aplicativo XR atual. Os desenvolvedores podem realizar análises de desempenho e fazer otimização direcionada no aplicativo de XR usando os contadores de métricas de desempenho coletados. O aplicativo não pode mudar o comportamento com base nas leituras do contador.

Os contadores de métricas de desempenho são organizados em valores XrPath predefinidos, no caminho raiz /perfmetrics_android. Um aplicativo pode consultar os contadores disponíveis usando xrEnumeratePerformanceMetricsCounterPathsANDROID. Confira uma lista de caminhos de contador de métricas de desempenho que podem ser fornecidos em dispositivos Android:

  • /perfmetrics_android/app/cpu_frametime (milissegundos, float) - tempo de parede gasto pelo cliente para processar um frame.
  • /perfmetrics_android/app/gpu_frametime (milissegundos, float) - tempo de parede que o cliente gastou aguardando a conclusão do trabalho da GPU por frame. Observações:
    • Um tempo de espera alto pode significar que a GPU estava ocupada com outras tarefas, não necessariamente que o cliente está fazendo muito trabalho de GPU.
    • O tempo de espera da GPU pode ser zero se a renderização já tiver sido concluída quando verificada pelo compositor.
  • /perfmetrics_android/app/cpu_utilization (porcentagem, float) é a taxa total de uso da CPU do app em média ao longo do tempo.
    • Ele pode ser maior que 100% em processadores multicore.
  • /perfmetrics_android/app/gpu_utilization (porcentagem): taxa de utilização total da GPU do app em média ao longo do tempo.
  • /perfmetrics_android/app/motion_to_photon_latency (milissegundos, float) é o tempo gasto desde o evento de movimento iniciado pelo usuário até a atualização da imagem física correspondente na tela.
  • /perfmetrics_android/compositor/cpu_frametime (milissegundos, float) - tempo de parede gasto pelo compositor para processar um frame.
  • /perfmetrics_android/compositor/gpu_frametime (milissegundos, float) - tempo de parede que o compositor gastou esperando a GPU ser concluída por frame.
  • /perfmetrics_android/compositor/dropped_frame_count (número inteiro) é o número total de frames descartados de todos os apps.
  • /perfmetrics_android/compositor/frames_per_second (float) - número de frames do compositor renderizados no dispositivo por segundo.
  • /perfmetrics_android/device/cpu_utilization_average (porcentagem, float) é a taxa de utilização da CPU do dispositivo calculada em todos os núcleos e em média ao longo do tempo.
  • /perfmetrics_android/device/cpu_utilization_worst (porcentagem, flutuante) - taxa de utilização da CPU do dispositivo do núcleo de pior desempenho em média ao longo do tempo.
  • /perfmetrics_android/device/cpu0_utilization até /perfmetrics_android/device/cpuX_utilization (porcentagem, flutuante, X é o número de núcleos de CPU menos um) - taxa de utilização da CPU do dispositivo por núcleo de CPU, em média, ao longo do tempo.
  • /perfmetrics_android/device/cpu_frequency (MHz, float) - a frequência da CPU do dispositivo é calculada em todas as cores e em média ao longo do tempo.
  • /perfmetrics_android/device/gpu_utilization (porcentagem, flutuante) — taxa de utilização da GPU do dispositivo com média ao longo do tempo.

Depois que uma sessão é criada, um aplicativo pode usar xrSetPerformanceMetricsStateANDROID para ativar o sistema de métricas de desempenho para essa sessão. Um aplicativo pode usar xrQueryPerformanceMetricsCounterANDROID para consultar um contador de métricas de desempenho em uma sessão que tenha o sistema de métricas de desempenho ativado ou usar xrGetPerformanceMetricsStateANDROID para consultar se o sistema de métricas de desempenho está ativado.

Para ativar a funcionalidade dessa extensão, o aplicativo precisa transmitir o nome da extensão para xrCreateInstance usando o parâmetro XrInstanceCreateInfo::enabledExtensionNames conforme indicado na seção Extensões.

Novos tipos de flag

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;

Novas constantes de tipo enumerado

A enumeração XrStructureType foi ampliada com:

  • XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

Novos tipos enumerados

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;

Novas estruturas

A estrutura XrPerformanceMetricsStateANDROID é definida como: 

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

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no núcleo do OpenXR ou nesta extensão.
  • enabled é definido como XR_TRUE para indicar que o sistema de métricas de performance está ativado. Caso contrário, XR_FALSE é usado ao receber o estado. Ao definir o estado, defina como XR_TRUE para ativar o sistema de métricas de desempenho e XR_FALSE para desativá-lo.

XrPerformanceMetricsStateANDROID é fornecido como entrada ao chamar xrSetPerformanceMetricsStateANDROID para ativar ou desativar o sistema de métricas de desempenho. XrPerformanceMetricsStateANDROID é preenchido como um parâmetro de saída ao chamar xrGetPerformanceMetricsStateANDROID para consultar se o sistema de métricas de desempenho está ativado.

Uso válido (implícito)

A estrutura XrPerformanceMetricsCounterANDROID é definida como: 

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

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no núcleo do OpenXR ou nesta extensão.
  • counterFlags é uma máscara de bits de XrPerformanceMetricsCounterFlagsANDROID que descreve a validade dos membros de valor.
  • counterUnit é um tipo enumerado de XrPerformanceMetricsCounterUnitANDROID que descreve a unidade de medida.
  • uintValue é o valor do contador no formato uint32_t. É válido se counterFlags contiver XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID.
  • floatValue é o valor do contador no formato float. É válido se counterFlags contiver XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID.

O XrPerformanceMetricsCounterANDROID é preenchido chamando xrQueryPerformanceMetricsCounterANDROID para consultar informações de contador de métricas de desempenho em tempo real.

Uso válido (implícito)

Novas funções

A função xrEnumeratePerformanceMetricsCounterPathsANDROID enumera todos os caminhos de contador de métricas de desempenho que têm suporte do ambiente de execução. Ela é definida como: 

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

Descrições dos parâmetros

  • instance é um identificador XrInstance criado anteriormente com xrCreateInstance.
  • counterPathCapacityInput é a capacidade da matriz counterPaths ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • O counterPathCountOutput é preenchido pelo ambiente de execução com a contagem de counterPaths gravada ou a capacidade necessária caso counterPathCapacityInput seja insuficiente.
  • counterPaths é uma matriz de XrPath preenchida pelo ambiente de execução que contém todos os contadores de métricas de performance disponíveis, mas pode ser NULL se counterPathCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho counterPaths necessário.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

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

A função xrSetPerformanceMetricsStateANDROID é definida como: 

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

Descrições dos parâmetros

A função xrSetPerformanceMetricsStateANDROID ativa ou desativa o sistema de métricas de desempenho.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

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

A função xrGetPerformanceMetricsStateANDROID é definida como: 

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

Descrições dos parâmetros

A função xrGetPerformanceMetricsStateANDROID recebe o estado atual do sistema de métricas de desempenho.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST

A função xrQueryPerformanceMetricsCounterANDROID é definida como: 

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

Descrições dos parâmetros

A função xrQueryPerformanceMetricsCounterANDROID consulta um contador de métricas de desempenho.

O aplicativo precisa ativar o sistema de métricas de desempenho chamando xrSetPerformanceMetricsStateANDROID antes de consultar as métricas usando xrQueryPerformanceMetricsCounterANDROID.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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