پسوند دوربین

سازندگان دستگاه‌ها می‌توانند افزونه‌هایی مانند بوکه، حالت شب و HDR را از طریق رابط برنامه‌های افزودنی دوربین ارائه‌شده توسط کتابخانه فروشنده OEM در اختیار توسعه‌دهندگان شخص ثالث قرار دهند. توسعه دهندگان می توانند از Camera2 Extensions API و CameraX Extensions API برای دسترسی به برنامه های افزودنی پیاده سازی شده در کتابخانه فروشنده OEM استفاده کنند.

برای لیستی از برنامه‌های افزودنی پشتیبانی‌شده، که در Camera2 و CameraX یکسان است، CameraX Extensions API را ببینید. اگر می‌خواهید پسوندی اضافه کنید، یک اشکال را با ردیاب مشکل ثبت کنید.

این صفحه نحوه پیاده سازی و فعال کردن کتابخانه فروشنده OEM را در دستگاه ها شرح می دهد.

معماری

نمودار زیر معماری رابط یا extensions-interface افزودنی دوربین را شرح می‌دهد:

شکل 1. نمودار معماری Extensions دوربین

همانطور که در نمودار نشان داده شده است، برای پشتیبانی از برنامه های افزودنی دوربین، باید extensions-interface ارائه شده توسط کتابخانه فروشنده OEM را پیاده سازی کنید. کتابخانه فروشنده OEM شما دو API را فعال می‌کند: CameraX Extensions API و Camera2 Extensions API که به ترتیب توسط برنامه‌های CameraX و Camera2 برای دسترسی به برنامه‌های افزودنی فروشنده استفاده می‌شوند.

کتابخانه فروشنده OEM را پیاده سازی کنید

برای پیاده سازی کتابخانه فروشنده OEM، فایل های camera-extensions-stub را در پروژه کتابخانه سیستم کپی کنید. این فایل ها رابط برنامه افزودنی دوربین را تعریف می کنند.

توجه: باید فایل ها را در بسته های جاوا androidx.camera.extensions.impl نگه دارید. برای مرجع، نمونه پروژه را ببینید.

فایل های 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

کلاس های توسعه دهنده بوکه (اگر برنامه افزودنی بوکه پشتیبانی می شود، آن را اجرا کنید)

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

کلاس های توسعه دهنده شب (اگر Night extension پشتیبانی می شود، آن را اجرا کنید)

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

کلاس های توسعه دهنده خودکار (اگر پسوند خودکار پشتیبانی می شود، آن را اجرا کنید)

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

کلاس های توسعه دهنده HDR (اگر پسوند HDR پشتیبانی می شود، آن را اجرا کنید)

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

کلاس‌های توسعه‌دهنده روتوش چهره (اگر برنامه افزودنی روتوش چهره پشتیبانی می‌شود، آن را اجرا کنید)

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

برنامه های کاربردی (اختیاری، قابل حذف است)

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

برای هر برنامه افزودنی نیازی به ارائه یک پیاده سازی نیست. اگر افزونه ای را پیاده سازی نمی کنید، isExtensionAvailable() را تنظیم کنید تا false برگرداند یا کلاس های Extender مربوطه را حذف کنید. APIهای Camera2 و CameraX Extensions به برنامه گزارش می دهند که برنامه افزودنی در دسترس نیست.

توجه: از آنجا که کتابخانه فروشنده OEM به عنوان بخشی از فرآیند برنامه شخص ثالث اجرا می شود، کتابخانه فروشنده نباید به مجوزهای خاصی (مانند مجوزهای سیستم) نیاز داشته باشد.

بیایید نحوه تعامل APIهای Camera2 و CameraX Extensions با کتابخانه فروشنده را برای فعال کردن یک برنامه افزودنی بررسی کنیم. نمودار زیر جریان انتها به انتها را با استفاده از پسوند Night به عنوان مثال نشان می دهد:

شکل 2. اجرای برنامه افزودنی شب

توجه: برای راحتی کار، ما به Camera2 و CameraX Extensions API به عنوان Camera2/X اشاره می کنیم.

1. تایید نسخه:

   Camera2/X ExtensionVersionImpl.checkApiVersion() را فراخوانی می کند تا اطمینان حاصل کند که نسخه extensions-interface پیاده سازی شده توسط OEM با نسخه های پشتیبانی شده Camera2/X سازگار است.

2. مقداردهی اولیه کتابخانه فروشنده:

   InitializerImpl دارای یک متد init() است که کتابخانه فروشنده را مقداردهی اولیه می کند. Camera2/X قبل از دسترسی به کلاس های Extender، مقداردهی اولیه را تکمیل می کند.

3. کلاس های Instantiate Extender:

   کلاس های Extender را برای برنامه افزودنی نمونه سازی می کند. دو نوع Extender وجود دارد: Basic Extender و Advanced Extender. شما باید یک نوع Extender را برای همه افزونه ها پیاده سازی کنید. برای اطلاعات بیشتر، به Basic Extender در مقابل Advanced Extender مراجعه کنید.

   Camera2/X کلاس های Extender را برای بازیابی اطلاعات و فعال کردن برنامه افزودنی نمونه سازی می کند و با آنها تعامل می کند. برای یک پسوند معین، Camera2/X می‌تواند چندین بار کلاس‌های Extender را نمونه‌سازی کند. در نتیجه، مقداردهی اولیه را در سازنده یا فراخوانی init() init انجام ندهید. کارهای سنگین را فقط زمانی انجام دهید که جلسه دوربین در شرف شروع است، مانند زمانی که onInit() در Basic Extender یا initSession() در Advanced Extender فراخوانی می شود.

   برای افزونه Night، کلاس‌های Extender زیر برای نوع Basic Extender نمونه‌سازی شده‌اند:

   • NightImageCaptureExtenderImpl.java
   • NightPreviewExtenderImpl.java

   و برای نوع Advanced Extender:

   • NightAdvancedExtenderImpl.java

