Thermal API

リリース日:

Android 11（API レベル 30） - Thermal API

Android 12（API レベル 31） - NDK API

（プレビュー）Android 15（DP1）- getThermalHeadroomThresholds()

アプリの潜在的なパフォーマンスは、デバイスの温度状態によって制限され、天気、最近の使用状況、デバイスの温度設計などの特性に応じて変化する可能性があります。デバイスは、サーマル スロットリングされるまでの限られた時間にわたってのみ高レベルのパフォーマンスを維持できます。実装の主な目標は、温度の上限を超えることなくパフォーマンス目標を達成することです。Thermal API を使用すると、デバイス固有の最適化を行わずに済みます。さらに、パフォーマンスの問題をデバッグするときは、デバイスの温度状態がパフォーマンスを制限しているかどうかを把握することが重要です。さらに、パフォーマンスの問題をデバッグするときは、デバイスの温度状態がパフォーマンスを制限しているかどうかを知ることが重要です。

通常、ゲームエンジンには、エンジンがデバイスにかけるワークロードを調整できるランタイム パフォーマンス パラメータがあります。たとえば、これらのパラメータを使用して、ワーカー スレッドの数、大小のコアのワーカー スレッド アフィニティ、GPU の忠実度オプション、フレームバッファの解像度を設定できます。Unity Engine では、ゲーム デベロッパーは、アダプティブ パフォーマンス プラグインを使用して品質設定を変更することでワークロードを調整できます。Unreal Engine の場合は、スケーラビリティ設定を使用して品質レベルを動的に調整します。

デバイスが安全ではない温度状態に近づくと、ゲームはこれらのパラメータを使用してワークロードを軽減することでスロットリングを回避できます。スロットリングを回避するには、デバイスの温度状態をモニタリングし、ゲームエンジンのワークロードを事前に調整する必要があります。デバイスが過熱すると、ワークロードは熱を放出するためにサステナブルなパフォーマンス レベルを下回る必要があります。サーマル ヘッドルームが安全なレベルまで低下すると、ゲームは品質設定を再度上げることができますが、最適なプレイ時間を実現するサステナブルな品質レベルを見つけます。

デバイスの温度状態をモニタリングするには、getThermalHeadroom メソッドをポーリングします。このメソッドは、デバイスが過熱することなく現在のパフォーマンス レベルを維持できる期間を予測します。維持できる期間がワークロードの実行に必要な期間よりも短い場合、ゲームはワークロードを持続可能なレベルまで下げる必要があります。たとえば、ゲームはより小さなコアに移行したり、フレームレートを下げたり、忠実度を下げたりする可能性があります。

温度マネージャーを取得する

Thermal API を使用するには、まず Thermal Manager を取得する必要があります。

AThermalManager* thermal_manager = AThermal_acquireManager();

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

詳細な制御のためにサーマル ヘッドルームを x 秒先で予測する

現在のワークロードから x 秒前に温度を予測するようシステムに指示できます。これにより、ワークロードを減らしてサーマル スロットリングが発生しないようにすることで、よりきめ細かい制御と対応のための時間を増やすことができます。

結果の範囲は、0.0f（スロットリングなし、THERMAL_STATUS_NONE）から 1.0f（ヘビー スロットリング、THERMAL_STATUS_SEVERE）です。ゲーム内のグラフィック品質レベルが異なる場合は、サーマル ヘッドルームに関するガイドラインに準拠してください。

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

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

または、熱ステータスに基づいて明確にします。

デバイスモデルによってデザインが異なる場合があります。デバイスによっては、熱の分散性が向上するため、スロットリング前に大きなサーマル ヘッドルームに耐えられる場合があります。サーマル ヘッドルームの範囲の簡素化されたグループを読み取る場合は、サーマル ステータスを確認して、現在のデバイスのサーマル ヘッドルーム値を把握できます。

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

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

熱ステータスが変更されたときに通知を受け取る

また、thermalStatus が特定のレベル（THERMAL_STATUS_LIGHT など）に達するまで thermalHeadroom をポーリングしないようにすることもできます。そのためには、ステータスが変わるたびにシステムから通知されるコールバックを登録します。

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

完了したら、忘れずにリスナーを削除してください

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

