Rozszerzenia do aparatu

Producenci urządzeń mogą udostępniać rozszerzenia, takie jak bokeh, tryb nocny czy HDR firmom zewnętrznym za pomocą interfejsu rozszerzenia aparatu oferowanego przez w bibliotece dostawcy OEM. Programiści mogą używać Interfejs Camera2 Extensions API oraz CameraX Extensions API rozszerzenia zaimplementowane w bibliotece dostawcy OEM.

Listę obsługiwanych rozszerzeń, która jest taka sama w Aparacie 2 i AparatX, zobacz Interfejs CameraX Extensions API. Jeśli chcesz dodać rozszerzenie, zgłoś błąd w Issue Tracker.

Na tej stronie dowiesz się, jak wdrożyć i włączyć bibliotekę dostawcy OEM w urządzenia.

Architektura

Poniższy schemat przedstawia architekturę rozszerzeń do aparatu lub extensions-interface: Architektura

Rysunek 1. Schemat architektury rozszerzeń aparatu

Jak pokazano na schemacie, aby korzystać z rozszerzeń do aparatu, musisz: zaimplementuj kod extensions-interface udostępniony przez bibliotekę dostawcy OEM. Twoje Biblioteka dostawcy OEM włącza 2 interfejsy API: CameraX Extensions API i Interfejs Camera2 Extensions API które są używane odpowiednio przez aplikacje AparatX i Aparat2. z rozszerzeniami dostawców.

Wdróż bibliotekę dostawcy OEM

Aby wdrożyć bibliotekę dostawcy OEM, skopiuj camera-extensions-stub do projektu biblioteki systemowej. Te pliki definiują rozszerzenia aparatu za pomocą prostego interfejsu online.

camera-extensions-stub pliki są podzielone na następujące kategorie:

Niezbędne pliki interfejsu (nie zmieniaj)

  • 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

Obowiązkowe implementacje (dodaj swoją implementację)

  • ExtensionVersionImpl.java
  • InitializerImpl.java

Klasy rozszerzenia bokeh (implementacja, jeśli obsługiwane jest rozszerzenie Bokeh)

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

Zajęcia wydłużające noc (wprowadź je, jeśli obsługiwane jest rozszerzenie nocne)

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

Klasy z automatycznym rozszerzeniem (zaimplementuj je, jeśli obsługiwane jest automatyczne rozszerzenie)

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

Klasy przedłużania HDR (wprowadź je, jeśli obsługiwane jest rozszerzenie HDR)

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

Klasy rozszerzenia do retuszu twarzy (implementuj je, jeśli obsługiwane jest rozszerzenie do retuszu twarzy)

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

Narzędzia (opcjonalnie, można je usunąć)

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

Nie musisz udostępniać implementacji w przypadku każdego rozszerzenia. Jeśli nie implementuj rozszerzenia, ustaw isExtensionAvailable() tak, aby zwracał false lub usuń odpowiednie klasy Extender. Rozszerzenia Camera2 i CameraX Interfejsy API zgłaszają aplikacji, że rozszerzenie jest niedostępne.

Omówmy teraz, jak interfejsy API rozszerzeń Camera2 i CameraX współdziałają z biblioteki dostawcy, aby włączyć rozszerzenie. Poniższy diagram przedstawia możesz przeprowadzić cały proces, korzystając z przykładu rozszerzenia Night:

Mainflow

Rysunek 2. Implementacja rozszerzenia nocnego

  1. Weryfikacja wersji:

    Kamera2/X wywołuje ExtensionVersionImpl.checkApiVersion(), by upewnić się, że Wdrożona przez OEM wersja extensions-interface jest zgodna z Aparatem 2/X obsługiwanych wersji.

  2. Inicjowanie biblioteki dostawcy:

    InitializerImpl ma metodę init(), która inicjuje bibliotekę dostawcy. Camera2/X kończy proces inicjowania przed uzyskaniem dostępu do klas Extender.

  3. Klasy instancji Extender:

    Tworzy instancje klas Extender dla rozszerzenia. Dostępne są dwa Basic Extender i Advanced Extender. Musisz zaimplementować jeden Typ rozszerzenia dla wszystkich rozszerzeń. Więcej informacji: Podstawowy i zaawansowany Extender.

    Camera2/X tworzy instancję klas Extender i wchodzi z nimi w interakcję, aby pobrać dane i włączyć rozszerzenie. Dla danego rozszerzenia Aparat2/X może wiele razy utworzyć instancję klas Extender. Dlatego nie rób inicjalizację dużego obciążenia w konstruktorze lub wywołaniu init(). Wykonaj podnoszenie ciężarów tylko wtedy, gdy sesja kamery zbliża się do start, na przykład po wywołaniu funkcji onInit() w rozszerzeniu Basic Extender lub Funkcja initSession() jest wywoływana w rozszerzeniu zaawansowanym.

    W przypadku rozszerzenia Night tworzone są następujące klasy Extender dla typu Basic Extender:

    • NightImageCaptureExtenderImpl.java
    • NightPreviewExtenderImpl.java

    W przypadku typu Advanced Extender:

    • NightAdvancedExtenderImpl.java

  4. Sprawdź dostępność rozszerzeń:

    Przed włączeniem rozszerzenia isExtensionAvailable() sprawdza, czy rozszerzenie jest dostępne dla podanego identyfikatora kamery przez rozszerzenie instancji.

  5. Zainicjuj Extender, podając informacje o kamerze:

    Kamera2/X wywołuje init() w instancji Extender i przekazuje ją do kamery Identyfikator i CameraCharacteristics.

  6. Informacje o zapytaniu:

    Wywołuje klasę Extender w celu pobrania informacji takich jak obsługiwane rozdzielczości, nadal przechwytywać szacowany czas oczekiwania oraz przechwytywać klucze żądania w ramach przygotowań do włączenia rozszerzenia.

  7. Włącz rozszerzenie na urządzeniu Extender:

    Klasa Extender zawiera wszystkie interfejsy potrzebne do włączenia zajęcia. Oferuje mechanizm umożliwiający przyciąganie uwagi OEM implementacja w potoku Camera2, na przykład wstrzykiwanie żądania zapisu lub włączyć post CPU.

    W przypadku zaawansowanego przedłużeniaera Aparat2/X współdziała z SessionProcessorImpl, aby włączyć rozszerzenie. Aparat2/X pobiera SessionProcessorImpl instancję, wywołując createSessionProcessor() w Przedłużenie platformy.

W kolejnych sekcjach szczegółowo opisano proces dodawania rozszerzeń.

Weryfikacja wersji

Podczas wczytywania biblioteki dostawcy OEM z urządzenia w czasie działania aplikacja Camera2/X sprawdza, czy biblioteka jest zgodna z wersją extensions-interface. extensions-interface używa semantycznej obsługi wersji lub GŁÓWNA.PODRZĘDNA.POPRAWKA, na przykład 1.1.0 lub 1.2.0. Pamiętaj jednak, że tylko wersji głównej i podrzędnej.