4. بررسی در دسترس بودن برنامه افزودنی:

   قبل از فعال کردن برنامه افزودنی، isExtensionAvailable() بررسی می کند که آیا برنامه افزودنی در شناسه دوربین مشخص شده از طریق نمونه Extender موجود است یا خیر.

5. برنامه توسعه دهنده را با اطلاعات دوربین راه اندازی کنید:

   Camera2/X init() در نمونه Extender فراخوانی می کند و شناسه دوربین و CameraCharacteristics را به آن ارسال می کند.

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

   کلاس Extender را فراخوانی می‌کند تا اطلاعاتی مانند وضوح‌های پشتیبانی‌شده، هنوز هم زمان تأخیر تخمینی را ضبط کند و کلیدهای درخواست را از Extender در آماده‌سازی برای فعال کردن برنامه افزودنی بازیابی کند.

7. فعال کردن افزونه در Extender:

   کلاس Extender تمام رابط های مورد نیاز برای فعال کردن کلاس را فراهم می کند. مکانیزمی را برای قلاب کردن اجرای OEM به خط لوله Camera2 ارائه می دهد، مانند تزریق پارامترهای درخواست ضبط یا فعال کردن یک پردازشگر پست.

   برای نوع Advanced Extender، Camera2/X با SessionProcessorImpl تعامل دارد تا برنامه افزودنی را فعال کند. Camera2/X نمونه SessionProcessorImpl با فراخوانی createSessionProcessor() در Extender بازیابی می کند.

بخش‌های زیر جریان گسترش را با جزئیات بیشتری شرح می‌دهند.

تایید نسخه

هنگام بارگیری کتابخانه فروشنده OEM از دستگاه در زمان اجرا، Camera2/X بررسی می کند که آیا کتابخانه با نسخه extensions-interface سازگار است یا خیر. extensions-interface از نسخه‌سازی معنایی یا MAJOR.MINOR.PATCH برای مثال 1.1.0 یا 1.2.0 استفاده می‌کند. با این حال، تنها نسخه اصلی و فرعی در تأیید نسخه استفاده می شود.

برای تأیید نسخه، Camera2/X ExtensionVersionImpl.checkApiVersion() را با نسخه extensions-interface پشتیبانی شده فراخوانی می کند. Camera2/X سپس از نسخه گزارش شده توسط کتابخانه OEM استفاده می کند تا تعیین کند که آیا برنامه افزودنی می تواند فعال شود و چه قابلیت هایی باید فراخوانی کند.

توجه: checkApiVersion() نباید نسخه extensions-interface را که جدیدتر از نسخه پشتیبانی شده Camera2/X است را برگرداند. به عنوان مثال، اگر Camera2/X از 1.3.0 پشتیبانی می کند و کتابخانه فروشنده OEM از 1.4.0 پشتیبانی می کند، باید به جای 1.4.0، 1.3.0 را برگرداند.

سازگاری نسخه اصلی

اگر نسخه‌های اصلی رابط-افزونه بین 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 بستگی دارد. اگر برای پیاده‌سازی برنامه‌های افزودنی به برخی ویژگی‌ها نیاز دارید، ممکن است بخواهید برنامه‌های افزودنی را از یک نسخه خاص فعال کنید. در این مورد، زمانی که نسخه کتابخانه Camera2/X شرایط را برآورده می کند، می توانید نسخه extensions-interface پشتیبانی شده را برگردانید. اگر نسخه‌های 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 وجود دارد: توسعه دهنده پایه و توسعه دهنده پیشرفته. توسعه دهنده پیشرفته از extensions-interface 1.2.0 پشتیبانی شده است.

Basic Extender را برای برنامه‌های افزودنی که تصاویر را در دوربین HAL پردازش می‌کنند یا از یک پردازشگر پستی که قادر به پردازش جریان‌های YUV است، استفاده کنید.

برای برنامه‌های افزودنی که نیاز به سفارشی کردن پیکربندی جریان Camera2 و ارسال درخواست‌های عکسبرداری در صورت نیاز دارند، Advanced Extender را اجرا کنید.

برای مقایسه به جدول زیر مراجعه کنید:

	توسعه دهنده پایه	توسعه دهنده پیشرفته