powerManager.removeThermalStatusListener(listener);

クリーンアップ

完了したら、取得した thermal_manager をクリーンアップする必要があります。Java を使用している場合、PowerManager 参照は自動的にガベージ コレクションされる可能性があります。ただし、JNI 経由で Java API を使用していて、参照を保持している場合は、参照をクリーンアップすることを忘れないでください。

AThermal_releaseManager(thermal_manager);

C++ API（NDK API）と Java API（JNI 経由）の両方を使用してネイティブ C++ ゲームに Thermal API を実装する方法の詳細なガイドについては、適応性に関する Codelab セクションの Thermal API を統合するセクションをご覧ください。

サーマル ヘッドルームのガイドライン

デバイスの温度状態をモニタリングするには、getThermalHeadroom メソッドをポーリングします。このメソッドは、デバイスが THERMAL_STATUS_SEVERE に達するまでに現在のパフォーマンス レベルを維持できる期間を予測します。たとえば、getThermalHeadroom(30) が 0.8 を返す場合、30 秒後にヘッドルームが 0.8（厳しいスロットリングから 0.2 の距離にある 1.0）に達すると予想されることを示します。この時間がワークロードの実行に必要な時間より短い場合、ゲームはワークロードを持続可能なレベルまで減らす必要があります。たとえば、フレームレートを下げたり、忠実度を下げたり、ネットワーク接続作業を減らしたりできます。

熱ステータスと意味

• デバイスがサーマル スロットリングされていない場合:
  • THERMAL_STATUS_NONE
• ある程度のスロットリングがあるが、パフォーマンスに大きな影響はない:
  • THERMAL_STATUS_LIGHT
  • THERMAL_STATUS_MODERATE
• パフォーマンスに影響する大幅なスロットリング:
  • THERMAL_STATUS_SEVERE
  • THERMAL_STATUS_CRITICAL
  • THERMAL_STATUS_EMERGENCY
  • THERMAL_STATUS_SHUTDOWN

Thermal API のデバイス制限

Thermal API には、古いデバイスに Thermal API が実装されているため、いくつかの既知の制限事項や追加要件があります。制限事項と回避方法は次のとおりです。

• GetThermalHeadroom() API を頻繁に呼び出さないでください。そのようにすると、API から NaN が返されます。1 秒に 1 回まで呼び出す必要があります。
• GetThermalHeadroom() の初期値が NaN の場合、デバイスで API は使用できません。
• GetThermalHeadroom() が高い値（0.85 以上など）を返しても GetCurrentThermalStatus() が THERMAL_STATUS_NONE を返す場合、ステータスは更新されていない可能性があります。ヒューリスティックを使用して、正しいサーマル スロットリング ステータスを推定するか、getCurrentThermalStatus() なしで getThermalHeadroom() を使用します。

ヒューリスティックの例:

1. Thermal API がサポートされていることを確認します。isAPISupported() は、getThermalHeadroom の最初の呼び出しの値が 0 または NaN でないことを確認し、最初の値が 0 または NaN の場合は API の使用をスキップします。
2. getCurrentThermalStatus() が THERMAL_STATUS_NONE 以外の値を返す場合、デバイスはサーマル スロットリングされています。
3. getCurrentThermalStatus() が THERMAL_STATUS_NONE を返し続けても、必ずしもデバイスがサーマル スロットリングされていないとは限りません。デバイスで getCurrentThermalStatus() がサポートされていない可能性があります。getThermalHeadroom() の戻り値をチェックして、デバイスの状態を確認します。
4. getThermalHeadroom() が 1.0 より大きい値を返す場合、ステータスは実際には THERMAL_STATUS_SEVERE 以上になり、すぐにワークロードを減らして、getThermalHeadroom() が小さい値を返すまで低いワークロードを維持します。
5. getThermalHeadroom() が値 0.95 を返す場合、ステータスは実際には THERMAL_STATUS_MODERATE 以上になり、すぐにワークロードを減らして、読み取り値が高くなることを防いで監視を継続します。
6. getThermalHeadroom() が値 0.85 を返す場合、ステータスは実際には THERMAL_STATUS_LIGHT である可能性があります。監視を継続し、可能であればワークロードを減らしてください。

擬似コード:

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

図: