कैमरे के एक्सटेंशन

डिवाइस बनाने वाली कंपनियां, तीसरे पक्ष के डेवलपर के लिए एक्सटेंशन उपलब्ध करा सकती हैं. जैसे, बोकेह, नाइट मोड, और एचडीआर. ये एक्सटेंशन, ओईएम वेंडर लाइब्रेरी की ओर से उपलब्ध कराए गए Camera Extensions इंटरफ़ेस के ज़रिए उपलब्ध कराए जा सकते हैं. डेवलपर, ओईएम वेंडर लाइब्रेरी में लागू किए गए एक्सटेंशन को ऐक्सेस करने के लिए, Camera2 Extensions API और CameraX Extensions API का इस्तेमाल कर सकते हैं.

Camera2 और CameraX, दोनों के साथ काम करने वाले एक्सटेंशन की सूची देखने के लिए, CameraX Extensions API पर जाएं. अगर आपको कोई एक्सटेंशन जोड़ना है, तो समस्या ट्रैकर में जाकर, गड़बड़ी की शिकायत करें.

इस पेज पर, डिवाइसों पर ओईएम वेंडर लाइब्रेरी को लागू करने और चालू करने का तरीका बताया गया है.

वास्तुकला

यहां दिए गए डायग्राम में, Camera Extensions इंटरफ़ेस या extensions-interface के आर्किटेक्चर के बारे में बताया गया है:

पहली इमेज. कैमरा एक्सटेंशन के आर्किटेक्चर का डायग्राम

डायग्राम में दिखाए गए तरीके से, कैमरा एक्सटेंशन के लिए आपको OEM वेंडर लाइब्रेरी से मिले extensions-interface को लागू करना होगा. आपकी ओईएम वेंडर लाइब्रेरी, दो एपीआई चालू करती है: CameraX Extensions API और Camera2 Extensions API. इनका इस्तेमाल, CameraX और Camera2 ऐप्लिकेशन करते हैं, ताकि वेंडर एक्सटेंशन को ऐक्सेस किया जा सके.

ओईएम वेंडर लाइब्रेरी लागू करना

ओईएम वेंडर लाइब्रेरी को लागू करने के लिए, camera-extensions-stub फ़ाइलों को सिस्टम लाइब्रेरी प्रोजेक्ट में कॉपी करें. इन फ़ाइलों से, Camera Extensions इंटरफ़ेस तय होता है.

camera-extensions-stub फ़ाइलों को इन कैटगरी में बांटा गया है:

ज़रूरी इंटरफ़ेस फ़ाइलें (इनमें बदलाव न करें)

• PreviewExtenderImpl.java
• ImageCaptureExtenderImpl.java
• ExtenderStateListener.java
• ProcessorImpl.java
• PreviewImageProcessorImpl.java
• CaptureProcessorImpl.java
• CaptureStageImpl.java
• RequestUpdateProcessorImpl.java
• ProcessResultImpl.java
• advanced/AdvancedExtenderImpl.java
• advanced/Camera2OutputConfigImpl.java
• advanced/Camera2SessionConfigImpl.java
• advanced/ImageProcessorImpl.java
• advanced/ImageReaderOutputConfigImpl.java
• advanced/ImageReferenceImpl.java
• advanced/MultiResolutionImageReaderOutputConfigImpl.java
• advanced/OutputSurfaceImpl.java
• advanced/RequestProcessorImpl.java
• advanced/SessionProcessorImpl.java
• advanced/SurfaceOutputConfigImpl.java

लागू करना ज़रूरी है (लागू करने का तरीका जोड़ें)

• ExtensionVersionImpl.java
• InitializerImpl.java

बोकेह एक्सटेंडर क्लास (अगर बोकेह एक्सटेंशन काम करता है, तो इसे लागू करें)

• BokehImageCaptureExtenderImpl.java
• BokehPreviewExtenderImpl.java
• advanced/BokehAdvancedExtenderImpl.java

रात में चलने वाली एक्सटेंडर क्लास (अगर नाइट एक्सटेंशन की सुविधा काम करती है, तो इसे लागू करें)

• NightImageCaptureExtenderImpl.java
• NightPreviewExtenderImpl.java
• advanced/NightAdvancedExtenderImpl.java

ऑटो एक्सटेंडर क्लास (अगर ऑटो एक्सटेंशन काम करता है, तो इसे लागू करें)

• AutoImageCaptureExtenderImpl.java
• AutoPreviewExtenderImpl.java
• advanced/AutoAdvancedExtenderImpl.java

एचडीआर एक्सटेंडर क्लास (अगर एचडीआर एक्सटेंशन काम करता है, तो इसे लागू करें)

• HdrImageCaptureExtenderImpl.java
• HdrPreviewExtenderImpl.java
• advanced/HdrAdvancedExtenderImpl.java

चेहरे की फ़ोटो क्वालिटी में सुधार करने की सुविधा के लिए एक्सटेंडर क्लास (अगर चेहरे की फ़ोटो क्वालिटी में सुधार करने की सुविधा के लिए एक्सटेंशन काम करता है, तो इसे लागू करें)

• BeautyImageCaptureExtenderImpl.java
• BeautyPreviewExtenderImpl.java
• advanced/BeautyAdvancedExtenderImpl.java

काम आने वाली ज़रूरी सेवाएं (ज़रूरी नहीं, इन्हें मिटाया जा सकता है)

• advanced/Camera2OutputConfigImplBuilder.java
• advanced/Camera2SessionConfigImplBuilder.java

हर एक्सटेंशन के लिए, आपको लागू करने का तरीका बताने की ज़रूरत नहीं है. अगर आपको एक्सटेंशन लागू नहीं करना है, तो isExtensionAvailable() को false पर सेट करें या उससे जुड़ी Extender क्लास हटाएं. Camera2 और CameraX एक्सटेंशन एपीआई, ऐप्लिकेशन को यह सूचना देते हैं कि एक्सटेंशन उपलब्ध नहीं है.

आइए, जानते हैं कि एक्सटेंशन को चालू करने के लिए, Camera2 और CameraX Extensions API, वेंडर लाइब्रेरी के साथ कैसे इंटरैक्ट करते हैं. इस डायग्राम में, नाइट मोड एक्सटेंशन का इस्तेमाल करके, एंड-टू-एंड फ़्लो दिखाया गया है:

दूसरी इमेज. नाइट एक्सटेंशन लागू करना

1. वर्शन की पुष्टि:

   Camera2/X, ExtensionVersionImpl.checkApiVersion() को कॉल करता है, ताकि यह पक्का किया जा सके कि ओईएम के लागू किए गए extensions-interface वर्शन, Camera2/X के साथ काम करने वाले वर्शन के साथ काम करते हैं.

2. वेंडर लाइब्रेरी को शुरू करना:

   InitializerImpl में एक init() तरीका होता है, जो वेंडर लाइब्रेरी को शुरू करता है. Camera2/X, Extender क्लास को ऐक्सेस करने से पहले, शुरू होने की प्रोसेस पूरी करता है.

3. Extender क्लास को इंस्टैंशिएट करें:

   यह एक्सटेंशन के लिए, Extender क्लास को इंस्टैंशिएट करता है. एक्सटेंडर दो तरह के होते हैं: बेसिक एक्सटेंडर और ऐडवांस एक्सटेंडर. आपको सभी एक्सटेंशन के लिए, एक एक्सटेंडर टाइप लागू करना होगा. ज़्यादा जानकारी के लिए, बेसिक एक्सटेंडर बनाम ऐडवांस एक्सटेंडर लेख पढ़ें.

   Camera2/X, Extender क्लास को इंस्टैंशिएट करता है और उनसे इंटरैक्ट करता है, ताकि जानकारी मिल सके और एक्सटेंशन चालू किया जा सके. किसी एक्सटेंशन के लिए, Camera2/X, Extender क्लास को कई बार इंस्टैंटिएट कर सकता है. इसलिए, कंस्ट्रक्टर या init() कॉल में भारी-भरकम इनिशियलाइज़ेशन न करें. कैमरा सेशन शुरू होने से ठीक पहले ही, ज़्यादा प्रोसेसिंग वाला काम करें. जैसे, जब बेसिक एक्सटेंडर में onInit() को कॉल किया जाता है या ऐडवांस एक्सटेंडर में initSession() को कॉल किया जाता है.

   नाइट एक्सटेंशन के लिए, बेसिक एक्सटेंडर टाइप के लिए इन एक्सटेंडर क्लास को इंस्टैंटिएट किया जाता है:

   • NightImageCaptureExtenderImpl.java
   • NightPreviewExtenderImpl.java

   साथ ही, अडवांस एक्सटेंडर टाइप के लिए:

   • NightAdvancedExtenderImpl.java

4. देखें कि एक्सटेंशन उपलब्ध है या नहीं:

   एक्सटेंशन चालू करने से पहले, isExtensionAvailable() यह जांच करता है कि एक्सटेंडर इंस्टेंस के ज़रिए, तय किए गए कैमरा आईडी पर एक्सटेंशन उपलब्ध है या नहीं.