تنظیمات جریان	ثابت شد پیش نمایش: PRIVATE یا YUV_420_888 (در صورت وجود پردازنده) عکسبرداری همچنان: JPEG یا YUV_420_888 (در صورت وجود پردازنده)	قابل تنظیم توسط OEM.
ارسال درخواست ضبط	فقط Camera2/X می تواند درخواست عکسبرداری ارسال کند. شما می توانید پارامترها را برای این درخواست ها تنظیم کنید. هنگامی که پردازنده برای ضبط تصویر ارائه می شود، Camera2/X می تواند چندین درخواست عکسبرداری ارسال کند و تمام تصاویر و نتایج ضبط را برای پردازنده ارسال کند.	یک نمونه RequestProcessorImpl برای اجرای درخواست عکسبرداری camera2 و دریافت نتایج و تصویر در اختیار شما قرار می گیرد. Camera2/X startRepeating و startCapture در SessionProcessorImpl فراخوانی می‌کند تا به OEM سیگنال دهد تا درخواست تکراری برای پیش‌نمایش را شروع کند و دنباله ضبط ثابت را شروع کند.
قلاب در خط لوله دوربین	onPresetSession پارامترهای جلسه را ارائه می دهد. onEnableSession بلافاصله پس از پیکربندی CameraCaptureSession یک درخواست را ارسال می کند. onDisableSession یک درخواست را قبل از بسته شدن CameraCaptureSession ارسال می کند.	initSession پیکربندی جلسه دوربین2 سفارشی را برای ایجاد جلسه ضبط مقداردهی اولیه می کند و برمی گرداند. onCaptureSessionStart درست پس از پیکربندی CameraCaptureSession فراخوانی می شود. onCaptureSessionEnd قبل از بسته شدن CameraCaptureSession فراخوانی می شود.
مناسب برای	برنامه‌های افزودنی که در دوربین HAL یا پردازنده‌ای که تصاویر YUV را پردازش می‌کند، پیاده‌سازی شده‌اند.	دارای پیاده سازی های مبتنی بر Camera2 برای برنامه های افزودنی. به پیکربندی جریان سفارشی مانند جریان RAW نیاز دارد. به دنباله عکسبرداری تعاملی نیاز دارد.
نسخه API پشتیبانی شده	برنامه های افزودنی Camera2: اندروید 13 یا بالاتر برنامه های افزودنی CameraX: camera-extensions 1.1.0 یا بالاتر	برنامه های افزودنی Camera2: Android 12L یا بالاتر برنامه های افزودنی CameraX: camera-extensions 1.2.0-alpha03 یا بالاتر

توجه: اگر ExtensionVersionImpl.isAdvancedExtenderImplemented() true را برگرداند، باید همه پسوندها را در Advanced Extender پیاده سازی کنید. اگر isAdvancedExtenderImplemented() false را برگرداند، باید همه پسوندها را در Basic Extender پیاده سازی کنید.

برنامه جریان می یابد

جدول زیر سه نوع جریان برنامه و فراخوانی های Camera Extensions API مربوط به آنها را نشان می دهد. در حالی که Camera2/X این API ها را ارائه می دهد، شما باید کتابخانه فروشنده را به درستی پیاده سازی کنید تا از این جریان ها پشتیبانی کند، که در بخش بعدی با جزئیات بیشتر توضیح خواهیم داد.

	پسوند Camera2	پسوند CameraX
در دسترس بودن برنامه افزودنی پرس و جو	CameraExtensionCharacteristics . getSupportedExtensions	ExtensionsManager. isExtensionAvailable
استعلام اطلاعات	CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys	ExtensionsManager. getEstimatedCaptureLatencyRange CameraX بقیه اطلاعات موجود در کتابخانه را مدیریت می کند.
پیش‌نمایش و عکسبرداری با پسوند فعال است	CameraDevice. createExtensionSession cameraExtensionsSession. setRepeatingRequest cameraExtensionsSession. capture	val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector bindToLifecycle(lifecycleOwner، cameraSelector، پیش نمایش، ...)

توسعه دهنده پایه

رابط Basic Extender قلاب هایی را در چندین مکان در خط لوله دوربین فراهم می کند. هر نوع برنامه افزودنی دارای کلاس های توسعه دهنده مربوطه است که OEM ها باید آن ها را پیاده سازی کنند.

جدول زیر کلاس های Extender را که OEMS باید برای هر برنامه افزودنی پیاده سازی کند فهرست می کند:

	کلاس های توسعه دهنده برای پیاده سازی
شب	NightPreviewExtenderImpl.java NightImageCaptureExtenderImpl.java
HDR	HdrPreviewExtenderImpl.java HdrImageCaptureExtenderImpl.java
خودکار	AutoPreviewExtenderImpl.java AutoImageCaptureExtenderImpl.java
بوکه	BokehPreviewExtenderImpl.java BokehImageCaptureExtenderImpl.java
روتوش صورت	BeautyPreviewExtenderImpl.java BeautyImageCaptureExtenderImpl.java

ما در مثال زیر PreviewExtenderImpl و ImageCaptureExtenderImpl به عنوان متغیرهایی استفاده می کنیم. اینها را با نام فایل های واقعی که در حال پیاده سازی هستید جایگزین کنید.

توجه: این کلاس های Extender ممکن است چندین بار در صورت نیاز در داخل Camera2/X نمونه سازی شوند.

Basic Extender دارای قابلیت های زیر است:

• هنگام پیکربندی CameraCaptureSession ( onPresetSession ) پارامترهای جلسه را وارد کنید.
• شما را از رویدادهای شروع و بسته شدن جلسه ضبط مطلع می کند و یک درخواست برای اطلاع HAL با پارامترهای برگشتی ارسال می کند ( onEnableSession ، onDisableSession ).
• پارامترهای ضبط را برای درخواست تزریق کنید ( PreviewExtenderImpl.getCaptureStage ، ImageCaptureExtenderImpl.getCaptureStages ).
• پردازنده‌هایی را برای پیش‌نمایش و عکس‌برداری اضافه کنید که قادر به پردازش جریان YUV_420_888 هستند.

توجه: برای برنامه‌های افزودنی که می‌خواهید فعال کنید، باید هم پیش‌نمایش و هم عکس‌برداری را اجرا کنید. برای مثال، اگر می‌خواهید پسوند Night را فعال کنید، باید NightPreviewExtenderImpl.java و NightCaptureExtenderImpl.java را اجرا کنید.

