API térmica

Lanzado:

Android 11 (nivel de API 30): API de Thermal

Android 12 (nivel de API 31): API del NDK

(Versión preliminar) Android 15 (DP1) - getThermalHeadroomThresholds()

El rendimiento potencial de tu app está limitado por el estado térmico del dispositivo, que puede variar según las características, como el clima, el uso reciente y el diseño térmico del dispositivo. Los dispositivos solo pueden mantener un nivel alto de rendimiento durante un tiempo limitado antes de que se los limite térmicamente. Un objetivo clave de la implementación debe ser alcanzar los objetivos de rendimiento sin exceder las limitaciones térmicas. La API de Thermal lo hace posible sin necesidad de optimizaciones específicas del dispositivo. Además, cuando depuras problemas de rendimiento, es importante saber si el estado térmico de tu dispositivo limita el rendimiento.

Por lo general, los motores de juegos tienen parámetros de rendimiento del entorno de ejecución que pueden ajustar la carga de trabajo que el motor coloca en el dispositivo. Por ejemplo, estos parámetros pueden establecer la cantidad de subprocesos de trabajo, afinidad de subprocesos de trabajo para núcleos grandes y pequeños, opciones de fidelidad de GPU y resoluciones de búfer de fotogramas. En Unity Engine, los desarrolladores de juegos pueden ajustar la carga de trabajo cambiando la configuración de calidad con el complemento de Adaptive Performance. En el caso de Unreal Engine, usa la configuración de escalabilidad para ajustar los niveles de calidad de forma dinámica.

Cuando un dispositivo se acerca a un estado térmico inseguro, el juego puede evitar ser limitado al disminuir la carga de trabajo a través de estos parámetros. Para evitar la limitación, se debe supervisar el estado térmico del dispositivo y ajustar la carga de trabajo del motor de juego de forma proactiva.

Una vez que el dispositivo se sobrecalienta, la carga de trabajo debe caer por debajo del nivel de rendimiento sostenible para disipar el calor. Después de que el margen térmico disminuya a niveles más seguros, el juego puede volver a aumentar la configuración de calidad, pero asegúrate de encontrar un nivel de calidad sostenible para un tiempo de juego óptimo.

Puedes supervisar el estado térmico del dispositivo sondeando el método getThermalHeadroom. Este método predice cuánto tiempo el dispositivo puede mantener el nivel de rendimiento actual sin sobrecalentarse. Si el tiempo es menor que la cantidad necesaria para ejecutar la carga de trabajo, el juego debe disminuirla a un nivel sostenible. Por ejemplo, el juego puede cambiar a núcleos más pequeños, reducir la velocidad de fotogramas o reducir la fidelidad.

Adquiere Thermal Manager

Para usar la API de Thermal, primero debes adquirir el Thermal Manager.

AThermalManager* thermal_manager = AThermal_acquireManager();

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

Prevé el margen térmico con X segundos de anticipación para tener más control

Puedes pedirle al sistema que pronostique la temperatura dentro de X segundos con la carga de trabajo actual. Esto te brinda un control más detallado y más tiempo para reaccionar, ya que reduce la carga de trabajo para evitar que se active la regulación térmica.

El resultado varía de 0.0f (sin limitación, THERMAL_STATUS_NONE)

a 1.0f (limitación intensa, THERMAL_STATUS_SEVERE). Si tienes diferentes niveles de calidad de gráficos en tus juegos, puedes seguir nuestros Lineamientos de margen térmico.

float thermal_headroom = AThermal_getThermalHeadroom(0);
ALOGI("ThermalHeadroom: %f", thermal_headroom);

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

Como alternativa, puedes usar el estado térmico para obtener más información.

Cada modelo de dispositivo puede diseñarse de manera diferente. Es posible que algunos dispositivos puedan distribuir mejor el calor y, por lo tanto, puedan soportar una mayor capacidad térmica antes de que se los limite. Si deseas leer una agrupación simplificada de los rangos de margen térmico, puedes consultar el estado térmico para comprender el valor del margen térmico en el dispositivo actual.

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

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

Recibe notificaciones cuando cambie el estado térmico

También puedes evitar sondear el thermalHeadroom hasta que el thermalStatus alcance un cierto nivel (por ejemplo, THERMAL_STATUS_LIGHT). Para ello, puedes registrar una devolución de llamada para que el sistema te notifique cada vez que cambie el estado.

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

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

Recuerda quitar el objeto de escucha cuando termines

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

powerManager.removeThermalStatusListener(listener);

