Kameraerweiterungen

Gerätehersteller können Erweiterungen wie Bokeh, Nachtmodus und HDR anbieten. über die Oberfläche für Kameraerweiterungen, die von der OEM-Anbieterbibliothek. Entwickler können die Camera2 Extensions API und der CameraX Extensions API um auf die Erweiterungen zuzugreifen, die in der OEM-Anbieterbibliothek implementiert sind.

Eine Liste der unterstützten Erweiterungen, die für Kamera2 identisch sind und CameraX, siehe CameraX Extensions API an. Wenn Sie eine Erweiterung hinzufügen möchten, melden Sie einen Fehler mit dem Problemverfolgung

Auf dieser Seite wird beschrieben, wie Sie die OEM-Anbieterbibliothek für Geräte.

Architektur

Im folgenden Diagramm wird die Architektur der Kameraerweiterungen beschrieben. oder extensions-interface:

Abbildung 1: Architekturdiagramm für Kameraerweiterungen

Wie in der Abbildung dargestellt, müssen Sie zur Unterstützung von Kameraerweiterungen Implementieren Sie die extensions-interface aus der OEM-Anbieterbibliothek. Ihr Die OEM-Anbieterbibliothek ermöglicht zwei APIs: CameraX Extensions API und Camera2 Extensions API, die von den CameraX- bzw. Camera2-Apps verwendet werden, Anbietererweiterungen hinzu.

OEM-Anbieterbibliothek implementieren

Kopieren Sie zum Implementieren der OEM-Anbieterbibliothek camera-extensions-stub in ein Systembibliotheksprojekt. Diese Dateien definieren die Kameraerweiterungen. .

Hinweis: Sie müssen für die Dateien das Java-Protokoll androidx.camera.extensions.impl beibehalten. Pakete. Weitere Informationen finden Sie in der Beispielprojekt

Die camera-extensions-stub werden in folgende Kategorien unterteilt:

Wichtige 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 (Implementierung hinzufügen)

• ExtensionVersionImpl.java
• InitializerImpl.java

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

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

Nachterweiterungsklassen (implementieren, wenn die Nachterweiterung unterstützt wird)

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

Klassen von automatischen Erweiterungen (implementieren, wenn automatische Erweiterungen unterstützt werden)

• 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

Klassen für die Gesichtsretusche-Verlängerung (implementieren, wenn die Gesichtsretusche-Erweiterung unterstützt wird)

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

Dienstprogramme (optional, können gelöscht werden)

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

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

Hinweis: Da die OEM-Anbieterbibliothek als Teil eines Drittanbieter-App-Prozesses ausgeführt wird, darf die Anbieterbibliothek KEINE speziellen Berechtigungen (z. B. Berechtigungen).

Sehen wir uns an, wie die Camera2- und CameraX-Erweiterungs-APIs mit dem Anbieterbibliothek zum Aktivieren einer Erweiterung. Das folgende Diagramm veranschaulicht die End-to-End-Ablauf mit der Night-Erweiterung als Beispiel:

Abbildung 2: Nachterweiterung implementieren

Hinweis: Der Einfachheit halber verweisen wir auf die Camera2- und CameraX-Erweiterungs-APIs als Camera2/X.

1. Versionsüberprüfung:

   Camera2/X ruft ExtensionVersionImpl.checkApiVersion() auf, um sicherzustellen, dass der Die vom OEM implementierte extensions-interface-Version ist mit Camera2/X kompatibel. Versionen unterstützt.

2. Initialisierung der Anbieterbibliothek:

   InitializerImpl hat die Methode init(), mit der die Anbieterbibliothek initialisiert wird. Camera2/X schließt die Initialisierung ab, bevor auf die Extender-Klassen zugegriffen wird.

3. Extender-Klassen instanziieren:

   Instanziiert die Extender-Klassen für die Erweiterung. Es gibt zwei Repeater Typen: Basic Extender und Advanced Extender. Sie müssen eine Extendertyp für alle Erweiterungen. Weitere Informationen finden Sie unter Basic Extender und Advanced Extender

   Camera2/X instanziiert und interagiert mit den Extender-Klassen, um abzurufen und aktivieren Sie die Erweiterung. Kamera2/X kann für eine bestimmte Erweiterung die Extender-Klassen mehrmals instanziieren. Daher sollten Sie aufwendige Initialisierung im Konstruktor oder im Aufruf init(). Führen Sie die folgenden Schritte aus: nur dann schwer, wenn die Kamera kurz vor der z. B. wenn onInit() im Basic Extender aufgerufen wird oder initSession() wird im Advanced Extender aufgerufen.

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

   • NightImageCaptureExtenderImpl.java
   • NightPreviewExtenderImpl.java

   Und für den Advanced Extender-Typ:

   • NightAdvancedExtenderImpl.java

4. Verfügbarkeit von Erweiterungen prüfen:

   Vor der Aktivierung der Erweiterung prüft isExtensionAvailable(), für die angegebene Kamera-ID über den Extender verfügbar Instanz.

5. Extender mit Kamerainformationen initialisieren:

   Camera2/X ruft init() für die Extender-Instanz auf und übergibt es an die Kamera. ID und CameraCharacteristics.

6. Informationen zur Suchanfrage:

   Ruft die Extender-Klasse auf, um Informationen wie unterstützte Auflösungen zu erfassen, trotzdem die geschätzte Latenz und die Anfrageschlüssel den Extender in Vorbereitung auf die Aktivierung der Erweiterung.

7. Erweiterung auf dem Extender aktivieren:

   Die Extender-Klasse stellt alle erforderlichen Schnittstellen zur Verfügung, um den . Es bietet einen Mechanismus, um den OEM zu fesseln Implementierung in die Camera2-Pipeline, z. B. durch das Einfügen einer Erfassungsanfrage oder die Aktivierung eines Nachverarbeitungsprogramms.

   Beim erweiterten Verlängerungstyp interagiert Kamera2/X mit SessionProcessorImpl, um die Erweiterung zu aktivieren. Camera2/X ruft den SessionProcessorImpl durch Aufrufen von createSessionProcessor() auf der Extender

In den folgenden Abschnitten wird der Ablauf von Erweiterungen ausführlicher beschrieben.

Versionsüberprüfung

Beim Laden der OEM-Anbieterbibliothek vom Gerät zur Laufzeit prüft, ob die Bibliothek mit der extensions-interface-Version kompatibel ist. Für extensions-interface wird die semantische Versionsverwaltung verwendet. MAJOR.MINOR.PATCH, z. B. 1.1.0 oder 1.2.0. Allerdings werden nur die Haupt- und Nebenversionen werden bei der Versionsüberprüfung verwendet.

Zur Überprüfung der Version ruft Camera2/X ExtensionVersionImpl.checkApiVersion() mit den unterstützten Version extensions-interface. Camera2/X verwendet dann die vom OEM-Bibliothek, um zu ermitteln, ob die Erweiterung aktiviert werden kann und welche Funktionen aufrufen soll.