بیایید ببینیم Camera2/X چگونه extensions-interface برای دستیابی به سه جریان برنامه ذکر شده در بالا فراخوانی می‌کند.

توجه: Camera2/X همیشه قبل از شروع هر یک از این برنامه‌ها، کتابخانه فروشنده ( InitializerImpl.init() ) را مقداردهی اولیه می‌کند.

جریان برنامه 1: در دسترس بودن برنامه افزودنی را بررسی کنید

شکل 3. جریان برنامه 1 در Basic Extender

در این جریان، Camera2/X مستقیماً متد isExtensionAvailable() از هر دو PreviewExtenderImpl و ImageCaptureExtenderImpl را بدون فراخوانی init() فراخوانی می‌کند. هر دو کلاس Extender باید true برگردانند تا افزونه ها فعال شوند.

این اغلب اولین گام برای برنامه‌ها برای بررسی اینکه آیا نوع پسوند داده‌شده برای یک شناسه دوربین مشخص پشتیبانی می‌شود، قبل از فعال کردن برنامه افزودنی است. این به این دلیل است که برخی از برنامه‌های افزودنی فقط در شناسه‌های دوربین خاص پشتیبانی می‌شوند.

جریان برنامه 2: اطلاعات را جستجو کنید

شکل 4. جریان برنامه 2 در Basic Extender

پس از تعیین اینکه آیا برنامه افزودنی در دسترس است، برنامه‌ها باید اطلاعات زیر را قبل از فعال کردن برنامه افزودنی جستجو کنند.

• محدوده تأخیر ضبط هنوز: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange محدوده تأخیر ضبط را به برنامه برمی گرداند تا ارزیابی کند که آیا برای فعال کردن برنامه افزودنی برای سناریوی فعلی مناسب است یا خیر.

• اندازه‌های پشتیبانی‌شده برای سطح پیش‌نمایش و عکس‌برداری: ImageCaptureExtenderImpl.getSupportedResolutions و PreviewExtenderImpl.getSupportedResolutions فهرستی از قالب‌های تصویر و اندازه‌هایی را که برای قالب و اندازه سطح پشتیبانی می‌شوند، برمی‌گردانند.

• کلیدهای درخواست و نتیجه پشتیبانی شده: Camera2/X روش‌های زیر را برای بازیابی کلیدهای درخواست ضبط پشتیبانی شده و کلیدهای نتیجه از پیاده‌سازی شما فراخوانی می‌کند:

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
  • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X همیشه ابتدا init() در این کلاس های Extender قبل از درخواست اطلاعات بیشتر فراخوانی می کند.

جریان برنامه 3: پیش‌نمایش/عکس‌برداری با برنامه افزودنی فعال (اجرای HAL)

شکل 5. جریان برنامه 3 در Basic Extender

نمودار بالا جریان اصلی فعال کردن پیش‌نمایش و ضبط عکس با پسوند بدون هیچ پردازنده را نشان می‌دهد. این بدان معناست که دوربین HAL پسوند را پردازش می کند.

در این جریان، Camera2/X ابتدا init() و سپس onInit فراخوانی می‌کند، که به شما اطلاع می‌دهد که جلسه دوربین با پسوندهای مشخص شده شروع می‌شود. می توانید مقداردهی اولیه را در onInit() انجام دهید.

هنگام پیکربندی CameraCaptureSession ، Camera2/X روی onPresetSession را فراخوانی می‌کند تا پارامترهای جلسه را دریافت کند. پس از پیکربندی موفقیت آمیز جلسه ضبط، Camera2/X با فراخوانی onEnableSession یک نمونه CaptureStageImpl را که حاوی پارامترهای ضبط است، برمی گرداند. Camera2/X فوراً یک درخواست واحد با این پارامترهای ضبط برای اطلاع HAL ارسال می کند. به طور مشابه، قبل از بسته شدن جلسه عکسبرداری، Camera2/X روی onDisableSession را فراخوانی می کند و سپس یک درخواست را با پارامترهای ضبط برگشتی ارسال می کند.

درخواست تکراری ایجاد شده توسط Camera2/X حاوی پارامترهای درخواستی است که توسط PreviewExtenderImpl.getCaptureStage() برگردانده شده است. علاوه بر این، درخواست ضبط عکس حاوی پارامترهایی است که توسط ImageCaptureExtenderImpl.getCaptureStages() برگردانده شده است.

در نهایت، Camera2/X پس از پایان جلسه دوربین onDeInit() فراخوانی می کند. می توانید منابع را در onDeinit() منتشر کنید.

توجه: Camera2/X می‌تواند چندین جلسه دوربین باز و بسته بین onInit() و 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 را برمی گرداند، که در آن هر عنصر با پارامترهای ضبط که توسط Camera2/X ارسال می شود، به یک نمونه CaptureRequest نگاشت می شود. برای مثال، اگر لیستی از سه نمونه CaptureStageImpl را برگرداند، Camera2/X با استفاده از captureBurst API، سه درخواست عکسبرداری را با پارامترهای عکسبرداری مربوطه ارسال می کند.

   توجه: getCaptureStages() مجاز به برگرداندن بیش از یک نمونه CaptureStageImpl تنها زمانی است که getCaptureProcessor() یک نمونه را برگرداند.

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#JPEG_QUALITY و CaptureRequest#JPEG_ORIENTATION بدون در نظر گرفتن اینکه آیا به لیست اضافه شده باشند، همیشه پشتیبانی می شوند.

