إضافات الكاميرا

يمكن لمصنّعي الأجهزة إتاحة إضافات، مثل الخلفية الضبابية والوضع الليلي والنطاق العالي الديناميكية، للمطوّرين الخارجيين من خلال واجهة Camera Extensions التي توفّرها مكتبة المصنّع الأصلي للجهاز. يمكن للمطوّرين استخدام واجهة برمجة التطبيقات Camera2 Extensions API وواجهة برمجة التطبيقات CameraX Extensions API للوصول إلى الإضافات المضمّنة في مكتبة مورّد OEM.

للاطّلاع على قائمة بالإضافات المتوافقة، وهي نفسها في Camera2 وCameraX، راجِع واجهة برمجة التطبيقات لإضافات CameraX. إذا أردت إضافة إضافة، يُرجى الإبلاغ عن خطأ باستخدام أداة تتبُّع المشاكل.

توضّح هذه الصفحة كيفية تنفيذ مكتبة مورّد OEM وتفعيلها على الأجهزة.

هندسة معمارية

يوضّح المخطّط التالي بنية واجهة Camera Extensions أو extensions-interface:

الشكل 1: مخطّط بنية إضافات الكاميرا

كما هو موضّح في الرسم التخطيطي، لتوفير إضافات الكاميرا، عليك تنفيذ extensions-interface المقدَّم من مكتبة مورّد المصنّع الأصلي للجهاز. تتيح مكتبة مورّد OEM واجهتَي برمجة تطبيقات: واجهة برمجة تطبيقات إضافات CameraX وواجهة برمجة تطبيقات إضافات Camera2، ويتم استخدامهما من قِبل تطبيقات 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

فئات موسّع تأثيرات الخلفية الضبابية (يجب تنفيذها إذا كانت إضافة Bokeh متوافقة)

• 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 Extensions التطبيق بأنّ الإضافة غير متاحة.

لنتعرّف على كيفية تفاعل واجهات برمجة التطبيقات Camera2 وCameraX Extensions مع مكتبة المورّد لتفعيل إضافة. يوضّح المخطّط التالي مسار العمل المتكامل باستخدام إضافة Night كمثال:

الشكل 2: تنفيذ إضافة "الليل"

1. التحقّق من الإصدار:

   تتطلّب استدعاءات Camera2/X ExtensionVersionImpl.checkApiVersion() التأكّد من أنّ إصدار extensions-interface الذي نفّذه مصنّع المعدات الأصلية متوافق مع الإصدارات المتوافقة مع Camera2/X.

2. بدء استخدام مكتبة المورّدين:

   يحتوي InitializerImpl على طريقة init() تعمل على إعداد مكتبة المورّد. تُكمل Camera2/X عملية التهيئة قبل الوصول إلى فئات Extender.

3. إنشاء مثيل لفئات Extender:

   تنشئ هذه السمة مثيلاً لفئات Extender الخاصة بالإضافة. هناك نوعان من أجهزة التوسيع: جهاز التوسيع الأساسي وجهاز التوسيع المتقدّم. يجب تنفيذ نوع Extender واحد لجميع الإضافات. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الفرق بين "أداة التوسيع الأساسية" و"أداة التوسيع المتقدّمة".

   تنشئ Camera2/X فئات Extender وتتفاعل معها لاسترداد المعلومات وتفعيل الإضافة. بالنسبة إلى إضافة معيّنة، يمكن أن تنشئ Camera2/X فئات Extender عدة مرات. نتيجةً لذلك، لا تنفّذ عمليات تهيئة معقّدة في الدالة الإنشائية أو في استدعاء init(). يجب تنفيذ العمليات المعقّدة فقط عندما تكون جلسة الكاميرا على وشك البدء، مثلاً عند استدعاء onInit() في Basic Extender أو استدعاء initSession() في Advanced Extender.

   بالنسبة إلى إضافة Night، يتم إنشاء فئات Extender التالية لنوع Basic Extender:

   • NightImageCaptureExtenderImpl.java
   • NightPreviewExtenderImpl.java

   بالنسبة إلى نوع "الموسّع المتقدّم":

   • NightAdvancedExtenderImpl.java

4. التحقّق من توفّر الإضافة:

   قبل تفعيل الإضافة، يتحقّق isExtensionAvailable() مما إذا كانت الإضافة متاحة على معرّف الكاميرا المحدّد من خلال مثيل Extender.

5. ابدأ عملية الإعداد باستخدام معلومات الكاميرا:

   يطلب Camera2/X init() من مثيل Extender ويُمرِّر إليه معرّف الكاميرا CameraCharacteristics.

6. معلومات طلب البحث:

   يستدعي فئة Extender لاسترداد معلومات، مثل درجات الدقة المتوافقة، والوقت المقدّر لوقت الاستجابة عند التقاط صورة ثابتة، ومفاتيح طلب الالتقاط من Extender استعدادًا لتفعيل الإضافة.

