थर्मल एपीआई

रिलीज़ की गई:

Android 11 (एपीआई लेवल 30) - थर्मल एपीआई

Android 12 (एपीआई लेवल 31) - एनडीके एपीआई

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

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

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

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

डिवाइस के ज़्यादा गर्म होने पर, काम का बोझ कम होना चाहिए, ताकि डिवाइस का तापमान कम हो सके. जब डिवाइस का तापमान कम हो जाता है, तब गेम की क्वालिटी सेटिंग को फिर से बढ़ाया जा सकता है. हालांकि, यह पक्का करें कि गेम की क्वालिटी का लेवल ऐसा हो जिससे उसे ज़्यादा देर तक खेला जा सके.

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

ध्यान दें: अगर आपका गेम, खिलाड़ियों से परफ़ॉर्मेंस टेलीमेट्री इकट्ठा करता है, तो डिवाइस की थर्मल स्थिति को शामिल करना एक अच्छी मेट्रिक है. ऐसा इसलिए, क्योंकि इससे किसी भी समस्या के बारे में ज़्यादा जानकारी मिलती है.

पहली इमेज. getThermalHeadroom

को ऐक्टिव तौर पर मॉनिटर किए बिना थर्मल हेडरूम

दूसरी इमेज. `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(0);
ALOGI("ThermalHeadroom: %f", thermal_headroom);

Java

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

ध्यान दें: अगर getThermalHeadroom NaN दिखाता है, तो पक्का करें कि इसे हर 10 सेकंड में एक से ज़्यादा बार कॉल न किया जा रहा हो. अगर अब भी 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);

ध्यान दें: ऐसा हो सकता है कि एक डिवाइस मॉडल पर किसी thermalStatus के लिए thermalHeadroom की एक ही वैल्यू मैप की गई हो, लेकिन दूसरे डिवाइस पर thermalStatus के लिए thermalHeadroom की कोई दूसरी वैल्यू मैप की गई हो. डिवाइस के डिज़ाइन, थर्मल की विशेषताओं, और परफ़ॉर्मेंस प्रोफ़ाइल में अंतर होने की वजह से ऐसा हो सकता है.

ध्यान दें: ऐसा हो सकता है कि कुछ डिवाइसों पर यह टेक्नोलॉजी अभी पूरी तरह से काम न करे. ऐसे में, थर्मल हेडरूम और थ्रॉटलिंग की स्थिति की असल वैल्यू के बावजूद, 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 लागू करने के बारे में पूरी जानकारी पाने के लिए, Adaptability codelab सेक्शन में Integrate Thermal API सेक्शन देखें.

थर्मल हेडरूम के दिशा-निर्देश

getThermalHeadroom तरीके को पोल करके, डिवाइस की थर्मल स्थिति पर नज़र रखी जा सकती है. इस तरीके से यह अनुमान लगाया जाता है कि डिवाइस, THERMAL_STATUS_SEVERE तक पहुंचने से पहले, मौजूदा परफ़ॉर्मेंस लेवल को कितने समय तक बनाए रख सकता है. उदाहरण के लिए, अगर getThermalHeadroom(30) की वैल्यू 0.8 है, तो इसका मतलब है कि 30 सेकंड में हेडरूम 0.8 तक पहुंच जाएगा. इसमें थ्रॉटलिंग की सीमा 0.2 या 1.0 से दूर है. अगर समय, वर्कलोड को पूरा करने के लिए ज़रूरी समय से कम है, तो आपके गेम को वर्कलोड को कम करके एक ऐसे लेवल पर ले जाना चाहिए जहां उसे पूरा किया जा सके. उदाहरण के लिए, गेम फ़्रेम रेट को कम कर सकता है, फ़िडेलिटी को कम कर सकता है या नेटवर्क कनेक्टिविटी को कम कर सकता है.

डिवाइस के गर्म होने की स्थितियां और उनका मतलब

• अगर डिवाइस की परफ़ॉर्मेंस पर तापमान का असर नहीं पड़ रहा है, तो:
  • 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 लागू करने की वजह से, इसकी कुछ सीमाएं हैं या इसके लिए कुछ अतिरिक्त ज़रूरी शर्तें हैं. इनकी सीमाएं और इन्हें इस्तेमाल करने का तरीका यहां दिया गया है:

• GetThermalHeadroom() एपीआई को बार-बार कॉल न करें. ऐसा करने पर, एपीआई 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.
      }
    }
  }

डायग्राम:

तीसरी इमेज.पुराने डिवाइसों पर Thermal API की सुविधा काम करती है या नहीं, यह पता लगाने के लिए इस्तेमाल किए जाने वाले अनुमानित तरीके का उदाहरण