שימוש בכמה שידורי מצלמה בו-זמנית

הערה: הדף הזה מתייחס לחבילה Camera2. אלא אם האפליקציה שלכם דורשת תכונות ספציפיות ברמה נמוכה מ-Camera2, מומלץ להשתמש ב-CameraX. ‫CameraX ו-Camera2 תומכות ב-Android 5.0 (רמת API‏ 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 מספקת כמה הבטחות לתמיכה בשילובים ספציפיים בהתאם לשלושה משתנים: סוג הפלט, גודל הפלט ורמת החומרה.

יכול להיות ששימוש בשילוב לא נתמך של משתנים יפעל בקצב פריימים נמוך. אם הוא לא יפעל, יופעל אחד מה-callbacks של הכשל. במסמכי העזרה של 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					תצוגה מקדימה פשוטה, עיבוד וידאו ב-GPU או הקלטת וידאו ללא תצוגה מקדימה.
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 (רמת API‏ 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.