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

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

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

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

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

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

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

كما هو موضّح في المخطّط البياني، لتفعيل الإضافات الخاصة بالكاميرا، عليك تنفيذ extensions-interface المقدَّمة من مكتبة المورّد الأصلي للجهاز. تفعِّل مكتبة المورّد الأصلي للجهاز واجهتَي برمجة تطبيقات: CameraX Extensions API و Camera2 Extensions API، اللتان يستخدمهما تطبيقا CameraX وCamera2 على التوالي للوصول إلى إضافات المورّد.

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

لتنفيذ مكتبة المورّد الأصلي للجهاز، انسخ ملفات 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 (نفِّذها إذا كانت إضافة Bokeh متوافقة)

  • BokehImageCaptureExtenderImpl.java
  • BokehPreviewExtenderImpl.java
  • advanced/BokehAdvancedExtenderImpl.java

فئات مُمدِّد وقت العروض الليلية (طبِّق هذه الفئات إذا كان وقت عرض "العروض الليلية" متوافقًا)

  • NightImageCaptureExtenderImpl.java
  • NightPreviewExtenderImpl.java
  • advanced/NightAdvancedExtenderImpl.java

فئات موسّعات المساحة التلقائية (طبِّقها إذا كانت ميزة "التوسيع التلقائي" متاحة)

  • AutoImageCaptureExtenderImpl.java
  • AutoPreviewExtenderImpl.java
  • advanced/AutoAdvancedExtenderImpl.java

فئات موسّعات النطاق العالي الديناميكية (HDR) (طبِّق هذه الفئات إذا كانت موسّعات النطاق العالي الديناميكية متوافقة)

  • 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 مع مكتبة المورّد لتفعيل إضافة. يوضّح المخطّط البياني التالي مسار المعالجة بالكامل باستخدام إضافة "الليل" كمثال:

Mainflow

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

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

    تتصل Camera2/X بـ ExtensionVersionImpl.checkApiVersion() لضمان توافق الإصدار extensions-interface الذي نفَّذه المصنّع الأصلي للجهاز مع الإصدارات المتوافقة مع Camera2/X.

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

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

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

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

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

    بالنسبة إلى إضافة "الليل"، يتم إنشاء مثيلات لفئات "الموسّع" التالية لنوع "الموسّع الأساسي":

    • NightImageCaptureExtenderImpl.java
    • NightPreviewExtenderImpl.java

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

    • NightAdvancedExtenderImpl.java

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

    قبل تفعيل الإضافة، يتحقّق isExtensionAvailable() مما إذا كانت الإضافة متاحة في معرّف الكاميرا المحدّد من خلال مثيل "موسّع نطاق الشبكة".

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

    تُجري Camera2/X مكالمة إلى init() في مثيل Extender وتُرسل إليه رقم تعريف الكاميرا وCameraCharacteristics.

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

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

  7. تفعيل الإضافة على الموسّع:

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

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

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

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

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

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

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

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

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

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

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

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

بدء مكتبة المورّد

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

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

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

موسّع المساحة التخزينية الأساسي مقارنةً بموسّع المساحة التخزينية المتقدّم

هناك نوعان من عمليات تنفيذ extensions-interface: "الموسّع الأساسي" و"الموسّع المتقدّم". تم توفير "الموسّع المتقدّم" منذ الإصدار extensions-interface 1.2.0.

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

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

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

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

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

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

مسارات المستخدمين في التطبيق

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

إضافات 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, ...)

موسّع ذاكرة التخزين الأساسي

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

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

فئات الموسّعات المطلوب تنفيذها
الليل NightPreviewExtenderImpl.java

NightImageCaptureExtenderImpl.java

HDR HdrPreviewExtenderImpl.java

HdrImageCaptureExtenderImpl.java

تلقائي AutoPreviewExtenderImpl.java

AutoImageCaptureExtenderImpl.java

تأثير "موهبة" BokehPreviewExtenderImpl.java

BokehImageCaptureExtenderImpl.java

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

BeautyImageCaptureExtenderImpl.java

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

تتوفر لـ "الموسّع الأساسي" الإمكانات التالية:

  • أدرِج مَعلمات الجلسة عند ضبط 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 على أداة التمديد الأساسية

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

  • نطاق وقت الاستجابة لالتقاط الصور الثابتة: 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.

  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 API جميع المفاتيح المذكورة أعلاه بشكل صريح. بالنسبة إلى الإصدار extensions-interface 1.3.0، يحترم كلّ من CameraX وCamera2 القائمة المعروضة ويتوافقان مع المفاتيح الواردة فيها فقط. على سبيل المثال، إذا قرّرت عرض CaptureRequest#CONTROL_ZOOM_RATIO وCaptureRequest#SCALER_CROP_REGION فقط في عملية التنفيذ 1.3.0، يعني ذلك أنّه لا يمكن استخدام ميزة التكبير/التصغير في التطبيق إلا أنّه لا يمكن استخدام ميزة النقر للتركيز والفلاش وميزة التعويض عن الإضاءة.

موسّع مساحة تخزين متقدّم

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

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

  • إمكانية إرسال طلبات Camera2: يجب أن تتيح هذه الواجهة منطق تفاعل معقدًا يمكنه إرسال طلبات التقاط الصور باستخدام مَعلمات استنادًا إلى نتائج الطلبات السابقة.

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

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

