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

הערה: הדף הזה מתייחס לחבילה camera2. מומלץ להשתמש ב-CameraX, אלא אם לאפליקציה שלך נדרשים תכונות ספציפיות ברמה נמוכה. גם CameraX וגם Camera2 תומכים ב-Android 5.0 (רמת API 21) ואילך.

אפליקציית מצלמה יכולה להשתמש ביותר מסטרימינג אחד של פריימים בו-זמנית. לחשבון במקרים מסוימים, סטרימינג שונה אפילו דורש רזולוציית פריים שונה או פיקסל שונה הפורמט. דוגמאות לתרחישים נפוצים:

  • הקלטת וידאו: שידור אחד לתצוגה מקדימה, שידור אחר לקידוד ולשמירה לקובץ.
  • סריקת ברקוד: שידור אחד לתצוגה מקדימה, שידור נוסף לזיהוי ברקוד.
  • צילום חישובי: שידור אחד לתצוגה מקדימה, שידור אחר לפנים או לסצנה זיהוי וזיהוי אובייקטים.

יש עלות ביצועים לא שולית במהלך עיבוד פריימים, והעלות היא כפול כאשר מבצעים עיבוד מקביל של זרם נתונים או צינור עיבוד נתונים.

משאבים כמו מעבד (CPU), מעבד (GPU) ו-DSP יכולים לנצל בעיבוד מחדש של framework אבל משאבים כמו זיכרון יגדלו באופן לינארי.

מספר יעדים לכל בקשה

אפשר לשלב כמה שידורים חיים ממצלמה אחת 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);

אם תגדירו את פלטפורמות היעד בצורה נכונה, הקוד הזה יפיק רק שידורים שעומדים ב-FPS המינימלי שנקבע לפי StreamComfigurationMap.GetOutputMinFrameDuration(int, Size) וגם StreamComfigurationMap.GetOutputStallDuration(int, Size) הביצועים בפועל משתנים ממכשיר למכשיר, אבל מערכת Android מספקת מבטיחה תמיכה בשילובים ספציפיים, בהתאם לשלושה משתנים: סוג פלט, גודל פלט ורמת חומרה.

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

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

הקוד הבא מגדיר מחלקה מסייעת, 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 תצוגה מקדימה ועיבוד בתוך האפליקציה.
PRIV PREVIEW YUV PREVIEW JPEG MAXIMUM צילום עדיין מתבצע ועיבוד בתוך האפליקציה.

LEGACY היא רמת החומרה הנמוכה ביותר שאפשר לקבל. בטבלה הזו אפשר לראות שבכל פעם מכשיר שתומך ב- Camera2 (רמת API 21 ומעלה) יכול להפיק עד שלושה פלט משדרים בו-זמנית באמצעות ההגדרות הנכונות, ואם אין יותר מדי תכנים הגבלות תקורה על ביצועים, כמו מגבלות זיכרון, מעבד (CPU) או מגבלות תרמיות.

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

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.