Thermal API

Dirilis:

Android 11 (Level API 30) - Thermal API

Android 12 (Level API 31) - NDK API

(Pratinjau) Android 15 (DP1) - getThermalHeadroomThresholds()

Potensi performa aplikasi Anda dibatasi oleh status termal perangkat, yang dapat bervariasi berdasarkan karakteristik seperti cuaca, penggunaan terbaru, dan desain termal perangkat. Perangkat hanya dapat mempertahankan level performa yang tinggi selama jangka waktu tertentu sebelum di-throttle secara termal. Sasaran utama penerapan Anda adalah untuk mencapai sasaran performa tanpa melampaui batasan termal. Thermal API memungkinkan hal ini tanpa perlu pengoptimalan khusus perangkat. Selain itu, saat men-debug masalah performa, penting untuk mengetahui apakah status termal perangkat Anda membatasi performa.

Game engine biasanya memiliki parameter performa runtime yang dapat menyesuaikan beban kerja yang diberikan mesin di perangkat. Misalnya, parameter ini dapat menetapkan jumlah thread pekerja, afinitas thread pekerja untuk core besar dan kecil, opsi fidelitas GPU, dan resolusi framebuffer. Di Unity Engine, developer game dapat menyesuaikan beban kerja dengan mengubah Setelan Kualitas menggunakan plugin Adaptive Performance. Untuk Unreal Engine, gunakan Scalability Settings untuk menyesuaikan tingkat kualitas secara dinamis.

Saat perangkat mendekati status termal yang tidak aman, game Anda dapat menghindari throttling dengan mengurangi beban kerja melalui parameter ini. Untuk menghindari throttling, Anda harus memantau status termal perangkat dan secara proaktif menyesuaikan beban kerja game engine.

Setelah perangkat menjadi terlalu panas, beban kerja harus berkurang di bawah level performa berkelanjutan untuk menghilangkan panas. Setelah ruang termal menurun ke tingkat yang lebih aman, game dapat meningkatkan setelan kualitas lagi, tetapi pastikan untuk menemukan tingkat kualitas yang berkelanjutan untuk waktu bermain yang optimal.

Anda dapat memantau status termal perangkat dengan melakukan polling pada metode getThermalHeadroom. Metode ini memprediksi berapa lama perangkat dapat mempertahankan level performa saat ini tanpa panas berlebih. Jika waktunya kurang dari jumlah yang diperlukan untuk menjalankan beban kerja, game Anda harus mengurangi beban kerja ke level yang berkelanjutan. Misalnya, game dapat beralih ke core yang lebih kecil, mengurangi kecepatan frame, atau menurunkan fidelitas.

Mendapatkan Thermal Manager

Untuk menggunakan Thermal API, Anda harus mendapatkan Thermal Manager terlebih dahulu

AThermalManager* thermal_manager = AThermal_acquireManager();

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

Memperkirakan Headroom Termal x detik sebelumnya untuk kontrol yang lebih baik

Anda dapat meminta sistem untuk memperkirakan suhu x detik ke depan dengan beban kerja saat ini. Hal ini memberi Anda kontrol yang lebih mendetail dan lebih banyak waktu untuk bereaksi dengan mengurangi beban kerja guna mencegah terjadinya pembatasan termal.

Hasilnya berkisar dari 0,0f (tanpa pembatasan, THERMAL_STATUS_NONE)

hingga 1,0f (pembatasan berat, THERMAL_STATUS_SEVERE). Jika Anda memiliki tingkat kualitas grafis yang berbeda dalam game, Anda dapat mengikuti Panduan Ruang Termal kami.

float thermal_headroom = AThermal_getThermalHeadroom(0);
ALOGI("ThermalHeadroom: %f", thermal_headroom);

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

Atau, mengandalkan status termal untuk mendapatkan klarifikasi

Setiap model perangkat mungkin didesain secara berbeda. Beberapa perangkat mungkin dapat mendistribusikan panas dengan lebih baik dan dengan demikian dapat menahan ruang termal yang lebih tinggi sebelum di-throttle. Jika Anda ingin membaca pengelompokan rentang headroom termal yang disederhanakan, Anda dapat memeriksa status termal untuk memahami nilai headroom termal di perangkat saat ini.

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

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

Mendapatkan notifikasi saat status termal berubah

Anda juga dapat menghindari polling thermalHeadroom hingga thermalStatus mencapai tingkat tertentu (misalnya: THERMAL_STATUS_LIGHT). Untuk melakukannya, Anda dapat mendaftarkan callback agar sistem memberi tahu Anda setiap kali status berubah.

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

Jangan lupa menghapus pemroses setelah selesai

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

powerManager.removeThermalStatusListener(listener);

Pembersihan

