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