Thermal API

リリース:

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

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

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

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

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

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

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

注: ゲームがプレーヤーからパフォーマンス テレメトリーを収集する場合は、デバイスの温度状態を指標として含めることをおすすめします。関連する問題の詳細なコンテキストを得ることができます。

図 1. getThermalHeadroom を積極的にモニタリングしないサーマル ヘッドルーム

図 2. 「getThermalHeadroom」のアクティブ モニタリングによるサーマル ヘッドルーム

Thermal Manager を取得する

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

C++

AThermalManager* thermal_manager = AThermal_acquireManager();

Java

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

サーマル ヘッドルームを x 秒先に予測して、より細かく制御

現在のワークロードで x 秒先の気温を予測するようにシステムに依頼できます。これにより、よりきめ細かい制御が可能になり、ワークロードを減らしてサーマル スロットリングが開始されないようにすることで、対応時間を長くすることができます。

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

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

注: getThermalHeadroom が NaN を返す場合は、10 秒間に 1 回以上呼び出していないことを確認してください。それでも NaN が返される場合は、デバイスモデルにサーマル ハードウェアが搭載されておらず、Thermal API がサポートされていない可能性があります。

または、熱ステータスを確認して明確にすることもできます

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

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

注: 同じ thermalHeadroom 値が、あるデバイスモデルでは特定の thermalStatus にマッピングされ、別のデバイスでは別の thermalStatus にマッピングされる場合があります。これは、デバイスの設計、熱特性、パフォーマンス プロファイルの違いにより想定されます。

注: 一部のデバイスでは、この技術がまだ完全にサポートされていないため、熱ヘッドルームとスロットリング状態の実際の値に関係なく THERMAL_STATUS_NONE が返される場合があります。このため、代わりに getThermalHeadroom を使用することをおすすめします。この状況の解決策については、Thermal API のデバイスの制限事項をご覧ください。

熱ステータスが変化したときに通知を受け取る

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

注: Thermal API のデバイスの制限事項を確認し、GetThermalHeadroom() で検証せずに GetCurrentThermalStatus() のみに依存しないでください。

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

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

C++

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

Java

powerManager.removeThermalStatusListener(listener);

クリーンアップ

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

C++

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 に達することが予想されます。これは、厳しいスロットリング（1.0）から 0.2 離れていることを示します。維持できる期間がワークロードの実行に必要な期間よりも短い場合、ゲームはワークロードを持続可能なレベルまで下げる必要があります。たとえば、ゲームはフレームレートを下げたり、忠実度を下げたり、ネットワーク接続の作業を減らしたりできます。

熱ステータスとその意味

• デバイスがサーマル スロットリングを受けていない場合:
  • THERMAL_STATUS_NONE
• スロットリングが一部行われるが、パフォーマンスには大きく影響しない:
  • THERMAL_STATUS_LIGHT
  • THERMAL_STATUS_MODERATE
• パフォーマンスに影響する重大なスロットリング:
  • THERMAL_STATUS_SEVERE
  • THERMAL_STATUS_CRITICAL
  • THERMAL_STATUS_EMERGENCY
  • THERMAL_STATUS_SHUTDOWN

Thermal API のデバイスの制限事項

古いデバイスでのサーマル API の実装により、サーマル API には既知の制限や追加の要件があります。制限事項とその回避方法は次のとおりです。

• GetThermalHeadroom() API を頻繁に呼び出さないでください。その場合、API は NaN を返します。10 秒間に 1 回を超えて呼び出さないでください。
• 複数のスレッドから呼び出すことは避けてください。呼び出し頻度を確保しづらく、API が NaN を返す原因となる可能性があります。
• 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.
      }
    }
  }

図:

図 3. 古いデバイスで Thermal API のサポートを判断するヒューリスティクスの例