Hinweis: checkApiVersion() sollte keine extensions-interface-Version zurückgeben. die aktueller als die von Camera2/X unterstützte Version ist. Wenn beispielsweise Camera2/X unterstützt 1.3.0 und die OEM-Anbieterbibliothek 1.4.0. sollte 1.3.0 anstelle von 1.4.0 zurückgeben.

Kompatibilität mit Hauptversionen

Wenn sich die Hauptversionen der extension-interface zwischen „Kamera2/X“ und die Herstellerbibliothek enthält, gilt sie als inkompatibel und die Erweiterung deaktiviert ist.

Abwärtskompatibilität

Solange die Hauptversion identisch ist, sorgt Kamera 2/X dafür, Abwärtskompatibilität mit OEM-Anbieterbibliotheken, die mit früheren extensions-interface Versionen. Wenn z. B. Camera2/X extensions-interface 1.3.0, die OEM-Anbieterbibliotheken, die 1.0.0 implementiert haben, 1.1.0 und 1.2.0 sind weiterhin kompatibel. Das bedeutet auch, dass nach der Implementierung bestimmte Version der Anbieterbibliothek verwenden, stellt Camera2/X sicher, dass die Bibliothek ist mit zukünftigen extension-interface-Versionen abwärtskompatibel.

Aufwärtskompatibilität

Aufwärtskompatibilität mit Anbieterbibliotheken des neueren extensions-interface hängt von Ihnen als OEM ab. Wenn Sie Funktionen zum Implementieren der Erweiterungen benötigen, können Sie die Erweiterungen ab einer bestimmten Version aktivieren. In dieser können Sie die unterstützte extensions-interface-Version zurückgeben, wenn der Die Version der Camera2/X-Bibliothek erfüllt die Anforderungen. Wenn die Camera2/X-Versionen nicht unterstützt werden, können Sie eine inkompatible Version wie 99.0.0 die Erweiterungen zu deaktivieren.

Initialisierung der Anbieterbibliothek

Nach Überprüfung der vom OEM implementierten extensions-interface-Version wird der Initialisierungsprozess von Camera2/X gestartet. Die Mit der Methode InitializerImpl.init() wird der OEM-Bibliothek signalisiert, dass eine App es versucht , um Erweiterungen zu verwenden.

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

Sie müssen InitializerImpl Stand: extensions-interface 1.1.0. Camera2/X überspringt die Initialisierung der Bibliothek wenn die OEM-Anbieterbibliothek extensions-interface 1.0.0 implementiert.

Basic Extender und Advanced Extender

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

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

Implementiere Advanced Extender für Erweiterungen, die die Kamera anpassen müssen2 Streamkonfiguration an und senden bei Bedarf Erfassungsanfragen.

Den Vergleich sehen Sie in der folgenden Tabelle:

	Basic Extender	Erweiterter Repeater
Streamkonfigurationen	Fest Vorschau: PRIVATE oder YUV_420_888 (falls Prozessor vorhanden) Standbild: JPEG oder YUV_420_888 (falls Prozessor vorhanden)	Anpassbar durch OEM.
Aufnahmeanfrage wird gesendet	Nur Camera2/X kann Aufnahmeanfragen senden. Sie können die Parameter auf diese Anträge stellen. Wenn der Prozessor für die Bilderfassung bereitgestellt wird, stellt Camera2/X mehrere Aufnahmeanfragen senden, alle Bilder senden an den Prozessor weitergegeben werden.	Eine RequestProcessorImpl-Instanz wird Ihnen zur Verfügung gestellt, um die Kamera2-Erfassungsanfrage aus, um Ergebnisse und Bild abzurufen. Camera2/X ruft startRepeating und startCapture auf SessionProcessorImpl, um dem OEM zu signalisieren, dass er mit der Wiederholung beginnen soll -Anforderung für die Vorschau und Starten der entsprechenden Aufnahmesequenz.
Aufhänger in der Kamera-Pipeline	onPresetSession stellt Sitzungsparameter bereit. onEnableSession sendet direkt nach der Konfiguration von CameraCaptureSession eine einzelne Anfrage. onDisableSession sendet eine einzelne Anfrage, bevor CameraCaptureSession geschlossen wird.	initSession initialisiert eine benutzerdefinierte Kamera und gibt sie zurück.2 Sitzungskonfiguration zum Erstellen der Erfassungssitzung. onCaptureSessionStart wird direkt nach der Konfiguration von CameraCaptureSession aufgerufen. onCaptureSessionEnd wird aufgerufen, bevor CameraCaptureSession geschlossen wird.
Geeignet für	Erweiterungen, die im Kamera-HAL oder in einem Prozessor implementiert sind, der YUV-Bilder.	Hat Camera2-basierte Implementierungen für die Erweiterungen. Erfordert eine benutzerdefinierte Streamkonfiguration, z. B. einen RAW-Stream. Interaktive Erfassungssequenz erforderlich.
Unterstützte API-Version	Kamera2-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

Hinweis: Wenn ExtensionVersionImpl.isAdvancedExtenderImplemented() den Wert true zurückgibt, Du musst alle Erweiterungen in Advanced Extend implementieren. Wenn isAdvancedExtenderImplemented() gibt false zurück. Sie müssen alle in Basic Extender.

App-Abläufe

Die folgende Tabelle zeigt drei Arten von App-Abläufen und ihre Camera Extensions API-Aufrufe an. Camera2/X hingegen bietet APIs erforderlich sind, müssen Sie die Anbieterbibliothek ordnungsgemäß implementieren. die in einem späteren Abschnitt ausführlicher beschrieben werden.

	Kamera2-Erweiterungen	CameraX-Erweiterungen
Verfügbarkeit von Suchanfragenerweiterungen	CameraExtensionCharacteristics .getSupportedExtensions	ExtensionsManager. isExtensionAvailable
Informationen zur Suchanfrage	CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys	ExtensionsManager. getEstimatedCaptureLatencyRange Die restlichen Informationen innerhalb der Bibliothek werden von CameraX verarbeitet.
Vorschau und Fotoaufnahme mit aktivierter Erweiterung	CameraDevice. createExtensionSession cameraExtensionsSession. setRepeatingRequest cameraExtensionsSession. capture	val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector bindToLifecycle(lifecycleOwner, cameraSelector, preview, ...)

Basic Extender

Die Oberfläche des Basic Extenders bietet Haken an verschiedenen Stellen der Kamera. zu erstellen. Für jeden Erweiterungstyp gibt es entsprechende Extender-Klassen, die OEMs benötigen. zu implementieren.

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

	Zu implementierende Extender-Klassen
