API Thermal

Date de sortie:

Android 11 (niveau d'API 30) – API Thermal

Android 12 (niveau d'API 31) – API NDK

(Preview) Android 15 (DP1) : getThermalHeadroomThresholds()

Les performances potentielles de votre application sont limitées par l'état thermique de l'appareil, qui peut varier en fonction de caractéristiques telles que la météo, son utilisation récente et sa conception thermique. Les appareils ne peuvent maintenir un niveau de performances élevé que pendant une certaine durée avant de devoir faire face à des limites thermiques. L'un des buts ultimes de votre implémentation est d'atteindre les objectifs de performances sans dépasser les limites thermiques. L'API Thermal permet de le faire sans avoir besoin d'optimisations spécifiques à l'appareil. En outre, lors du débogage des problèmes de performances, il est important de savoir si l'état thermique de votre appareil limite les performances.

Les moteurs de jeu disposent généralement de paramètres de performances d'exécution permettant d'ajuster la charge de travail qu'ils imposent à l'appareil. Par exemple, ces paramètres peuvent définir le nombre de threads de calcul, l'affinité entre les nœuds de calcul et les threads pour les cœurs de petite et de grande taille, les options de fidélité GPU et les résolutions de tampon de trame. Dans Unity Engine, les développeurs de jeux peuvent ajuster la charge de travail en modifiant les paramètres de qualité à l'aide du plug-in Adaptive Performance. Pour Unreal Engine, utilisez les paramètres d'évolutivité pour ajuster dynamiquement les niveaux de qualité.

Lorsqu'un appareil se rapproche d'un état thermique qui n'est pas sûr, ces paramètres contribuent à réduire la charge de travail afin que votre jeu n'ait pas à en subir les conséquences. Pour éviter toute limitation, vous devez surveiller l'état thermique de l'appareil et ajuster de manière proactive la charge de travail du moteur de jeu. Lorsque l'appareil est en surchauffe, la charge de travail doit descendre en dessous des niveaux de performances durables pour dissiper la chaleur. Une fois que la marge thermique est descendue à des niveaux plus sûrs, le jeu peut à nouveau augmenter les paramètres de qualité, mais veillez à trouver un niveau de qualité durable pour une durée de jeu optimale.

Pour surveiller l'état thermique de l'appareil, interrogez la méthode getThermalHeadroom. Cette méthode prédit la durée pendant laquelle l'appareil peut maintenir le niveau de performances actuel sans surchauffe. 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, il peut basculer sur des cœurs plus petits, diminuer la fréquence de frames ou réduire la fidélité.

Remarque : Si votre jeu collecte des données télémétriques de performances auprès des joueurs, l'état thermique de l'appareil est une métrique qu'il est conseillé d'inclure, car elle fournit plus de contexte sur les problèmes associés.

Figure 1. Plage de température sans surveillance active de getThermalHeadroom

Figure 2. Plage de température avec surveillance active de "getThermalHeadroom"

Acquérir Thermal Manager

Pour utiliser l'API Thermal, vous devez d'abord acquérir Thermal Manager.

C++

AThermalManager* thermal_manager = AThermal_acquireManager();

Java

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

Prévoir la marge thermique x secondes à l'avance pour plus de contrôle

Vous pouvez demander au système de prévoir la température x secondes à l'avance avec la charge de travail actuelle. Vous bénéficiez ainsi d'un contrôle plus précis et de plus de temps pour réagir en réduisant la charge de travail afin d'éviter le déclenchement du throttling thermique.

Le résultat varie de 0,0 f (pas de limitation, THERMAL_STATUS_NONE) à 1,0 f (limitation importante, THERMAL_STATUS_SEVERE). Si vous avez différents niveaux de qualité graphique dans vos jeux, vous pouvez suivre nos Consignes concernant la marge thermique.

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

Remarque :Si getThermalHeadroom renvoie NaN, assurez-vous de ne pas l'appeler plus d'une fois toutes les 10 secondes. Si la valeur NaN est toujours renvoyée, il est possible que le modèle d'appareil ne dispose pas du matériel thermique et que l'API Thermal ne soit pas prise en charge.

Vous pouvez également vous fier à l'état thermique pour obtenir des précisions.

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

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

Remarque :La même valeur thermalHeadroom peut être mappée sur un certain thermalStatus sur un modèle d'appareil, mais sur un autre thermalStatus sur un autre appareil. Cela est prévisible en raison des différences de conception, des caractéristiques thermiques et du profil de performances de l'appareil.

Remarque :Il est possible que certains appareils ne soient pas encore entièrement compatibles avec cette technologie et renvoient THERMAL_STATUS_NONE, quelle que soit la valeur réelle de la marge thermique et de l'état de limitation. C'est pourquoi nous vous recommandons d'utiliser plutôt getThermalHeadroom. Consultez la section Limites de l'appareil de l'API Thermal pour trouver une solution à ce problème.

Recevoir une notification lorsque l'état thermique change

Vous pouvez également éviter d'interroger thermalHeadroom tant que thermalStatus n'a pas atteint un certain niveau (par exemple, THERMAL_STATUS_LIGHT). Pour ce faire, vous pouvez enregistrer un rappel pour que le système vous avertisse chaque fois que l'état a changé.

Remarque :Consultez les limites de l'API Thermal pour les appareils et ne vous appuyez pas uniquement sur GetCurrentThermalStatus() sans validation avec 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'oubliez pas de supprimer l'écouteur lorsque vous avez terminé.

C++

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

Java

powerManager.removeThermalStatusListener(listener);

Effectuer un nettoyage

Une fois 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.

C++

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 de l'atelier de programmation Adaptabilité.

Consignes concernant la plage de température

Pour surveiller l'état thermique de l'appareil, interrogez la méthode getThermalHeadroom. 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 marge de manœuvre devrait atteindre 0,8, avec une distance de 0,2 de la limitation sévère, soit 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, réduire la fidélité ou réduire 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, mais cela n'a pas d'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 concernant les appareils

L'API Thermal présente certaines limites ou exigences supplémentaires connues, en raison des implémentations de l'API Thermal sur les anciens appareils. Voici les limites et les solutions pour les contourner:

• N'appelez pas l'API GetThermalHeadroom() trop fréquemment. Dans ce cas, 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 s'assurer de la fréquence des appels 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, l'état n'est probablement pas mis à jour. Utilisez des heuristiques pour estimer l'état de limitation thermique approprié 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 égale à 0 ou NaN.
2. Si getCurrentThermalStatus() renvoie une valeur autre que THERMAL_STATUS_NONE, l'appareil est limité thermiquement.
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 ê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 réalité ê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 réalité ê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.
      }
    }
  }

Diagramme:

Figure 3 : Exemple d'heuristique pour déterminer la compatibilité de l'API Thermal sur les appareils plus anciens