ملحقات الكاميرا

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

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

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

بنيان

يصف الرسم البياني التالي بنية واجهة ملحقات الكاميرا أو extensions-interface : بنيان

الشكل 1. مخطط بنية ملحقات الكاميرا

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

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

لتنفيذ مكتبة بائع OEM، انسخ ملفات camera-extensions-stub إلى مشروع مكتبة النظام. تحدد هذه الملفات واجهة ملحقات الكاميرا.

تنقسم ملفات 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 (نفذها إذا كان امتداد HDR مدعومًا)

  • HdrImageCaptureExtenderImpl.java
  • HdrPreviewExtenderImpl.java
  • advanced/HdrAdvancedExtenderImpl.java

فئات موسع Face Retouch (نفذها إذا كان ملحق Face Retouch مدعومًا)

  • BeautyImageCaptureExtenderImpl.java
  • BeautyPreviewExtenderImpl.java
  • advanced/BeautyAdvancedExtenderImpl.java

المرافق (اختياري، يمكن حذفها)

  • advanced/Camera2OutputConfigImplBuilder.java
  • advanced/Camera2SessionConfigImplBuilder.java

ليس مطلوبًا منك توفير تطبيق لكل ملحق. إذا لم تقم بتنفيذ ملحق، فقم بتعيين isExtensionAvailable() لإرجاع false أو إزالة فئات الموسع المقابلة. تقوم واجهات برمجة تطبيقات Camera2 وCameraX Extensions API بإبلاغ التطبيق بأن الامتداد غير متاح.

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

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

الشكل 2. تنفيذ التمديد الليلي

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

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

  2. تهيئة مكتبة البائع:

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

  3. إنشاء مثيل لفئات الموسع:

    إنشاء مثيل لفئات الموسع للامتداد. هناك نوعان من الموسعات: الموسع الأساسي والموسع المتقدم. يجب عليك تنفيذ نوع موسع واحد لجميع الملحقات. لمزيد من المعلومات، راجع الموسع الأساسي مقابل الموسع المتقدم .

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

    بالنسبة للملحق الليلي، يتم إنشاء فئات الموسع التالية لنوع الموسع الأساسي:

    • NightImageCaptureExtenderImpl.java
    • NightPreviewExtenderImpl.java

    وبالنسبة لنوع الموسع المتقدم:

    • NightAdvancedExtenderImpl.java
  4. التحقق من توفر الامتداد:

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

  5. قم بتهيئة الموسع باستخدام معلومات الكاميرا:

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

  6. معلومات الاستعلام:

    يستدعي فئة الموسع لاسترداد معلومات مثل الحلول المدعومة، والاستمرار في التقاط زمن الاستجابة المقدر، والتقاط مفاتيح الطلب من الموسع استعدادًا لتمكين الامتداد.

  7. تمكين الامتداد على الموسع:

    توفر فئة الموسع كافة الواجهات اللازمة لتمكين الفئة. فهو يوفر آلية لربط تنفيذ OEM في مسار Camera2 مثل إدخال معلمات طلب الالتقاط أو تمكين معالج النشر.

    بالنسبة لنوع الموسع المتقدم، يتفاعل Camera2/X مع SessionProcessorImpl لتمكين الامتداد. يسترد Camera2/X مثيل SessionProcessorImpl عن طريق استدعاء createSessionProcessor() على الموسع.

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

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

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

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

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

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

التوافق

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

التوافق إلى الأمام

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

تهيئة مكتبة البائع

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

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

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

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

هناك نوعان من تنفيذ extensions-interface : الموسع الأساسي والموسع المتقدم. تم دعم Advanced Extender منذ extensions-interface 1.2.0.

قم بتطبيق Basic Extender للملحقات التي تعالج الصور في كاميرا HAL أو تستخدم معالجًا لاحقاً قادرًا على معالجة تدفقات YUV.

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

انظر الجدول التالي للمقارنة:

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

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

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

تدفقات التطبيق

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

ملحقات الكاميرا 2 ملحقات كاميرا اكس
توفر ملحق الاستعلام CameraExtensionCharacteristics . getSupportedExtensions ExtensionsManager. isExtensionAvailable
معلومات الاستعلام CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys احصل على خصائص ملحقة الكاميرا CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys ExtensionsManager. getEstimatedCaptureLatencyRange

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

المعاينة والتقاط الصور الثابتة مع تمكين الامتداد CameraDevice. createExtensionSession

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector bindToLifecycle(lifecycleOwner, CameraSelector, Preview,...)

الموسع الأساسي

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

يسرد الجدول التالي فئات الموسعات التي يحتاج OEMs إلى تنفيذها لكل ملحق:

فئات موسع للتنفيذ
ليلة NightPreviewExtenderImpl.java

NightImageCaptureExtenderImpl.java

تقرير التنمية البشرية 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 على الموسع الأساسي

في هذا التدفق، يستدعي 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() أولاً في فئات الموسع هذه قبل الاستعلام عن مزيد من المعلومات.

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

الموسع المتقدم

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

  • تكوين التدفق المخصص: قم بتكوين التدفقات المخصصة مثل تدفق RAW أو احصل على تدفقات متعددة لمعرفات الكاميرا الفعلية المختلفة.

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

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

ملفات للتنفيذ

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

فئات موسع للتنفيذ
ليلة advanced/NightAdvancedExtenderImpl.java
تقرير التنمية البشرية advanced/HdrAdvancedExtenderImpl.java
آلي advanced/AutoAdvancedExtenderImpl.java
خوخه advanced/BokehAdvancedExtenderImpl.java
تنميق الوجه advanced/BeautyAdvancedExtenderImpl.java

