API Thermal

Lançamento:

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

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

(Pré-lançamento) 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 performance por um período limitado antes de serem limitados termicamente. Um objetivo importante da implementação precisa ser atingir as metas de performance sem exceder as limitações térmicas. A API Thermal permite isso sem a necessidade de otimizações específicas do dispositivo. Além disso, ao depurar problemas de performance, é importante saber se o estado térmico do dispositivo está limitando a performance.

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 desenvolvedores de jogos podem ajustar a carga de trabalho mudando as Configurações de qualidade usando o plug-in de desempenho adaptável. No Unreal Engine, use as Configurações de escalonamento para ajustar os níveis de qualidade dinamicamente.

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 que o headroom térmico diminui para níveis mais seguros, o jogo pode aumentar as configurações de qualidade novamente, mas é importante encontrar um nível de qualidade sustentável para um tempo de jogo ideal.

Para monitorar o estado térmico do dispositivo, pesquise o método getThermalHeadroom. Esse método prevê por quanto tempo o dispositivo pode manter o nível de performance atual 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 monitorar ativamente o getThermalHeadroom

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

Adquirir o Thermal Manager

Para usar a API Thermal, primeiro você precisa adquirir o Thermal Manager.

C++

AThermalManager* thermal_manager = AThermal_acquireManager();

Java

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

Prever o headroom térmico x segundos à frente para ter mais controle

Você pode pedir ao sistema para prever a temperatura x segundos à frente com a carga de trabalho atual. Isso oferece um controle mais refinado e mais tempo para reagir, reduzindo a carga de trabalho para evitar que o estrangulamento térmico seja acionado.

O resultado varia de 0,0f (sem limitação, THERMAL_STATUS_NONE) a 1,0f (limitação alta, THERMAL_STATUS_SEVERE). Se você tiver diferentes níveis de qualidade gráfica nos jogos, siga nossas 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, verifique se você não está chamando mais de uma vez a cada 10 segundos. Se ele ainda retornar NaN, o modelo do dispositivo pode não ter o hardware térmico e a API Thermal não terá suporte.

Como alternativa, use o status térmico para esclarecimento

Cada modelo de dispositivo pode ser projetado de maneira diferente. Alguns dispositivos podem distribuir o calor melhor e, portanto, suportar uma margem térmica maior antes de serem limitados. 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 um determinado thermalStatus em um modelo de dispositivo, mas para um thermalStatus diferente em outro dispositivo. Isso é esperado devido a diferenças no design do dispositivo, nas características térmicas e no perfil de desempenho.

Observação: alguns dispositivos ainda não oferecem suporte total a essa tecnologia e retornam THERMAL_STATUS_NONE, independentemente do valor real do headroom térmico e do estado de limitação. Por isso, recomendamos o uso de getThermalHeadroom. Confira as limitações de dispositivo da API Thermal para encontrar uma solução para essa situação.

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

Também é possível evitar a pesquisa da thermalHeadroom até que a thermalStatus atinja um determinado nível (por exemplo, THERMAL_STATUS_LIGHT). Para isso, registre um callback para que o sistema notifique você sempre que o status mudar.

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

Não se esqueça 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 thermal_manager que adquiriu. Se você estiver usando Java, a referência do PowerManager poderá ser coletada automaticamente. No entanto, se você estiver usando a API Java pelo JNI e tiver retido uma referência, lembre-se de limpá-la.

C++

AThermal_releaseManager(thermal_manager);

Para um guia completo sobre como implementar a API Thermal em um jogo C++ nativo usando a API C++ (API NDK) e a API Java (por meio do JNI), consulte a seção Integrar a API Thermal no codelab de adaptabilidade.

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 pode manter o nível de performance atual antes de atingir THERMAL_STATUS_SEVERE. Por exemplo, se getThermalHeadroom(30) retornar 0,8, isso indica que em 30 segundos, o headroom deve chegar a 0,8, com uma distância de 0,2 do estrangulamento severo, ou 1,0. 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 reduzir a frame rate, diminuir a fidelidade ou reduzir o trabalho de conectividade de rede.

Status térmicos e significado

• Se o dispositivo não estiver sob limitação térmica:
  • THERMAL_STATUS_NONE
• Alguma limitação, mas sem impacto significativo na performance:
  • THERMAL_STATUS_LIGHT
  • THERMAL_STATUS_MODERATE
• Limitação significativa que afeta a performance:
  • 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 às implementações da API Thermal em dispositivos mais antigos. As limitações e como contornar são as seguintes:

• Não chame a API GetThermalHeadroom() com muita frequência. Se você fizer isso, a API vai retornar NaN. Não chame mais de uma vez a cada 10 segundos.
• Evite chamar de várias linhas de execução. É mais difícil garantir a frequência de chamadas, e isso pode fazer com que a API retorne NaN.
• Se o valor inicial de GetThermalHeadroom() for NaN, a API não estará disponível no dispositivo.
• Se GetThermalHeadroom() retornar um valor alto (por exemplo, 0,85 ou mais) e GetCurrentThermalStatus() ainda retornar THERMAL_STATUS_NONE, é provável que o status não tenha sido atualizado. Use heurísticas para estimar o status correto de limitação térmica ou use apenas getThermalHeadroom() sem getCurrentThermalStatus().

Exemplo de heurísticas:

1. Verifique se a API Thermal tem suporte. isAPISupported() verifica o valor da primeira chamada para getThermalHeadroom para garantir que ele não seja 0 ou NaN e pula o uso da API se o primeiro valor for 0 ou NaN.
2. Se getCurrentThermalStatus() retornar um valor diferente de THERMAL_STATUS_NONE, o dispositivo estará sendo limitado termicamente.
3. Se getCurrentThermalStatus() continuar retornando THERMAL_STATUS_NONE, isso não significa necessariamente que o dispositivo não está sendo limitado termicamente. Isso pode significar que o getCurrentThermalStatus() não tem suporte para o dispositivo. Verifique o valor de retorno de getThermalHeadroom() para garantir a condição do dispositivo.
4. Se getThermalHeadroom() retornar um valor de > 1,0, o status poderá ser THERMAL_STATUS_SEVERE ou maior, reduzir a carga de trabalho imediatamente e manter a carga de trabalho mais baixa até que getThermalHeadroom() retorne um valor menor.
5. Se getThermalHeadroom() retornar um valor de 0, 95, o status poderá ser THERMAL_STATUS_MODERATE ou maior. Reduza a carga de trabalho imediatamente e mantenha a observação para evitar leituras mais altas.
6. Se getThermalHeadroom() retornar um valor de 0, 85, o status poderá ser THERMAL_STATUS_LIGHT. Fique atento 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 da API Thermal em dispositivos mais antigos