للتبديل إلى تنفيذ "الموسّع المتقدّم"، يجب أن تُعرِض isAdvancedExtenderImplemented() في ExtensionVersionImpl true. يجب أن تنفّذ المصنّعين الأصليّين للأجهزة فئات "الموسّع" المناسبة لكل نوع من أنواع الإضافات. يمكن العثور على ملفات تنفيذ "الموسّع المتقدّم" في حزمة 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 على أداة التمديد المتقدّمة

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

  1. مثيل SessionProcessorImpl

    يتم تنفيذ وظائف "الموسّع المتقدّم" الأساسية في 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 واستدعاء إطار عمل Camera لتحميل onConfigured()، يستدعي Camera2/X SessionProcessorImpl.onCaptureSessionStart() باستخدام RequestProcessImpl، وهو ملف لفِّ الطلبات في Camera2. تُنفِّذ Camera2/X واجهة برمجة التطبيقات RequestProcessImpl، التي تتيح لك تنفيذ طلبات الالتقاط، و استرداد الصور في حال استخدام واجهة برمجة التطبيقات ImageReaderOutputConfigImpl.

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

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

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

    تصبح نسخة RequestProcessImpl غير صالحة بعد أن تتصل Camera2/X SessionProcessorImpl.onCaptureSessionEnd().

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

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

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

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

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

    عندما يضبط المطوّرون المفاتيح في قائمة getAvailableCaptureRequestKeys، يجب تفعيل المَعلمات والتأكّد من أنّ نتيجة الالتقاط تحتوي على المفاتيح في قائمة 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.

بالنسبة إلى "الموسّع المتقدّم"، تُرسِل Camera2/X ثلاث مساحات عرض إلى دعوة SessionProcessorImpl.initSession(). وتكون مساحات العرض هذه مخصّصة لمعاينة الصور الثابتة وتحليلها وتصويرها، على التوالي. يجب التأكّد من أنّ مساحات عرض معاينة وتسجيل الشاشة تعرض النتيجة الصالحة. ومع ذلك، بالنسبة إلى مساحة عرض ناتج تحليل الصور، تأكَّد من أنّها تعمل فقط عندما تكون غير فارغة. إذا لم يكن بإمكان عملية التنفيذ استخدام بث تحليل الصور، يمكنك عرض قائمة فارغة في AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions(). يضمن ذلك أنّ سطح إخراج تحليل الصور يكون دائمًا فارغًا في SessionProcessorImpl.initSession().

إتاحة تسجيل الفيديو

لا تتيح بنية Camera Extension الحالية سوى حالات استخدام المعاينة والتصوير الساكن. لا نتيح تفعيل الإضافة على مساحتَي العرض MediaCodec أو MediaRecorder لتسجيل الفيديو. ومع ذلك، يمكن للتطبيقات تسجيل المحتوى الذي يتم عرضه في المعاينة.

نحن ننظر في إمكانية إتاحة مساحات العرض MediaCodec وMediaRecorder.

البيانات الوصفية الخاصة باإضافة

في الإصدار 14 من نظام التشغيل Android والإصدارات الأحدث، تتيح البيانات الوصفية الخاصة بالإضافة لعملاء إضافات الكاميرا ضبط إعدادات طلب التقاط الصور والحصول عليها، وذلك حسب نوع الإضافة. على وجه التحديد، يمكن لعملاء إضافة الكاميرا استخدام المَعلمة 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.

تقدير وقت الاستجابة لالتقاط الصور الثابتة في الوقت الفعلي

في الإصدار 14 من نظام التشغيل Android والإصدارات الأحدث، يمكن لعملاء الإضافات التي تتعامل مع الكاميرا الاستعلام عن تقديرات وقت استجابة التقاط الصور الثابتة في الوقت الفعلي استنادًا إلى المشهد و ظروف البيئة باستخدام 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();

لتفعيل تقديرات وقت الاستجابة لالتقاط الصور الثابتة في الوقت الفعلي، نفِّذ يلي:

تسجيل عمليات تسجيل المكالمات لرصد مستوى التقدّم في المعالجة

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

يمكن للتطبيقات استخدام الرمز البرمجي التالي لدمج هذه الميزة:

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
    }
  }
…
}

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

التقاط لقطة ثابتة للإجراء بعد المشاهدة

في الإصدار 14 من نظام التشغيل Android والإصدارات الأحدث، يمكن لإضافات الكاميرا توفير معاينة بعد الالتقاط (صورة المعاينة) باستخدام 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

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

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

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

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

تعمل الميزة بالكامل ضمن إطار العمل ومجموعة المورّدين، ولا تؤثّر في واجهة برمجة التطبيقات الظاهرة للعملاء أو للجمهور.

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

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

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

الإصدار الميزات المُضافة
1.0.0
  • التحقّق من الإصدار
    • ExtensionVersionImpl
  • موسّع المساحة الأساسي
    • 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: مكتبة المصنّعين الأصليّين للأجهزة (OEM) لإضافات الكاميرا لواجهات برمجة التطبيقات Camera2 وCameraX Extensions API التي تنفِّذ Extensions-Interface ويعمل هذا الإجراء كآلية توجيه تهدف إلى إعادة توجيه المكالمات من Extensions-Interface إلى الخدمة. توفّر هذه المكتبة أيضًا ملفات AIDL وفئات ملفّات التفاف للتواصل مع الخدمة.

      يكون "الموسّع المتقدّم" مفعَّلاً تلقائيًا. لتفعيل "الموسّع الأساسي"، غيِّر 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 نفسها أثناء التشغيل.

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

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

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

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