Sitzungen und Anfragen für Kameraaufnahmen

Hinweis: Diese Seite bezieht sich auf das Camera2-Paket. Sofern Ihre App keine speziellen, Low-Level-Funktionen von Camera2 benötigt, empfehlen wir die Verwendung von CameraX. Sowohl CameraX als auch Camera2 unterstützen Android 5.0 (API-Level 21) und höher.

Ein einzelnes Android-Gerät kann mehrere Kameras haben. Jede Kamera ist ein CameraDevice und ein CameraDevice kann mehrere Streams gleichzeitig ausgeben.

Ein Grund dafür ist, dass ein Stream, also aufeinanderfolgende Kameraframes von einem CameraDevice, für eine bestimmte Aufgabe optimiert ist, z. B. für die Anzeige eines Suchers, während andere für die Aufnahme eines Fotos oder Videos verwendet werden können. Die Streams fungieren als parallele Pipelines, die Rohframes aus der Kamera nacheinander verarbeiten:

Parallele Streamverarbeitung von Rohframes von einem Kameragerät in verschiedene Ausgabeformate
Abbildung 1. Abbildung aus „Building a Universal Camera App“ (Google I/O '18)

Die parallele Verarbeitung deutet darauf hin, dass es je nach verfügbarer Verarbeitungsleistung der CPU, GPU oder eines anderen Prozessors Leistungslimits geben kann. Wenn eine Pipeline mit den eingehenden Frames nicht Schritt halten kann, werden sie verworfen.

Jede Pipeline hat ihr eigenes Ausgabeformat. Die eingehenden Rohdaten werden automatisch in das entsprechende Ausgabeformat umgewandelt, und zwar durch die implizite Logik, die mit jeder Pipeline verknüpft ist. Die in den Codebeispielen auf dieser Seite verwendete CameraDevice ist nicht spezifisch. Daher müssen Sie zuerst alle verfügbaren Kameras aufzählen, bevor Sie fortfahren.

Sie können mit dem CameraDevice ein CameraCaptureSession erstellen, das für diesen CameraDevice spezifisch ist. Ein CameraDevice muss für jeden Rohframe eine Frame-Konfiguration über die CameraCaptureSession erhalten. In der Konfiguration werden Kameraattribute wie Autofokus, Blende, Effekte und Belichtung angegeben. Aufgrund von Hardwareeinschränkungen ist im Kamerasensor jeweils nur eine einzige Konfiguration aktiv, die als aktive Konfiguration bezeichnet wird.

Mit Stream-Anwendungsfällen werden jedoch die bisherigen Möglichkeiten zur Verwendung von CameraDevice zum Streamen von Aufnahmesitzungen verbessert und erweitert. So können Sie den Kamerastream für Ihren speziellen Anwendungsfall optimieren. So kann beispielsweise die Akkulaufzeit bei der Optimierung von Videoanrufen verbessert werden.

Eine CameraCaptureSession beschreibt alle möglichen Pipelines, die an die CameraDevice gebunden sind. Nachdem eine Sitzung erstellt wurde, können Sie keine Pipelines mehr hinzufügen oder entfernen. Der CameraCaptureSession verwaltet eine Warteschlange von CaptureRequests, die zur aktiven Konfiguration werden.

Ein CaptureRequest fügt der Warteschlange eine Konfiguration hinzu und wählt eine, mehrere oder alle verfügbaren Pipelines aus, um einen Frame vom CameraDevice zu empfangen. Sie können während der Lebensdauer einer Erfassungssitzung viele Erfassungsanfragen senden. Mit jeder Anfrage können die aktive Konfiguration und die Gruppe von Ausgabepipelines, die das Rohbild empfangen, geändert werden.

Stream-Anwendungsfälle für bessere Leistung verwenden

Stream-Anwendungsfälle sind eine Möglichkeit, die Leistung von Camera2-Aufnahmesitzungen zu verbessern. Sie liefern dem Hardwaregerät mehr Informationen, um Parameter anzupassen, was für eine bessere Kameraleistung für Ihre spezifische Aufgabe sorgt.

Dadurch kann das Kameragerät die Hardware- und Softwarepipelines der Kamera basierend auf Nutzerszenarien für jeden Stream optimieren. Weitere Informationen zu Stream-Anwendungsfällen finden Sie unter setStreamUseCase.

Mit Stream-Anwendungsfällen können Sie genauer angeben, wie ein bestimmter Kamerastream verwendet wird. Außerdem können Sie eine Vorlage in CameraDevice.createCaptureRequest() festlegen. So kann die Kamerahardware Parameter wie Abstimmung, Sensormodus oder Kamerasensoreinstellungen basierend auf Qualitäts- oder Latenzkompromissen optimieren, die für bestimmte Anwendungsfälle geeignet sind.

Anwendungsfälle für Streams:

  • DEFAULT: Deckt das gesamte vorhandene Anwendungsverhalten ab. Dies entspricht dem Nichtfestlegen eines Stream-Anwendungsfalls.

  • PREVIEW: Empfohlen für die Bildanalyse im Sucher oder in der App.

  • STILL_CAPTURE: Optimiert für die Aufnahme in hoher Qualität und Auflösung. Es wird nicht erwartet, dass die Frameraten der Vorschau beibehalten werden.

  • VIDEO_RECORD: Optimiert für die Aufnahme von Videos in hoher Qualität, einschließlich hochwertiger Bildstabilisierung, sofern vom Gerät unterstützt und von der Anwendung aktiviert. Bei dieser Option können Ausgabeframes mit einer erheblichen Verzögerung gegenüber der Echtzeit erzeugt werden, um eine Stabilisierung oder andere Verarbeitung in höchster Qualität zu ermöglichen.

  • VIDEO_CALL: Empfohlen für die langfristige Nutzung der Kamera, wenn der Stromverbrauch ein Problem darstellt.

  • PREVIEW_VIDEO_STILL: Empfohlen für Social-Media-Apps oder Anwendungsfälle mit einem einzelnen Stream. Es ist ein Mehrzweck-Stream.

  • VENDOR_START: Wird für OEM-definierte Anwendungsfälle verwendet.

CameraCaptureSession erstellen

Wenn Sie eine Kamerasitzung erstellen möchten, müssen Sie einen oder mehrere Ausgabepuffer angeben, in die Ihre App Ausgabe-Frames schreiben kann. Jeder Puffer stellt eine Pipeline dar. Dies muss vor der Verwendung der Kamera erfolgen, damit das Framework die internen Pipelines des Geräts konfigurieren und Arbeitsspeicherpuffer für das Senden von Frames an die erforderlichen Ausgabeziele zuweisen kann.

Das folgende Code-Snippet zeigt, wie Sie eine Kamerasitzung mit zwei Ausgabepuffern vorbereiten können, von denen einer zu einem SurfaceView und der andere zu einem ImageReader gehört. Wenn du den Stream-Anwendungsfall PREVIEW zu previewSurface und den Stream-Anwendungsfall STILL_CAPTURE zu imReaderSurface hinzufügst, kann die Gerätehardware diese Streams noch weiter optimieren.

// Retrieve the target surfaces, which might be coming from a number of places:
// 1. SurfaceView, if you want to display the image directly to the user
// 2. ImageReader, if you want to read each frame or perform frame-by-frame
// analysis
// 3. OpenGL Texture or TextureView, although discouraged for maintainability
// reasons
// 4. RenderScript.Allocation, if you want to do parallel processing
val surfaceView = findViewById<SurfaceView>(
    // ...
)
val imageReader = ImageReader.newInstance(
    // ...
)

// Remember to call this only *after* SurfaceHolder.Callback.surfaceCreated().
val previewSurface = surfaceView.holder.surface
val imReaderSurface = imageReader.surface
val targets = listOf(previewSurface, imReaderSurface)

// Create a capture session using the predefined targets; this also involves
// defining the session state callback to be notified of when the session is
// ready.
// Setup Stream Use Case while setting up your Output Configuration.
@RequiresApi(Build.VERSION_CODES.TIRAMISU)
fun configureSession(device: CameraDevice, targets: List<Surface>) {
    val configs = mutableListOf<OutputConfiguration>()
    val streamUseCase = CameraMetadata
        .SCALER_AVAILABLE_STREAM_USE_CASES_PREVIEW_VIDEO_STILL

    targets.forEach {
        val config = OutputConfiguration(it)
        config.streamUseCase = streamUseCase.toLong()
        configs.add(config)
    }
    // ...
    device.createCaptureSession(session)
}

An dieser Stelle hast du die aktive Konfiguration der Kamera noch nicht definiert. Wenn die Sitzung konfiguriert ist, können Sie dazu Aufnahmeanfragen erstellen und senden.

Die Transformation, die auf Eingaben angewendet wird, wenn sie in ihren Zwischenspeicher geschrieben werden, wird durch den Typ jedes Ziels bestimmt, der ein Surface sein muss. Das Android-Framework kann ein Rohbild in der aktiven Konfiguration in ein für jedes Ziel geeignetes Format konvertieren. Die Konvertierung wird durch das Pixelformat und die Größe des jeweiligen Surface gesteuert.

Das Framework versucht, sein Bestes zu tun, aber einige Surface-Konfigurationskombinationen funktionieren möglicherweise nicht. Dies kann zu Problemen führen, z. B. dass die Sitzung nicht erstellt wird, ein Laufzeitfehler beim Senden einer Anfrage auftritt oder die Leistung beeinträchtigt wird. Das Framework bietet Garantien für bestimmte Kombinationen aus Gerät, Oberfläche und Anfrageparametern. Weitere Informationen finden Sie in der Dokumentation zu createCaptureSession().

Einzelne CaptureRequests

Die für jeden Frame verwendete Konfiguration wird in einem CaptureRequest codiert, das an die Kamera gesendet wird. Zum Erstellen einer Erfassungsanfrage können Sie eine der vordefinierten Vorlagen oder TEMPLATE_MANUAL für die vollständige Kontrolle verwenden. Wenn Sie eine Vorlage auswählen, müssen Sie einen oder mehrere Ausgabepuffer angeben, die mit der Anfrage verwendet werden sollen. Sie können nur Puffer verwenden, die bereits in der Erfassungssitzung definiert wurden, die Sie verwenden möchten.

Aufnahmeanfragen verwenden ein Builder-Muster und bieten Entwicklern die Möglichkeit, viele verschiedene Optionen festzulegen, darunter automatische Belichtung, Autofokus und Objektivblende. Bevor du ein Feld festlegst, solltest du prüfen, ob die jeweilige Option für das Gerät verfügbar ist. Rufe dazu CameraCharacteristics.getAvailableCaptureRequestKeys() auf und prüfe, ob der ausgewählte Wert unterstützt wird. Sieh dir dazu die entsprechende Kameraeigenschaft an, z. B. die verfügbaren Modi für die automatische Belichtung.

Wenn Sie eine Erfassungsanfrage für eine SurfaceView mit der Vorlage für die Vorabversion ohne Änderungen erstellen möchten, verwenden Sie CameraDevice.TEMPLATE_PREVIEW:

val session: CameraCaptureSession = /* ... */ // from CameraCaptureSession.StateCallback
val captureRequest = session.device.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW)
captureRequest.addTarget(previewSurface)

