API Thermal

Lançamento:

Android 11 (nível 30 da API): API Thermal

Android 12 (nível 31 da API): API NDK

(Prévia) Android 15 (DP1): getThermalHeadroomThresholds()

A performance em potencial do app é limitada pelo estado térmico do dispositivo, que pode variar de acordo com características como clima, uso recente e o design térmico do aparelho. Os dispositivos só podem manter um alto nível de por um período limitado antes de serem restringidas térmica. Um objetivo importante da implementação precisa ser atingir as metas de performance sem exceder as limitações térmicas. Com a API Thermal, isso não é necessário para otimizações específicas do dispositivo. Além disso, ao depurar o desempenho problemas, saber se o estado térmico do dispositivo está limitando o desempenho é muito importante.

Os mecanismos de jogo geralmente têm parâmetros de performance relacionados ao tempo de execução que podem ajustar o tanto de recursos do dispositivo usados pelo mecanismo. Por exemplo, esses parâmetros podem definir o número de linhas de execução de worker, afinidade entre linha de execução e worker para núcleos grandes e pequenos, opções de fidelidade de GPU e resoluções de framebuffer. No Unity Engine, os jogos os desenvolvedores podem ajustar a carga de trabalho alterando a Qualidade Configurações usando o plug-in Adaptive Performance. No Unreal Engine, use as configurações de escalonabilidade para ajustar os níveis de qualidade de maneira dinâmica.

Quando um dispositivo se aproxima de um estado térmico não seguro, o jogo pode evitar a limitação, reduzindo a carga de trabalho por esses parâmetros. Para evitar a limitação, monitore o estado térmico do dispositivo e ajuste de forma proativa a carga de trabalho do mecanismo de jogo. Depois que o dispositivo superaquece, a carga de trabalho precisa ficar abaixo do nível de performance sustentável para dissipar o calor. Depois a margem térmica diminuir para níveis mais seguros, o jogo pode aumentar configurações de qualidade novamente, mas mantenha um nível de qualidade sustentável para um melhor momento de jogo.

Para monitorar o estado térmico do dispositivo, pesquise o método getThermalHeadroom. Esse método prevê por quanto tempo o dispositivo consegue manter nível de desempenho sem superaquecimento. Se o tempo for menor que a quantidade necessária para executar a carga de trabalho, o jogo vai precisar diminuir essa carga a um nível sustentável. Por exemplo, o jogo pode mudar para núcleos menores, reduzir o frame rate ou diminuir a fidelidade.

Observação: se o jogo coleta telemetria de performance dos jogadores, o estado térmico do dispositivo é uma boa métrica a ser incluída, porque oferece mais contexto para qualquer problema relacionado.

Figura 1. Margem térmica sem monitoramento ativo da getThermalHeadroom

Figura 2. Margem térmica com monitoramento ativo de "getThermalHeadroom"

Adquirir gerente térmico

Para usar a API Thermal, você precisa primeiro adquirir o gerenciador térmico

C++

AThermalManager* thermal_manager = AThermal_acquireManager();

Java

PowerManager powerManager = (PowerManager)this.getSystemService(Context.POWER_SERVICE);

Preveja a margem térmica x segundos à frente para ter mais controle

Você pode pedir ao sistema para prever a temperatura com x segundos de antecedência com o carga de trabalho atual. Assim, você tem um controle mais detalhado e mais tempo para reagem reduzindo a carga de trabalho para impedir a limitação térmica.

O resultado varia de 0,0f (sem limitação, THERMAL_STATUS_NONE) a 1,0f (limitação pesada, THERMAL_STATUS_SEVERE). Se você tiver diferentes níveis de qualidade gráfica nos seus jogos, siga nosso Diretrizes de margem térmica.

C++

float thermal_headroom = AThermal_getThermalHeadroom(10);
ALOGI("ThermalHeadroom in 10 sec: %f", thermal_headroom);

Java

float thermalHeadroom = powerManager.getThermalHeadroom(10);
Log.d("ADPF", "ThermalHeadroom in 10 sec: " + thermalHeadroom);

Observação: se getThermalHeadroom retornar NaN, certifique-se de não chamá-lo mais de uma vez por segundo. Se ainda estiver retornando um NaN, o modelo do dispositivo poderá não ter a temperatura hardware e a API Thermal não são compatíveis.

