कैमराएक्स विक्रेता एक्सटेंशन

डिवाइस निर्माता कैमराएक्स एक्सटेंशन इंटरफेस के माध्यम से तीसरे पक्ष के डेवलपर्स के लिए डिवाइस-विशिष्ट प्रभावों को उजागर करने के लिए कैमराएक्स ओईएम विक्रेता पुस्तकालय को लागू कर सकते हैं। कैमराएक्स रनटाइम पर लोड किए गए विक्रेता-कार्यान्वित कक्षाओं के लिए कैमराएक्स एक्सटेंशन इंटरफ़ेस को परिभाषित करता है। यह पृष्ठ वर्णन करता है कि OEM विक्रेता पुस्तकालय को कैसे कार्यान्वित किया जाए और इसे उपकरणों पर कैसे सक्षम किया जाए।

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

आर्किटेक्चर

आर्किटेक्चर

चित्रा 1. विक्रेता विस्तार वास्तुकला आरेख

यह आरेख कैमराएक्स विक्रेता एक्सटेंशन की वास्तुकला का वर्णन करता है। कैमराएक्स एक्सटेंशन लाइब्रेरी ( कैमरा-एक्सटेंशन ) के खिलाफ थर्ड-पार्टी ऐप्स बनाए जा सकते हैं और कैमरा एक्सटेंशन पब्लिक एपीआई ( कैमरा-एक्सटेंशन एपीआई ) का उपयोग कर सकते हैं। कैमरा-एक्सटेंशन एपीआई को कैमराएक्स द्वारा परिभाषित किया गया है और इसे तब अपडेट किया जाता है जब कैमरा-एक्सटेंशन लाइब्रेरी का नया संस्करण जारी किया जाता है। कैमरा-एक्सटेंशन सार्वजनिक एपीआई और कैमरा-एक्सटेंशन लाइब्रेरी का संस्करण समान है।

Android 12 से, Camera2 एक्सटेंशन API के विरुद्ध तृतीय-पक्ष एप्लिकेशन बनाए जा सकते हैं। समर्थित एक्सटेंशन मोड को सक्षम करने के लिए, ऐप्स CameraDevice#createExtensionSession() का उपयोग करके कैमरा कैप्चर सत्र ( CameraExtensionSession ) बना सकते हैं।

कैमराएक्स द्वारा परिभाषित एक्सटेंशन इंटरफ़ेस ( एक्सटेंशन-इंटरफ़ेस ) कैमराएक्स कैमरा-एक्सटेंशन लाइब्रेरी और कैमरा 2 एक्सटेंशन एपीआई दोनों को OEM विक्रेता लाइब्रेरी ( कैमरा-एक्सटेंशन-स्टब ) के साथ संचार करने की अनुमति देता है। इसका मतलब यह है कि कैमराएक्स ओईएम विक्रेता पुस्तकालय को लागू करने वाले उपकरणों में कैमरा 2 एक्सटेंशन एपीआई के लिए भी समर्थन है।

OEM विक्रेता पुस्तकालय को कार्यान्वित करना

ये कार्यान्वयन निर्देश एक उदाहरण के रूप में बोकेह (पोर्ट्रेट) विक्रेता एक्सटेंशन का उपयोग करते हैं, लेकिन आप इन्हें एचडीआर, फेस रीटच और नाइट मोड एक्सटेंशन जैसे अन्य एक्सटेंशन पर लागू कर सकते हैं। ऐसा करने के लिए, बोकेह एक्सटेंशन के लिए उपयोग किए गए कोड को कॉपी और पेस्ट करें और एक्सटेंशन नाम को वांछित एक्सटेंशन से बदलें (उदाहरण के लिए, BokehImageCaptureExtenderImpl को HdrImageCaptureExtenderImpl से बदलना)।

आपको प्रत्येक प्रभाव के लिए कार्यान्वयन प्रदान करने की आवश्यकता नहीं है। एक विक्रेता कार्यान्वयन के बिना एक प्रभाव कैमराएक्स कार्यान्वयन के लिए डिफ़ॉल्ट है। यदि कोई प्रभाव उपलब्ध नहीं है, तो डिफ़ॉल्ट कार्यान्वयन प्रभाव को सक्षम नहीं करता है और तृतीय-पक्ष डेवलपर को रिपोर्ट करता है कि प्रभाव अनुपलब्ध है।

संस्करण सत्यापन