Nacht	NightPreviewExtenderImpl.java NightImageCaptureExtenderImpl.java
HDR	HdrPreviewExtenderImpl.java HdrImageCaptureExtenderImpl.java
Automatisch	AutoPreviewExtenderImpl.java AutoImageCaptureExtenderImpl.java
Bokeh	BokehPreviewExtenderImpl.java BokehImageCaptureExtenderImpl.java
Gesichtsretusche	BeautyPreviewExtenderImpl.java BeautyImageCaptureExtenderImpl.java

Wir verwenden PreviewExtenderImpl und ImageCaptureExtenderImpl als Platzhalter im folgenden Beispiel. Ersetzen Sie sie durch die Namen der die Sie implementieren.

Hinweis: Diese Extender-Klassen können bei Bedarf mehrmals instanziiert werden. in Camera2/X.

Basic Extender hat folgende Funktionen:

• Sitzungsparameter bei der Konfiguration von CameraCaptureSession einfügen ( onPresetSession).
• Benachrichtigt Sie über Start- und Schließereignisse der Erfassungssitzung und senden Sie eine Anfrage zur Benachrichtigung des HAL mit den zurückgegebenen Parametern (onEnableSession, onDisableSession).
• Erfassungsparameter für die Anfrage einfügen (PreviewExtenderImpl.getCaptureStage, ImageCaptureExtenderImpl.getCaptureStages).
• Prozessoren für die Vorschau hinzufügen und trotzdem verarbeitungsfähige Prozessoren erfassen Stream "YUV_420_888".

Hinweis :Für die Erweiterungen, bei denen dies nicht der Fall ist, müssen Sie sowohl die Vorschau als auch die Erfassung implementieren. die Sie aktivieren möchten. Wenn Sie beispielsweise die Erweiterung „Nacht“ aktivieren möchten, müssen Sie sowohl NightPreviewExtenderImpl.java als auch NightCaptureExtenderImpl.java

Sehen wir uns an, wie Camera2/X die extensions-interface aufruft, um die drei wie oben beschrieben.

Hinweis :Camera2/X initialisiert die Anbieterbibliothek immer. (InitializerImpl.init()) bevor Sie einen dieser App-Abläufe starten.

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

Abbildung 3: App-Ablauf 1 auf dem Basic Extender

Bei diesem Ablauf ruft Camera2/X die Methode isExtensionAvailable() des sowohl PreviewExtenderImpl als auch ImageCaptureExtenderImpl ohne init(). 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 die jeweilige Erweiterung wird für eine bestimmte Kamera-ID unterstützt, bevor Sie die Erweiterung aktivieren. Das liegt daran, dass einige Erweiterungen nur für bestimmte Kamera-IDs unterstützt werden.

Anwendungsfluss 2: Abfrageinformationen

Abbildung 4: App-Ablauf 2 auf dem Basic Extender

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

• Latenzbereich erfassen: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange gibt den Bereich die Erfassungslatenz, damit die App beurteilen kann, ob die Erweiterung für das aktuelle Szenario zu aktivieren.

• Unterstützte Größen für die Vorschau- und Erfassungsoberfläche: ImageCaptureExtenderImpl.getSupportedResolutions und PreviewExtenderImpl.getSupportedResolutions gibt eine Liste mit Bildformaten zurück. die für das Oberflächenformat und die -größe unterstützt werden.

• Unterstützte Anfrage- und Ergebnisschlüssel: Camera2/X ruft die folgenden Methoden auf, um die unterstützte Aufnahme abzurufen. Anforderungsschlüssel und Ergebnisschlüssel aus Ihrer Implementierung:

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
  • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X ruft bei diesen Extender-Klassen vor der Abfrage immer zuerst init() auf .

App-Ablauf 3: Vorschau/Aufnahme mit aktivierter Erweiterung (HAL-Implementierung)

Abbildung 5: App-Ablauf 3 auf dem Basic Extender

Das Diagramm oben zeigt den Hauptablauf beim Aktivieren der Vorschau. mit einer Erweiterung ohne Auftragsverarbeiter aufnehmen können. Das bedeutet, dass der Kamera-HAL verarbeitet die Erweiterung.

Bei diesem Ablauf ruft Camera2/X zuerst init() und dann onInit auf, wodurch du benachrichtigt wirst. dass eine Kamerasitzung mit den angegebenen Erweiterungen beginnt. Eine umständliche Initialisierung ist in onInit() möglich.

Beim Konfigurieren von CameraCaptureSession ruft Camera2/X onPresetSession zum Abrufen der Sitzungsparameter. Nach der Aufnahme aktiviert, ruft Camera2/X onEnableSession auf und gibt CaptureStageImpl -Instanz, die die Erfassungsparameter enthält. Kamera2/X sendet sofort eine einzelne Anfrage mit diesen Erfassungsparametern, um den HAL. Vor dem Schließen der Aufnahmesitzung ruft Camera2/X onDisableSession und sendet dann eine einzelne Anfrage mit der zurückgegebenen Aufnahme. Parameter.

Die sich wiederholende Anfrage, die von Camera2/X ausgelöst wird, enthält die Anfrageparameter. zurückgegeben von PreviewExtenderImpl.getCaptureStage(). Darüber hinaus ist das Erfassungsanfrage die Parameter enthält, die von ImageCaptureExtenderImpl.getCaptureStages()

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

Hinweis :Bei Camera2/X können mehrere Kamerasitzungen zwischen onInit() und onDeInit(), obwohl dieses Diagramm nur eine Kamerasitzung zeigt.

Vorschauprozessor

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

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

• PROCESSOR_TYPE_NONE: Kein Prozessor. Bilder werden in der Kamera verarbeitet HAL.

• PROCESSOR_TYPE_REQUEST_UPDATE_ONLY:Mit dem Prozessortyp können Sie Aktualisieren Sie die wiederkehrende Anfrage mit neuen Parametern für die Erfassungsanfrage, späteste TotalCaptureResult.

  PreviewExtenderImpl.getProcessor muss Folgendes zurückgeben: RequestUpdateProcessorImpl -Instanz, die die TotalCaptureResult-Instanz verarbeitet und eine CaptureStageImpl-Instanz, um die wiederkehrende Anfrage zu aktualisieren. PreviewExtenderImpl.getCaptureStage() sollte auch das Ergebnis von Verarbeitung ausführen und das neueste CaptureStageImpl zurückgeben.

• PROCESSOR_TYPE_IMAGE_PROCESSOR:Mit diesem Typ können Sie verarbeitet, um YUV_420_888 Bilder zu verarbeiten und die Ausgabe in einen PRIVATE.

  Sie müssen eine PreviewImageProcessorImpl Instanz in PreviewExtenderImpl.getProcessor. Der Auftragsverarbeiter ist für zur Verarbeitung von YUV_420_888 Eingabebildern verwendet. Die Ausgabe sollte in den Vorschauformat PRIVATE. Für Kamera 2/X wird stattdessen eine YUV_420_888-Oberfläche verwendet von PRIVATE, um CameraCaptureSession für die Vorschau zu konfigurieren.

  Den Ablauf sehen Sie in der folgenden Abbildung:

