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

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

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

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

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

قد تتمكن موارد مثل وحدة المعالجة المركزية (CPU) ووحدة معالجة الرسومات وDSP من الاستفادة من إمكانات إعادة معالجة إطار العمل، لكن الموارد مثل الذاكرة ستنمو بشكل خطي.

عدة أهداف لكل طلب

يمكن دمج أحداث بث متعددة في كاميرات CameraCaptureRequest واحدة. يوضّح مقتطف الرمز التالي كيفية إعداد جلسة كاميرا باستخدام بث واحد لمعاينة الكاميرا وآخر لمعالجة الصور:

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)

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، استخدِم الرمز التالي:

val characteristics: CameraCharacteristics = ...
val supportedFormats = characteristics.get(
    CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP).outputFormats

CameraCharacteristics characteristics = …;
        int[] supportedFormats = characteristics.get(
CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP).getOutputFormats();

حجم الإخراج

يتم إدراج جميع أحجام المخرجات المتاحة في StreamConfigurationMap.getOutputSizes()، ولكن هناك اثنان فقط مرتبطان بالتوافق: PREVIEW وMAXIMUM. تعمل الأحجام كحدود قصوى. وإذا كان مقاس PREVIEW مناسبًا، يمكن أيضًا استخدام أي منتج بحجم أصغر من PREVIEW. وينطبق الشيء نفسه على MAXIMUM. تشرح مستندات CameraDevice هذه الأحجام.

وتعتمد أحجام الإخراج المتاحة على اختيار التنسيق. استنادًا إلى تنسيق CameraCharacteristics والتنسيق، يمكنك البحث عن أحجام المخرجات المتاحة، كما يلي:

val characteristics: CameraCharacteristics = ...
val outputFormat: Int = ...  // such as ImageFormat.JPEG
val sizes = characteristics.get(
    CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
    .getOutputSizes(outputFormat)

CameraCharacteristics characteristics = …;
        int outputFormat = …;  // such as ImageFormat.JPEG
Size[] sizes = characteristics.get(
                CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
                .getOutputSizes(outputFormat);

في حالات الاستخدام الخاصة بمعاينة الكاميرا وتسجيلها، استخدِم الفئة المستهدفة لتحديد الأحجام المتوافقة. سيتم التعامل مع التنسيق من خلال إطار عمل الكاميرا نفسه:

val characteristics: CameraCharacteristics = ...
val targetClass: Class <T> = ...  // such as SurfaceView::class.java
val sizes = characteristics.get(
    CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
    .getOutputSizes(targetClass)

CameraCharacteristics characteristics = …;
   int outputFormat = …;  // such as ImageFormat.JPEG
   Size[] sizes = characteristics.get(
                CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
                .getOutputSizes(outputFormat);

للحصول على الحجم MAXIMUM، عليك ترتيب أحجام المخرجات حسب المنطقة وعرض أكبر حجم:

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

 @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، ما سيسهّل مقارنة المقاسات:

/** 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
}

/** 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، يمكنك استرداد مستوى الأجهزة باستخدام عبارة واحدة:

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)

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.

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

يحتاج تطبيقك أيضًا إلى إعداد استهداف الموارد الاحتياطية للمخرجات. على سبيل المثال، لاستهداف جهاز بمستوى جهاز LEGACY، يمكنك إعداد سطحَين مستهدفَين، أحدهما باستخدام ImageFormat.PRIVATE والآخر باستخدام ImageFormat.YUV_420_888. هذه تركيبة متوافقة عند استخدام المقاس PREVIEW. باستخدام الوظيفة المحددة سابقًا في هذا الموضوع، يتطلب الحصول على أحجام المعاينة المطلوبة لمعرّف الكاميرا الرمز التالي:

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)

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" جاهزًا باستخدام عمليات معاودة الاتصال المقدَّمة:

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
  }
  ...
})

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 بالتنسيق المطلوب، لأنه لا تتوفّر طلبات استدعاء يمكن انتظارها:

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)

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، تجاهل الإطارات بعد استخدامها:

imageReader.setOnImageAvailableListener({
  val frame =  it.acquireNextImage()
  // Do something with "frame" here
  it.close()
}, null)

imageReader.setOnImageAvailableListener(listener -> {
            Image frame = listener.acquireNextImage();
            // Do something with "frame" here
            listener.close();
        }, null);

يستهدف مستوى الأجهزة LEGACY الأجهزة ذات المقام المشترك الأدنى. يمكنك إضافة تفريع مشروط واستخدام حجم RECORD لأحد مساحات العرض المستهدفة في الأجهزة التي تتضمن مستوى جهاز LIMITED، أو زيادته إلى حجمه إلى MAXIMUM للأجهزة التي تتضمن مستوى جهاز واحد (FULL).