API Nhiệt

Đã phát hành:

Android 11 (API cấp 30) – API nhiệt

Android 12 (API cấp 31) – API NDK

(Bản dùng thử) Android 15 (DP1) – getThermalHeadroomThresholds()

Hiệu suất tiềm năng của ứng dụng bị giới hạn bởi trạng thái nhiệt của thiết bị. Trạng thái nhiệt có thể thay đổi tuỳ theo các yếu tố đặc thù như thời tiết, mức sử dụng gần đây và thiết kế tản nhiệt của thiết bị. Các thiết bị chỉ có thể duy trì hiệu suất cao trong một khoảng thời gian giới hạn trước khi bị điều tiết nhiệt. Mục tiêu chính của việc triển khai là đạt được mục tiêu về hiệu suất mà không bị vượt quá giới hạn nhiệt. Thermal API giúp bạn làm được điều này mà không cần tối ưu hoá theo thiết bị cụ thể. Ngoài ra, khi gỡ lỗi các vấn đề về hiệu suất, điều quan trọng là biết được liệu trạng thái nhiệt của thiết bị có đang giới hạn hiệu suất hay không.

Các công cụ phát triển trò chơi thường có các thông số hiệu suất trong thời gian chạy giúp điều chỉnh mức tải mà công cụ phân cho thiết bị. Ví dụ: các thông số này có thể thiết lập số lượng luồng công việc, chỉ định luồng công việc cho các nhân xử lý lớn và nhỏ, các tuỳ chọn về độ trung thực của GPU cũng như độ phân giải bộ đệm khung. Trong Unity Engine, nhà phát triển trò chơi có thể điều chỉnh khối lượng công việc bằng cách thay đổi Cài đặt chất lượng bằng trình bổ trợ Hiệu suất thích ứng. Đối với Unreal Engine, hãy sử dụng Scalability Settings (Cài đặt khả năng mở rộng) để điều chỉnh linh động các cấp chất lượng.

Khi thiết bị đạt đến trạng thái nhiệt không an toàn, trò chơi có thể tránh bị điều tiết bằng cách giảm mức tải thông qua các thông số này. Để tránh việc bị điều tiết, bạn nên theo dõi trạng thái nhiệt của thiết bị và chủ động điều chỉnh mức tải của công cụ phát triển trò chơi. Khi thiết bị quá nóng, mức tải phải giảm xuống dưới mức hiệu suất ổn định để phân tán nhiệt. Sau khi khoảng nhiệt giảm xuống mức an toàn hơn, trò chơi có thể tăng lại chế độ cài đặt chất lượng, nhưng hãy nhớ tìm mức chất lượng bền vững để có thời gian chơi tối ưu.

Bạn có thể theo dõi trạng thái nhiệt của thiết bị bằng cách thăm dò phương thức getThermalHeadroom. Phương thức này dự đoán khoảng thời gian thiết bị có thể duy trì mức hiệu suất hiện tại mà không quá nhiệt. Nếu khoảng thời gian này ít hơn thời gian cần thiết để chạy mức tải, thì trò chơi sẽ giảm mức tải xuống một mức ổn định. Ví dụ: trò chơi có thể chuyển sang các nhân xử lý nhỏ hơn, giảm tốc độ khung hình hoặc giảm độ trung thực.

Lưu ý: Nếu trò chơi của bạn thu thập dữ liệu về hiệu suất qua người chơi ở xa, thì trạng thái nhiệt của thiết bị là một chỉ số phù hợp để đưa vào vì chỉ số này sẽ cung cấp thêm bối cảnh cho mọi vấn đề liên quan.

Hình 1. Khoảng nhiệt mà không chủ động theo dõi getThermalHeadroom

Hình 2. Khoảng nhiệt với tính năng giám sát chủ động `getThermalHeadroom`

Mua Trình quản lý nhiệt

Để sử dụng API nhiệt, trước tiên, bạn cần có Trình quản lý nhiệt

C++

AThermalManager* thermal_manager = AThermal_acquireManager();

Java

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

Dự báo Khoảng nhiệt trước x giây để có thêm quyền kiểm soát

Bạn có thể yêu cầu hệ thống dự báo nhiệt độ trước x giây với mức tải hiện tại. Điều này giúp bạn có thêm quyền kiểm soát chi tiết hơn và có nhiều thời gian hơn để phản ứng bằng cách giảm mức tải để ngăn tình trạng điều tiết nhiệt.