Aby zweryfikować wersję, aplikacja Camera2/X wywołuje ExtensionVersionImpl.checkApiVersion() z obsługiwaną Wersja extensions-interface. Aparat2/X używa wersji zgłoszonej przez bibliotekę OEM określającą, czy rozszerzenie można włączyć i jakie funkcje który ma zostać wywołany.

Zgodność wersji głównej

Jeśli główne wersje interfejsu rozszerzenia są różne Camera2/X i biblioteki dostawcy, jest uznawany za niezgodny i gdy rozszerzenie jest wyłączone.

Zgodność wsteczna

Jeśli wersja główna jest taka sama, Aparat2/X zapewnia zgodność wsteczną z bibliotekami dostawcy OEM utworzonymi z wcześniejszymi extensions-interface wersji. Jeśli na przykład Aparat2/X obsługuje extensions-interface 1.3.0, biblioteki dostawcy OEM, które wdrożyły wersję 1.0.0, Wersje 1.1.0 i 1.2.0 są nadal zgodne. Oznacza to również, że po wdrożeniu określonych wersji biblioteki dostawcy, Camera2/X zapewnia jest zgodny wstecznie z nadchodzącymi wersjami extension-interface.

Zgodność z wyprzedzeniem

Większą zgodność z bibliotekami dostawców w nowszej wersji extensions-interface zależy od Ciebie, producenta OEM. Jeśli do wdrożenia rozszerzeń są potrzebne funkcje, możesz włączyć rozszerzenia, zaczynając od określonej wersji. W tym możesz zwrócić obsługiwaną wersję extensions-interface, gdy Biblioteka Camera2/X spełnia wymagania. W przypadku wersji Camera2/X nie są obsługiwane, możesz zwrócić niezgodną wersję, np. 99.0.0, wyłączyć rozszerzenia.

Inicjowanie biblioteki dostawcy

Po sprawdzeniu wersji extensions-interface wdrożonej przez OEM , Camera2/X rozpocznie proces inicjowania. InitializerImpl.init() wysyła do biblioteki OEM sygnały, że aplikacja próbuje na korzystanie z rozszerzeń.

Camera2/X nie wywołuje żadnych innych wywołań do biblioteki OEM (oprócz sprawdzania wersji). dopóki biblioteka dostawcy OEM nie wywoła funkcji OnExtensionsInitializedCallback.onSuccess() , aby powiadamiać o zakończeniu inicjowania.

Musisz zaimplementować InitializerImpl na dzień extensions-interface 1.1.0. Aparat2/X pomija inicjowanie biblioteki jeśli biblioteka dostawcy OEM wdrożyła extensions-interface 1.0.0.

przedłużenie podstawowe i zaawansowane

Są 2 typy implementacji extensions-interface: Basic Extender i Advanced Extender. Rozszerzenie Advanced Extender jest obsługiwane od extensions-interface 1.2.0.

Zaimplementuj rozszerzenie Basic Extender dla rozszerzeń, które przetwarzają obrazy w HAL aparatu lub korzystamy z procesora pocztowego, który potrafi przetwarzać strumienie YUV.

Zaimplementuj rozszerzenie Advanced Extender dla rozszerzeń, które chcą dostosować Aparat 2 strumieniowania i wysyłania żądań przechwytywania.

W tej tabeli znajdziesz porównanie:

Przedłużacz podstawowy Przedłużacz zaawansowany
Konfiguracje strumienia Naprawiony
Podgląd: PRIVATE lub YUV_420_888 (jeśli istnieje procesor)
Nadal przechwytywane: JPEG lub YUV_420_888 (jeśli procesor jest dostępny) 		Możliwość dostosowania przez OEM.
Wysyłam prośbę o nagranie Żądania przechwytywania mogą wysyłać tylko aparaty Camera2/X. Możesz ustawić następujące parametry: tych żądań. Jeśli do robienia zdjęć jest dołączony procesor, Aparat2/X wysyłać wiele żądań przechwytywania i wysyłać wszystkie do procesora. Instancja RequestProcessorImpl jest udostępniana do przez wykonanie żądania przechwytywania Camera2 w celu uzyskania wyników i obrazu.

Aparat2/X wywołuje funkcje startRepeating i startCapture SessionProcessorImpl, aby zasygnalizować producentowi OEM, że powinien rozpocząć procedurę cykliczną. żądania wyświetlenia podglądu i rozpoczęcie sekwencji nieruchomego rejestrowania.

Blokady w ruchu kamery
  • onPresetSession udostępnia parametry sesji.
  • onEnableSession wysyła jedno żądanie tuż po skonfigurowaniu usługi CameraCaptureSession.
  • onDisableSession wysyła jedno żądanie przed zamknięciem usługi CameraCaptureSession.
  • initSession inicjuje i zwraca dostosowaną aparat 2 do utworzenia sesji przechwytywania.
  • Funkcja onCaptureSessionStart jest wywoływana zaraz po skonfigurowaniu metody CameraCaptureSession.
  • Funkcja onCaptureSessionEnd jest wywoływana przed zamknięciem elementu CameraCaptureSession.
Odpowiednie dla Rozszerzenia zaimplementowane w HAL aparatu lub w procesorze, który przetwarza Zdjęcia YUV.
  • Implementacje rozszerzeń oparte na kamerze Camera2.
  • Wymaga niestandardowej konfiguracji strumienia, np. strumienia RAW.
  • Wymaga interaktywnej sekwencji przechwytywania.
Obsługiwana wersja interfejsu API Rozszerzenia Camera2: Android 13 lub nowszy
Rozszerzenia CameraX: camera-extensions w wersji 1.1.0 lub nowszej		 Rozszerzenia Camera2: Android 12L lub nowszy
Rozszerzenia CameraX: camera-extensions w wersji 1.2.0-alfa03 lub nowszej

Przepływy aplikacji

W tabeli poniżej znajdziesz 3 typy przepływów w aplikacji i ich odpowiednie wywołania interfejsu Camera Extensions API. Aparaty 2/X tych interfejsów API, należy poprawnie wdrożyć bibliotekę dostawcy, aby je obsługiwała procesach, które omówimy bardziej szczegółowo w dalszej sekcji.

Rozszerzenia Camera2 Rozszerzenia CameraX
Dostępność rozszerzeń zapytań CameraExtensionCharacteristics .getSupportedExtensions ExtensionsManager. isExtensionAvailable
Informacje o zapytaniu CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys ExtensionsManager. getEstimatedCaptureLatencyRange

Aparat X obsługuje resztę informacji z biblioteki.

Podgląd i rejestrowanie bez przerwy z włączonym rozszerzeniem CameraDevice. createExtensionSession

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector

bindToLifecycle(lifecycleOwner, cameraSelector, preview, ...)

Przedłużacz podstawowy

Interfejs Basic Extender umożliwia zaczepienie kamery w kilku miejscach potoku. Każdy typ rozszerzenia ma odpowiednie klasy Extender wymagane przez OEM do wdrożenia.

W tabeli poniżej znajdziesz klasy urządzeń przedłużających, które firmy OEM muszą wdrożyć w przypadku każdego z nich rozszerzenie:

Rozszerzaj klasy do wdrożenia
Noc NightPreviewExtenderImpl.java

NightImageCaptureExtenderImpl.java

HDR. HdrPreviewExtenderImpl.java

HdrImageCaptureExtenderImpl.java

Auto AutoPreviewExtenderImpl.java

AutoImageCaptureExtenderImpl.java

Bokeh BokehPreviewExtenderImpl.java

BokehImageCaptureExtenderImpl.java

Retusz twarzy BeautyPreviewExtenderImpl.java

BeautyImageCaptureExtenderImpl.java

Używamy PreviewExtenderImpl i ImageCaptureExtenderImpl jako obiektów zastępczych w poniższym przykładzie. Zastąp je nazwami odpowiednich obiektów we wdrażanych plikach.

Basic Extender ma te możliwości:

  • Wstawiaj parametry sesji podczas konfigurowania CameraCaptureSession ( onPresetSession).
  • Powiadamia o zdarzeniach rozpoczęcia i zakończenia sesji przechwytywania i wysyła żądanie powiadomienia HAL o zwróconych parametrach (onEnableSession, onDisableSession).
  • Wstrzyknij parametry przechwytywania dla żądania (PreviewExtenderImpl.getCaptureStage, ImageCaptureExtenderImpl.getCaptureStages).
  • Dodaj procesory, aby wyświetlić podgląd i nadal przechwytywać, które są w stanie przetworzyć Strumień YUV_420_888.

Zobaczmy, jak Aparat2/X wywołuje funkcję extensions-interface, aby uzyskać trzy. procesów aplikacji wymienionych powyżej.

Przepływ aplikacji 1. Sprawdź dostępność rozszerzenia

BasicExtenderAppFlow1

Rysunek 3. Krok 1 w aplikacji na urządzeniu Basic Extender

W tym przykładzie Aparat2/X wywołuje bezpośrednio metodę isExtensionAvailable() zarówno PreviewExtenderImpl, jak i ImageCaptureExtenderImpl bez połączenia init() Aby można było włączyć rozszerzenia, obie klasy Extender muszą zwracać wartość true.

Często jest to pierwszy etap sprawdzania przez aplikacje, czy dane rozszerzenie jest obsługiwany dla danego identyfikatora kamery przed włączeniem rozszerzenia. Dzieje się tak, ponieważ niektóre rozszerzenia są obsługiwane tylko w przypadku określonych identyfikatorów aparatów.

Przepływ aplikacji 2. Zapytanie o informacje

BasicExtenderAppFlow2

Rysunek 4. Krok 2 w aplikacji na urządzeniu Basic Extender

Po określeniu, czy rozszerzenie jest dostępne, aplikacje powinny wysłać zapytanie z poniższymi informacjami.

  • Zakres opóźnienia rejestrowania: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange zwraca zakres oraz opóźnienia w zapisie, po których aplikacja może ocenić, czy włączyć rozszerzenie na obecną sytuację.

  • Obsługiwane rozmiary platformy do podglądu i rejestrowania: ImageCaptureExtenderImpl.getSupportedResolutions i PreviewExtenderImpl.getSupportedResolutions zwraca listę formatów obrazu, a obsługiwane rozmiary i format powierzchni.

  • Obsługiwane klucze żądania i wyników: Camera2/X wywołuje następujące metody, aby pobrać obsługiwane przechwytywanie żądania kluczy i kluczy wyników w ramach implementacji:

    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
    • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Kamera2/X zawsze najpierw wywołuje funkcję init() w tych klasach Extender przed wysłaniem zapytania .

Proces w aplikacji 3: podgląd/zdjęcie nadal z włączonym rozszerzeniem (implementacja HAL)

BasicExtenderAppFlow3

Rysunek 5. Krok 3 w aplikacji na urządzeniu Basic Extender

Schemat powyżej ilustruje główny proces włączania podglądu za pomocą rozszerzenia bez procesora. Oznacza to, że kod HAL aparatu przetworzy rozszerzenie.

W ramach tej procedury Kamera 2/X najpierw wywołuje metodę init(), a potem onInit, co powiadamia Cię że sesja kamery ma się rozpocząć z wybranymi rozszerzeniami. Inicjalizację intensywną użytkowania można wykonać w programie onInit().

Podczas konfigurowania funkcji CameraCaptureSession aparat 2/X wywołuje onPresetSession, aby pobrać parametry sesji. Po zakończeniu sesji nagrywania została skonfigurowana, Aparat2/X wywołuje funkcję onEnableSession, która zwraca CaptureStageImpl instancji zawierającej parametry przechwytywania. Aparat 2/X natychmiast wysyła jedno żądanie z tymi parametrami przechwytywania, aby powiadomić HAL. I analogicznie, przed zamknięciem sesji przechwytywania aparat 2/X wywołuje onDisableSession, a następnie wysyła jedno żądanie ze zwróconym zapisem .

Powtarzające się żądanie uruchomione przez Aparat 2/X zawiera parametry żądania zwrócone przez PreviewExtenderImpl.getCaptureStage(). Ponadto, zawiera parametry zwrócone przez ImageCaptureExtenderImpl.getCaptureStages()

Na koniec Aparat2/X wywołuje funkcję onDeInit() po zakończeniu sesji. Możesz zwolnić zasoby w onDeinit().

Podgląd procesora

Oprócz HAL aparatu możesz też zaimplementować rozszerzenia w procesorze.

Zaimplementuj PreviewExtenderImpl.getProcessorType, aby określić typ procesora jak opisano poniżej:

  • PROCESSOR_TYPE_NONE: brak podmiotu przetwarzającego. Zdjęcia są przetwarzane w aparacie HAL.

  • PROCESSOR_TYPE_REQUEST_UPDATE_ONLY: typ procesora umożliwia zaktualizować cykliczne żądanie o nowe parametry żądania przechwytywania na podstawie parametru najnowszy TotalCaptureResult.

    PreviewExtenderImpl.getProcessor musi zwrócić błąd RequestUpdateProcessorImpl instancję, która przetwarza instancję TotalCaptureResult i zwraca CaptureStageImpl instancji, aby zaktualizować powtarzające się żądanie. PreviewExtenderImpl.getCaptureStage() powinien również odzwierciedlać wynik funkcji przetwarza dane i zwraca najnowsze dane (CaptureStageImpl).

  • PROCESSOR_TYPE_IMAGE_PROCESSOR: ten typ pozwala zaimplementować komponent procesora do przetworzenia YUV_420_888 obrazów i zapisania danych wyjściowych w PRIVATE.

    Musisz zaimplementować i zwrócić PreviewImageProcessorImpl w instancji PreviewExtenderImpl.getProcessor. Podmiot przetwarzający odpowiada do przetwarzania YUV_420_888 obrazów wejściowych. Powinien zapisać dane wyjściowe w funkcji Format podglądu PRIVATE. Aparat2/X używa powierzchni YUV_420_888 PRIVATE, aby skonfigurować CameraCaptureSession na potrzeby podglądu.

    Ilustracja procesu obsługi:

