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

ملاحظة: تشير هذه الصفحة إلى حزمة Camera2. ننصحك باستخدام CameraX ما لم يكن تطبيقك يتطلّب ميزات محدّدة منخفضة المستوى من Camera2. تتوافق كل من CameraX وCamera2 مع الإصدار 5.0 من نظام التشغيل Android (المستوى 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 basic 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 basic 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‏ (1920×1080)، أيهما أصغر. قد لا تتطابق نسبة العرض إلى الارتفاع مع نسبة العرض إلى الارتفاع للشاشة تمامًا، لذا قد تحتاج إلى تطبيق تأثيرات الشاشة العريضة أو اقتصاص البث لعرضه في وضع ملء الشاشة. للحصول على حجم المعاينة المناسب، قارِن بين أحجام الإخراج المتاحة وحجم العرض مع مراعاة أنّ العرض قد يكون تم تدويره.

يحدّد الرمز التالي فئة مساعدة، 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 من الوحدة المشتركة لعينات الكاميرا على 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);

When using a blocking target buffer such as ImageReader, discard the frames after using them:

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 hardware level targets the lowest common denominator  devices. يمكنك إضافة تفرّع شرطي واستخدام حجم RECORD لإحدى مساحات العرض المستهدَفة في الأجهزة التي تتضمّن مستوى الأجهزة LIMITED، أو حتى زيادته إلى حجم MAXIMUM للأجهزة التي تتضمّن مستوى الأجهزة FULL.