API Thermal

Acquérir le gestionnaire thermique

Pour utiliser l'API Thermal, vous devez d'abord acquérir le gestionnaire thermique.

AThermalManager* thermal_manager = AThermal_acquireManager();

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

Interroger la plage de température

Vous pouvez demander au système la plage de température actuelle. Cela indique à quel point votre charge de travail est proche de la limitation thermique. L'API vous permet également de prévoir la température dans x secondes avec la charge de travail actuelle. Cela peut donner plus de temps à votre application pour répondre, mais sera moins précis que l'utilisation de l'état thermique actuel.

Le résultat varie de 0,0f (aucune limitation, THERMAL_STATUS_NONE)

à 1,0f (limitation importante, THERMAL_STATUS_SEVERE). Si vos jeux présentent différents niveaux de qualité graphique, vous pouvez suivre nos consignes concernant la plage de température.

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

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

Vous pouvez également vous appuyer sur l'état thermique pour obtenir des éclaircissements

Chaque modèle d'appareil peut être conçu différemment. Certains appareils peuvent mieux répartir la chaleur et donc supporter une plage de température plus élevée avant d'être limités. Si vous souhaitez lire un regroupement simplifié de plages de température, vous pouvez vérifier l'état thermique pour comprendre la valeur de la plage de température sur l'appareil actuel.

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

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

Recevoir une notification lorsque l'état thermique change

Vous pouvez également éviter d'interroger thermalHeadroom jusqu'à ce que thermalStatus atteigne un certain niveau (par exemple : THERMAL_STATUS_LIGHT). Pour ce faire, vous pouvez enregistrer un rappel afin que le système vous avertisse chaque fois que l'état a changé.

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

N'oubliez pas de supprimer l'écouteur lorsque vous avez terminé.

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

powerManager.removeThermalStatusListener(listener);

Nettoyage

Une fois que vous avez terminé, vous devez nettoyer le thermal_manager que vous avez acquis. Si vous utilisez Java, la référence PowerManager peut être automatiquement collectée par le garbage collector. Toutefois, si vous utilisez l'API Java via JNI et que vous avez conservé une référence, n'oubliez pas de la nettoyer.

AThermal_releaseManager(thermal_manager);

Pour obtenir un guide complet sur l'implémentation de l'API Thermal dans un jeu C++ natif à l'aide de l'API C++ (API NDK) et de l'API Java (via JNI), consultez la section Intégrer l'API Thermal dans la section Atelier de programmation sur l'adaptabilité.

Consignes concernant la plage de température

Pour surveiller l'état thermique de l'appareil, interrogez la getThermalHeadroom méthode. Cette méthode prédit la durée pendant laquelle l'appareil peut maintenir le niveau de performances actuel avant d'atteindre THERMAL_STATUS_SEVERE. Par exemple, si getThermalHeadroom(30) renvoie 0,8, cela indique que dans 30 secondes, la plage de température devrait atteindre 0,8, soit une distance de 0,2 par rapport à une limitation importante (1,0). Si cette durée est inférieure au temps nécessaire à l'exécution de la charge de travail, le jeu doit limiter la charge de travail à un niveau durable. Par exemple, le jeu peut réduire la fréquence d'images, la fidélité ou le travail de connectivité réseau.

États thermiques et signification

• Si l'appareil n'est pas soumis à une limitation thermique :
  • THERMAL_STATUS_NONE
• L'appareil est soumis à quelques limitations, sans impact significatif sur les performances :
  • THERMAL_STATUS_LIGHT
  • THERMAL_STATUS_MODERATE
• L'appareil est soumis à des limitations significatives qui nuisent aux performances :
  • THERMAL_STATUS_SEVERE
  • THERMAL_STATUS_CRITICAL
  • THERMAL_STATUS_EMERGENCY
  • THERMAL_STATUS_SHUTDOWN

Limites de l'API Thermal liées aux appareils

L'API Thermal présente certaines limites connues ou exigences supplémentaires en raison de son implémentation sur les anciens appareils. Voici les limites et comment les contourner :

• N'appelez pas l'API GetThermalHeadroom() trop fréquemment. Si vous le faites, l'API renvoie NaN. Vous ne devez pas l'appeler plus d'une fois toutes les 10 secondes.
• Évitez d'appeler à partir de plusieurs threads. Il est plus difficile de garantir la fréquence d'appel et l'API peut renvoyer NaN.
• Si la valeur initiale de GetThermalHeadroom() est NaN, l'API n'est pas disponible sur l'appareil.
• Si GetThermalHeadroom() renvoie une valeur élevée (par exemple, 0,85 ou plus) et que GetCurrentThermalStatus() renvoie toujours THERMAL_STATUS_NONE, il est probable que l'état ne soit pas mis à jour. Utilisez des heuristiques pour estimer l'état de limitation thermique correct ou utilisez simplement getThermalHeadroom() sans getCurrentThermalStatus().

Exemple d'heuristique :

1. Vérifiez que l'API Thermal est compatible. isAPISupported() vérifie la valeur du premier appel à getThermalHeadroom pour s'assurer qu'elle n'est pas égale à 0 ou NaN, et ignore l'utilisation de l'API si la première valeur est 0 ou NaN.
2. Si getCurrentThermalStatus() renvoie une valeur autre que THERMAL_STATUS_NONE, l'appareil est soumis à une limitation thermique.
3. Si getCurrentThermalStatus() continue de renvoyer THERMAL_STATUS_NONE, cela ne signifie pas nécessairement que l'appareil n'est pas soumis à une limitation thermique. Cela peut signifier que getCurrentThermalStatus() n'est pas compatible avec l'appareil. Vérifiez la valeur renvoyée par getThermalHeadroom() pour vous assurer de l'état de l'appareil.
4. Si getThermalHeadroom() renvoie une valeur supérieure à 1, 0, l'état peut en fait être THERMAL_STATUS_SEVERE ou supérieur. Réduisez immédiatement la charge de travail et maintenez-la à un niveau inférieur jusqu'à ce que getThermalHeadroom() renvoie une valeur inférieure.
5. Si getThermalHeadroom() renvoie une valeur de 0, 95, l'état peut en fait être THERMAL_STATUS_MODERATE ou supérieur. Réduisez immédiatement la charge de travail et restez vigilant pour éviter une lecture plus élevée.
6. Si getThermalHeadroom() renvoie une valeur de 0, 85, l'état peut en fait être THERMAL_STATUS_LIGHT. Restez vigilant et réduisez la charge de travail si possible.

Pseudo-code :

  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.
      }
    }
  }

Schéma :