Podgląd procesora

Rysunek 6. Wyświetl podgląd procesu z usługą PreviewImageProcessorImpl

Interfejs PreviewImageProcessorImpl rozszerza ProcessImpl i ma 3 ważne metody:

  • onOutputSurface(Surface surface, int imageFormat) ustawia powierzchnię wyjściową za procesor. W aplikacji PreviewImageProcessorImpl imageFormat to piksel taki jak PixelFormat.RGBA_8888.

  • onResolutionUpdate(Size size) ustawia rozmiar obrazu wejściowego.

  • onImageFormatUpdate(int imageFormat) ustawia format obrazu danych wejściowych . Obecnie może to być tylko YUV_420_888.

Procesor przechwytywania obrazu

W przypadku przechwytywania możesz wdrożyć procesor, zwracając klucz CaptureProcessorImpl w instancji za pomocą ImageCaptureExtenderImpl.getCaptureProcessor. Procesor jest odpowiedzialny za przetworzenie listy YUV_420_888 zrobionych zdjęć oraz TotalCaptureResult instancji i zapisz dane wyjściowe na platformie YUV_420_888.

Możesz bez obaw przyjąć, że podgląd jest włączony i uruchomiony, przed wysłaniem nadal przechwytywać.

Zobacz ten schemat:

Procesor przechwytywania

Rysunek 7. Nadal rejestruj przepływ dzięki aplikacji CaptureProcessorImpl

  1. Aparat 2/X do konfiguracji używa platformy formatu YUV_420_888 do robienia zdjęć w sesji przechwytywania. Camera2/X przygotowuje urządzenie CaptureProcessorImpl, dzwoniąc pod numer:

    • CaptureProcessorImpl.onImageFormatUpdate() z: YUV_420_888.
    • CaptureProcessorImpl.onResolutionUpdate() z rozmiarem obrazu wejściowego.
    • CaptureProcessorImpl.onOutputSurface() z wynikiem YUV_420_888 na różnych powierzchniach.

  2. ImageCaptureExtenderImpl.getCaptureStages zwraca listę CaptureStageImpl , gdzie każdy element jest mapowany na instancję CaptureRequest z parametrami przechwytywania wysyłane przez aparaty 2/X. Jeśli na przykład wyświetli się lista trzech instancji: CaptureStageImpl, Camera2/X wysyła 3 żądania przechwytywania: odpowiednich parametrów przechwytywania, korzystając z captureBurst API.

  3. Otrzymane obrazy i TotalCaptureResult instancji są grupowane w pakiet i przesłane do CaptureProcessorImpl w celu przetworzenia.

  4. CaptureProcessorImpl zapisuje wynikowy obraz (w formacie YUV_420_888) w powierzchnia wyjściowa określona przez wywołanie onOutputSurface(). Aparat Camera2/X konwertuje w plikach JPEG, jeśli to konieczne.

Obsługa kluczy i wyników żądania przechwytywania

Oprócz podglądu i nagrywania aparatu aplikacje mogą też ustawiać powiększenie, parametrów lampy błyskowej lub ustawić ostrość przez dotknięcie. Te parametry mogą nie być zgodne z Twoim wdrożeniem rozszerzenia.

Poniższe metody zostały dodane do extensions-interface w wersji 1.3.0, aby umożliwić ujawnianie parametrów, które obsługuje Twoja implementacja:

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() zwraca błąd przechwytywanie kluczy żądania obsługiwanych przez Twoją implementację.
  • ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() zwraca błąd przechwytywać klucze wyników zawarte w wyniku przechwytywania.

Jeśli HAL aparatu przetworzy rozszerzenie, Aparat2/X pobierze zapis daje wynik CameraCaptureSession.CaptureCallback. Jeśli jednak lub zaimplementowany jest procesor, a Aparat2/X pobierze wyniki przechwytywania ProcessResultImpl , która jest przekazywana do metody process() Metoda w PreviewImageProcessorImpl oraz CaptureProcessorImpl. Odpowiadasz za raportowanie za pomocą ProcessResultImpl do Aparatu2/X.

Zobacz poniżej przykładową definicję interfejsu CaptureProcessorImpl. W extensions-interface w wersji 1.3.0 lub nowszej wywoływane jest drugie wywołanie process():

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);
}

Na potrzeby typowych działań związanych z aparatem, takich jak zoom, ustawianie ostrości, lampa błyskowa i ekspozycja wynagrodzenia, zalecamy obsługę następujących klawiszy zarówno w przypadku przechwytywania, wynik żądania i przechwycenia:

  • Powiększenie:
    • CaptureRequest#CONTROL_ZOOM_RATIO
    • CaptureRequest#SCALER_CROP_REGION
  • Dotknij, aby ustawić ostrość:
    • CaptureRequest#CONTROL_AF_MODE
    • CaptureRequest#CONTROL_AF_TRIGGER
    • CaptureRequest#CONTROL_AF_REGIONS
    • CaptureRequest#CONTROL_AE_REGIONS
    • CaptureRequest#CONTROL_AWB_REGIONS
  • Lampa błyskowa:
    • CaptureRequest#CONTROL_AE_MODE
    • CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
    • CaptureRequest#FLASH_MODE
  • Kompensacja ekspozycji:
    • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

W przypadku podstawowych rozszerzeń z wersjami 1.2.0 lub wcześniejszymi aparatami CameraX Interfejs Extensions API obsługuje wszystkie powyższe klucze. Dla: extensions-interface 1.3.0, zarówno aparatX, jak i aparat2 obsługują listę zwróconych i obsługują tylko zawarte w niej klucze. Jeśli na przykład zdecydujesz się wrócić tylko CaptureRequest#CONTROL_ZOOM_RATIO i CaptureRequest#SCALER_CROP_REGION w wersji 1.3.0, oznacza, że aplikacja obsługuje tylko powiększenie i dotykowe ustawianie ostrości, lampa błyskowa i ekspozycja są niedozwolone.

Przedłużacz zaawansowany