برای عملکردهای رایج دوربین مانند زوم، ضربه برای فوکوس، فلاش، و جبران نوردهی، توصیه می‌کنیم از کلیدهای زیر برای درخواست عکس‌برداری و نتیجه عکس‌برداری پشتیبانی کنید:

• بزرگنمایی:
  • 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

برای Basic Extenders که نسخه‌های 1.2.0 یا نسخه‌های قبلی را اجرا می‌کنند، CameraX Extensions API صراحتاً از همه کلیدهای بالا پشتیبانی می‌کند. برای extensions-interface 1.3.0، هر دو CameraX و Camera2 لیست بازگشتی را ارج می نهند و فقط از کلیدهای موجود در آن پشتیبانی می کنند. به عنوان مثال، اگر تصمیم دارید فقط CaptureRequest#CONTROL_ZOOM_RATIO و CaptureRequest#SCALER_CROP_REGION در پیاده‌سازی 1.3.0 برگردانید، این بدان معناست که فقط زوم برای برنامه پشتیبانی می‌شود در حالی که ضربه برای فوکوس، فلاش و جبران نوردهی مجاز نیست.

توجه: برنامه‌های افزودنی Camera2 فقط از تنظیم پارامترهای JPEG_QUALITY و JPEG_ORIENTATION در Android 12 و Android 12L پشتیبانی می‌کنند. با شروع Android 13، Camera2 Extensions API از پارامترهای دیگری مانند زوم یا فلش پشتیبانی می‌کند تا زمانی که این کلیدها توسط ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys در کتابخانه فروشنده OEM شما که extensions-interface 1.3.0 یا بالاتر را پیاده‌سازی می‌کند، بازگردانده شوند.

توسعه دهنده پیشرفته

Advanced Extender نوعی پیاده سازی فروشنده بر اساس Camera2 API است. این نوع Extender در extensions-interface 1.2.0 اضافه شد. بسته به سازنده دستگاه، برنامه‌های افزودنی ممکن است در لایه برنامه پیاده‌سازی شوند که به عوامل زیر بستگی دارد:

• پیکربندی پخش جریانی سفارشی: جریان‌های سفارشی مانند جریان RAW را پیکربندی کنید یا برای شناسه‌های دوربین فیزیکی مختلف، چندین جریان داشته باشید.

• قابلیت ارسال درخواست‌های Camera2: از یک منطق تعاملی پیچیده پشتیبانی می‌کند که می‌تواند درخواست‌های ضبط را با پارامترهایی بر اساس نتایج درخواست‌های قبلی ارسال کند.

Advanced Extender یک پوشش یا یک لایه میانی ارائه می دهد، بنابراین می توانید پیکربندی جریان را سفارشی کنید و درخواست های ضبط را در صورت درخواست ارسال کنید.

توجه: Camera2 Extensions API از Advanced Extender از اندروید 12L پشتیبانی می‌کند. برای CameraX Extensions API، Advanced Extender از CameraX 1.2.0-alpha03 پشتیبانی می‌شود.

فایل هایی برای پیاده سازی

برای تغییر به پیاده سازی Advanced Extender، متد isAdvancedExtenderImplemented() در ExtensionVersionImpl باید true برگرداند. برای هر نوع پسوند، OEM ها باید کلاس های Extender مربوطه را پیاده سازی کنند. فایل های پیاده سازی Advanced Extender در بسته پیشرفته هستند.

	کلاس های توسعه دهنده برای پیاده سازی
شب	advanced/NightAdvancedExtenderImpl.java
HDR	advanced/HdrAdvancedExtenderImpl.java
خودکار	advanced/AutoAdvancedExtenderImpl.java
بوکه	advanced/BokehAdvancedExtenderImpl.java
روتوش صورت	advanced/BeautyAdvancedExtenderImpl.java

ما در مثال زیر از AdvancedExtenderImpl به عنوان مکان نگهدارنده استفاده می کنیم. آن را با نام فایل Extender برای پسوندی که پیاده‌سازی می‌کنید جایگزین کنید.

بیایید ببینیم Camera2/X چگونه extensions-interface برای دستیابی به سه جریان برنامه فراخوانی می‌کند.

توجه: Camera2/X همیشه قبل از شروع هر یک از این برنامه‌ها، کتابخانه فروشنده ( InitializerImpl.init() ) را مقداردهی اولیه می‌کند.

جریان برنامه 1: در دسترس بودن برنامه های افزودنی را بررسی کنید

شکل 8. جریان برنامه 1 در Advanced Extender

ابتدا، برنامه بررسی می کند که آیا پسوند داده شده پشتیبانی می شود یا خیر.

توجه: قبل از فراخوانی isExtensionAvailable() برنامه نیازی به فراخوانی AdvancedExtenderImpl.init() ندارد.

جریان برنامه 2: اطلاعات را جستجو کنید

شکل 9. جریان برنامه 2 در Advanced Extender

پس از فراخوانی AdvancedExtenderImpl.init() ، برنامه می تواند اطلاعات زیر را در AdvancedExtenderImpl پرس و جو کند:

• تأخیر تصویربرداری تخمینی: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() دامنه تأخیر ضبط را به برنامه برمی‌گرداند تا ارزیابی کند که آیا فعال کردن برنامه افزودنی برای سناریوی فعلی مناسب است یا خیر.

• رزولوشن های پشتیبانی شده برای پیش نمایش و عکسبرداری:

  • AdvancedExtenderImpl.getSupportedPreviewOutputResolutions() نقشه ای از فرمت تصویر را به لیست اندازه هایی که برای قالب و اندازه سطح پیش نمایش پشتیبانی می شود، برمی گرداند. OEM ها باید حداقل از قالب 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