5. कैमरे की जानकारी के साथ एक्सटेंडर को शुरू करें:

   Camera2/X, Extender इंस्टेंस पर init() को कॉल करता है और उसे कैमरा आईडी और CameraCharacteristics पास करता है.

6. क्वेरी की जानकारी:

   यह Extender क्लास को कॉल करता है, ताकि एक्सटेंशन चालू करने की तैयारी के दौरान, यह जानकारी वापस पाई जा सके. जैसे, काम करने वाले रिज़ॉल्यूशन, अनुमानित लेटेन्सी, और Extender से अनुरोध कुंजियां.

7. एक्सटेंडर पर एक्सटेंशन चालू करें:

   Extender क्लास, क्लास को चालू करने के लिए ज़रूरी सभी इंटरफ़ेस उपलब्ध कराती है. यह OEM को Camera2 पाइपलाइन में हुक करने का तरीका उपलब्ध कराता है. जैसे, कैप्चर करने के अनुरोध के पैरामीटर डालना या पोस्ट प्रोसेसर चालू करना.

   ऐडवांस एक्सटेंडर टाइप के लिए, Camera2/X, एक्सटेंशन चालू करने के लिए SessionProcessorImpl के साथ इंटरैक्ट करता है. Camera2/X, Extender पर createSessionProcessor() को कॉल करके SessionProcessorImpl इंस्टेंस को वापस पाता है.

यहां दिए गए सेक्शन में, एक्सटेंशन के फ़्लो के बारे में ज़्यादा जानकारी दी गई है.

वर्शन की पुष्टि करना

डिवाइस से ओईएम वेंडर लाइब्रेरी को रनटाइम पर लोड करते समय, Camera2/X यह पुष्टि करता है कि लाइब्रेरी, extensions-interface वर्शन के साथ काम करती है या नहीं. extensions-interface सिमेंटिक वर्शनिंग का इस्तेमाल करता है. उदाहरण के लिए, MAJOR.MINOR.PATCH, 1.1.0 या 1.2.0. हालांकि, वर्शन की पुष्टि के दौरान सिर्फ़ मुख्य और छोटे वर्शन का इस्तेमाल किया जाता है.

वर्शन की पुष्टि करने के लिए, Camera2/X, extensions-interface को कॉल करता है. इसके लिए, extensions-interface का इस्तेमाल किया जाता है.ExtensionVersionImpl.checkApiVersion() इसके बाद, Camera2/X, ओईएम लाइब्रेरी से मिले वर्शन का इस्तेमाल करके यह तय करता है कि एक्सटेंशन को चालू किया जा सकता है या नहीं. साथ ही, यह तय करता है कि एक्सटेंशन को किन सुविधाओं को चालू करना चाहिए.

मेजर वर्शन के साथ काम करने की सुविधा

अगर Camera2/X और वेंडर लाइब्रेरी के extension-interface के मुख्य वर्शन अलग-अलग हैं, तो इसे काम न करने वाला माना जाता है. साथ ही, एक्सटेंशन बंद हो जाता है.

पिछले वर्शन के साथ काम करने की सुविधा

जब तक मुख्य वर्शन एक जैसा होता है, तब तक Camera2/X यह पक्का करता है कि पिछले वर्शन के साथ काम करने की सुविधा, OEM वेंडर लाइब्रेरी के साथ काम करती है. ये लाइब्रेरी, extensions-interface के पिछले वर्शन के साथ बनाई गई हैं. उदाहरण के लिए, अगर Camera2/X extensions-interface 1.3.0 के साथ काम करता है, तो ओईएम वेंडर की वे लाइब्रेरी अब भी काम करेंगी जिनमें 1.0.0, 1.1.0, और 1.2.0 लागू किया गया है. इसका यह भी मतलब है कि वेंडर लाइब्रेरी का कोई वर्शन लागू करने के बाद, Camera2/X यह पक्का करता है कि लाइब्रेरी, आने वाले extension-interface वर्शन के साथ काम करती हो.

फ़ॉरवर्ड कंपैटिबिलिटी

वेंडर की नई extensions-interface लाइब्रेरी के साथ आगे की ओर काम करने की सुविधा, ओईएम पर निर्भर करती है. अगर आपको एक्सटेंशन लागू करने के लिए कुछ सुविधाओं की ज़रूरत है, तो हो सकता है कि आपको किसी वर्शन से एक्सटेंशन चालू करने हों. इस मामले में, Camera2/X लाइब्रेरी का वर्शन ज़रूरी शर्तों को पूरा करने पर, extensions-interface का काम करने वाला वर्शन वापस लाया जा सकता है. अगर Camera2/X वर्शन काम नहीं करते हैं, तो एक्सटेंशन बंद करने के लिए, 99.0.0 जैसे काम न करने वाले वर्शन को वापस लाया जा सकता है.

वेंडर लाइब्रेरी शुरू करना

ओईएम की लाइब्रेरी में लागू किए गए extensions-interface वर्शन की पुष्टि करने के बाद, Camera2/X, शुरू होने की प्रोसेस शुरू करता है. InitializerImpl.init() तरीके से, ओईएम लाइब्रेरी को यह सूचना मिलती है कि कोई ऐप्लिकेशन एक्सटेंशन का इस्तेमाल करने की कोशिश कर रहा है.

Camera2/X, ओईएम लाइब्रेरी को कोई और कॉल नहीं करता. हालांकि, वर्शन की जांच करने के लिए कॉल करता है. ऐसा तब तक होता है, जब तक ओईएम वेंडर लाइब्रेरी, OnExtensionsInitializedCallback.onSuccess() को कॉल करके यह सूचना नहीं देती कि शुरू करने की प्रोसेस पूरी हो गई है.

आपको extensions-interface 1.1.0 से InitializerImpl लागू करना होगा. अगर OEM वेंडर लाइब्रेरी, extensions-interface 1.0.0 को लागू करती है, तो Camera2/X, लाइब्रेरी शुरू करने वाले चरण को छोड़ देता है.

बेसिक एक्सटेंडर और ऐडवांस एक्सटेंडर में फ़र्क़

extensions-interface को दो तरह से लागू किया जा सकता है: बेसिक एक्सटेंडर और अडवांस एक्सटेंडर. ऐडवांस एक्सटेंडर, extensions-interface 1.2.0 से काम कर रहा है.

कैमरा HAL में इमेज प्रोसेस करने वाले एक्सटेंशन या YUV स्ट्रीम को प्रोसेस करने में सक्षम पोस्ट प्रोसेसर का इस्तेमाल करने वाले एक्सटेंशन के लिए, Basic Extender लागू करें.

उन एक्सटेंशन के लिए Advanced Extender लागू करें जिन्हें Camera2 स्ट्रीम कॉन्फ़िगरेशन को पसंद के मुताबिक बनाने और ज़रूरत के हिसाब से कैप्चर करने के अनुरोध भेजने की ज़रूरत होती है.

तुलना के लिए, यहां दी गई टेबल देखें:

ऐप्लिकेशन फ़्लो

यहां दी गई टेबल में, ऐप्लिकेशन के तीन तरह के फ़्लो और उनसे जुड़े Camera Extensions API कॉल दिखाए गए हैं. Camera2/X ये एपीआई उपलब्ध कराते हैं. हालांकि, आपको इन फ़्लो के लिए वेंडर लाइब्रेरी को सही तरीके से लागू करना होगा. इसके बारे में हम बाद के सेक्शन में ज़्यादा जानकारी देंगे.

बेसिक एक्सटेंडर

Basic Extender इंटरफ़ेस, कैमरा पाइपलाइन में कई जगहों पर हुक उपलब्ध कराता है. हर एक्सटेंशन टाइप के लिए, एक्सटेंडर क्लास होती हैं. ओईएम को इन्हें लागू करना होता है.

यहां दी गई टेबल में, एक्सटेंडर क्लास की सूची दी गई है. ओईएम को हर एक्सटेंशन के लिए इन्हें लागू करना होगा:

हमने इस उदाहरण में, PreviewExtenderImpl और ImageCaptureExtenderImpl को प्लेसहोल्डर के तौर पर इस्तेमाल किया है. इनकी जगह, उन फ़ाइलों के नाम डालें जिन्हें आपको लागू करना है.

बेसिक एक्सटेंडर में ये सुविधाएं उपलब्ध हैं:

• CameraCaptureSession ( onPresetSession) को कॉन्फ़िगर करते समय, सेशन पैरामीटर इंजेक्ट करें.
• आपको कैप्चर सेशन शुरू होने और बंद होने वाले इवेंट के बारे में सूचना देता है. साथ ही, HAL को सूचना देने के लिए एक ही अनुरोध भेजता है. इसमें, दिखाए गए पैरामीटर (onEnableSession,onDisableSession) शामिल होते हैं.
• अनुरोध के लिए कैप्चर पैरामीटर इंजेक्ट करें (PreviewExtenderImpl.getCaptureStage, ImageCaptureExtenderImpl.getCaptureStages).
• झलक और इमेज कैप्चर के लिए प्रोसेसर जोड़ें, जो YUV_420_888 स्ट्रीम को प्रोसेस कर सके.