Abbildung 6: Vorschau mit PreviewImageProcessorImpl

Die PreviewImageProcessorImpl-Schnittstelle erweitert ProcessImpl und hat drei wichtige Methoden:

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

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

• Mit onImageFormatUpdate(int imageFormat) wird das Bildformat der Eingabe festgelegt. Bild. Derzeit können maximal YUV_420_888 Zeichen verwendet werden.

Bilderfassungsprozessor

Für Standbilder können Sie einen Prozessor implementieren, indem Sie eine CaptureProcessorImpl Instanz mit ImageCaptureExtenderImpl.getCaptureProcessor. Der Prozessor ist Verantwortlich für die Verarbeitung einer Liste erfasster YUV_420_888 Bilder und TotalCaptureResult-Instanzen und schreiben die Ausgabe in eine YUV_420_888-Oberfläche.

Sie können davon ausgehen, dass die Vorschau aktiviert ist und ausgeführt wird, bevor Sie den Anfrage trotzdem erfassen.

Siehe den Ablauf im folgenden Diagramm:

Abbildung 7: Vorgang mit CaptureProcessorImpl wird noch aufgenommen

1. Camera2/X verwendet zur Konfiguration eine Oberfläche des YUV_420_888-Formats für Standbilder. während der Aufnahme. Camera2/X bereitet CaptureProcessorImpl durch folgenden Aufruf vor:

   • CaptureProcessorImpl.onImageFormatUpdate() mit YUV_420_888.
   • CaptureProcessorImpl.onResolutionUpdate() durch die Größe des eingegebenen Bilds.
   • CaptureProcessorImpl.onOutputSurface() mit der Ausgabe YUV_420_888 Oberfläche.

2. ImageCaptureExtenderImpl.getCaptureStages gibt eine Liste mit CaptureStageImpl , wobei jedes Element einer CaptureRequest-Instanz mit Erfassungsparametern zugeordnet ist. die von Camera2/X gesendet werden. Wird z. B. eine Liste mit drei Elementen zurückgegeben, CaptureStageImpl Instanzen sendet Camera2/X drei Aufnahmeanfragen mit entsprechenden Erfassungsparametern mithilfe der captureBurst der API erstellen.

   Hinweis: getCaptureStages() kann mehr als ein Element zurückgeben. CaptureStageImpl-Instanz nur dann, wenn getCaptureProcessor() eine Instanz.

3. Die empfangenen Images und TotalCaptureResult Instanzen werden zu einem Bundle zusammengefasst und zur Verarbeitung an CaptureProcessorImpl gesendet.

4. CaptureProcessorImpl schreibt das Ergebnisbild im Format YUV_420_888 in den die durch den Aufruf onOutputSurface() angegebene Ausgabeoberfläche. Camera2/X konvertiert sie in JPEG-Bilder umwandeln.

Schlüssel und Ergebnisse für Erfassungsanfragen unterstützen

Neben der Kameravorschau und -aufnahme können Apps auch Zoom, oder einen Tap-to-Focus-Effekt auslösen. Diese Parameter sind möglicherweise nicht die mit Ihrer Erweiterungsimplementierung kompatibel sind.

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

• ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() gibt den Fehlerwert von Ihrer Implementierung unterstützte Anfrageschlüssel erfassen.
• ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() gibt den Fehlerwert Erfassungsergebnisschlüssel, die im Erfassungsergebnis enthalten sind.

Wenn der Kamera-HAL die Erweiterung verarbeitet, ruft Camera2/X die Aufnahme ab. Ergebnisse auf CameraCaptureSession.CaptureCallback. Wenn jedoch implementiert ist, ruft Camera2/X die Erfassungsergebnisse ProcessResultImpl , die an die process() übergeben wird Methode in PreviewImageProcessorImpl und CaptureProcessorImpl Sie sind für die Berichterstellung verantwortlich das Aufnahmeergebnis über ProcessResultImpl an Camera2/X senden.

Unten finden Sie ein Beispiel in der Definition der CaptureProcessorImpl-Schnittstelle. Ab extensions-interface 1.3.0 wird der zweite process()-Aufruf 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);
}

Hinweis: Die CaptureRequest#JPEG_QUALITY und CaptureRequest#JPEG_ORIENTATION Schlüssel werden immer unterstützt, unabhängig davon, ob sie der Liste hinzugefügt werden.

Für gängige Kamerafunktionen wie Zoomen, Tippen für Fokus, Blitz und Belichtung kompensieren, empfehlen wir, die folgenden Schlüssel sowohl für die Anfrage- und Erfassungsergebnis:

• Zoomen: <ph type="x-smartling-placeholder">
  </ph>
  • CaptureRequest#CONTROL_ZOOM_RATIO
  • CaptureRequest#SCALER_CROP_REGION
• Zum Fokussieren tippen: <ph type="x-smartling-placeholder">
  </ph>
  • CaptureRequest#CONTROL_AF_MODE
  • CaptureRequest#CONTROL_AF_TRIGGER
  • CaptureRequest#CONTROL_AF_REGIONS
  • CaptureRequest#CONTROL_AE_REGIONS
  • CaptureRequest#CONTROL_AWB_REGIONS
• Flash: <ph type="x-smartling-placeholder">
  </ph>
  • CaptureRequest#CONTROL_AE_MODE
  • CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
  • CaptureRequest#FLASH_MODE
• Belichtungskorrektur: <ph type="x-smartling-placeholder">
  </ph>
  • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

Bei Basic Extendern mit Version 1.2.0 oder älteren Versionen enthält die CameraX- Die Extensions API unterstützt explizit alle oben genannten Schlüssel. Für extensions-interface 1.3.0 wird sowohl von CameraX als auch von Camera2 die zurückgegebene Liste berücksichtigt und unterstützen nur die darin enthaltenen Schlüssel. Wenn Sie sich z. B. dafür entscheiden, nur CaptureRequest#CONTROL_ZOOM_RATIO und CaptureRequest#SCALER_CROP_REGION in der Implementierung von Version 1.3.0 geändert hat, bedeutet, dass von der App nur Zoomen unterstützt wird, während Tap-to-Fokus, Blitz und Belichtung unterstützt werden. Vergütungen nicht zulässig sind.

Hinweis: Die Camera2-Erweiterungen unterstützen nur die Einstellung von Parametern. JPEG_QUALITY und JPEG_ORIENTATION unter Android 12 und Android 12L. Wird gestartet In Android 13 unterstützt die Camera2 Extensions API andere Parameter wie die Zoom-Funktion. oder Flash, solange diese Schlüssel vom ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys bei Ihrem OEM-Anbieter Bibliothek, die extensions-interface 1.3.0 oder höher implementiert.

Erweiterter Repeater

Advanced Extender ist eine 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 auf der App-Ebene implementiert werden, Dies hängt von folgenden Faktoren ab:

