Thermal API

已发布:

Android 11 (API Level 30) - Thermal API

Android 12 (API Level 31) - NDK API

(预览版) Android 15 (DP1) - getThermalHeadroomThresholds()

应用的潜在性能受设备热状态的限制，这可能因天气、近期使用情况和设备散热设计等特征而异。设备只能在有限的时间内保持高水平性能，之后就会因散热问题而受到限制。您的实现的一个关键目标是，在不超出散热限制的情况下实现性能目标。Thermal API 使这成为可能，无需针对特定设备进行优化。此外，在调试性能问题时，了解设备的热状态是否限制了性能非常重要。

游戏引擎通常具有运行时性能参数，可以调整引擎施加到设备上的工作负载。例如，这些参数可以设置工作线程数、大小核的工作线程亲和性、GPU 保真度选项和帧缓冲区分辨率。在 Unity 引擎中，游戏开发者可以使用 Adaptive Performance 插件更改质量设置来调整工作负载。对于 Unreal Engine，请使用可伸缩性设置来动态调整质量级别。

当设备接近不安全的热状态时，您的游戏可以通过这些参数降低工作负载，从而避免受到限制。为避免限制，您应监控设备的热状态，并主动调整游戏引擎工作负载。一旦设备过热，工作负载必须降至可持续的性能水平以下，以便散热。在散热余量降至更安全的水平后，游戏可以再次提高质量设置，但请务必找到一个可持续的质量水平以实现最佳游戏时长。

您可以通过轮询 getThermalHeadroom 方法来监控设备的热状态。此方法会预测设备在不过热的情况下可以维持当前性能水平的时长。如果时间少于运行工作负载所需的时间，那么您的游戏应将工作负载降低到可持续的水平。例如，游戏可以切换到较小的核心、降低帧速率或降低保真度。

ADPF Thermal API Pre-Integration — **图 1.** 未主动监控 getThermalHeadroom 时的散热余量

ADPF Thermal API Post-Integration — **图 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);

或者，依靠热状态进行说明

每个设备型号的设计可能不同。有些设备可能能够更好地散热，因此在受到限制之前能够承受更高的散热余量。如果您想读取散热余量范围的简化分组，可以检查热状态以理解当前设备上的散热余量值。

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 达到某个级别（例如：THERMAL_STATUS_LIGHT）。为此，您可以注册回调，让系统在状态更改时通知您。

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++ 游戏中使用 C++ API (NDK API) 和 Java API（通过 JNI）实现 Thermal API 的完整指南，请参阅 Adaptability 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 API 的设备限制

由于较旧设备上的 Thermal API 实现，存在一些已知的 Thermal API 限制或额外要求。限制及其解决方法如下：

不要过于频繁地调用 GetThermalHeadroom() API。如果这样做，API 将返回 NaN。您调用它的频率不应超过每 10 秒一次。
避免从多个线程调用，这会更难确保调用频率，并可能导致 API 返回 NaN。
如果 GetThermalHeadroom() 的初始值为 NaN，则设备上不可用该 API
如果 GetThermalHeadroom() 返回高值（例如：0.85 或更高），并且 GetCurrentThermalStatus() 仍然返回 THERMAL_STATUS_NONE，则状态可能未更新。请使用启发式方法来估计正确的散热节流状态，或者仅使用 getThermalHeadroom() 而不使用 getCurrentThermalStatus()。

启发式示例

检查是否支持 Thermal API。isAPISupported() 会检查对 getThermalHeadroom 的首次调用的值，以确保它不为 0 或 NaN；如果首次调用值为 0 或 NaN，则跳过使用该 API。
如果 getCurrentThermalStatus() 返回的值不是 THERMAL_STATUS_NONE，则设备正在受到散热限制。
如果 getCurrentThermalStatus() 持续返回 THERMAL_STATUS_NONE，这不一定表示设备未受到散热限制。这可能意味着设备不支持 getCurrentThermalStatus()。请检查 getThermalHeadroom() 的返回值以确保设备状况。
如果 getThermalHeadroom() 返回的值 > 1.0，则实际状态可能为 THERMAL_STATUS_SEVERE 或更高，请立即减少工作负载并保持较低工作负载，直到 getThermalHeadroom() 返回较低值
如果 getThermalHeadroom() 返回 0.95，则实际状态可能为 THERMAL_STATUS_MODERATE 或更高，请立即减少工作负载并保持警惕以防止更高的读数
如果 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.
      }
    }
  }

图表

ADPF Heuristic Example — **图 3.** 在较旧设备上确定 Thermal API 支持情况的启发式示例

Thermal API 使用收藏整理内容 根据您的偏好保存并分类内容。

获取 Thermal Manager

C++

Java

提前 x 秒预测散热余量以进行更多控制

C++

Java

或者，依靠热状态进行说明

C++

Java

在热状态更改时收到通知

C++

Java

C++

Java

清理

C++

散热余量指南

热状态及其含义

Thermal API 的设备限制

Thermal API