ملاحظة: تشير هذه الصفحة إلى حزمة camera2. ننصحك باستخدام cameraX ما لم يكن تطبيقك يتطلب ميزات محدّدة ومنخفضة المستوى من Camera2. يتوافق كل من CameraX و Camera2 مع الإصدار Android 5.0 (المستوى 21 من واجهة برمجة التطبيقات) والإصدارات الأحدث.
يمكن لتطبيق الكاميرا استخدام أكثر من مجموعة من الإطارات في الوقت نفسه. وفي بعض الحالات، تتطلب عمليات البث المختلفة درجة دقة إطار أو تنسيق بكسل مختلف. وتشمل بعض حالات الاستخدام المعتادة ما يلي:
- تسجيل الفيديو: مجموعة بث للمعاينة وأخرى يتم ترميزها وحفظها في ملف
- المسح الضوئي للرمز الشريطي: مجموعة بث للمعاينة وأخرى لاكتشاف الرمز الشريطي.
- التصوير الحاسوبي: مجموعة بث للمعاينة وأخرى لاكتشاف الوجه/المشهد.
تُفرض تكلفة أداء غير بسيطة عند معالجة الإطارات، ويتم مضاعفة التكلفة عند إجراء عمليات معالجة تدفقات أو عمليات متوازية.
قد تتمكن موارد مثل وحدة المعالجة المركزية (CPU) ووحدة معالجة الرسومات وDSP من الاستفادة من إمكانات إعادة معالجة إطار العمل، لكن الموارد مثل الذاكرة ستنمو بشكل خطي.
عدة أهداف لكل طلب
يمكن دمج أحداث بث متعددة في كاميرات
CameraCaptureRequest
واحدة.
يوضّح مقتطف الرمز التالي كيفية إعداد جلسة كاميرا باستخدام بث واحد لمعاينة الكاميرا وآخر لمعالجة الصور:
Kotlin
val session: CameraCaptureSession = ... // from CameraCaptureSession.StateCallback // You will use the preview capture template for the combined streams // because it is optimized for low latency; for high-quality images, use // TEMPLATE_STILL_CAPTURE, and for a steady frame rate use TEMPLATE_RECORD val requestTemplate = CameraDevice.TEMPLATE_PREVIEW val combinedRequest = session.device.createCaptureRequest(requestTemplate) // Link the Surface targets with the combined request combinedRequest.addTarget(previewSurface) combinedRequest.addTarget(imReaderSurface) // In this simple case, the SurfaceView gets updated automatically. ImageReader // has its own callback that you have to listen to in order to retrieve the // frames so there is no need to set up a callback for the capture request session.setRepeatingRequest(combinedRequest.build(), null, null)
Java
CameraCaptureSession session = …; // from CameraCaptureSession.StateCallback // You will use the preview capture template for the combined streams // because it is optimized for low latency; for high-quality images, use // TEMPLATE_STILL_CAPTURE, and for a steady frame rate use TEMPLATE_RECORD CaptureRequest.Builder combinedRequest = session.getDevice().createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW); // Link the Surface targets with the combined request combinedRequest.addTarget(previewSurface); combinedRequest.addTarget(imReaderSurface); // In this simple case, the SurfaceView gets updated automatically. ImageReader // has its own callback that you have to listen to in order to retrieve the // frames so there is no need to set up a callback for the capture request session.setRepeatingRequest(combinedRequest.build(), null, null);
في حال إعداد مساحات العرض المستهدَفة بشكل صحيح، لن يُنتج هذا الرمز سوى
أحداث بث تستوفي الحدّ الأدنى لعدد اللقطات في الثانية الذي يحدّده رمزَي
StreamComfigurationMap.GetOutputMinFrameDuration(int, Size)
وStreamComfigurationMap.GetOutputStallDuration(int, Size)
.
يختلف الأداء الفعلي من جهاز لآخر، على الرغم من أن Android يقدم بعض
الضمانات لإتاحة مجموعات محددة وفقًا بثلاثة متغيّرات:
نوع إخراج، وحجم إخراج، ومستوى الجهاز.
وقد يعمل استخدام مجموعة غير متوافقة من المتغيّرات بمعدّل عرض إطارات منخفض، وفي حال عدم حدوث ذلك، سيؤدي ذلك إلى ظهور إحدى عمليات استدعاء الخطأ.
توضّح مستندات createCaptureSession
ما يمكن ضمان نجاحه.
نوع الإخراج
يشير نوع الإخراج إلى التنسيق الذي يتم ترميز الإطارات به. القيم المحتملة هي PRIV وYUV وJPEG وRAW. تشرح مستندات createCaptureSession
هذه القيم.
عند اختيار نوع مخرجات تطبيقك، إذا كان الهدف هو زيادة التوافق إلى أقصى حد، استخدِم ImageFormat.YUV_420_888
لتحليل الإطارات وImageFormat.JPEG
للصور الثابتة. بالنسبة إلى سيناريوهات المعاينة والتسجيل، من المحتمل أن تستخدم
SurfaceView
أو
TextureView
أو MediaRecorder
أو
MediaCodec
أو
RenderScript.Allocation
. في هذه الحالات، لا تحدّد تنسيقًا للصورة. بالنسبة إلى التوافق، سيتم احتسابه على أنّه
ImageFormat.PRIVATE
،
بغض النظر عن التنسيق الفعلي المستخدَم داخليًا. لطلب التنسيقات المتوافقة مع جهاز معيّن من خلال CameraCharacteristics
، استخدِم الرمز التالي:
Kotlin
val characteristics: CameraCharacteristics = ... val supportedFormats = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP).outputFormats
Java
CameraCharacteristics characteristics = …; int[] supportedFormats = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP).getOutputFormats();
حجم الإخراج
يتم إدراج جميع أحجام المخرجات المتاحة في
StreamConfigurationMap.getOutputSizes()
، ولكن هناك اثنان فقط مرتبطان بالتوافق: PREVIEW
وMAXIMUM
. تعمل الأحجام كحدود قصوى. وإذا كان مقاس PREVIEW
مناسبًا، يمكن أيضًا استخدام أي منتج بحجم أصغر من PREVIEW
. وينطبق الشيء نفسه على MAXIMUM
. تشرح مستندات CameraDevice
هذه الأحجام.
وتعتمد أحجام الإخراج المتاحة على اختيار التنسيق. استنادًا إلى تنسيق CameraCharacteristics
والتنسيق، يمكنك البحث عن أحجام المخرجات المتاحة، كما يلي:
Kotlin
val characteristics: CameraCharacteristics = ... val outputFormat: Int = ... // such as ImageFormat.JPEG val sizes = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) .getOutputSizes(outputFormat)
Java
CameraCharacteristics characteristics = …; int outputFormat = …; // such as ImageFormat.JPEG Size[] sizes = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) .getOutputSizes(outputFormat);
في حالات الاستخدام الخاصة بمعاينة الكاميرا وتسجيلها، استخدِم الفئة المستهدفة لتحديد الأحجام المتوافقة. سيتم التعامل مع التنسيق من خلال إطار عمل الكاميرا نفسه:
Kotlin
val characteristics: CameraCharacteristics = ... val targetClass: Class <T> = ... // such as SurfaceView::class.java val sizes = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) .getOutputSizes(targetClass)
Java
CameraCharacteristics characteristics = …; int outputFormat = …; // such as ImageFormat.JPEG Size[] sizes = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) .getOutputSizes(outputFormat);
للحصول على الحجم MAXIMUM
، عليك ترتيب أحجام المخرجات حسب المنطقة وعرض أكبر حجم:
Kotlin
fun <T>getMaximumOutputSize( characteristics: CameraCharacteristics, targetClass: Class <T>, format: Int? = null): Size { val config = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) // If image format is provided, use it to determine supported sizes; or else use target class val allSizes = if (format == null) config.getOutputSizes(targetClass) else config.getOutputSizes(format) return allSizes.maxBy { it.height * it.width } }
Java
@RequiresApi(api = Build.VERSION_CODES.N) <T> Size getMaximumOutputSize(CameraCharacteristics characteristics, Class <T> targetClass, Integer format) { StreamConfigurationMap config = characteristics.get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP); // If image format is provided, use it to determine supported sizes; else use target class Size[] allSizes; if (format == null) { allSizes = config.getOutputSizes(targetClass); } else { allSizes = config.getOutputSizes(format); } return Arrays.stream(allSizes).max(Comparator.comparing(s -> s.getHeight() * s.getWidth())).get(); }
يشير PREVIEW
إلى أفضل حجم مطابق لدقة شاشة الجهاز أو إلى 1080p (1920x1080)، أيهما أصغر. قد لا تتطابق نسبة العرض إلى الارتفاع مع نسبة العرض إلى الارتفاع للشاشة تمامًا، لذا قد تحتاج إلى إضافة إطار محيط بالخط أو اقتصاصه إلى البث لعرضه في وضع ملء الشاشة. للحصول على الحجم المناسب للمعاينة، قارِن أحجام الإخراج المتاحة بحجم شاشة العرض مع الأخذ في الاعتبار إمكانية تدوير شاشة العرض.
يحدّد الرمز البرمجي التالي فئة مساعِدة، وهي SmartSize
، ما سيسهّل مقارنة المقاسات:
Kotlin
/** Helper class used to pre-compute shortest and longest sides of a [Size] */ class SmartSize(width: Int, height: Int) { var size = Size(width, height) var long = max(size.width, size.height) var short = min(size.width, size.height) override fun toString() = "SmartSize(${long}x${short})" } /** Standard High Definition size for pictures and video */ val SIZE_1080P: SmartSize = SmartSize(1920, 1080) /** Returns a [SmartSize] object for the given [Display] */ fun getDisplaySmartSize(display: Display): SmartSize { val outPoint = Point() display.getRealSize(outPoint) return SmartSize(outPoint.x, outPoint.y) } /** * Returns the largest available PREVIEW size. For more information, see: * https://d.android.com/reference/android/hardware/camera2/CameraDevice */ fun <T>getPreviewOutputSize( display: Display, characteristics: CameraCharacteristics, targetClass: Class <T>, format: Int? = null ): Size { // Find which is smaller: screen or 1080p val screenSize = getDisplaySmartSize(display) val hdScreen = screenSize.long >= SIZE_1080P.long || screenSize.short >= SIZE_1080P.short val maxSize = if (hdScreen) SIZE_1080P else screenSize // If image format is provided, use it to determine supported sizes; else use target class val config = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)!! if (format == null) assert(StreamConfigurationMap.isOutputSupportedFor(targetClass)) else assert(config.isOutputSupportedFor(format)) val allSizes = if (format == null) config.getOutputSizes(targetClass) else config.getOutputSizes(format) // Get available sizes and sort them by area from largest to smallest val validSizes = allSizes .sortedWith(compareBy { it.height * it.width }) .map { SmartSize(it.width, it.height) }.reversed() // Then, get the largest output size that is smaller or equal than our max size return validSizes.first { it.long <= maxSize.long && it.short <= maxSize.short }.size }
Java
/** Helper class used to pre-compute shortest and longest sides of a [Size] */ class SmartSize { Size size; double longSize; double shortSize; public SmartSize(Integer width, Integer height) { size = new Size(width, height); longSize = max(size.getWidth(), size.getHeight()); shortSize = min(size.getWidth(), size.getHeight()); } @Override public String toString() { return String.format("SmartSize(%sx%s)", longSize, shortSize); } } /** Standard High Definition size for pictures and video */ SmartSize SIZE_1080P = new SmartSize(1920, 1080); /** Returns a [SmartSize] object for the given [Display] */ SmartSize getDisplaySmartSize(Display display) { Point outPoint = new Point(); display.getRealSize(outPoint); return new SmartSize(outPoint.x, outPoint.y); } /** * Returns the largest available PREVIEW size. For more information, see: * https://d.android.com/reference/android/hardware/camera2/CameraDevice */ @RequiresApi(api = Build.VERSION_CODES.N) <T> Size getPreviewOutputSize( Display display, CameraCharacteristics characteristics, Class <T> targetClass, Integer format ){ // Find which is smaller: screen or 1080p SmartSize screenSize = getDisplaySmartSize(display); boolean hdScreen = screenSize.longSize >= SIZE_1080P.longSize || screenSize.shortSize >= SIZE_1080P.shortSize; SmartSize maxSize; if (hdScreen) { maxSize = SIZE_1080P; } else { maxSize = screenSize; } // If image format is provided, use it to determine supported sizes; else use target class StreamConfigurationMap config = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP); if (format == null) assert(StreamConfigurationMap.isOutputSupportedFor(targetClass)); else assert(config.isOutputSupportedFor(format)); Size[] allSizes; if (format == null) { allSizes = config.getOutputSizes(targetClass); } else { allSizes = config.getOutputSizes(format); } // Get available sizes and sort them by area from largest to smallest List <Size> sortedSizes = Arrays.asList(allSizes); List <SmartSize> validSizes = sortedSizes.stream() .sorted(Comparator.comparing(s -> s.getHeight() * s.getWidth())) .map(s -> new SmartSize(s.getWidth(), s.getHeight())) .sorted(Collections.reverseOrder()).collect(Collectors.toList()); // Then, get the largest output size that is smaller or equal than our max size return validSizes.stream() .filter(s -> s.longSize <= maxSize.longSize && s.shortSize <= maxSize.shortSize) .findFirst().get().size; }
التحقق من مستوى الأجهزة المتوافقة
لتحديد الإمكانات المتاحة في وقت التشغيل، يمكنك التحقّق من مستوى الأجهزة المتوافقة باستخدام
CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL
.
باستخدام كائن CameraCharacteristics
، يمكنك استرداد مستوى الأجهزة باستخدام عبارة واحدة:
Kotlin
val characteristics: CameraCharacteristics = ... // Hardware level will be one of: // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_FULL, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3 val hardwareLevel = characteristics.get( CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL)
Java
CameraCharacteristics characteristics = ...; // Hardware level will be one of: // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_FULL, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3 Integer hardwareLevel = characteristics.get( CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL);
إن وضع جميع القطع معًا
باستخدام نوع الإخراج وحجم الإخراج ومستوى الجهاز، يمكنك تحديد مجموعات مجموعات البث الصالحة. يمثّل الرسم البياني التالي نبذة عن عمليات الضبط المتوافقة مع CameraDevice
على مستوى جهاز LEGACY
.
الهدف 1 | الهدف 2 | الهدف 3 | أمثلة على حالات الاستخدام | |||
---|---|---|---|---|---|---|
Type | أقصى حجم | Type | أقصى حجم | Type | أقصى حجم | |
PRIV |
MAXIMUM |
معاينة بسيطة، أو معالجة فيديو وحدة معالجة الرسومات، أو تسجيل فيديو بدون معاينة. | ||||
JPEG |
MAXIMUM |
التقاط صورة ثابتة بدون استخدام عدسة الكاميرا | ||||
YUV |
MAXIMUM |
معالجة الفيديوهات/الصور داخل التطبيق. | ||||
PRIV |
PREVIEW |
JPEG |
MAXIMUM |
صورة ثابتة عادية. | ||
YUV |
PREVIEW |
JPEG |
MAXIMUM |
المعالجة داخل التطبيق بالإضافة إلى التقاط الصور الثابتة | ||
PRIV |
PREVIEW |
PRIV |
PREVIEW |
تسجيل عادي | ||
PRIV |
PREVIEW |
YUV |
PREVIEW |
المعاينة والمعالجة داخل التطبيق | ||
PRIV |
PREVIEW |
YUV |
PREVIEW |
المعاينة والمعالجة داخل التطبيق | ||
PRIV |
PREVIEW |
YUV |
PREVIEW |
JPEG |
MAXIMUM |
لا يزال التقاط الصورة جاريًا بالإضافة إلى المعالجة داخل التطبيق. |
LEGACY
هو أدنى مستوى ممكن للأجهزة. يوضّح هذا الجدول أنّ كل
جهاز متوافق مع Camera2 (المستوى 21 من واجهة برمجة التطبيقات والمستويات الأعلى) يمكنه بث ما يصل إلى ثلاثة
أحداث بث متزامنة باستخدام الإعداد الصحيح، وإذا لم يكن هناك الكثير من التكاليف التي تحدّ من الأداء، مثل قيود الذاكرة أو وحدة المعالجة المركزية (CPU) أو القيود الحرارية.
يحتاج تطبيقك أيضًا إلى إعداد استهداف الموارد الاحتياطية للمخرجات. على سبيل المثال، لاستهداف جهاز بمستوى جهاز LEGACY
، يمكنك إعداد سطحَين مستهدفَين، أحدهما باستخدام ImageFormat.PRIVATE
والآخر باستخدام ImageFormat.YUV_420_888
. هذه تركيبة متوافقة عند استخدام
المقاس PREVIEW
. باستخدام الوظيفة المحددة سابقًا في هذا الموضوع، يتطلب الحصول على
أحجام المعاينة المطلوبة لمعرّف الكاميرا الرمز التالي:
Kotlin
val characteristics: CameraCharacteristics = ... val context = this as Context // assuming you are inside of an activity val surfaceViewSize = getPreviewOutputSize( context, characteristics, SurfaceView::class.java) val imageReaderSize = getPreviewOutputSize( context, characteristics, ImageReader::class.java, format = ImageFormat.YUV_420_888)
Java
CameraCharacteristics characteristics = ...; Context context = this; // assuming you are inside of an activity Size surfaceViewSize = getPreviewOutputSize( context, characteristics, SurfaceView.class); Size imageReaderSize = getPreviewOutputSize( context, characteristics, ImageReader.class, format = ImageFormat.YUV_420_888);
يتطلّب ذلك الانتظار حتى يصبح "SurfaceView
" جاهزًا باستخدام عمليات معاودة الاتصال المقدَّمة:
Kotlin
val surfaceView = findViewById <SurfaceView>(...) surfaceView.holder.addCallback(object : SurfaceHolder.Callback { override fun surfaceCreated(holder: SurfaceHolder) { // You do not need to specify image format, and it will be considered of type PRIV // Surface is now ready and you could use it as an output target for CameraSession } ... })
Java
SurfaceView surfaceView = findViewById <SurfaceView>(...); surfaceView.getHolder().addCallback(new SurfaceHolder.Callback() { @Override public void surfaceCreated(@NonNull SurfaceHolder surfaceHolder) { // You do not need to specify image format, and it will be considered of type PRIV // Surface is now ready and you could use it as an output target for CameraSession } ... });
يمكنك أن تفرض على SurfaceView
مطابقة حجم إخراج الكاميرا من خلال استدعاء
SurfaceHolder.setFixedSize()
أو يمكنك اتّباع نهج مشابه لـ
AutoFitSurfaceView
من الوحدة
الشائعة
لعيّنات الكاميرا على GitHub، التي تحدد حجمًا كاملاً مع مراعاة
نسبة العرض إلى الارتفاع والمساحة المتوفرة، مع ضبطها تلقائيًا عند تفعيل تغييرات النشاط.
ويمكن بسهولة أكبر ضبط المساحة الأخرى من
ImageReader
بالتنسيق المطلوب،
لأنه لا تتوفّر طلبات استدعاء يمكن انتظارها:
Kotlin
val frameBufferCount = 3 // just an example, depends on your usage of ImageReader val imageReader = ImageReader.newInstance( imageReaderSize.width, imageReaderSize.height, ImageFormat.YUV_420_888, frameBufferCount)
Java
int frameBufferCount = 3; // just an example, depends on your usage of ImageReader ImageReader imageReader = ImageReader.newInstance( imageReaderSize.width, imageReaderSize.height, ImageFormat.YUV_420_888, frameBufferCount);
عند استخدام مخزن مؤقت مستهدف للحظر مثل ImageReader
، تجاهل الإطارات بعد استخدامها:
Kotlin
imageReader.setOnImageAvailableListener({ val frame = it.acquireNextImage() // Do something with "frame" here it.close() }, null)
Java
imageReader.setOnImageAvailableListener(listener -> { Image frame = listener.acquireNextImage(); // Do something with "frame" here listener.close(); }, null);
يستهدف مستوى الأجهزة LEGACY
الأجهزة ذات المقام المشترك الأدنى. يمكنك
إضافة تفريع مشروط واستخدام حجم RECORD
لأحد مساحات العرض المستهدفة
في الأجهزة التي تتضمن مستوى جهاز LIMITED
، أو زيادته إلى
حجمه إلى
MAXIMUM
للأجهزة التي تتضمن مستوى جهاز واحد (FULL
).