• Benutzerdefinierte Streamkonfiguration:Benutzerdefinierte Streams wie RAW-Streams konfigurieren oder mehrere Streams für unterschiedliche IDs für physische Kameras haben.

• Funktion zum Senden von Camera2-Anfragen:Unterstützung einer komplizierten Interaktion eine Logik, die Erfassungsanfragen mit Parametern auf der Grundlage der Ergebnisse von vorherigen Anträgen.

Advanced Extender stellt einen Wrapper oder eine Zwischenebene bereit, damit Sie die Streamkonfiguration anpassen und bei Bedarf Erfassungsanfragen senden.

Hinweis: Die Camera2 Extensions API unterstützt seit Android Advanced Extender. 12L. Advanced Extender wird für die CameraX Extensions API seit CameraX 1.2.0-alpha03.

Zu implementierende Dateien

Um zur Implementierung des Advanced Extenders zu wechseln, muss der isAdvancedExtenderImplemented()-Methode in ExtensionVersionImpl muss true zurückgeben. Für jeden Erweiterungstyp müssen OEMs die entsprechenden Extender-Klassen. Die Implementierungsdateien für Advanced Extender werden im Paket advanced.

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

Im folgenden Beispiel wird AdvancedExtenderImpl als Platzhalter verwendet. Ersetzen Sie ihn durch den Namen der Extender-Datei für die Erweiterung, die Sie verwenden möchten. bei der Umsetzung.

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

Hinweis: Camera2/X initialisiert immer die Anbieterbibliothek ( InitializerImpl.init()) bevor Sie einen dieser Anwendungsabläufe starten.

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

Abbildung 8: App-Ablauf 1 auf Advanced Extender

Zuerst prüft die App, ob die jeweilige Erweiterung unterstützt wird.

Hinweis :Die App muss nicht AdvancedExtenderImpl.init() aufrufen. bevor Sie isExtensionAvailable() anrufen.

Anwendungsfluss 2: Abfrageinformationen

Abbildung 9: App-Ablauf 2 auf Advanced Extender

Nach dem Aufrufen von AdvancedExtenderImpl.init() kann die App die auf die folgenden Informationen zu AdvancedExtenderImpl:

• Geschätzte Latenz für die Aufnahme nach wie vor: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() gibt den Bereich die Erfassungslatenz, damit die App beurteilen kann, ob die Erweiterung für das aktuelle Szenario zu aktivieren.

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

  • AdvancedExtenderImpl.getSupportedPreviewOutputResolutions() gibt eine Karte zurück. des Bildformats der Liste der Größen hinzu, die für das Vorschauformat unterstützt werden. und Größe. OEMs müssen mindestens das Format PRIVATE unterstützen.

  • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() gibt den Fehlerwert unterstützte Formate und Größen für die weiterhin erfasste Oberfläche. OEMs müssen sowohl Ausgabe im Format JPEG und YUV_420_888.

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

• Verfügbare Schlüssel/Ergebnisse für Erfassungsanfragen (in extensions-interface 1.3.0 hinzugefügt): Camera2/X ruft die folgenden Methoden auf, um die unterstützte Aufnahme abzurufen. Anforderungsschlüssel und Ergebnisschlüssel aus Ihrer Implementierung:

  • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
  • AdvancedExtenderImpl.getAvailableCaptureResultKeys

Weitere Informationen finden Sie unter Erfassen Sie Anfrageschlüssel und Ergebnisse.

App-Ablauf 3: Vorschau/Aufnahme mit aktivierter Erweiterung

Abbildung 10. App-Ablauf 3 auf Advanced Extender

Das Diagramm oben zeigt den Hauptablauf für den Start der Vorschau und die Erfassung Advanced Extender-Typ Sehen wir uns die einzelnen Schritte im Einzelnen an.

1. SessionProcessorImpl Instanz

   Die zentrale Implementierung des Advanced Extenders befindet sich in SessionProcessorImpl. ist für die Bereitstellung einer benutzerdefinierten Sitzungskonfiguration und Anfragen erfassen, um die Vorschau zu starten und dennoch die Anfrage zu erfassen. AdvancedExtenderImpl.createSessionProcessor() wird aufgerufen, um den Parameter SessionProcessorImpl-Instanz.

   Hinweis: Eine Kamerasitzung kann eine SessionProcessorImpl-Instanz mehrmals verwenden. Daher muss die Implementierung mehrere initSession()- und deInitSession()-Aufrufe für eine SessionProcessorImpl-Instanz.

2. initSession

   SessionProcessorImpl.initSession() initialisiert die Sitzung für die Erweiterung. Hier ordnen Sie Ressourcen zu und geben eine Sitzungskonfiguration für CameraCaptureSession wird vorbereitet.

   Bei den Eingabeparametern gibt Camera2/X die Konfigurationen der Ausgabefläche an. für Vorschau, Stillerfassung und eine optionale YUV-Bildanalyse. Diese Ausgabe Die Flächenkonfiguration (OutputSurfaceImpl) enthält die Oberfläche, die Größe und das Bild. -Format, die mit den folgenden Methoden in AdvancedExtenderImpl abgerufen werden:

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

   Sie müssen eine Camera2SessionConfigImpl-Instanz zurückgeben, die aus einem Liste der Camera2OutputConfigImpl-Instanzen und der verwendeten Sitzungsparameter zum Konfigurieren von CameraCaptureSession. Sie sind verantwortlich für Ausgabe der richtigen Kamerabilder an die Ausgabeoberflächen, die von Camera2/X. Hier sind einige Optionen zum Aktivieren der Ausgabe:

   • Verarbeitung in Kamera-HAL:Sie können die Ausgabeflächen direkt hinzufügen. nach CameraCaptureSession mit SurfaceOutputConfigImpl Implementierung. Dadurch wird die bereitgestellte Ausgabeoberfläche für die Kamera konfiguriert und ermöglicht es dem Kamera-HAL, das Bild zu verarbeiten.

   • Verarbeitung der ImageReader-Zwischenoberfläche (RAW, YUV usw.): Füge die ImageReader-Zwischenlandungen in Richtung CameraCaptureSession mit einem ImageReaderOutputConfigImpl-Instanz.

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

   Hinweis: Camera2/X erstellt und verwaltet die ImageReader-Instanzen für Sie. Ich kann eine ImageProcessorImpl-Instanz zum Abrufen des Images festlegen.
   • Kamerabereich teilen:Sie können eine andere Oberfläche verwenden, um sie mit anderen zu teilen. indem Sie eine beliebige Camera2OutputConfigImpl-Instanz zum getSurfaceSharingOutputConfigs()-Methode einer anderen Camera2OutputConfigImpl-Instanz. Format und Größe der Oberfläche müssen identisch.

   Alle Camera2OutputConfigImpl, einschließlich SurfaceOutputConfigImpl und ImageReaderOutputConfigImpl muss eine eindeutige ID (getId()) haben: wird verwendet, um die Zieloberfläche anzugeben und das Bild von ImageReaderOutputConfigImpl

3. onCaptureSessionStart und RequestProcessorImpl

   Wenn CameraCaptureSession gestartet wird und das Kamera-Framework aufruft, onConfigured(), dann ruft Camera2/X auf SessionProcessorImpl.onCaptureSessionStart() mit der Camera2-Anfrage Wrapper RequestProcessImpl. Camera2/X implementiert RequestProcessImpl, Damit können Sie die Erfassungsanfragen ausführen. Bilder abrufen, wenn ImageReaderOutputConfigImpl verwendet wird

   Die RequestProcessImpl-APIs ähneln denen von Camera2. CameraCaptureSession APIs in Bezug auf das Ausführen von Anfragen. Es gibt folgende Unterschiede:

   • Die Zieloberfläche wird durch die ID des Camera2OutputConfigImpl-Instanz.
   • Die Fähigkeit zum Abrufen des Bildes von ImageReader.

   Sie können RequestProcessorImpl.setImageProcessor() mit einem bestimmten Camera2OutputConfigImpl-ID, bei der eine ImageProcessorImpl-Instanz registriert werden soll Bilder empfangen.

   Die Instanz RequestProcessImpl wird nach Camera2/X-Aufrufen ungültig SessionProcessorImpl.onCaptureSessionEnd().

4. Vorschau starten und ein Bild aufnehmen

   In der Advanced Extender-Implementierung kannst du Erfassungsanfragen senden über die RequestProcessorImpl-Schnittstelle. Camera2/X benachrichtigt dich, wenn die wiederholte Anfrage für die Vorschau oder die stille Aufnahmesequenz starten, indem Sie SessionProcessorImpl#startRepeating wird angerufen und SessionProcessorImpl#startCapture. Aufnahme senden -Anfragen erfüllen, die diesen Vorschau- und trotzdem Erfassungsanfragen entsprechen.

   Camera2/X legt auch die Parameter für die Erfassungsanfrage über SessionProcessorImpl#setParameters Sie müssen diese Anfrageparameter festlegen (wenn Parameter unterstützt werden) sowohl bei wiederkehrenden als auch bei Einzelanfragen.

   Sie müssen mindestens CaptureRequest.JPEG_ORIENTATION unterstützen und CaptureRequest.JPEG_QUALITY. extensions-interface 1.3.0 unterstützt Anfragen und Ergebnisschlüssel, die mit den folgenden Methoden bereitgestellt werden:

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

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

5. startTrigger

   SessionProcessorImpl.startTrigger() wird aufgerufen, um den Trigger folgendermaßen zu starten: als CaptureRequest.CONTROL_AF_TRIGGER und CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER Sie können alle Anfrageschlüssel erfassen, die nicht in AdvancedExtenderImpl.getAvailableCaptureRequestKeys()

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

6. Aufräumen

   Am Ende einer Aufnahme SessionProcessorImpl.onCaptureSessionEnd() wird vor dem Schließen aufgerufen CameraCaptureSession. Nach der Aufnahme deInitSession() führt die Bereinigung durch.

Unterstützung für Vorschau, Bilderfassung und Bildanalyse

Sie sollten die Erweiterung sowohl auf die Vorschau anwenden als auch Anwendungsfälle erfassen. Ist die Latenz jedoch zu hoch, um die Vorschau reibungslos anzuzeigen, können Sie die Erweiterung nur für Standaufnahmen anwenden.

Unabhängig davon, ob die Erweiterung für die Vorschau aktiviert ist, müssen Sie sowohl ImageCaptureExtenderImpl als auch PreviewExtenderImpl implementieren für eine bestimmte Erweiterung. Häufig verwendet eine App auch einen YUV-Stream, um den Messwert Bildinhalte wie QR-Codes oder Text zu finden Um diesen Anwendungsfall besser zu unterstützen, , sollten Sie die Stream-Kombination aus Vorschau, Standbildaufnahme und YUV_420_888-Stream zum Konfigurieren von CameraCaptureSession. Das bedeutet, einen Prozessor implementieren, den Stream zu unterstützen, Kombination aus drei YUV_420_888-Streams.

Bei Advanced Extender übergibt Camera2/X drei Ausgabeflächen an den SessionProcessorImpl.initSession() Anruf. Diese Ausgabeoberflächen sind für die Vorschau bestimmt , Standbildaufnahme und Bildanalyse. Sie müssen sicherstellen, dass die Vorschau und trotzdem die Ausgabeoberflächen die gültige Ausgabe anzeigen. Für das Bild analysieren und sicherstellen, dass sie nur funktioniert, wenn sie nicht null ist. Wenn Ihr Implementierung den Bildanalyse-Stream nicht unterstützen kann, können Sie ein leeres Liste auf AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions(). Dieses stellt sicher, dass die Ausgabeoberfläche der Bildanalyse in SessionProcessorImpl.initSession()

Hinweis :Die Erweiterung muss nicht auf die Bildanalyse angewendet werden. . Außerdem können mit der Camera2 Extensions API nur zwei Oberflächen: Vorschau anzeigen und immer noch aufnehmen.

Supportvideoaufnahme

Die aktuelle Architektur der Kameraerweiterung unterstützt nur die Vorschau und trotzdem Anwendungsfälle zu erfassen. Das Aktivieren der Erweiterung auf der MediaCodec wird nicht unterstützt oder MediaRecorder Oberflächen zum Aufnehmen des Videos. Es ist jedoch möglich, damit Apps die Vorschauausgabe aufzeichnen können.

Die Unterstützung von MediaCodec- und MediaRecorder-Oberflächen wird derzeit geprüft.

Erweiterungsspezifische Metadaten

Erweiterungsspezifische Metadaten für Android 14 und höher Ermöglicht es Kunden mit Kameraerweiterung, erweiterungsspezifische Aufnahmen einzurichten und zu empfangen Einstellungen und Ergebnisse für Anfragen. Insbesondere die Kameraerweiterung Clients können den Anfrageparameter EXTENSION_STRENGTH zur Erfassung von Daten verwenden, die Erweiterungsstärke und das EXTENSION_CURRENT_TYPE-Erfassungsergebnis, geben Sie den aktivierten Erweiterungstyp an.

Anfragen erfassen

Die EXTENSION_STRENGTH Anforderungsparameter erfassen steuert die Stärke des Nachbearbeitungseffekts der Erweiterung. Die entsprechenden Das Erfassungsergebnis enthält den Standardwert für die Stärke, wenn dieser Parameter nicht festgelegt ist explizit durch die Kundschaft. Dieser Parameter kann auf folgende Arten angewendet werden: Erweiterungstypen:

• BOKEH: Steuert das Ausmaß der Unschärfe.
• HDR und NIGHT: Steuert die Menge an verschmelzten Bildern und die Helligkeit der das endgültige Bild.
• FACE_RETOUCH: Steuert den Grad der kosmetischen Verbesserung und der Haut. Glättung.

