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

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

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

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

البنية

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

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

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

فئات موسّع تأثيرات الخلفية الضبابية (يجب تنفيذها إذا كانت إضافة 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 كمثال:

Mainflow

الشكل 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:

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

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

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

التوافق مع الإصدارات السابقة

ما دام الإصدار الرئيسي متطابقًا، يضمن Camera2/X التوافق مع الإصدارات القديمة مع مكتبات مورّدي الشركات المصنّعة الأصلية التي تم إنشاؤها باستخدام إصدارات extensions-interface سابقة. على سبيل المثال، إذا كان Camera2/X يتوافق مع الإصدار 1.3.0 من extensions-interface، ستظل مكتبات مورّدي OEM التي نفّذت الإصدارات 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 أي طلبات أخرى إلى مكتبة الشركة المصنّعة للجهاز (بخلاف التحقّق من الإصدار) إلى أن تستدعي مكتبة المورّد الخاصة بالشركة المصنّعة للجهاز OnExtensionsInitializedCallback.onSuccess() لإعلامها باكتمال عملية التهيئة.

يجب تنفيذ InitializerImpl اعتبارًا من الإصدار extensions-interface 1.1.0. تتخطى 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 وإرسال طلبات الالتقاط حسب الحاجة

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

Basic Extender Advanced Extender
إعدادات البث تم إصلاحها
المعاينة: PRIVATE أو YUV_420_888 (في حال توفّر معالج)
التقاط صورة ثابتة: JPEG أو YUV_420_888 (في حال توفّر معالج) 		يمكن للمصنّع الأصلي للجهاز تخصيصها.
جارٍ إرسال طلب الالتقاط يمكن فقط لواجهة برمجة التطبيقات Camera2/X إرسال طلبات الالتقاط. يمكنك ضبط المَعلمات لهذه الطلبات. عند توفير المعالج لالتقاط الصور، يمكن أن يرسل Camera2/X طلبات التقاط متعددة ويرسل جميع الصور ونتائج الالتقاط إلى المعالج. يتم توفير مثيل RequestProcessorImpl لك لتنفيذ طلب الالتقاط باستخدام Camera2 والحصول على النتائج والصورة.

تستدعي Camera2/X الرمزين startRepeating وstartCapture على SessionProcessorImpl لإرسال إشارة إلى المصنّع الأصلي للجهاز لبدء الطلب المتكرّر للمعاينة وبدء تسلسل التقاط الصور الثابتة على التوالي.

نقاط ربط في مسار الكاميرا
  • توفّر onPresetSession مَعلمات الجلسة.
  • يرسل onEnableSession طلبًا واحدًا بعد إعداد CameraCaptureSession مباشرةً.
  • يرسل onDisableSession طلبًا واحدًا قبل إغلاق CameraCaptureSession.
  • تعمل الدالة initSession على تهيئة إعدادات مخصّصة لجلسة camera2 وعرضها من أجل إنشاء جلسة الالتقاط.
  • يتم استدعاء onCaptureSessionStart مباشرةً بعد ضبط CameraCaptureSession.
  • يتم استدعاء onCaptureSessionEnd قبل إغلاق CameraCaptureSession.
مناسب لـ الإضافات التي تم تنفيذها في طبقة تجريد الأجهزة (HAL) الخاصة بالكاميرا أو في معالج يعالج صور YUV
  • تتضمّن عمليات تنفيذ مستندة إلى Camera2 للإضافات.
  • بحاجة إلى إعدادات مخصّصة لمجموعة البث، مثل مجموعة البث RAW
  • يجب توفّر تسلسل لعملية الالتقاط التفاعلية.
إصدار واجهة برمجة التطبيقات المتوافق إضافات Camera2: الإصدار 13 من نظام التشغيل Android أو إصدار أحدث
إضافات CameraX: camera-extensions الإصدار 1.1.0 أو إصدار أحدث		 إضافات Camera2: الإصدار 12L من نظام التشغيل Android أو إصدار أحدث
إضافات CameraX: الإصدار camera-extensions 1.2.0-alpha03 أو إصدار أحدث

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

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

إضافات Camera2 إضافات CameraX
مدى توفّر إضافة طلب البحث CameraExtensionCharacteristics .getSupportedExtensions ExtensionsManager. isExtensionAvailable
معلومات طلب البحث CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys ExtensionsManager. getEstimatedCaptureLatencyRange

تتولّى CameraX معالجة بقية المعلومات داخل المكتبة.

المعاينة والتقاط صور ثابتة مع تفعيل الإضافة CameraDevice. createExtensionSession

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector

bindToLifecycle(lifecycleOwner, cameraSelector, preview, ...)

Basic Extender

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

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

فئات أدوات التوسيع التي يجب تنفيذها
ليلة NightPreviewExtenderImpl.java

NightImageCaptureExtenderImpl.java

HDR HdrPreviewExtenderImpl.java

HdrImageCaptureExtenderImpl.java

تلقائي AutoPreviewExtenderImpl.java

AutoImageCaptureExtenderImpl.java

تأثير البوكيه BokehPreviewExtenderImpl.java

BokehImageCaptureExtenderImpl.java

تجميل الوجه BeautyPreviewExtenderImpl.java

BeautyImageCaptureExtenderImpl.java

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

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

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

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

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

BasicExtenderAppFlow1

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

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

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

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

BasicExtenderAppFlow2

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

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

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

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

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

    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
    • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

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

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

BasicExtenderAppFlow3

الشكل 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 بغرض المعاينة.

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

PreviewProcessor

الشكل 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.

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

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

CaptureProcessor

الشكل 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 أدناه كمثال. في الإصدار 1.3.0 أو الإصدارات الأحدث من extensions-interface، يتم استدعاء المكالمة الثانية 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 برنامج تضمين أو طبقة وسيطة، ما يتيح لك تخصيص إعدادات البث وإرسال طلبات الالتقاط عند الطلب.

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

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

فئات الإضافات التي يجب تنفيذها
ليلة advanced/NightAdvancedExtenderImpl.java
HDR advanced/HdrAdvancedExtenderImpl.java
تلقائي advanced/AutoAdvancedExtenderImpl.java
تأثير البوكيه advanced/BokehAdvancedExtenderImpl.java
تجميل الوجه advanced/BeautyAdvancedExtenderImpl.java

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

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

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

AdvancedAppFlow1

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

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

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

AdvancedAppFlow2

الشكل 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: المعاينة/التقاط صورة ثابتة مع تفعيل الإضافة

AdvancedAppFlow3

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

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

  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 لتحليل محتوى الصورة، مثل العثور على رموز QR أو نص. لتحسين دعم حالة الاستخدام هذه، يجب توفير إمكانية دمج البث المباشر مع معاينة الفيديو والتقاط صور ثابتة وبث 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();

لإتاحة تقديرات وقت الاستجابة لالتقاط الصور الثابتة في الوقت الفعلي، عليك تنفيذ ما يلي:

عمليات معاودة الاتصال بشأن تقدّم عملية تسجيل البيانات

في نظام التشغيل 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
    }
  }
…
}

لإتاحة استخدام عمليات رد الاتصال الخاصة بتقدّم معالجة الالتقاط، يجب أن ينفّذ مورّد الإضافة عمليات رد الاتصال التالية مع قيمة التقدّم الحالية:

لقطة ما بعد المشاهدة

في نظام التشغيل 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();
…
}

لتوفير ميزة التقاط الصور الثابتة بعد انتهاء العرض، يجب أن يتضمّن تنفيذ المورّد ما يلي:

إتاحة إخراج SurfaceView

في نظام التشغيل Android 14 والإصدارات الأحدث، يمكن لبرامج الكاميرا التي تستخدم الإضافات استخدام مسارات عرض المعاينة المحسَّنة من حيث الطاقة والأداء من خلال تسجيل مثيل SurfaceView لإخراج المعاينة للطلبات المتكررة.

لإتاحة إخراج SurfaceView، يجب أن يكون تنفيذ إضافة المورّد قادرًا على بث المعاينة وإخراجها إلى مثيلات SurfaceView. للتأكّد من توفّر هذه الميزة، شغِّل وحدة SurfaceViewExtensionPreviewTest.java في مجموعة اختبار التوافق (CTS).

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

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

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

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

سجلّ إصدارات واجهة الإضافات

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

الإصدار الميزات التي تمّت إضافتها
1.0.0
  • التحقّق من الإصدار
    • ExtensionVersionImpl
  • Basic Extender
    • PreviewExtenderImpl
    • ImageCaptureExtenderImpl
    • Processor
      • PreviewImageProcessorImpl
      • CaptureProcessorImpl
      • RequestUpdateProcessorImpl
1.1.0
  • إعداد المكتبة
    • InitializerImpl
  • عرض درجات الدقة المتوافقة
    • PreviewExtenderImpl.getSupportedResolutions
    • ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0
  • AdvancedExtender
    • AdvancedExtenderImpl
    • SessionProcessorImpl
  • الحصول على وقت الاستجابة المقدَّر لعملية الالتقاط
    • ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0
  • عرض مفاتيح طلبات الالتقاط/نتائج الالتقاط المتوافقة
    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys وgetAvailableCaptureResultKeys
    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys وgetAvailableCaptureResultKeys
    • مكالمة process() جديدة تستغرق ProcessResultImpl في PreviewImageProcessorImpl وCaptureProcessorImpl
    • طلب نوع مشغّل الدعم
      • AdvancedExtenderImpl.startTrigger
1.4.0
  • البيانات الوصفية الخاصة بالإضافة
  • تقديرات وقت الاستجابة لالتقاط الصور الثابتة الديناميكية
  • عمليات معاودة الاتصال بشأن تقدّم عملية تسجيل البيانات
  • لقطة ما بعد المشاهدة
  • التوافق مع مخرجات SurfaceView
  • أنواع الجلسات الخاصة بالمورّد

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

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

لإعداد مكتبة الشركة المصنّعة للمعدّات الأصلية على جهاز، اتّبِع الخطوات التالية:

  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 أو الإصدارات الأحدث، يجب ضبط السمة ro.camerax.extensions.enabled على true في الأجهزة المتوافقة مع إضافات CameraX، ما يتيح الاستعلام عمّا إذا كان الجهاز متوافقًا مع الإضافات. لإجراء ذلك، أضِف السطر التالي في ملف تصنيع الجهاز:

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

التحقُّق

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

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

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

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

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

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

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

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

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

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