OEM लाइब्रेरी लोड करते समय, CameraX सत्यापित करता है कि OEM लाइब्रेरी में एक ऐसा संस्करण है जो एक्सटेंशन इंटरफ़ेस संस्करण (इस दस्तावेज़ में एक्सटेंशन-संस्करण के रूप में संदर्भित) के साथ संगत है। संस्करण संगतता निर्धारित करने के लिए, कैमराएक्स केवल प्रमुख और छोटे संस्करणों की जांच करता है (उदाहरण के लिए, 1.0) लेकिन पैच संस्करण की जांच नहीं करता है क्योंकि इसका उपयोग केवल बग फिक्स के लिए किया जाता है, इंटरफ़ेस परिवर्तनों के लिए नहीं। विशिष्ट API के लिए आवश्यक एक्सटेंशन-संस्करण इस दस्तावेज़ में नोट किया गया है। निर्दिष्ट एक्सटेंशन-संस्करण के बिना API एक्सटेंशन-संस्करण 1.0 के साथ संगत हैं।

संस्करण को सत्यापित करने के लिए, कैमराएक्स ExtensionVersionImpl इंटरफ़ेस से पूछताछ करता है। कैमराएक्स तब ओईएम लाइब्रेरी द्वारा रिपोर्ट किए गए संस्करण का उपयोग उस कार्यक्षमता को निर्धारित करने के लिए करता है जिसे कॉल किया जा सकता है।

प्रारंभ

कैमराएक्स आरंभीकरण प्रक्रिया शुरू करता है जब उसने ओईएम लाइब्रेरी द्वारा कार्यान्वित एक्सटेंशन इंटरफ़ेस के संस्करण को निर्धारित किया है। InitializerImpl.init विधि OEM लाइब्रेरी को संकेत देती है कि कोई ऐप एक्सटेंशन का उपयोग करना चाहता है। जब तक OnExtensionsInitializedCallback को सफल स्थिति के साथ कॉल नहीं किया जाता, तब तक OEM लाइब्रेरी (संस्करण जाँच के अलावा) को कोई अन्य कॉल नहीं किया जाता है।

इस पद्धति को विस्तार-संस्करण 1.1 के रूप में लागू किया जाना चाहिए। विवरण के लिए, InitializerImpl पर स्रोत देखें।

एक्सटेंडरस्टेट लिस्टनर इंटरफ़ेस

कैमराएक्स अपनी पाइपलाइन में कई स्थानों पर हुक प्रदान करता है ताकि ओईएम लाइब्रेरी को प्रासंगिक सत्र पैरामीटर और SessionParameters मान सेट करने की अनुमति CaptureRequest सके। OEM लाइब्रेरी को इन मानों को निर्दिष्ट समय पर सेट करने की अनुमति देने के लिए, ExtenderStateListener इंटरफ़ेस लागू करें। इस इंटरफ़ेस को किसी भी एक्सटेंडर के हिस्से के रूप में लागू किया जाना चाहिए, चाहे वह प्रीव्यू हो, इमेज कैप्चर, बोकेह या एचडीआर एक्सटेंडर।

चित्र उतारना

इमेज कैप्चर के लिए एक्सटेंशन का समर्थन करने के लिए, संबंधित ImageCaptureExtender इंटरफ़ेस (उदाहरण के लिए, BokehImageCaptureExtenderImpl या HdrImageCaptureExtenderImpl ) को लागू करें।

ImageCaptureExtenderImpl में इमेज कैप्चर से संबंधित एक्सटेंशन के लिए आवश्यक इंटरफेस शामिल हैं।

ऐप परत पर पोस्ट प्रोसेसिंग के लिए CaptureProcessorImpl इंटरफ़ेस को लागू किया जाना चाहिए। एक्सटेंशन इंटरफ़ेस संस्करण 1.1 के अनुसार, केवल YUV_420_888 इनपुट छवि प्रारूप का समर्थन किया जाना चाहिए। यदि कैमरा एचएएल में प्रसंस्करण किया जाता है तो CaptureProcessor इंटरफ़ेस की आवश्यकता नहीं होती है।

निम्न चित्र छवि कैप्चर प्रक्रिया प्रवाह को दिखाता है।

छवि कैप्चर प्रक्रिया प्रवाह

चित्र 2. छवि कैप्चर प्रवाह आरेख

उदाहरण: BokehImageCaptureExtenderImpl

छवि कैप्चर के लिए बोकेह एक्सटेंशन का समर्थन करने के लिए, androidx.camera.extensions.impl पैकेज में BokehImageCaptureExtenderImpl वर्ग लागू करें।

पूर्वावलोकन

पूर्वावलोकन के लिए एक्सटेंशन का समर्थन करने के लिए, संबंधित PreviewExtender इंटरफ़ेस को लागू करें (उदाहरण के लिए, BokehPreviewExtenderImpl या HdrPreviewExtenderImpl )। PreviewExtender इंटरफ़ेस में पूर्वावलोकन-संबंधी एक्सटेंशन के लिए आवश्यक इंटरफ़ेस शामिल हैं।

विवरण के लिए, PreviewExtenderImpl पर स्रोत देखें।

पूर्वावलोकन एक्सटेंशन के लिए इमेज प्रोसेसिंग कैमरा HAL या ऐप लेयर में किया जा सकता है। यह ProcessorType के मान से निर्धारित होता है, जो PreviewExtenderImpl द्वारा लौटाया जाता है।

यदि PROCESSOR_TYPE_REQUEST_UPDATE_ONLY प्रकार लौटाया जाता है, तो CaptureRequest कुंजियों के माध्यम से एचएएल में प्रसंस्करण किया जाता है। यदि PROCESSOR_TYPE_IMAGE_PROCESSOR प्रकार लौटाया जाता है, तो PreviewImageProcessorImpl इंटरफ़ेस द्वारा ऐप परत में प्रसंस्करण किया जाता है। यह इंटरफ़ेस एक Image और TotalCaptureResult जोड़ी पर काम करता है। एक्सटेंशन इंटरफ़ेस संस्करण 1.1 के अनुसार, केवल YUV_420_888 इनपुट छवि प्रारूप का समर्थन किया जाना चाहिए।

निम्न आरेख पूर्वावलोकन विक्रेता एक्सटेंशन के लिए प्रक्रिया प्रवाह को दर्शाता है।

पूर्वावलोकन प्रवाह आरेख

चित्र 3. पूर्वावलोकन प्रवाह आरेख

उदाहरण: BokehPreviewExtenderImpl

पूर्वावलोकन के लिए बोकेह का समर्थन करने के लिए, androidx.camera.extensions.impl पैकेज में BokehPreviewExtenderImpl वर्ग लागू करें।

संदर्भ कार्यान्वयन

संदर्भ OEM विक्रेता पुस्तकालय कार्यान्वयन के लिए, camera-testlib-extensions देखें। ध्यान दें कि यह कार्यान्वयन वास्तव में प्रभावों को लागू किए बिना पासथ्रू करता है।

डिवाइस पर विक्रेता पुस्तकालय की स्थापना

OEM विक्रेता पुस्तकालय एक ऐप में नहीं बनाया गया है, बल्कि कैमराएक्स द्वारा रनटाइम पर डिवाइस से लोड किया गया है। <uses-library> टैग घोषित करता है कि androidx.camera.extensions.impl लाइब्रेरी, जिसे AndroidManifest.xml फ़ाइल में परिभाषित किया गया है, CameraX की निर्भरता है और इसे रनटाइम पर लोड किया जाना चाहिए। यह विक्रेता एक्सटेंशन का उपयोग करने वाले तृतीय-पक्ष एप्लिकेशन को OEM विक्रेता लाइब्रेरी को स्वचालित रूप से लोड करने का प्रयास करने की अनुमति देता है। OEM लाइब्रेरी को वैकल्पिक के रूप में चिह्नित किया गया है ताकि ऐप्स उन डिवाइस पर चल सकें जिनके पास डिवाइस पर लाइब्रेरी नहीं है।

कैमराएक्स इस व्यवहार को स्वचालित रूप से संभालता है जब कोई ऐप विक्रेता एक्सटेंशन का उपयोग करने का प्रयास करता है जब तक कि डिवाइस निर्माता डिवाइस पर ओईएम लाइब्रेरी रखता है ताकि इसे ऐप द्वारा खोजा जा सके।

किसी डिवाइस पर OEM लाइब्रेरी सेट करने के लिए, निम्न कार्य करें:

  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 \

मान्यकरण

विकास चरण के दौरान OEM विक्रेता पुस्तकालय के अपने कार्यान्वयन का परीक्षण करने के लिए, androidx-main/camera/integration-tests/extensionstestapp/ पर उदाहरण ऐप का उपयोग करें, जो विभिन्न विक्रेता एक्सटेंशन के माध्यम से चलता है।

अपने कार्यान्वयन को पूरा करने के बाद, स्वचालित और मैन्युअल परीक्षण चलाने के लिए कैमराएक्स विक्रेता एक्सटेंशन सत्यापन उपकरण का उपयोग करें ताकि यह सत्यापित किया जा सके कि विक्रेता पुस्तकालय सही ढंग से कार्यान्वित किया गया है।

अक्सर पूछे जाने वाले प्रश्न (एफएक्यू)

क्या एपीआई स्तरों पर कोई प्रतिबंध है?

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