Nachdem Sie eine Aufnahmeanfrage definiert haben, können Sie sie an die Kamerasitzung senden:

val session: CameraCaptureSession = ...  // from CameraCaptureSession.StateCallback
val captureRequest: CaptureRequest.Builder = ...  // from CameraDevice.createCaptureRequest()

// The first null argument corresponds to the capture callback, which you
// provide if you want to retrieve frame metadata or keep track of failed capture
// requests that can indicate dropped frames; the second null argument
// corresponds to the Handler used by the asynchronous callback, which falls
// back to the current thread's looper if null.
session.capture(captureRequest.build(), null, null)

Wenn ein Ausgabeframe in den spezifischen Zwischenspeicher gestellt wird, wird ein Aufnahme-Callback ausgelöst. In vielen Fällen werden zusätzliche Callbacks wie ImageReader.OnImageAvailableListener ausgelöst, wenn der darin enthaltene Frame verarbeitet wird. An diesem Punkt können Sie Bilddaten aus dem angegebenen Zwischenspeicher abrufen.

CaptureRequests wiederholen

Anfragen für eine einzelne Kamera sind einfach zu erstellen, aber für die Anzeige einer Live-Vorschau oder eines Videos sind sie nicht sehr nützlich. In diesem Fall müssen Sie einen kontinuierlichen Stream von Frames empfangen, nicht nur einen einzelnen. Das folgende Code-Snippet zeigt, wie Sie der Sitzung eine wiederholte Anfrage hinzufügen:

