Kameraerweiterungen

Gerätehersteller können Erweiterungen wie Bokeh, Nachtmodus und HDR über die von der OEM-Anbieterbibliothek bereitgestellte Kameraerweiterungsschnittstelle Drittentwicklern zur Verfügung stellen. Entwickler können die Camera2 Extensions API und die CameraX Extensions API verwenden, um auf die in der OEM-Anbieterbibliothek implementierten Erweiterungen zuzugreifen.

Eine Liste der unterstützten Erweiterungen, die für Camera2 und CameraX gleich ist, finden Sie unter CameraX Extensions API . Wenn Sie eine Erweiterung hinzufügen möchten, melden Sie einen Fehler beim Issue Tracker .

Auf dieser Seite wird beschrieben, wie Sie die OEM-Anbieterbibliothek auf Geräten implementieren und aktivieren.

Die Architektur

Das folgende Diagramm beschreibt die Architektur der Camera Extensions-Schnittstelle oder extensions-interface : Die Architektur

Abbildung 1. Architekturdiagramm der Kameraerweiterungen

Wie im Diagramm gezeigt, müssen Sie zur Unterstützung von Kameraerweiterungen die von der OEM-Anbieterbibliothek bereitgestellte extensions-interface implementieren. Ihre OEM-Anbieterbibliothek ermöglicht zwei APIs: CameraX Extensions API und Camera2 Extensions API , die von CameraX- bzw. Camera2-Apps verwendet werden, um auf Anbietererweiterungen zuzugreifen.

Implementieren Sie die OEM-Anbieterbibliothek

Um die OEM-Anbieterbibliothek zu implementieren, kopieren Sie die camera-extensions-stub Dateien in ein Systembibliotheksprojekt. Diese Dateien definieren die Kameraerweiterungsschnittstelle.

Die camera-extensions-stub Dateien sind in die folgenden Kategorien unterteilt:

Wesentliche Schnittstellendateien (nicht ändern)

  • PreviewExtenderImpl.java
  • ImageCaptureExtenderImpl.java
  • ExtenderStateListener.java
  • ProcessorImpl.java
  • PreviewImageProcessorImpl.java
  • CaptureProcessorImpl.java
  • CaptureStageImpl.java
  • RequestUpdateProcessorImpl.java
  • ProcessResultImpl.java
  • advanced/AdvancedExtenderImpl.java
  • advanced/Camera2OutputConfigImpl.java
  • advanced/Camera2SessionConfigImpl.java
  • advanced/ImageProcessorImpl.java
  • advanced/ImageReaderOutputConfigImpl.java
  • advanced/ImageReferenceImpl.java
  • advanced/MultiResolutionImageReaderOutputConfigImpl.java
  • advanced/OutputSurfaceImpl.java
  • advanced/RequestProcessorImpl.java
  • advanced/SessionProcessorImpl.java
  • advanced/SurfaceOutputConfigImpl.java

Obligatorische Implementierungen (fügen Sie Ihre Implementierung hinzu)

  • ExtensionVersionImpl.java
  • InitializerImpl.java

Bokeh-Extender-Klassen (implementieren, wenn die Bokeh-Erweiterung unterstützt wird)

  • BokehImageCaptureExtenderImpl.java
  • BokehPreviewExtenderImpl.java
  • advanced/BokehAdvancedExtenderImpl.java

Nachtverlängerungsklassen (implementieren Sie diese, wenn die Nachtverlängerung unterstützt wird)

  • NightImageCaptureExtenderImpl.java
  • NightPreviewExtenderImpl.java
  • advanced/NightAdvancedExtenderImpl.java

Auto-Extender-Klassen (implementieren Sie sie, wenn die automatische Erweiterung unterstützt wird)

  • AutoImageCaptureExtenderImpl.java
  • AutoPreviewExtenderImpl.java
  • advanced/AutoAdvancedExtenderImpl.java

HDR-Extender-Klassen (implementieren, wenn die HDR-Erweiterung unterstützt wird)

  • HdrImageCaptureExtenderImpl.java
  • HdrPreviewExtenderImpl.java
  • advanced/HdrAdvancedExtenderImpl.java

Face Retouch-Extender-Klassen (implementieren Sie sie, wenn die Face Retouch-Erweiterung unterstützt wird)

  • BeautyImageCaptureExtenderImpl.java
  • BeautyPreviewExtenderImpl.java
  • advanced/BeautyAdvancedExtenderImpl.java

Dienstprogramme (optional, kann gelöscht werden)

  • advanced/Camera2OutputConfigImplBuilder.java
  • advanced/Camera2SessionConfigImplBuilder.java

Sie müssen nicht für jede Erweiterung eine Implementierung bereitstellen. Wenn Sie keine Erweiterung implementieren, legen Sie isExtensionAvailable() so fest, dass false zurückgegeben wird, oder entfernen Sie die entsprechenden Extender-Klassen. Die Camera2- und CameraX-Erweiterungs-APIs melden der App, dass die Erweiterung nicht verfügbar ist.

Sehen wir uns an, wie die Camera2- und CameraX-Erweiterungs-APIs mit der Anbieterbibliothek interagieren, um eine Erweiterung zu ermöglichen. Das folgende Diagramm veranschaulicht den End-to-End-Ablauf am Beispiel der Nachterweiterung:

Hauptstrom

Abbildung 2. Implementierung der Nachtverlängerung

  1. Versionsüberprüfung:

    Camera2/X ruft ExtensionVersionImpl.checkApiVersion() auf, um sicherzustellen, dass die OEM-implementierte extensions-interface mit den von Camera2/X unterstützten Versionen kompatibel ist.

  2. Initialisierung der Anbieterbibliothek:

    InitializerImpl verfügt über eine Methode init() , die die Herstellerbibliothek initialisiert. Camera2/X schließt die Initialisierung ab, bevor auf die Extender-Klassen zugegriffen wird.

  3. Instanziieren Sie Extender-Klassen:

    Instanziiert die Extender-Klassen für die Erweiterung. Es gibt zwei Extender-Typen: Basic Extender und Advanced Extender. Sie müssen einen Extender-Typ für alle Erweiterungen implementieren. Weitere Informationen finden Sie unter Basic Extender im Vergleich zu Advanced Extender .

    Camera2/X instanziiert die Extender-Klassen und interagiert mit ihnen, um Informationen abzurufen und die Erweiterung zu aktivieren. Für eine bestimmte Erweiterung kann Camera2/X die Extender-Klassen mehrmals instanziieren. Führen Sie daher keine aufwändige Initialisierung im Konstruktor oder beim init() Aufruf durch. Führen Sie die schwere Arbeit nur aus, wenn die Kamerasitzung gerade beginnt, z. B. wenn onInit() in Basic Extender oder initSession() in Advanced Extender aufgerufen wird.

    Für die Night-Erweiterung werden die folgenden Extender-Klassen für den Basic Extender-Typ instanziiert:

    • NightImageCaptureExtenderImpl.java
    • NightPreviewExtenderImpl.java

    Und für den Advanced Extender-Typ:

    • NightAdvancedExtenderImpl.java
  4. Überprüfen Sie die Verfügbarkeit der Erweiterung:

    Bevor die Erweiterung aktiviert wird, prüft isExtensionAvailable() , ob die Erweiterung auf der angegebenen Kamera-ID über die Extender-Instanz verfügbar ist.

  5. Initialisieren Sie den Extender mit Kamerainformationen:

    Camera2/X ruft init() auf der Extender-Instanz auf und übergibt ihr die Kamera-ID und CameraCharacteristics .

  6. Abfrageinformationen:

    Ruft die Extender-Klasse auf, um Informationen wie unterstützte Auflösungen abzurufen, weiterhin die geschätzte Latenz zu erfassen und Anforderungsschlüssel vom Extender zu erfassen, um die Aktivierung der Erweiterung vorzubereiten.

  7. Erweiterung auf dem Extender aktivieren:

    Die Extender-Klasse stellt alle Schnittstellen bereit, die zum Aktivieren der Klasse erforderlich sind. Es bietet einen Mechanismus zum Einbinden der OEM-Implementierung in die Camera2-Pipeline, z. B. durch das Einfügen von Aufnahmeanforderungsparametern oder das Aktivieren eines Postprozessors.

    Beim Advanced Extender-Typ interagiert Camera2/X mit SessionProcessorImpl , um die Erweiterung zu aktivieren. Camera2/X ruft die SessionProcessorImpl Instanz ab, indem es createSessionProcessor() auf dem Extender aufruft.

In den folgenden Abschnitten wird der Erweiterungsablauf ausführlicher beschrieben.

Versionsüberprüfung

Beim Laden der OEM-Anbieterbibliothek vom Gerät zur Laufzeit überprüft Camera2/X, ob die Bibliothek mit der extensions-interface kompatibel ist. Die extensions-interface verwendet semantische Versionierung oder MAJOR.MINOR.PATCH, zum Beispiel 1.1.0 oder 1.2.0. Bei der Versionsüberprüfung werden jedoch nur die Haupt- und Nebenversionen verwendet.

Um die Version zu überprüfen, ruft Camera2/X ExtensionVersionImpl.checkApiVersion() mit der unterstützten extensions-interface auf. Camera2/X verwendet dann die von der OEM-Bibliothek gemeldete Version, um zu bestimmen, ob die Erweiterung aktiviert werden kann und welche Funktionen sie aufrufen soll.

Kompatibilität mit Hauptversionen

Wenn die Hauptversionen der Erweiterungsschnittstelle zwischen Camera2/X und der Herstellerbibliothek unterschiedlich sind, gilt sie als inkompatibel und die Erweiterung wird deaktiviert.

Rückwärtskompatibilität

Solange die Hauptversion identisch ist, gewährleistet Camera2/X die Abwärtskompatibilität mit OEM-Anbieterbibliotheken, die mit früheren extensions-interface erstellt wurden. Wenn Camera2/X beispielsweise extensions-interface 1.3.0 unterstützt, sind die OEM-Anbieterbibliotheken, die 1.0.0, 1.1.0 und 1.2.0 implementiert haben, weiterhin kompatibel. Das bedeutet auch, dass Camera2/X nach der Implementierung einer bestimmten Version der Herstellerbibliothek sicherstellt, dass die Bibliothek mit kommenden extension-interface abwärtskompatibel ist.

Vorwärtskompatibilität

Die Vorwärtskompatibilität mit Herstellerbibliotheken neuerer extensions-interface hängt von Ihnen als OEM ab. Wenn Sie einige Funktionen zum Implementieren der Erweiterungen benötigen, möchten Sie die Erweiterungen möglicherweise ab einer bestimmten Version aktivieren. In diesem Fall können Sie die unterstützte extensions-interface zurückgeben, wenn die Camera2/X-Bibliotheksversion die Anforderungen erfüllt. Wenn die Camera2/X-Versionen nicht unterstützt werden, können Sie eine inkompatible Version wie 99.0.0 zurückgeben, um die Erweiterungen zu deaktivieren.

Initialisierung der Anbieterbibliothek

Nach der Überprüfung der von der OEM-Bibliothek implementierten extensions-interface startet Camera2/X den Initialisierungsprozess. Die Methode InitializerImpl.init() signalisiert der OEM-Bibliothek, dass eine App versucht, Erweiterungen zu verwenden.

Camera2/X führt keine weiteren Aufrufe an die OEM-Bibliothek durch (abgesehen von der Versionsprüfung), bis die OEM-Anbieterbibliothek OnExtensionsInitializedCallback.onSuccess() aufruft, um den Abschluss der Initialisierung zu melden.

Sie müssen InitializerImpl ab extensions-interface 1.1.0 implementieren. Camera2/X überspringt den Bibliotheksinitialisierungsschritt, wenn die OEM-Anbieterbibliothek extensions-interface 1.0.0 implementiert.

Basic Extender im Vergleich zu Advanced Extender

Es gibt zwei Arten der Implementierung von extensions-interface : Basic Extender und Advanced Extender. Advanced Extender wird seit extensions-interface 1.2.0 unterstützt.

Implementieren Sie Basic Extender für Erweiterungen, die Bilder im Kamera-HAL verarbeiten, oder verwenden Sie einen Postprozessor, der YUV-Streams verarbeiten kann.

Implementieren Sie Advanced Extender für Erweiterungen, die die Kamera2-Stream-Konfiguration anpassen und bei Bedarf Aufnahmeanfragen senden müssen.

Den Vergleich finden Sie in der folgenden Tabelle:

Basis-Extender Erweiterter Extender
Stream-Konfigurationen Fest
Vorschau: PRIVATE oder YUV_420_888 (sofern Prozessor vorhanden)
Standbildaufnahme: JPEG oder YUV_420_888 (sofern Prozessor vorhanden)
Anpassbar durch OEM.
Aufnahmeanfrage wird gesendet Nur Camera2/X kann Aufnahmeanfragen senden. Sie können die Parameter für diese Anfragen festlegen. Wenn der Prozessor für die Bildaufnahme bereitgestellt wird, kann Camera2/X mehrere Aufnahmeanfragen senden und alle Bilder und Aufnahmeergebnisse an den Prozessor senden. Ihnen wird eine RequestProcessorImpl Instanz zur Verfügung gestellt, um die Kamera2-Erfassungsanforderung auszuführen und Ergebnisse und Bilder zu erhalten.

Camera2/X ruft startRepeating und startCapture auf SessionProcessorImpl auf, um dem OEM zu signalisieren, die wiederholte Anforderung für die Vorschau zu starten bzw. die Standbildaufnahmesequenz zu starten.

Haken in der Kamera-Pipeline
  • onPresetSession stellt Sitzungsparameter bereit.
  • onEnableSession sendet eine einzelne Anfrage direkt nach der Konfiguration CameraCaptureSession .
  • onDisableSession sendet eine einzelne Anfrage, bevor CameraCaptureSession geschlossen wird.
  • initSession initialisiert und gibt eine angepasste Kamera2-Sitzungskonfiguration zum Erstellen der Aufnahmesitzung zurück.
  • onCaptureSessionStart wird direkt nach der Konfiguration von CameraCaptureSession aufgerufen.
  • onCaptureSessionEnd wird aufgerufen, bevor CameraCaptureSession geschlossen wird.
Passend für Erweiterungen, die in der Kamera-HAL oder in einem Prozessor implementiert sind, der YUV-Bilder verarbeitet.
  • Verfügt über Camera2-basierte Implementierungen für die Erweiterungen.
  • Benötigt eine angepasste Stream-Konfiguration, z. B. einen RAW-Stream.
  • Benötigt interaktive Aufnahmesequenz.
Unterstützte API-Version Camera2-Erweiterungen: Android 13 oder höher
CameraX-Erweiterungen: camera-extensions 1.1.0 oder höher
Kamera2-Erweiterungen: Android 12L oder höher
CameraX-Erweiterungen: camera-extensions 1.2.0-alpha03 oder höher

App-Flows

Die folgende Tabelle zeigt drei Arten von App-Flows und ihre entsprechenden API-Aufrufe für Kameraerweiterungen. Während Camera2/X diese APIs bereitstellt, müssen Sie die Herstellerbibliothek ordnungsgemäß implementieren, um diese Abläufe zu unterstützen, die wir in einem späteren Abschnitt ausführlicher beschreiben.

Camera2-Erweiterungen CameraX-Erweiterungen
Verfügbarkeit der Erweiterung abfragen CameraExtensionCharacteristics . getSupportedExtensions ExtensionsManager. isExtensionAvailable
Informationen abfragen CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys ExtensionsManager. getEstimatedCaptureLatencyRange

CameraX verwaltet den Rest der Informationen innerhalb der Bibliothek.

Vorschau und Standbildaufnahme mit aktivierter Erweiterung CameraDevice. createExtensionSession

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector bindToLifecycle(lifecycleOwner, cameraSelector, Vorschau, ...)

Basis-Extender

Die Basic Extender-Schnittstelle bietet Hooks an mehreren Stellen in der Kamera-Pipeline. Jeder Erweiterungstyp verfügt über entsprechende Extender-Klassen, die OEMs implementieren müssen.

In der folgenden Tabelle sind die Extender-Klassen aufgeführt, die OEMS für jede Erweiterung implementieren müssen:

Zu implementierende Extender-Klassen
Nacht NightPreviewExtenderImpl.java

NightImageCaptureExtenderImpl.java

HDR HdrPreviewExtenderImpl.java HdrImageCaptureExtenderImpl.java
Auto AutoPreviewExtenderImpl.java AutoImageCaptureExtenderImpl.java
Bokeh BokehPreviewExtenderImpl.java BokehImageCaptureExtenderImpl.java
Gesichtsretusche BeautyPreviewExtenderImpl.java BeautyImageCaptureExtenderImpl.java

Im folgenden Beispiel verwenden wir PreviewExtenderImpl und ImageCaptureExtenderImpl als Platzhalter. Ersetzen Sie diese durch die Namen der tatsächlichen Dateien, die Sie implementieren.

Basic Extender verfügt über die folgenden Funktionen:

  • Fügen Sie Sitzungsparameter ein, wenn Sie CameraCaptureSession ( onPresetSession ) konfigurieren.
  • Benachrichtigen Sie Sie über die Start- und Abschlussereignisse der Erfassungssitzung und senden Sie eine einzelne Anfrage, um die HAL mit den zurückgegebenen Parametern ( onEnableSession , onDisableSession ) zu benachrichtigen.
  • Fügen Sie Erfassungsparameter für die Anforderung ein ( PreviewExtenderImpl.getCaptureStage , ImageCaptureExtenderImpl.getCaptureStages ).
  • Fügen Sie Prozessoren für die Vorschau hinzu und erfassen Sie weiterhin, die YUV_420_888 -Stream verarbeiten können.

Sehen wir uns an, wie Camera2/X die extensions-interface aufruft, um die drei oben genannten App-Flows zu erreichen.

App-Flow 1: Verfügbarkeit der Erweiterung prüfen

BasicExtenderAppFlow1

Abbildung 3. App-Flow 1 auf Basic Extender

In diesem Ablauf ruft Camera2/X direkt die Methode isExtensionAvailable() von PreviewExtenderImpl und ImageCaptureExtenderImpl auf, ohne init() aufzurufen. Beide Extender-Klassen müssen true zurückgeben, um die Erweiterungen zu aktivieren.

Dies ist oft der erste Schritt für Apps, um zu prüfen, ob der angegebene Erweiterungstyp für eine bestimmte Kamera-ID unterstützt wird, bevor die Erweiterung aktiviert wird. Dies liegt daran, dass einige Erweiterungen nur auf bestimmten Kamera-IDs unterstützt werden.

App-Flow 2: Informationen abfragen

BasicExtenderAppFlow2

Abbildung 4. App-Flow 2 auf Basic Extender

Nachdem festgestellt wurde, ob die Erweiterung verfügbar ist, sollten Apps die folgenden Informationen abfragen, bevor sie die Erweiterung aktivieren.

  • Noch erfasster Latenzzeitbereich: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange gibt den Bereich der Erfassungslatenz für die App zurück, um zu bewerten, ob es angemessen ist, die Erweiterung für das aktuelle Szenario zu aktivieren.

  • Unterstützte Größen für die Vorschau- und Aufnahmeoberfläche: ImageCaptureExtenderImpl.getSupportedResolutions und PreviewExtenderImpl.getSupportedResolutions geben eine Liste der Bildformate und der Größen zurück, die für Oberflächenformat und -größe unterstützt werden.

  • Unterstützte Anforderungs- und Ergebnisschlüssel: Camera2/X ruft die folgenden Methoden auf, um die unterstützten Erfassungsanforderungsschlüssel und Ergebnisschlüssel aus Ihrer Implementierung abzurufen:

    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
    • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X ruft bei diesen Extender-Klassen immer zuerst init() auf, bevor weitere Informationen abgefragt werden.

App-Flow 3: Vorschau/Standbildaufnahme mit aktivierter Erweiterung (HAL-Implementierung)

BasicExtenderAppFlow3

Abbildung 5. App-Flow 3 auf Basic Extender

Das obige Diagramm veranschaulicht den Hauptablauf der Aktivierung der Vorschau und der Standbildaufnahme mit einer Erweiterung ohne Prozessor. Dies bedeutet, dass die Kamera-HAL die Erweiterung verarbeitet.

In diesem Ablauf ruft Camera2/X zuerst init() und dann onInit auf, was Sie benachrichtigt, dass eine Kamerasitzung mit den angegebenen Erweiterungen beginnen wird. Mit onInit() können Sie eine anspruchsvolle Initialisierung durchführen.

Beim Konfigurieren CameraCaptureSession ruft Camera2/X onPresetSession auf, um die Sitzungsparameter abzurufen. Nachdem die Aufnahmesitzung erfolgreich konfiguriert wurde, ruft Camera2/X onEnableSession auf und gibt eine CaptureStageImpl Instanz zurück, die die Aufnahmeparameter enthält. Camera2/X sendet sofort eine einzelne Anfrage mit diesen Aufnahmeparametern, um den HAL zu benachrichtigen. Ebenso ruft Camera2/X vor dem Schließen der Aufnahmesitzung onDisableSession auf und sendet dann eine einzelne Anfrage mit den zurückgegebenen Aufnahmeparametern.

Die von Camera2/X ausgelöste wiederholte Anfrage enthält die von PreviewExtenderImpl.getCaptureStage() zurückgegebenen Anfrageparameter. Darüber hinaus enthält die Standbildaufnahmeanforderung die von ImageCaptureExtenderImpl.getCaptureStages() zurückgegebenen Parameter.

Schließlich ruft Camera2/X onDeInit() auf, nachdem die Kamerasitzung beendet ist. Sie können Ressourcen in onDeinit() freigeben.

Vorschauprozessor

Zusätzlich zum Kamera-HAL können Sie auch Erweiterungen in einem Prozessor implementieren.

Implementieren Sie PreviewExtenderImpl.getProcessorType , um den Prozessortyp wie unten erläutert anzugeben:

  • PROCESSOR_TYPE_NONE : Kein Prozessor. Die Bilder werden im Kamera-HAL verarbeitet.

  • PROCESSOR_TYPE_REQUEST_UPDATE_ONLY : Mit dem Prozessortyp können Sie die wiederholte Anforderung mit neuen Erfassungsanforderungsparametern basierend auf dem neuesten TotalCaptureResult aktualisieren.

    PreviewExtenderImpl.getProcessor muss eine RequestUpdateProcessorImpl Instanz zurückgeben, die die TotalCaptureResult Instanz verarbeitet, und eine CaptureStageImpl Instanz zurückgeben, um die wiederholte Anforderung zu aktualisieren. PreviewExtenderImpl.getCaptureStage() sollte auch das Ergebnis der Verarbeitung widerspiegeln und das neueste CaptureStageImpl zurückgeben.

  • PROCESSOR_TYPE_IMAGE_PROCESSOR : Mit diesem Typ können Sie einen Prozessor implementieren, um YUV_420_888 -Bilder zu verarbeiten und die Ausgabe auf eine PRIVATE Oberfläche zu schreiben.

    Sie müssen eine PreviewImageProcessorImpl Instanz in PreviewExtenderImpl.getProcessor implementieren und zurückgeben. Der Prozessor ist für die Verarbeitung YUV_420_888 Eingabebildern verantwortlich. Die Ausgabe sollte in das PRIVATE Vorschauformat geschrieben werden. Camera2/X verwendet eine YUV_420_888 Oberfläche anstelle von PRIVATE , um die CameraCaptureSession für die Vorschau zu konfigurieren.

    Den Ablauf finden Sie in der folgenden Abbildung:

PreviewProcessor

Abbildung 6. Vorschauablauf mit PreviewImageProcessorImpl

Die PreviewImageProcessorImpl Schnittstelle erweitert ProcessImpl und verfügt über drei wichtige Methoden:

  • onOutputSurface(Surface surface, int imageFormat) legt die Ausgabeoberfläche für den Prozessor fest. Für PreviewImageProcessorImpl ist imageFormat ein Pixelformat wie PixelFormat.RGBA_8888 .

  • onResolutionUpdate(Size size) legt die Größe des Eingabebildes fest.

  • onImageFormatUpdate(int imageFormat) legt das Bildformat des Eingabebildes fest. Derzeit kann es nur YUV_420_888 sein.

Bilderfassungsprozessor

Für die Standbilderfassung können Sie einen Prozessor implementieren, indem Sie mit ImageCaptureExtenderImpl.getCaptureProcessor eine CaptureProcessorImpl Instanz zurückgeben. Der Prozessor ist dafür verantwortlich, eine Liste der erfassten YUV_420_888 Bilder und TotalCaptureResult Instanzen zu verarbeiten und die Ausgabe auf eine YUV_420_888 -Oberfläche zu schreiben.

Sie können mit Sicherheit davon ausgehen, dass die Vorschau aktiviert ist und ausgeführt wird, bevor Sie die Anforderung zur Standbildaufnahme senden.

Sehen Sie sich den Ablauf im Diagramm unten an:

CaptureProcessor

Abbildung 7. Standbild-Erfassungsfluss mit CaptureProcessorImpl

  1. Camera2/X verwendet eine Oberfläche YUV_420_888 -Format für die Standbildaufnahme, um die Aufnahmesitzung zu konfigurieren. Camera2/X bereitet CaptureProcessorImpl vor, indem es Folgendes aufruft:

    • CaptureProcessorImpl.onImageFormatUpdate() mit YUV_420_888 .
    • CaptureProcessorImpl.onResolutionUpdate() mit der Eingabebildgröße.
    • CaptureProcessorImpl.onOutputSurface() mit einer Ausgabeoberfläche YUV_420_888 .
  2. ImageCaptureExtenderImpl.getCaptureStages gibt eine Liste von CaptureStageImpl zurück, wobei jedes Element einer CaptureRequest Instanz mit Erfassungsparametern zugeordnet ist, die von Camera2/X gesendet werden. Wenn beispielsweise eine Liste mit drei CaptureStageImpl Instanzen zurückgegeben wird, sendet Camera2/X mithilfe der captureBurst API drei Aufnahmeanforderungen mit entsprechenden Aufnahmeparametern.

  3. Die empfangenen Bilder und TotalCaptureResult Instanzen werden gebündelt und zur Verarbeitung an CaptureProcessorImpl gesendet.

  4. CaptureProcessorImpl schreibt das Ergebnisbild (Format YUV_420_888 ) auf die Ausgabeoberfläche, die durch den Aufruf onOutputSurface() angegeben wird. Camera2/X wandelt es bei Bedarf in JPEG-Bilder um.

Support-Capture-Anfrageschlüssel und -ergebnisse

Zusätzlich zur Kameravorschau und -aufnahme können Apps Zoom und Blitzparameter einstellen oder einen Tap-to-Focus auslösen. Diese Parameter sind möglicherweise nicht mit Ihrer Erweiterungsimplementierung kompatibel.

Die folgenden Methoden wurden zu extensions-interface 1.3.0 hinzugefügt, damit Sie die von Ihrer Implementierung unterstützten Parameter verfügbar machen können:

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() gibt die von Ihrer Implementierung unterstützten Erfassungsanforderungsschlüssel zurück.
  • ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() gibt die Erfassungsergebnisschlüssel zurück, die im Erfassungsergebnis enthalten sind.

Wenn die Kamera-HAL die Erweiterung verarbeitet, ruft Camera2/X die Aufnahmeergebnisse in CameraCaptureSession.CaptureCallback ab. Wenn der Prozessor jedoch implementiert ist, ruft Camera2/X die Aufnahmeergebnisse in ProcessResultImpl ab, die an die Methode process() in PreviewImageProcessorImpl und CaptureProcessorImpl übergeben werden. Sie sind dafür verantwortlich, das Erfassungsergebnis über ProcessResultImpl an Camera2/X zu melden.

Sehen Sie sich die Definition der CaptureProcessorImpl Schnittstelle unten als Beispiel an. In extensions-interface 1.3.0 oder höher wird der zweite Aufruf von process() aufgerufen:

Interface CaptureProcessorImpl extends ProcessorImpl {
    // invoked when extensions-interface version < 1.3.0
    void process(Map<Integer, Pair<Image, TotalCaptureResult>> results);
    // invoked when extensions-interface version >= 1.3.0
    void process(Map<Integer, Pair<Image, TotalCaptureResult>> results,
            ProcessResultImpl resultCallback, Executor executor);
}

Für gängige Kamerafunktionen wie Zoom, Tippen zum Fokussieren, Blitz und Belichtungskorrektur empfehlen wir die Unterstützung der folgenden Tasten sowohl für die Aufnahmeanforderung als auch für das Aufnahmeergebnis:

  • Zoomen:
    • CaptureRequest#CONTROL_ZOOM_RATIO
    • CaptureRequest#SCALER_CROP_REGION
  • Tippen zum Fokussieren:
    • CaptureRequest#CONTROL_AF_MODE
    • CaptureRequest#CONTROL_AF_TRIGGER
    • CaptureRequest#CONTROL_AF_REGIONS
    • CaptureRequest#CONTROL_AE_REGIONS
    • CaptureRequest#CONTROL_AWB_REGIONS
  • Blitz:
    • CaptureRequest#CONTROL_AE_MODE
    • CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
    • CaptureRequest#FLASH_MODE
  • Belichtungsausgleich:
    • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

Für Basic Extender, die 1.2.0 oder frühere Versionen implementieren, unterstützt die CameraX Extensions API explizit alle oben genannten Schlüssel. Für extensions-interface 1.3.0 berücksichtigen sowohl CameraX als auch Camera2 die zurückgegebene Liste und unterstützen nur die darin enthaltenen Schlüssel. Wenn Sie sich beispielsweise dafür entscheiden, in der 1.3.0-Implementierung nur CaptureRequest#CONTROL_ZOOM_RATIO und CaptureRequest#SCALER_CROP_REGION zurückzugeben, bedeutet dies, dass nur Zoom für die App unterstützt wird, während Tap-to-Focus, Blitz und Belichtungskorrektur nicht zulässig sind.

Erweiterter Extender