आइए देखते हैं कि Camera2/X, ऊपर बताए गए तीन ऐप्लिकेशन फ़्लो को पूरा करने के लिए, extensions-interface को कैसे चालू करता है.

ऐप्लिकेशन फ़्लो 1: एक्सटेंशन की उपलब्धता की जांच करना

तीसरी इमेज. बेसिक एक्सटेंडर पर ऐप्लिकेशन फ़्लो 1

इस फ़्लो में, Camera2/X सीधे तौर पर PreviewExtenderImpl और ImageCaptureExtenderImpl, दोनों के isExtensionAvailable() तरीके को कॉल करता है. इसके लिए, वह init() को कॉल नहीं करता. एक्सटेंशन चालू करने के लिए, दोनों एक्सटेंडर क्लास को true वैल्यू दिखानी होगी.

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

ऐप्लिकेशन फ़्लो 2: क्वेरी की जानकारी

चौथी इमेज. बेसिक एक्सटेंडर पर ऐप्लिकेशन फ़्लो 2

एक्सटेंशन उपलब्ध है या नहीं, यह तय करने के बाद ऐप्लिकेशन को एक्सटेंशन चालू करने से पहले, यह जानकारी क्वेरी करनी चाहिए.

• अब भी कैप्चर करने में लगने वाले समय की रेंज का पता लगाएं: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange इससे, ऐप्लिकेशन के लिए कैप्चर करने में लगने वाले समय की रेंज मिलती है. इससे यह पता लगाया जा सकता है कि मौजूदा स्थिति में एक्सटेंशन को चालू करना सही है या नहीं.

• झलक और कैप्चर करने के लिए इस्तेमाल किए जा सकने वाले साइज़: ImageCaptureExtenderImpl.getSupportedResolutions और PreviewExtenderImpl.getSupportedResolutions, इमेज फ़ॉर्मैट की सूची और उन साइज़ की सूची दिखाता है जिनका इस्तेमाल, सर्फ़ेस फ़ॉर्मैट और साइज़ के लिए किया जा सकता है.

• अनुरोध और नतीजे की कुंजियों के लिए सहायता: Camera2/X, कैप्चर करने के अनुरोध और नतीजे की कुंजियों को लागू करने के लिए, यहां दिए गए तरीकों का इस्तेमाल करता है:

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
  • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X, ज़्यादा जानकारी के लिए क्वेरी करने से पहले, इन Extender क्लास पर हमेशा init() को कॉल करता है.

ऐप्लिकेशन फ़्लो 3: एक्सटेंशन चालू होने पर झलक देखना/अब भी कैप्चर करना (एचएएल लागू करना)

पांचवीं इमेज. Basic Extender पर ऐप्लिकेशन फ़्लो 3

ऊपर दिए गए डायग्राम में, बिना किसी प्रोसेसर के एक्सटेंशन की मदद से, झलक देखने और फ़ोटो कैप्चर करने की सुविधा चालू करने का मुख्य फ़्लो दिखाया गया है. इसका मतलब है कि कैमरा HAL, एक्सटेंशन को प्रोसेस करता है.

इस फ़्लो में, Camera2/X पहले init() को और फिर onInit को कॉल करता है. इससे आपको सूचना मिलती है कि तय किए गए एक्सटेंशन के साथ कैमरा सेशन शुरू होने वाला है. onInit() में, भारी-भरकम डेटा को प्रोसेस करने की सुविधा मिलती है.

CameraCaptureSession को कॉन्फ़िगर करते समय, Camera2/X, सेशन के पैरामीटर पाने के लिए onPresetSession को शुरू करता है. कैप्चर सेशन को कॉन्फ़िगर करने के बाद, Camera2/X, onEnableSession को शुरू करता है. इससे CaptureStageImpl का एक इंस्टेंस मिलता है, जिसमें कैप्चर पैरामीटर शामिल होते हैं. Camera2/X, कैप्चर करने के इन पैरामीटर के साथ तुरंत एक अनुरोध भेजता है, ताकि HAL को सूचना दी जा सके. इसी तरह, कैप्चर सेशन बंद होने से पहले, Camera2/X onDisableSession को शुरू करता है. इसके बाद, कैप्चर किए गए पैरामीटर के साथ एक अनुरोध भेजता है.

Camera2/X से ट्रिगर किए गए बार-बार किए जाने वाले अनुरोध में, PreviewExtenderImpl.getCaptureStage() से मिले अनुरोध पैरामीटर शामिल होते हैं. इसके अलावा, स्टिल इमेज कैप्चर करने के अनुरोध में, ImageCaptureExtenderImpl.getCaptureStages() से मिले पैरामीटर शामिल होते हैं.

आखिर में, Camera2/X, कैमरा सेशन खत्म होने के बाद onDeInit() को कॉल करता है. onDeinit() में जाकर, संसाधनों को रिलीज़ किया जा सकता है.

प्रीव्यू प्रोसेसर

कैमरा HAL के अलावा, प्रोसेसर में भी एक्सटेंशन लागू किए जा सकते हैं.

प्रोसेसर का टाइप बताने के लिए, PreviewExtenderImpl.getProcessorType एट्रिब्यूट का इस्तेमाल करें. इसके बारे में यहां बताया गया है:

• PROCESSOR_TYPE_NONE: कोई प्रोसेसर नहीं है. इमेज को कैमरा HAL में प्रोसेस किया जाता है.

• PROCESSOR_TYPE_REQUEST_UPDATE_ONLY: प्रोसेसर टाइप की मदद से, TotalCaptureResult के आधार पर, बार-बार किए जाने वाले अनुरोध को नए कैप्चर अनुरोध पैरामीटर के साथ अपडेट किया जा सकता है.

  PreviewExtenderImpl.getProcessor को RequestUpdateProcessorImpl का एक ऐसा इंस्टेंस वापस करना होगा जो TotalCaptureResult इंस्टेंस को प्रोसेस करता है. साथ ही, बार-बार किए जाने वाले अनुरोध को अपडेट करने के लिए, CaptureStageImpl इंस्टेंस वापस करता है. PreviewExtenderImpl.getCaptureStage() में प्रोसेसिंग का नतीजा भी दिखना चाहिए और यह सबसे नया CaptureStageImpl दिखाना चाहिए.

• PROCESSOR_TYPE_IMAGE_PROCESSOR: इस टाइप की मदद से, YUV_420_888 इमेज को प्रोसेस करने के लिए प्रोसेसर लागू किया जा सकता है. साथ ही, आउटपुट को PRIVATE पर लिखा जा सकता है.

  आपको PreviewExtenderImpl.getProcessor में, PreviewImageProcessorImpl इंस्टेंस को लागू करना होगा और उसे वापस भेजना होगा. प्रोसेसर, YUV_420_888 इनपुट इमेज को प्रोसेस करने के लिए ज़िम्मेदार होता है. इसे आउटपुट को झलक के PRIVATE फ़ॉर्मैट में लिखना चाहिए. Camera2/X, झलक देखने के लिए CameraCaptureSession को कॉन्फ़िगर करने के लिए, PRIVATE के बजाय YUV_420_888 सरफ़ेस का इस्तेमाल करता है.

  फ़्लो के बारे में जानने के लिए, यह इमेज देखें:

छठी इमेज. PreviewImageProcessorImpl की झलक देखने का तरीका

PreviewImageProcessorImpl इंटरफ़ेस, ProcessImpl को बढ़ाता है और इसमें तीन अहम तरीके होते हैं:

• onOutputSurface(Surface surface, int imageFormat) प्रोसेसर के लिए आउटपुट सरफेस सेट करता है. PreviewImageProcessorImpl के लिए, imageFormat एक पिक्सल फ़ॉर्मैट है, जैसे कि PixelFormat.RGBA_8888.

• onResolutionUpdate(Size size) से इनपुट इमेज का साइज़ सेट किया जाता है.

• onImageFormatUpdate(int imageFormat) इनपुट इमेज का फ़ॉर्मैट सेट करता है. फ़िलहाल, इसे सिर्फ़ YUV_420_888 पर सेट किया जा सकता है.

इमेज कैप्चर करने वाला प्रोसेसर

स्टिल कैप्चर के लिए, ImageCaptureExtenderImpl.getCaptureProcessor का इस्तेमाल करके CaptureProcessorImpl इंस्टेंस को वापस भेजकर, प्रोसेसर लागू किया जा सकता है. प्रोसेसर, कैप्चर की गई YUV_420_888 इमेज और TotalCaptureResult इंस्टेंस की सूची को प्रोसेस करने के लिए ज़िम्मेदार होता है. साथ ही, वह आउटपुट को YUV_420_888 प्लैटफ़ॉर्म पर लिखता है.

आपके पास यह मानने की वजह है कि स्टिल कैप्चर का अनुरोध भेजने से पहले, झलक दिखाने की सुविधा चालू है और काम कर रही है.