Como alternativa, confie no status térmico para esclarecimento.

Cada modelo de dispositivo pode ser projetado de maneira diferente. Alguns dispositivos podem distribuir melhor o calor e ser capaz de suportar uma margem térmica maior antes de serem restringidas. Se você quiser ler um agrupamento simplificado de intervalos de margem térmica, verifique o status térmico para entender o valor da margem térmica no dispositivo atual.

C++

AThermalStatus thermal_status = AThermal_getCurrentThermalStatus(thermal_manager);
ALOGI("ThermalStatus is: %d", thermal_status);

Java

int thermalStatus = powerManager.getCurrentThermalStatus();
Log.d("ADPF", "ThermalStatus is: " + thermalStatus);

Observação: o mesmo valor de thermalHeadroom pode ser mapeado para uma determinada thermalStatus em um modelo de dispositivo, mas com um thermalStatus diferente em outro. Isso é esperado devido a diferenças no design do dispositivo, características térmicas perfil de desempenho.

Observação: alguns dispositivos podem ainda não ser totalmente compatíveis com essa tecnologia e THERMAL_STATUS_NONE, independente do valor real da margem térmica e estado de limitação. Por isso, recomendamos usar getThermalHeadroom como alternativa. Acesse Limitações de dispositivo da API Thermal para uma solução para essa situação.

Receber notificações quando o status térmico mudar

Você também pode evitar pesquisar o thermalHeadroom até que thermalStatus chegue um determinado nível (por exemplo: THERMAL_STATUS_LIGHT). Para isso, você pode registrar um retorno de chamada para permitir que o sistema notifique você sempre que o foi alterado.

Observação: confira as limitações de dispositivo da API Thermal. e não dependa apenas de GetCurrentThermalStatus() sem validar com GetThermalHeadroom()

C++

int result = AThermal_registerThermalStatusListener(thermal_manager, callback);
if ( result != 0 ) {
  // failed, check whether you have previously registered callback that
  // hasn’t been unregistered
}

Java

// PowerManager.OnThermalStatusChangedListener is an interface, thus you can
// also define a class that implements the methods
PowerManager.OnThermalStatusChangedListener listener = new
  PowerManager.OnThermalStatusChangedListener() {
    @Override
    public void onThermalStatusChanged(int status) {
        Log.d("ADPF", "ThermalStatus changed: " + status);
        // check the status and flip the flag to start/stop pooling when
        // applicable
    }
};
powerManager.addThermalStatusListener(listener);

Lembre-se de remover o listener quando terminar

C++

int result = AThermal_unregisterThermalStatusListener(thermal_manager, callback);
if ( result != 0 ) {
  // failed, check whether the callback has been registered previously
}

Java

powerManager.removeThermalStatusListener(listener);

Limpeza

Quando terminar, você vai precisar limpar o termal_manager adquirido. Se você estiver usando Java, a referência do PowerManager poderá ser descartada automaticamente coletados para você. Mas, se você estiver usando a API Java pelo JNI e tiver manteve uma referência, lembre-se de limpar a referência.

C++

AThermal_releaseManager(thermal_manager);

Para ver um guia completo sobre como implementar a API Thermal em um jogo em C++ nativo usando a API C++ (API NDK) e a API Java (pela JNI), confira a página Integrar Seção da API Thermal no codelab sobre adaptabilidade. nesta seção.

Diretrizes de margem térmica

Para monitorar o estado térmico do dispositivo, pesquise o método getThermalHeadroom. Esse método prevê por quanto tempo o dispositivo consegue manter nível de performance antes de alcançar THERMAL_STATUS_SEVERE. Por exemplo, se getThermalHeadroom(30) retornar 0,8, isso indica que em 30 segundos, espera-se que a margem atinja 0,8, com uma distância de 0,2 de uma limitação grave, ou seja, 1,0. Se o tempo for menor que o tempo necessário para executar a carga de trabalho, então seu jogo deve diminuir a carga de trabalho para um nível Por exemplo, o jogo pode reduzir o frame rate, a fidelidade menor ou e reduzir o trabalho de conectividade de rede.

Status e significado térmico