Advanced Extender ist eine Art Anbieterimplementierung, die auf der Camera2-API basiert. Dieser Extender-Typ wurde in extensions-interface 1.2.0 hinzugefügt. Je nach Gerätehersteller können Erweiterungen im App-Layer implementiert werden, was von folgenden Faktoren abhängt:

  • Benutzerdefinierte Stream-Konfiguration: Konfigurieren Sie benutzerdefinierte Streams wie RAW-Streams oder verfügen Sie über mehrere Streams für verschiedene physische Kamera-IDs.

  • Möglichkeit zum Senden von Camera2-Anfragen: Unterstützt eine komplizierte Interaktionslogik, die Aufnahmeanfragen mit Parametern senden kann, die auf den Ergebnissen früherer Anfragen basieren.

Advanced Extender stellt einen Wrapper oder eine Zwischenschicht bereit, sodass Sie die Stream-Konfiguration anpassen und Erfassungsanforderungen bei Bedarf senden können.

Zu implementierende Dateien

Um zur Advanced Extender-Implementierung zu wechseln, muss die Methode isAdvancedExtenderImplemented() in ExtensionVersionImpl true zurückgeben. Für jeden Erweiterungstyp müssen OEMs die entsprechenden Extender-Klassen implementieren. Die Advanced Extender-Implementierungsdateien befinden sich im Advanced- Paket.

Zu implementierende Extender-Klassen
Nacht advanced/NightAdvancedExtenderImpl.java
HDR advanced/HdrAdvancedExtenderImpl.java
Auto advanced/AutoAdvancedExtenderImpl.java
Bokeh advanced/BokehAdvancedExtenderImpl.java
Gesichtsretusche advanced/BeautyAdvancedExtenderImpl.java

Im folgenden Beispiel verwenden wir AdvancedExtenderImpl als Platzhalter. Ersetzen Sie es durch den Namen der Extender-Datei für die Erweiterung, die Sie implementieren.

Sehen wir uns an, wie Camera2/X die extensions-interface aufruft, um die drei App-Flows zu erreichen.

App-Ablauf 1: Verfügbarkeit von Erweiterungen prüfen

AdvancedAppFlow1

Abbildung 8. App-Flow 1 auf Advanced Extender

Zunächst prüft die App, ob die angegebene Erweiterung unterstützt wird.

App-Flow 2: Informationen abfragen

AdvancedAppFlow2

Abbildung 9. App-Flow 2 auf Advanced Extender

Nach dem Aufruf AdvancedExtenderImpl.init() kann die App die folgenden Informationen zu AdvancedExtenderImpl abfragen:

  • Geschätzte Stillstand-Erfassungslatenz: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() gibt den Bereich der Erfassungslatenz für die App zurück, um zu bewerten, ob es angemessen ist, die Erweiterung für das aktuelle Szenario zu aktivieren.

  • Unterstützte Auflösungen für Vorschau und Standbildaufnahme:

    • AdvancedExtenderImpl.getSupportedPreviewOutputResolutions() gibt eine Zuordnung des Bildformats zur Größenliste zurück, die für Format und Größe der Vorschauoberfläche unterstützt wird. OEMs müssen mindestens das PRIVATE Format unterstützen.

    • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() gibt das unterstützte Format und die unterstützten Größen für die Standbildaufnahmeoberfläche zurück. OEMs müssen sowohl die Ausgabe JPEG als auch YUV_420_888 -Format unterstützen.

    • AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() gibt die unterstützten Größen für einen zusätzlichen YUV_420_888 Stream für die Bildanalyse zurück. Wenn die YUV-Oberfläche der Bildanalyse nicht unterstützt wird, sollte getSupportedYuvAnalysisResolutions() null oder eine leere Liste zurückgeben.

  • Verfügbare Erfassungsanforderungsschlüssel/-ergebnisse (hinzugefügt in extensions-interface 1.3.0): Camera2/X ruft die folgenden Methoden auf, um die unterstützten Erfassungsanforderungsschlüssel und Ergebnisschlüssel aus Ihrer Implementierung abzurufen:

    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
    • AdvancedExtenderImpl.getAvailableCaptureResultKeys

Weitere Informationen finden Sie unter Schlüssel und Ergebnisse von Support-Erfassungsanfragen .

App-Flow 3: Vorschau/Standbildaufnahme mit aktivierter Erweiterung

AdvancedAppFlow3

Abbildung 10. App-Flow 3 auf Advanced Extender

Das obige Diagramm zeigt den Hauptablauf zum Starten der Vorschau und Standbildaufnahme für den Advanced Extender-Typ. Gehen wir jeden Schritt durch.

  1. SessionProcessorImpl Instanz

    Die Kernimplementierung von Advanced Extender befindet sich in SessionProcessorImpl , das für die Bereitstellung einer benutzerdefinierten Sitzungskonfiguration und das Senden von Erfassungsanforderungen verantwortlich ist, um die Vorschau- und Standbilderfassungsanfrage zu initiieren. AdvancedExtenderImpl.createSessionProcessor() wird aufgerufen, um die SessionProcessorImpl Instanz zurückzugeben.

  2. initSession

    SessionProcessorImpl.initSession() initialisiert die Sitzung für die Erweiterung. Hier weisen Sie Ressourcen zu und geben eine Sitzungskonfiguration zur Vorbereitung einer CameraCaptureSession zurück.

    Für die Eingabeparameter gibt Camera2/X die Ausgabeoberflächenkonfigurationen für Vorschau, Standbildaufnahme und eine optionale YUV-Bildanalyse an. Diese Ausgabeoberflächenkonfiguration ( OutputSurfaceImpl ) enthält die Oberfläche, Größe und das Bildformat, die durch die folgenden Methoden in AdvancedExtenderImpl abgerufen werden:

    • getSupportedPreviewOutputResolutions()
    • getSupportedCaptureOutputResolutions()
    • getSupportedYuvAnalysisResolutions()

    Sie müssen eine Camera2SessionConfigImpl Instanz zurückgeben, die aus einer Liste von Camera2OutputConfigImpl Instanzen und den Sitzungsparametern besteht, die zum Konfigurieren CameraCaptureSession verwendet werden. Sie sind dafür verantwortlich, die richtigen Kamerabilder an die von Camera2/X übergebenen Ausgabeoberflächen auszugeben. Hier sind einige Optionen, um die Ausgabe zu aktivieren:

    • Verarbeitung in Kamera-HAL: Sie können die Ausgabeoberflächen mit einer SurfaceOutputConfigImpl Implementierung direkt zu CameraCaptureSession hinzufügen. Dadurch wird die bereitgestellte Ausgabeoberfläche für die Kamera-Pipeline konfiguriert und ermöglicht der Kamera-HAL, das Bild zu verarbeiten.
    • Verarbeiten der Zwischen- ImageReader Oberfläche (RAW, YUV usw.): Fügen Sie die Zwischen- ImageReader Oberflächen mit einer ImageReaderOutputConfigImpl Instanz zur CameraCaptureSession hinzu.

      Sie müssen die Zwischenbilder verarbeiten und das Ergebnisbild auf die Ausgabeoberfläche schreiben.

    • Kamera2-Oberflächenfreigabe verwenden: Verwenden Sie die Oberflächenfreigabe mit einer anderen Oberfläche, indem Sie eine beliebige Camera2OutputConfigImpl Instanz zur getSurfaceSharingOutputConfigs() Methode einer anderen Camera2OutputConfigImpl Instanz hinzufügen. Das Flächenformat und die Größe müssen identisch sein.

    Alle Camera2OutputConfigImpl , einschließlich SurfaceOutputConfigImpl und ImageReaderOutputConfigImpl , müssen eine eindeutige ID ( getId() ) haben, die verwendet wird, um die Zieloberfläche anzugeben und das Bild von ImageReaderOutputConfigImpl abzurufen.

  3. onCaptureSessionStart und RequestProcessorImpl

    Wenn CameraCaptureSession startet und das Kamera-Framework onConfigured() aufruft, ruft Camera2/X SessionProcessorImpl.onCaptureSessionStart() mit dem Camera2-Anforderungswrapper RequestProcessImpl auf. Camera2/X implementiert RequestProcessImpl , wodurch Sie die Aufnahmeanforderungen ausführen und Bilder abrufen können, wenn ImageReaderOutputConfigImpl verwendet wird.

    Die RequestProcessImpl APIs ähneln hinsichtlich der Ausführung von Anforderungen den Camera2 CameraCaptureSession APIs. Die Unterschiede sind:

    • Die Zieloberfläche wird durch die ID der Camera2OutputConfigImpl Instanz angegeben.
    • Die Fähigkeit, das Bild des ImageReader abzurufen.

    Sie können RequestProcessorImpl.setImageProcessor() mit einer angegebenen Camera2OutputConfigImpl ID aufrufen, um eine ImageProcessorImpl Instanz für den Empfang von Bildern zu registrieren.

    Die RequestProcessImpl Instanz wird ungültig, nachdem Camera2/X SessionProcessorImpl.onCaptureSessionEnd() aufruft.

  4. Starten Sie die Vorschau und machen Sie ein Foto

    In der Advanced Extender-Implementierung können Sie Erfassungsanforderungen über die Schnittstelle RequestProcessorImpl senden. Camera2/X benachrichtigt Sie, die wiederholte Anforderung für die Vorschau oder die Standbildaufnahmesequenz zu starten, indem es SessionProcessorImpl#startRepeating bzw. SessionProcessorImpl#startCapture aufruft. Sie sollten Aufnahmeanfragen senden, um diese Vorschau- und Standbildaufnahmeanfragen zu erfüllen.

    Camera2/X legt außerdem die Aufnahmeanforderungsparameter über SessionProcessorImpl#setParameters fest. Sie müssen diese Anforderungsparameter (sofern Parameter unterstützt werden) sowohl für wiederholte als auch für einzelne Anforderungen festlegen.

    Sie müssen mindestens CaptureRequest.JPEG_ORIENTATION und CaptureRequest.JPEG_QUALITY unterstützen. extensions-interface 1.3.0 unterstützt Anforderungs- und Ergebnisschlüssel, die durch die folgenden Methoden verfügbar gemacht werden:

    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys()
    • AdvancedExtenderImpl.getAvailableCaptureResultKeys()

    Wenn Entwickler die Schlüssel in der Liste getAvailableCaptureRequestKeys festlegen, müssen Sie die Parameter aktivieren und sicherstellen, dass das Erfassungsergebnis die Schlüssel in der Liste getAvailableCaptureResultKeys enthält.

  5. startTrigger

    SessionProcessorImpl.startTrigger() wird aufgerufen, um den Trigger wie CaptureRequest.CONTROL_AF_TRIGGER und CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER zu starten. Sie können alle Erfassungsanforderungsschlüssel ignorieren, die nicht in AdvancedExtenderImpl.getAvailableCaptureRequestKeys() angekündigt wurden.

    startTrigger() wird seit extensions-interface 1.3.0 unterstützt. Es ermöglicht Apps, Tap-to-Focus und Flash mit Erweiterungen zu implementieren.

  6. Aufräumen

    Beim Beenden einer Aufnahmesitzung wird SessionProcessorImpl.onCaptureSessionEnd() vor dem Schließen von CameraCaptureSession aufgerufen. Nachdem die Capture-Sitzung geschlossen wurde, führt deInitSession() die Bereinigung durch.

Unterstützt Vorschau, Standbildaufnahme und Bildanalyse

Sie sollten die Erweiterung sowohl für die Anwendungsfälle Vorschau als auch Standbilderfassung anwenden. Wenn die Latenz jedoch zu hoch ist, um die Vorschau reibungslos anzuzeigen, können Sie die Erweiterung nur für die Standbildaufnahme anwenden.

Für den Basic Extender-Typ müssen Sie unabhängig davon, ob die Erweiterung für die Vorschau aktiviert ist, sowohl ImageCaptureExtenderImpl als auch PreviewExtenderImpl für eine bestimmte Erweiterung implementieren. Oft nutzt eine App auch einen YUV-Stream, um den Bildinhalt zu analysieren, etwa um QR-Codes oder Texte zu finden. Um diesen Anwendungsfall besser zu unterstützen, sollten Sie die Stream -Kombination aus Vorschau, noch Capture und einem YUV_420_888 -Stream für die Konfiguration CameraCaptureSession unterstützen. Dies bedeutet, dass Sie die Stream -Kombination von drei YUV_420_888 -Streams unterstützen müssen, wenn Sie einen Prozessor implementieren.

Für Advanced Extender übergibt Camera2/X drei Ausgangsoberflächen an den Aufruf SessionProcessorImpl.initSession() . Diese Ausgangsoberflächen dienen der Vorschau, der Erfassung und der Bildanalyse. Sie müssen sicherstellen, dass die Vorschau und die Erfassung der Ausgangsflächen die gültige Ausgabe anzeigen. Stellen Sie jedoch sicher, dass die Bildanalyse-Ausgabeoberfläche jedoch nur dann funktioniert, wenn sie nicht null ist. Wenn Ihre Implementierung den Image -Analyse -Stream nicht unterstützen kann, können Sie eine leere Liste in AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() zurückgeben. Dies stellt sicher, dass die Bildanalyse -Ausgangsfläche in SessionProcessorImpl.initSession() immer null ist.

Support Video Capture

Die aktuelle Architektur der Kameraerweiterung unterstützt nur die Vorschau und erfasst dennoch Anwendungsfälle. Wir unterstützen nicht, die Erweiterung auf den MediaCodec oder MediaRecorder -Oberflächen für die Aufzeichnung des Videos zu aktivieren. Es ist jedoch möglich, dass Apps die Vorschau -Ausgabe aufzeichnen.

Die Unterstützung von MediaCodec und MediaRecorder -Oberflächen wird untersucht.

Erweiterungsspezifische Metadaten

Für Android 14 und höher können Sie mit Erweiterungsspezifisch-spezifischen Metadaten die Einstellungen und Ergebnisse von Erweiterungsanforderungen einstellen und empfangen. Insbesondere können die Clients der Kameraerweiterung mit dem Parameter EXTENSION_STRENGTH -Capture -Anforderung die Erweiterungsstärke und das Ergebnis der Erweiterung der EXTENSION_CURRENT_TYPE des erweiterten Erweiterungstyps angeben.

Anfragen erfassen

Der Parameter zur Erweiterung der Anforderung EXTENSION_STRENGTH Capture steuert die Stärke des Erweiterungs-Nachbearbeitungseffekts. Das entsprechende Erfassungsergebnis enthält den Standardfestigkeitswert, wenn dieser Parameter nicht explizit vom Client festgelegt wird. Dieser Parameter kann für diese Erweiterungstypen wie folgt angewendet werden:

  • BOKEH : Kontrolliert die Menge an Unschärfe.
  • HDR und NIGHT : steuert die Anzahl der geschmückten Bilder und die Helligkeit des endgültigen Bildes.
  • FACE_RETOUCH : Steuert die Menge an kosmetischer Verbesserung und Hautglättung.

Der unterstützte Bereich für den Parameter EXTENSION_STRENGTH liegt zwischen 0 und 100 , wobei 0 keine Verlängerungsverarbeitung oder einfache Durchgangs- und 100 angibt, was die maximale Verlängerungsstärke des Verarbeitungseffekts anzeigt.

Verwenden Sie die in Version 1.3.0 der Erweiterungsbibliotheksschnittstelle eingeführte Lieferanten -Parameter -APIs, um Unterstützung für die EXTENSION_STRENGTH hinzuzufügen. Weitere Informationen finden Sie unter getAvailableCaptureRequestKeys() .