नीचे दिए गए डायग्राम में फ़्लो देखें:

सातवीं इमेज. अब भी CaptureProcessorImpl के साथ कैप्चर फ़्लो

1. Camera2/X, फ़ोटो कैप्चर करने के लिए YUV_420_888 फ़ॉर्मैट वाले सर्फ़ेस का इस्तेमाल करता है, ताकि कैप्चर सेशन को कॉन्फ़िगर किया जा सके. Camera2/X, CaptureProcessorImpl को तैयार करता है. इसके लिए, वह इन फ़ंक्शन को कॉल करता है:

   • CaptureProcessorImpl.onImageFormatUpdate() में YUV_420_888 की सदस्यता लें.
   • CaptureProcessorImpl.onResolutionUpdate() के साथ इनपुट इमेज का साइज़.
   • CaptureProcessorImpl.onOutputSurface() के साथ आउटपुट YUV_420_888 सरफ़ेस.

2. ImageCaptureExtenderImpl.getCaptureStages, CaptureStageImpl की सूची दिखाता है. इसमें हर एलिमेंट, CaptureRequest इंस्टेंस पर मैप होता है. इसमें Camera2/X से भेजे गए कैप्चर पैरामीटर होते हैं. उदाहरण के लिए, अगर यह तीन CaptureStageImpl इंस्टेंस की सूची दिखाता है, तो Camera2/X, captureBurst एपीआई का इस्तेमाल करके, कैप्चर के पैरामीटर के साथ तीन कैप्चर अनुरोध भेजता है.

3. मिली हुई इमेज और TotalCaptureResult इंस्टेंस को एक साथ बंडल किया जाता है. इसके बाद, इन्हें प्रोसेस करने के लिए CaptureProcessorImpl को भेजा जाता है.

4. CaptureProcessorImpl, onOutputSurface() कॉल से तय किए गए आउटपुट सर्फ़ेस पर, नतीजे वाली इमेज (YUV_420_888 फ़ॉर्मैट) लिखता है. ज़रूरत पड़ने पर, Camera2/X इसे JPEG इमेज में बदल देता है.

अनुरोध की कुंजियों और नतीजों को कैप्चर करने की सुविधा

कैमरे की झलक देखने और फ़ोटो कैप्चर करने के अलावा, ऐप्लिकेशन ज़ूम करने, फ़्लैश के पैरामीटर सेट करने या टैप-टू-फ़ोकस सुविधा को ट्रिगर करने की सुविधा दे सकते हैं. ऐसा हो सकता है कि ये पैरामीटर, आपके एक्सटेंशन के साथ काम न करें.

extensions-interface 1.3.0 में ये तरीके जोड़े गए हैं, ताकि आप उन पैरामीटर को दिखा सकें जिन्हें लागू करने की सुविधा उपलब्ध है:

• ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys(), आपके लागू किए गए सिस्टम के साथ काम करने वाले कैप्चर अनुरोध की कुंजियां दिखाता है.
• ImageCaptureExtenderImpl.getAvailableCaptureResultKeys(), कैप्चर किए गए नतीजे की उन कुंजियों को दिखाता है जो कैप्चर किए गए नतीजे में शामिल हैं.

अगर कैमरा HAL एक्सटेंशन को प्रोसेस करता है, तो Camera2/X, CameraCaptureSession.CaptureCallback में कैप्चर किए गए नतीजे वापस पाता है. हालांकि, अगर प्रोसेसर लागू किया जाता है, तो Camera2/X, कैप्चर किए गए नतीजे ProcessResultImpl में वापस लाता है. इसे process() तरीके से PreviewImageProcessorImpl और CaptureProcessorImpl में पास किया जाता है. Camera2/X को ProcessResultImpl के ज़रिए, कैप्चर किए गए नतीजे की रिपोर्ट करने की ज़िम्मेदारी आपकी है.

उदाहरण के लिए, यहां CaptureProcessorImpl इंटरफ़ेस की परिभाषा दी गई है. extensions-interface 1.3.0 या इसके बाद के वर्शन में, दूसरे process() कॉल को इस तरह से शुरू किया जाता है:

Interface CaptureProcessorImpl extends ProcessorImpl {
    // invoked when extensions-interface version < 1.3.0
    void process(Map<Integer, Pair<Image, TotalCaptureResult>> results);
    // invoked when extensions-interface version >= 1.3.0
    void process(Map<Integer, Pair<Image, TotalCaptureResult>> results,
            ProcessResultImpl resultCallback, Executor executor);
}

कैमरे की सामान्य कार्रवाइयों, जैसे कि ज़ूम करना, फ़ोकस करने के लिए टैप करना, फ़्लैश, और एक्सपोज़र को कम या ज़्यादा करने के लिए, हम सुझाव देते हैं कि कैप्चर करने के अनुरोध और कैप्चर किए गए नतीजे, दोनों के लिए इन कुंजियों का इस्तेमाल किया जाए:

• ज़ूम करें:
  • CaptureRequest#CONTROL_ZOOM_RATIO
  • CaptureRequest#SCALER_CROP_REGION
• टैप करके फ़ोकस करने की सुविधा:
  • CaptureRequest#CONTROL_AF_MODE
  • CaptureRequest#CONTROL_AF_TRIGGER
  • CaptureRequest#CONTROL_AF_REGIONS
  • CaptureRequest#CONTROL_AE_REGIONS
  • CaptureRequest#CONTROL_AWB_REGIONS
• फ़्लैश:
  • CaptureRequest#CONTROL_AE_MODE
  • CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
  • CaptureRequest#FLASH_MODE
• एक्सपोज़र कंपंसेशन:
  • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

1.2.0 या इससे पहले के वर्शन लागू करने वाले बेसिक एक्सटेंडर के लिए, CameraX Extensions API ऊपर दी गई सभी कुंजियों के साथ काम करता है. extensions-interface 1.3.0 के लिए, CameraX और Camera2, दोनों ही वापस की गई सूची का पालन करते हैं. साथ ही, इसमें मौजूद कुंजियों के साथ ही काम करते हैं. उदाहरण के लिए, अगर आपको 1.3.0 वर्शन में सिर्फ़ CaptureRequest#CONTROL_ZOOM_RATIO और CaptureRequest#SCALER_CROP_REGION को वापस लाना है, तो इसका मतलब है कि ऐप्लिकेशन के लिए सिर्फ़ ज़ूम करने की सुविधा काम करेगी. वहीं, टैप करके फ़ोकस करने, फ़्लैश, और एक्सपोज़र को कम या ज़्यादा करने की सुविधा काम नहीं करेगी.

ऐडवांस एक्सटेंडर

ऐडवांस एक्सटेंडर, Camera2 API पर आधारित वेंडर के ज़रिए लागू किया जाने वाला एक तरीका है. इस एक्सटेंडर टाइप को extensions-interface 1.2.0 में जोड़ा गया था. डिवाइस बनाने वाली कंपनी के हिसाब से, एक्सटेंशन को ऐप्लिकेशन लेयर में लागू किया जा सकता है. यह इन बातों पर निर्भर करता है:

• स्ट्रीम को पसंद के मुताबिक कॉन्फ़िगर करना: रॉ स्ट्रीम जैसी कस्टम स्ट्रीम कॉन्फ़िगर करें या अलग-अलग फ़िज़िकल कैमरा आईडी के लिए एक से ज़्यादा स्ट्रीम बनाएं.

• Camera2 अनुरोध भेजने की सुविधा: यह सुविधा, जटिल इंटरैक्शन लॉजिक के साथ काम करती है. यह पिछले अनुरोधों के नतीजों के आधार पर, पैरामीटर के साथ कैप्चर करने के अनुरोध भेज सकती है.

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

लागू करने के लिए फ़ाइलें

ऐडवांस एक्सटेंडर के साथ काम करने वाले वर्शन पर स्विच करने के लिए, ExtensionVersionImpl में मौजूद isAdvancedExtenderImplemented() तरीके को true वैल्यू दिखानी होगी. हर तरह के एक्सटेंशन के लिए, ओईएम को एक्सटेंडर क्लास लागू करनी होंगी. ऐडवांस एक्सटेंडर को लागू करने वाली फ़ाइलें, ऐडवांस पैकेज में मौजूद होती हैं.

हमने यहां दिए गए उदाहरण में, AdvancedExtenderImpl को प्लेसहोल्डर के तौर पर इस्तेमाल किया है. इसे उस एक्सटेंशन के एक्सटेंडर फ़ाइल के नाम से बदलें जिसे आपको लागू करना है.

आइए देखते हैं कि Camera2/X, तीन ऐप्लिकेशन फ़्लो को पूरा करने के लिए extensions-interface को कैसे चालू करता है.

ऐप्लिकेशन का पहला फ़्लो: एक्सटेंशन की उपलब्धता की जांच करना

आठवीं इमेज. ऐडवांस एक्सटेंडर पर ऐप्लिकेशन फ़्लो 1

सबसे पहले, ऐप्लिकेशन यह जांच करता है कि दिया गया एक्सटेंशन काम करता है या नहीं.

ऐप्लिकेशन फ़्लो 2: क्वेरी की जानकारी

नौवीं इमेज. ऐडवांस एक्सटेंडर पर ऐप्लिकेशन फ़्लो 2

AdvancedExtenderImpl.init() को कॉल करने के बाद, ऐप्लिकेशन AdvancedExtenderImpl पर मौजूद इस जानकारी के बारे में क्वेरी कर सकता है:

• अब भी कैप्चर होने में लगने वाला अनुमानित समय: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() यह कैप्चर होने में लगने वाले समय की रेंज दिखाता है. इससे ऐप्लिकेशन यह तय कर पाता है कि मौजूदा स्थिति में एक्सटेंशन को चालू करना सही है या नहीं.

• झलक देखने और फ़ोटो कैप्चर करने के लिए, काम करने वाले रिज़ॉल्यूशन:

  • AdvancedExtenderImpl.getSupportedPreviewOutputResolutions(), इमेज फ़ॉर्मैट का एक मैप दिखाता है. इसमें, इमेज के उन साइज़ की सूची होती है जो प्रीव्यू दिखाने वाले फ़ॉर्मैट और साइज़ के साथ काम करते हैं. ओईएम को कम से कम PRIVATE फ़ॉर्मैट के साथ काम करना चाहिए.

  • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions(), फ़ोटो कैप्चर करने के लिए इस्तेमाल की जा सकने वाली सतह के लिए, काम करने वाले फ़ॉर्मैट और साइज़ दिखाता है. OEM को JPEG और YUV_420_888, दोनों फ़ॉर्मैट में आउटपुट देना होगा.

  • AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions(), इमेज का विश्लेषण करने के लिए, अतिरिक्त YUV_420_888 स्ट्रीम के लिए काम करने वाले साइज़ दिखाता है. अगर इमेज विश्लेषण के लिए YUV सर्फ़ेस काम नहीं करता है, तो getSupportedYuvAnalysisResolutions() को null या खाली सूची दिखानी चाहिए.

• कैप्चर के अनुरोध के लिए उपलब्ध कुंजियां/नतीजे (extensions-interface 1.3.0 में जोड़े गए): Camera2/X, कैप्चर के अनुरोध के लिए उपलब्ध कुंजियां और नतीजे की कुंजियां पाने के लिए, आपके लागू किए गए कोड में ये तरीके इस्तेमाल करता है:

  • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
  • AdvancedExtenderImpl.getAvailableCaptureResultKeys

ज़्यादा जानकारी के लिए, कैप्चर अनुरोध की कुंजियों और नतीजों के बारे में जानकारी लेख पढ़ें.

ऐप्लिकेशन फ़्लो 3: एक्सटेंशन चालू होने पर, झलक देखना/अब भी कैप्चर करना

दसवीं इमेज. ऐडवांस एक्सटेंडर पर ऐप्लिकेशन फ़्लो 3

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

1. SessionProcessorImpl instance

   ऐडवांस एक्सटेंडर को मुख्य तौर पर SessionProcessorImpl में लागू किया जाता है. यह कस्टम सेशन कॉन्फ़िगरेशन उपलब्ध कराने और कैप्चर अनुरोध भेजने के लिए ज़िम्मेदार होता है, ताकि झलक और कैप्चर अनुरोध शुरू किया जा सके. AdvancedExtenderImpl.createSessionProcessor() को SessionProcessorImpl इंस्टेंस वापस करने के लिए शुरू किया जाता है.

2. initSession

   SessionProcessorImpl.initSession() एक्सटेंशन के लिए सेशन शुरू करता है. यहां आपको संसाधन असाइन करने होते हैं. साथ ही, CameraCaptureSession तैयार करने के लिए, सेशन कॉन्फ़िगरेशन वापस करना होता है.

   इनपुट पैरामीटर के लिए, Camera2/X, आउटपुट सर्फ़ेस कॉन्फ़िगरेशन तय करता है. ये कॉन्फ़िगरेशन, झलक देखने, फ़ोटो कैप्चर करने, और YUV इमेज का विश्लेषण करने के लिए होते हैं. हालांकि, YUV इमेज का विश्लेषण करना ज़रूरी नहीं है. इस आउटपुट सरफ़ेस कॉन्फ़िगरेशन (OutputSurfaceImpl) में सरफ़ेस, साइज़, और इमेज फ़ॉर्मैट शामिल होता है. इन्हें AdvancedExtenderImpl में इन तरीकों से वापस पाया जाता है:

   • getSupportedPreviewOutputResolutions()
   • getSupportedCaptureOutputResolutions()
   • getSupportedYuvAnalysisResolutions()

   आपको Camera2SessionConfigImpl इंस्टेंस वापस करना होगा. इसमें Camera2OutputConfigImpl इंस्टेंस की सूची और CameraCaptureSession को कॉन्फ़िगर करने के लिए इस्तेमाल किए गए सेशन पैरामीटर शामिल होते हैं. Camera2/X से पास की गई आउटपुट सतहों पर, कैमरे की सही इमेज आउटपुट करने की ज़िम्मेदारी आपकी है. आउटपुट चालू करने के कुछ विकल्प यहां दिए गए हैं:

   • कैमरा एचएएल में प्रोसेसिंग: SurfaceOutputConfigImpl लागू करके, आउटपुट सर्फ़ेस को सीधे CameraCaptureSession में जोड़ा जा सकता है. इससे, कैमरे की पाइपलाइन को आउटपुट देने वाली सतह कॉन्फ़िगर होती है. साथ ही, कैमरा HAL को इमेज प्रोसेस करने की अनुमति मिलती है.

   • इंटरमीडिएट ImageReader फ़ॉर्मैट (रॉ, YUV वगैरह) में प्रोसेसिंग: ImageReaderOutputConfigImpl इंस्टेंस के साथ CameraCaptureSession में इंटरमीडिएट ImageReader फ़ॉर्मैट जोड़ें.

     आपको इंटरमीडिएट इमेज को प्रोसेस करना होगा और नतीजे की इमेज को आउटपुट सर्फ़ेस पर लिखना होगा.

   • Camera2 की सतह शेयर करने की सुविधा का इस्तेमाल करना: किसी अन्य Camera2OutputConfigImpl इंस्टेंस के getSurfaceSharingOutputConfigs() तरीके में कोई भी Camera2OutputConfigImpl इंस्टेंस जोड़कर, किसी अन्य सतह के साथ सतह शेयर करने की सुविधा का इस्तेमाल करें. सरफ़ेस का फ़ॉर्मैट और साइज़ एक जैसा होना चाहिए.

   सभी Camera2OutputConfigImpl, जिनमें SurfaceOutputConfigImpl और ImageReaderOutputConfigImpl शामिल हैं, का एक यूनीक आईडी (getId()) होना चाहिए. इसका इस्तेमाल, टारगेट सरफेस के बारे में बताने और ImageReaderOutputConfigImpl से इमेज पाने के लिए किया जाता है.

3. onCaptureSessionStart और RequestProcessorImpl

   जब CameraCaptureSession शुरू होता है और कैमरा फ़्रेमवर्क onConfigured() को शुरू करता है, तब Camera2/X, Camera2 के अनुरोध रैपर RequestProcessImpl के साथ SessionProcessorImpl.onCaptureSessionStart() को शुरू करता है. Camera2/X, RequestProcessImpl को लागू करता है. इससे, कैप्चर करने के अनुरोधों को पूरा किया जा सकता है. साथ ही, अगर ImageReaderOutputConfigImpl का इस्तेमाल किया जाता है, तो इमेज वापस पाई जा सकती हैं.

   अनुरोधों को पूरा करने के मामले में, RequestProcessImpl एपीआई, Camera2 CameraCaptureSession एपीआई के जैसे ही होते हैं. इनमें ये अंतर हैं:

   • टारगेट सरफेस, Camera2OutputConfigImpl इंस्टेंस के आईडी से तय होता है.
   • ImageReader की इमेज वापस लाने की सुविधा.

   इमेज पाने के लिए, ImageProcessorImpl इंस्टेंस को रजिस्टर करने के लिए, दिए गए Camera2OutputConfigImpl आईडी के साथ RequestProcessorImpl.setImageProcessor() पर कॉल करें.

   Camera2/X कॉल के बाद, RequestProcessImpl इंस्टेंस अमान्य हो जाता है SessionProcessorImpl.onCaptureSessionEnd().

4. झलक देखना शुरू करें और फ़ोटो लें

   ऐडवांस एक्सटेंडर को लागू करने पर, RequestProcessorImpl इंटरफ़ेस के ज़रिए कैप्चर करने के अनुरोध भेजे जा सकते हैं. Camera2/X, आपको झलक देखने के लिए बार-बार किए जाने वाले अनुरोध या स्टिल कैप्चर करने के क्रम को शुरू करने के लिए सूचना देता है. इसके लिए, SessionProcessorImpl#startRepeating और SessionProcessorImpl#startCapture को कॉल किया जाता है. आपको इन पूर्वावलोकन और स्टिल-कैप्चर के अनुरोधों को पूरा करने के लिए, कैप्चर करने के अनुरोध भेजने चाहिए.

   Camera2/X, SessionProcessorImpl#setParameters के ज़रिए कैप्चर अनुरोध पैरामीटर भी सेट करता है. अगर पैरामीटर काम करते हैं, तो आपको दोहराए जाने वाले और एक बार किए जाने वाले अनुरोधों, दोनों पर ये अनुरोध पैरामीटर सेट करने होंगे.

   आपको कम से कम CaptureRequest.JPEG_ORIENTATION और CaptureRequest.JPEG_QUALITY को सपोर्ट करना होगा. extensions-interface 1.3.0, अनुरोध और नतीजे के कुंजियों के साथ काम करता है. इन्हें इन तरीकों से दिखाया जाता है:

   • AdvancedExtenderImpl.getAvailableCaptureRequestKeys()
   • AdvancedExtenderImpl.getAvailableCaptureResultKeys()

   जब डेवलपर, getAvailableCaptureRequestKeys सूची में कुंजियां सेट करते हैं, तो आपको पैरामीटर चालू करने होंगे. साथ ही, यह पक्का करना होगा कि कैप्चर किए गए नतीजे में, getAvailableCaptureResultKeys सूची में मौजूद कुंजियां शामिल हों.

5. startTrigger

   SessionProcessorImpl.startTrigger() का इस्तेमाल, ट्रिगर शुरू करने के लिए किया जाता है. जैसे, CaptureRequest.CONTROL_AF_TRIGGER और CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER. AdvancedExtenderImpl.getAvailableCaptureRequestKeys() में जिन कैप्चर अनुरोध कुंजियों का विज्ञापन नहीं किया गया है उन्हें अनदेखा किया जा सकता है.

   startTrigger(), extensions-interface 1.3.0 से काम करता है. इससे ऐप्लिकेशन, एक्सटेंशन के साथ टैप-टू-फ़ोकस और फ़्लैश की सुविधा लागू कर पाते हैं.

6. खाली करने के लिए जगह

   कैप्चर सेशन खत्म करते समय, SessionProcessorImpl.onCaptureSessionEnd() को CameraCaptureSession बंद करने से पहले शुरू किया जाता है. कैप्चर सेशन बंद होने के बाद, deInitSession() डेटा को मिटा देता है.

झलक देखने, इमेज कैप्चर करने, और इमेज का विश्लेषण करने की सुविधा

आपको झलक और अब भी कैप्चर किए जा रहे इस्तेमाल के उदाहरण, दोनों के लिए एक्सटेंशन लागू करना चाहिए. हालांकि, अगर झलक को आसानी से दिखाने में ज़्यादा समय लग रहा है, तो सिर्फ़ स्टिल कैप्चर के लिए एक्सटेंशन लागू किया जा सकता है.

बेसिक एक्सटेंडर टाइप के लिए, झलक के लिए एक्सटेंशन चालू करने के बावजूद, आपको दिए गए एक्सटेंशन के लिए ImageCaptureExtenderImpl और PreviewExtenderImpl, दोनों को लागू करना होगा. अक्सर, कोई ऐप्लिकेशन इमेज कॉन्टेंट का विश्लेषण करने के लिए, YUV स्ट्रीम का इस्तेमाल करता है. जैसे, क्यूआर कोड या टेक्स्ट ढूंढना. इस इस्तेमाल के उदाहरण को बेहतर तरीके से सपोर्ट करने के लिए, आपको इन स्ट्रीम को एक साथ इस्तेमाल करने की सुविधा देनी चाहिए: झलक, स्टिल कैप्चर, और YUV_420_888 स्ट्रीम. इससे CameraCaptureSession को कॉन्फ़िगर किया जा सकेगा. इसका मतलब है कि अगर आपने प्रोसेसर लागू किया है, तो आपको तीन YUV_420_888 स्ट्रीम के कॉम्बिनेशन वाली स्ट्रीम के साथ काम करना होगा.

ऐडवांस एक्सटेंडर के लिए, Camera2/X, SessionProcessorImpl.initSession() कॉल को तीन आउटपुट सर्फ़ेस पास करता है. ये आउटपुट सर्फ़ेस, क्रमशः झलक देखने, इमेज कैप्चर करने, और इमेज का विश्लेषण करने के लिए हैं. आपको यह पक्का करना होगा कि प्रीव्यू और स्टिल कैप्चर आउटपुट सर्फ़ेस पर मान्य आउटपुट दिख रहा हो. हालांकि, इमेज विश्लेषण के आउटपुट सर्फ़ेस के लिए, पक्का करें कि यह सिर्फ़ तब काम कर रहा हो, जब यह शून्य न हो. अगर आपका इंटिग्रेशन, इमेज विश्लेषण स्ट्रीम के साथ काम नहीं करता है, तो AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() में खाली सूची दिखाई जा सकती है. इससे यह पक्का होता है कि SessionProcessorImpl.initSession() में इमेज विश्लेषण का आउटपुट हमेशा शून्य होता है.

वीडियो कैप्चर करने की सुविधा

कैमरा एक्सटेंशन का मौजूदा आर्किटेक्चर, सिर्फ़ झलक देखने और फ़ोटो कैप्चर करने के लिए काम करता है. हम वीडियो रिकॉर्ड करने के लिए, MediaCodec या MediaRecorder प्लैटफ़ॉर्म पर एक्सटेंशन चालू करने की सुविधा नहीं देते. हालांकि, ऐप्लिकेशन के लिए प्रीव्यू आउटपुट को रिकॉर्ड करना मुमकिन है.

MediaCodec और MediaRecorder प्लैटफ़ॉर्म पर इस सुविधा के काम करने की जांच की जा रही है.

एक्सटेंशन के हिसाब से मेटाडेटा

Android 14 और इसके बाद के वर्शन के लिए, एक्सटेंशन के हिसाब से मेटाडेटा उपलब्ध होता है. इससे कैमरा एक्सटेंशन क्लाइंट, एक्सटेंशन के हिसाब से कैप्चर करने के अनुरोध की सेटिंग सेट कर सकते हैं और नतीजे पा सकते हैं. खास तौर पर, कैमरा एक्सटेंशन क्लाइंट, एक्सटेंशन की परफ़ॉर्मेंस को कंट्रोल करने के लिए EXTENSION_STRENGTH कैप्चर अनुरोध पैरामीटर का इस्तेमाल कर सकते हैं. साथ ही, चालू किए गए एक्सटेंशन टाइप के बारे में बताने के लिए EXTENSION_CURRENT_TYPE कैप्चर नतीजे का इस्तेमाल कर सकते हैं.

अनुरोधों को कैप्चर करना

EXTENSION_STRENGTH कैप्चर अनुरोध पैरामीटर, एक्सटेंशन के पोस्ट-प्रोसेसिंग इफ़ेक्ट की इंटेंसिटी को कंट्रोल करता है. अगर क्लाइंट ने इस पैरामीटर को साफ़ तौर पर सेट नहीं किया है, तो कैप्चर के नतीजे में डिफ़ॉल्ट स्ट्रेंथ वैल्यू शामिल होती है. इस पैरामीटर को इन एक्सटेंशन टाइप के लिए इस तरह लागू किया जा सकता है:

• BOKEH: इससे धुंधलेपन की मात्रा को कंट्रोल किया जाता है.
• HDR और NIGHT: इससे यह कंट्रोल किया जाता है कि कितनी इमेज को एक साथ मर्ज किया जाए और फ़ाइनल इमेज की चमक कितनी हो.
• FACE_RETOUCH: इससे, कॉस्मेटिक इफ़ेक्ट और त्वचा को स्मूद करने की सुविधा को कंट्रोल किया जाता है.

EXTENSION_STRENGTH पैरामीटर के लिए, 0 से 100 के बीच की वैल्यू इस्तेमाल की जा सकती है. 0 का मतलब है कि एक्सटेंशन प्रोसेसिंग नहीं की गई है या सिर्फ़ पासथ्रू किया गया है. वहीं, 100 का मतलब है कि प्रोसेसिंग इफ़ेक्ट के लिए एक्सटेंशन की सबसे ज़्यादा वैल्यू इस्तेमाल की गई है.

EXTENSION_STRENGTH के लिए सहायता जोड़ने के लिए, एक्सटेंशन लाइब्रेरी इंटरफ़ेस के वर्शन 1.3.0 में पेश किए गए, वेंडर के हिसाब से पैरामीटर एपीआई का इस्तेमाल करें. ज़्यादा जानकारी के लिए, getAvailableCaptureRequestKeys() देखें.

नतीजे कैप्चर करना

EXTENSION_CURRENT_TYPE कैप्चर करने के नतीजे से, एक्सटेंशन लागू करने की प्रोसेस में शामिल क्लाइंट को चालू एक्सटेंशन टाइप के बारे में सूचना मिलती है.

AUTO टाइप का इस्तेमाल करने वाले एक्सटेंशन, सीन की स्थितियों के आधार पर एक्सटेंशन टाइप के बीच डाइनैमिक तरीके से स्विच करते हैं. जैसे, HDR और NIGHT. इसलिए, कैमरा एक्सटेंशन ऐप्लिकेशन, EXTENSION_CURRENT_TYPE का इस्तेमाल करके AUTO एक्सटेंशन से चुने गए मौजूदा एक्सटेंशन के बारे में जानकारी दिखा सकते हैं.

रीयल-टाइम में फ़ोटो कैप्चर करने में लगने वाले समय का अनुमान

Android 14 और इसके बाद के वर्शन पर, कैमरा एक्सटेंशन क्लाइंट, सीन और आस-पास की स्थितियों के आधार पर, रीयल-टाइम में इमेज कैप्चर करने में लगने वाले समय का अनुमान लगाने के लिए क्वेरी कर सकते हैं. इसके लिए, उन्हें getRealtimeStillCaptureLatency() का इस्तेमाल करना होगा. इस तरीके से, स्टैटिक getEstimatedCaptureLatencyRangeMillis() तरीके की तुलना में ज़्यादा सटीक अनुमान मिलते हैं. लेटेंसी के अनुमान के आधार पर, ऐप्लिकेशन एक्सटेंशन प्रोसेसिंग को छोड़ने का फ़ैसला कर सकते हैं. इसके अलावा, वे उपयोगकर्ताओं को लंबे समय तक चलने वाली कार्रवाई के बारे में सूचना देने के लिए, कोई इंडिकेटर दिखा सकते हैं.

CameraExtensionSession.StillCaptureLatency latency;

latency = extensionSession.getRealtimeStillCaptureLatency();

// The capture latency from ExtensionCaptureCallback#onCaptureStarted() until ExtensionCaptureCallback#onCaptureProcessStarted().

latency.getCaptureLatency();

// The processing latency from  ExtensionCaptureCallback#onCaptureProcessStarted() until  the processed frame returns to the client.

latency.getProcessingLatency();

रीयल-टाइम में फ़ोटो कैप्चर करने में लगने वाले समय का अनुमान लगाने की सुविधा के लिए, ये काम करें:

• बुनियादी एक्सटेंशन: ImageCaptureExtenderImpl.getRealtimeCaptureLatency()
• ऐडवांस एक्सटेंशन: SessionProcessorImpl.getRealtimeCaptureLatency

कैप्चर करने की प्रोसेस की प्रोग्रेस के कॉलबैक

Android 14 और इसके बाद के वर्शन पर, कैमरा एक्सटेंशन क्लाइंट को, लंबे समय तक चलने वाली स्टिल कैप्चर प्रोसेसिंग की प्रोग्रेस के लिए कॉलबैक मिल सकते हैं. ऐप्लिकेशन, उपयोगकर्ताओं को मौजूदा प्रोग्रेस दिखा सकते हैं, ताकि उन्हें बेहतर अनुभव मिल सके.

ऐप्लिकेशन इस सुविधा को इंटिग्रेट करने के लिए, यहां दिए गए कोड का इस्तेमाल कर सकते हैं:

import android.hardware.camera2.CameraExtensionSession.
ExtensionCaptureCallback;

{
…
  class AppCallbackImpl extends ExtensionCaptureCallback {
…
    @Override
    public void onCaptureProcessProgressed(
      @NonNull CameraExtensionSession session,
      @NonNull CaptureRequest request,
      @IntRange(from = 0, to = 100) int progress) {
      // Update app UI with current progress
    }
  }
…
}

कैप्चर प्रोसेसिंग की प्रोग्रेस के बारे में जानकारी देने वाले कॉलबैक के लिए, आपके एक्सटेंशन वेंडर को मौजूदा प्रोग्रेस वैल्यू के साथ इन कॉलबैक को कॉल करना होगा:

• बुनियादी एक्सटेंशन: ProcessResultImpl.onCaptureProcessProgressed()
• ऐडवांस एक्सटेंशन: CaptureCallback.onCaptureProcessProgressed()

पोस्टव्यू स्टिल कैप्चर

Android 14 और इसके बाद के वर्शन वाले डिवाइसों पर, कैमरा एक्सटेंशन setPostviewOutputConfiguration का इस्तेमाल करके, पोस्टव्यू (प्रीव्यू इमेज) उपलब्ध करा सकते हैं. उपयोगकर्ता अनुभव को बेहतर बनाने के लिए, ऐप्लिकेशन पोस्टव्यू इमेज को प्लेसहोल्डर के तौर पर दिखा सकते हैं. ऐसा तब किया जा सकता है, जब एक्सटेंशन को प्रोसेस करने में ज़्यादा समय लग रहा हो. इसके बाद, फ़ाइनल इमेज उपलब्ध होने पर, उसे बदला जा सकता है. ऐप्लिकेशन, इस रेफ़रंस कोड का इस्तेमाल करके, पोस्टव्यू कैप्चर करने के अनुरोधों को कॉन्फ़िगर और जारी कर सकते हैं:

{
…
if (!CameraExtensionCharacteristics.isPostviewAvailable()) {
    continue;
}
…
ExtensionSessionConfiguration extensionConfiguration = new
        ExtensionSessionConfiguration(
                CameraExtensionCharacteristics.EXTENSION_NIGHT,
                outputConfig,
                backgroundExecutor,
                extensionSessionStateCallback
    );

extensionConfiguration.setPostviewOutputConfiguration(
    postviewImageOutput);
…
CaptureRequest.Builder captureRequestBuilder =
    cameraDevice.createCaptureRequest(
        CameraDevice.TEMPLATE_STILL_CAPTURE);
captureRequestBuilder.addTarget(stillImageReader.getSurface());
captureRequestBuilder.addTarget(postviewImageSurface);

CaptureRequest captureRequest = captureRequestBuilder.build();
…
}

पोस्टव्यू स्टिल कैप्चर की सुविधा के लिए, आपके वेंडर को ये काम करने होंगे:

• बुनियादी एक्सटेंशन: CaptureProcessorImpl.onPostviewOutputSurface और CaptureProcessorImpl.processWithPostview

• ऐडवांस एक्सटेंशन: SessionProcessorImpl.startCaptureWithPostview

SurfaceView आउटपुट के साथ काम करता है

Android 14 और इसके बाद के वर्शन के लिए, कैमरा एक्सटेंशन क्लाइंट, बार-बार किए जाने वाले अनुरोधों के लिए, SurfaceView इंस्टेंस रजिस्टर करके, पावर और परफ़ॉर्मेंस के लिए ऑप्टिमाइज़ किए गए प्रीव्यू रेंडर पाथ का इस्तेमाल कर सकते हैं.

SurfaceView आउटपुट के लिए, वेंडर एक्सटेंशन को लागू करने की सुविधा ऐसी होनी चाहिए जो SurfaceView इंस्टेंस को स्ट्रीम कर सके और झलक दिखा सके. यह सुविधा काम करती है या नहीं, यह देखने के लिए SurfaceViewExtensionPreviewTest.java सीटीएस मॉड्यूल चलाएं.

वेंडर के हिसाब से सेशन टाइप

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

यह सुविधा, फ़्रेमवर्क और वेंडर स्टैक के साथ पूरी तरह से काम करती है. साथ ही, इसका क्लाइंट/सार्वजनिक तौर पर दिखने वाले एपीआई पर कोई असर नहीं पड़ता.

वेंडर के हिसाब से सेशन टाइप चुनने के लिए, अपनी एक्सटेंशन लाइब्रेरी के लिए यहां दिया गया कोड लागू करें: * बुनियादी एक्सटेंशन के लिए ExtenderStateListener.onSessionType() * ऐडवांस एक्सटेंशन के लिए Camera2SessionConfigImpl.getSessionType()

एक्सटेंशन इंटरफ़ेस के वर्शन का इतिहास

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

रेफ़रंस के तौर पर लागू करना

frameworks/ex में, ओईएम वेंडर लाइब्रेरी के ये रेफ़रंस लागू किए जा सकते हैं.

• advancedSample: इसमें Advanced Extender को बुनियादी तौर पर लागू किया जाता है.

• sample: बेसिक एक्सटेंडर को बुनियादी तौर पर लागू करने का तरीका.

