थर्मल एपीआई

रि‍लीज़ का तारीख:

Android 11 (एपीआई लेवल 30) - Thermal API

Android 12 (एपीआई लेवल 31) - NDK API

(प्रीव्यू) Android 15 (DP1) - getThermalHeadroomThresholds()

आपके ऐप्लिकेशन की संभावित परफ़ॉर्मेंस, डिवाइस की थर्मल स्थिति से सीमित होती है. यह स्थिति, मौसम, हाल ही में किए गए इस्तेमाल, और डिवाइस के थर्मल डिज़ाइन जैसी विशेषताओं के आधार पर अलग-अलग हो सकती है. डिवाइस, थर्मल थ्रॉटलिंग से पहले, सीमित समय के लिए ही बेहतर परफ़ॉर्मेंस दे सकते हैं. आपके ऐप्लिकेशन को लागू करने का मुख्य लक्ष्य, थर्मल सीमाओं से ज़्यादा परफ़ॉर्मेंस के लक्ष्यों को हासिल करना होना चाहिए. Thermal API की मदद से, डिवाइस के हिसाब से ऑप्टिमाइज़ेशन की ज़रूरत के बिना ऐसा किया जा सकता है. इसके अलावा, परफ़ॉर्मेंस से जुड़ी समस्याओं को डीबग करते समय, यह जानना ज़रूरी है कि आपके डिवाइस की थर्मल स्थिति, परफ़ॉर्मेंस को सीमित कर रही है या नहीं.

गेम इंजन में आम तौर पर, रनटाइम परफ़ॉर्मेंस पैरामीटर होते हैं. इनकी मदद से, इंजन के ज़रिए डिवाइस पर डाले जाने वाले वर्कलोड को अडजस्ट किया जा सकता है. उदाहरण के लिए, इन पैरामीटर से वर्कर थ्रेड की संख्या, बड़े और छोटे कोर के लिए वर्कर-थ्रेड अफ़िनिटी, जीपीयू फ़िडेलिटी के विकल्प, और फ़्रेमबफ़र रिज़ॉल्यूशन सेट किए जा सकते हैं. Unity Engine में, गेम डेवलपर, अडैप्टिव परफ़ॉर्मेंस प्लग-इन का इस्तेमाल करके, क्वालिटी सेटिंग में बदलाव करके वर्कलोड को अडजस्ट कर सकते हैं. Unreal Engine के लिए, क्वालिटी लेवल को डाइनैमिक तरीके से अडजस्ट करने के लिए, स्केलेबिलिटी सेटिंग का इस्तेमाल करें.

जब कोई डिवाइस, थर्मल की असुरक्षित स्थिति में पहुंचता है, तो आपका गेम, इन पैरामीटर की मदद से वर्कलोड कम करके थ्रॉटल होने से बच सकता है. थ्रॉटलिंग से बचने के लिए, आपको डिवाइस की थर्मल स्थिति की निगरानी करनी चाहिए और गेम इंजन के वर्कलोड को पहले से ही अडजस्ट करना चाहिए.

डिवाइस के ज़्यादा गर्म होने पर, गर्मी को कम करने के लिए, वर्कलोड को सस्टेनेबल परफ़ॉर्मेंस लेवल से कम करना होगा. थर्मल हेडरूम के सुरक्षित लेवल तक कम होने के बाद, गेम, क्वालिटी सेटिंग को फिर से बढ़ा सकता है. हालांकि, यह पक्का करें कि खेलने के लिए ऑप्टिमाइज़ किए गए समय के लिए, सस्टेनेबल क्वालिटी लेवल सेट किया गया हो.

` getThermalHeadroom` तरीके को पोल करके, डिवाइस की थर्मल स्थिति की निगरानी की जा सकती है. इस तरीके से यह अनुमान लगाया जा सकता है कि डिवाइस, ज़्यादा गर्म हुए बिना, मौजूदा परफ़ॉर्मेंस लेवल को कितने समय तक बनाए रख सकता है. अगर वर्कलोड को चलाने के लिए ज़रूरी समय, अनुमानित समय से कम है, तो आपके गेम को वर्कलोड को सस्टेनेबल लेवल तक कम करना चाहिए. उदाहरण के लिए, गेम, छोटे कोर पर शिफ़्ट हो सकता है, फ़्रेम रेट कम कर सकता है या फ़िडेलिटी कम कर सकता है.

थर्मल मैनेजर हासिल करना

Thermal API का इस्तेमाल करने के लिए, सबसे पहले आपको थर्मल मैनेजर हासिल करना होगा

AThermalManager* thermal_manager = AThermal_acquireManager();

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

थर्मल हेडरूम के बारे में क्वेरी करना