نمودار بالا جریان اصلی را برای شروع پیش‌نمایش و گرفتن عکس برای نوع Advanced Extender نشان می‌دهد. بیایید هر مرحله را طی کنیم.

1. نمونه SessionProcessorImpl

   هسته پیاده‌سازی Advanced Extender در SessionProcessorImpl است که مسئول ارائه پیکربندی جلسه سفارشی و ارسال درخواست‌های ضبط برای شروع درخواست پیش‌نمایش و ضبط عکس است. AdvancedExtenderImpl.createSessionProcessor() برای برگرداندن نمونه SessionProcessorImpl فراخوانی می شود.

   توجه: یک جلسه دوربین می تواند چندین بار از یک نمونه SessionProcessorImpl استفاده کند. در نتیجه، پیاده سازی باید قادر به پشتیبانی از چندین initSession() و deInitSession() برای یک نمونه SessionProcessorImpl باشد.

2. initSession

   SessionProcessorImpl.initSession() جلسه را برای برنامه افزودنی مقداردهی اولیه می کند. این جایی است که شما منابع را تخصیص می دهید و پیکربندی جلسه را برای تهیه CameraCaptureSession برمی گردانید.

   برای پارامترهای ورودی، Camera2/X پیکربندی‌های سطح خروجی را برای پیش‌نمایش، گرفتن عکس و تجزیه و تحلیل تصویر YUV اختیاری مشخص می‌کند. این پیکربندی سطح خروجی ( OutputSurfaceImpl ) شامل سطح، اندازه و قالب تصویر است که با روش‌های زیر در AdvancedExtenderImpl بازیابی می‌شوند:

   • getSupportedPreviewOutputResolutions()
   • getSupportedCaptureOutputResolutions()
   • getSupportedYuvAnalysisResolutions()

   شما باید یک نمونه Camera2SessionConfigImpl را برگردانید، که شامل لیستی از نمونه های Camera2OutputConfigImpl و پارامترهای جلسه مورد استفاده برای پیکربندی CameraCaptureSession است. شما مسئول ارسال تصاویر دوربین صحیح به سطوح خروجی ارسال شده توسط Camera2/X هستید. در اینجا چند گزینه برای فعال کردن خروجی وجود دارد:

   • پردازش در دوربین HAL: می توانید سطوح خروجی را مستقیماً با اجرای SurfaceOutputConfigImpl به CameraCaptureSession اضافه کنید. این سطح خروجی ارائه شده را به خط لوله دوربین پیکربندی می کند و به HAL دوربین اجازه می دهد تا تصویر را پردازش کند.

   • پردازش سطح میانی ImageReader (RAW، YUV، و غیره): سطوح میانی ImageReader را با یک نمونه ImageReaderOutputConfigImpl به CameraCaptureSession اضافه کنید.

     شما باید تصاویر میانی را پردازش کنید و تصویر نتیجه را روی سطح خروجی بنویسید.

   توجه: Camera2/X نمونه های ImageReader را برای شما ایجاد و مدیریت می کند. می توانید یک نمونه ImageProcessorImpl برای بازیابی تصویر تنظیم کنید.
   • استفاده از اشتراک‌گذاری سطح Camera2: با افزودن هر نمونه Camera2OutputConfigImpl به متد getSurfaceSharingOutputConfigs() نمونه Camera2OutputConfigImpl دیگر از اشتراک‌گذاری سطح با سطح دیگری استفاده کنید. قالب و اندازه سطح باید یکسان باشد.

   همه Camera2OutputConfigImpl از جمله SurfaceOutputConfigImpl و ImageReaderOutputConfigImpl باید یک شناسه منحصر به فرد ( getId() ) داشته باشند که برای تعیین سطح هدف و بازیابی تصویر از ImageReaderOutputConfigImpl استفاده می شود.

3. onCaptureSessionStart و RequestProcessorImpl

   وقتی CameraCaptureSession شروع می شود و چارچوب Camera onConfigured() را فراخوانی می کند، سپس Camera2/X SessionProcessorImpl.onCaptureSessionStart() را با پوشش درخواست Camera2 RequestProcessImpl فراخوانی می کند. Camera2/X RequestProcessImpl را پیاده‌سازی می‌کند، که به شما امکان می‌دهد درخواست‌های ضبط را اجرا کنید و در صورت استفاده از ImageReaderOutputConfigImpl ، تصاویر را بازیابی کنید .

   API های RequestProcessImpl از نظر اجرای درخواست ها مشابه API های Camera2 CameraCaptureSession هستند. تفاوت ها عبارتند از:

   • سطح هدف با شناسه نمونه Camera2OutputConfigImpl مشخص می شود.
   • قابلیت بازیابی تصویر ImageReader .

   می توانید RequestProcessorImpl.setImageProcessor() را با شناسه Camera2OutputConfigImpl مشخص شده برای ثبت یک نمونه ImageProcessorImpl برای دریافت تصاویر فراخوانی کنید.

   پس از فراخوانی SessionProcessorImpl.onCaptureSessionEnd() توسط Camera2/X، نمونه RequestProcessImpl نامعتبر می شود.

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() پاکسازی را انجام می دهد.

پشتیبانی از پیش نمایش، عکسبرداری ثابت و تجزیه و تحلیل تصویر

