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

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

للحصول على قائمة بالإضافات المتوافقة، وهي نفسها على قسم "كاميرا2" والكاميراX، يمكنك مراجعة واجهة برمجة تطبيقات إضافات CameraX إذا كنت ترغب في تثبيت إضافة، الإبلاغ عن الخطأ باستخدام أداة تتبُّع المشاكل

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

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

يوضِّح المخطّط البياني التالي بنية "إضافات الكاميرا". أو extensions-interface: هندسة معمارية

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

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

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

لتنفيذ مكتبة مورّدي المصنّعين الأصليين، انسخ camera-extensions-stub الملفات في مشروع مكتبة النظام. تحدِّد هذه الملفات إضافات الكاميرا. من واجهة pyplot.

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 تُبلِغ واجهات برمجة التطبيقات للتطبيق بأنّ الإضافة غير متاحة.

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

التدفق الرئيسي

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

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

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

  2. إعداد مكتبة المورّدين:

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

  3. فئات Extendiate:

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

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

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

    • NightImageCaptureExtenderImpl.java
    • NightPreviewExtenderImpl.java

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

    • NightAdvancedExtenderImpl.java

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

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

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

    يتصل تطبيق Camera2/X بـ init() على مثيل Extender ويمرره إلى الكاميرا. المعرّف وCameraCharacteristics.

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

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

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

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

    بالنسبة إلى نوع الموسِّع المتقدّم، تتفاعل الكاميرا2/X مع SessionProcessorImpl لتفعيل الإضافة. تسترد الكاميرا2/X ملف حدث SessionProcessorImpl من خلال استدعاء createSessionProcessor() على موسِّع مساحة تخزين

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

التحقق من النسخة

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

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

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

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

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

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

الموسع الأساسي مقابل الموسع المتقدم

هناك نوعان من تنفيذ extensions-interface: الموسِّع الأساسي موسِّع متقدّم أصبح الموسِّع المتقدّم متاحًا منذ extensions-interface 1.2.0.

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

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

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

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

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

عناصر الجذب في مسار الكاميرا
  • توفّر الدالة onPresetSession مَعلمات الجلسة.
  • يرسل "onEnableSession" طلبًا واحدًا بعد إعداد CameraCaptureSession مباشرةً.
  • يرسل "onDisableSession" طلبًا واحدًا قبل إغلاق CameraCaptureSession.
  • يقوم initSession بإعداد وعرض كاميرا مخصصة2 تهيئة الجلسة لإنشاء جلسة التسجيل.
  • يتم استدعاء 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 أو أعلى

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

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

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

تعالج الكاميرا بقية المعلومات داخل المكتبة.

المعاينة والالتقاط بعد تفعيل الإضافة 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"

لنرَ كيف يستدعي كاميرا 2/X السمة extensions-interface للوصول إلى القيم الثلاثة مسارات التطبيقات المذكورة أعلاه.

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

BasicExtenderAppFlow1

الشكل 3. تدفق التطبيق 1 في الموسِّع الأساسي

في هذا التدفق، تستدعي Camera2/X طريقة isExtensionAvailable() كل من PreviewExtenderImpl وImageCaptureExtenderImpl بدون اتصال init() يجب أن تعرض كلتا فئتَي الموسِّع 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 في الموسِّع الأساسي

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

    • "CaptureProcessorImpl.onImageFormatUpdate()" مع "YUV_420_888"
    • CaptureProcessorImpl.onResolutionUpdate() بحجم صورة الإدخال.
    • CaptureProcessorImpl.onOutputSurface() مع الناتج YUV_420_888 السطح.

  2. تعرض الدالة ImageCaptureExtenderImpl.getCaptureStages قائمة CaptureStageImpl ، حيث يتم ربط كل عنصر بمثيل CaptureRequest يتضمّن معلَمات الالتقاط التي ترسلها كاميرا 2/X على سبيل المثال، إذا عرضت قائمة من ثلاثة CaptureStageImpl أمثلة، يرسل تطبيق Camera2/X ثلاثة طلبات لالتقاط الصور باستخدام معلمات الالتقاط المقابلة باستخدام captureBurst واجهة برمجة التطبيقات.

  3. تم تجميع الصور التي تم استلامها وTotalCaptureResult نسخة معًا وإرسالها إلى CaptureProcessorImpl لمعالجتها.

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

دعم مفاتيح ونتائج طلب الالتقاط

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

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

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

في حال معالجة طبقة تجريد الأجهزة (HAL) للكاميرا للإضافة، تسترد الكاميرا2/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
  • فلاش:
    • CaptureRequest#CONTROL_AE_MODE
    • CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
    • CaptureRequest#FLASH_MODE
  • التعويض عن التعرّض لفيروس كورونا:
    • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

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

موسِّع متقدّم

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

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

  • إمكانية إرسال طلبات الكاميرا 2: إتاحة تفاعل معقد يمكنه إرسال طلبات التقاط باستخدام المعاملات بناءً على نتائج الطلبات السابقة.

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

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

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

تمديد الفئات للتنفيذ
ليلاً advanced/NightAdvancedExtenderImpl.java
نطاق عالي الديناميكية (HDR) advanced/HdrAdvancedExtenderImpl.java
تلقائي advanced/AutoAdvancedExtenderImpl.java
ضبابي advanced/BokehAdvancedExtenderImpl.java
تجميل الوجه advanced/BeautyAdvancedExtenderImpl.java

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

لنرَ كيف يستدعي كاميرا 2/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

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

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

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

  3. onCaptureSessionStart وRequestProcessorImpl

    عند بدء CameraCaptureSession واستدعاء إطار عمل الكاميرا onConfigured()، ثم يستدعي Camera2/X. SessionProcessorImpl.onCaptureSessionStart() مع طلب Camera2 برنامج تضمين RequestProcessImpl. يتم تنفيذ 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

بالنسبة إلى الموسِّع المتقدِّم، تمرِّر الكاميرا2/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 من مكتبة الإضافات من واجهة pyplot. لمزيد من المعلومات، يُرجى مراجعة 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
  • موسِّع أساسي
    • PreviewExtenderImpl
    • ImageCaptureExtenderImpl
    • Processor
      • PreviewImageProcessorImpl
      • CaptureProcessorImpl
      • RequestUpdateProcessorImpl
1.1.0
  • إعداد المكتبة
    • InitializerImpl
  • عرض درجات الدقة المتوافقة
    • PreviewExtenderImpl.getSupportedResolutions
    • ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0
  • موسع متقدم
    • 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-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 في وقت التشغيل

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

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

التحقُّق

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

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

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

بالنسبة إلى امتداد الخلفية الضبابية، وبالإضافة إلى تعريضه للضوء باستخدام إضافات الكاميرا، يمكنك عرض الإضافة باستخدام وضع المشهد الممتد، والذي يتم تفعيله من خلال الـ CONTROL_EXTENDED_SCENE_MODE المفتاح. لمزيد من تفاصيل التنفيذ، يُرجى الاطّلاع على تعتيم الكاميرا.

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

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

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

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

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

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