थर्मल एपीआई

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

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

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

(झलक) Android 15 (DP1) - getThermalHeadroomThresholds()

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

गेम इंजन में आम तौर पर, रनटाइम परफ़ॉर्मेंस पैरामीटर होते हैं. इनसे, इंजन के डिवाइस पर डाले जाने वाले वर्कलोड में बदलाव किया जा सकता है. उदाहरण के लिए, इन पैरामीटर की मदद से, वर्क थ्रेड की संख्या, बड़े और छोटे कोर के लिए वर्क थ्रेड अफ़िनिटी, जीपीयू फ़िडेलिटी के विकल्प, और फ़्रेमबफ़र रिज़ॉल्यूशन सेट किए जा सकते हैं. Unity Engine में, गेम डेवलपर अडैप्टिव परफ़ॉर्मेंस प्लग इन का इस्तेमाल करके, क्वालिटी सेटिंग बदलकर, वर्कलोड में बदलाव कर सकते हैं. 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(10);
ALOGI("ThermalHeadroom in 10 sec: %f", thermal_headroom);

Java

float thermalHeadroom = powerManager.getThermalHeadroom(10);
Log.d("ADPF", "ThermalHeadroom in 10 sec: " + 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);

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

ध्यान दें: ऐसा हो सकता है कि कुछ डिवाइस अभी तक इस टेक्नोलॉजी के साथ पूरी तरह काम न करते हों और थर्मल हेडरूम और थ्रॉटल करने की स्थिति की असल वैल्यू के बावजूद, THERMAL_STATUS_NONE दिखाएं. इसलिए, हमारा सुझाव है कि आप इसके बजाय getThermalHeadroom का इस्तेमाल करें. इस समस्या का समाधान पाने के लिए, Thermal API की डिवाइस से जुड़ी सीमाएं देखें.

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

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

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

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

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 हो. ऐसे में, इस पर नज़र रखें और अगर हो सके, तो वर्कलोड कम करें

स्‍यूडोकोड:

  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 के काम करने की जानकारी देने के लिए, हेरिस्टिक का उदाहरण