• Se o dispositivo não estiver sendo limitado térmico:
  • THERMAL_STATUS_NONE
• Pouco limitação, mas sem impacto significativo no desempenho:
  • THERMAL_STATUS_LIGHT
  • THERMAL_STATUS_MODERATE
• Limitação significativa que afeta o desempenho:
  • THERMAL_STATUS_SEVERE
  • THERMAL_STATUS_CRITICAL
  • THERMAL_STATUS_EMERGENCY
  • THERMAL_STATUS_SHUTDOWN

Limitações de dispositivo da API Thermal

Há algumas limitações conhecidas ou requisitos adicionais da API Thermal, devido a implementações da API Thermal em dispositivos mais antigos. As limitações e como e contorná-los são os seguintes:

• Não chame a API GetThermalHeadroom() com muita frequência. Ao fazer isso, fará com que a API retorne um NaN. Você deve chamá-lo no máximo uma vez por segundo.
• Se o valor inicial de GetThermalHeadroom() for NaN, a API não será disponível no dispositivo
• Se GetThermalHeadroom() retornar um valor alto (por exemplo: 0,85 ou mais) e GetCurrentThermalStatus() ainda retorna THERMAL_STATUS_NONE, o status é provavelmente não foi atualizada. Usar heurística para estimar a limitação térmica correta ou apenas usar getThermalHeadroom() sem getCurrentThermalStatus().

Exemplo de heurística:

1. Verifique se há suporte para a API Thermal. isAPISupported() verifica o valor de a primeira chamada para getThermalHeadroom para garantir que não seja 0 ou NaN pula usando a API se o primeiro valor for 0 ou NaN.
2. Se getCurrentThermalStatus() retornar um valor diferente de THERMAL_STATUS_NONE, o dispositivo está sendo limitado térmico.
3. Se getCurrentThermalStatus() continuar retornando THERMAL_STATUS_NONE, ele não significa necessariamente que o dispositivo não esteja sendo limitado térmico. Poderia significa que getCurrentThermalStatus() não é compatível com o dispositivo. Verifique o valor de retorno de getThermalHeadroom() para garantir a condição de o dispositivo.
4. Se getThermalHeadroom() retornar um valor > 1.0, o status poderia ser de THERMAL_STATUS_SEVERE ou mais, reduza a carga de trabalho imediatamente manter a carga de trabalho menor até que getThermalHeadroom() retorne um valor menor
5. Se getThermalHeadroom() retornar um valor de 0,95, o status poderá ser de THERMAL_STATUS_MODERATE ou mais, reduza a carga de trabalho imediatamente e fique atento para evitar leituras mais altas
6. Se getThermalHeadroom() retornar um valor de 0,85, o status poderá ser THERMAL_STATUS_LIGHT, mantenha a observação e reduza a carga de trabalho Se possível,

Pseudocódigo:

  bool isAPISupported() {
    float first_value_of_thermal_headroom = getThermalHeadroom();
    if ( first_value_of_thermal_headroom == 0 ||
      first_value_of_thermal_headroom == NaN ) {
        // Checked the thermal Headroom API's initial return value
        // it is NaN or 0，so, return false (not supported)
        return false;
    }
    return true;
  }
  
  if (!isAPISupported()) {
    // Checked the thermal Headroom API's initial return value, it is NaN or 0
    // Don’t use the API
  } else {
      // Use thermalStatus API to check if it returns valid values.
      if (getCurrentThermalStatus() > THERMAL_STATUS_NONE) {
          // The device IS being thermally throttled
      } else {
      // The device is not being thermally throttled currently. However, it
      // could also be an indicator that the ThermalStatus API may not be
      // supported in the device.
      // Currently this API uses predefined threshold values for thermal status
      // mapping. In the future  you may be able to query this directly.
      float thermal_headroom = getThermalHeadroom();
      if ( thermal_headroom > 1.0) {
            // The device COULD be severely throttled.
      } else  if ( thermal_headroom > 0.95) {
            // The device COULD be moderately throttled.
      } else if ( thermal_headroom > 0.85) {
            // The device COULD be experiencing light throttling.
      }
    }
  }

Diagrama:

Figura 3. Exemplo de heurística para determinar o suporte à API Thermal em dispositivos mais antigos.