הערה: הדף הזה מתייחס לחבילה camera2. מומלץ להשתמש ב-CameraX, אלא אם לאפליקציה שלך נדרשים תכונות ספציפיות ברמה נמוכה. גם CameraX וגם Camera2 תומכים ב-Android 5.0 (רמת API 21) ואילך.
אפליקציית מצלמה יכולה להשתמש ביותר מסטרימינג אחד של פריימים בו-זמנית. לחשבון במקרים מסוימים, סטרימינג שונה אפילו דורש רזולוציית פריים שונה או פיקסל שונה הפורמט. דוגמאות לתרחישים נפוצים:
- הקלטת וידאו: שידור אחד לתצוגה מקדימה, שידור אחר לקידוד ולשמירה לקובץ.
- סריקת ברקוד: שידור אחד לתצוגה מקדימה, שידור נוסף לזיהוי ברקוד.
- צילום חישובי: שידור אחד לתצוגה מקדימה, שידור אחר לפנים או לסצנה זיהוי וזיהוי אובייקטים.
יש עלות ביצועים לא שולית במהלך עיבוד פריימים, והעלות היא כפול כאשר מבצעים עיבוד מקביל של זרם נתונים או צינור עיבוד נתונים.
משאבים כמו מעבד (CPU), מעבד (GPU) ו-DSP יכולים לנצל בעיבוד מחדש של framework אבל משאבים כמו זיכרון יגדלו באופן לינארי.
מספר יעדים לכל בקשה
אפשר לשלב כמה שידורים חיים ממצלמה אחת
CameraCaptureRequest
קטע הקוד הבא מדגים איך אפשר להגדיר סשן של צילום באמצעות מצלמה
שידור לתצוגה מקדימה של המצלמה וסטרימינג נוסף לעיבוד תמונה:
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)
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
צריך להשתמש בקוד הבא:
val characteristics: CameraCharacteristics = ...
val supportedFormats = characteristics.get(
CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP).outputFormats
CameraCharacteristics characteristics = …;
int[] supportedFormats = characteristics.get(
CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP).getOutputFormats();
גודל פלט
כל גדלי הפלט הזמינים מפורטים לפי
StreamConfigurationMap.getOutputSizes()
,
אבל רק שתיים מהן קשורות לתאימות: PREVIEW
ו-MAXIMUM
. הגדלים
לשמש כגבולות העליונים. אם פריט בגודל PREVIEW
מתאים, כל דבר עם
גם גודל קטן מ-PREVIEW
יעבוד. אותו עיקרון נכון גם לגבי MAXIMUM
.
תיעוד עבור
CameraDevice
נסביר על הגדלים האלה.
גודלי הפלט הזמינים תלויים בפורמט שנבחר. בהינתן
CameraCharacteristics
ופורמט, אפשר לשלוח שאילתה לגבי גודלי פלט זמינים באופן הבא:
val characteristics: CameraCharacteristics = ...
val outputFormat: Int = ... // such as ImageFormat.JPEG
val sizes = characteristics.get(
CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
.getOutputSizes(outputFormat)
CameraCharacteristics characteristics = …;
int outputFormat = …; // such as ImageFormat.JPEG
Size[] sizes = characteristics.get(
CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
.getOutputSizes(outputFormat);
בתצוגה המקדימה ובהקלטה של המצלמה, משתמשים בסיווג היעד כדי לקבוע בגדלים הנתמכים. המצלמה עצמה תטפל בפורמט:
val characteristics: CameraCharacteristics = ...
val targetClass: Class <T> = ... // such as SurfaceView::class.java
val sizes = characteristics.get(
CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
.getOutputSizes(targetClass)
CameraCharacteristics characteristics = …;
int outputFormat = …; // such as ImageFormat.JPEG
Size[] sizes = characteristics.get(
CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
.getOutputSizes(outputFormat);
כדי לקבל את הגודל MAXIMUM
, צריך למיין את גודלי הפלט לפי שטח ולהחזיר את הגודל הגדול ביותר
one:
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 }
}
@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
, שקובעת את הגודל
לבצע השוואות בצורה קלה יותר:
/** 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
}
/** 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
אפשר לאחזר את רמת החומרה באמצעות הצהרה אחת:
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)
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
. באמצעות הפונקציה שהוגדרה קודם לכן בנושא, מקבלים
כדי להגדיר את הגודל של התצוגה המקדימה למזהה המצלמה, צריך להזין את הקוד הבא:
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)
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
יהיה מוכן באמצעות הקריאות החוזרות שסופקו:
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
}
...
})
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) שצריך להמתין ל:
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)
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
, צריך למחוק את הפריימים אחרי
באמצעותם:
imageReader.setOnImageAvailableListener({
val frame = it.acquireNextImage()
// Do something with "frame" here
it.close()
}, null)
imageReader.setOnImageAvailableListener(listener -> {
Image frame = listener.acquireNextImage();
// Do something with "frame" here
listener.close();
}, null);
רמת החומרה של LEGACY
מטרגטת מכשירים עם המכנה המשותף הנמוך ביותר. אפשר
הוספת הסתעפות מותנה ושימוש בגודל RECORD
לאחד מיעדי הפלט
במכשירים עם רמת חומרה של LIMITED
, או אפילו להגדיל אותה
גודל של MAXIMUM
למכשירים עם רמת חומרה של FULL
.