val session: CameraCaptureSession = ... // from CameraCaptureSession.StateCallback
val captureRequest: CaptureRequest.Builder = ... // from CameraDevice.createCaptureRequest()

// This keeps sending the capture request as frequently as possible until
// the session is torn down or session.stopRepeating() is called.
session.setRepeatingRequest(captureRequest.build(), null, null)

Bei einer wiederholten Aufnahmeaufforderung nimmt die Kamera kontinuierlich Bilder mit den Einstellungen im angegebenen CaptureRequest auf. Mit der Camera2 API können Nutzer auch Videos von der Kamera aufnehmen, indem sie wiederholte CaptureRequests senden, wie in diesem Camera2-Beispiel-Repository auf GitHub zu sehen ist. Sie kann auch Zeitlupenvideos rendern, indem sie ein Hochgeschwindigkeitsvideo (Zeitlupe) mit wiederholten Burst-CaptureRequests aufnimmt, wie in der Camera2-Beispiel-App für Zeitlupenvideos auf GitHub gezeigt.

CaptureRequests verschachteln

Wenn du eine zweite Aufnahme-Anfrage senden möchtest, während die wiederholte Aufnahme-Anfrage aktiv ist, z. B. um einen Sucher anzuzeigen und Nutzern die Möglichkeit zu geben, ein Foto aufzunehmen, musst du die laufende wiederholte Anfrage nicht beenden. Stattdessen stellen Sie eine nicht wiederholte Aufnahme-Anfrage, während die wiederholte Anfrage weiter ausgeführt wird.