Kết quả dao động từ 0,0f (không điều tiết, THERMAL_STATUS_NONE) đến 1,0f (điều tiết nhiều, THERMAL_STATUS_SEVERE). Nếu có nhiều cấp chất lượng đồ hoạ trong trò chơi, bạn có thể làm theo Nguyên tắc về khoảng nhiệt của chúng tôi.

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

Lưu ý: Nếu getThermalHeadroom trả về NaN, hãy đảm bảo rằng bạn không gọi hàm này nhiều hơn một lần trong mỗi 10 giây. Nếu vẫn trả về NaN, thì có thể mô hình thiết bị không có phần cứng nhiệt và API nhiệt không được hỗ trợ.

Ngoài ra, bạn có thể dựa vào trạng thái nhiệt để làm rõ

Mỗi mẫu thiết bị có thể được thiết kế theo cách khác nhau. Một số thiết bị có thể phân phối nhiệt tốt hơn, nhờ đó có thể chịu được khoảng nhiệt cao hơn trước khi bị điều tiết. Nếu muốn đọc một nhóm đơn giản các dải nhiệt độ, bạn có thể kiểm tra trạng thái nhiệt để hiểu rõ giá trị khoảng nhiệt trên thiết bị hiện tại.

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

Lưu ý: Cùng một giá trị thermalHeadroom có thể được liên kết với một thermalStatus nhất định trên một mẫu thiết bị, nhưng lại là một thermalStatus khác trên một thiết bị khác. Điều này là dự kiến do sự khác biệt về thiết kế thiết bị, đặc điểm nhiệt và hồ sơ hiệu suất.

Lưu ý: Một số thiết bị có thể chưa hỗ trợ đầy đủ công nghệ này và trả về THERMAL_STATUS_NONE bất kể giá trị thực tế của khoảng nhiệt và trạng thái điều tiết. Vì lý do này, bạn nên sử dụng getThermalHeadroom. Hãy xem phần Các giới hạn của thiết bị đối với API Nhiệt để biết giải pháp cho trường hợp này.

Nhận thông báo khi trạng thái nhiệt thay đổi

Bạn cũng có thể tránh thăm dò ý kiến thermalHeadroom cho đến khi thermalStatus đạt đến một cấp độ nhất định (ví dụ: THERMAL_STATUS_LIGHT). Để làm như vậy, bạn có thể đăng ký một lệnh gọi lại để hệ thống thông báo cho bạn bất cứ khi nào trạng thái thay đổi.

Lưu ý: Hãy xem Các giới hạn của thiết bị đối với API Nhiệt và đừng chỉ dựa vào GetCurrentThermalStatus() mà không xác thực bằng 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);

Hãy nhớ xoá trình nghe khi hoàn tất

C++

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

Java

powerManager.removeThermalStatusListener(listener);

Dọn dẹp

Sau khi hoàn tất, bạn cần dọn dẹp thermal_manager mà bạn đã mua. Nếu bạn đang sử dụng Java, tham chiếu PowerManager có thể được tự động thu thập rác cho bạn. Tuy nhiên, nếu bạn đang sử dụng API Java thông qua JNI và đã giữ lại một tệp tham chiếu, hãy nhớ xoá tệp tham chiếu đó!

C++

AThermal_releaseManager(thermal_manager);

Để biết hướng dẫn đầy đủ về cách triển khai API Nhiệt trên trò chơi C++ gốc bằng cả API C++ (API NDK) và API Java (thông qua JNI), hãy xem phần Tích hợp API Nhiệt trong phần Lớp học lập trình về khả năng thích ứng.

Nguyên tắc về khoảng nhiệt

Bạn có thể theo dõi trạng thái nhiệt của thiết bị bằng cách thăm dò phương thức getThermalHeadroom. Phương thức này dự đoán khoảng thời gian thiết bị có thể duy trì mức hiệu suất hiện tại trước khi đạt đến THERMAL_STATUS_SEVERE. Ví dụ: nếu getThermalHeadroom(30) trả về 0,8, thì điều này cho biết rằng trong 30 giây, khoảng không sẽ đạt đến 0,8, trong đó có khoảng cách 0,2 từ tình trạng điều tiết nghiêm trọng hoặc 1,0. Nếu khoảng thời gian này ít hơn thời gian cần thiết để chạy mức tải, thì trò chơi sẽ giảm mức tải xuống một mức ổn định. Ví dụ: trò chơi có thể giảm tốc độ khung hình, giảm độ trung thực hoặc giảm công việc kết nối mạng.