7. تفعيل الإضافة على جهاز توسيع نطاق الشبكة:

   توفّر فئة Extender جميع الواجهات اللازمة لتفعيل الفئة. توفّر هذه الواجهة آلية موضع الإدراج لتنفيذ المصنّع الأصلي للجهاز (OEM) في مسار Camera2، مثل إدخال مَعلمات طلب الالتقاط أو تفعيل معالج لاحق.

   بالنسبة إلى نوع "الإضافة المتقدّمة"، تتفاعل Camera2/X مع SessionProcessorImpl لتفعيل الإضافة. يسترد Camera2/X مثيل SessionProcessorImpl من خلال استدعاء createSessionProcessor() على Extender.

توضّح الأقسام التالية مسار الإضافة بمزيد من التفصيل.

تأكيد الإصدار

عند تحميل مكتبة مورّد OEM من الجهاز في وقت التشغيل، تتحقّق Camera2/X من ما إذا كانت المكتبة متوافقة مع إصدار extensions-interface. يستخدم extensions-interface الترقيم الدلالي للإصدارات، أو MAJOR.MINOR.PATCH، مثل 1.1.0 أو 1.2.0. ومع ذلك، لا يتم استخدام سوى الإصدارَين الرئيسي والثانوي أثناء عملية التحقّق من الإصدار.

للتحقّق من الإصدار، تستدعي Camera2/X ExtensionVersionImpl.checkApiVersion() الإصدار extensions-interface المتوافق. بعد ذلك، تستخدم Camera2/X الإصدار الذي أبلغت عنه مكتبة الشركة المصنّعة للجهاز (OEM) لتحديد ما إذا كان يمكن تفعيل الإضافة وإمكاناتها.

التوافق مع رقم الإصدار الرئيسي

إذا كانت الإصدارات الرئيسية من extension-interface مختلفة بين Camera2/X والمكتبة الخاصة بالمورّد، سيتم اعتبارها غير متوافقة وسيتم إيقاف الإضافة.

التوافق مع الأنظمة القديمة

ما دام رقم الإصدار الرئيسي متطابقًا، يضمن Camera2/X التوافق مع الأنظمة القديمة مع مكتبات مورّدي المصنّعين الأصليين للأجهزة التي تم إنشاؤها باستخدام إصدارات extensions-interface سابقة. على سبيل المثال، إذا كان Camera2/X يتوافق مع الإصدار 1.3.0 من extensions-interface، ستظل مكتبات مورّدي المعدات الأصلية التي نفّذت الإصدارات 1.0.0 و1.1.0 و1.2.0 متوافقة. يعني هذا أيضًا أنّه بعد تنفيذ إصدار معيّن من مكتبة المورّد، تتأكّد واجهة Camera2/X من أنّ المكتبة متوافقة مع الإصدارات القادمة من extension-interface.

التوافق مع الإصدارات الأحدث

يعتمد التوافق مع الإصدارات الأحدث من مكتبات المورِّدين extensions-interface على الشركة المصنّعة للمعدات الأصلية. إذا كنت بحاجة إلى بعض الميزات لتنفيذ الإضافات، يمكنك تفعيل الإضافات بدءًا من إصدار معيّن. في هذه الحالة، يمكنك عرض إصدار extensions-interface المتوافق عندما يستوفي إصدار مكتبة Camera2/X المتطلبات. إذا لم تكن إصدارات Camera2/X متوافقة، يمكنك عرض إصدار غير متوافق، مثل 99.0.0، لإيقاف الإضافات.

تهيئة مكتبة المورّد

بعد التحقّق من إصدار extensions-interface الذي تم تنفيذه بواسطة مكتبة الشركة المصنّعة للجهاز الأصلي، تبدأ Camera2/X عملية التهيئة. تشير الطريقة InitializerImpl.init() إلى مكتبة الشركة المصنّعة للجهاز الأصلي بأنّ أحد التطبيقات يحاول استخدام الإضافات.

لا تجري Camera2/X أي طلبات أخرى إلى مكتبة الشركة المصنّعة للجهاز الأصلي (OEM) (بخلاف التحقّق من الإصدار) إلى أن تستدعي مكتبة المورّد التابعة للشركة المصنّعة للجهاز الأصلي OnExtensionsInitializedCallback.onSuccess() لإعلامها باكتمال عملية التهيئة.

يجب تنفيذ InitializerImpl اعتبارًا من الإصدار 1.1.0 من extensions-interface. تتخطى Camera2/X خطوة تهيئة المكتبة إذا كانت مكتبة مورّد OEM تنفّذ extensions-interface 1.0.0.

مقارنة بين "أداة التوسيع الأساسية" و"أداة التوسيع المتقدّمة"

هناك نوعان من عمليات تنفيذ extensions-interface: Basic Extender وAdvanced Extender. تتوافق أداة Advanced Extender مع الإصدار 1.2.0 والإصدارات الأحدث منذ extensions-interface.

تنفيذ Basic Extender للإضافات التي تعالج الصور في طبقة تجريد الأجهزة (HAL) الخاصة بالكاميرا أو التي تستخدم معالجًا لاحقًا قادرًا على معالجة بث YUV

استخدِم Advanced Extender للإضافات التي تحتاج إلى تخصيص إعدادات بث Camera2 وإرسال طلبات الالتقاط حسب الحاجة.

اطّلِع على الجدول التالي للاطّلاع على المقارنة:

مسارات التطبيق

يعرض الجدول التالي ثلاثة أنواع من مسارات التطبيق وطلبات البيانات المقابلة من واجهة برمجة التطبيقات Camera Extensions API. على الرغم من أنّ Camera2/X توفّر واجهات برمجة التطبيقات هذه، عليك تنفيذ مكتبة المورّد بشكل صحيح لإتاحة هذه العمليات، وسنوضّحها بمزيد من التفصيل في قسم لاحق.

Basic Extender

توفّر واجهة Basic Extender مواضع إدراج في عدة أماكن ضمن مسار عمل الكاميرا. لكل نوع من أنواع الإضافات فئات Extender مقابلة يجب أن تنفّذها الشركات المصنّعة للمعدات الأصلية.

يسرد الجدول التالي فئات Extender التي على مصنّعي المعدات الأصلية تنفيذها لكل إضافة:

نستخدم PreviewExtenderImpl وImageCaptureExtenderImpl كعناصر نائبة في المثال التالي. استبدِلها بأسماء الملفات الفعلية التي تنفّذها.

تتضمّن أداة Basic Extender الإمكانات التالية:

• أدخِل مَعلمات الجلسة عند ضبط CameraCaptureSession ( onPresetSession).
• إشعارك ببدء جلسة الالتقاط وإغلاقها وإرسال طلب واحد لإشعار طبقة تجريد الأجهزة (HAL) بالمعلَمات التي تم إرجاعها (onEnableSession وonDisableSession).
• إدخال مَعلمات الالتقاط للطلب (PreviewExtenderImpl.getCaptureStage, ImageCaptureExtenderImpl.getCaptureStages).
• أضِف معالِجات لمعاينة الصور الثابتة والتقاطها، وتكون هذه المعالِجات قادرة على معالجة بث YUV_420_888.

لنطّلع على كيفية استدعاء Camera2/X للرمز extensions-interface لتحقيق مسارات التطبيق الثلاثة المذكورة أعلاه.

مسار التطبيق 1: التحقّق من توفّر الإضافة

الشكل 3: مسار التطبيق 1 على أداة Basic Extender

في هذا المسار، تستدعي Camera2/X الطريقة isExtensionAvailable() مباشرةً لكل من PreviewExtenderImpl وImageCaptureExtenderImpl بدون استدعاء init(). يجب أن تعرض كلتا فئتَي Extender القيمة true لتفعيل الإضافات.

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

مسار التطبيق 2: معلومات طلب البحث

الشكل 4. مسار التطبيق 2 على Basic Extender

بعد تحديد ما إذا كانت الإضافة متاحة، يجب أن تستعلم التطبيقات عن المعلومات التالية قبل تفعيل الإضافة.

• نطاق وقت الاستجابة أثناء التسجيل: تعرض الدالة ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange نطاق وقت الاستجابة أثناء التسجيل لكي يقيّم التطبيق ما إذا كان من المناسب تفعيل الإضافة في السيناريو الحالي.

• الأحجام المتوافقة مع سطح العرض المسبق والتقاط الصور: تعرض الدالتان ImageCaptureExtenderImpl.getSupportedResolutions و PreviewExtenderImpl.getSupportedResolutions قائمة بتنسيقات الصور والأحجام المتوافقة مع تنسيق وحجم السطح.

• مفاتيح الطلبات والنتائج المتوافقة: تستدعي Camera2/X الطرق التالية لاسترداد مفاتيح طلبات الالتقاط ومفاتيح النتائج المتوافقة من عملية التنفيذ:

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
  • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

تستدعي Camera2/X دائمًا init() أولاً في فئات Extender هذه قبل طلب المزيد من المعلومات.

مسار التطبيق 3: المعاينة/التقاط صورة ثابتة مع تفعيل الإضافة (تنفيذ HAL)

الشكل 5. مسار التطبيق 3 على Basic Extender

يوضّح المخطّط أعلاه المسار الرئيسي لتفعيل المعاينة والتقاط الصور الثابتة باستخدام إضافة بدون أي معالج. وهذا يعني أنّ طبقة تجريد الأجهزة (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.

  يجب تنفيذ وعرض مثيل PreviewImageProcessorImpl في PreviewExtenderImpl.getProcessor. المعالج مسؤول عن معالجة صور الإدخال YUV_420_888. يجب أن يكتب الناتج بالتنسيق PRIVATE الخاص بالمعاينة. تستخدم Camera2/X مساحة YUV_420_888 بدلاً من PRIVATE لإعداد CameraCaptureSession بغرض المعاينة.

  اطّلِع على الرسم التوضيحي التالي لمعرفة الخطوات:

الشكل 6. معاينة سير العمل باستخدام "PreviewImageProcessorImpl"

توسّع واجهة PreviewImageProcessorImpl واجهة ProcessImpl وتتضمّن ثلاث طرق مهمة:

• تضبط هذه السمة مساحة العرض الناتجة للمعالج.onOutputSurface(Surface surface, int imageFormat) بالنسبة إلى PreviewImageProcessorImpl، يكون imageFormat بتنسيق بكسل، مثل PixelFormat.RGBA_8888.

• تضبط onResolutionUpdate(Size size) حجم الصورة الأساسية.

• تضبط onImageFormatUpdate(int imageFormat) تنسيق الصورة المدخلة. يمكن أن يكون هذا الإعداد حاليًا YUV_420_888 فقط.

معالج التقاط الصور

لالتقاط صور ثابتة، يمكنك تنفيذ معالج من خلال عرض مثيل CaptureProcessorImpl باستخدام ImageCaptureExtenderImpl.getCaptureProcessor. المعالج مسؤول عن معالجة قائمة بصور YUV_420_888 وعناصر TotalCaptureResult تم التقاطها وكتابة الناتج على سطح YUV_420_888.

يمكنك افتراض أنّ المعاينة مفعّلة وتعمل قبل إرسال طلب التقاط صورة ثابتة.

اطّلِع على مسار العمل في الرسم البياني أدناه:

الشكل 7. مواصلة تسجيل التدفق باستخدام 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.

   CaptureStageImpl

3. يتم تجميع الصور التي تم تلقّيها مع مثيلات TotalCaptureResult وإرسالها إلى CaptureProcessorImpl للمعالجة.

4. تكتب CaptureProcessorImpl صورة النتيجة (بتنسيق YUV_420_888) إلى مساحة العرض المحدّدة في استدعاء onOutputSurface(). وتحوّلها Camera2/X إلى صور JPEG إذا لزم الأمر.

إتاحة مفاتيح طلبات البحث ونتائجها

بالإضافة إلى معاينة الكاميرا والتقاط الصور، يمكن للتطبيقات ضبط مَعلمات التكبير/التصغير أو الفلاش أو تشغيل ميزة "النقر للتركيز". قد لا تكون هذه المَعلمات متوافقة مع عملية تنفيذ الإضافة.

تمت إضافة الطرق التالية إلى الإصدار extensions-interface 1.3.0 للسماح لك بعرض المَعلمات التي يتوافق معها التنفيذ:

• تعرض ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() مفاتيح طلبات الالتقاط المتوافقة مع عملية التنفيذ.
• تعرض ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() مفاتيح نتائج الالتقاط التي تتضمّنها نتيجة الالتقاط.

إذا عالجت طبقة تجريد الأجهزة (HAL) للكاميرا الإضافة، سيسترد Camera2/X نتائج الالتقاط في CameraCaptureSession.CaptureCallback. ومع ذلك، إذا تم تنفيذ المعالج، تسترد Camera2/X نتائج الالتقاط في ProcessResultImpl، ويتم تمريرها إلى الطريقة process() في PreviewImageProcessorImpl وCaptureProcessorImpl. أنت المسؤول عن الإبلاغ عن نتيجة الالتقاط من خلال ProcessResultImpl إلى Camera2/X.

اطّلِع على تعريف واجهة 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
• Flash:
  • CaptureRequest#CONTROL_AE_MODE
  • CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
  • CaptureRequest#FLASH_MODE
• تعويض درجة الإضاءة:
  • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

بالنسبة إلى أدوات التوسيع الأساسية التي تستخدم الإصدار 1.2.0 أو الإصدارات الأقدم، تتوافق واجهة برمجة التطبيقات CameraX Extensions بشكل صريح مع جميع المفاتيح المذكورة أعلاه. في الإصدار extensions-interface 1.3.0، تلتزم كلّ من CameraX وCamera2 بالقائمة التي تم عرضها ولا تتوافقان إلا مع المفاتيح الواردة فيها. على سبيل المثال، إذا قررت إرجاع CaptureRequest#CONTROL_ZOOM_RATIO وCaptureRequest#SCALER_CROP_REGION فقط في الإصدار 1.3.0، يعني ذلك أنّه لا يمكن استخدام سوى ميزة التكبير/التصغير في التطبيق، بينما لا يُسمح باستخدام ميزات "النقر للتركيز" و"الفلاش" و"تعويض التعرض للضوء".

Advanced Extender

Advanced Extender هو نوع من عمليات التنفيذ الخاصة بالمورّدين استنادًا إلى Camera2 API. تمت إضافة نوع Extender هذا في الإصدار 1.2.0 من extensions-interface. استنادًا إلى الشركة المصنّعة للجهاز، قد يتم تنفيذ الإضافات في طبقة التطبيق، وهي تعتمد على العوامل التالية:

• إعدادات البث المخصّص: يمكنك إعداد عمليات بث مخصّصة، مثل بث RAW، أو إجراء عمليات بث متعددة لمعرّفات كاميرات فعلية مختلفة.

• إمكانية إرسال طلبات Camera2: إتاحة منطق تفاعل معقّد يمكنه إرسال طلبات التقاط مع مَعلمات استنادًا إلى نتائج الطلبات السابقة

توفّر أداة Advanced Extender برنامج تضمين أو طبقة وسيطة، ما يتيح لك تخصيص إعدادات البث وإرسال طلبات الالتقاط عند الطلب.

الملفات المطلوب تنفيذها

للانتقال إلى تنفيذ "أداة التوسيع المتقدّمة"، يجب أن يعرض الإجراء isAdvancedExtenderImplemented() في ExtensionVersionImpl القيمة true. بالنسبة إلى كل نوع من أنواع الإضافات، على الشركات المصنّعة للأجهزة الأصلية تنفيذ فئات Extender المقابلة. تتوفّر ملفات تنفيذ Advanced Extender في حزمة advanced.

نستخدم AdvancedExtenderImpl كعنصر نائب في المثال التالي. استبدِلها باسم ملف Extender الخاص بالإضافة التي تريد تنفيذها.

دعونا نرى كيف تستدعي Camera2/X extensions-interface لتحقيق مسارات التطبيق الثلاثة.

مسار التطبيق 1: التحقّق من توفّر الإضافات

الشكل 8. مسار التطبيق 1 على "أداة التوسيع المتقدّمة"

في البداية، يتحقّق التطبيق مما إذا كانت الإضافة المحدّدة متوافقة.

مسار التطبيق 2: معلومات طلب البحث

الشكل 9. مسار التطبيق 2 على "أداة التوسيع المتقدّمة"

بعد طلب AdvancedExtenderImpl.init()، يمكن للتطبيق الاستعلام عن المعلومات التالية في AdvancedExtenderImpl:

• وقت الاستجابة المقدَّر لالتقاط صورة ثابتة: تعرض الدالة AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() نطاق وقت الاستجابة لالتقاط الصورة لكي يقيّم التطبيق ما إذا كان من المناسب تفعيل الإضافة في السيناريو الحالي.

• درجات الدقة المتوافقة مع المعاينة والتقاط الصور الثابتة:

  • تعرض AdvancedExtenderImpl.getSupportedPreviewOutputResolutions() خريطة لتنسيق الصورة وقائمة الأحجام المتوافقة مع تنسيق وحجم سطح المعاينة. يجب أن تتوافق أجهزة المصنّعين الأصليين للأجهزة مع تنسيق PRIVATE على الأقل.

  • تعرض AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() التنسيق والأحجام المتوافقة لسطح التقاط الصور الثابتة. على المصنّعين الأصليين للأجهزة توفير إخراج بتنسيقَي JPEG وYUV_420_888.

  • تعرض AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() الأحجام المتوافقة مع بث YUV_420_888 إضافي لتحليل الصور. إذا كان سطح YUV لتحليل الصور غير متاح، يجب أن تعرض getSupportedYuvAnalysisResolutions() القيمة null أو قائمة فارغة.

• مفاتيح/نتائج طلب الالتقاط المتاحة (تمت إضافتها في extensions-interface 1.3.0): تستدعي Camera2/X الطرق التالية لاسترداد مفاتيح طلب الالتقاط ومفاتيح النتائج المتوافقة من عملية التنفيذ:

  • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
  • AdvancedExtenderImpl.getAvailableCaptureResultKeys

لمزيد من المعلومات، يُرجى الاطّلاع على مفاتيح ونتائج طلبات تسجيل البيانات.

مسار التطبيق 3: معاينة/التقاط صورة ثابتة مع تفعيل الإضافة

الشكل 10. مسار التطبيق 3 على "أداة التوسيع المتقدّمة"

يوضّح المخطّط أعلاه المسار الرئيسي لبدء المعاينة والتقاط الصور الثابتة لنوع "الموسّع المتقدّم". لنستعرض كل خطوة.

1. مثال SessionProcessorImpl

   يتم تنفيذ وظيفة Advanced Extender الأساسية في SessionProcessorImpl، وهي المسؤولة عن توفير إعدادات مخصّصة للجلسة وإرسال طلبات الالتقاط لبدء المعاينة وطلب التقاط صورة ثابتة. يتم استدعاء AdvancedExtenderImpl.createSessionProcessor() لعرض مثيل SessionProcessorImpl.

2. initSession

   تعمل السمة SessionProcessorImpl.initSession() على بدء الجلسة للإضافة. هذا هو المكان الذي يمكنك فيه تخصيص الموارد وعرض إعدادات الجلسة لتجهيز CameraCaptureSession.

   بالنسبة إلى مَعلمات الإدخال، تحدّد Camera2/X إعدادات مساحة العرض الناتجة للمعاينة والتقاط الصور الثابتة وتحليل صور YUV الاختياري. يحتوي إعداد مساحة العرض (OutputSurfaceImpl) هذا على مساحة العرض والحجم وتنسيق الصورة التي يتم استردادها باستخدام الطرق التالية في AdvancedExtenderImpl:

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

   يجب عرض مثيل Camera2SessionConfigImpl، والذي يتألف من قائمة بمثيلات Camera2OutputConfigImpl ومَعلمات الجلسة المستخدَمة في ضبط CameraCaptureSession. أنت المسؤول عن عرض صور الكاميرا الصحيحة على مساحات العرض التي تم تمريرها من خلال Camera2/X. في ما يلي بعض الخيارات لتفعيل الإخراج:

   • المعالجة في طبقة تجريد الأجهزة (HAL) الخاصة بالكاميرا: يمكنك إضافة أسطح الإخراج مباشرةً إلى CameraCaptureSession باستخدام تنفيذ SurfaceOutputConfigImpl. يضبط هذا الإعداد مساحة العرض المقدَّمة على مسار الكاميرا، ويسمح لطبقة تجريد الأجهزة (HAL) الخاصة بالكاميرا بمعالجة الصورة.

   • معالجة مساحة العرض الوسيطة ImageReader (مثل RAW وYUV وما إلى ذلك): أضِف مساحات العرض الوسيطة ImageReader إلى CameraCaptureSession باستخدام مثيل ImageReaderOutputConfigImpl.

     عليك معالجة الصور الوسيطة وكتابة صورة النتيجة على مساحة العرض الناتجة.

   • استخدام ميزة مشاركة مساحة العرض Camera2: يمكنك استخدام ميزة مشاركة مساحة العرض مع مساحة عرض أخرى من خلال إضافة أي مثيل Camera2OutputConfigImpl إلى طريقة getSurfaceSharingOutputConfigs() لمثيل Camera2OutputConfigImpl آخر. يجب أن يكون تنسيق السطح وحجمه متطابقَين.

   يجب أن يتضمّن كل Camera2OutputConfigImpl، بما في ذلك SurfaceOutputConfigImpl وImageReaderOutputConfigImpl، معرّفًا فريدًا (getId()) يُستخدم لتحديد مساحة العرض المستهدَفة واسترداد الصورة من ImageReaderOutputConfigImpl.

3. ‫onCaptureSessionStart وRequestProcessorImpl

   عندما يبدأ CameraCaptureSession ويستدعي إطار عمل الكاميرا onConfigured()، يستدعي Camera2/X SessionProcessorImpl.onCaptureSessionStart() مع برنامج تضمين طلب Camera2 RequestProcessImpl. تنفّذ Camera2/X RequestProcessImpl، ما يتيح لك تنفيذ طلبات الالتقاط واسترداد الصور في حال استخدام ImageReaderOutputConfigImpl.

   تتشابه واجهات برمجة التطبيقات RequestProcessImpl مع واجهات برمجة التطبيقات CameraCaptureSession Camera2 من حيث تنفيذ الطلبات. وفي ما يلي أوجه الاختلاف:

   • يتم تحديد مساحة العرض المستهدَفة من خلال معرّف مثيل Camera2OutputConfigImpl.
   • إمكانية استرداد صورة ImageReader

   يمكنك الاتصال بالرقم RequestProcessorImpl.setImageProcessor() باستخدام معرّف Camera2OutputConfigImpl محدّد لتسجيل مثيل ImageProcessorImpl لتلقّي الصور.

   يصبح مثيل RequestProcessImpl غير صالح بعد إجراء عمليات استدعاء Camera2/X SessionProcessorImpl.onCaptureSessionEnd().

4. بدء المعاينة والتقاط صورة

   في عملية تنفيذ Advanced Extender، يمكنك إرسال طلبات الالتقاط من خلال واجهة RequestProcessorImpl. تُعلمك Camera2/X ببدء طلب متكرّر للمعاينة أو تسلسل التقاط الصور الثابتة من خلال استدعاء SessionProcessorImpl#startRepeating وSessionProcessorImpl#startCapture على التوالي. عليك إرسال طلبات الالتقاط لتلبية طلبات المعاينة والالتقاط الثابت.

   تضبط Camera2/X أيضًا مَعلمات طلب الالتقاط من خلال SessionProcessorImpl#setParameters. يجب ضبط مَعلمات الطلب هذه (في حال توفّر المَعلمات) على كلّ من الطلبات المتكرّرة والطلبات الفردية.

   يجب أن تتوافق مع CaptureRequest.JPEG_ORIENTATION وCaptureRequest.JPEG_QUALITY على الأقل. يتوافق الإصدار 1.3.0 من extensions-interface مع مفاتيح الطلبات والنتائج التي تعرضها الطرق التالية:

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

   عندما يضبط المطوّرون المفاتيح في القائمة getAvailableCaptureRequestKeys، عليك تفعيل المَعلمات والتأكّد من أنّ نتيجة الالتقاط تتضمّن المفاتيح في القائمة getAvailableCaptureResultKeys.

5. startTrigger

   يتم استدعاء SessionProcessorImpl.startTrigger() لبدء المشغّل، مثل CaptureRequest.CONTROL_AF_TRIGGER وCaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER. يمكنك تجاهل أي مفاتيح لطلبات الالتقاط لم يتم الإعلان عنها في AdvancedExtenderImpl.getAvailableCaptureRequestKeys().

   تتوفّر startTrigger() منذ الإصدار 1.3.0 من extensions-interface. يتيح هذا الإذن للتطبيقات استخدام ميزة "النقر للتركيز" والفلاش مع الإضافات.

6. إخلاء مساحة

   عند الانتهاء من جلسة تسجيل، يتم استدعاء SessionProcessorImpl.onCaptureSessionEnd() قبل إغلاق CameraCaptureSession. بعد إغلاق جلسة الالتقاط، deInitSession() تنفِّذ عملية التنظيف.

معاينة المحتوى والتقاط صور ثابتة وتحليل الصور

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

بالنسبة إلى نوع "أداة التوسيع الأساسية"، بغض النظر عمّا إذا تم تفعيل الإضافة للمعاينة، يجب تنفيذ كل من ImageCaptureExtenderImpl وPreviewExtenderImpl لإضافة معيّنة. في كثير من الأحيان، يستخدم التطبيق أيضًا بث YUV لتحليل محتوى الصورة، مثل العثور على رموز الاستجابة السريعة أو نص. لتحسين دعم حالة الاستخدام هذه، يجب توفير إمكانية دمج البث المباشر مع معاينة الفيديو والتقاط صور ثابتة وبث YUV_420_888 لضبط CameraCaptureSession. وهذا يعني أنّه في حال تنفيذ معالج، عليك توفير إمكانية دمج ثلاثة أحداث YUV_420_888.

بالنسبة إلى Advanced Extender، يمرِّر 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 في مجموعة اختبار التوافق (CTS).

أنواع الجلسات الخاصة بالمورّد

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

تعمل هذه الميزة بالكامل ضمن إطار العمل ومجموعة أدوات المورّد، ولا يكون لها أي تأثير على واجهة برمجة التطبيقات المرئية للعميل/الجمهور.

لاختيار نوع جلسة خاص بمورّد معيّن، نفِّذ ما يلي لمكتبات الإضافات: * ExtenderStateListener.onSessionType() للإضافات الأساسية * Camera2SessionConfigImpl.getSessionType() للإضافات المتقدّمة

سجلّ التعديلات لإصدارات الإضافات

يعرض الجدول التالي سجلّ إصدارات واجهة "إضافة الكاميرا". يجب دائمًا استخدام أحدث إصدار من مكتبة المورّد.

التنفيذ المرجعي

تتوفّر عمليات تنفيذ مكتبة مورّد المصنّع الأصلي للسيارة المرجعية التالية في frameworks/ex.

• advancedSample: تنفيذ أساسي لـ "أداة التوسيع المتقدّمة"

• ‫sample: تنفيذ أساسي لـ "أداة التوسيع الأساسية".

• service_based_sample: هي عملية تنفيذ توضّح كيفية استضافة إضافات الكاميرا في Service. يتضمّن هذا التنفيذ المكوّنات التالية:

  • ‫oem_library: هي مكتبة خاصة بمصنّعي المعدات الأصلية لتطبيقات "إضافات الكاميرا"، وتتضمّن واجهات برمجة التطبيقات Camera2 وCameraX Extensions، وتنفّذ Extensions-Interface. يعمل هذا التطبيق كواجهة تمرير تعيد توجيه المكالمات من Extensions-Interface إلى الخدمة. توفر هذه المكتبة أيضًا ملفات AIDL وفئات تضمين للتواصل مع الخدمة.

    يتم تفعيل ميزة "الموسّع المتقدّم" تلقائيًا. لتفعيل Basic Extender، غيِّر ExtensionsVersionImpl#isAdvancedExtenderImplemented إلى false.

  • extensions_service: نموذج لتنفيذ "خدمة الإضافات". أضِف رمز التنفيذ هنا. تكون الواجهة التي سيتم تنفيذها في الخدمة مشابهة لواجهة Extensions-Interface. على سبيل المثال، يؤدي تنفيذ IAdvancedExtenderImpl.Stub العمليات نفسها التي يؤديها AdvancedExtenderImpl. ImageWrapper وTotalCaptureResultWrapper مطلوبان لجعل Image وTotalCaptureResult قابلَين للتسلسل.

إعداد مكتبة المورّد على جهاز

لا يتم إنشاء مكتبة المورّد الخاص بالمصنّع الأصلي للجهاز في تطبيق، بل يتم تحميلها من الجهاز أثناء وقت التشغيل بواسطة Camera2/X. في CameraX، تعلن العلامة <uses-library> أنّ المكتبة androidx.camera.extensions.impl، المحدّدة في ملف AndroidManifest.xml الخاص بالمكتبة camera-extensions، هي إحدى الاعتماديات في CameraX ويجب تحميلها في وقت التشغيل. في Camera2، يحمّل إطار العمل خدمة إضافات تعلن أيضًا أنّ <uses-library>تحمّل المكتبة نفسها androidx.camera.extensions.impl في وقت التشغيل.

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

في الإصدار 12 من نظام التشغيل Android أو الإصدارات الأحدث، يجب ضبط السمة ro.camerax.extensions.enabled على true في الأجهزة المتوافقة مع إضافات CameraX، ما يتيح الاستعلام عمّا إذا كان الجهاز متوافقًا مع الإضافات. لإجراء ذلك، أضِف السطر التالي في ملف تصنيع الجهاز:

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

التحقق من صحة البيانات

لاختبار تنفيذ مكتبة مورّد OEM خلال مرحلة التطوير، استخدِم التطبيق النموذجي على androidx-main/camera/integration-tests/extensionstestapp/، والذي يتم تشغيله من خلال إضافات مختلفة للمورّد.

بعد إكمال عملية التنفيذ، استخدِم أداة التحقّق من صحة إضافات الكاميرا لإجراء اختبارات مبرمَجة ويدوية للتأكّد من تنفيذ مكتبة المورّد بشكلٍ سليم.

وضع المشهد الموسّع مقارنةً بإضافات الكاميرا

بالنسبة إلى إضافة "تأثير البوكيه"، بالإضافة إلى إتاحتها باستخدام إضافات الكاميرا، يمكنك إتاحتها باستخدام وضع المشهد الموسّع الذي يتم تفعيله من خلال المفتاح CONTROL_EXTENDED_SCENE_MODE. لمزيد من التفاصيل حول التنفيذ، اطّلِع على تأثير الخلفية الضبابية في الكاميرا.

يفرض وضع المشهد الموسّع قيودًا أقل مقارنةً بإضافات الكاميرا لتطبيقات camera2. على سبيل المثال، يمكنك تفعيل وضع المشهد الموسّع في مثيل CameraCaptureSession عادي يتيح مجموعات مرنة من عمليات البث ومعلمات طلب الالتقاط. في المقابل، لا تتوافق إضافات الكاميرا إلا مع مجموعة ثابتة من أنواع البث، كما أنّها تتوافق بشكل محدود مع مَعلمات طلبات الالتقاط.

من عيوب وضع المشهد الموسّع أنّه لا يمكن تنفيذه إلا في طبقة تجريد الأجهزة (HAL) الخاصة بالكاميرا، ما يعني أنّه يجب التحقّق من عمله مع جميع عناصر التحكّم المتعامدة المتاحة لمطوّري التطبيقات.

ننصحك بإتاحة تأثير الخلفية الضبابية باستخدام كلّ من وضع المشهد الموسّع وCamera Extensions، لأنّ التطبيقات قد تفضّل استخدام واجهة برمجة تطبيقات معيّنة لتفعيل هذا التأثير. ننصحك أولاً باستخدام وضع المشهد الموسّع لأنّه الطريقة الأكثر مرونة لتفعيل ميزة "تأثير البوكيه" في التطبيقات. بعد ذلك، يمكنك تنفيذ واجهة إضافات الكاميرا استنادًا إلى وضع المشهد الموسّع. إذا كان تنفيذ تأثيرات الخلفية الضبابية في طبقة تجريد الأجهزة (HAL) الخاصة بالكاميرا أمرًا صعبًا، مثلاً لأنّه يتطلّب معالجًا لاحقًا يعمل في طبقة التطبيق لمعالجة الصور، ننصح بتنفيذ إضافة الخلفية الضبابية باستخدام واجهة Camera Extensions.

الأسئلة الشائعة

هل هناك أي قيود على مستويات واجهة برمجة التطبيقات؟

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