Erfassungsergebnisse

Mit dem Ergebnis von EXTENSION_CURRENT_TYPE können Erweiterungsimplementierungen Clients über den aktiven Erweiterungstyp benachrichtigen.

Da Erweiterungen, die den AUTO Typ unter Verwendung des automatischen Typs dynamisch zwischen Erweiterungstypen wie HDR und NIGHT wechseln, je nach den Szenenbedingungen dynamisch wechseln, können Apps mit Kameraerweiterungen EXTENSION_CURRENT_TYPE verwenden, um Informationen über die aktuelle Erweiterung anzuzeigen, die von der AUTO Erweiterung ausgewählt wurde.

Schätzung der Stillstandslatenz in Echtzeit

Für Android 14 und höher können Clients der Kameraerweiterung Echtzeit abfragen, die Latenzschätzungen auf der Grundlage der Szene- und Umgebungsbedingungen unter Verwendung von getRealtimeStillCaptureLatency() erfassen können. Diese Methode liefert genauere Schätzungen als die statische getEstimatedCaptureLatencyRangeMillis() -Methode. Basierend auf der Latenzschätzung können Apps entscheiden, die Erweiterungsverarbeitung zu überspringen oder einen Hinweis anzuzeigen, um den Benutzern über einen langen Betrieb zu informieren.

CameraExtensionSession.StillCaptureLatency latency;

latency = extensionSession.getRealtimeStillCaptureLatency();

// The capture latency from ExtensionCaptureCallback#onCaptureStarted() until ExtensionCaptureCallback#onCaptureProcessStarted().

latency.getCaptureLatency();

// The processing latency from  ExtensionCaptureCallback#onCaptureProcessStarted() until  the processed frame returns to the client.

latency.getProcessingLatency();

Um die Echtzeit-Erfassung von Latenzschätzungen zu unterstützen, implementieren Sie Folgendes:

Erfassen Sie Rückrufe zum Verarbeitungsfortschritt

Für Android 14 und höher können Clients der Kameraerweiterung Rückrufe für den Fortschritt von Langzeitaufnahme -Verarbeitungsvorgängen erhalten. Apps können die aktuellen Fortschritte für Benutzer anzeigen, um die allgemeine Benutzererfahrung zu verbessern.

Apps können den folgenden Code verwenden, um diese Funktion zu integrieren:

import android.hardware.camera2.CameraExtensionSession.
ExtensionCaptureCallback;

{
…
  class AppCallbackImpl extends ExtensionCaptureCallback {
…
    @Override
    public void onCaptureProcessProgressed(
      @NonNull CameraExtensionSession session,
      @NonNull CaptureRequest request,
      @IntRange(from = 0, to = 100) int progress) {
      // Update app UI with current progress
    }
  }
…
}

Um die Rückrufe von Capture Processing Progress -Fortschritt zu unterstützen, muss Ihre Implementierung Ihrer Erweiterungsanbieter die folgenden Rückrufe mit dem aktuellen Fortschrittswert aufrufen:

Postview erfasst immer noch

Für Android 14 und höher können Kameraverlängerungen ein Post -View (Vorschau -Bild) mithilfe von setPostviewOutputConfiguration liefern. Um die Benutzererfahrung zu verbessern, können Apps ein Post -View -Image als Platzhalter anzeigen, wenn eine Erweiterung erhöht wird, und das Bild ersetzen, wenn das endgültige Bild verfügbar ist. Apps können nach dem folgenden Referenzcode Post -View -Erfassungsanforderungen konfigurieren und ausgeben:

{
…
if (!CameraExtensionCharacteristics.isPostviewAvailable()) {
    continue;
}
…
ExtensionSessionConfiguration extensionConfiguration = new
        ExtensionSessionConfiguration(
                CameraExtensionCharacteristics.EXTENSION_NIGHT,
                outputConfig,
                backgroundExecutor,
                extensionSessionStateCallback
    );

extensionConfiguration.setPostviewOutputConfiguration(
    postviewImageOutput);
…
CaptureRequest.Builder captureRequestBuilder =
    cameraDevice.createCaptureRequest(
        CameraDevice.TEMPLATE_STILL_CAPTURE);
captureRequestBuilder.addTarget(stillImageReader.getSurface());
captureRequestBuilder.addTarget(postviewImageSurface);

CaptureRequest captureRequest = captureRequestBuilder.build();
…
}

Um die Post -View -Capture zu unterstützen, muss Ihre Anbieter -Implementierung Folgendes implementieren:

Unterstützt die SurfaceView-Ausgabe

Für Android 14 und höher können Clients der Kameraerweiterung Strom und leistungsoptimierte Vorschau -Render -Pfade verwenden, indem eine SurfaceView -Instanz für die Vorschau -Ausgabe für Wiederholungsanforderungen registriert wird.

Um SurfaceView -Ausgabe zu unterstützen, muss Ihre Implementierung der Anbieter -Erweiterung in der Lage sein, Vorschau auf SurfaceView -Instanzen zu streamen und auszugeben. Um zu überprüfen, ob dies unterstützt wird, führen Sie das SurfaceViewExtensionPreviewTest.java CTS -Modul aus.

Lieferantenspezifische Sitzungstypen

Mit der Funktion können Anbieter -Erweiterungsimplementierungen einen von einem anstelle des standardmäßigen Werteswerts festgelegten Anbieter -Sitzungstyp aus auswählen.

Die Funktion funktioniert vollständig im Rahmen- und Anbieter -Stapel und hat keinen Kunden-/öffentlichen sichtbaren API -Auswirkungen.

So implementieren Sie einen Lieferanten-spezifischen Sitzungstyp, implementieren Sie Folgendes für Ihre Erweiterungsbibliotheken: * ExtenderStateListener.onSessionType() für grundlegende Erweiterungen * Camera2SessionConfigImpl.getSessionType() für fortschrittliche Erweiterungen

Verlängerungen Schnittstellenversionsverlauf

Die folgende Tabelle zeigt den Versionsverlauf der Kameraerweiterungsschnittstelle. Sie sollten die Lieferantenbibliothek immer mit der neuesten Version implementieren.

Ausführung Funktionen hinzugefügt
1.0.0
  • Versionsüberprüfung
    • ExtensionVersionImpl
  • Grundlegender Extender
    • PreviewExtenderImpl
    • ImageCaptureExtenderImpl
    • Processor
      • PreviewImageProcessorImpl
      • CaptureProcessorImpl
      • RequestUpdateProcessorImpl
1.1.0
  • Bibliotheksinitialisierung
    • InitializerImpl
  • Entdecken Sie unterstützte Resolutionen
    • PreviewExtenderImpl.getSupportedResolutions
    • ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0
  • AdvancedExtender
    • AdvancedExtenderImpl
    • SessionProcessorImpl
  • Erhalten Sie eine geschätzte Erfassungslatenz
    • ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0
  • Entdecken Sie unterstützte Erfassungsanforderungsschlüssel/Ergebnisschlüssel
    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys und getAvailableCaptureResultKeys
    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys und getAvailableCaptureResultKeys
    • Neue process() Aufruf, der ProcessResultImpl in PreviewImageProcessorImpl und CaptureProcessorImpl nimmt
    • Unterstützen Sie Triggertypanfragen
      • AdvancedExtenderImpl.startTrigger
1.4.0
  • Erweiterungsspezifische Metadaten
  • Dynamic erfasst immer noch Latenzschätzungen
  • Erfassen Sie Rückrufe zum Verarbeitungsfortschritt
  • Postview erfasst immer noch
  • Unterstützung für die Ausgabe SurfaceView
  • Lieferantenspezifische Sitzungstypen

