این صفحه تفاوتهای نسخه در دوربینهای HAL، API و تستهای مجموعه تست سازگاری (CTS) مرتبط را توضیح میدهد. همچنین چندین تغییر معماری ایجاد شده برای سختتر کردن و ایمنسازی چارچوب دوربین در اندروید 7.0، تغییر به Treble در اندروید 8.0، و بهروزرسانیهایی را که فروشندگان باید برای پشتیبانی از این تغییرات در اجرای دوربین خود انجام دهند، پوشش میدهد.
واژه شناسی
در این صفحه از اصطلاحات زیر استفاده می شود:
- دوربین API1
- چارچوب دوربین در سطح برنامه در دستگاههای Android نسخه ۴.۴ و پایینتر، از طریق کلاس
android.hardware.Camera
در معرض دید قرار میگیرد. - دوربین API2
- چارچوب دوربین سطح برنامه در دستگاههای Android نسخه 5.0 و بالاتر، از طریق بسته
android.hardware.camera2
در معرض دید قرار میگیرد. - دوربین HAL
- لایه ماژول دوربین که توسط فروشندگان SoC پیاده سازی شده است. چارچوب های عمومی در سطح برنامه در بالای دوربین HAL ساخته شده اند.
- دوربین HAL3.1
- نسخه دوربین دستگاه HAL با اندروید 4.4 منتشر شد.
- دوربین HAL3.2
- نسخه دوربین دستگاه HAL با اندروید 5.0 منتشر شد.
- دوربین API1 CTS
- مجموعه ای از تست های CTS دوربین که در بالای دوربین API1 اجرا می شوند.
- دوربین API2 CTS
- مجموعه دیگری از تستهای CTS دوربین که در بالای دوربین API2 اجرا میشوند.
- سه گانه
- پیادهسازی فروشنده (نرمافزار سطح پایینتر و ویژه دستگاه را که توسط سازندگان سیلیکون نوشته شده است) از چارچوب سیستم عامل Android از طریق یک رابط فروشنده جدید جدا میکند.
- HIDL
- زبان تعریف رابط HAL با Treble معرفی شد و برای مشخص کردن رابط بین HAL و کاربران آن استفاده شد.
- VTS
- مجموعه تست فروشنده در کنار Treble معرفی شد.
API های دوربین
اندروید شامل API های دوربین زیر است.
دوربین API1
Android 5.0 Camera API1 منسوخ شده است، که با تمرکز توسعه پلتفرم جدید بر Camera API2، به تدریج حذف می شود. با این حال، دوره حذف تدریجی طولانی خواهد بود و نسخههای اندرویدی تا مدتی از برنامههای Camera API1 پشتیبانی خواهند کرد. به طور خاص، پشتیبانی برای موارد زیر ادامه دارد:
- رابط های دوربین API1 برای برنامه ها. برنامههای دوربین ساختهشده در بالای Camera API1 باید مانند دستگاههایی که نسخههای پایینتر اندروید دارند کار کنند.
- نسخه های دوربین HAL. شامل پشتیبانی از دوربین HAL1.0.
دوربین API2
چارچوب Camera API2 کنترل دوربین سطح پایینتری را در اختیار برنامه قرار میدهد، از جمله جریانهای پیاپی/جریانگذاری کارآمد صفر کپی و کنترلهای نوردهی، افزایش، افزایش تعادل رنگ سفید، تبدیل رنگ، حذف نویز، شفافسازی و غیره در هر فریم. برای جزئیات، نمای کلی ویدیوی Google I/O را تماشا کنید.
اندروید 5.0 و بالاتر شامل Camera API2 است. با این حال، دستگاههای دارای Android نسخه 5.0 و بالاتر ممکن است از همه ویژگیهای Camera API2 پشتیبانی نکنند. ویژگی android.info.supportedHardwareLevel
که برنامهها میتوانند از طریق رابطهای Camera API2 درخواست کنند، یکی از سطوح پشتیبانی زیر را گزارش میدهد:
-
LEGACY
: این دستگاهها قابلیتهایی را از طریق رابطهای Camera API2 در معرض برنامهها قرار میدهند که تقریباً همان قابلیتهایی هستند که از طریق رابطهای Camera API1 در معرض برنامهها قرار میگیرند. کد فریمورک های قدیمی به طور مفهومی فراخوانی های Camera API2 را به تماس های Camera API1 تبدیل می کند. دستگاههای قدیمی از ویژگیهای Camera API2 مانند کنترلهای هر فریم پشتیبانی نمیکنند. -
LIMITED
: این دستگاهها از برخی قابلیتهای Camera API2 (اما نه همه) پشتیبانی میکنند و باید از دوربین HAL 3.2 یا بالاتر استفاده کنند. -
FULL
: این دستگاهها از تمام قابلیتهای اصلی Camera API2 پشتیبانی میکنند و باید از دوربین HAL 3.2 یا بالاتر و اندروید 5.0 یا بالاتر استفاده کنند. -
LEVEL_3
: این دستگاهها از پردازش مجدد YUV و ضبط تصویر RAW به همراه تنظیمات جریان خروجی اضافی پشتیبانی میکنند. -
EXTERNAL
: این دستگاه ها مشابه دستگاه هایLIMITED
با برخی استثناها هستند. به عنوان مثال، برخی از اطلاعات حسگر یا لنز ممکن است گزارش نشوند یا نرخ فریم پایدار کمتری داشته باشند. این سطح برای دوربین های خارجی مانند وب کم USB استفاده می شود.
قابلیتهای فردی از طریق ویژگی android.request.availableCapabilities
در رابطهای Camera API2 آشکار میشوند. دستگاههای FULL
به قابلیتهای MANUAL_SENSOR
و MANUAL_POST_PROCESSING
از جمله موارد دیگر نیاز دارند. قابلیت RAW
حتی برای دستگاه های FULL
اختیاری است. دستگاه های LIMITED
می توانند هر زیر مجموعه ای از این قابلیت ها را تبلیغ کنند، از جمله هیچ کدام. با این حال، قابلیت BACKWARD_COMPATIBLE
همیشه باید تعریف شود.
سطح سختافزار پشتیبانیشده دستگاه، و همچنین قابلیتهای خاص Camera API2 که از آن پشتیبانی میکند، بهعنوان پرچمهای ویژگی زیر در دسترس هستند تا به Google Play اجازه فیلتر کردن برنامههای دوربین دوربین API2 را بدهد.
-
android.hardware.camera.hardware_level.full
-
android.hardware.camera.capability.raw
-
android.hardware.camera.capability.manual_sensor
-
android.hardware.camera.capability.manual_post_processing
الزامات CTS
دستگاههایی که Android نسخه 5.0 و بالاتر دارند باید آزمایشهای دوربین API1 CTS، Camera API2 CTS و CTS Verifier را پشت سر بگذارند.
دستگاههایی که فاقد اجرای Camera HAL3.2 هستند و قادر به پشتیبانی از رابطهای کامل Camera API2 نیستند، همچنان باید تستهای Camera API2 CTS را پشت سر بگذارند. با این حال، دستگاه در حالت Camera API2 LEGACY
اجرا میشود (که در آن تماسهای Camera API2 به صورت مفهومی با تماسهای Camera API1 نگاشت میشوند) بنابراین هر آزمایش CTS دوربین API2 مربوط به ویژگیها یا قابلیتهای فراتر از Camera API1 بهطور خودکار نادیده گرفته میشود.
در دستگاههای قدیمی، آزمایشهای Camera API2 CTS که اجرا میشوند از رابطها و قابلیتهای عمومی Camera API1 بدون نیاز جدید استفاده میکنند. اشکالاتی که در معرض دید قرار میگیرند (و باعث خرابی دوربین API2 CTS میشوند) اشکالاتی هستند که از قبل در دوربین HAL موجود دستگاه وجود دارند و بنابراین توسط برنامههای Camera API1 موجود پیدا میشوند. ما انتظار بسیاری از باگهای این ماهیت را نداریم (با این حال، برای گذراندن تستهای Camera API2 CTS باید چنین اشکالاتی برطرف شود).
الزامات VTS
دستگاههای دارای Android نسخه ۸.۰ و بالاتر با اجرای HAL binderized باید تستهای Camera VTS را پشت سر بگذارند.
سخت شدن چارچوب دوربین
برای سختتر کردن رسانه و امنیت چارچوب دوربین، Android 7.0 سرویس دوربین را از سرور رسانه خارج میکند. با شروع Android 8.0، هر دوربین HAL بایندر شده در فرآیندی جدا از سرویس دوربین اجرا میشود. ممکن است فروشندگان بسته به نسخه های API و HAL در حال استفاده، نیاز به تغییر در HAL دوربین داشته باشند. بخشهای زیر تغییرات معماری در AP1 و AP2 برای HAL1 و HAL3 و همچنین الزامات کلی را شرح میدهد.
تغییرات معماری برای API1
ضبط ویدیوی API1 ممکن است دوربین و رمزگذار ویدیو را در یک فرآیند زنده فرض کند. هنگام استفاده از API1 در:
- HAL3، جایی که سرویس دوربین از BufferQueue برای عبور بافرها بین فرآیندها استفاده می کند، به روز رسانی فروشنده لازم نیست .
شکل 1. دوربین اندروید 7.0 و پشته رسانه در API1 در HAL3
- HAL1 که از ارسال ابرداده در بافرهای ویدیویی پشتیبانی میکند، فروشندگان باید HAL را برای استفاده از
kMetadataBufferTypeNativeHandleSource
بهروزرسانی کنند. (kMetadataBufferTypeCameraSource
دیگر در Android 7.0 پشتیبانی نمیشود.)شکل 2. دوربین اندروید 7.0 و پشته رسانه در API1 در HAL1
تغییرات معماری برای API2
برای API2 در HAL1 یا HAL3، BufferQueue بافرها را پاس میکند تا این مسیرها به کار خود ادامه دهند. معماری Android 7.0 برای API2 در:
- HAL1 تحت تأثیر حرکت دوربین سرویس قرار نمی گیرد و به روز رسانی فروشنده لازم نیست .
- HAL3 تحت تأثیر قرار گرفته است ، اما بهروزرسانی فروشنده لازم نیست :
شکل 3. دوربین اندروید 7.0 و پشته رسانه در API2 در HAL3
الزامات اضافی
تغییرات معماری ایجاد شده برای سخت شدن رسانه و امنیت چارچوب دوربین شامل الزامات دستگاه اضافی زیر است.
- عمومی. دستگاه ها به دلیل IPC به پهنای باند اضافی نیاز دارند، که ممکن است بر موارد استفاده از دوربین حساس به زمان مانند ضبط ویدیوی با سرعت بالا تأثیر بگذارد. فروشندگان می توانند تأثیر واقعی را با اجرای
android.hardware.camera2.cts.PerformanceTest
و برنامه دوربین Google برای ضبط ویدیوی پرسرعت 120/240 FPS اندازه گیری کنند. دستگاه ها همچنین به مقدار کمی رم اضافی برای ایجاد فرآیند جدید نیاز دارند. - ارسال فراداده در بافرهای ویدیویی ( فقط HAL1 ). اگر HAL1 متادیتا را به جای دادههای فریم YUV واقعی در بافرهای ویدیو ذخیره میکند، HAL باید از
kMetadataBufferTypeNativeHandleSource
بهعنوان نوع بافر فراداده استفاده کند وVideoNativeHandleMetadata
را در بافرهای ویدیویی ارسال کند. (kMetadataBufferTypeCameraSource
دیگر در Android 7.0 پشتیبانی نمیشود.) باVideoNativeHandleMetadata
، چارچوبهای دوربین و رسانه میتوانند با سریالسازی و سریالزدایی صحیح دستههای اصلی، بافرهای ویدیویی را بین فرآیندها منتقل کنند. - آدرس دسته بافر همیشه یک بافر را ذخیره نمی کند ( فقط HAL3 ). برای هر درخواست ضبط، HAL3 آدرس دستههای بافر را دریافت میکند. HAL نمیتواند از آدرسها برای شناسایی بافرها استفاده کند، زیرا آدرسها ممکن است دسته بافر دیگری را پس از بازگشت HAL بافر ذخیره کنند. شما باید HAL را به روز کنید تا از دسته های بافر برای شناسایی بافرها استفاده کنید. به عنوان مثال، HAL یک آدرس دسته بافر A را دریافت می کند، که دسته بافر A را ذخیره می کند. پس از اینکه HAL دسته بافر A را برگرداند، آدرس دسته بافر A ممکن است دسته بافر B را دفعه بعد که HAL آن را دریافت کند، ذخیره کند.
- سیاست های SELinux را برای سرور دوربین به روز کنید. اگر خطمشیهای SELinux مخصوص دستگاه، مجوزهای سرور مدیا را برای اجرای دوربین میدهند، باید خطمشیهای SELinux را بهروزرسانی کنید تا به سرور دوربین مجوزهای مناسب بدهید. ما از تکرار خطمشیهای SELinux سرور رسانه برای سرور دوربین خودداری میکنیم (زیرا سرور رسانه و سرور دوربین معمولاً به منابع مختلفی در سیستم نیاز دارند). سرور دوربین باید فقط مجوزهای لازم برای انجام عملکردهای دوربین را داشته باشد و هر گونه مجوز غیر ضروری مربوط به دوربین در سرور رسانه باید حذف شود.
- جداسازی دوربین HAL و سرور دوربین. Android 8.0 و بالاتر علاوه بر این، دوربین HAL را در فرآیندی متفاوت از سرور دوربین جدا می کند. IPC از طریق رابط های تعریف شده توسط HIDL می رود.
اعتبار سنجی
برای همه دستگاههایی که دارای دوربین هستند و Android 7.0 را اجرا میکنند، با اجرای Android 7.0 CTS اجرای آن را تأیید کنید. اگرچه Android 7.0 شامل تستهای CTS جدید برای تأیید تغییرات سرویس دوربین نمیشود، اما اگر بهروزرسانیهای ذکر شده در بالا را انجام نداده باشید، آزمایشهای CTS موجود با شکست مواجه میشوند.
برای همه دستگاههایی که دارای دوربین هستند و اندروید 8.0 و بالاتر دارند، با اجرای VTS، اجرای فروشنده را تأیید کنید.
تاریخچه نسخه دوربین HAL
برای لیستی از تستهای موجود برای ارزیابی دوربین Android HAL، به چک لیست تست دوربین HAL مراجعه کنید.
اندروید 10
اندروید 10 به روز رسانی های زیر را معرفی می کند.
دوربین API
- بهبودهای چند دوربینی که امکان استفاده از دوربین های فیزیکی را به صورت جداگانه یا از طریق دوربین های منطقی مربوطه با پنهان کردن شناسه های فیزیکی دوربین فراهم می کند. به پشتیبانی از چند دوربین مراجعه کنید.
- امکان بررسی اینکه آیا یک پیکربندی جلسه خاص بدون سربار عملکرد ایجاد یک جلسه جدید پشتیبانی می شود یا خیر.
CameraDevice
ببینید. - امکان بازیابی تنظیمات جریان توصیه شده برای یک مورد خاص برای افزایش کارایی و کارایی مشتری.
getRecommendedStreamConfigurationMap
را ببینید. - پشتیبانی از فرمت تصویر با عمق JPEG برای جزئیات بیشتر، مشخصات دینامیک عمق را ببینید.
- پشتیبانی از فرمت تصویر HEIC به تصویربرداری HEIF مراجعه کنید.
- بهبود حریم خصوصی کلیدهای خاصی برای برخورداری مشتری از مجوزهای
CAMERA
قبل از بازیابی ازCameraCharacteristics
لازم است. بهgetKeysNeedingPermission
مراجعه کنید.
دوربین HAL
نسخه های دوربین HAL زیر در اندروید 10 به روز شده اند.
3.5
ICameraDevice
-
getPhysicalCameraCharacteristics
: اطلاعات ثابت دوربین برای شناسه دوربین فیزیکی که پشتیبان یک دستگاه دوربین منطقی است. به پشتیبانی از چند دوربین مراجعه کنید. -
isStreamCombinationSupported
: این روش از یک API عمومی پشتیبانی میکند که به مشتریان کمک میکند در صورت پشتیبانی از پیکربندی جلسه، پرس و جو کنند. به API برای پرس و جو از ترکیبات جریان مراجعه کنید.
ICameraDeviceSession
-
isReconfigurationNeeded
: روشی که به چارچوب دوربین می گوید که آیا پیکربندی مجدد جریان برای مقادیر پارامترهای جدید جلسه احتمالی لازم است یا خیر. این به جلوگیری از تاخیرهای غیرضروری پیکربندی مجدد دوربین کمک می کند. به جستجوی پیکربندی مجدد جلسه مراجعه کنید. - APIهای مدیریت بافر HAL : این APIها به HAL دوربین اجازه میدهند که به جای جفت کردن هر درخواست ضبط با بافرهای مرتبط در سراسر خط لوله دوربین، بافرهایی را از چارچوب دوربین درخواست کند، که منجر به صرفهجویی قابل توجهی در حافظه میشود.
-
signalStreamFlush
: به HAL سیگنال می دهد که سرویس دوربین در شرف انجامconfigureStreams_3_5
است و اینکه HAL باید تمام بافرهای جریان های تعیین شده را برگرداند. -
configureStreams_3_5
: مشابهICameraDevice3.4.configureStreams
، اما علاوه بر این، شمارندهstreamConfigCounter
برای بررسی شرایط مسابقه بین تماسهایconfigureStreams_3_5
وsignalStreamFlush
ارائه شده است.
-
بهروزرسانیهای ICameraDeviceCallback
:
-
requestStreamBuffers
: پاسخ به تماس همزمانی که دوربین HAL برای درخواست بافر از سرور دوربین فراخوانی می کند. بهrequestStreamBuffers
مراجعه کنید. -
returnStreamBuffers
: پاسخ به تماس همزمان برای دوربین HAL برای بازگرداندن بافرهای خروجی به سرور دوربین.returnStreamBuffers
ببینید.
3.4
کلیدهای زیر به ابرداده دوربین در اندروید 10 اضافه شده است.
- فرمت های تصویر
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW10
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW12
-
ANDROID_SCALER_AVAILABLE_FORMATS_Y8
-
- تگ های فراداده دوربین
-
ANDROID_REQUEST_CHARACTERISTIC_KEYS_NEEDING_PERMISSION
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_INPUT_OUTPUT_FORMATS_MAP
-
ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION
-
ANDROID_DEPTH_AVAILABLE_RECOMMENDED_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_MIN_FRAME_DURATIONS
-
ANDROID_LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_MIN_FRAME_DURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_STALL_DURATIONS
-
ANDROID_HEIC_INFO_SUPPORTED
-
ANDROID_HEIC_INFO_MAX_JPEG_APP_SEGMENTS_COUNT
-
- توانایی ها
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_SECURE_IMAGE_DATA
-
- مقادیر برای کلید
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_MONO
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_NIR
-
- پیکربندیهای جریان عمق پویا موجود
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_INPUT
-
- پیکربندیهای جریان HEIC موجود
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_INPUT
-
ماژول دوربین
نسخه های ماژول دوربین زیر در اندروید 10 به روز شده اند.
2.5
- روش
notifyDeviceStateChange
را برای دستگاهها اضافه میکند تا زمانی که تغییرات فیزیکی، مانند تا شدن، دوربین و مسیریابی را تحت تأثیر قرار میدهد، HAL دوربین را مطلع کند.
2.4
- دستگاههایی که با سطح API 29 یا بالاتر راهاندازی میشوند، باید برای
isTorchModeSupported
true
گزارش دهند.
اندروید 9
نسخه اندروید 9 به روز رسانی های زیر را برای دوربین API2 و رابط HAL معرفی می کند.
دوربین API
- API چند دوربینی را برای پشتیبانی بهتر از دستگاههایی که چندین دوربین در یک جهت دارند، معرفی میکند و ویژگیهایی مانند بوکه و زوم بدون درز را فعال میکند. این به برنامه ها اجازه می دهد تا چندین دوربین را در یک دستگاه به عنوان یک واحد منطقی (دوربین منطقی) مشاهده کنند. درخواستهای عکسبرداری همچنین میتوانند به دستگاههای دوربین جداگانه که توسط یک دوربین منطقی احاطه شدهاند ارسال شوند. به پشتیبانی از چند دوربین مراجعه کنید.
- پارامترهای جلسه را معرفی می کند. پارامترهای جلسه زیرمجموعهای از پارامترهای ضبط موجود هستند که در صورت تغییر میتوانند باعث تأخیر شدید پردازش شوند. این هزینه ها را می توان کاهش داد اگر مشتریان مقادیر اولیه خود را در طول اولیه سازی جلسه ضبط ارسال کنند. به پارامترهای جلسه مراجعه کنید.
- کلیدهای داده تثبیت کننده نوری (OIS) را برای تثبیت و اثرات در سطح برنامه اضافه می کند.
STATISTICS_OIS_SAMPLES
را ببینید. - پشتیبانی از فلاش خارجی را اضافه می کند.
CONTROL_AE_MODE_ON_EXTERNAL_FLASH
را ببینید. - یک هدف ردیابی حرکت را در
CAPTURE_INTENT
اضافه می کند.CONTROL_CAPTURE_INTENT_MOTION_TRACKING
را ببینید. -
LENS_RADIAL_DISTORTION
منسوخ می کند وLENS_DISTORTION
به جای خود اضافه می کند. - حالت های تصحیح اعوجاج را در
CaptureRequest
اضافه می کند.DISTORTION_CORRECTION_MODE
را ببینید. - پشتیبانی از دوربین های خارجی USB/UVC را در دستگاه های پشتیبانی شده اضافه می کند.
INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL
را ببینید.
دوربین HAL
3.4
به روز رسانی به ICameraDeviceSession
-
configureStreams_3_4
: پشتیبانی ازsessionParameters
و دوربین های منطقی را اضافه می کند. -
processCaptureRequest_3_4
: پشتیبانی از گنجاندن شناسه های فیزیکی دوربین در ساختار جریان را اضافه می کند.
به روز رسانی به ICameraDeviceCallback
-
processCaptureResult_3_4
: فراداده های فیزیکی دوربین را در نتایج عکس اضافه می کند.
3.3
کلیدهای زیر به ابرداده دوربین در اندروید 9 اضافه شده است.
- توانایی ها
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
-
- تگ های فراداده دوربین
-
ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS
-
ANDROID_LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE
-
ANDROID_DISTORTION_CORRECTION_AVAILABLE_MODES
-
ANDROID_LENS_POSE_REFERENCE
-
ANDROID_LENS_DISTORTION
-
ANDROID_REQUEST_AVAILABLE_SESSION_KEYS
-
ANDROID_REQUEST_AVAILABLE_PHYSICAL_CAMERA_REQUEST_KEYS
-
ANDROID_STATISTICS_OIS_DATA_MODE
-
ANDROID_STATISTICS_OIS_TIMESTAMPS
-
ANDROID_STATISTICS_OIS_X_SHIFTS
-
ANDROID_STATISTICS_OIS_Y_SHIFTS
-
اندروید 8.0
نسخه اندروید 8.0 Treble را معرفی می کند. با Treble، پیادهسازیهای دوربین HAL فروشنده باید بایندر شوند. Android 8.0 همچنین شامل این پیشرفتهای کلیدی در سرویس دوربین است:
- سطوح مشترک: چندین سطح را فعال کنید که
OutputConfiguration
یکسان را به اشتراک بگذارند - API سیستم برای حالت های دوربین سفارشی
-
onCaptureQueueEmpty
برای اطلاعات بیشتر در مورد این ویژگی ها به بخش های زیر مراجعه کنید.
سطوح مشترک
این ویژگی تنها یک مجموعه از بافرها را قادر میسازد تا دو خروجی مانند پیشنمایش و کدگذاری ویدیو را هدایت کند که مصرف انرژی و حافظه را کاهش میدهد. برای پشتیبانی از این ویژگی، سازندگان دستگاه باید اطمینان حاصل کنند که پیادهسازی HAL و gralloc HAL دوربین آنها میتوانند به جای یک مصرفکننده، بافرهای gralloc را ایجاد کنند که توسط چندین مصرفکننده مختلف (مانند آهنگساز/GPU و رمزگذار ویدیو) استفاده میشود. سرویس دوربین پرچم های استفاده مصرف کننده را به دوربین HAL و gralloc HAL ارسال می کند. آنها باید یا نوع مناسبی از بافرها را تخصیص دهند، یا دوربین HAL باید خطایی را نشان دهد که این ترکیب از مصرف کنندگان پشتیبانی نمی شود.
برای جزئیات بیشتر به مستندات توسعه دهنده enableSurfaceSharing
مراجعه کنید.
API سیستم برای حالت های دوربین سفارشی
API دوربین عمومی دو حالت عملیاتی را تعریف می کند: ضبط معمولی و محدود با سرعت بالا. آنها معنای نسبتاً متفاوتی دارند. به عنوان مثال، حالت پرسرعت حداکثر به دو خروجی خاص در یک زمان محدود می شود. OEM های مختلف به تعریف حالت های سفارشی دیگر برای قابلیت های سخت افزاری خاص ابراز علاقه کرده اند. در زیر هود، حالت فقط یک عدد صحیح است که به configure_streams
منتقل می شود. ببینید: hardware/camera/device/3.2/ICameraDeviceSession#configurestreams
.
این ویژگی شامل یک تماس API سیستم است که برنامههای دوربین OEM میتوانند از آن برای فعال کردن حالت سفارشی استفاده کنند. این حالتها باید با مقدار صحیح 0x8000 شروع شوند تا از تداخل با حالتهای آینده اضافه شده به API عمومی جلوگیری شود.
برای پشتیبانی از این ویژگی، OEM ها فقط باید حالت جدید را به HAL خود اضافه کنند، که توسط این عدد صحیح به HAL در configure_streams ارسال می شود، و سپس برنامه دوربین سفارشی آنها از API سیستم استفاده کند.
نام روش android.hardware.camera2.CameraDevice#createCustomCaptureSession
است. ببینید: frameworks/base/core/java/android/hardware/camera2/CameraDevice
.
onCaptureQueueEmpty
هدف این API کاهش تأخیر تغییرات کنترل مانند زوم با خالی نگه داشتن صف درخواست تا حد امکان است. onCaptureQueueEmpty
به هیچ کار HAL نیاز ندارد. این صرفاً یک افزودنی در سمت چارچوب بود. برنامههایی که میخواهند از آن بهره ببرند، باید یک شنونده به آن تماس اضافه کنند و به طور مناسب پاسخ دهند. معمولاً با ارسال یک درخواست عکسبرداری دیگر به دستگاه دوربین است.
رابط HIDL دوربین
رابط دوربین HIDL یک بازسازی کامل از رابط دوربین HAL است که از API های تعریف شده با HIDL پایدار استفاده می کند. تمامی ویژگی ها و قابلیت های دوربین معرفی شده در جدیدترین نسخه های قدیمی 3.4 و 2.4 (برای ماژول دوربین) نیز بخشی از تعاریف HIDL هستند.
3.4
اضافات جزئی به ابرداده های پشتیبانی شده و تغییرات در پشتیبانی data_space:
- در صورت پشتیبانی از فرمت
RAW_OPAQUE
ANDROID_SENSOR_OPAQUE_RAW_SIZE
فراداده ایستا را به عنوان اجباری اضافه کنید. - در صورت پشتیبانی از هر قالب RAW،
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
فراداده ایستا را به عنوان اجباری اضافه کنید. - با استفاده از تعریف نسخه 0 کدگذاری فضای داده، قسمت
camera3_stream_t data_space
را به یک تعریف انعطافپذیرتر تغییر دهید. - اضافههای فراداده عمومی که برای استفاده برای HALv3.2 یا جدیدتر در دسترس هستند:
-
ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
-
ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL
-
ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL
-
ANDROID_SENSOR_OPAQUE_RAW_SIZE
-
ANDROID_SENSOR_OPTICAL_BLACK_REGIONS
-
3.3
بازبینی جزئی HAL با قابلیت توسعه یافته:
- به روز رسانی OPAQUE و YUV پردازش مجدد API.
- پشتیبانی اولیه از بافرهای خروجی عمق.
- افزودن فیلد
data_space
بهcamera3_stream_t
. - افزودن فیلد چرخش به
camera3_stream_t
. - اضافه شدن حالت عملیات پیکربندی جریان camera3 به
camera3_stream_configuration_t
.
3.2
بازبینی جزئی HAL با قابلیت توسعه یافته:
-
get_metadata_vendor_tag_ops
را منسوخ می کند. به جای آن ازget_vendor_tag_ops
درcamera_common.h
استفاده کنید. -
register_stream_buffers
منسوخ می کند. همه بافرهای gralloc ارائه شده توسط فریمورک به HAL درprocess_capture_request
ممکن است در هر زمانی جدید باشند. - پشتیبانی از نتیجه جزئی را اضافه کنید.
process_capture_result
ممکن است چندین بار با زیرمجموعه ای از نتایج موجود قبل از اینکه نتیجه کامل در دسترس باشد فراخوانی شود. - قالب دستی را به
camera3_request_template
اضافه کنید. برنامهها ممکن است از این الگو برای کنترل مستقیم تنظیمات ضبط استفاده کنند. - مشخصات دو طرفه و جریان ورودی را دوباره کار کنید.
- مسیر بازگشت بافر ورودی را تغییر دهید. بافر به جای
process_capture_request
درprocess_capture_result
برگردانده می شود.
3.1
بازبینی جزئی HAL با قابلیت توسعه یافته:
-
configure_streams
پرچم های استفاده مصرف کننده را به HAL ارسال می کند. - برای رها کردن تمام درخواستها/بافرهای حین پرواز در سریعترین زمان ممکن، تماس را هموار کنید.
3.0
اولین بازبینی HAL با قابلیت توسعه یافته:
- تغییرات عمده نسخه از ABI کاملا متفاوت است. هیچ تغییری در قابلیت های سخت افزاری یا مدل عملیاتی مورد نیاز از 2.0 وجود ندارد.
- درخواست ورودی مجدد و واسطهای صف جریان: فراخوانی چارچوب به HAL با درخواست بعدی و بافرهای جریانی که قبلاً از صف خارج شدهاند. پشتیبانی از چارچوب همگامسازی گنجانده شده است که برای اجرای کارآمد ضروری است.
- محرکها به درخواستها، بیشتر اعلانها به نتایج منتقل شدند.
- تمام callbackها را در چارچوب در یک ساختار، و تمام متدهای راه اندازی را در یک
initialize()
ادغام کرد. - پیکربندی جریان را در یک تماس واحد انجام داد تا مدیریت جریان را ساده کند. جریان های دو جهته جایگزین ساختار
STREAM_FROM_STREAM
می شوند. - معناشناسی حالت محدود برای دستگاه های سخت افزاری قدیمی/محدود.
2.0
انتشار اولیه HAL با قابلیت توسعه یافته (Android 4.2) [camera2.h]:
- برای پیاده سازی
android.hardware.Camera
API موجود کافی است. - صف ZSL را در لایه سرویس دوربین اجازه می دهد.
- برای هیچ ویژگی جدیدی مانند کنترل ضبط دستی، ضبط RAW Bayer، پردازش مجدد دادههای RAW و غیره آزمایش نشده است.
1.0
دوربین اولیه Android HAL (Android 4.0) [camera.h]:
- از لایه انتزاعی CameraHardwareInterface C++ تبدیل شده است.
- از
android.hardware.Camera
API پشتیبانی می کند.
تاریخچه نسخه ماژول دوربین
این بخش حاوی اطلاعات نسخهسازی ماژول برای ماژول سختافزار دوربین، بر اساس camera_module_t.common.module_api_version
است. دو رقم شش ضلعی که بیشترین اهمیت را دارند نشان دهنده نسخه اصلی و دو رقم کم اهمیت نشان دهنده نسخه کوچک هستند.
2.4
این نسخه ماژول دوربین تغییرات API زیر را اضافه می کند:
- پشتیبانی از حالت مشعل این چارچوب میتواند حالت مشعل را برای هر دستگاه دوربینی که واحد فلاش دارد، بدون باز کردن دستگاه دوربین روشن کند. دستگاه دوربین برای دسترسی به واحد فلاش اولویت بیشتری نسبت به ماژول دوربین دارد. باز کردن یک دستگاه دوربین، مشعل را خاموش می کند اگر از طریق رابط ماژول فعال شده بود. هنگامی که هر گونه تداخل منابع وجود دارد، مانند
open()
برای باز کردن یک دستگاه دوربین، ماژول دوربین HAL باید چارچوب را از طریق پاسخ تماس وضعیت حالت مشعل اعلام کند که حالت مشعل خاموش شده است. - دوربین خارجی (به عنوان مثال، دوربین USB hot-plug) پشتیبانی می کند. بهروزرسانیهای API مشخص میکنند که اطلاعات استاتیک دوربین فقط زمانی در دسترس است که دوربین متصل باشد و برای دوربینهای خارجی با اتصال داغ آماده استفاده باشد. وقتی وضعیت دوربین
CAMERA_DEVICE_STATUS_PRESENT
نباشد، تماسها برای دریافت اطلاعات ثابت، تماسهای نامعتبر هستند. این چارچوب برای مدیریت لیست دوربین خارجی موجود، تنها بر روی تماسهای تغییر وضعیت دستگاه حساب میکند. - نکات داوری دوربین پشتیبانی برای نشان دادن صریح تعداد دستگاههای دوربینی که میتوان به طور همزمان باز و استفاده کرد اضافه میکند. برای تعیین ترکیبهای معتبر از دستگاهها، فیلدهای
resource_cost
وconflicting_devices
باید همیشه در ساختارcamera_info
که با تماسget_camera_info
بازگردانده شده است، تنظیم شوند. - روش مقداردهی اولیه ماژول پس از بارگیری ماژول HAL توسط سرویس دوربین فراخوانی می شود تا امکان راه اندازی یکباره HAL فراهم شود. قبل از فراخوانی هر روش ماژول دیگری فراخوانی می شود.
2.3
این نسخه ماژول دوربین پشتیبانی از دستگاه HAL دوربین قدیمی را اضافه می کند. اگر همان دستگاه بتواند از چندین نسخه API دستگاه پشتیبانی کند، چارچوب میتواند از آن برای باز کردن دستگاه دوربین به عنوان دستگاه HAL نسخه پایینتر استفاده کند. فراخوانی باز ماژول سخت افزاری استاندارد ( common.methods->open
) همچنان دستگاه دوربین را با آخرین نسخه پشتیبانی شده باز می کند، که همچنین نسخه فهرست شده در camera_info_t.device_version
است.
2.2
این نسخه ماژول دوربین، پشتیبانی از برچسب فروشنده را از ماژول اضافه میکند و vendor_tag_query_ops
قدیمی را که قبلاً فقط با دستگاه باز قابل دسترسی بودند، منسوخ میکند.
2.1
این نسخه ماژول دوربین از ماژول دوربین HAL پشتیبانی از تماس های ناهمزمان را به چارچوب اضافه می کند، که برای اطلاع رسانی به چارچوب در مورد تغییرات وضعیت ماژول دوربین استفاده می شود. ماژول هایی که یک متد set_callbacks()
معتبر ارائه می کنند باید حداقل این شماره نسخه را گزارش کنند.
2.0
ماژولهای دوربینی که این شماره نسخه را گزارش میکنند، نسخه دوم رابط ماژول دوربین HAL را اجرا میکنند. دستگاههای دوربین قابل باز شدن از طریق این ماژول ممکن است از نسخه 1.0 یا 2.0 رابط HAL دستگاه دوربین پشتیبانی کنند. قسمت device_version
دوربین_info همیشه معتبر است. قسمت static_camera_characteristics
camera_info
در صورتی معتبر است که قسمت device_version
2.0 یا بالاتر باشد.
1.0
ماژولهای دوربین که این شمارههای نسخه را گزارش میکنند، رابط HAL ماژول دوربین اولیه را پیادهسازی میکنند. تمام دستگاه های دوربین قابل باز شدن از طریق این ماژول فقط از نسخه 1 دستگاه دوربین HAL پشتیبانی می کنند. فیلدهای device_version
و static_camera_characteristics
camera_info
معتبر نیستند. فقط android.hardware.Camera
API می تواند توسط این ماژول و دستگاه های آن پشتیبانی شود.
این صفحه تفاوتهای نسخه در دوربینهای HAL، API و تستهای مجموعه تست سازگاری (CTS) مرتبط را توضیح میدهد. همچنین چندین تغییر معماری ایجاد شده برای سختتر کردن و ایمنسازی چارچوب دوربین در اندروید 7.0، تغییر به Treble در اندروید 8.0، و بهروزرسانیهایی را که فروشندگان باید برای پشتیبانی از این تغییرات در اجرای دوربین خود انجام دهند، پوشش میدهد.
واژه شناسی
در این صفحه از اصطلاحات زیر استفاده می شود:
- دوربین API1
- چارچوب دوربین در سطح برنامه در دستگاههای Android نسخه ۴.۴ و پایینتر، از طریق کلاس
android.hardware.Camera
در معرض دید قرار میگیرد. - دوربین API2
- چارچوب دوربین سطح برنامه در دستگاههای Android نسخه 5.0 و بالاتر، از طریق بسته
android.hardware.camera2
در معرض دید قرار میگیرد. - دوربین HAL
- لایه ماژول دوربین که توسط فروشندگان SoC پیاده سازی شده است. چارچوب های عمومی در سطح برنامه در بالای دوربین HAL ساخته شده اند.
- دوربین HAL3.1
- نسخه دوربین دستگاه HAL با اندروید 4.4 منتشر شد.
- دوربین HAL3.2
- نسخه دوربین دستگاه HAL با اندروید 5.0 منتشر شد.
- دوربین API1 CTS
- مجموعه ای از تست های CTS دوربین که در بالای دوربین API1 اجرا می شوند.
- دوربین API2 CTS
- مجموعه دیگری از تستهای CTS دوربین که در بالای دوربین API2 اجرا میشوند.
- سه گانه
- پیادهسازی فروشنده (نرمافزار سطح پایینتر و ویژه دستگاه را که توسط سازندگان سیلیکون نوشته شده است) از چارچوب سیستم عامل Android از طریق یک رابط فروشنده جدید جدا میکند.
- HIDL
- زبان تعریف رابط HAL با Treble معرفی شد و برای مشخص کردن رابط بین HAL و کاربران آن استفاده شد.
- VTS
- مجموعه تست فروشنده در کنار Treble معرفی شد.
API های دوربین
اندروید شامل API های دوربین زیر است.
دوربین API1
Android 5.0 Camera API1 منسوخ شده است، که با تمرکز توسعه پلتفرم جدید بر Camera API2، به تدریج حذف می شود. با این حال، دوره حذف تدریجی طولانی خواهد بود و نسخههای اندرویدی تا مدتی از برنامههای Camera API1 پشتیبانی خواهند کرد. به طور خاص، پشتیبانی برای:
- رابط های دوربین API1 برای برنامه ها. برنامههای دوربین ساختهشده در بالای Camera API1 باید مانند دستگاههایی که نسخههای پایینتر اندروید دارند کار کنند.
- نسخه های دوربین HAL. شامل پشتیبانی از دوربین HAL1.0 است.
دوربین API2
چارچوب Camera API2 کنترل دوربین سطح پایینتری را در اختیار برنامه قرار میدهد، از جمله جریانهای پیاپی/جریانگذاری کارآمد صفر کپی و کنترلهای نوردهی، افزایش، افزایش تعادل رنگ سفید، تبدیل رنگ، حذف نویز، شفافسازی و غیره در هر فریم. برای جزئیات، نمای کلی ویدیوی Google I/O را تماشا کنید.
اندروید 5.0 و بالاتر شامل Camera API2 است. با این حال، دستگاههای دارای Android نسخه 5.0 و بالاتر ممکن است از همه ویژگیهای Camera API2 پشتیبانی نکنند. ویژگی android.info.supportedHardwareLevel
که برنامهها میتوانند از طریق رابطهای Camera API2 درخواست کنند، یکی از سطوح پشتیبانی زیر را گزارش میدهد:
-
LEGACY
: این دستگاهها قابلیتهایی را از طریق رابطهای Camera API2 در معرض برنامهها قرار میدهند که تقریباً همان قابلیتهایی هستند که از طریق رابطهای Camera API1 در معرض برنامهها قرار میگیرند. کد فریمورک های قدیمی به طور مفهومی فراخوانی های Camera API2 را به تماس های Camera API1 تبدیل می کند. دستگاههای قدیمی از ویژگیهای Camera API2 مانند کنترلهای هر فریم پشتیبانی نمیکنند. -
LIMITED
: این دستگاهها از برخی قابلیتهای Camera API2 (اما نه همه) پشتیبانی میکنند و باید از دوربین HAL 3.2 یا بالاتر استفاده کنند. -
FULL
: این دستگاهها از تمام قابلیتهای اصلی Camera API2 پشتیبانی میکنند و باید از دوربین HAL 3.2 یا بالاتر و اندروید 5.0 یا بالاتر استفاده کنند. -
LEVEL_3
: این دستگاهها از پردازش مجدد YUV و ضبط تصویر RAW به همراه تنظیمات جریان خروجی اضافی پشتیبانی میکنند. -
EXTERNAL
: این دستگاه ها مشابه دستگاه هایLIMITED
با برخی استثناها هستند. به عنوان مثال، برخی از اطلاعات حسگر یا لنز ممکن است گزارش نشوند یا نرخ فریم پایدار کمتری داشته باشند. این سطح برای دوربین های خارجی مانند وب کم USB استفاده می شود.
قابلیتهای فردی از طریق ویژگی android.request.availableCapabilities
در رابطهای Camera API2 آشکار میشوند. دستگاههای FULL
به قابلیتهای MANUAL_SENSOR
و MANUAL_POST_PROCESSING
از جمله موارد دیگر نیاز دارند. قابلیت RAW
حتی برای دستگاه های FULL
اختیاری است. دستگاه های LIMITED
می توانند هر زیر مجموعه ای از این قابلیت ها را تبلیغ کنند، از جمله هیچ کدام. با این حال، قابلیت BACKWARD_COMPATIBLE
همیشه باید تعریف شود.
سطح سختافزار پشتیبانیشده دستگاه، و همچنین قابلیتهای خاص Camera API2 که از آن پشتیبانی میکند، بهعنوان پرچمهای ویژگی زیر در دسترس هستند تا به Google Play اجازه فیلتر کردن برنامههای دوربین دوربین API2 را بدهد.
-
android.hardware.camera.hardware_level.full
-
android.hardware.camera.capability.raw
-
android.hardware.camera.capability.manual_sensor
-
android.hardware.camera.capability.manual_post_processing
الزامات CTS
دستگاههایی که Android نسخه 5.0 و بالاتر دارند باید آزمایشهای دوربین API1 CTS، Camera API2 CTS و CTS Verifier را پشت سر بگذارند.
دستگاههایی که فاقد اجرای Camera HAL3.2 هستند و قادر به پشتیبانی از رابطهای کامل Camera API2 نیستند، همچنان باید تستهای Camera API2 CTS را پشت سر بگذارند. با این حال، دستگاه در حالت Camera API2 LEGACY
اجرا میشود (که در آن تماسهای Camera API2 به صورت مفهومی با تماسهای Camera API1 نگاشت میشوند) بنابراین هر آزمایش CTS دوربین API2 مربوط به ویژگیها یا قابلیتهای فراتر از Camera API1 بهطور خودکار نادیده گرفته میشود.
در دستگاههای قدیمی، آزمایشهای Camera API2 CTS که اجرا میشوند از رابطها و قابلیتهای عمومی Camera API1 بدون نیاز جدید استفاده میکنند. اشکالاتی که در معرض دید قرار میگیرند (و باعث خرابی دوربین API2 CTS میشوند) اشکالاتی هستند که از قبل در دوربین HAL موجود دستگاه وجود دارند و بنابراین توسط برنامههای Camera API1 موجود پیدا میشوند. ما انتظار بسیاری از باگهای این ماهیت را نداریم (با این حال، برای گذراندن تستهای Camera API2 CTS باید چنین اشکالاتی برطرف شود).
الزامات VTS
دستگاههای دارای Android نسخه ۸.۰ و بالاتر با اجرای HAL binderized باید تستهای Camera VTS را پشت سر بگذارند.
سخت شدن چارچوب دوربین
برای سختتر کردن رسانه و امنیت چارچوب دوربین، Android 7.0 سرویس دوربین را از سرور رسانه خارج میکند. با شروع Android 8.0، هر دوربین HAL بایندر شده در فرآیندی جدا از سرویس دوربین اجرا میشود. ممکن است فروشندگان بسته به نسخه های API و HAL در حال استفاده، نیاز به تغییر در HAL دوربین داشته باشند. بخشهای زیر تغییرات معماری در AP1 و AP2 برای HAL1 و HAL3 و همچنین الزامات کلی را شرح میدهد.
تغییرات معماری برای API1
ضبط ویدیوی API1 ممکن است دوربین و رمزگذار ویدیو را در یک فرآیند زنده فرض کند. هنگام استفاده از API1 در:
- HAL3، جایی که سرویس دوربین از BufferQueue برای عبور بافرها بین فرآیندها استفاده می کند، به روز رسانی فروشنده لازم نیست .
شکل 1. دوربین اندروید 7.0 و پشته رسانه در API1 در HAL3
- HAL1 که از ارسال ابرداده در بافرهای ویدیویی پشتیبانی میکند، فروشندگان باید HAL را برای استفاده از
kMetadataBufferTypeNativeHandleSource
بهروزرسانی کنند. (kMetadataBufferTypeCameraSource
دیگر در Android 7.0 پشتیبانی نمیشود.)شکل 2. دوربین اندروید 7.0 و پشته رسانه در API1 در HAL1
تغییرات معماری برای API2
برای API2 در HAL1 یا HAL3، BufferQueue بافرها را پاس میکند تا این مسیرها به کار خود ادامه دهند. معماری Android 7.0 برای API2 در:
- HAL1 تحت تأثیر حرکت دوربین سرویس قرار نمی گیرد و به روز رسانی فروشنده لازم نیست .
- HAL3 تحت تأثیر قرار گرفته است ، اما بهروزرسانی فروشنده لازم نیست :
شکل 3. دوربین اندروید 7.0 و پشته رسانه در API2 در HAL3
الزامات اضافی
تغییرات معماری ایجاد شده برای سخت شدن رسانه و امنیت چارچوب دوربین شامل الزامات دستگاه اضافی زیر است.
- عمومی. Devices require additional bandwidth due to IPC, which may affect time-sensitive camera use cases such as high-speed video recording. Vendors can measure actual impact by running
android.hardware.camera2.cts.PerformanceTest
and the Google Camera app for 120/240 FPS high-speed video recording. Devices also require a small amount of additional RAM to create the new process. - Pass metadata in video buffers ( HAL1 only ). If HAL1 stores metadata instead of real YUV frame data in video buffers, the HAL must use
kMetadataBufferTypeNativeHandleSource
as the metadata buffer type and passVideoNativeHandleMetadata
in video buffers. (kMetadataBufferTypeCameraSource
is no longer supported on Android 7.0.) WithVideoNativeHandleMetadata
, camera and media frameworks are able to pass the video buffers between processes by serializing and deserializing the native handles properly. - Buffer handle address doesn't always store the same buffer ( HAL3 only ). For each capture request, HAL3 gets addresses of buffer handles. HAL can't use the addresses to identify buffers because the addresses may store another buffer handle after HAL returns the buffer. You must update the HAL to use buffer handles to identify the buffers. For example, HAL receives a buffer handle address A, which stores buffer handle A. After HAL returns buffer handle A, buffer handle address A may store buffer handle B next time the HAL receives it.
- Update SELinux policies for cameraserver. If device-specific SELinux policies give mediaserver permissions to run the camera, you must update the SELinux policies to give cameraserver proper permissions. We discourage replicating the mediaserver's SELinux policies for cameraserver (as mediaserver and cameraserver generally require different resources in the system). Cameraserver should have only the permissions needed to perform camera functionalities and any unnecessary camera-related permissions in mediaserver should be removed.
- Separation between Camera HAL and cameraserver. Android 8.0 and higher additionally separate the binderized Camera HAL in a process different from cameraserver. IPC goes through HIDL-defined interfaces.
اعتبار سنجی
For all devices that include a camera and run Android 7.0, verify the implementation by running Android 7.0 CTS. Although Android 7.0 doesn't include new CTS tests that verify camera service changes, existing CTS tests fail if you haven't made the updates indicated above.
For all devices that include a camera and run Android 8.0 and higher, verify the vendor implementation by running VTS.
Camera HAL version history
For a list of tests available for evaluating the Android Camera HAL, see the Camera HAL Testing Checklist .
Android 10
Android 10 introduces the following updates.
Camera API
- Multi-camera improvements that allow physical cameras to be used individually or through corresponding logical cameras by hiding physical camera IDs. See Multi-Camera Support .
- Ability to check whether a particular session configuration is supported without the performance overhead of creating a new session. See
CameraDevice
. - Ability to retrieve recommended stream configurations for a given use case to make the client more power efficient and performant. See
getRecommendedStreamConfigurationMap
. - Support for the depth JPEG image format . For further details, see the Dynamic Depth specification .
- Support for the HEIC Image format . See HEIF Imaging .
- Privacy improvements. Certain keys are required for the client to have
CAMERA
permissions before they can be retrieved fromCameraCharacteristics
. SeegetKeysNeedingPermission
.
Camera HAL
The following Camera HAL versions are updated in Android 10.
3.5
ICameraDevice
-
getPhysicalCameraCharacteristics
: The static camera information for a physical camera ID backing a logical camera device. See Multi-Camera Support . -
isStreamCombinationSupported
: This method supports a public API that helps clients query if a session configuration is supported. See API to query stream combinations .
ICameraDeviceSession
-
isReconfigurationNeeded
: Method that tells the camera framework whether complete stream reconfiguration is required for possible new session parameter values. This helps avoid unnecessary camera reconfiguration delays. See Session reconfiguration query . - HAL buffer management APIs : These APIs allow the camera HAL to request buffers from the camera framework only when required instead of coupling each capture request with its associated buffers throughout the camera pipeline, resulting in potentially significant memory savings.
-
signalStreamFlush
: Signals to the HAL that the camera service is about to performconfigureStreams_3_5
and that the HAL must return all buffers of designated streams. -
configureStreams_3_5
: Similar toICameraDevice3.4.configureStreams
, but in addition, thestreamConfigCounter
counter is provided to check for a race condition between theconfigureStreams_3_5
andsignalStreamFlush
calls.
-
Updates to ICameraDeviceCallback
:
-
requestStreamBuffers
: Synchronous callback that the camera HAL calls to ask the camera server for buffers. SeerequestStreamBuffers
. -
returnStreamBuffers
: Synchronous callback for the camera HAL to return output buffers to the camera server. SeereturnStreamBuffers
.
3.4
The following keys are added to camera metadata in Android 10.
- Image formats
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW10
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW12
-
ANDROID_SCALER_AVAILABLE_FORMATS_Y8
-
- Camera metadata tags
-
ANDROID_REQUEST_CHARACTERISTIC_KEYS_NEEDING_PERMISSION
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_INPUT_OUTPUT_FORMATS_MAP
-
ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION
-
ANDROID_DEPTH_AVAILABLE_RECOMMENDED_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_MIN_FRAME_DURATIONS
-
ANDROID_LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_MIN_FRAME_DURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_STALL_DURATIONS
-
ANDROID_HEIC_INFO_SUPPORTED
-
ANDROID_HEIC_INFO_MAX_JPEG_APP_SEGMENTS_COUNT
-
- Capabilities
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_SECURE_IMAGE_DATA
-
- Values for the
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
key-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_MONO
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_NIR
-
- Available dynamic depth stream configurations
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_INPUT
-
- Available HEIC stream configurations
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_INPUT
-
Camera module
The following camera module versions are updated in Android 10.
2.5
- Adds the
notifyDeviceStateChange
method for devices to notify the camera HAL when physical changes, such as folding, affect camera and routing.
2.4
- Devices launching with API level 29 or higher MUST report
true
forisTorchModeSupported
.
Android 9
The Android 9 release introduces the following updates to the camera API2 and HAL interface.
Camera API
- Introduces the multi-camera API to better support devices with multiple cameras facing in the same direction, enabling features such as bokeh and seamless zoom. This allows apps to view multiple cameras on a device as one logical unit (logical camera). Capture requests can also be sent to individual camera devices encompassed by one logical camera. See Multi-Camera Support .
- Introduces session parameters. Session parameters are a subset of the available capture parameters that can cause severe processing delays when modified. These costs can be mitigated if clients pass their initial values during capture session initialization. See Session Parameters .
- Adds optical stabilization (OIS) data keys for app-level stabilization and effects. See
STATISTICS_OIS_SAMPLES
. - Adds external flash support. See
CONTROL_AE_MODE_ON_EXTERNAL_FLASH
. - Adds a motion tracking intent in
CAPTURE_INTENT
. SeeCONTROL_CAPTURE_INTENT_MOTION_TRACKING
. - Deprecates
LENS_RADIAL_DISTORTION
and addsLENS_DISTORTION
in its place. - Adds distortion correction modes in
CaptureRequest
. SeeDISTORTION_CORRECTION_MODE
. - Adds support for external USB/UVC cameras on supported devices. See
INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL
.
Camera HAL
3.4
Updates to ICameraDeviceSession
-
configureStreams_3_4
: Adds support forsessionParameters
and logical cameras. -
processCaptureRequest_3_4
: Adds support for including physical camera IDs in stream structure.
Updates to ICameraDeviceCallback
-
processCaptureResult_3_4
: Adds physical camera metadata in capture results.
3.3
The following keys are added to camera metadata in Android 9.
- Capabilities
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
-
- Camera metadata tags
-
ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS
-
ANDROID_LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE
-
ANDROID_DISTORTION_CORRECTION_AVAILABLE_MODES
-
ANDROID_LENS_POSE_REFERENCE
-
ANDROID_LENS_DISTORTION
-
ANDROID_REQUEST_AVAILABLE_SESSION_KEYS
-
ANDROID_REQUEST_AVAILABLE_PHYSICAL_CAMERA_REQUEST_KEYS
-
ANDROID_STATISTICS_OIS_DATA_MODE
-
ANDROID_STATISTICS_OIS_TIMESTAMPS
-
ANDROID_STATISTICS_OIS_X_SHIFTS
-
ANDROID_STATISTICS_OIS_Y_SHIFTS
-
Android 8.0
The Android 8.0 release introduces Treble. With Treble, vendor Camera HAL implementations must be binderized . Android 8.0 also contains these key enhancements to the Camera service:
- Shared surfaces: Enable multiple surfaces sharing the same
OutputConfiguration
- System API for custom camera modes
-
onCaptureQueueEmpty
See the sections below for more information on these features.
Shared surfaces
This feature enables only one set of buffers to drive two outputs, such as preview and video encoding, which lowers power and memory consumption. To support this feature, device manufacturers need to ensure their camera HAL and gralloc HAL implementations can create gralloc buffers that are used by multiple different consumers (such as the hardware composer/GPU and the video encoder), instead of just one consumer. The camera service passes the consumer usage flags to the camera HAL and the gralloc HAL; they need to either allocate the right kinds of buffers, or the camera HAL needs to return an error that this combination of consumers isn't supported.
See the enableSurfaceSharing
developer documentation for additional details.
System API for custom camera modes
The public camera API defines two operating modes: normal and constrained high-speed recording. They have fairly different semantics; for example, high-speed mode is limited to at most two specific outputs at once. Various OEMs have expressed interest in defining other custom modes for hardware-specific capabilities. Under the hood, the mode is just an integer passed to configure_streams
. See: hardware/camera/device/3.2/ICameraDeviceSession#configurestreams
.
This feature includes a system API call that OEM camera apps can use to enable a custom mode. These modes must start at integer value 0x8000 to avoid conflicting with future modes added to the public API.
To support this feature, OEMs merely need to add the new mode to their HAL, triggered by this integer passed to the HAL on configure_streams, and then have their custom camera app use the system API.
The method name is android.hardware.camera2.CameraDevice#createCustomCaptureSession
. See: frameworks/base/core/java/android/hardware/camera2/CameraDevice
.
onCaptureQueueEmpty
The purpose of this API is to reduce the latency of control changes like zoom by keeping the request queue as empty as possible. onCaptureQueueEmpty
requires no HAL work; it was purely a framework-side addition. Applications that want to take advantage of it need to add a listener to that callback and respond appropriately. Generally that's by sending another capture request to the camera device.
Camera HIDL interface
The Camera HIDL interface is a complete overhaul of the Camera HAL interface that uses stable HIDL-defined APIs. All features and camera capabilities introduced in the most recent legacy versions 3.4 and 2.4 (for the camera module) are also part of the HIDL definitions.
3.4
Minor additions to supported metadata and changes to data_space support:
- Add
ANDROID_SENSOR_OPAQUE_RAW_SIZE
static metadata as mandatory ifRAW_OPAQUE
format is supported. - Add
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
static metadata as mandatory if any RAW format is supported. - Switch
camera3_stream_t data_space
field to a more flexible definition, using the version 0 definition of dataspace encoding. - General metadata additions which are available to use for HALv3.2 or newer:
-
ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
-
ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL
-
ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL
-
ANDROID_SENSOR_OPAQUE_RAW_SIZE
-
ANDROID_SENSOR_OPTICAL_BLACK_REGIONS
-
3.3
Minor revision of expanded-capability HAL:
- OPAQUE and YUV reprocessing API updates.
- Basic support for depth output buffers.
- Addition of
data_space
field tocamera3_stream_t
. - Addition of rotation field to
camera3_stream_t
. - Addition of camera3 stream configuration operation mode to
camera3_stream_configuration_t
.
3.2
Minor revision of expanded-capability HAL:
- Deprecates
get_metadata_vendor_tag_ops
. Useget_vendor_tag_ops
incamera_common.h
instead. - Deprecates
register_stream_buffers
. All gralloc buffers provided by framework to HAL inprocess_capture_request
may be new at any time. - Add partial result support.
process_capture_result
may be called multiple times with a subset of the available results before the full result is available. - Add manual template to
camera3_request_template
. Applications may use this template to control the capture settings directly. - Rework the bidirectional and input stream specifications.
- Change the input buffer return path. The buffer is returned in
process_capture_result
instead ofprocess_capture_request
.
3.1
Minor revision of expanded-capability HAL:
-
configure_streams
passes consumer usage flags to the HAL. - flush call to drop all in-flight requests/buffers as fast as possible.
3.0
First revision of expanded-capability HAL:
- Major version change since the ABI is completely different. No change to the required hardware capabilities or operational model from 2.0.
- Reworked input request and stream queue interfaces: Framework calls into HAL with next request and stream buffers already dequeued. Sync framework support is included, necessary for efficient implementations.
- Moved triggers into requests, most notifications into results.
- Consolidated all callbacks into framework into one structure, and all setup methods into a single
initialize()
call. - Made stream configuration into a single call to simplify stream management. Bidirectional streams replace the
STREAM_FROM_STREAM
construct. - Limited mode semantics for older/limited hardware devices.
2.0
Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:
- Sufficient for implementing existing
android.hardware.Camera
API. - Allows for ZSL queue in camera service layer.
- Not tested for any new features such as manual capture control, Bayer RAW capture, reprocessing of RAW data, etc.
1.0
Initial Android camera HAL (Android 4.0) [camera.h]:
- Converted from C++ CameraHardwareInterface abstraction layer.
- Supports
android.hardware.Camera
API.
Camera module version history
This section contains module versioning information for the Camera hardware module, based on camera_module_t.common.module_api_version
. The two most significant hex digits represent the major version, and the two least significant represent the minor version.
2.4
This camera module version adds the following API changes:
- Torch mode support. The framework can turn on torch mode for any camera device that has a flash unit, without opening a camera device. The camera device has a higher priority accessing the flash unit than the camera module; opening a camera device turns off the torch if it had been enabled through the module interface. When there are any resource conflicts, such as
open()
is called to open a camera device, the camera HAL module must notify the framework through the torch mode status callback that the torch mode has been turned off. - External camera (for example, USB hot-plug camera) support. The API updates specify the camera static info is available only when camera is connected and ready to use for external hot-plug cameras. Calls to get static info are invalid calls when camera status isn't
CAMERA_DEVICE_STATUS_PRESENT
. The framework counts solely on device status change callbacks to manage the available external camera list. - Camera arbitration hints. Adds support for explicitly indicating the number of camera devices that can be simultaneously opened and used. To specify valid combinations of devices, the
resource_cost
andconflicting_devices
fields should always be set in thecamera_info
structure returned by theget_camera_info
call. - Module initialization method. Called by the camera service after the HAL module is loaded to allow for one-time initialization of the HAL. It is called before any other module methods are invoked.
2.3
This camera module version adds open legacy camera HAL device support. The framework can use it to open the camera device as lower device HAL version HAL device if the same device can support multiple device API versions. The standard hardware module open call ( common.methods->open
) continues to open the camera device with the latest supported version, which is also the version listed in camera_info_t.device_version
.
2.2
This camera module version adds vendor tag support from the module, and deprecates the old vendor_tag_query_ops
that were previously only accessible with a device open.
2.1
This camera module version adds support for asynchronous callbacks to the framework from the camera HAL module, which is used to notify the framework about changes to the camera module state. Modules that provide a valid set_callbacks()
method must report at least this version number.
2.0
Camera modules that report this version number implement the second version of the camera module HAL interface. Camera devices openable through this module may support either version 1.0 or version 2.0 of the camera device HAL interface. The device_version
field of camera_info is always valid; the static_camera_characteristics
field of camera_info
is valid if the device_version
field is 2.0 or higher.
1.0
Camera modules that report these version numbers implement the initial camera module HAL interface. All camera devices openable through this module support only version 1 of the camera device HAL. The device_version
and static_camera_characteristics
fields of camera_info
aren't valid. Only the android.hardware.Camera
API can be supported by this module and its devices.
This page details version differences in Camera HALs, APIs, and associated Compatibility Test Suite (CTS) tests. It also covers several architectural changes made to harden and secure the camera framework in Android 7.0, the switch to Treble in Android 8.0, and the updates vendors must make to support these changes in their camera implementations.
Terminology
The following terms are used on this page:
- Camera API1
- The app-level camera framework on Android 4.4 and lower devices, exposed through the
android.hardware.Camera
class. - Camera API2
- The app-level camera framework on Android 5.0 and higher devices, exposed through the
android.hardware.camera2
package. - Camera HAL
- The camera module layer implemented by SoC vendors. The app-level public frameworks are built on top of the camera HAL.
- Camera HAL3.1
- Version of the camera device HAL released with Android 4.4.
- Camera HAL3.2
- Version of the camera device HAL released with Android 5.0.
- Camera API1 CTS
- Set of camera CTS tests that run on top of Camera API1.
- Camera API2 CTS
- Additional set of camera CTS tests that run on top of Camera API2.
- Treble
- Separates the vendor implementation (device-specific, lower-level software written by silicon manufacturers) from the Android OS framework through a new vendor interface.
- HIDL
- HAL interface definition language introduced with Treble and used to specify the interface between a HAL and its users.
- VTS
- Vendor test suite introduced alongside Treble.
Camera APIs
Android includes the following camera APIs.
Camera API1
Android 5.0 deprecated Camera API1, which continues to be phased out as new platform development focuses on Camera API2. However, the phase-out period will be lengthy, and Android releases will continue to support Camera API1 apps for some time. Specifically, support continues for:
- Camera API1 interfaces for apps. Camera apps built on top of Camera API1 should work as they do on devices running lower Android release versions.
- Camera HAL versions. Includes support for Camera HAL1.0.
Camera API2
The Camera API2 framework exposes lower-level camera control to the app, including efficient zero-copy burst/streaming flows and per-frame controls of exposure, gain, white balance gains, color conversion, denoising, sharpening, and more. For details, watch the Google I/O video overview .
Android 5.0 and higher includes Camera API2; however, devices running Android 5.0 and higher may not support all Camera API2 features. The android.info.supportedHardwareLevel
property that apps can query through the Camera API2 interfaces reports one of the following support levels:
-
LEGACY
: These devices expose capabilities to apps through the Camera API2 interfaces that are approximately the same capabilities as those exposed to apps through the Camera API1 interfaces. The legacy frameworks code conceptually translates Camera API2 calls into Camera API1 calls; legacy devices don't support Camera API2 features such as per-frame controls. -
LIMITED
: These devices support some Camera API2 capabilities (but not all) and must use Camera HAL 3.2 or higher. -
FULL
: These devices support all of the major capabilities of Camera API2 and must use Camera HAL 3.2 or higher and Android 5.0 or higher. -
LEVEL_3
: These devices support YUV reprocessing and RAW image capture, along with additional output stream configurations. -
EXTERNAL
: These devices are similar toLIMITED
devices with some exceptions; for example, some sensor or lens information may not be reported or have less stable frame rates. This level is used for external cameras such as USB webcams.
Individual capabilities are exposed through the android.request.availableCapabilities
property in the Camera API2 interfaces. FULL
devices require the MANUAL_SENSOR
and MANUAL_POST_PROCESSING
capabilities, among others. The RAW
capability is optional even for FULL
devices. LIMITED
devices can advertise any subset of these capabilities, including none of them. However, the BACKWARD_COMPATIBLE
capability must always be defined.
The supported hardware level of the device, as well as the specific Camera API2 capabilities it supports, are available as the following feature flags to allow Google Play filtering of Camera API2 camera apps.
-
android.hardware.camera.hardware_level.full
-
android.hardware.camera.capability.raw
-
android.hardware.camera.capability.manual_sensor
-
android.hardware.camera.capability.manual_post_processing
CTS requirements
Devices running Android 5.0 and higher must pass the Camera API1 CTS, Camera API2 CTS, and CTS Verifier camera tests.
Devices that don't feature a Camera HAL3.2 implementation and aren't capable of supporting the full Camera API2 interfaces must still pass the Camera API2 CTS tests. However, the device runs in Camera API2 LEGACY
mode (in which the Camera API2 calls are conceptually mapped to Camera API1 calls) so any Camera API2 CTS tests related to features or capabilities beyond Camera API1 are automatically skipped.
On legacy devices, Camera API2 CTS tests that are run use the existing public Camera API1 interfaces and capabilities with no new requirements. Bugs that are exposed (and that cause a Camera API2 CTS failure) are bugs already present in the device's existing Camera HAL, and thus would be found by existing Camera API1 apps. We don't expect many bugs of this nature (however, any such bugs must be fixed to pass the Camera API2 CTS tests).
VTS requirements
Devices running Android 8.0 and higher with binderized HAL implementations must pass the Camera VTS tests .
Camera framework hardening
To harden media and camera framework security, Android 7.0 moves camera service out of mediaserver. Starting with Android 8.0, each binderized Camera HAL runs in a process separate from camera service. Vendors may need to make changes in the camera HAL depending on the API and HAL versions in use. The following sections detail architectural changes in AP1 and AP2 for HAL1 and HAL3, as well as general requirements.
Architectural changes for API1
API1 video recording may assume camera and video encoder live in the same process. When using API1 on:
- HAL3, where camera service uses BufferQueue to pass buffers between processes, no vendor update is necessary.
Figure 1. Android 7.0 camera and media stack in API1 on HAL3
- HAL1, which supports passing metadata in video buffers, vendors must update the HAL to use
kMetadataBufferTypeNativeHandleSource
. (kMetadataBufferTypeCameraSource
is no longer supported in Android 7.0.)Figure 2. Android 7.0 camera and media stack in API1 on HAL1
Architectural changes for API2
For API2 on HAL1 or HAL3, BufferQueue passes buffers so those paths continue to work. The Android 7.0 architecture for API2 on:
- HAL1 isn't affected by the cameraservice move, and no vendor update is necessary.
- HAL3 is affected, but no vendor update is necessary:
Figure 3. Android 7.0 camera and media stack in API2 on HAL3
Additional requirements
The architectural changes made for hardening media and camera framework security include the following additional device requirements.
- General. Devices require additional bandwidth due to IPC, which may affect time-sensitive camera use cases such as high-speed video recording. Vendors can measure actual impact by running
android.hardware.camera2.cts.PerformanceTest
and the Google Camera app for 120/240 FPS high-speed video recording. Devices also require a small amount of additional RAM to create the new process. - Pass metadata in video buffers ( HAL1 only ). If HAL1 stores metadata instead of real YUV frame data in video buffers, the HAL must use
kMetadataBufferTypeNativeHandleSource
as the metadata buffer type and passVideoNativeHandleMetadata
in video buffers. (kMetadataBufferTypeCameraSource
is no longer supported on Android 7.0.) WithVideoNativeHandleMetadata
, camera and media frameworks are able to pass the video buffers between processes by serializing and deserializing the native handles properly. - Buffer handle address doesn't always store the same buffer ( HAL3 only ). For each capture request, HAL3 gets addresses of buffer handles. HAL can't use the addresses to identify buffers because the addresses may store another buffer handle after HAL returns the buffer. You must update the HAL to use buffer handles to identify the buffers. For example, HAL receives a buffer handle address A, which stores buffer handle A. After HAL returns buffer handle A, buffer handle address A may store buffer handle B next time the HAL receives it.
- Update SELinux policies for cameraserver. If device-specific SELinux policies give mediaserver permissions to run the camera, you must update the SELinux policies to give cameraserver proper permissions. We discourage replicating the mediaserver's SELinux policies for cameraserver (as mediaserver and cameraserver generally require different resources in the system). Cameraserver should have only the permissions needed to perform camera functionalities and any unnecessary camera-related permissions in mediaserver should be removed.
- Separation between Camera HAL and cameraserver. Android 8.0 and higher additionally separate the binderized Camera HAL in a process different from cameraserver. IPC goes through HIDL-defined interfaces.
اعتبار سنجی
For all devices that include a camera and run Android 7.0, verify the implementation by running Android 7.0 CTS. Although Android 7.0 doesn't include new CTS tests that verify camera service changes, existing CTS tests fail if you haven't made the updates indicated above.
For all devices that include a camera and run Android 8.0 and higher, verify the vendor implementation by running VTS.
Camera HAL version history
For a list of tests available for evaluating the Android Camera HAL, see the Camera HAL Testing Checklist .
Android 10
Android 10 introduces the following updates.
Camera API
- Multi-camera improvements that allow physical cameras to be used individually or through corresponding logical cameras by hiding physical camera IDs. See Multi-Camera Support .
- Ability to check whether a particular session configuration is supported without the performance overhead of creating a new session. See
CameraDevice
. - Ability to retrieve recommended stream configurations for a given use case to make the client more power efficient and performant. See
getRecommendedStreamConfigurationMap
. - Support for the depth JPEG image format . For further details, see the Dynamic Depth specification .
- Support for the HEIC Image format . See HEIF Imaging .
- Privacy improvements. Certain keys are required for the client to have
CAMERA
permissions before they can be retrieved fromCameraCharacteristics
. SeegetKeysNeedingPermission
.
Camera HAL
The following Camera HAL versions are updated in Android 10.
3.5
ICameraDevice
-
getPhysicalCameraCharacteristics
: The static camera information for a physical camera ID backing a logical camera device. See Multi-Camera Support . -
isStreamCombinationSupported
: This method supports a public API that helps clients query if a session configuration is supported. See API to query stream combinations .
ICameraDeviceSession
-
isReconfigurationNeeded
: Method that tells the camera framework whether complete stream reconfiguration is required for possible new session parameter values. This helps avoid unnecessary camera reconfiguration delays. See Session reconfiguration query . - HAL buffer management APIs : These APIs allow the camera HAL to request buffers from the camera framework only when required instead of coupling each capture request with its associated buffers throughout the camera pipeline, resulting in potentially significant memory savings.
-
signalStreamFlush
: Signals to the HAL that the camera service is about to performconfigureStreams_3_5
and that the HAL must return all buffers of designated streams. -
configureStreams_3_5
: Similar toICameraDevice3.4.configureStreams
, but in addition, thestreamConfigCounter
counter is provided to check for a race condition between theconfigureStreams_3_5
andsignalStreamFlush
calls.
-
Updates to ICameraDeviceCallback
:
-
requestStreamBuffers
: Synchronous callback that the camera HAL calls to ask the camera server for buffers. SeerequestStreamBuffers
. -
returnStreamBuffers
: Synchronous callback for the camera HAL to return output buffers to the camera server. SeereturnStreamBuffers
.
3.4
The following keys are added to camera metadata in Android 10.
- Image formats
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW10
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW12
-
ANDROID_SCALER_AVAILABLE_FORMATS_Y8
-
- Camera metadata tags
-
ANDROID_REQUEST_CHARACTERISTIC_KEYS_NEEDING_PERMISSION
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_INPUT_OUTPUT_FORMATS_MAP
-
ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION
-
ANDROID_DEPTH_AVAILABLE_RECOMMENDED_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_MIN_FRAME_DURATIONS
-
ANDROID_LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_MIN_FRAME_DURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_STALL_DURATIONS
-
ANDROID_HEIC_INFO_SUPPORTED
-
ANDROID_HEIC_INFO_MAX_JPEG_APP_SEGMENTS_COUNT
-
- Capabilities
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_SECURE_IMAGE_DATA
-
- Values for the
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
key-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_MONO
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_NIR
-
- Available dynamic depth stream configurations
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_INPUT
-
- Available HEIC stream configurations
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_INPUT
-
Camera module
The following camera module versions are updated in Android 10.
2.5
- Adds the
notifyDeviceStateChange
method for devices to notify the camera HAL when physical changes, such as folding, affect camera and routing.
2.4
- Devices launching with API level 29 or higher MUST report
true
forisTorchModeSupported
.
Android 9
The Android 9 release introduces the following updates to the camera API2 and HAL interface.
Camera API
- Introduces the multi-camera API to better support devices with multiple cameras facing in the same direction, enabling features such as bokeh and seamless zoom. This allows apps to view multiple cameras on a device as one logical unit (logical camera). Capture requests can also be sent to individual camera devices encompassed by one logical camera. See Multi-Camera Support .
- Introduces session parameters. Session parameters are a subset of the available capture parameters that can cause severe processing delays when modified. These costs can be mitigated if clients pass their initial values during capture session initialization. See Session Parameters .
- Adds optical stabilization (OIS) data keys for app-level stabilization and effects. See
STATISTICS_OIS_SAMPLES
. - Adds external flash support. See
CONTROL_AE_MODE_ON_EXTERNAL_FLASH
. - Adds a motion tracking intent in
CAPTURE_INTENT
. SeeCONTROL_CAPTURE_INTENT_MOTION_TRACKING
. - Deprecates
LENS_RADIAL_DISTORTION
and addsLENS_DISTORTION
in its place. - Adds distortion correction modes in
CaptureRequest
. SeeDISTORTION_CORRECTION_MODE
. - Adds support for external USB/UVC cameras on supported devices. See
INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL
.
Camera HAL
3.4
Updates to ICameraDeviceSession
-
configureStreams_3_4
: Adds support forsessionParameters
and logical cameras. -
processCaptureRequest_3_4
: Adds support for including physical camera IDs in stream structure.
Updates to ICameraDeviceCallback
-
processCaptureResult_3_4
: Adds physical camera metadata in capture results.
3.3
The following keys are added to camera metadata in Android 9.
- Capabilities
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
-
- Camera metadata tags
-
ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS
-
ANDROID_LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE
-
ANDROID_DISTORTION_CORRECTION_AVAILABLE_MODES
-
ANDROID_LENS_POSE_REFERENCE
-
ANDROID_LENS_DISTORTION
-
ANDROID_REQUEST_AVAILABLE_SESSION_KEYS
-
ANDROID_REQUEST_AVAILABLE_PHYSICAL_CAMERA_REQUEST_KEYS
-
ANDROID_STATISTICS_OIS_DATA_MODE
-
ANDROID_STATISTICS_OIS_TIMESTAMPS
-
ANDROID_STATISTICS_OIS_X_SHIFTS
-
ANDROID_STATISTICS_OIS_Y_SHIFTS
-
Android 8.0
The Android 8.0 release introduces Treble. With Treble, vendor Camera HAL implementations must be binderized . Android 8.0 also contains these key enhancements to the Camera service:
- Shared surfaces: Enable multiple surfaces sharing the same
OutputConfiguration
- System API for custom camera modes
-
onCaptureQueueEmpty
See the sections below for more information on these features.
Shared surfaces
This feature enables only one set of buffers to drive two outputs, such as preview and video encoding, which lowers power and memory consumption. To support this feature, device manufacturers need to ensure their camera HAL and gralloc HAL implementations can create gralloc buffers that are used by multiple different consumers (such as the hardware composer/GPU and the video encoder), instead of just one consumer. The camera service passes the consumer usage flags to the camera HAL and the gralloc HAL; they need to either allocate the right kinds of buffers, or the camera HAL needs to return an error that this combination of consumers isn't supported.
See the enableSurfaceSharing
developer documentation for additional details.
System API for custom camera modes
The public camera API defines two operating modes: normal and constrained high-speed recording. They have fairly different semantics; for example, high-speed mode is limited to at most two specific outputs at once. Various OEMs have expressed interest in defining other custom modes for hardware-specific capabilities. Under the hood, the mode is just an integer passed to configure_streams
. See: hardware/camera/device/3.2/ICameraDeviceSession#configurestreams
.
This feature includes a system API call that OEM camera apps can use to enable a custom mode. These modes must start at integer value 0x8000 to avoid conflicting with future modes added to the public API.
To support this feature, OEMs merely need to add the new mode to their HAL, triggered by this integer passed to the HAL on configure_streams, and then have their custom camera app use the system API.
The method name is android.hardware.camera2.CameraDevice#createCustomCaptureSession
. See: frameworks/base/core/java/android/hardware/camera2/CameraDevice
.
onCaptureQueueEmpty
The purpose of this API is to reduce the latency of control changes like zoom by keeping the request queue as empty as possible. onCaptureQueueEmpty
requires no HAL work; it was purely a framework-side addition. Applications that want to take advantage of it need to add a listener to that callback and respond appropriately. Generally that's by sending another capture request to the camera device.
Camera HIDL interface
The Camera HIDL interface is a complete overhaul of the Camera HAL interface that uses stable HIDL-defined APIs. All features and camera capabilities introduced in the most recent legacy versions 3.4 and 2.4 (for the camera module) are also part of the HIDL definitions.
3.4
Minor additions to supported metadata and changes to data_space support:
- Add
ANDROID_SENSOR_OPAQUE_RAW_SIZE
static metadata as mandatory ifRAW_OPAQUE
format is supported. - Add
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
static metadata as mandatory if any RAW format is supported. - Switch
camera3_stream_t data_space
field to a more flexible definition, using the version 0 definition of dataspace encoding. - General metadata additions which are available to use for HALv3.2 or newer:
-
ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
-
ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL
-
ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL
-
ANDROID_SENSOR_OPAQUE_RAW_SIZE
-
ANDROID_SENSOR_OPTICAL_BLACK_REGIONS
-
3.3
Minor revision of expanded-capability HAL:
- OPAQUE and YUV reprocessing API updates.
- Basic support for depth output buffers.
- Addition of
data_space
field tocamera3_stream_t
. - Addition of rotation field to
camera3_stream_t
. - Addition of camera3 stream configuration operation mode to
camera3_stream_configuration_t
.
3.2
Minor revision of expanded-capability HAL:
- Deprecates
get_metadata_vendor_tag_ops
. Useget_vendor_tag_ops
incamera_common.h
instead. - Deprecates
register_stream_buffers
. All gralloc buffers provided by framework to HAL inprocess_capture_request
may be new at any time. - Add partial result support.
process_capture_result
may be called multiple times with a subset of the available results before the full result is available. - Add manual template to
camera3_request_template
. Applications may use this template to control the capture settings directly. - Rework the bidirectional and input stream specifications.
- Change the input buffer return path. The buffer is returned in
process_capture_result
instead ofprocess_capture_request
.
3.1
Minor revision of expanded-capability HAL:
-
configure_streams
passes consumer usage flags to the HAL. - flush call to drop all in-flight requests/buffers as fast as possible.
3.0
First revision of expanded-capability HAL:
- Major version change since the ABI is completely different. No change to the required hardware capabilities or operational model from 2.0.
- Reworked input request and stream queue interfaces: Framework calls into HAL with next request and stream buffers already dequeued. Sync framework support is included, necessary for efficient implementations.
- Moved triggers into requests, most notifications into results.
- Consolidated all callbacks into framework into one structure, and all setup methods into a single
initialize()
call. - Made stream configuration into a single call to simplify stream management. Bidirectional streams replace the
STREAM_FROM_STREAM
construct. - Limited mode semantics for older/limited hardware devices.
2.0
Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:
- Sufficient for implementing existing
android.hardware.Camera
API. - Allows for ZSL queue in camera service layer.
- Not tested for any new features such as manual capture control, Bayer RAW capture, reprocessing of RAW data, etc.
1.0
Initial Android camera HAL (Android 4.0) [camera.h]:
- Converted from C++ CameraHardwareInterface abstraction layer.
- Supports
android.hardware.Camera
API.
Camera module version history
This section contains module versioning information for the Camera hardware module, based on camera_module_t.common.module_api_version
. The two most significant hex digits represent the major version, and the two least significant represent the minor version.
2.4
This camera module version adds the following API changes:
- Torch mode support. The framework can turn on torch mode for any camera device that has a flash unit, without opening a camera device. The camera device has a higher priority accessing the flash unit than the camera module; opening a camera device turns off the torch if it had been enabled through the module interface. When there are any resource conflicts, such as
open()
is called to open a camera device, the camera HAL module must notify the framework through the torch mode status callback that the torch mode has been turned off. - External camera (for example, USB hot-plug camera) support. The API updates specify the camera static info is available only when camera is connected and ready to use for external hot-plug cameras. Calls to get static info are invalid calls when camera status isn't
CAMERA_DEVICE_STATUS_PRESENT
. The framework counts solely on device status change callbacks to manage the available external camera list. - Camera arbitration hints. Adds support for explicitly indicating the number of camera devices that can be simultaneously opened and used. To specify valid combinations of devices, the
resource_cost
andconflicting_devices
fields should always be set in thecamera_info
structure returned by theget_camera_info
call. - Module initialization method. Called by the camera service after the HAL module is loaded to allow for one-time initialization of the HAL. It is called before any other module methods are invoked.
2.3
This camera module version adds open legacy camera HAL device support. The framework can use it to open the camera device as lower device HAL version HAL device if the same device can support multiple device API versions. The standard hardware module open call ( common.methods->open
) continues to open the camera device with the latest supported version, which is also the version listed in camera_info_t.device_version
.
2.2
This camera module version adds vendor tag support from the module, and deprecates the old vendor_tag_query_ops
that were previously only accessible with a device open.
2.1
This camera module version adds support for asynchronous callbacks to the framework from the camera HAL module, which is used to notify the framework about changes to the camera module state. Modules that provide a valid set_callbacks()
method must report at least this version number.
2.0
Camera modules that report this version number implement the second version of the camera module HAL interface. Camera devices openable through this module may support either version 1.0 or version 2.0 of the camera device HAL interface. The device_version
field of camera_info is always valid; the static_camera_characteristics
field of camera_info
is valid if the device_version
field is 2.0 or higher.
1.0
Camera modules that report these version numbers implement the initial camera module HAL interface. All camera devices openable through this module support only version 1 of the camera device HAL. The device_version
and static_camera_characteristics
fields of camera_info
aren't valid. Only the android.hardware.Camera
API can be supported by this module and its devices.