Advanced Extender to typ implementacji przez dostawcę oparty na interfejsie Camera2 API. Ten typ rozszerzenia został dodany w extensions-interface w wersji 1.2.0. W zależności od producenta urządzenia, rozszerzenia można wdrożyć w warstwie aplikacji, Zależy to od tych czynników:

  • Niestandardowa konfiguracja strumienia:skonfiguruj strumienie niestandardowe, takie jak strumień RAW. lub wiele strumieni dla różnych identyfikatorów fizycznych kamer.

  • możliwość wysyłania żądań do aplikacji Camera2: obsługa złożonych interakcji; który może wysyłać żądania przechwytywania z parametrami opartymi na wynikach z poprzednich żądań.

Rozszerzenie Advanced Extender udostępnia kod lub warstwę pośrednią, dzięki której można dostosować konfigurację strumieniowania i na żądanie wysyłać żądania zapisu.

Pliki do implementacji

Aby przełączyć się na implementację Advanced Extender, Metoda isAdvancedExtenderImplemented() w ExtensionVersionImpl musi zwracać wartość true. W przypadku każdego typu rozszerzenia OEM musi wdrożyć odpowiednich klas Extender. Pliki implementacji Advanced Extender w pakiecie zaawansowanym.

Klasy rozszerzające do implementacji
Noc advanced/NightAdvancedExtenderImpl.java
HDR. advanced/HdrAdvancedExtenderImpl.java
Auto advanced/AutoAdvancedExtenderImpl.java
Bokeh advanced/BokehAdvancedExtenderImpl.java
Retusz twarzy advanced/BeautyAdvancedExtenderImpl.java

W poniższym przykładzie używamy zmiennej AdvancedExtenderImpl jako zmiennej. Zastąp go nazwą pliku Extender dla używanego rozszerzenia. ich wdrażanie.

Zobaczmy, jak Aparat2/X wywołuje funkcję extensions-interface, aby uzyskać trzy. przepływów aplikacji.

Przepływ aplikacji 1. Sprawdź dostępność rozszerzeń

Zaawansowane AppFlow1

Rysunek 8. Przepływ aplikacji 1 na urządzeniu Advanced Extender

Najpierw aplikacja sprawdza, czy dane rozszerzenie jest obsługiwane.

Przepływ aplikacji 2. Zapytanie o informacje

Zaawansowane AppFlow2

Rysunek 9. Krok 2 w aplikacji na urządzeniu Advanced Extender

Po wywołaniu funkcji AdvancedExtenderImpl.init() aplikacja może wysłać zapytanie na temat według informacji z AdvancedExtenderImpl:

  • Szacowany czas oczekiwania na obraz w ruchu: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() zwraca zakres czas oczekiwania na zapis, po którym aplikacja może ocenić, czy włączyć rozszerzenie na obecną sytuację.

  • Obsługiwane rozdzielczości podglądu i rejestrowania:

    • AdvancedExtenderImpl.getSupportedPreviewOutputResolutions() zwraca mapę formatu obrazu na listę rozmiarów, które są obsługiwane w przypadku formatu powierzchni podglądu i rozmiaru. Produkty OEM muszą obsługiwać co najmniej format PRIVATE.

    • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() zwraca błąd obsługiwane formaty i rozmiary powierzchni do przechwytywania. OEM musi obsługiwać Dane wyjściowe w formacie JPEG i YUV_420_888.

    • AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() zwraca błąd obsługiwane rozmiary dla dodatkowego strumienia YUV_420_888 na potrzeby analizy obrazu. Jeśli analiza obrazu nie jest obsługiwana, Funkcja getSupportedYuvAnalysisResolutions() powinna zwrócić wartość null lub pustą listę.

  • Dostępne klucze żądania przechwytywania i wyniki (dodane w extensions-interface 1.3.0): Camera2/X wywołuje następujące metody, aby pobrać obsługiwane przechwytywanie żądania kluczy i kluczy wyników w ramach implementacji:

    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
    • AdvancedExtenderImpl.getAvailableCaptureResultKeys

Więcej informacji: Obsługa kluczy i wyników żądania przechwytywania.

Proces aplikacji 3. Wyświetl podgląd/zdjęcie z włączonym rozszerzeniem

ZaawansowanyAppFlow3

Rysunek 10. Krok 3 w aplikacji na urządzeniu Advanced Extender

Powyższy diagram przedstawia główny proces uruchamiania podglądu i rejestrowania w przypadku typu Advanced Extender. Omówmy każdy krok po kroku.

  1. SessionProcessorImpl instancja

    Podstawowa implementacja pakietu Advanced Extender znajduje się w regionie SessionProcessorImpl, odpowiada za dostarczanie niestandardowych konfiguracji sesji i wysyłanie żądania przechwytywania, aby zainicjować podgląd i nadal przechwytywać żądania. Funkcja AdvancedExtenderImpl.createSessionProcessor() jest wywoływana w celu zwrócenia SessionProcessorImpl instancję.

  2. initSession

    SessionProcessorImpl.initSession() inicjuje sesję rozszerzenia. Tutaj przydzielasz zasoby i zwracasz konfigurację sesji przygotowuję plik CameraCaptureSession.

    W przypadku parametrów wejściowych kamera2/X określa konfiguracje powierzchni wyjściowej do podglądu i zdjęcia oraz opcjonalnie analizę obrazu YUV. Te dane wyjściowe konfiguracja powierzchni (OutputSurfaceImpl) obejmuje powierzchnię, rozmiar i obraz pobierane są te metody w AdvancedExtenderImpl:

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

    Musisz zwrócić instancję Camera2SessionConfigImpl, która składa się z lista Camera2OutputConfigImpl instancji i użytych parametrów sesji do konfiguracji usługi CameraCaptureSession. Odpowiadasz za wysyłanie prawidłowych zdjęć z aparatu na platformy wyjściowe przekazywane przez Aparat 2/X. Oto kilka sposobów na włączenie danych wyjściowych:

    • Przetwarzanie w panelu HAL aparatu: możesz bezpośrednio dodawać platformy wyjściowe. do: CameraCaptureSession, liniami SurfaceOutputConfigImpl implementacji. Służy do konfigurowania panelu wyjściowego kamery i umożliwia przetwarzanie obrazu przez HAL aparatu.

    • Przetwarzanie pośredniej powierzchni ImageReader (RAW, YUV itp.): dodaj pośrednie platformy ImageReader do CameraCaptureSession z ImageReaderOutputConfigImpl instancję.

      Musisz przetworzyć obrazy pośrednie i zapisać obraz wynikowy w na powierzchni wyjściowej.

    • Korzystanie z udostępniania powierzchni w aplikacji Camera2: używanie opcji udostępniania powierzchni innym urządzeniom dodając dowolną instancję Camera2OutputConfigImpl do Metoda getSurfaceSharingOutputConfigs() innej Camera2OutputConfigImpl instancję. Format i rozmiar powierzchni muszą być identyczna.

    Wszystkie Camera2OutputConfigImpl, w tym SurfaceOutputConfigImpli ImageReaderOutputConfigImpl musi mieć unikalny identyfikator (getId()), który jest służy do określania powierzchni docelowej i pobierania obrazu z ImageReaderOutputConfigImpl

  3. onCaptureSessionStart i RequestProcessorImpl

    Po uruchomieniu CameraCaptureSession i wywołaniu platformy aparatu onConfigured(), a następnie Aparat2/X wywoła SessionProcessorImpl.onCaptureSessionStart() z żądaniem Camera2 kod RequestProcessImpl. Aparat2/X implementuje funkcję RequestProcessImpl, który umożliwia wykonywanie żądań przechwytywania oraz pobierz obrazy, jeśli jest używany ImageReaderOutputConfigImpl.

    Interfejsy API RequestProcessImpl są podobne do interfejsów Camera2 CameraCaptureSession interfejsów API w zakresie wykonywania żądań. Różnice to:

    • Platformę docelową określa się za pomocą identyfikatora Camera2OutputConfigImpl instancja.
    • Możliwość pobrania obrazu: ImageReader.

    Możesz wywołać funkcję RequestProcessorImpl.setImageProcessor() z określonym Identyfikator Camera2OutputConfigImpl umożliwiający zarejestrowanie instancji ImageProcessorImpl ani otrzymywać obrazów.

    Po wywołaniu Camera2/X instancja RequestProcessImpl traci ważność SessionProcessorImpl.onCaptureSessionEnd()

  4. Uruchamianie podglądu i zrobienie zdjęcia

    W implementacji Advanced Extender można wysyłać żądania przechwytywania w interfejsie RequestProcessorImpl. Camera2/X powiadamia Cię o uruchomić cykliczne żądanie podglądu lub sekwencję przechwytywania ruchu przez dzwonię pod numer SessionProcessorImpl#startRepeating i SessionProcessorImpl#startCapture. Należy wysłać zapis w odpowiedzi na żądania podglądu i wciąż przechwytywanego obrazu.

    Camera2/X ustawia też parametry żądania zapisu za pomocą funkcji SessionProcessorImpl#setParameters Musisz ustawić te parametry żądania (jeśli parametry są obsługiwane) zarówno w żądaniach cyklicznych, jak i pojedynczych.

    Musisz obsługiwać co najmniej CaptureRequest.JPEG_ORIENTATION i CaptureRequest.JPEG_QUALITY extensions-interface Wersja 1.3.0 obsługuje żądania i kluczy wyników, które są udostępniane przy użyciu tych metod:

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

    Gdy deweloperzy skonfigurują klucze na liście getAvailableCaptureRequestKeys, musisz włączyć parametry i upewnić się, że przechwytywanie Wynik zawiera klucze na liście getAvailableCaptureResultKeys.

  5. startTrigger

    Pole SessionProcessorImpl.startTrigger() jest wywoływane, aby uruchomić aktywator, taki jak jako CaptureRequest.CONTROL_AF_TRIGGER oraz CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER Każdą przechwytywać klucze żądania, które nie były reklamowane AdvancedExtenderImpl.getAvailableCaptureRequestKeys()

    Usługa startTrigger() jest obsługiwana od extensions-interface w wersji 1.3.0. it umożliwia aplikacjom używanie funkcji Dotknij, aby ostrość i lampa błyskowa z rozszerzeniami.

  6. Czyszczenie danych

    Po zakończeniu sesji nagrywania Funkcja SessionProcessorImpl.onCaptureSessionEnd() jest wywoływana przed zamknięciem CameraCaptureSession Po zakończeniu sesji przechwytywania deInitSession() wykonuje czyszczenie.

Obsługa podglądu, przechwytywania i analizy obrazów

Zalecamy zastosowanie rozszerzenia zarówno w wersji testowej, jak i nadal przechwytywać przypadki użycia. Jeśli jednak opóźnienie jest zbyt duże i nie można wyświetlić podglądu płynnie, stosowanie rozszerzenia tylko do zdjęć nieruchomych.

W przypadku rozszerzenia Basic Extender niezależnie od tego, czy włączysz podgląd, musisz zaimplementować zarówno ImageCaptureExtenderImpl, jak i PreviewExtenderImpl dla danego rozszerzenia. Często aplikacja wykorzystuje też strumień YUV do analizowania treści graficznych, np. kodu QR lub tekstu. Aby lepiej wspierać ten przypadek użycia , powinien obsługiwać połączenie podglądu, obrazu nieruchomego i obrazu Strumień YUV_420_888 do konfigurowania usługi CameraCaptureSession. Oznacza to, że że jeśli wdrożysz procesor, musisz obsługiwać strumień połączenie 3 strumieni YUV_420_888.

W przypadku zaawansowanego przedłużenia kamery Aparat2/X przekazuje 3 platformy wyjściowe do SessionProcessorImpl.initSession() połączenie. Te platformy wyjściowe są przeznaczone do podglądu , zdjęcia i analizę obrazu. Musisz upewnić się, że w podglądzie a platformy, na których można przechwytywać dane wyjściowe, pojawiają się prawidłowe dane wyjściowe. Jednak w przypadku obrazu platformy wyjściowej analizy, upewnij się, że działa on tylko wtedy, gdy nie ma wartości null. Jeśli implementacja nie obsługuje strumienia analizy obrazu, możesz zwrócić pustą wartość listę w usłudze AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions(). Ten zapewnia, że powierzchnia danych wyjściowych analizy obrazu ma zawsze wartość null SessionProcessorImpl.initSession()

Obsługa nagrywania filmów

Obecna architektura rozszerzenia aparatu obsługuje tylko podgląd rejestrowania przypadków użycia. Nie można włączać tego rozszerzenia na urządzeniu MediaCodec lub MediaRecorder miejsca do nagrywania filmu. Jest jednak możliwe na potrzeby rejestrowania danych wyjściowych podglądu przez aplikacje.

Sprawdzamy platformę MediaCodec i MediaRecorder.

Metadane poszczególnych rozszerzeń

W przypadku Androida 14 lub nowszego metadane dotyczące rozszerzeń umożliwia klientom rozszerzenia aparatu ustawianie i odbieranie zapisów określonych rozszerzeń ustawienia i wyniki żądania. Rozszerzenie aparatu Klienci mogą używać parametru żądania przechwytywania EXTENSION_STRENGTH, aby kontrolować siłę rozszerzenia i wynik przechwytywania EXTENSION_CURRENT_TYPE, wskazują typ włączonego rozszerzenia.

Prośby o przechwytywanie