Setelah selesai, Anda harus membersihkan thermal_manager yang Anda peroleh. Jika Anda menggunakan Java, referensi PowerManager dapat secara otomatis dikumpulkan sampah untuk Anda. Namun, jika Anda menggunakan Java API melalui JNI dan telah mempertahankan referensi, jangan lupa untuk membersihkan referensi tersebut.

AThermal_releaseManager(thermal_manager);

Untuk panduan lengkap tentang cara menerapkan Thermal API di game C++ native menggunakan C++ API (NDK API) dan Java API (melalui JNI), lihat bagian Mengintegrasikan Thermal API di bagian Codelab adaptasi.

Panduan headroom termal

Anda dapat memantau status termal perangkat dengan memilih metode getThermalHeadroom. Metode ini memprediksi berapa lama perangkat dapat mempertahankan level performa saat ini sebelum mencapai THERMAL_STATUS_SEVERE. Misalnya, jika getThermalHeadroom(30) menampilkan 0,8, hal ini menunjukkan bahwa dalam 30 detik, headroom diperkirakan akan mencapai 0,8, yang berjarak 0,2 dari pembatasan berat, atau 1,0. Jika waktunya kurang dari jumlah yang diperlukan untuk menjalankan beban kerja, game Anda harus mengurangi beban kerja ke level yang berkelanjutan. Misalnya, game dapat mengurangi kecepatan frame, menurunkan fidelitas, atau mengurangi beban kerja konektivitas jaringan.

Status termal dan artinya

• Jika perangkat tidak mengalami throttling termal:
  • THERMAL_STATUS_NONE
• Beberapa throttling, tetapi tidak berdampak signifikan pada performa:
  • THERMAL_STATUS_LIGHT
  • THERMAL_STATUS_MODERATE
• Throttling signifikan yang memengaruhi performa:
  • THERMAL_STATUS_SEVERE
  • THERMAL_STATUS_CRITICAL
  • THERMAL_STATUS_EMERGENCY
  • THERMAL_STATUS_SHUTDOWN

Batasan perangkat Thermal API

Ada beberapa batasan umum atau persyaratan tambahan Thermal API, karena penerapan Thermal API di perangkat lama. Batasan dan cara mengatasinya adalah sebagai berikut:

• Jangan terlalu sering memanggil API GetThermalHeadroom(). Jika Anda melakukannya, API akan menampilkan NaN. Anda tidak boleh memanggilnya lebih dari sekali setiap 10 detik.
• Hindari panggilan dari beberapa thread, karena lebih sulit untuk memastikan frekuensi panggilan dan dapat menyebabkan API menampilkan NaN.
• Jika nilai awal GetThermalHeadroom() adalah NaN, API tidak tersedia di perangkat
• Jika GetThermalHeadroom() menampilkan nilai yang tinggi (misalnya: 0,85 atau lebih) dan GetCurrentThermalStatus() masih menampilkan THERMAL_STATUS_NONE, kemungkinan status belum diperbarui. Gunakan heuristik untuk memperkirakan status pembatasan termal yang benar atau cukup gunakan getThermalHeadroom() tanpa getCurrentThermalStatus().

Contoh heuristik:

1. Periksa apakah Thermal API didukung. isAPISupported() memeriksa nilai panggilan pertama ke getThermalHeadroom untuk memastikan bahwa nilai tersebut bukan 0 atau NaN dan melewati penggunaan API jika nilai pertama adalah 0 atau NaN.
2. Jika getCurrentThermalStatus() menampilkan nilai selain THERMAL_STATUS_NONE, perangkat sedang mengalami pembatasan termal.
3. Jika getCurrentThermalStatus() terus menampilkan THERMAL_STATUS_NONE, hal ini tidak berarti perangkat tidak mengalami throttling termal. Hal ini dapat berarti bahwa getCurrentThermalStatus() tidak didukung di perangkat. Periksa nilai yang ditampilkan oleh getThermalHeadroom() untuk memastikan kondisi perangkat.
4. Jika getThermalHeadroom() menampilkan nilai > 1,0, statusnya sebenarnya bisa THERMAL_STATUS_SEVERE atau lebih tinggi, segera kurangi beban kerja dan pertahankan beban kerja yang lebih rendah hingga getThermalHeadroom() menampilkan nilai yang lebih rendah
5. Jika getThermalHeadroom() menampilkan nilai 0,95, statusnya sebenarnya bisa THERMAL_STATUS_MODERATE atau lebih tinggi, kurangi beban kerja segera dan tetap perhatikan untuk mencegah pembacaan yang lebih tinggi
6. Jika getThermalHeadroom() menampilkan nilai 0,85, statusnya sebenarnya bisa THERMAL_STATUS_LIGHT, tetap waspada dan kurangi beban kerja jika memungkinkan

Kode semu:

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

Diagram: