پسوند دوربین

سازندگان دستگاه‌ها می‌توانند افزونه‌هایی مانند بوکه، حالت شب و 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 را در پروژه کتابخانه سیستم کپی کنید. این فایل ها رابط برنامه افزودنی دوربین را تعریف می کنند.

فایل های 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 به برنامه گزارش می دهند که برنامه افزودنی در دسترس نیست.

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

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

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() انجام ندهید. کارهای سنگین را فقط زمانی انجام دهید که جلسه دوربین در شرف شروع است، مانند زمانی که 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 استفاده می کند تا تعیین کند که آیا برنامه افزودنی می تواند فعال شود و چه قابلیت هایی باید فراخوانی کند.

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

اگر نسخه‌های اصلی رابط-افزونه بین 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 یا بالاتر

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

جدول زیر سه نوع جریان برنامه و فراخوانی های 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 به عنوان متغیرهایی استفاده می کنیم. اینها را با نام فایل های واقعی که در حال پیاده سازی هستید جایگزین کنید.

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

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

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

جریان برنامه 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() منتشر کنید.

پیش نمایش پردازنده

علاوه بر دوربین 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، سه درخواست عکسبرداری را با پارامترهای عکسبرداری مربوطه ارسال می کند.

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

برای 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 برگردانید، این بدان معناست که فقط زوم برای برنامه پشتیبانی می‌شود در حالی که ضربه برای فوکوس، فلاش و جبران نوردهی مجاز نیست.

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

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

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

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

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

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

برای تغییر به پیاده سازی 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 برای دستیابی به سه جریان برنامه فراخوانی می‌کند.

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

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

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

جریان برنامه 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 فراخوانی می شود.

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: با افزودن هر نمونه 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 یا متن استفاده می کند. برای پشتیبانی بهتر از این مورد استفاده ، شما باید از ترکیب جریان پیش نمایش ، هنوز ضبط و یک جریان YUV_420_888 برای پیکربندی CameraCaptureSession پشتیبانی کنید. این بدان معنی است که اگر یک پردازنده را پیاده سازی کنید ، باید از ترکیب جریان سه جریان YUV_420_888 پشتیبانی کنید.

برای توسعه پیشرفته ، Camera2/X سه سطح خروجی را به تماس SessionProcessorImpl.initSession() منتقل می کند. این سطوح خروجی به ترتیب برای پیش نمایش ، هنوز ضبط و تجزیه و تحلیل تصویر است. شما باید اطمینان حاصل کنید که پیش نمایش و هنوز ضبط سطوح خروجی خروجی معتبر را نشان می دهد. با این حال ، برای سطح خروجی تجزیه و تحلیل تصویر ، اطمینان حاصل کنید که فقط در هنگام غیر تهی کار می کند. اگر اجرای شما نمی تواند از جریان تجزیه و تحلیل تصویر پشتیبانی کند ، می توانید یک لیست خالی را در AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() برگردانید. این تضمین می کند که سطح خروجی تجزیه و تحلیل تصویر همیشه در SessionProcessorImpl.initSession() تهی است.

پشتیبانی از ضبط ویدیو

معماری پسوند دوربین فعلی فقط از پیش نمایش پشتیبانی می کند و هنوز هم موارد استفاده را ضبط می کند. ما از فعال کردن برنامه افزودنی در سطوح MediaCodec یا MediaRecorder برای ضبط فیلم پشتیبانی نمی کنیم. با این حال ، برای برنامه ها امکان ضبط خروجی پیش نمایش وجود دارد.

حمایت از سطوح MediaCodec و MediaRecorder در دست بررسی است.

ابرداده اختصاصی

برای Android 14 و بالاتر ، ابرداده اختصاصی خاص به مشتریان اجازه می دهد تا مشتریان پسوند دوربین تنظیمات و نتایج درخواست خاص ضبط را تنظیم و دریافت کنند. به طور خاص ، مشتری های پسوند دوربین می توانند از پارامتر درخواست EXTENSION_STRENGTH برای کنترل مقاومت پسوند و نتیجه ضبط EXTENSION_CURRENT_TYPE استفاده کنند تا نوع پسوند فعال را نشان دهند.

درخواست های ضبط

پارامتر درخواست EXTENSION_STRENGTH Capture Parameter استحکام اثر پس از پردازش پسوند را کنترل می کند. اگر این پارامتر به صراحت توسط مشتری تنظیم نشده باشد ، نتیجه ضبط مربوطه شامل مقدار پیش فرض استحکام است. این پارامتر را می توان به شرح زیر برای این انواع پسوند اعمال کرد:

• BOKEH : میزان تاری را کنترل می کند.
• HDR و NIGHT : میزان تصاویر ذوب شده و روشنایی تصویر نهایی را کنترل می کند.
• FACE_RETOUCH : میزان تقویت زیبایی و صاف کردن پوست را کنترل می کند.

دامنه پشتیبانی شده برای پارامتر EXTENSION_STRENGTH بین 0 تا 100 است که 0 نشانگر پردازش پسوند یا گذر ساده و 100 است که حداکثر مقاومت پسوند اثر پردازش را نشان می دهد.

برای افزودن پشتیبانی از EXTENSION_STRENGTH ، از API های پارامتر خاص فروشنده معرفی شده در نسخه 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()

بررسی پس از آن هنوز ضبط

برای 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() برای پسوندهای پیشرفته

سابقه نسخه رابط برنامه افزودنی

جدول زیر تاریخچه نسخه رابط برنامه افزودنی دوربین را نشان می دهد. شما همیشه باید کتابخانه فروشنده را با آخرین نسخه پیاده سازی کنید.

نسخه	ویژگی های اضافه شده
1.0.0	تأیید نسخه ExtensionVersionImpl توسعه دهنده PreviewExtenderImpl ImageCaptureExtenderImpl Processor PreviewImageProcessorImpl CaptureProcessorImpl RequestUpdateProcessorImpl
1.1.0	اولیه سازی InitializerImpl قطعنامه های پشتیبانی شده PreviewExtenderImpl.getSupportedResolutions ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0	دارای پیشروی پیشرفته AdvancedExtenderImpl SessionProcessorImpl تخمین زده می شود تأخیر در دستگیری ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0	کلیدها/نتایج درخواست ضبط پشتیبانی شده را در معرض نمایش قرار دهید ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys و getAvailableCaptureResultKeys AdvancedExtenderImpl.getAvailableCaptureRequestKeys getAvailableCaptureResultKeys process() فراخوانی که در ProcessResultImpl PreviewImageProcessorImpl و CaptureProcessorImpl انجام می شود پشتیبانی از نوع ماشه را پشتیبانی کنید AdvancedExtenderImpl.startTrigger
1.4.0	ابرداده اختصاصی پویا هنوز برآورد تأخیر را ضبط می کند ضبط تماس با پاسخ های پیشرفت در حال پیشرفت بررسی پس از آن هنوز ضبط پشتیبانی از خروجی SurfaceView انواع جلسه خاص فروشنده

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

اجرای کتابخانه فروشنده OEM مرجع زیر در frameworks/ex موجود است.

• advancedSample : یک اجرای اساسی از پیشرفته پیشرفته.

• sample : اجرای اساسی توسعه دهنده اصلی.

• service_based_sample : عملی که نشان می دهد نحوه میزبانی پسوندهای دوربین در یک Service را نشان می دهد. این اجرای شامل مؤلفه های زیر است:

  • oem_library : یک کتابخانه OEM Extensions Camera برای Camera2 و برنامه های افزودنی Camerax که از Extensions-Interface استفاده می کند. این به عنوان یک گذرگاه عمل می کند که تماس های مربوط به Extensions-Interface را به سرویس منتقل می کند. این کتابخانه همچنین برای برقراری ارتباط با سرویس ، پرونده های AIDL و کلاس های بسته بندی را ارائه می دهد.

    Extender پیشرفته به طور پیش فرض فعال می شود. برای فعال کردن توسعه اصلی ، تغییر 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 تعریف شده است ، وابستگی کامراکس است و باید در زمان اجرا بارگیری شود. در 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 /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/ استفاده کنید ، که از طریق پسوندهای مختلف فروشنده اجرا می شود.

پس از تکمیل اجرای خود ، از ابزار اعتبار سنجی Extensions Camera برای اجرای تست های خودکار و دستی استفاده کنید تا تأیید کنید که کتابخانه فروشنده به درستی پیاده سازی شده است.

حالت صحنه گسترده در مقابل پسوندهای دوربین

برای پسوند بوکه ، علاوه بر قرار گرفتن در معرض آن با استفاده از پسوندهای دوربین ، می توانید با استفاده از حالت صحنه گسترده ، که از طریق کلید CONTROL_EXTENDED_SCENE_MODE فعال می شود ، پسوند را در معرض نمایش قرار دهید. برای جزئیات بیشتر ، به دوربین Bokeh مراجعه کنید.

حالت صحنه گسترده محدودیت های کمتری در مقایسه با برنامه های افزودنی دوربین برای برنامه های Camera2 دارد. به عنوان مثال ، می توانید حالت صحنه گسترده را در یک نمونه CameraCaptureSession به طور منظم فعال کنید که از ترکیبات جریان انعطاف پذیر پشتیبانی می کند و پارامترهای درخواست ضبط را پشتیبانی می کند. در مقابل ، پسوندهای دوربین فقط از مجموعه ثابت از انواع جریان پشتیبانی می کنند و از پارامترهای درخواست ضبط پشتیبانی محدودی دارند.

نکته منفی از حالت صحنه گسترده این است که شما فقط می توانید آن را در دوربین HAL پیاده سازی کنید ، به این معنی که باید تأیید شود که در تمام کنترل های متعامد موجود در دسترس برای توسعه دهندگان برنامه باشد.

ما توصیه می کنیم Bokeh را با استفاده از هر دو حالت صحنه گسترده و پسوند دوربین در معرض دید قرار دهید زیرا برنامه ها ممکن است ترجیح دهند از API خاص برای فعال کردن Bokeh استفاده کنند. توصیه می کنیم ابتدا از حالت صحنه گسترده استفاده کنید زیرا این انعطاف پذیر ترین روش برای برنامه ها برای فعال کردن پسوند بوکه است. سپس می توانید رابط Extensions Camera را بر اساس حالت صحنه گسترده پیاده سازی کنید. اگر اجرای Bokeh در دوربین HAL دشوار است ، به عنوان مثال ، زیرا برای پردازش تصاویر به یک پردازنده پست در حال اجرا در لایه برنامه نیاز دارد ، توصیه می کنیم با استفاده از رابط Extensions Camera ، پسوند Bokeh را پیاده سازی کنید.

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

آیا محدودیتی در سطح API وجود دارد؟

آره. این بستگی به مجموعه ویژگی API Android دارد که توسط اجرای کتابخانه فروشنده OEM مورد نیاز است. به عنوان مثال ، ExtenderStateListener.onPresetSession() از تماس با SessionConfiguration.setSessionParameters() برای تنظیم مجموعه ای از برچسب ها استفاده می کند. این تماس فقط در سطح API 28 و بالاتر در دسترس است. برای جزئیات بیشتر در مورد روشهای رابط خاص ، به مستندات مرجع API مراجعه کنید.