ملحقات بائع CameraX

يمكن لمصنعي الأجهزة تنفيذ مكتبة بائع CameraX OEM لعرض التأثيرات الخاصة بالجهاز لمطوري الجهات الخارجية من خلال واجهة ملحقات CameraX. يحدد CameraX واجهة ملحقات CameraX للفئات التي ينفذها البائع والتي يتم تحميلها في وقت التشغيل. توضح هذه الصفحة كيفية تنفيذ مكتبة بائع OEM وتمكينها على الأجهزة.

قبل تنفيذ مكتبة البائع ، تأكد من فهم كيفية عمل مكتبة دعم CameraX Jetpack. لمعرفة المزيد حول CameraX ، راجع نظرة عامة على CameraX . لمزيد من المعلومات حول ملحقات البائعين ، راجع ملحقات البائع .

بنيان

بنيان

الشكل 1. مخطط هندسة ملحقات البائعين

يصف هذا الرسم التخطيطي بنية امتدادات بائع CameraX. يمكن إنشاء تطبيقات الجهات الخارجية مقابل مكتبة ملحقات CameraX (ملحقات الكاميرا ) واستخدام واجهة برمجة تطبيقات ملحقات الكاميرا العامة (واجهة برمجة تطبيقات ملحقات الكاميرا ). يتم تعريف واجهة برمجة تطبيقات ملحقات الكاميرا بواسطة CameraX ويتم تحديثها عند إصدار إصدار جديد من مكتبة ملحقات الكاميرا. تعد إصدارات واجهة برمجة التطبيقات العامة الخاصة بامتدادات الكاميرا ومكتبة ملحقات الكاميرا هي نفسها.

من Android 12 ، يمكن إنشاء تطبيقات الجهات الخارجية مقابل واجهة برمجة تطبيقات ملحقات Camera2. لتمكين أوضاع الامتداد المدعومة ، يمكن للتطبيقات إنشاء جلسة التقاط الكاميرا ( CameraExtensionSession ) باستخدام CameraDevice#createExtensionSession() .

تسمح واجهة الامتدادات (واجهة الامتدادات ) التي حددها CameraX لكل من مكتبة ملحقات الكاميرا CameraX وواجهة برمجة تطبيقات ملحقات Camera2 بالتواصل مع مكتبة بائع OEM ( camera-extension-stub ). هذا يعني أن الأجهزة التي تطبق مكتبة بائع CameraX OEM لديها أيضًا دعم لواجهة برمجة تطبيقات ملحقات Camera2.

تنفيذ مكتبة بائع OEM

تستخدم إرشادات التنفيذ هذه امتداد البائع bokeh (عموديًا) كمثال ، ولكن يمكنك تطبيقها على ملحقات أخرى مثل HDR وتنقيح الوجه وإضافات الوضع الليلي. للقيام بذلك ، انسخ والصق الكود المستخدم لملحق bokeh واستبدل اسم الامتداد بالامتداد المطلوب (على سبيل المثال ، استبدال BokehImageCaptureExtenderImpl بـ HdrImageCaptureExtenderImpl ).

لست مطالبًا بتوفير تطبيق لكل تأثير. التأثير بدون تطبيق البائع الافتراضي هو تطبيق CameraX. إذا لم يكن أحد التأثيرات متاحًا ، فإن التطبيق الافتراضي لا يمكّن التأثير ويبلغ مطور الجهة الخارجية بأن التأثير غير متاح.

التحقق من الإصدار

عند تحميل مكتبة OEM ، يتحقق CameraX من احتواء مكتبة OEM على إصدار متوافق مع إصدار واجهة الملحقات (يشار إليه باسم إصدار الملحق في هذا المستند). لتحديد توافق الإصدار ، يتحقق CameraX فقط من الإصدارات الرئيسية والثانوية (على سبيل المثال ، 1.0) ولكنه لا يتحقق من إصدار التصحيح لأنه يُستخدم فقط لإصلاح الأخطاء ، وليس لتغييرات الواجهة. تمت الإشارة إلى إصدار الامتداد المطلوب لواجهات برمجة تطبيقات معينة في هذا المستند. واجهات برمجة التطبيقات التي لا تحتوي على إصدار ملحق محدد متوافقة مع الإصدار 1.0 من الملحق.

للتحقق من الإصدار ، يستعلم CameraX عن واجهة ExtensionVersionImpl . ثم يستخدم CameraX الإصدار الذي تم الإبلاغ عنه بواسطة مكتبة OEM لتحديد الوظيفة التي يمكن استدعاؤها.

التهيئة

يبدأ CameraX عملية التهيئة عندما تحدد إصدار واجهة الملحقات التي تنفذها مكتبة OEM. تشير طريقة InitializerImpl.init إلى مكتبة OEM إلى أن التطبيق يريد استخدام الامتدادات. لا يتم إجراء أي مكالمات أخرى إلى مكتبة OEM (باستثناء التحقق من الإصدار) حتى يتم استدعاء OnExtensionsInitializedCallback بحالة نجاح.

يجب تنفيذ هذه الطريقة اعتبارًا من الإصدار 1.1 من الامتداد. للحصول على تفاصيل ، راجع المصدر في InitializerImpl .

واجهة ExtenderStateListener

يوفر CameraX خطافات في عدة أماكن في خط الأنابيب الخاص به للسماح لمكتبة OEM بتعيين معلمات SessionParameters وقيم CaptureRequest ذات الصلة. للسماح لمكتبة OEM بتعيين هذه القيم في الأوقات المحددة ، قم بتطبيق واجهة ExtenderStateListener . يجب تنفيذ هذه الواجهة كجزء من أي موسع ، سواء كانت معاينة أو التقاط صورة أو خوخه أو موسع HDR.

التقاط الصور

لدعم امتداد التقاط الصورة ، قم بتنفيذ واجهة ImageCaptureExtender المقابلة (على سبيل المثال ، BokehImageCaptureExtenderImpl أو HdrImageCaptureExtenderImpl ).

يتضمن ImageCaptureExtenderImpl الواجهات المطلوبة للامتدادات المتعلقة بالتقاط الصور.

يجب تنفيذ واجهة CaptureProcessorImpl حتى تتم المعالجة اللاحقة في طبقة التطبيق. اعتبارًا من الإصدار 1.1 لواجهة الامتدادات ، يجب دعم تنسيق صورة الإدخال YUV_420_888 فقط. لا تكون واجهة CaptureProcessor مطلوبة إذا تمت المعالجة في HAL الخاص بالكاميرا.

يوضح الرسم البياني التالي تدفق عملية التقاط الصورة.

تدفق عملية التقاط الصور

الشكل 2. رسم تخطيطي لتدفق التقاط الصور

مثال: BokehImageCaptureExtenderImpl

لدعم امتداد bokeh لالتقاط الصورة ، قم بتنفيذ فئة BokehImageCaptureExtenderImpl في حزمة androidx.camera.extensions.impl .

معاينة

لدعم امتداد المعاينة ، قم بتنفيذ واجهة PreviewExtender المقابلة (على سبيل المثال ، BokehPreviewExtenderImpl أو HdrPreviewExtenderImpl ). تشتمل واجهة PreviewExtender على الواجهات المطلوبة لملحقات المعاينة ذات الصلة.

للحصول على التفاصيل ، راجع المصدر في PreviewExtenderImpl .

يمكن إجراء معالجة الصورة لامتداد المعاينة في HAL للكاميرا أو طبقة التطبيق. يتم تحديد ذلك من خلال قيمة ProcessorType ، والتي يتم إرجاعها بواسطة PreviewExtenderImpl .

إذا تم إرجاع نوع PROCESSOR_TYPE_REQUEST_UPDATE_ONLY ، يتم تنفيذ المعالجة في HAL من خلال مفاتيح CaptureRequest . إذا تم إرجاع نوع PROCESSOR_TYPE_IMAGE_PROCESSOR ، يتم تنفيذ المعالجة في طبقة التطبيق بواسطة واجهة PreviewImageProcessorImpl . تعمل هذه الواجهة على زوج Image و TotalCaptureResult . اعتبارًا من الإصدار 1.1 لواجهة الامتدادات ، يجب دعم تنسيق صورة الإدخال YUV_420_888 فقط.

يوضح الرسم التخطيطي التالي تدفق العملية لملحق مورد المعاينة.

معاينة مخطط التدفق

الشكل 3. معاينة مخطط التدفق

مثال: BokehPreviewExtenderImpl

لدعم bokeh للمعاينة ، قم بتنفيذ فئة BokehPreviewExtenderImpl في حزمة androidx.camera.extensions.impl .

تنفيذ المرجع

للحصول على تطبيق مرجعي لمكتبة بائع OEM ، راجع camera-testlib-extensions . لاحظ أن هذا التنفيذ يؤدي عبورًا دون تنفيذ التأثيرات فعليًا.

إعداد مكتبة البائع على الجهاز

مكتبة بائع OEM ليست مضمنة في أحد التطبيقات ولكن بدلاً من ذلك يتم تحميلها من الجهاز في وقت التشغيل بواسطة CameraX. تعلن العلامة <uses-library> أن مكتبة androidx.camera.extensions.impl ، المحددة في ملف AndroidManifest.xml ، هي تبعية لـ CameraX ويجب تحميلها في وقت التشغيل. يسمح هذا لتطبيقات الجهات الخارجية التي تستخدم ملحقات البائعين بمحاولة تحميل مكتبة بائع OEM تلقائيًا. تم وضع علامة على مكتبة OEM على أنها اختيارية بحيث يمكن تشغيل التطبيقات على الأجهزة التي لا تحتوي على مكتبة على الجهاز.

يتعامل CameraX مع هذا السلوك تلقائيًا عندما يحاول أحد التطبيقات استخدام امتداد البائع طالما أن الشركة المصنعة للجهاز تضع مكتبة 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/ ، والذي يتم تشغيله من خلال امتدادات البائعين المختلفة.

بعد إكمال التنفيذ ، استخدم أداة التحقق من صحة ملحقات البائع CameraX لتشغيل الاختبارات الآلية واليدوية للتحقق من تنفيذ مكتبة البائع بشكل صحيح.

أسئلة وأجوبة (FAQ)

هل هناك أي قيود على مستويات API؟

نعم. يعتمد هذا على مجموعة ميزات Android API التي يتطلبها تنفيذ مكتبة بائع OEM. على سبيل المثال ، يستخدم ExtenderStateListener.onPresetSession() SessionConfiguration.setSessionParameters() لتعيين مجموعة أساسية من العلامات. هذه المكالمة متاحة فقط على مستوى API 28 والإصدارات الأحدث. للحصول على تفاصيل حول طرق معينة للواجهة ، راجع الوثائق المرجعية لواجهة برمجة التطبيقات .