Der unterstützte Bereich für den Parameter EXTENSION_STRENGTH liegt zwischen 0 und 100, wobei 0 angibt, dass keine Erweiterungsverarbeitung oder einfaches Passthrough erfolgt. 100 gibt die maximale Erweiterungsstärke des Verarbeitungseffekts an.

Wenn Sie EXTENSION_STRENGTH unterstützen möchten, verwenden Sie den Anbieter APIs für spezifische Parameter, die in Version 1.3.0 der Erweiterungsbibliothek eingeführt wurden . Weitere Informationen finden Sie unter getAvailableCaptureRequestKeys()

Ergebnisse erfassen

Die EXTENSION_CURRENT_TYPE Mit dem Erfassen des Ergebnisses können die Implementierungen von Erweiterungen Kunden über die aktiven Erweiterungstyp.

Weil Erweiterungen mit dem Typ AUTO dynamisch zwischen Erweiterungen wechseln wie HDR und NIGHT, je nach Umgebungsbedingungen, Erweiterungen, die Apps EXTENSION_CURRENT_TYPE verwenden können, um Informationen über Die aktuell von der Erweiterung „AUTO“ ausgewählte Erweiterung.

Latenzschätzung dennoch in Echtzeit erfassen

Kamera-Erweiterungs-Clients für Android 14 und höher in Echtzeit abfragen und trotzdem Latenzschätzungen anhand der Szene und die Umgebungsbedingungen mithilfe von getRealtimeStillCaptureLatency() Dieses genauere Schätzungen als die statische Methode, getEstimatedCaptureLatencyRangeMillis() . Basierend auf der Latenzschätzung können Apps entscheiden, ob die Erweiterung übersprungen werden soll oder die Anzeige eines Hinweises zur Benachrichtigung der Nutzer ausgeführt wird.

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 weiterhin Latenzschätzungen in Echtzeit zu erfassen, implementieren Sie Folgendes:

• Einfache Erweiterungen: ImageCaptureExtenderImpl.getRealtimeCaptureLatency()
• Erweiterte Erweiterungen: SessionProcessorImpl.getRealtimeCaptureLatency

Callbacks für den Aufnahmefortschritt

Kamera-Erweiterungs-Clients für Android 14 und höher kann Rückrufe für den Fortschritt einer lange laufenden Erfassungsverarbeitung erhalten Geschäftsabläufe. Apps können Nutzern den aktuellen Fortschritt anzeigen, um die User Experience insgesamt.

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
    }
  }
…
}

Damit Callbacks für den Verarbeitungsfortschritt bei der Erfassung unterstützt werden, muss Ihr Erweiterungsanbieter Die Implementierung muss die folgenden Callbacks mit dem aktuellen Fortschritt aufrufen Wert:

• Einfache Erweiterungen: ProcessResultImpl.onCaptureProcessProgressed()
• Erweiterte Erweiterungen: CaptureCallback.onCaptureProcessProgressed()

Postview-Standbild erfassen

Ab Android 14 können Kameraerweiterungen Postview (Vorschaubild) mithilfe von setPostviewOutputConfiguration Zur Verbesserung der Nutzererfahrung können Apps ein Postview-Bild als wenn eine Erweiterung eine erhöhte Verarbeitungslatenz aufweist. und ersetzen Sie das Bild, wenn das fertige Bild verfügbar ist. Apps können konfigurieren und Postview-Erfassungsanfragen mit dem folgenden Referenzcode senden:

{
…
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();
…
}

Damit die Postview-Erfassung weiterhin unterstützt wird, muss in Ihrer Anbieterimplementierung die Methode Folgendes:

• Einfache Erweiterungen: CaptureProcessorImpl.onPostviewOutputSurface und CaptureProcessorImpl.processWithPostview

• Erweiterte Erweiterungen: SessionProcessorImpl.startCaptureWithPostview

SurfaceView-Ausgabe

Kamera-Erweiterungs-Clients für Android 14 und höher können leistungs- und leistungsoptimierte Vorschau-Renderingpfade nutzen, indem ein SurfaceView Instanz für die Vorschauausgabe für wiederkehrende Anfragen.

Damit die Ausgabe von SurfaceView unterstützt wird, muss die Implementierung der Anbietererweiterung so aussehen: in der Lage, Streaming und Vorschau an SurfaceView Instanzen auszugeben. Bis Prüfen Sie, ob dies unterstützt wird, führen Sie den SurfaceViewExtensionPreviewTest.java aus. CTS-Modul.

Anbieterspezifische Sitzungstypen

Mit dieser Funktion kann bei Implementierungen der Anbietererweiterung ein anbieterspezifischer Sitzungstyp ausgewählt werden, der bei der Aufnahme mit der internen Kamera statt des Standardwerts festgelegt wird.

Die Funktion ist vollständig innerhalb des Frameworks und Anbieter-Stacks integriert und hat keine vom Client oder der Öffentlichkeit sichtbaren API-Auswirkungen.

Implementieren Sie Folgendes für Ihre Erweiterungsbibliotheken, um einen anbieterspezifischen Sitzungstyp auszuwählen: * ExtenderStateListener.onSessionType() für einfache Erweiterungen * Camera2SessionConfigImpl.getSessionType() für erweiterte Erweiterungen

Versionsverlauf der Benutzeroberfläche für Erweiterungen

Die folgende Tabelle zeigt den Versionsverlauf der Benutzeroberfläche der Kameraerweiterung. Ich Die Anbieterbibliothek sollte immer mit der neuesten Version implementiert werden.

Version	Zusätzliche Funktionen
1.0.0	Versionsüberprüfung <ph type="x-smartling-placeholder"> </ph> ExtensionVersionImpl Basic Extender <ph type="x-smartling-placeholder"> </ph> PreviewExtenderImpl ImageCaptureExtenderImpl Processor PreviewImageProcessorImpl CaptureProcessorImpl RequestUpdateProcessorImpl
1.1.0	Initialisierung der Bibliothek <ph type="x-smartling-placeholder"> </ph> InitializerImpl Unterstützte Auflösungen anzeigen <ph type="x-smartling-placeholder"> </ph> PreviewExtenderImpl.getSupportedResolutions ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0	AdvancedExtender AdvancedExtenderImpl SessionProcessorImpl Geschätzte Aufnahmelatenz abrufen ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0	Unterstützte Anfrageschlüssel/Ergebnisschlüssel für die Aufnahme bereitstellen ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys und getAvailableCaptureResultKeys AdvancedExtenderImpl.getAvailableCaptureRequestKeys und getAvailableCaptureResultKeys Neuer process()-Anruf, der ProcessResultImpl in PreviewImageProcessorImpl und CaptureProcessorImpl dauert Anfrage des Support-Triggertyps AdvancedExtenderImpl.startTrigger
1.4.0	Erweiterungsspezifische Metadaten Dynamisch erfassen weiterhin Latenzschätzungen Callbacks für den Aufnahmefortschritt Postview-Standbild erfassen Unterstützung für SurfaceView-Ausgabe Anbieterspezifische Sitzungstypen