نحن نستخدم AdvancedExtenderImpl كعنصر نائب في المثال التالي. استبدله باسم ملف الموسع للملحق الذي تقوم بتنفيذه.

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

تدفق التطبيق 1: التحقق من توفر الملحقات

تدفق التطبيقات المتقدم1

الشكل 8. تدفق التطبيق 1 على Advanced Extender

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

تدفق التطبيق 2: معلومات الاستعلام

AdvancedAppFlow2

الشكل 9. تدفق التطبيق 2 على Advanced Extender

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

  • زمن استجابة الالتقاط المقدر: يقوم AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() بإرجاع نطاق زمن انتقال الالتقاط للتطبيق لتقييم ما إذا كان من المناسب تمكين الامتداد للسيناريو الحالي.

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

    • يقوم AdvancedExtenderImpl.getSupportedPreviewOutputResolutions() بإرجاع خريطة تنسيق الصورة إلى قائمة الأحجام المدعومة لمعاينة تنسيق السطح وحجمه. يجب أن تدعم الشركات المصنعة للمعدات الأصلية التنسيق PRIVATE على الأقل.

    • يقوم AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() بإرجاع التنسيق والأحجام المدعومة لسطح الالتقاط الثابت. يجب أن تدعم الشركات المصنعة للمعدات الأصلية (OEM) كلاً من تنسيقات الإخراج JPEG و YUV_420_888 .

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

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

    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
    • AdvancedExtenderImpl.getAvailableCaptureResultKeys

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

تدفق التطبيق 3: معاينة/التقاط الصور الثابتة مع تمكين الامتداد

تدفق التطبيقات المتقدم3

الشكل 10. تدفق التطبيق 3 على Advanced Extender

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

  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 واجهات برمجة التطبيقات Camera2 CameraCaptureSession من حيث تنفيذ الطلبات. الاختلافات هي:

    • يتم تحديد السطح المستهدف بواسطة معرف مثيل 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 . يدعم 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() منذ extensions-interface 1.3.0. فهو يمكّن التطبيقات من تنفيذ النقر للتركيز والفلاش مع الامتدادات.

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

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

لا يزال يتم التقاط Postview

بالنسبة لنظام التشغيل 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.

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

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

تعمل هذه الميزة بالكامل ضمن إطار العمل ومكدس البائع وليس لها أي تأثير مرئي على واجهة برمجة التطبيقات (API) الخاصة بالعميل/العامة.

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

تاريخ إصدار واجهة الإضافات

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

إصدار الميزات المضافة
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
  • البيانات الوصفية الخاصة بالامتداد
  • لا تزال ديناميكية تلتقط تقديرات زمن الوصول
  • التقاط عمليات الاسترجاعات تقدم المعالجة
  • لا يزال يتم التقاط Postview
  • دعم إخراج SurfaceView
  • أنواع الجلسات الخاصة بالموردين

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

تتوفر تطبيقات مكتبة موردي OEM المرجعية التالية في frameworks/ex .

  • advancedSample : تطبيق أساسي للموسع المتقدم.

  • sample : تطبيق أساسي للموسع الأساسي.

  • service_based_sample : تطبيق يوضح كيفية استضافة ملحقات الكاميرا في Service . يحتوي هذا التنفيذ على المكونات التالية:

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

      يتم تمكين "الموسع المتقدم" بشكل افتراضي. لتمكين الموسع الأساسي، قم بتغيير ExtensionsVersionImpl#isAdvancedExtenderImplemented لإرجاع false .

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

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

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

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

لإعداد مكتبة OEM على جهاز، قم بما يلي:

  1. قم بإضافة ملف إذن مطلوب بواسطة علامة <uses-library> ، باستخدام التنسيق التالي: /etc/permissions/ ANY_FILENAME .xml . على سبيل المثال، /etc/permissions/camera_extensions.xml . توفر الملفات الموجودة في هذا الدليل تعيينًا للمكتبة المسماة في <uses-library> لمسار الملف الفعلي على الجهاز.
  2. استخدم المثال أدناه لإضافة المعلومات المطلوبة إلى الملف.

    • يجب أن يكون name androidx.camera.extensions.impl لأن هذه هي المكتبة التي يبحث عنها CameraX.
    • file هو المسار المطلق للملف الذي يحتوي على تطبيق الامتدادات (على سبيل المثال، /system/framework/androidx.camera.extensions.impl.jar ).
    <?xml version="1.0" encoding="utf-8"?>
    <permissions>
        <library name="androidx.camera.extensions.impl"
                 file="OEM_IMPLEMENTED_JAR" />
    </permissions>
    

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

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

تصديق

لاختبار تنفيذك لمكتبة بائعي OEM أثناء مرحلة التطوير، استخدم التطبيق النموذجي على androidx-main/camera/integration-tests/extensionstestapp/ ، والذي يعمل من خلال ملحقات البائعين المختلفة.

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

وضع المشهد الممتد مقابل ملحقات الكاميرا

بالنسبة لامتداد البوكيه، بالإضافة إلى تعريضه باستخدام ملحقات الكاميرا، يمكنك تعريض الامتداد باستخدام وضع المشهد الممتد، والذي يتم تمكينه من خلال مفتاح CONTROL_EXTENDED_SCENE_MODE . لمزيد من تفاصيل التنفيذ، راجع Camera Bokeh .

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

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

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

الأسئلة المتداولة (الأسئلة الشائعة)

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

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