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