باید افزونه را برای موارد استفاده پیش‌نمایش و ضبط همچنان اعمال کنید. با این حال، اگر تأخیر بیش از حد زیاد است که پیش‌نمایش را به آرامی نشان نمی‌دهد، می‌توانید برنامه افزودنی را فقط برای ضبط ثابت اعمال کنید.

برای نوع Basic Extender، صرف نظر از فعال کردن پسوند برای پیش نمایش، باید هر دو ImageCaptureExtenderImpl و PreviewExtenderImpl برای یک برنامه افزودنی معین پیاده سازی کنید. اغلب، یک برنامه همچنین از یک جریان YUV برای تجزیه و تحلیل محتوای تصویر مانند یافتن کدهای QR یا متن استفاده می کند. To better support this use case , you should support the stream combination of preview, still capture, and a YUV_420_888 stream for configuring CameraCaptureSession . This means that if you implement a processor, then you have to support the stream combination of three YUV_420_888 streams.

For Advanced Extender, Camera2/X passes three output surfaces to the SessionProcessorImpl.initSession() call. These output surfaces are for preview , still capture, and image analysis, respectively. You must ensure that preview and still capture output surfaces show the valid output. However, for the image analysis output surface, ensure it's working only when it's non-null. If your implementation can't support the image analysis stream, you can return an empty list in AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() . This ensures the image analysis output surface is always null in SessionProcessorImpl.initSession() .

Note: You aren't required to apply the extension on the image analysis stream. Furthermore, the Camera2 Extensions API only allows for configuring two surfaces: preview and still capture.

Support video capture

The current Camera Extension architecture supports only the preview and still capture use cases. We don't support enabling the extension on the MediaCodec or MediaRecorder surfaces for recording the video. However, it's possible for apps to record the preview output.

Supporting MediaCodec and MediaRecorder surfaces is under investigation.

Extension-specific metadata

For Android 14 and higher, extension-specific metadata lets camera extension clients set and receive extension specific capture request settings and results. Specifically, camera extension clients can use the EXTENSION_STRENGTH capture request parameter to control the extension strength and the EXTENSION_CURRENT_TYPE capture result to indicate the enabled extension type.

Capture requests

The EXTENSION_STRENGTH capture request parameter controls the strength of the extension post-processing effect. The corresponding capture result includes the default strength value if this parameter isn't set explicitly by the client. This parameter can be applied as follows for these extension types:

• BOKEH : Controls the amount of blur.
• HDR and NIGHT : Controls the amount of images fused and the brightness of the final image.
• FACE_RETOUCH : Controls the amount of cosmetic enhancement and skin smoothing.

The supported range for the EXTENSION_STRENGTH parameter is between 0 and 100 , with 0 indicating no extension processing or simple passthrough and 100 indicating the maximum extension strength of the processing effect.

To add support for EXTENSION_STRENGTH , use the vendor specific parameter APIs introduced in version 1.3.0 of the extension library interface. For more information, see getAvailableCaptureRequestKeys() .

Capture results

The EXTENSION_CURRENT_TYPE capture result lets extension implementations notify clients about the active extension type.

Because extensions using the AUTO type dynamically switch between extension types such as HDR and NIGHT depending on the scene conditions, camera extensions apps can use EXTENSION_CURRENT_TYPE to display information about the current extension selected by the AUTO extension.

Real-time still capture latency estimate

For Android 14 and higher, camera extension clients can query real-time still capture latency estimates based on the scene and environment conditions using getRealtimeStillCaptureLatency() . This method provides more accurate estimates than the static getEstimatedCaptureLatencyRangeMillis() method. Based on the latency estimate, apps can decide to skip extension processing or to display an indication to notify users about a long running operation.

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();

To support real-time still capture latency estimates, implement the following:

• Basic extensions: ImageCaptureExtenderImpl.getRealtimeCaptureLatency()
• Advanced extensions: SessionProcessorImpl.getRealtimeCaptureLatency

Capture processing progress callbacks

For Android 14 and higher, camera extension clients can receive callbacks for the progress of long running still capture processing operations. Apps can display the current progress to users to improve the overall user experience.

Apps can use the following code to integrate this feature:

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

To support capture processing progress callbacks, your extension vendor implementation must call the following callbacks with the current progress value:

• Basic extensions: ProcessResultImpl.onCaptureProcessProgressed()
• Advanced extensions: CaptureCallback.onCaptureProcessProgressed()

Postview still capture

For Android 14 and higher, camera extensions can supply a postview (preview image) using setPostviewOutputConfiguration . To improve the user experience, apps can display a postview image as a placeholder when an extension is experiencing increased processing latency, and replace the image when the final image is available. Apps can configure and issue postview capture requests using the following reference code:

{
…
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();
…
}

To support postview still capture, your vendor implementation must implement the following:

• Basic extensions: CaptureProcessorImpl.onPostviewOutputSurface and CaptureProcessorImpl.processWithPostview

• Advanced extensions: SessionProcessorImpl.startCaptureWithPostview

Support SurfaceView output

For Android 14 and higher, camera extension clients can use power and performance optimized preview render paths by registering a SurfaceView instance for preview output for repeating requests.

To support SurfaceView output, your vendor extension implementation must be capable of streaming and outputting preview to SurfaceView instances. To verify that this is supported, run the SurfaceViewExtensionPreviewTest.java CTS module.

Vendor specific session types

The feature enables vendor extension implementations to select a vendor specific session type that will be set in the internal camera capture session instead of the default value.

The feature works entirely within the framework and vendor stack and has no client/public visible API impact.

