يمكن لمصنعي الأجهزة الكشف عن ملحقات مثل 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. تنفيذ التمديد الليلي
التحقق من الإصدار:
يستدعي Camera2/X
ExtensionVersionImpl.checkApiVersion()
للتأكد من أن إصدارextensions-interface
التي تم تنفيذها بواسطة OEM متوافق مع الإصدارات المدعومة من Camera2/X.تهيئة مكتبة البائع:
يحتوي
InitializerImpl
على طريقةinit()
التي تقوم بتهيئة مكتبة البائع. يكمل Camera2/X عملية التهيئة قبل الوصول إلى فئات Extender.إنشاء مثيل لفئات الموسع:
إنشاء مثيل لفئات الموسع للامتداد. هناك نوعان من الموسعات: الموسع الأساسي والموسع المتقدم. يجب عليك تنفيذ نوع موسع واحد لجميع الملحقات. لمزيد من المعلومات، راجع الموسع الأساسي مقابل الموسع المتقدم .
يقوم Camera2/X بإنشاء مثيلات لفئات الموسع والتفاعل معها لاسترداد المعلومات وتمكين الامتداد. بالنسبة لامتداد معين، يمكن لـ Camera2/X إنشاء مثيل لفئات الموسع عدة مرات. ونتيجة لذلك، لا تقم بإجراء تهيئة ثقيلة في المنشئ أو استدعاء
init()
. قم بالمهمة الثقيلة فقط عندما تكون جلسة الكاميرا على وشك البدء، كما هو الحال عند استدعاءonInit()
في Basic Extender أوinitSession()
في Advanced Extender.بالنسبة للملحق الليلي، يتم إنشاء فئات الموسع التالية لنوع الموسع الأساسي:
-
NightImageCaptureExtenderImpl.java
-
NightPreviewExtenderImpl.java
وبالنسبة لنوع الموسع المتقدم:
-
NightAdvancedExtenderImpl.java
-
التحقق من توفر الامتداد:
قبل تمكين الامتداد، يتحقق
isExtensionAvailable()
مما إذا كان الامتداد متاحًا على معرف الكاميرا المحدد من خلال مثيل الموسع.قم بتهيئة الموسع باستخدام معلومات الكاميرا:
يستدعي Camera2/X
init()
على مثيل Extender ويمرر إليه معرف الكاميرا وCameraCharacteristics
.معلومات الاستعلام:
يستدعي فئة الموسع لاسترداد معلومات مثل الحلول المدعومة، والاستمرار في التقاط زمن الاستجابة المقدر، والتقاط مفاتيح الطلب من الموسع استعدادًا لتمكين الامتداد.
تمكين الامتداد على الموسع:
توفر فئة الموسع كافة الواجهات اللازمة لتمكين الفئة. فهو يوفر آلية لربط تنفيذ 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 |
السنانير في خط أنابيب الكاميرا |
|
|
مناسب ل | الامتدادات المطبقة في الكاميرا HAL أو في المعالج الذي يعالج صور YUV. |
|
إصدار واجهة برمجة التطبيقات المدعومة | ملحقات 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 | val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector bindToLifecycle(lifecycleOwner, CameraSelector, Preview,...) |
الموسع الأساسي
توفر واجهة Basic Extender خطافات في عدة أماكن في مسار الكاميرا. يحتوي كل نوع ملحق على فئات الموسع المقابلة التي يحتاج مصنعو المعدات الأصلية إلى تنفيذها.
يسرد الجدول التالي فئات الموسعات التي يحتاج OEMs إلى تنفيذها لكل ملحق:
فئات موسع للتنفيذ | |
---|---|
ليلة | NightPreviewExtenderImpl.java |
تقرير التنمية البشرية | HdrPreviewExtenderImpl.java |
آلي | AutoPreviewExtenderImpl.java |
خوخه | BokehPreviewExtenderImpl.java |
تنميق الوجه | BeautyPreviewExtenderImpl.java |
نستخدم PreviewExtenderImpl
و ImageCaptureExtenderImpl
كعناصر نائبة في المثال التالي. استبدلها بأسماء الملفات الفعلية التي تقوم بتنفيذها.
يتمتع الموسع الأساسي بالقدرات التالية:
- أدخل معلمات الجلسة عند تكوين
CameraCaptureSession
(onPresetSession
). - أعلمك بأحداث بدء وإغلاق جلسة الالتقاط وأرسل طلبًا واحدًا لإخطار HAL باستخدام المعلمات التي تم إرجاعها (
onEnableSession
،onDisableSession
). - أدخل معلمات الالتقاط للطلب (
PreviewExtenderImpl.getCaptureStage
,ImageCaptureExtenderImpl.getCaptureStages
). - أضف معالجات للمعاينة واستمر في التقاط ما هو قادر على معالجة دفق
YUV_420_888
.
دعونا نرى كيف يستدعي Camera2/X extensions-interface
لتحقيق تدفقات التطبيقات الثلاثة المذكورة أعلاه.
تدفق التطبيق 1: التحقق من توفر الامتداد
الشكل 3. تدفق التطبيق 1 على الموسع الأساسي
في هذا التدفق، يستدعي Camera2/X مباشرة الأسلوب isExtensionAvailable()
لكل من PreviewExtenderImpl
و ImageCaptureExtenderImpl
دون استدعاء init()
. يجب أن تعود كلا فئتي الموسع إلى القيمة true
لتمكين الامتدادات.
غالبًا ما تكون هذه هي الخطوة الأولى للتطبيقات للتحقق مما إذا كان نوع الامتداد المحدد مدعومًا لمعرف كاميرا معين قبل تمكين الامتداد. وذلك لأن بعض الملحقات مدعومة فقط على معرفات كاميرا معينة.
تدفق التطبيق 2: معلومات الاستعلام
الشكل 4. تدفق التطبيق 2 على الموسع الأساسي
بعد تحديد ما إذا كان الامتداد متاحًا، يجب على التطبيقات الاستعلام عن المعلومات التالية قبل تمكين الامتداد.
نطاق زمن انتقال الالتقاط المستمر: يقوم
ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
بإرجاع نطاق زمن انتقال الالتقاط للتطبيق لتقييم ما إذا كان من المناسب تمكين الامتداد للسيناريو الحالي.الأحجام المدعومة لسطح المعاينة والالتقاط: يقوم
ImageCaptureExtenderImpl.getSupportedResolutions
وPreviewExtenderImpl.getSupportedResolutions
بإرجاع قائمة بتنسيقات الصور والأحجام المدعومة لتنسيق السطح وحجمه.مفاتيح الطلب والنتيجة المدعومة: يستدعي Camera2/X الطرق التالية لاسترداد مفاتيح طلب الالتقاط المدعومة ومفاتيح النتائج من التنفيذ الخاص بك:
-
ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
-
ImageCaptureExtenderImpl.getAvailableCapturetResultKeys
-
يقوم Camera2/X دائمًا باستدعاء init()
أولاً في فئات الموسع هذه قبل الاستعلام عن مزيد من المعلومات.
تدفق التطبيق 3: معاينة/التقاط الصور الثابتة مع تمكين الامتداد (تنفيذ HAL)
الشكل 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
يستخدم Camera2/X سطح تنسيق
YUV_420_888
لالتقاط الصور الثابتة لتكوين جلسة الالتقاط. يقوم Camera2/X بإعدادCaptureProcessorImpl
عن طريق الاتصال:-
CaptureProcessorImpl.onImageFormatUpdate()
معYUV_420_888
. -
CaptureProcessorImpl.onResolutionUpdate()
بحجم صورة الإدخال. -
CaptureProcessorImpl.onOutputSurface()
مع سطح الإخراجYUV_420_888
.
-
يقوم
ImageCaptureExtenderImpl.getCaptureStages
بإرجاع قائمةCaptureStageImpl
، حيث يتم تعيين كل عنصر إلى مثيلCaptureRequest
مع معلمات الالتقاط التي يتم إرسالها بواسطة Camera2/X. على سبيل المثال، إذا قامت بإرجاع قائمة بثلاثة مثيلاتCaptureStageImpl
، فإن Camera2/X يرسل ثلاثة طلبات التقاط مع معلمات الالتقاط المقابلة باستخدام واجهة برمجة تطبيقاتcaptureBurst
.يتم تجميع الصور المستلمة ومثيلات
TotalCaptureResult
معًا وإرسالها إلىCaptureProcessorImpl
للمعالجة.يقوم
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: التحقق من توفر الملحقات
الشكل 8. تدفق التطبيق 1 على Advanced Extender
أولاً، يتحقق التطبيق مما إذا كان الامتداد المحدد مدعومًا.
تدفق التطبيق 2: معلومات الاستعلام
الشكل 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: معاينة/التقاط الصور الثابتة مع تمكين الامتداد
الشكل 10. تدفق التطبيق 3 على Advanced Extender
يوضح الرسم البياني أعلاه التدفق الرئيسي لبدء المعاينة والتقاط نوع الموسع المتقدم. دعونا نسير خلال كل خطوة.
مثيل
SessionProcessorImpl
يتم تطبيق Advanced Extender الأساسي في
SessionProcessorImpl
، وهو المسؤول عن توفير تكوين جلسة مخصص وإرسال طلبات الالتقاط لبدء المعاينة وطلب الالتقاط المستمر. يتم استدعاءAdvancedExtenderImpl.createSessionProcessor()
لإرجاع مثيلSessionProcessorImpl
.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
.-
onCaptureSessionStart
وRequestProcessorImpl
عند بدء تشغيل
CameraCaptureSession
واستدعاء إطار عمل الكاميراonConfigured()
، يقوم Camera2/X باستدعاءSessionProcessorImpl.onCaptureSessionStart()
مع مجمّع طلب Camera2RequestProcessImpl
. يقوم Camera2/X بتنفيذRequestProcessImpl
، والذي يمكّنك من تنفيذ طلبات الالتقاط واسترداد الصور في حالة استخدامImageReaderOutputConfigImpl
.تشبه واجهات برمجة التطبيقات
RequestProcessImpl
واجهات برمجة التطبيقات Camera2CameraCaptureSession
من حيث تنفيذ الطلبات. الاختلافات هي:- يتم تحديد السطح المستهدف بواسطة معرف مثيل
Camera2OutputConfigImpl
. - إمكانية استرجاع الصورة من
ImageReader
.
يمكنك الاتصال بـ
RequestProcessorImpl.setImageProcessor()
باستخدام معرفCamera2OutputConfigImpl
المحدد لتسجيل مثيلImageProcessorImpl
لتلقي الصور.يصبح مثيل
RequestProcessImpl
غير صالح بعد استدعاء Camera2/XSessionProcessorImpl.onCaptureSessionEnd()
.- يتم تحديد السطح المستهدف بواسطة معرف مثيل
ابدأ المعاينة والتقط صورة
في تطبيق 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
.-
startTrigger
يتم استدعاء
SessionProcessorImpl.startTrigger()
لبدء المشغل مثلCaptureRequest.CONTROL_AF_TRIGGER
وCaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER
. يمكنك تجاهل أي مفاتيح طلب التقاط لم يتم الإعلان عنها فيAdvancedExtenderImpl.getAvailableCaptureRequestKeys()
.لقد تم دعم
startTrigger()
منذextensions-interface
1.3.0. فهو يمكّن التطبيقات من تنفيذ النقر للتركيز والفلاش مع الامتدادات.تنظيف
عند الانتهاء من جلسة الالتقاط، يتم استدعاء
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();
لدعم تقديرات زمن الاستجابة في الوقت الفعلي، قم بتنفيذ ما يلي:
- الملحقات الأساسية:
ImageCaptureExtenderImpl.getRealtimeCaptureLatency()
- الملحقات المتقدمة:
SessionProcessorImpl.getRealtimeCaptureLatency
التقاط عمليات الاسترجاعات تقدم المعالجة
بالنسبة إلى نظام التشغيل Android 14 والإصدارات الأحدث، يمكن لعملاء ملحق الكاميرا تلقي عمليات رد الاتصال لتقدم عمليات معالجة الالتقاط المستمر على المدى الطويل. يمكن للتطبيقات عرض التقدم الحالي للمستخدمين لتحسين تجربة المستخدم الشاملة.
يمكن للتطبيقات استخدام الكود التالي لدمج هذه الميزة:
import android.hardware.camera2.CameraExtensionSession.
ExtensionCaptureCallback;
{
…
class AppCallbackImpl extends ExtensionCaptureCallback {
…
@Override
public void onCaptureProcessProgressed(
@NonNull CameraExtensionSession session,
@NonNull CaptureRequest request,
@IntRange(from = 0, to = 100) int progress) {
// Update app UI with current progress
}
}
…
}
لدعم عمليات الاسترجاعات الخاصة بتقدم معالجة الالتقاط، يجب أن يقوم تنفيذ بائع الامتداد الخاص بك باستدعاء عمليات الاسترجاعات التالية بقيمة التقدم الحالية:
- الملحقات الأساسية:
ProcessResultImpl.onCaptureProcessProgressed()
- الملحقات المتقدمة:
CaptureCallback.onCaptureProcessProgressed()
لا يزال يتم التقاط 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();
…
}
لدعم الالتقاط المستمر للعرض اللاحق، يجب أن يقوم تنفيذ البائع الخاص بك بتنفيذ ما يلي:
الامتدادات الأساسية:
CaptureProcessorImpl.onPostviewOutputSurface
وCaptureProcessorImpl.processWithPostview
الملحقات المتقدمة:
SessionProcessorImpl.startCaptureWithPostview
دعم إخراج SurfaceView
بالنسبة لنظام التشغيل Android 14 والإصدارات الأحدث، يمكن لعملاء ملحق الكاميرا استخدام مسارات عرض المعاينة المحسنة للطاقة والأداء من خلال تسجيل مثيل SurfaceView
لمعاينة الإخراج للطلبات المتكررة.
لدعم إخراج SurfaceView
، يجب أن يكون تنفيذ ملحق البائع الخاص بك قادرًا على دفق وإخراج المعاينة إلى مثيلات SurfaceView
. للتحقق من دعم ذلك، قم بتشغيل وحدة SurfaceViewExtensionPreviewTest.java
CTS.
أنواع الجلسات الخاصة بالموردين
تتيح هذه الميزة لتطبيقات ملحق البائع تحديد نوع جلسة خاص بالمورد والذي سيتم تعيينه في جلسة التقاط الكاميرا الداخلية بدلاً من القيمة الافتراضية.
تعمل هذه الميزة بالكامل ضمن إطار العمل ومكدس البائع وليس لها أي تأثير مرئي على واجهة برمجة التطبيقات (API) الخاصة بالعميل/العامة.
لتحديد نوع جلسة خاص بالمورد، قم بتنفيذ ما يلي لمكتبات الملحقات الخاصة بك: * ExtenderStateListener.onSessionType()
للامتدادات الأساسية * Camera2SessionConfigImpl.getSessionType()
للامتدادات المتقدمة
تاريخ إصدار واجهة الإضافات
يعرض الجدول التالي سجل إصدار واجهة Camera Extension. يجب عليك دائمًا تنفيذ مكتبة البائع بأحدث إصدار.
إصدار | الميزات المضافة |
---|---|
1.0.0 |
|
1.1.0 |
|
1.2.0 |
|
1.3.0 |
|
1.4.0 |
|
التنفيذ المرجعي
تتوفر تطبيقات مكتبة موردي 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 على جهاز، قم بما يلي:
- قم بإضافة ملف إذن مطلوب بواسطة علامة
<uses-library>
، باستخدام التنسيق التالي:/etc/permissions/ ANY_FILENAME .xml
. على سبيل المثال،/etc/permissions/camera_extensions.xml
. توفر الملفات الموجودة في هذا الدليل تعيينًا للمكتبة المسماة في<uses-library>
لمسار الملف الفعلي على الجهاز. استخدم المثال أدناه لإضافة المعلومات المطلوبة إلى الملف.
- يجب أن يكون
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) .