استخدام عدّة بث كاميرا في الوقت نفسه

ملاحظة: تشير هذه الصفحة إلى حزمة Camera2. ننصحك باستخدام CameraX ما لم يكن تطبيقك يتطلّب ميزات معيّنة منخفضة المستوى من Camera2. تتوافق كلّ من CameraX وCamera2 مع نظام التشغيل Android 5.0 (المستوى 21 من واجهة برمجة التطبيقات) والإصدارات الأحدث.

يمكن لتطبيق الكاميرا استخدام أكثر من سلسلة واحدة من اللقطات في الوقت نفسه. في بعض الحالات، تتطلّب مجموعات البث المختلفة درجة دقة إطار أو تنسيق بكسل مختلفَين. تشمل بعض حالات الاستخدام النموذجية ما يلي:

  • تسجيل الفيديو: بث واحد للمعاينة، وبث آخر يتم ترميزه وحفظه في ملف
  • مسح الرموز الشريطية ضوئيًا: بث واحد للمعاينة، وآخر لرصد الرموز الشريطية
  • التصوير الحسابي: بث واحد للمعاينة، وآخر لرصد الوجوه/المشاهد

تتضمّن معالجة اللقطات تكلفة أداء غير بسيطة، وتتضاعف هذه التكلفة عند إجراء معالجة متوازية للتدفق أو خط أنابيب.

قد تتمكّن موارد مثل وحدة المعالجة المركزية (CPU) ووحدة معالجة الرسومات (GPU) ومعالج الإشارات الرقمية (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 أمثلة على حالات الاستخدام
النوع الحد الأقصى للحجم النوع الحد الأقصى للحجم النوع الحد الأقصى للحجم
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 JPEG MAXIMUM التقاط الصور الثابتة بالإضافة إلى المعالجة داخل التطبيق

LEGACY هو أدنى مستوى ممكن للأجهزة. يوضّح هذا الجدول أنّ كل جهاز متوافق مع Camera2 (المستوى 21 لواجهة برمجة التطبيقات والإصدارات الأحدث) يمكنه عرض ما يصل إلى ثلاثة مصادر بث متزامنة باستخدام الإعداد الصحيح، وفي حال عدم وجود الكثير من النفقات العامة التي تحدّ من الأداء، مثل قيود الذاكرة أو وحدة المعالجة المركزية أو الحرارة.

يجب أن يضبط تطبيقك أيضًا مخازن مؤقتة لنتائج الاستهداف. على سبيل المثال، لاستهداف جهاز بمستوى أمان 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 من وحدة Common في نماذج الكاميرا على 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.