To select a vendor-specific session type, implement the following for your extension libraries: * ExtenderStateListener.onSessionType() for basic extensions * Camera2SessionConfigImpl.getSessionType() for advanced extensions

Extensions interface version history

The following table shows the Camera Extension interface version history. You should always implement the vendor library with the latest version.

نسخه	Added features
1.0.0	Version verification ExtensionVersionImpl Basic Extender PreviewExtenderImpl ImageCaptureExtenderImpl Processor PreviewImageProcessorImpl CaptureProcessorImpl RequestUpdateProcessorImpl
1.1.0	Library initialization InitializerImpl Expose supported resolutions PreviewExtenderImpl.getSupportedResolutions ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0	AdvancedExtender AdvancedExtenderImpl SessionProcessorImpl Get estimated capture latency ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0	Expose supported capture request keys/results keys ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys and getAvailableCaptureResultKeys AdvancedExtenderImpl.getAvailableCaptureRequestKeys and getAvailableCaptureResultKeys New process() call that takes ProcessResultImpl in PreviewImageProcessorImpl and CaptureProcessorImpl Support trigger type request AdvancedExtenderImpl.startTrigger
1.4.0	Extension-specific metadata Dynamic still capture latency estimates Capture processing progress callbacks Postview still capture Support for SurfaceView output Vendor specific session types

پیاده سازی مرجع

The following reference OEM vendor library implementations are available in frameworks/ex .

• advancedSample : A basic implementation of Advanced Extender.

• sample : A basic implementation of Basic Extender.

• service_based_sample : An implementation that demonstrates how to host Camera Extensions in a Service . This implementation contains the following components:

  • oem_library : A Camera Extensions OEM library for Camera2 and CameraX Extensions APIs that implements Extensions-Interface . This acts as a passthrough that forwards calls from Extensions-Interface to the service. This library also provides AIDL files and wrapper classes to communicate with the service.

    Advanced Extender is enabled by default. To enable the Basic Extender, change ExtensionsVersionImpl#isAdvancedExtenderImplemented to return false .

  • extensions_service : A sample implementation of the Extensions Service. Add your implementation here. The interface to implement in the service is similar to the Extensions-Interface . For example, implementing the IAdvancedExtenderImpl.Stub performs the same operations as AdvancedExtenderImpl . ImageWrapper and TotalCaptureResultWrapper are required to make Image and TotalCaptureResult parcelable.

Set up the vendor library on a device

The OEM vendor library isn't built into an app; it's loaded from the device at runtime by Camera2/X. In CameraX, the <uses-library> tag declares that the androidx.camera.extensions.impl library, which is defined in the AndroidManifest.xml file of the camera-extensions library, is a dependency of CameraX and must be loaded at runtime. In Camera2, the framework loads an extensions service that also declares that the <uses-library> loads the same androidx.camera.extensions.impl library at runtime.

This allows third-party apps using extensions to automatically load the OEM vendor library. The OEM library is marked as optional so apps can run on devices that don't have the library on the device. Camera2/X handles this behavior automatically when an app tries to use a camera extension as long as the device manufacturer places the OEM library on the device so that it can be discovered by the app.

To set up the OEM library on a device, do the following:

1. Add a permission file, which is required by the <uses-library> tag, using the following format: /etc/permissions/ ANY_FILENAME .xml . For example, /etc/permissions/camera_extensions.xml . The files in this directory provide a mapping of the library named in <uses-library> to the actual file path on the device.

2. Use the example below to add the required information to the file.

   • name must be androidx.camera.extensions.impl as that's the library that CameraX searches for.
   • file is the absolute path of the file that contains the extensions implementation (for example, /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>

In Android 12 or higher, devices supporting CameraX extensions must have the ro.camerax.extensions.enabled property set to true , which allows for querying whether a device supports extensions. To do this, add the following line in the device make file:

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

اعتبار سنجی

To test your implementation of the OEM vendor library during the development stage, use the example app at androidx-main/camera/integration-tests/extensionstestapp/ , which runs through various vendor extensions.

After you complete your implementation, use the camera extensions validation tool to run automated and manual tests to verify that the vendor library is implemented correctly.

Extended scene mode versus camera extensions

For the bokeh extension, in addition to exposing it using camera extensions, you can expose the extension using the extended scene mode, which is enabled through the CONTROL_EXTENDED_SCENE_MODE key. For more implementation details, see Camera bokeh .

Extended scene mode has fewer restrictions compared to camera extensions for camera2 apps. For example, you can enable extended scene mode in a regular CameraCaptureSession instance that supports flexible stream combinations and capture request parameters. In contrast, camera extensions support only a fixed set of stream types and have limited support for capture request parameters.

A downside of extended scene mode is that you can only implement it in the camera HAL, which means that it must be verified to work across all orthogonal controls available to app developers.

We recommend exposing bokeh using both the extended scene mode and Camera Extensions because apps might prefer to use a particular API to enable bokeh. We recommend first using the extended scene mode because this is the most flexible way for apps to enable the bokeh extension. Then you can implement the camera extensions interface based on the extended scene mode. If implementing bokeh in the camera HAL is difficult, for example, because it requires a post processor running in the app layer to process images, we recommend implementing the bokeh extension using the Camera Extensions interface.

سوالات متداول (سؤالات متداول)

Are there any restrictions on API levels?

بله. This depends on the Android API feature set that's required by the OEM vendor library implementation. For example, ExtenderStateListener.onPresetSession() uses the SessionConfiguration.setSessionParameters() call to set a baseline set of tags. This call is available only on API level 28 and higher. For details on specific interface methods, see the API reference documentation .