Referenzimplementierung

Die folgenden Implementierungen der Referenz -OEM -Anbieter -Bibliothek sind in frameworks/ex verfügbar.

  • advancedSample : Eine grundlegende Implementierung von Advanced Extender.

  • sample : Eine grundlegende Implementierung von Basic Extender.

  • service_based_sample : Eine Implementierung, die zeigt, wie die Erweiterungen der Kamera in einem Service gehostet werden. Diese Implementierung enthält die folgenden Komponenten:

    • oem_library : Eine OEM-Bibliothek für Camera2- und Camerax-Erweiterungen APIs, die Extensions-Interface implementiert. Dies fungiert als Durchgang, die Anrufe von Extensions-Interface in den Dienst weiterleitet. Diese Bibliothek bietet auch AIDL -Dateien und Wrapper -Klassen, um mit dem Dienst zu kommunizieren.

      Advanced Extender ist standardmäßig aktiviert. Um den grundlegenden Extender zu ermöglichen, können Sie ExtensionsVersionImpl#isAdvancedExtenderImplemented zur Rückgabe false zurückgeben.

    • extensions_service : Eine Beispielimplementierung des Erweiterungsdienstes. Fügen Sie hier Ihre Implementierung hinzu. Die Schnittstelle, die im Service implementiert werden soll, ähnelt der Extensions-Interface . Beispielsweise führt die Implementierung des IAdvancedExtenderImpl.Stub die gleichen Operationen wie AdvancedExtenderImpl durch. ImageWrapper und TotalCaptureResultWrapper sind erforderlich, um Image und TotalCaptureResult -palzabierbar zu erstellen.

Richten Sie die Lieferantenbibliothek auf einem Gerät ein

Die OEM -Verkäuferbibliothek ist nicht in eine App integriert. Es wird zur Laufzeit von Camera2/x vom Gerät geladen. In Camerax erklärt das <uses-library> Tag, dass die in der Datei AndroidManifest.xml der camera-extensions Bibliothek definierte androidx.camera.extensions.impl -Bibliothek eine Abhängigkeit von Camerax ist und zur Laufzeit geladen werden muss. In Camera2 lädt das Framework einen Erweiterungsdienst, der auch erklärt, dass das <uses-library> dieselbe androidx.camera.extensions.impl Bibliothek zur Laufzeit lädt.

Auf diese Weise können Apps von Drittanbietern die Erweiterung der OEM-Anbieterbibliothek automatisch laden. Die OEM -Bibliothek ist als optional gekennzeichnet, sodass Apps auf Geräten ausgeführt werden können, die die Bibliothek nicht auf dem Gerät haben. Camera2/X erledigt dieses Verhalten automatisch, wenn eine App versucht, eine Kameraverlängerung zu verwenden, solange der Gerätehersteller die OEM -Bibliothek auf das Gerät platziert, damit sie von der App ermittelt werden kann.

Um die OEM -Bibliothek auf einem Gerät einzurichten, machen Sie Folgendes:

  1. Fügen Sie eine Berechtigungsdatei hinzu, die vom folgenden Format <uses-library> Tag erforderlich ist: /etc/permissions/ ANY_FILENAME .xml . Zum Beispiel /etc/permissions/camera_extensions.xml . Die Dateien in diesem Verzeichnis bieten eine Zuordnung der in <uses-library> genannten Bibliothek auf den tatsächlichen Dateipfad auf dem Gerät.
  2. Verwenden Sie das Beispiel unten, um die erforderlichen Informationen zur Datei hinzuzufügen.

    • name muss androidx.camera.extensions.impl sein, da dies die Bibliothek ist, nach der Camerax sucht.
    • file ist der absolute Pfad der Datei, der die Extensionsimplementierung enthält (z. B. /system/framework/androidx.camera.extensions.impl.jar ).
    <?xml version="1.0" encoding="utf-8"?>
    <permissions>
        <library name="androidx.camera.extensions.impl"
                 file="OEM_IMPLEMENTED_JAR" />
    </permissions>
    

In Android 12 oder höher müssen Geräte, die Camerax -Erweiterungen unterstützen, die auf true eingestellten ro.camerax.extensions.enabled -Eigenschaften haben, die es ermöglicht, ob ein Gerät Erweiterungen unterstützt. Fügen Sie dazu die folgende Zeile in das Gerät hinzu und erstellen Sie die Datei:

PRODUCT_VENDOR_PROPERTIES += \
    ro.camerax.extensions.enabled=true \

Validierung

Um Ihre Implementierung der OEM-Anbieterbibliothek während der Entwicklungsphase zu testen, verwenden Sie die Beispiel-App unter androidx-main/camera/integration-tests/extensionstestapp/ , die verschiedene Anbieter-Erweiterungen durchläuft.

Verwenden Sie nach Abschluss Ihrer Implementierung das Validierungswerkzeug der Kameraerweiterungen , um automatisierte und manuelle Tests auszuführen, um zu überprüfen, ob die Lieferantenbibliothek korrekt implementiert ist.

Erweiterter Szenenmodus im Vergleich zur Kamera -Erweiterungen

Für die Bokeh -Erweiterung können Sie zusätzlich zum Aussetzen der Kamera -Erweiterungen die Erweiterung mit dem erweiterten Szenenmodus freilegen, der über die Schlüsselsteuerung der CONTROL_EXTENDED_SCENE_MODE aktiviert ist. Weitere Informationen zur Implementierung finden Sie unter Kamera Bokeh .

Der erweiterte Szenenmodus weist im Vergleich zu Kamera -Apps weniger Einschränkungen auf. Sie können beispielsweise den erweiterten Szenenmodus in einer regulären CameraCaptureSession -Instanz aktivieren, die flexible Stream -Kombinationen und Capture -Anforderungsparameter unterstützt. Im Gegensatz dazu unterstützen Kameraerweiterungen nur einen festen Satz von Stream -Typen und unterstützen nur begrenzte Unterstützung für Capture -Anforderungsparameter.

Ein Nachteil des erweiterten Szenenmodus ist, dass Sie ihn nur in der Kamera -Hal -HAL implementieren können. Dies bedeutet, dass er überprüft werden muss, um alle orthogonalen Steuerelemente für App -Entwickler zur Verfügung zu stellen.

Wir empfehlen, Bokeh sowohl im erweiterten Szenenmodus als auch im Kamera -Erweiterungen auszusetzen, da Apps möglicherweise eine bestimmte API verwenden, um Bokeh zu aktivieren. Wir empfehlen zunächst den erweiterten Szenenmodus, da dies die flexibelste Möglichkeit für Apps ist, die Bokeh -Erweiterung zu ermöglichen. Anschließend können Sie die Schnittstelle der Kameraverlängerungen basierend auf dem erweiterten Szenenmodus implementieren. Wenn es beispielsweise schwierig ist, Bokeh in der Kamera HAL implementieren, da ein Postprozessor in der App -Ebene zum Verarbeiten von Bildern erforderlich ist, empfehlen wir die Implementierung der Bokeh -Erweiterung mithilfe der Schnittstelle der Kameraverlängerungen.

Häufig gestellte Fragen (FAQs)

Gibt es Beschränkungen für API -Ebenen?

Ja. Dies hängt von der Android -API -Funktion ab, die von der Implementierung der OEM -Anbieter -Bibliothek erforderlich ist. Beispielsweise verwendet ExtendERTERTATELISTENER.OnpresetSession SessionConfiguration.setSessionParameters() ExtenderStateListener.onPresetSession() die Sitzungskonfiguration. Dieser Anruf ist nur auf API Level 28 und höher verfügbar. Einzelheiten zu bestimmten Schnittstellenmethoden finden Sie in der API -Referenzdokumentation .