Alle verwendeten Ausgabepuffer müssen bei der ersten Erstellung der Kamerasitzung als Teil der Sitzung konfiguriert werden. Wiederholte Anfragen haben eine niedrigere Priorität als Einzelbild- oder Burst-Anfragen, sodass das folgende Beispiel funktioniert:

val session: CameraCaptureSession = /* ... */ // from CameraCaptureSession.StateCallback

// Create the repeating request and dispatch it.
val repeatingRequest = session.device.createCaptureRequest(
    CameraDevice.TEMPLATE_PREVIEW
)
repeatingRequest.addTarget(previewSurface)
session.setRepeatingRequest(repeatingRequest.build(), null, null)

// Some time later...

// Create the single request and dispatch it.
// NOTE: This can disrupt the ongoing repeating request momentarily.
val singleRequest = session.device.createCaptureRequest(
    CameraDevice.TEMPLATE_STILL_CAPTURE
)
singleRequest.addTarget(imReaderSurface)
session.capture(singleRequest.build(), null, null)

Dieser Ansatz hat jedoch einen Nachteil: Sie wissen nicht genau, wann die einzelne Anfrage erfolgt. In der folgenden Abbildung ist A die wiederholte Aufnahme-Anfrage und B die Einzelbild-Aufnahme-Anfrage. So verarbeitet die Sitzung die Anfrage-Warteschlange:

Aktive Warteschlange für wiederholte Aufnahmeanfragen durch eine einzelne Aufnahmeanfrage unterbrochen
Abbildung 2. Abbildung einer Anfrage-Warteschlange für die laufende Kamerasitzung

Es gibt keine Garantien für die Latenz zwischen der letzten wiederholten Anfrage von A vor der Aktivierung der Anfrage B und der nächsten Verwendung von A. Daher kann es zu übersprungenen Frames kommen. Es gibt einige Möglichkeiten, dieses Problem zu beheben:

  • Fügen Sie die Ausgabeziele aus Anfrage A zu Anfrage B hinzu. Wenn der Frame von B bereit ist, wird er in die Ausgabeziele von A kopiert. Dies ist beispielsweise bei Video-Snapshots wichtig, um eine konstante Framerate aufrechtzuerhalten. Im vorherigen Code fügen Sie singleRequest.addTarget(previewSurface) hinzu, bevor Sie die Anfrage erstellen.

  • Verwenden Sie eine Kombination aus Vorlagen, die für dieses spezielle Szenario entwickelt wurden, z. B. Zero-Shutter-Lag.