सिस्टम से मौजूदा थर्मल हेडरूम के बारे में पूछा जा सकता है. इससे यह पता चलता है कि आपका वर्कलोड, थर्मल थ्रॉटलिंग के कितने करीब है. एपीआई की मदद से, मौजूदा वर्कलोड के साथ x सेकंड पहले के तापमान का अनुमान भी लगाया जा सकता है. इससे आपके ऐप्लिकेशन को जवाब देने के लिए ज़्यादा समय मिल सकता है. हालांकि, यह मौजूदा थर्मल स्टेटस का इस्तेमाल करने की तुलना में कम सटीक होगा.

नतीजा 0.0f (कोई थ्रॉटलिंग नहीं, THERMAL_STATUS_NONE)

से लेकर 1.0f (ज़्यादा थ्रॉटलिंग, THERMAL_STATUS_SEVERE) तक हो सकता है. अगर आपके गेम में ग्राफ़िक्स क्वालिटी के अलग-अलग लेवल हैं, तो थर्मल हेडरूम के लिए हमारे दिशा-निर्देशों का पालन करें.

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

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

इसके अलावा, जानकारी पाने के लिए थर्मल स्टेटस पर भरोसा करें

हर डिवाइस मॉडल को अलग-अलग तरीके से डिज़ाइन किया जा सकता है. कुछ डिवाइस, गर्मी को बेहतर तरीके से फैला सकते हैं. इसलिए, थ्रॉटल होने से पहले, वे ज़्यादा थर्मल हेडरूम को झेल सकते हैं. अगर आपको थर्मल हेडरूम की रेंज के आसान ग्रुप को पढ़ना है, तो मौजूदा डिवाइस पर थर्मल हेडरूम की वैल्यू को समझने के लिए, थर्मल स्टेटस देखें.

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

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

थर्मल स्टेटस में बदलाव होने पर सूचना पाएं

thermalHeadroom को तब तक पोल करने से भी बचा जा सकता है, जब तक thermalStatus किसी खास लेवल पर न पहुंच जाए. उदाहरण के लिए: THERMAL_STATUS_LIGHT. ऐसा करने के लिए, कॉलबैक रजिस्टर किया जा सकता है, ताकि स्टेटस में बदलाव होने पर सिस्टम आपको सूचना दे सके.

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++ गेम पर, C++ API (NDK API) और Java API (JNI के ज़रिए) दोनों का इस्तेमाल करके, Thermal API को लागू करने के तरीके के बारे में पूरी जानकारी पाने के लिए, अडैप्टेबिलिटी कोडलैब सेक्शन में 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 की डिवाइस से जुड़ी सीमाएं

Thermal API की कुछ जानी-मानी सीमाएं या अतिरिक्त ज़रूरी शर्तें हैं. ऐसा इसलिए है, क्योंकि पुराने डिवाइसों पर Thermal API को लागू किया गया है. सीमाएं और उनसे जुड़ी समस्याओं को हल करने के तरीके यहां दिए गए हैं:

• GetThermalHeadroom() API को बार-बार कॉल न करें. ऐसा करने पर, एपीआई से NaN मिलता है. इसे हर 10 सेकंड में एक से ज़्यादा बार कॉल नहीं करना चाहिए.
• इसे एक से ज़्यादा थ्रेड से कॉल न करें. इससे कॉल करने की फ़्रीक्वेंसी को पक्का करना मुश्किल हो जाता है और एपीआई से NaN मिल सकता है.
• अगर GetThermalHeadroom() की शुरुआती वैल्यू NaN है, तो डिवाइस पर एपीआई उपलब्ध नहीं है
• अगर GetThermalHeadroom() से ज़्यादा वैल्यू मिलती है.उदाहरण के लिए: 0.85 या इससे ज़्यादा और GetCurrentThermalStatus() से अब भी THERMAL_STATUS_NONE मिलता है, तो हो सकता है कि स्टेटस अपडेट न हुआ हो. थर्मल थ्रॉटलिंग के सही स्टेटस का अनुमान लगाने के लिए, ह्यूरिस्टिक्स का इस्तेमाल करें या सिर्फ़ getThermalHeadroom() का इस्तेमाल करें. इसके लिए, getCurrentThermalStatus() का इस्तेमाल न करें.

ह्यूरिस्टिक्स का उदाहरण:

1. देखें कि Thermal API काम करता है या नहीं. isAPISupported() , getThermalHeadroom को पहले कॉल करने की वैल्यू की जांच करता है, ताकि यह पक्का किया जा सके कि यह 0 या NaN नहीं है. अगर पहली वैल्यू 0 या NaN है, तो एपीआई का इस्तेमाल नहीं किया जाता.
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 हो सकता है. इसलिए, इस पर नज़र रखें और अगर मुमकिन हो, तो वर्कलोड कम करें

Pseudocode:

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

डायग्राम: