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

डिवाइस बनाने वाली कंपनियां, तीसरे पक्ष के डेवलपर को एक्सटेंशन उपलब्ध करा सकती हैं. जैसे, बोकेह, नाइट मोड, और एचडीआर. इसके लिए, उन्हें ओईएम वेंडर लाइब्रेरी से मिले 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 ऐप्लिकेशन करते हैं, ताकि वेंडर एक्सटेंशन को ऐक्सेस किया जा सके.

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

OEM वेंडर लाइब्रेरी को लागू करने के लिए, 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 पर सेट करें या उससे जुड़ी एक्सटेंडर क्लास हटाएं. 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 क्लास को कॉल करता है, ताकि एक्सटेंशन चालू करने की तैयारी के दौरान, एक्सटेंडर से यह जानकारी मिल सके: काम करने वाले रिज़ॉल्यूशन, अब भी अनुमानित लेटेन्सी कैप्चर करें, और अनुरोध कुंजियां कैप्चर करें.

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

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

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

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

जब तक मुख्य वर्शन एक जैसा होता है, तब तक Camera2/X यह पक्का करता है कि पुराने वर्शन के साथ काम करने की सुविधा उपलब्ध हो. यह सुविधा, 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: एक्सटेंशन चालू होने पर झलक देखना/स्टिल इमेज कैप्चर करना (एचएएल लागू करना)

पांचवीं इमेज. बेसिक एक्सटेंडर पर ऐप्लिकेशन फ़्लो 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 पर आधारित वेंडर का एक तरीका है. इस Extender टाइप को extensions-interface 1.2.0 में जोड़ा गया था. डिवाइस बनाने वाली कंपनी के हिसाब से, एक्सटेंशन को ऐप्लिकेशन लेयर में लागू किया जा सकता है. यह इन बातों पर निर्भर करता है:

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

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

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

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

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

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

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

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

आठवीं इमेज. ऐडवांस एक्सटेंडर पर ऐप्लिकेशन फ़्लो 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 में जोड़ा जा सकता है. इससे, कैमरे की पाइपलाइन में दिए गए आउटपुट सर्फ़ेस को कॉन्फ़िगर किया जाता है. साथ ही, कैमरा एचएएल को इमेज प्रोसेस करने की अनुमति मिलती है.

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

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

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

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

3. onCaptureSessionStart और RequestProcessorImpl

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

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

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

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

   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 सूची में कुंजियां सेट करते हैं, तो आपको पैरामीटर चालू करने होंगे. साथ ही, यह पक्का करना होगा कि कैप्चर किए गए नतीजे में, 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 फ़ाइलें और रैपर क्लास भी उपलब्ध कराती है.

    ऐडवांस एक्सटेंडर की सुविधा डिफ़ॉल्ट रूप से चालू होती है. Basic Extender को चालू करने के लिए, 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" encoding="utf-8"?>
   <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 \

Validation

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

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

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

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

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

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

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

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

क्या एपीआई लेवल से जुड़ी कोई पाबंदी है?

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