Referenzimplementierung

Die folgenden Referenzimplementierungen für OEM-Anbieterbibliotheken sind verfügbar in frameworks/ex

• advancedSample: Eine einfache Implementierung des Advanced Extenders.

• sample: Eine einfache Implementierung des Basic Extenders.

• service_based_sample: Eine Implementierung, die zeigt, wie das Hosten Kameraerweiterungen in einem Service Diese Implementierung enthält die folgenden Komponenten:

  • oem_library: Eine Kamera-Erweiterungs-OEM-Bibliothek für Camera2- und CameraX-Erweiterungs-APIs das Extensions-Interface implementiert. Dies dient als Passthrough, leitet Anrufe von Extensions-Interface an den Dienst weiter. Diese Bibliothek bietet auch AIDL-Dateien und Wrapper-Klassen für die Kommunikation mit dem Service.

    Advanced Extender ist standardmäßig aktiviert. So aktivierst du den Basic Extender: ExtensionsVersionImpl#isAdvancedExtenderImplemented ändern, um zurückzukehren false.

  • extensions_service: Eine Beispielimplementierung des Erweiterungsdienstes. Implementierung hinzufügen hier. Die im Dienst zu implementierende Schnittstelle ist ähnlich zu Extensions-Interface. Zum Beispiel ist die Implementierung der IAdvancedExtenderImpl.Stub führt dieselben Vorgänge aus wie AdvancedExtenderImpl. ImageWrapper und TotalCaptureResultWrapper sind erforderlich, um Image und TotalCaptureResult parzellell zu machen.

Anbieterbibliothek auf einem Gerät einrichten

Die OEM-Anbieterbibliothek ist nicht in eine App integriert. es wird vom Gerät geladen zur Laufzeit von Camera2/X. In CameraX deklariert das Tag <uses-library> dass die androidx.camera.extensions.impl-Bibliothek, die im AndroidManifest.xml der camera-extensions-Bibliothek ist eine Abhängigkeit von CameraX und muss zur Laufzeit geladen werden. In Camera2 lädt das Framework einen Erweiterungsdienst, deklariert außerdem, dass <uses-library> androidx.camera.extensions.impl während der Laufzeit.

Dadurch können Drittanbieter-Apps, die Erweiterungen verwenden, den OEM automatisch laden. Lieferantenbibliothek. Die OEM-Bibliothek ist als optional gekennzeichnet, damit Apps auf Geräten ausgeführt werden können. die die Bibliothek nicht auf dem Gerät haben. Camera2/X verarbeitet dieses Verhalten automatisch, wenn eine App versucht, eine Kamera zu verwenden. solange der Gerätehersteller die OEM-Bibliothek damit sie von der App gefunden werden kann.

So richten Sie die OEM-Bibliothek auf einem Gerät ein:

1. Fügen Sie eine Berechtigungsdatei hinzu, die für das <uses-library>-Tag erforderlich ist. im folgenden Format: /etc/permissions/ANY_FILENAME.xml. Für Beispiel: /etc/permissions/camera_extensions.xml. Die Dateien in diesem eine Zuordnung der in <uses-library> genannten Bibliothek zur Dateipfad auf dem Gerät.

2. Verwenden Sie das Beispiel unten, um der Datei die erforderlichen Informationen hinzuzufügen.

   • „name“ muss androidx.camera.extensions.impl sein. Das ist Bibliothek, nach der CameraX sucht.
   • file ist der absolute Pfad der Datei, die den Implementierung von Erweiterungen (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>
   

Geräte mit Android 12 oder höher, die CameraX unterstützen Für Erweiterungen muss die Property ro.camerax.extensions.enabled auf true festgelegt sein. mit der Sie abfragen können, ob ein Gerät Erweiterungen unterstützt. Fügen Sie dazu die folgende Zeile in die Datei für die Gerätemarke ein:

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

Zertifizierungsstufe

Um Ihre Implementierung der OEM-Anbieterbibliothek während der Entwicklungsphase, verwenden Sie die Beispiel-App unter androidx-main/camera/integration-tests/extensionstestapp/, die verschiedene Anbietererweiterungen umfasst.

Nachdem Sie die Implementierung abgeschlossen haben, verwenden Sie die Methode Validierungstool für Kameraerweiterungen mit automatischen und manuellen Tests überprüfen, ob die Anbieterbibliothek korrekt implementiert wurde.

Erweiterter Szenenmodus im Vergleich zu Kameraerweiterungen

Bei der Bokeh-Erweiterung können Sie können Sie die Erweiterung im erweiterten Szenenmodus einblenden, der über die CONTROL_EXTENDED_SCENE_MODE . Weitere Informationen zur Implementierung finden Sie unter Kamera-Bokeh.

Der erweiterte Szenenmodus weist im Vergleich zu Kameraerweiterungen weniger Einschränkungen auf Kamera2-Apps. Sie können beispielsweise den erweiterten Szenenmodus eine reguläre CameraCaptureSession-Instanz, die einen flexiblen Stream unterstützt und Anfrageparameter erfassen. Kameraerweiterungen hingegen nur eine feste Anzahl von Streamtypen und nur begrenzte Unterstützung für die Anforderungsparameter.

Ein Nachteil des erweiterten Szenenmodus ist, dass Sie ihn nur in der Kamera-HAL. Das bedeutet, dass überprüft werden muss, dass sie auf allen orthogonale Steuerelemente für App-Entwickler.

Wir empfehlen, Bokeh-Effekte sowohl im erweiterten Szenenmodus als auch mit der Kamera aufzunehmen. Erweiterungen, da Apps möglicherweise eine bestimmte API bevorzugen, um Bokeh zu aktivieren. Wir empfehlen, zuerst den erweiterten Szenenmodus zu verwenden, da dies können Apps die Bokeh-Erweiterung flexibel aktivieren. Dann können Sie die auf der Oberfläche von Kameraerweiterungen basierend auf dem erweiterten Szenenmodus. Bei der Implementierung Bokeh in der Kamera-HAL ist schwierig, z. B. weil dafür ein Pfosten erforderlich ist. auf der App-Ebene ausgeführt wird, um Bilder zu verarbeiten, Bokeh-Erweiterung in der Benutzeroberfläche der Kameraerweiterungen an.

Häufig gestellte Fragen

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

Ja. Dies hängt vom Android API-Funktionssatz ab, der vom OEM gefordert wird. Implementierung der Vendor Library. Beispiel: ExtenderStateListener.onPresetSession() verwendet die SessionConfiguration.setSessionParameters() -Aufruf zum Festlegen eines Basissatzes von Tags. Dieser Aufruf ist nur auf API-Ebene verfügbar 28 und höher. Weitere Informationen zu bestimmten Oberflächenmethoden finden Sie in der API-Referenzdokumentation