• service_based_sample: इस इमेज में, Service में कैमरा एक्सटेंशन होस्ट करने का तरीका दिखाया गया है. इस तरीके में ये कॉम्पोनेंट शामिल हैं:

  • oem_library: यह Camera2 और CameraX Extensions API के लिए, Camera Extensions OEM लाइब्रेरी है. यह Extensions-Interface को लागू करती है. यह एक पासथ्रू के तौर पर काम करता है, जो Extensions-Interface से आने वाले कॉल को सेवा पर फ़ॉरवर्ड करता है. यह लाइब्रेरी, सेवा से कम्यूनिकेट करने के लिए AIDL फ़ाइलें और रैपर क्लास भी उपलब्ध कराती है.

    ऐडवांस एक्सटेंडर की सुविधा डिफ़ॉल्ट रूप से चालू होती है. बेसिक एक्सटेंडर को चालू करने के लिए, ExtensionsVersionImpl#isAdvancedExtenderImplemented को बदलकर false करें.

  • extensions_service: एक्सटेंशन सेवा को लागू करने का एक उदाहरण. यहां लागू करने का तरीका जोड़ें. सेवा में लागू किया जाने वाला इंटरफ़ेस, Extensions-Interface जैसा ही होता है. उदाहरण के लिए, IAdvancedExtenderImpl.Stub को लागू करने पर वही कार्रवाइयां होती हैं जो AdvancedExtenderImpl को लागू करने पर होती हैं. Image और TotalCaptureResult को पार्सल करने के लिए, ImageWrapper और TotalCaptureResultWrapper ज़रूरी हैं.

किसी डिवाइस पर वेंडर लाइब्रेरी सेट अप करना

ओईएम वेंडर लाइब्रेरी को किसी ऐप्लिकेशन में नहीं बनाया जाता. इसे Camera2/X, डिवाइस से रनटाइम पर लोड करता है. CameraX में, <uses-library> टैग यह एलान करता है कि androidx.camera.extensions.impl लाइब्रेरी, CameraX की डिपेंडेंसी है. यह लाइब्रेरी, camera-extensions लाइब्रेरी की AndroidManifest.xml फ़ाइल में तय की गई है. इसे रनटाइम के दौरान लोड किया जाना चाहिए. Camera2 में, फ़्रेमवर्क एक एक्सटेंशन सेवा लोड करता है. यह सेवा यह भी एलान करती है कि <uses-library>यह रनटाइम पर androidx.camera.extensions.implलाइब्रेरी को लोड करती है.

इससे एक्सटेंशन का इस्तेमाल करने वाले तीसरे पक्ष के ऐप्लिकेशन, ओईएम वेंडर लाइब्रेरी को अपने-आप लोड कर पाते हैं. OEM लाइब्रेरी को 'ज़रूरी नहीं' के तौर पर मार्क किया गया है, ताकि ऐप्लिकेशन उन डिवाइसों पर चल सकें जिन पर यह लाइब्रेरी मौजूद नहीं है. जब कोई ऐप्लिकेशन, कैमरा एक्सटेंशन का इस्तेमाल करने की कोशिश करता है, तो Camera2/X इस व्यवहार को अपने-आप मैनेज करता है. हालांकि, इसके लिए ज़रूरी है कि डिवाइस बनाने वाली कंपनी, डिवाइस पर ओईएम लाइब्रेरी इंस्टॉल करे, ताकि ऐप्लिकेशन उसे ढूंढ सके.

किसी डिवाइस पर ओईएम लाइब्रेरी सेट अप करने के लिए, यह तरीका अपनाएं:

1. अनुमति वाली फ़ाइल जोड़ें. यह फ़ाइल <uses-library> टैग के लिए ज़रूरी है. इसके लिए, इस फ़ॉर्मैट का इस्तेमाल करें: /etc/permissions/ANY_FILENAME.xml. उदाहरण के लिए, /etc/permissions/camera_extensions.xml. इस डायरेक्ट्री में मौजूद फ़ाइलें, <uses-library> में दिए गए नाम वाली लाइब्रेरी को डिवाइस पर मौजूद फ़ाइल के पाथ से मैप करती हैं.

2. फ़ाइल में ज़रूरी जानकारी जोड़ने के लिए, यहां दिए गए उदाहरण का इस्तेमाल करें.

   • name androidx.camera.extensions.impl होना चाहिए, क्योंकि CameraX इसी लाइब्रेरी को खोजता है.
   • file उस फ़ाइल का ऐब्सलूट पाथ है जिसमें एक्सटेंशन लागू करने का तरीका बताया गया है. उदाहरण के लिए, /system/framework/androidx.camera.extensions.impl.jar.

   <?xml version="1.0" encodin>g<="utf->8&quo<t;?
   permissions
       library name="androidx.camera.extensions.impl"
              > < file=">OEM_IMPLEMENTED_JAR" /
   /permissions

Android 12 या इसके बाद के वर्शन में, CameraX एक्सटेंशन के साथ काम करने वाले डिवाइसों में ro.camerax.extensions.enabled प्रॉपर्टी को true पर सेट किया जाना चाहिए. इससे यह पता लगाया जा सकता है कि कोई डिवाइस एक्सटेंशन के साथ काम करता है या नहीं. इसके लिए, डिवाइस की मेक फ़ाइल में यह लाइन जोड़ें:

PRODUCT_VENDOR_PROPERTIES += \
    ro.camerax.extensions.enabled=true \

सत्यापन

डेवलपमेंट के दौरान, ओईएम वेंडर लाइब्रेरी के इंटिग्रेशन को टेस्ट करने के लिए, androidx-main/camera/integration-tests/extensionstestapp/ पर मौजूद उदाहरण ऐप्लिकेशन का इस्तेमाल करें. यह ऐप्लिकेशन, वेंडर के अलग-अलग एक्सटेंशन के साथ काम करता है.

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

एक्सटेंडेड सीन मोड बनाम कैमरा एक्सटेंशन

बोके इफ़ेक्ट वाले एक्सटेंशन को कैमरे के एक्सटेंशन के ज़रिए इस्तेमाल करने के साथ-साथ, एक्सटेंशन को एक्सटेंडेड सीन मोड का इस्तेमाल करके भी इस्तेमाल किया जा सकता है. यह मोड, CONTROL_EXTENDED_SCENE_MODE कुंजी की मदद से चालू किया जाता है. लागू करने से जुड़ी ज़्यादा जानकारी के लिए, कैमरा बोके इफ़ेक्ट देखें.

कैमरा2 ऐप्लिकेशन के लिए कैमरा एक्सटेंशन की तुलना में, एक्सटेंडेड सीन मोड पर कम पाबंदियां होती हैं. उदाहरण के लिए, एक्सटेंडेड सीन मोड को ऐसे सामान्य CameraCaptureSession इंस्टेंस में चालू किया जा सकता है जो स्ट्रीम के अलग-अलग कॉम्बिनेशन के साथ काम करता है. साथ ही, अनुरोध के पैरामीटर कैप्चर करता है. इसके उलट, कैमरा एक्सटेंशन सिर्फ़ स्ट्रीम टाइप के एक तय सेट के साथ काम करते हैं. साथ ही, ये कैप्चर अनुरोध पैरामीटर के साथ सीमित तौर पर काम करते हैं.

एक्सटेंडेड सीन मोड की एक कमी यह है कि इसे सिर्फ़ कैमरा HAL में लागू किया जा सकता है. इसका मतलब है कि इसे ऐप्लिकेशन डेवलपर के लिए उपलब्ध सभी ऑर्थोगोनल कंट्रोल पर काम करने के लिए, पुष्टि की जानी चाहिए.

हमारा सुझाव है कि बोकेह को एक्सटेंडेड सीन मोड और CameraExtensions, दोनों का इस्तेमाल करके दिखाया जाए. ऐसा इसलिए, क्योंकि ऐप्लिकेशन बोकेह को चालू करने के लिए किसी खास एपीआई का इस्तेमाल करना पसंद कर सकते हैं. हमारा सुझाव है कि सबसे पहले एक्सटेंडेड सीन मोड का इस्तेमाल करें. ऐसा इसलिए, क्योंकि ऐप्लिकेशन के लिए बोके इफ़ेक्ट एक्सटेंशन को चालू करने का यह सबसे आसान तरीका है. इसके बाद, एक्सटेंडेड सीन मोड के आधार पर, कैमरा एक्सटेंशन इंटरफ़ेस लागू किया जा सकता है. अगर कैमरा एचएएल में बोकेह इफ़ेक्ट लागू करना मुश्किल है, तो हमारा सुझाव है कि आप Camera Extensions इंटरफ़ेस का इस्तेमाल करके, बोकेह एक्सटेंशन लागू करें. उदाहरण के लिए, अगर इमेज को प्रोसेस करने के लिए, ऐप्लिकेशन लेयर में पोस्ट प्रोसेसर की ज़रूरत होती है.

अक्सर पूछे जाने वाले सवाल

क्या एपीआई लेवल पर कोई पाबंदी है?

हां. यह इस बात पर निर्भर करता है कि ओईएम/वेंडर लाइब्रेरी को लागू करने के लिए, Android API की कौनसी सुविधाओं की ज़रूरत है. उदाहरण के लिए, ExtenderStateListener.onPresetSession(), टैग का बेसलाइन सेट सेट करने के लिए SessionConfiguration.setSessionParameters() कॉल का इस्तेमाल करता है. यह कॉल सिर्फ़ एपीआई लेवल 28 और इसके बाद के वर्शन पर उपलब्ध है. इंटरफ़ेस के खास तरीकों के बारे में जानकारी पाने के लिए, एपीआई के रेफ़रंस दस्तावेज़ देखें.