EXTENSION_STRENGTH parametr żądania przechwytywania kontroluje siłę efektu końcowego przetwarzania rozszerzenia. Odpowiednik wynik przechwytywania zawiera domyślną wartość siły, jeśli ten parametr nie jest ustawiony bezpośrednio przez klienta. Ten parametr można stosować w następujący sposób: typy rozszerzeń:

  • BOKEH: określa stopień rozmycia.
  • HDR i NIGHT: określa liczbę połączonych obrazów oraz jasność efekt końcowy.
  • FACE_RETOUCH: kontroluje ilość kosmetyków i pielęgnacji skóry. wygładzanie.

Obsługiwany zakres parametru EXTENSION_STRENGTH mieści się w zakresie od 0 do 100, gdzie 0 oznacza brak przetwarzania rozszerzenia lub proste przekazywanie i 100 wskazujący maksymalną siłę rozszerzenia efektu przetwarzania.

Aby dodać obsługę EXTENSION_STRENGTH, użyj dostawcy interfejsów API parametrów wprowadzonych w wersji 1.3.0 biblioteki rozszerzeń za pomocą prostego interfejsu online. Więcej informacji: getAvailableCaptureRequestKeys()

Rejestrowanie wyników

EXTENSION_CURRENT_TYPE Przechwytywanie wyniku pozwala implementom rozszerzeń powiadamiać klientów o aktywnych typu rozszerzenia.

Ponieważ rozszerzenia korzystające z typu AUTO dynamicznie przełączają się między rozszerzeniami takie jak HDR i NIGHT w zależności od warunków scenerii, aparatu rozszerzenia mogą używać rozszerzenia EXTENSION_CURRENT_TYPE do wyświetlania informacji o bieżące rozszerzenie wybrane przez rozszerzenie AUTO.

Szacowany czas oczekiwania na przechwytywanie w czasie rzeczywistym

Klienty z rozszerzeniami aparatu na Androida 14 lub nowszego może wysyłać zapytania w czasie rzeczywistym i rejestrować szacowane czasy oczekiwania na podstawie sceny warunków środowiska za pomocą getRealtimeStillCaptureLatency() Ten zapewnia dokładniejsze szacunki niż metoda statyczna getEstimatedCaptureLatencyRangeMillis() . Na podstawie szacowanego czasu oczekiwania aplikacje mogą pominąć rozszerzenie przetwarzania danych lub wyświetlania w nich informacji o konieczności wykonującą operację.

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();

Aby szacować czas oczekiwania w czasie rzeczywistym, zaimplementuj następujące:

Wywołania zwrotne postępu przetwarzania przechwytywania

Klienty z rozszerzeniami aparatu na Androida 14 lub nowszego może otrzymywać wywołania zwrotne dotyczące postępu długotrwałego przetwarzania nadal przechwytywania operacji. Aplikacje mogą wyświetlać użytkownikom aktualne informacje o postępach w ulepszaniu ogólne wrażenia użytkownika.

Aplikacje mogą korzystać z tego kodu do integracji tej funkcji:

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

Aby zapewnić obsługę wywołań zwrotnych postępu przetwarzania przechwytywania, dostawca rozszerzenia implementacja musi wywoływać następujące wywołania zwrotne z bieżącym postępem wartość:

Zdjęcie po wyświetleniu jest nadal rejestrowane

W Androidzie 14 lub nowszym rozszerzenia aparatu mogą udostępniać po wyświetleniu (obraz podglądu) za pomocą funkcji setPostviewOutputConfiguration Aby zwiększyć wygodę użytkowników, aplikacje mogą wyświetlać obraz po wyświetleniu jako obraz gdy czas przetwarzania rozszerzenia jest dłuższy, i zastąpić ją, gdy ostateczna wersja będzie dostępna. Aplikacje, które można konfigurować i wysyłać żądania rejestrowania po wyświetleniu, używając następującego kodu referencyjnego:

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

Aby możliwe było przechwytywanie po wyświetleniu, implementacja dostawcy musi zaimplementować komponent :

Obsługuj dane wyjściowe SurfaceView

Klienty z rozszerzeniami aparatu na Androida 14 lub nowszego może korzystać ze ścieżek renderowania zoptymalizowanych pod kątem wydajności i wydajności, rejestrując SurfaceView w celu generowania podglądu danych wyjściowych dla powtarzających się żądań.

Aby dane wyjściowe funkcji SurfaceView były obsługiwane, implementacja rozszerzenia dostawcy musi być możliwość strumieniowania i wyświetlania podglądu w instancjach SurfaceView. Do sprawdź, czy ta funkcja jest obsługiwana, uruchom SurfaceViewExtensionPreviewTest.java Moduł CTS.

Typy sesji u dostawców

Ta funkcja umożliwia implementacjom rozszerzeń dostawcy wybór określonego przez niego typu sesji, który zostanie ustawiony w wewnętrznej sesji nagrywania aparatu zamiast wartości domyślnej.

Funkcja działa w całości w ramach platformy i stosu dostawców oraz nie ma wpływu na interfejs API widoczny publicznie ani dla klienta.

Aby wybrać typ sesji zależny od dostawcy, zaimplementuj te komponenty na potrzeby swoich bibliotek rozszerzeń: * ExtenderStateListener.onSessionType() w przypadku rozszerzeń podstawowych * Camera2SessionConfigImpl.getSessionType() – rozszerzenia zaawansowane

Historia wersji interfejsu rozszerzeń

W tabeli poniżej znajdziesz historię wersji interfejsu rozszerzenia aparatu. Ty należy zawsze implementować bibliotekę dostawcy w najnowszej wersji.

Wersja Dodane funkcje
1.0.0
  • Weryfikacja wersji
    • ExtensionVersionImpl
  • Przedłużacz podstawowy
    • PreviewExtenderImpl
    • ImageCaptureExtenderImpl
    • Processor
      • PreviewImageProcessorImpl
      • CaptureProcessorImpl
      • RequestUpdateProcessorImpl
1.1.0
  • Inicjowanie biblioteki
    • InitializerImpl
  • Udostępnianie obsługiwanych rozdzielczości
    • PreviewExtenderImpl.getSupportedResolutions
    • ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0
  • AdvancedExtender
    • AdvancedExtenderImpl
    • SessionProcessorImpl
  • Uzyskaj szacowany czas oczekiwania na zapis
    • ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0
  • Udostępnianie obsługiwanych kluczy żądania przechwytywania/kluczy wyników
    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys i getAvailableCaptureResultKeys
    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys i getAvailableCaptureResultKeys
    • Nowe połączenie typu process(), które odbiera ProcessResultImpl w ciągu PreviewImageProcessorImpl i CaptureProcessorImpl
    • Żądanie typu aktywatora pomocy
      • AdvancedExtenderImpl.startTrigger
1.4.0
  • Metadane poszczególnych rozszerzeń
  • Szacowany czas oczekiwania na dynamiczne zapisywanie danych
  • Wywołania zwrotne postępu przetwarzania przechwytywania
  • Zdjęcie po wyświetleniu jest nadal rejestrowane
  • Obsługa danych wyjściowych SurfaceView
  • Typy sesji u dostawców

Implementacja referencyjna

Poniżej znajdziesz referencyjne implementacje biblioteki dostawcy OEM frameworks/ex

  • advancedSample: podstawowa implementacja zaawansowanego rozszerzenia.

  • sample: podstawowa implementacja rozszerzenia Basic Extender.

  • service_based_sample: implementacja pokazująca, jak hostować Rozszerzenia aparatu Service Implementacja obejmuje te komponenty:

    • oem_library: Biblioteka OEM rozszerzeń aparatów dla interfejsów API rozszerzeń Camera2 i CameraX , która implementuje Extensions-Interface. Jest to funkcja przekazująca, przekierowuje połączenia od Extensions-Interface do usługi. Ta biblioteka udostępnia też pliki AIDL i klasy kodu do komunikacji z posprzedażna.

      Rozszerzenie Advanced Extender jest domyślnie włączone. Aby włączyć rozszerzenie Basic Extender, zmień ExtensionsVersionImpl#isAdvancedExtenderImplemented, aby zwrócić false

    • extensions_service: Przykładowa implementacja usługi rozszerzeń. Dodaj implementację tutaj. Interfejs do wdrożenia w usłudze jest podobny do: Extensions-Interface. Na przykład wdrożenie Funkcja IAdvancedExtenderImpl.Stub wykonuje te same operacje co AdvancedExtenderImpl ImageWrapper i TotalCaptureResultWrapper są wymagane do tego, by można było użyć działek Image i TotalCaptureResult.

Konfigurowanie biblioteki dostawcy na urządzeniu

biblioteka dostawcy OEM nie jest wbudowana w aplikację; jest wczytywany z urządzenia w czasie działania aplikacji Camera2/X. W Aparacie X tag <uses-library> deklaruje że biblioteka androidx.camera.extensions.impl zdefiniowana w AndroidManifest.xml biblioteki camera-extensions, jest zależnością CameraX i musi zostać wczytywane w czasie działania. W Aparacie 2 platforma wczytuje usługę rozszerzeń, która deklaruje też, że <uses-library>wczytuje to samo Biblioteka androidx.camera.extensions.impl w czasie działania.

Dzięki temu aplikacje innych firm korzystające z rozszerzeń mogą automatycznie wczytywać dane OEM z biblioteką dostawców. Biblioteka OEM jest oznaczona jako opcjonalna, dzięki czemu aplikacje mogą działać na urządzeniach które nie mają biblioteki na urządzeniu. Camera2/X automatycznie obsługuje to zachowanie, gdy aplikacja próbuje użyć kamery. o ile producent urządzenia umieści bibliotekę OEM urządzenia, aby aplikacja mogła je wykryć.

Aby skonfigurować na urządzeniu bibliotekę OEM:

  1. Dodaj plik uprawnień, którego wymaga tag <uses-library>. w tym formacie: /etc/permissions/ANY_FILENAME.xml Dla: przykład: /etc/permissions/camera_extensions.xml. Pliki w tym folderze należy zmapować bibliotekę o nazwie <uses-library> na rzeczywistej ścieżce pliku na urządzeniu.

  2. Skorzystaj z przykładu poniżej, aby dodać wymagane informacje do pliku.

    • name musi mieć wartość androidx.camera.extensions.impl, ponieważ to w której biblioteka szuka aparatów X.
    • file to ścieżka bezwzględna do pliku zawierającego implementacji rozszerzeń (np. /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>

Urządzenia z Androidem 12 lub nowszym obsługujące Aparat X więc rozszerzenia muszą mieć właściwość ro.camerax.extensions.enabled ustawioną na true, który pozwala sprawdzać, czy urządzenie obsługuje rozszerzenia. Aby to zrobić, dodaj ten wiersz do pliku z nazwą urządzenia:

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

Weryfikacja

Aby przetestować implementację biblioteki dostawcy OEM w na etapie programowania, skorzystaj z przykładowej aplikacji androidx-main/camera/integration-tests/extensionstestapp/, który jest dostępny przez różne rozszerzenia dostawców.

Po zakończeniu wdrażania skorzystaj z Narzędzie do weryfikacji rozszerzeń aparatu automatycznych i ręcznych testów sprawdzających, czy biblioteka dostawcy .

Tryb rozszerzonej sceny a rozszerzenia aparatu

W przypadku rozszerzenia bokeh oprócz naświetlania go za pomocą rozszerzeń aparatu może pokazać rozszerzenie, używając trybu sceny rozszerzonej, który jest włączony CONTROL_EXTENDED_SCENE_MODE . Więcej informacji o implementacji znajdziesz w artykule Bokeh aparatu.

Rozszerzony tryb sceny ma mniej ograniczeń w porównaniu z rozszerzeniami aparatu w przypadku Camera2. Możesz na przykład włączyć tryb rozszerzonej sceny w zwykłej instancji CameraCaptureSession, która obsługuje elastyczny strumień z kombinacjami i parametrami żądania. Natomiast rozszerzenia z aparatem obsługują tylko stały zestaw typów strumieni i ograniczoną obsługę przechwytywania. parametrów żądania.

Wadą trybu rozszerzonej sceny jest to, że można go wdrożyć tylko w HAL kamery, co oznacza, że musi zostać zweryfikowany, aby działać na wszystkich ortogonalne elementy sterujące dostępne dla deweloperów aplikacji.

Zalecamy stosowanie efektu bokeh przy użyciu zarówno trybu rozszerzonej sceny, jak i aparatu Rozszerzenia, ponieważ aplikacje mogą preferować używanie określonego interfejsu API do włączania efektu bokeh. Zalecamy użycie najpierw trybu sceny rozszerzonej, ponieważ jest on najdłużej elastyczny sposób na włączenie rozszerzenia bokeh w aplikacjach. Następnie możesz zastosować interfejs rozszerzeń aparatu korzysta z trybu rozszerzonej sceny. Jeśli Efekt bokeh w HAL aparatu jest trudny, np. dlatego wymaga dodania posta procesora działającego w warstwie aplikacji do przetwarzania obrazów, zalecamy wdrożenie za pomocą rozszerzenia bokeh.

Najczęstsze pytania

Czy są jakieś ograniczenia dotyczące poziomów interfejsu API?

Tak. Zależy to od zestawu funkcji interfejsu Android API wymaganych przez OEM. lub wdrożenia biblioteki dostawcy. Przykład: Funkcja ExtenderStateListener.onPresetSession() używa funkcji SessionConfiguration.setSessionParameters() aby ustawić podstawowy zestaw tagów. To wywołanie jest dostępne tylko na poziomie interfejsu API 28 lub więcej. Szczegółowe informacje o konkretnych metodach interfejsu można znaleźć w Dokumentacja API