Trạng thái nhiệt và ý nghĩa

• Nếu thiết bị không bị điều tiết nhiệt:
  • THERMAL_STATUS_NONE
• Đôi khi có điều tiết, nhưng không ảnh hưởng đáng kể đến hiệu suất:
  • THERMAL_STATUS_LIGHT
  • THERMAL_STATUS_MODERATE
• Điều tiết đáng kể, ảnh hưởng đến hiệu suất:
  • THERMAL_STATUS_SEVERE
  • THERMAL_STATUS_CRITICAL
  • THERMAL_STATUS_EMERGENCY
  • THERMAL_STATUS_SHUTDOWN

Các hạn chế của thiết bị đối với Thermal API

Có một số hạn chế hoặc yêu cầu bổ sung đã biết của API nhiệt, do việc triển khai API nhiệt trên các thiết bị cũ. Sau đây là các giới hạn và cách khắc phục:

• Không gọi API GetThermalHeadroom() quá thường xuyên. Nếu bạn làm như vậy, API sẽ trả về NaN. Bạn không nên gọi hàm này nhiều hơn một lần trong mỗi 10 giây.
• Tránh gọi từ nhiều luồng, việc này sẽ khó đảm bảo tần suất gọi và có thể khiến API trả về NaN.
• Nếu giá trị ban đầu của GetThermalHeadroom() là NaN, thì API sẽ không có sẵn trên thiết bị
• Nếu GetThermalHeadroom() trả về một giá trị cao (ví dụ: 0,85 trở lên) và GetCurrentThermalStatus() vẫn trả về THERMAL_STATUS_NONE, thì trạng thái có thể không được cập nhật. Sử dụng phương pháp phỏng đoán để ước tính chính xác trạng thái điều tiết nhiệt hoặc chỉ sử dụng getThermalHeadroom() mà không cần getCurrentThermalStatus().

Ví dụ về quy tắc tìm kiếm phỏng đoán:

1. Kiểm tra để đảm bảo rằng Thermal API được hỗ trợ. isAPISupported() kiểm tra giá trị của lệnh gọi đầu tiên đến getThermalHeadroom để đảm bảo rằng giá trị đó không phải là 0 hoặc NaN và bỏ qua việc sử dụng API nếu giá trị đầu tiên là 0 hoặc NaN.
2. Nếu getCurrentThermalStatus() trả về một giá trị khác với THERMAL_STATUS_NONE, thì thiết bị đang bị điều tiết nhiệt.
3. Nếu getCurrentThermalStatus() liên tục trả về THERMAL_STATUS_NONE, thì điều này không nhất thiết có nghĩa là thiết bị không bị điều tiết nhiệt. Điều này có thể nghĩa là getCurrentThermalStatus() không được hỗ trợ trên thiết bị. Kiểm tra giá trị trả về của getThermalHeadroom() để đảm bảo tình trạng của thiết bị.
4. Nếu getThermalHeadroom() trả về giá trị > 1.0, thì trạng thái thực tế có thể là THERMAL_STATUS_SEVERE trở lên, giảm ngay khối lượng công việc và duy trì khối lượng công việc thấp hơn cho đến khi getThermalHeadroom() trả về giá trị thấp hơn
5. Nếu getThermalHeadroom() trả về giá trị 0,95, thì trạng thái thực tế có thể là THERMAL_STATUS_MODERATE trở lên, hãy giảm ngay khối lượng công việc và tiếp tục theo dõi để tránh đọc cao hơn
6. Nếu getThermalHeadroom() trả về giá trị 0,85, thì trạng thái thực sự có thể là THERMAL_STATUS_LIGHT, hãy tiếp tục theo dõi và giảm tải nếu có thể

Mã giả:

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

Sơ đồ:

Hình 3.Ví dụ về phương pháp phỏng đoán để xác định khả năng hỗ trợ Thermal API trên các thiết bị cũ