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

הערה: הדף הזה מתייחס לחבילה 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 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);

אם מגדירים את משטחי היעד בצורה נכונה, הקוד הזה ייצור רק סטרימינג שעומד במינימום ה-FPS שנקבע על ידי 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 יהיה מוכן באמצעות פונקציות הקריאה החוזרת (callback) שסופקו:

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 module של דוגמאות המצלמה ב-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.