Limpieza

Cuando termines, deberás limpiar el thermal_manager que adquiriste. Si usas Java, la referencia de PowerManager se puede recopilar automáticamente como basura. Sin embargo, si usas la API de Java a través de JNI y conservaste una referencia, recuerda limpiarla.

AThermal_releaseManager(thermal_manager);

Para obtener una guía completa sobre cómo implementar la API de Thermal en un juego nativo de C++ con la API de C++ (API del NDK) y la API de Java (a través de JNI), consulta la sección Integrate Thermal API en la sección Adaptability codelab.

Lineamientos sobre el margen térmico

Puedes supervisar el estado térmico del dispositivo mediante un sondeo del método getThermalHeadroom. Este método predice cuánto tiempo el dispositivo puede mantener el nivel de rendimiento actual antes de alcanzar THERMAL_STATUS_SEVERE. Por ejemplo, si getThermalHeadroom(30) devuelve 0.8, indica que, en 30 segundos, se espera que el margen alcance 0.8, donde hay una distancia de 0.2 del estrangulamiento grave o 1.0. Si el tiempo es menor que la cantidad necesaria para ejecutar la carga de trabajo, el juego debe disminuirla a un nivel sostenible. Por ejemplo, el juego puede reducir la velocidad de fotogramas, disminuir la fidelidad o reducir el trabajo de conectividad de red.

Estados térmicos y su significado

• Si el dispositivo no está en modo de limitación térmica, haz lo siguiente:
  • THERMAL_STATUS_NONE
• Algunas limitaciones, pero sin impacto significativo en el rendimiento:
  • THERMAL_STATUS_LIGHT
  • THERMAL_STATUS_MODERATE
• Limitación significativa que afecta el rendimiento:
  • THERMAL_STATUS_SEVERE
  • THERMAL_STATUS_CRITICAL
  • THERMAL_STATUS_EMERGENCY
  • THERMAL_STATUS_SHUTDOWN

Limitaciones de dispositivos de la API de Thermal

Existen algunas limitaciones conocidas o requisitos adicionales de la API de Thermal debido a las implementaciones de la API de Thermal en dispositivos más antiguos. A continuación, se indican las limitaciones y cómo solucionarlas:

• No llames a la API de GetThermalHeadroom() con demasiada frecuencia. Si lo haces, la API devolverá NaN. No deberías llamarlo más de una vez cada 10 segundos.
• Evita llamar desde varios subprocesos, ya que es más difícil garantizar la frecuencia de llamadas y puede hacer que la API devuelva NaN.
• Si el valor inicial de GetThermalHeadroom() es NaN, la API no está disponible en el dispositivo.
• Si GetThermalHeadroom() devuelve un valor alto (p. ej., 0.85 o más) y GetCurrentThermalStatus() sigue devolviendo THERMAL_STATUS_NONE, es probable que el estado no se haya actualizado. Usa heurísticas para estimar el estado correcto de regulación térmica o solo usa getThermalHeadroom() sin getCurrentThermalStatus().

Ejemplo de heurística:

1. Comprueba que se admita la API de Thermal. isAPISupported() verifica el valor de la primera llamada a getThermalHeadroom para asegurarse de que no sea 0 ni NaN, y omite el uso de la API si el primer valor es 0 o NaN.
2. Si getCurrentThermalStatus() devuelve un valor distinto de THERMAL_STATUS_NONE, el dispositivo está en modo de limitación térmica.
3. Si getCurrentThermalStatus() sigue devolviendo THERMAL_STATUS_NONE, no significa necesariamente que el dispositivo no esté en modo de limitación térmica. Esto podría significar que getCurrentThermalStatus() no es compatible con el dispositivo. Verifica el valor de retorno de getThermalHeadroom() para asegurarte del estado del dispositivo.
4. Si getThermalHeadroom() devuelve un valor superior a 1.0, es posible que el estado sea THERMAL_STATUS_SEVERE o superior. Reduce la carga de trabajo de inmediato y mantén una carga de trabajo más baja hasta que getThermalHeadroom() devuelva un valor más bajo.
5. Si getThermalHeadroom() devuelve un valor de 0.95, el estado podría ser THERMAL_STATUS_MODERATE o superior. Reduce la carga de trabajo de inmediato y mantén la vigilancia para evitar una lectura más alta.
6. Si getThermalHeadroom() devuelve un valor de 0.85, el estado podría ser THERMAL_STATUS_LIGHT. Mantén la vigilancia y reduce la carga de trabajo si es posible.

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: