Kamera Uzantıları

Cihaz üreticileri, OEM satıcı kitaplığı tarafından sağlanan Kamera Uzantıları arayüzü aracılığıyla bokeh, gece modu ve HDR gibi uzantıları üçüncü taraf geliştiricilerin kullanımına sunabilir. Geliştiriciler, OEM satıcı kitaplığında uygulanan uzantılara erişmek için Camera2 Extensions API'sini ve CameraX Extensions API'sini kullanabilir.

Camera2 ve CameraX'te aynı olan desteklenen uzantıların listesi için bkz. CameraX Uzantıları API'si . Bir uzantı eklemek istiyorsanız Sorun İzleyici'yi kullanarak bir hata bildirin.

Bu sayfada OEM satıcı kitaplığının cihazlarda nasıl uygulanacağı ve etkinleştirileceği açıklanmaktadır.

Mimari

Aşağıdaki şema, Kamera Uzantıları arayüzünün veya extensions-interface mimarisini açıklamaktadır: Mimari

Şekil 1. Kamera Uzantıları mimari şeması

Diyagramda gösterildiği gibi, Kamera Uzantılarını desteklemek için OEM satıcı kitaplığı tarafından sağlanan extensions-interface uygulamanız gerekir. OEM satıcı kitaplığınız iki API'yi etkinleştirir: CameraX Extensions API ve Camera2 Extensions API , sırasıyla CameraX ve Camera2 uygulamaları tarafından satıcı uzantılarına erişmek için kullanılır.

OEM satıcı kitaplığını uygulama

OEM satıcı kitaplığını uygulamak için camera-extensions-stub dosyalarını bir sistem kitaplığı projesine kopyalayın. Bu dosyalar Kamera Uzantıları arayüzünü tanımlar.

camera-extensions-stub dosyaları aşağıdaki kategorilere ayrılmıştır:

Temel arayüz dosyaları (değiştirmeyin)

  • 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

Zorunlu uygulamalar (uygulamanızı ekleyin)

  • ExtensionVersionImpl.java
  • InitializerImpl.java

Bokeh genişletici sınıfları (Bokeh uzantısı destekleniyorsa uygulayın)

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

Gece genişletici sınıfları (Gece ​​uzantısı destekleniyorsa uygulayın)

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

Otomatik genişletici sınıfları (Otomatik genişletme destekleniyorsa uygulayın)

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

HDR genişletici sınıfları (HDR uzantısı destekleniyorsa uygulayın)

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

Yüz Rötuş genişletici sınıfları (Yüz Rötuş uzantısı destekleniyorsa uygulayın)

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

Yardımcı programlar (isteğe bağlı, silinebilir)

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

Her uzantı için bir uygulama sağlamanız gerekmez. Bir uzantı uygulamazsanız isExtensionAvailable() işlevini false döndürecek veya karşılık gelen Extender sınıflarını kaldıracak şekilde ayarlayın. Camera2 ve CameraX Uzantıları API'leri uygulamaya uzantının kullanılamadığını bildirir.

Bir uzantıyı etkinleştirmek için Camera2 ve CameraX Uzantıları API'lerinin satıcı kitaplığıyla nasıl etkileşime girdiğini inceleyelim. Aşağıdaki diyagram, örnek olarak Gece uzantısını kullanarak uçtan uca akışı göstermektedir:

Ana akış

Şekil 2. Gece uzatma uygulaması

  1. Sürüm doğrulaması:

    Camera2/X, OEM tarafından uygulanan extensions-interface sürümünün Camera2/X destekli sürümlerle uyumlu olduğundan emin olmak için ExtensionVersionImpl.checkApiVersion() öğesini çağırır.

  2. Satıcı kitaplığının başlatılması:

    InitializerImpl satıcı kitaplığını başlatan bir init() yöntemine sahiptir. Camera2/X, Extender sınıflarına erişmeden önce başlatma işlemini tamamlar.

  3. Extender sınıflarını somutlaştırın:

    Uzantı için Extender sınıflarını başlatır. İki Genişletici türü vardır: Temel Genişletici ve Gelişmiş Genişletici. Tüm Uzantılar için bir Genişletici türü uygulamanız gerekir. Daha fazla bilgi için bkz. Temel Genişletici ve Gelişmiş Genişletici .

    Camera2/X, bilgi almak ve uzantıyı etkinleştirmek için Extender sınıflarını başlatır ve onlarla etkileşime girer. Belirli bir uzantı için Camera2/X, Extender sınıflarını birden çok kez başlatabilir. Sonuç olarak, yapıcıda veya init() çağrısında ağır başlatma işlemleri yapmayın. Ağır işleri yalnızca kamera oturumu başlamak üzereyken yapın; örneğin, Temel Genişleticide onInit() çağrıldığında veya Gelişmiş Genişleticide initSession() çağrıldığında.

    Night uzantısı için, Basic Extender türü için aşağıdaki Extender sınıfları başlatılır:

    • NightImageCaptureExtenderImpl.java
    • NightPreviewExtenderImpl.java

    Gelişmiş Genişletici türü için:

    • NightAdvancedExtenderImpl.java

  4. Uzantı kullanılabilirliğini kontrol edin:

    Uzantıyı etkinleştirmeden önce isExtensionAvailable() , uzantının Extender örneği aracılığıyla belirtilen kamera kimliğinde mevcut olup olmadığını kontrol eder.

  5. Extender'ı kamera bilgileriyle başlatın:

    Camera2/X, Extender örneğinde init() öğesini çağırır ve ona kamera kimliğini ve CameraCharacteristics değerini iletir.

  6. Sorgu bilgileri:

    Desteklenen çözünürlükler gibi bilgileri almak, tahmini gecikme süresini yakalamak ve uzantıyı etkinleştirmeye hazırlık olarak Extender'dan istek anahtarlarını yakalamak için Extender sınıfını çağırır.

  7. Extender'da uzantıyı etkinleştirin:

    Extender sınıfı, sınıfı etkinleştirmek için gereken tüm arayüzleri sağlar. OEM uygulamasını Camera2 boru hattına bağlamak için, yakalama isteği parametrelerinin enjekte edilmesi veya bir post işlemcinin etkinleştirilmesi gibi bir mekanizma sunar.

    Gelişmiş Genişletici türü için, Camera2/X, uzantıyı etkinleştirmek üzere SessionProcessorImpl ile etkileşime girer. Camera2/X, Extender'da createSessionProcessor() öğesini çağırarak SessionProcessorImpl örneğini alır.

Aşağıdaki bölümlerde uzatma akışı daha ayrıntılı olarak açıklanmaktadır.

Sürüm doğrulama

OEM satıcı kitaplığını çalışma zamanında cihazdan yüklerken Camera2/X, kitaplığın extensions-interface sürümüyle uyumlu olup olmadığını doğrular. extensions-interface anlamsal sürüm oluşturmayı veya MAJOR.MINOR.PATCH'i (örneğin 1.1.0 veya 1.2.0) kullanır. Ancak sürüm doğrulama sırasında yalnızca ana ve alt sürümler kullanılır.

Sürümü doğrulamak için Camera2/X, desteklenen extensions-interface sürümüyle ExtensionVersionImpl.checkApiVersion() öğesini çağırır. Camera2/X daha sonra uzantının etkinleştirilip etkinleştirilemeyeceğini ve hangi yetenekleri çağırması gerektiğini belirlemek için OEM kitaplığı tarafından bildirilen sürümü kullanır.

Ana sürüm uyumluluğu

Uzantı arayüzünün ana sürümleri Camera2/X ile satıcı kitaplığı arasında farklıysa uyumsuz olduğu kabul edilir ve uzantı devre dışı bırakılır.

Geriye dönük uyumluluk

Ana sürüm aynı olduğu sürece Camera2/X, önceki extensions-interface sürümleriyle oluşturulmuş OEM satıcı kitaplıklarıyla geriye dönük uyumluluk sağlar. Örneğin, Camera2/X, 1.3.0 extensions-interface destekliyorsa, 1.0.0, 1.1.0 ve 1.2.0'ı uygulayan OEM satıcı kitaplıkları hâlâ uyumludur. Bu aynı zamanda, satıcı kitaplığının belirli bir sürümünü uyguladıktan sonra Camera2/X'in kitaplığın gelecek extension-interface sürümleriyle geriye dönük olarak uyumlu olmasını sağladığı anlamına da gelir.

İleriye dönük uyumluluk

Daha yeni extensions-interface satıcı kitaplıklarıyla ileriye dönük uyumluluk size, yani OEM'e bağlıdır. Uzantıları uygulamak için bazı özelliklere ihtiyacınız varsa, belirli bir sürümden itibaren uzantıları etkinleştirmek isteyebilirsiniz. Bu durumda, Camera2/X kitaplık sürümü gereksinimleri karşıladığında desteklenen extensions-interface sürümünü geri döndürebilirsiniz. Camera2/X sürümleri desteklenmiyorsa uzantıları devre dışı bırakmak için 99.0.0 gibi uyumsuz bir sürümü döndürebilirsiniz.

Satıcı kitaplığının başlatılması

OEM kitaplığı tarafından uygulanan extensions-interface sürümünü doğruladıktan sonra Camera2/X, başlatma işlemini başlatır. InitializerImpl.init() yöntemi, OEM kitaplığına bir uygulamanın uzantıları kullanmaya çalıştığını bildirir.

Camera2/X, OEM satıcı kitaplığı başlatma işleminin tamamlandığını bildirmek için OnExtensionsInitializedCallback.onSuccess() öğesini çağırana kadar OEM kitaplığına (sürüm kontrolü dışında) başka çağrı yapmaz.

extensions-interface 1.1.0'dan itibaren InitializerImpl uygulamanız gerekir. OEM satıcı kitaplığı extensions-interface 1.0.0'ı uyguluyorsa Camera2/X kitaplık başlatma adımını atlar.

Temel Genişletici ve Gelişmiş Genişletici

İki tür extensions-interface uygulaması vardır: Temel Genişletici ve Gelişmiş Genişletici. Gelişmiş Genişletici, extensions-interface 1.2.0'dan beri desteklenmektedir.

Kamera HAL'indeki görüntüleri işleyen uzantılar için Temel Genişleticiyi uygulayın veya YUV akışlarını işleyebilen bir son işlemci kullanın.

Camera2 akış yapılandırmasını özelleştirmesi ve gerektiğinde yakalama istekleri göndermesi gereken uzantılar için Gelişmiş Genişleticiyi uygulayın.

Karşılaştırma için aşağıdaki tabloya bakın:

Temel Genişletici Gelişmiş Genişletici
Akış yapılandırmaları Sabit
Önizleme: PRIVATE veya YUV_420_888 (işlemci varsa)
Hareketsiz yakalama: JPEG veya YUV_420_888 (işlemci varsa)		 OEM tarafından özelleştirilebilir.
Yakalama isteği gönderiliyor Yalnızca Camera2/X yakalama istekleri gönderebilir. Bu isteklere göre parametreleri ayarlayabilirsiniz. Görüntü yakalama için işlemci sağlandığında, Camera2/X birden fazla yakalama isteği gönderebilir ve tüm görüntüleri ve yakalama sonuçlarını işlemciye gönderebilir. Camera2 yakalama isteğini yürütmek ve sonuçları ve Görüntüyü almak için size bir RequestProcessorImpl örneği sağlanır.

Camera2/X, OEM'e önizleme için yinelenen isteği başlatması ve sırasıyla hareketsiz yakalama dizisini başlatması için sinyal vermek üzere SessionProcessorImpl startRepeating ve startCapture çağırır.

Kamera boru hattındaki kancalar
  • onPresetSession oturum parametrelerini sağlar.
  • onEnableSession CameraCaptureSession yapılandırıldıktan hemen sonra tek bir istek gönderir.
  • onDisableSession CameraCaptureSession kapatılmadan önce tek bir istek gönderir.
  • initSession yakalama oturumunu oluşturmak için özelleştirilmiş bir kamera2 oturumu yapılandırmasını başlatır ve döndürür.
  • onCaptureSessionStart CameraCaptureSession yapılandırıldıktan hemen sonra çağrılır.
  • onCaptureSessionEnd , CameraCaptureSession kapatılmadan önce çağrılır.
İçin uygun Kamera HAL'sinde veya YUV görüntülerini işleyen bir işlemcide uygulanan uzantılar.
  • Uzantılar için Camera2 tabanlı uygulamalara sahiptir.
  • RAW akışı gibi özelleştirilmiş akış yapılandırmasına ihtiyaç duyar.
  • Etkileşimli yakalama dizisi gerekiyor.
Desteklenen API sürümü Camera2 Uzantıları: Android 13 veya üzeri
CameraX Uzantıları: camera-extensions 1.1.0 veya üzeri		 Camera2 Uzantıları: Android 12L veya üzeri
CameraX Uzantıları: camera-extensions 1.2.0-alpha03 veya üzeri

Uygulama akışları

Aşağıdaki tabloda üç tür uygulama akışı ve bunlara karşılık gelen Kamera Uzantıları API çağrıları gösterilmektedir. Camera2/X bu API'leri sağlarken, daha sonraki bir bölümde daha ayrıntılı olarak açıklayacağımız bu akışları desteklemek için satıcı kitaplığını doğru şekilde uygulamanız gerekir.

Kamera2 uzantıları CameraX uzantıları
Sorgu uzantısının kullanılabilirliği CameraExtensionCharacteristics . getSupportedExtensions ExtensionsManager. isExtensionAvailable
Bilgileri sorgula CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys ExtensionsManager. getEstimatedCaptureLatencyRange

CameraX kitaplıktaki bilgilerin geri kalanını yönetir.

Uzantı etkinken önizleme ve hareketsiz yakalama CameraDevice. createExtensionSession

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

 val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector binToLifecycle(lifecycleOwner, CameraSelector, önizleme, ...)

Temel Genişletici

Temel Genişletici arayüzü, kamera hattındaki çeşitli yerlere kancalar sağlar. Her uzantı türünün, OEM'lerin uygulaması gereken karşılık gelen Genişletici sınıfları vardır.

Aşağıdaki tabloda, OEM'lerin her uzantı için uygulaması gereken Genişletici sınıfları listelenmektedir:

Uygulanacak genişletici sınıflar
Gece NightPreviewExtenderImpl.java

NightImageCaptureExtenderImpl.java

HDR HdrPreviewExtenderImpl.java HdrImageCaptureExtenderImpl.java
Oto AutoPreviewExtenderImpl.java AutoImageCaptureExtenderImpl.java
Bokeh BokehPreviewExtenderImpl.java BokehImageCaptureExtenderImpl.java
Yüz rötuşu BeautyPreviewExtenderImpl.java BeautyImageCaptureExtenderImpl.java

Aşağıdaki örnekte yer tutucu olarak PreviewExtenderImpl ve ImageCaptureExtenderImpl kullanıyoruz. Bunları uyguladığınız gerçek dosyaların adlarıyla değiştirin.

Temel Genişletici aşağıdaki yeteneklere sahiptir:

  • CameraCaptureSession ( onPresetSession ) yapılandırırken oturum parametrelerini ekleyin.
  • Yakalama oturumunun başlangıç ​​ve kapanış olaylarını size bildirir ve döndürülen parametrelerle ( onEnableSession , onDisableSession ) HAL'ye bildirimde bulunmak için tek bir istek gönderir.
  • İstek için yakalama parametrelerini enjekte edin ( PreviewExtenderImpl.getCaptureStage , ImageCaptureExtenderImpl.getCaptureStages ).
  • Önizleme için işlemciler ekleyin ve YUV_420_888 akışını işleyebilen yakalamaya devam edin.

Yukarıda bahsedilen üç uygulama akışını elde etmek için Camera2/X'in extensions-interface nasıl çağırdığını görelim.

Uygulama akışı 1: Uzantının kullanılabilirliğini kontrol edin

BasicExtenderAppFlow1

Şekil 3. Basic Extender'daki uygulama akışı 1

Bu akışta Camera2/X, init() öğesini çağırmadan hem PreviewExtenderImpl hem de ImageCaptureExtenderImpl isExtensionAvailable() yöntemini doğrudan çağırır. Uzantıları etkinleştirmek için her iki Extender sınıfının da true döndürmesi gerekir.

Bu genellikle uygulamaların, uzantıyı etkinleştirmeden önce belirli bir kamera kimliği için verilen uzantı türünün desteklenip desteklenmediğini kontrol etmesi için ilk adımdır. Bunun nedeni, bazı uzantıların yalnızca belirli kamera kimliklerinde desteklenmesidir.

Uygulama akışı 2: Sorgu bilgileri

BasicExtenderAppFlow2

Şekil 4. Basic Extender'da uygulama akışı 2

Uzantının kullanılabilir olup olmadığını belirledikten sonra uygulamalar, uzantıyı etkinleştirmeden önce aşağıdaki bilgileri sorgulamalıdır.

  • Hala gecikme aralığını yakala: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange , uygulamanın geçerli senaryo için uzantıyı etkinleştirmenin uygun olup olmadığını değerlendirmesi için yakalama gecikmesi aralığını döndürür.

  • Önizleme ve yakalama yüzeyi için desteklenen boyutlar: ImageCaptureExtenderImpl.getSupportedResolutions ve PreviewExtenderImpl.getSupportedResolutions , yüzey formatı ve boyutu için desteklenen görüntü formatlarının ve boyutların bir listesini döndürür.

  • Desteklenen istek ve sonuç anahtarları: Camera2/X, uygulamanızdan desteklenen yakalama isteği anahtarlarını ve sonuç anahtarlarını almak için aşağıdaki yöntemleri çağırır:

    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
    • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X, daha fazla bilgi için sorgulama yapmadan önce her zaman bu Extender sınıflarında ilk olarak init() öğesini çağırır.

Uygulama akışı 3: Uzantı etkinken önizleme/hareketsiz yakalama (HAL uygulaması)

BasicExtenderAppFlow3

Şekil 5. Basic Extender'da uygulama akışı 3

Yukarıdaki şema, herhangi bir işlemci olmadan bir uzantıyla önizlemeyi etkinleştirmenin ve hala yakalamanın ana akışını göstermektedir. Bu, kamera HAL'nin uzantıyı işlediği anlamına gelir.

Bu akışta, Camera2/X önce init() öğesini, ardından onInit çağırır; bu, belirtilen uzantılarla bir kamera oturumunun başlamak üzere olduğunu size bildirir. onInit() içinde ağır kaldırma başlatma işlemi yapabilirsiniz.

CameraCaptureSession yapılandırılırken, Camera2/X oturum parametrelerini almak için onPresetSession çağırır. Yakalama oturumu başarıyla yapılandırıldıktan sonra Camera2/X, yakalama parametrelerini içeren bir CaptureStageImpl örneğini döndüren onEnableSession çağırır. Camera2/X, HAL'i bilgilendirmek için hemen bu yakalama parametreleriyle tek bir istek gönderir. Benzer şekilde, yakalama oturumu kapatılmadan önce Camera2/X, onDisableSession çağırır ve ardından döndürülen yakalama parametreleriyle tek bir istek gönderir.

Camera2/X tarafından tetiklenen yinelenen istek, PreviewExtenderImpl.getCaptureStage() tarafından döndürülen istek parametrelerini içerir. Ayrıca, hareketsiz yakalama isteği ImageCaptureExtenderImpl.getCaptureStages() tarafından döndürülen parametreleri içerir.

Son olarak, Camera2/X, kamera oturumu bittikten sonra onDeInit() öğesini çağırır. Kaynakları onDeinit() içinde serbest bırakabilirsiniz.

Önizleme işlemcisi

Kamera HAL'sine ek olarak bir işlemciye uzantılar da uygulayabilirsiniz.

Aşağıda açıklandığı gibi işlemci türünü belirtmek için PreviewExtenderImpl.getProcessorType uygulayın:

  • PROCESSOR_TYPE_NONE : İşlemci yok. Görüntüler kamera HAL'de işlenir.

  • PROCESSOR_TYPE_REQUEST_UPDATE_ONLY : İşlemci türü, yinelenen isteği en son TotalCaptureResult dayalı yeni yakalama isteği parametreleriyle güncellemenizi sağlar.

    PreviewExtenderImpl.getProcessor TotalCaptureResult örneğini işleyen ve yinelenen isteği güncellemek için bir CaptureStageImpl örneği döndüren bir RequestUpdateProcessorImpl örneği döndürmelidir. PreviewExtenderImpl.getCaptureStage() ayrıca işlemenin sonucunu yansıtmalı ve en son CaptureStageImpl değerini döndürmelidir.

  • PROCESSOR_TYPE_IMAGE_PROCESSOR : Bu tür, YUV_420_888 görüntülerini işlemek ve çıktıyı PRIVATE bir yüzeye yazmak için bir işlemci uygulamanıza olanak tanır.

    PreviewExtenderImpl.getProcessor içinde bir PreviewImageProcessorImpl örneğini uygulamanız ve döndürmeniz gerekir. İşlemci, YUV_420_888 giriş görüntülerinin işlenmesinden sorumludur. Çıktıyı PRIVATE önizleme biçimine yazmalıdır. Camera2/X, CameraCaptureSession önizleme amacıyla yapılandırmak için PRIVATE yerine YUV_420_888 yüzeyini kullanır.

    Akış için aşağıdaki resme bakın:

Önizlemeİşlemci

Şekil 6. PreviewImageProcessorImpl ile önizleme akışı

PreviewImageProcessorImpl arayüzü, ProcessImpl genişletir ve üç önemli yönteme sahiptir:

  • onOutputSurface(Surface surface, int imageFormat) işlemcinin çıktı yüzeyini ayarlar. PreviewImageProcessorImpl için imageFormat , PixelFormat.RGBA_8888 gibi bir piksel biçimidir.

  • onResolutionUpdate(Size size) giriş görüntüsünün boyutunu ayarlar.

  • onImageFormatUpdate(int imageFormat) giriş görüntüsünün görüntü formatını ayarlar. Şu anda yalnızca YUV_420_888 olabilir.

Görüntü yakalama işlemcisi

Hareketsiz yakalama için, ImageCaptureExtenderImpl.getCaptureProcessor kullanarak bir CaptureProcessorImpl örneği döndürerek bir işlemci uygulayabilirsiniz. İşlemci, yakalanan YUV_420_888 görüntülerinin ve TotalCaptureResult örneklerinin bir listesini işlemekten ve çıktıyı bir YUV_420_888 yüzeyine yazmaktan sorumludur.

Hareketsiz yakalama isteğini göndermeden önce önizlemenin etkin ve çalışıyor olduğunu güvenle varsayabilirsiniz.

Aşağıdaki diyagramdaki akışa bakın:

Yakalamaİşlemcisi

Şekil 7. CaptureProcessorImpl ile akışı yakalama

  1. Camera2/X, yakalama oturumunu yapılandırmak amacıyla hareketsiz yakalama için YUV_420_888 formatlı bir yüzey kullanır. Camera2/X, CaptureProcessorImpl aşağıdakileri çağırarak hazırlar:

    • CaptureProcessorImpl.onImageFormatUpdate() ile YUV_420_888 .
    • Giriş görüntüsü boyutuyla CaptureProcessorImpl.onResolutionUpdate() .
    • YUV_420_888 çıkış yüzeyine sahip CaptureProcessorImpl.onOutputSurface() .

  2. ImageCaptureExtenderImpl.getCaptureStages , CaptureStageImpl listesini döndürür; burada her öğe, Camera2/X tarafından gönderilen yakalama parametreleriyle bir CaptureRequest örneğiyle eşleşir. Örneğin, üç CaptureStageImpl örneğinin bir listesini döndürürse Camera2/X, captureBurst API'sini kullanarak karşılık gelen yakalama parametreleriyle birlikte üç yakalama isteği gönderir.

  3. Alınan görüntüler ve TotalCaptureResult örnekleri bir araya toplanır ve işlenmek üzere CaptureProcessorImpl gönderilir.

  4. CaptureProcessorImpl sonuç Görüntüsünü ( YUV_420_888 formatı) onOutputSurface() çağrısı tarafından belirtilen çıktı yüzeyine yazar. Camera2/X, gerekirse bunu JPEG görüntülerine dönüştürür.

Yakalama isteği anahtarlarını ve sonuçlarını destekleyin

Uygulamalar, kamera önizlemesi ve yakalamanın yanı sıra yakınlaştırma ve flaş parametrelerini ayarlayabilir veya odaklanmak için dokunmayı tetikleyebilir. Bu parametreler uzantı uygulamanızla uyumlu olmayabilir.

Uygulamanızın desteklediği parametreleri ortaya çıkarmanıza olanak sağlamak için extensions-interface 1.3.0'a aşağıdaki yöntemler eklenmiştir:

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() uygulamanız tarafından desteklenen yakalama isteği anahtarlarını döndürür.
  • ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() yakalama sonucunda bulunan yakalama sonucu anahtarlarını döndürür.

Kamera HAL'si uzantıyı işlerse, Camera2/X yakalama sonuçlarını CameraCaptureSession.CaptureCallback dosyasında alır. Ancak işlemci uygulanırsa Camera2/X, PreviewImageProcessorImpl ve CaptureProcessorImpl içindeki process() yöntemine aktarılan ProcessResultImpl içindeki yakalama sonuçlarını alır. Yakalama sonucunu ProcessResultImpl aracılığıyla Camera2/X'e raporlamaktan siz sorumlusunuz.

Örnek olarak aşağıdaki CaptureProcessorImpl arayüzünün tanımına bakın. extensions-interface 1.3.0 veya üzeri sürümlerde ikinci process() çağrısı çağrılır:

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

Yakınlaştırma, dokunarak odaklama, flaş ve poz telafisi gibi yaygın kamera işlemleri için hem yakalama isteği hem de yakalama sonucu için aşağıdaki tuşların desteklenmesini öneririz:

  • Yakınlaştır:
    • CaptureRequest#CONTROL_ZOOM_RATIO
    • CaptureRequest#SCALER_CROP_REGION
  • Odaklanmak için dokunun:
    • CaptureRequest#CONTROL_AF_MODE
    • CaptureRequest#CONTROL_AF_TRIGGER
    • CaptureRequest#CONTROL_AF_REGIONS
    • CaptureRequest#CONTROL_AE_REGIONS
    • CaptureRequest#CONTROL_AWB_REGIONS
  • Flaş:
    • CaptureRequest#CONTROL_AE_MODE
    • CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
    • CaptureRequest#FLASH_MODE
  • Pozlama telafisi:
    • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

1.2.0 veya önceki sürümleri uygulayan Temel Genişleticiler için CameraX Extensions API, yukarıdaki anahtarların tümünü açıkça destekler. extensions-interface 1.3.0 için hem CameraX hem de Camera2 döndürülen listeyi dikkate alır ve yalnızca içinde bulunan anahtarları destekler. Örneğin, 1.3.0 uygulamasında yalnızca CaptureRequest#CONTROL_ZOOM_RATIO ve CaptureRequest#SCALER_CROP_REGION döndürmeye karar verirseniz bu, uygulama için yalnızca yakınlaştırmanın desteklendiği ancak dokunarak odaklama, flaş ve poz telafisine izin verilmediği anlamına gelir.

Gelişmiş Genişletici

Advanced Extender, Camera2 API'sini temel alan bir tür satıcı uygulamasıdır. Bu Genişletici türü, extensions-interface 1.2.0'a eklendi. Cihaz üreticisine bağlı olarak uygulama katmanında aşağıdaki faktörlere bağlı olarak uzantılar uygulanabilir:

  • Özel akış yapılandırması: RAW akışı gibi özel akışları yapılandırın veya farklı fiziksel kamera kimlikleri için birden fazla akışa sahip olun.

  • Camera2 isteklerini gönderme yeteneği: Önceki isteklerin sonuçlarına dayalı olarak parametrelerle yakalama istekleri gönderebilen karmaşık bir etkileşim mantığını destekleyin.

Advanced Extender bir sarmalayıcı veya bir ara katman sağlar; böylece akış yapılandırmasını özelleştirebilir ve isteğe bağlı olarak yakalama istekleri gönderebilirsiniz.

Uygulanacak dosyalar

Advanced Extender uygulamasına geçmek için ExtensionVersionImpl isAdvancedExtenderImplemented() yönteminin true döndürmesi gerekir. Her uzantı türü için OEM'lerin karşılık gelen Genişletici sınıflarını uygulaması gerekir. Advanced Extender uygulama dosyaları gelişmiş pakettedir.

Uygulanacak genişletici sınıflar
Gece advanced/NightAdvancedExtenderImpl.java
HDR advanced/HdrAdvancedExtenderImpl.java
Oto advanced/AutoAdvancedExtenderImpl.java
Bokeh advanced/BokehAdvancedExtenderImpl.java
Yüz Rötuşu advanced/BeautyAdvancedExtenderImpl.java

Aşağıdaki örnekte yer tutucu olarak AdvancedExtenderImpl kullanıyoruz. Bunu, uyguladığınız uzantının Extender dosyasının adıyla değiştirin.

Camera2/X'in üç uygulama akışını elde etmek için extensions-interface nasıl çağırdığını görelim.

Uygulama akışı 1: Uzantıların kullanılabilirliğini kontrol edin

AdvancedAppFlow1

Şekil 8. Advanced Extender'da uygulama akışı 1

İlk olarak uygulama, verilen uzantının desteklenip desteklenmediğini kontrol eder.

Uygulama akışı 2: Sorgu bilgileri

GelişmişAppFlow2

Şekil 9. Advanced Extender'da uygulama akışı 2

AdvancedExtenderImpl.init() öğesini çağırdıktan sonra uygulama, AdvancedExtenderImpl ile ilgili aşağıdaki bilgileri sorgulayabilir:

  • Tahmini hareketsiz yakalama gecikmesi: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() uygulamanın geçerli senaryo için uzantıyı etkinleştirmenin uygun olup olmadığını değerlendirmesi için yakalama gecikmesi aralığını döndürür.

  • Önizleme ve hareketsiz yakalama için desteklenen çözünürlükler:

    • AdvancedExtenderImpl.getSupportedPreviewOutputResolutions() önizleme yüzey formatı ve boyutu için desteklenen boyutlar listesine görüntü formatının bir haritasını döndürür. OEM'ler en azından PRIVATE formatı desteklemelidir.

    • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() sabit yakalama yüzeyi için desteklenen formatı ve boyutları döndürür. OEM'lerin hem JPEG hem de YUV_420_888 formatındaki çıktıyı desteklemesi gerekir.

    • AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() görüntü analizi için fazladan bir YUV_420_888 akışı için desteklenen boyutları döndürür. Görüntü analizi YUV yüzeyi desteklenmiyorsa getSupportedYuvAnalysisResolutions() işlevi null veya boş bir liste döndürmelidir.

  • Mevcut yakalama isteği anahtarları/sonuçları ( extensions-interface 1.3.0'da eklenmiştir): Camera2/X, uygulamanızdan desteklenen yakalama isteği anahtarlarını ve sonuç anahtarlarını almak için aşağıdaki yöntemleri çağırır:

    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
    • AdvancedExtenderImpl.getAvailableCaptureResultKeys

Daha fazla bilgi için bkz. Destek yakalama isteği anahtarları ve sonuçları .

Uygulama akışı 3: Uzantı etkinken önizleme/hareketsiz yakalama

GelişmişAppFlow3

Şekil 10. Advanced Extender'da uygulama akışı 3

Yukarıdaki diyagram, Gelişmiş Genişletici türü için önizlemeyi başlatma ve hala yakalamaya yönelik ana akışı gösterir. Her adımı gözden geçirelim.

  1. SessionProcessorImpl örneği

    Temel Advanced Extender uygulaması, özelleştirilmiş oturum yapılandırması sağlamaktan ve önizlemeyi başlatmak ve yine de isteği yakalamak için yakalama istekleri göndermekten sorumlu olan SessionProcessorImpl . AdvancedExtenderImpl.createSessionProcessor() SessionProcessorImpl örneğini döndürmek için çağrılır.

  2. initSession

    SessionProcessorImpl.initSession() uzantının oturumunu başlatır. Burası, CameraCaptureSession hazırlamak için kaynakları ayıracağınız ve bir oturum yapılandırması döndüreceğiniz yerdir.

    Giriş parametreleri için Camera2/X, önizleme, sabit yakalama ve isteğe bağlı YUV görüntü analizi için çıkış yüzeyi yapılandırmalarını belirtir. Bu çıktı yüzeyi konfigürasyonu ( OutputSurfaceImpl ), AdvancedExtenderImpl aşağıdaki yöntemlerle alınan yüzey, boyut ve görüntü formatını içerir:

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

    Camera2SessionConfigImpl örneklerinin bir listesinden ve CameraCaptureSession yapılandırmak için kullanılan oturum parametrelerinden oluşan bir Camera2OutputConfigImpl örneği döndürmeniz gerekir. Camera2/X tarafından iletilen çıkış yüzeylerine doğru kamera görüntülerinin gönderilmesi sizin sorumluluğunuzdadır. Çıkışı etkinleştirmek için bazı seçenekler şunlardır:

    • Kamera HAL'de işleme: Çıkış yüzeylerini bir SurfaceOutputConfigImpl uygulamasıyla doğrudan CameraCaptureSession ekleyebilirsiniz. Bu, sağlanan çıkış yüzeyini kamera boru hattına yapılandırır ve kamera HAL'nin görüntüyü işlemesine olanak tanır.

    • Ara ImageReader yüzeyinin işlenmesi (RAW, YUV, vb.): Ara ImageReader yüzeylerini bir ImageReaderOutputConfigImpl örneğiyle CameraCaptureSession ekleyin.

      Ara görüntüleri işleyip sonuç görüntüsünü çıktı yüzeyine yazmanız gerekiyor.

    • Camera2 yüzey paylaşımını kullanın: Başka bir Camera2OutputConfigImpl örneğinin getSurfaceSharingOutputConfigs() yöntemine herhangi bir Camera2OutputConfigImpl örneğini ekleyerek başka bir yüzeyle yüzey paylaşımını kullanın. Yüzey formatı ve boyutu aynı olmalıdır.

    SurfaceOutputConfigImpl ve ImageReaderOutputConfigImpl dahil olmak üzere tüm Camera2OutputConfigImpl , hedef yüzeyi belirtmek ve ImageReaderOutputConfigImpl görüntüyü almak için kullanılan benzersiz bir kimliğe ( getId() ) sahip olmalıdır.

  3. onCaptureSessionStart ve RequestProcessorImpl

    CameraCaptureSession başladığında ve Camera çerçevesi onConfigured() öğesini çağırdığında, Camera2/X, Camera2 istek sarmalayıcısı RequestProcessImpl ile SessionProcessorImpl.onCaptureSessionStart() çağırır. Camera2/X, yakalama isteklerini yürütmenize ve ImageReaderOutputConfigImpl kullanılıyorsa görüntüleri almanıza olanak RequestProcessImpl uygular.

    RequestProcessImpl API'leri, istekleri yürütme açısından Camera2 CameraCaptureSession API'lerine benzer. Farklılıklar şunlardır:

    • Hedef yüzey, Camera2OutputConfigImpl örneğinin kimliğiyle belirtilir.
    • ImageReader görüntüsünü alma yeteneği.

    Görüntüleri almak üzere bir ImageProcessorImpl örneğini kaydetmek için, belirtilen bir Camera2OutputConfigImpl kimliğiyle RequestProcessorImpl.setImageProcessor() öğesini çağırabilirsiniz.

    RequestProcessImpl örneği, Camera2/X SessionProcessorImpl.onCaptureSessionEnd() çağırdıktan sonra geçersiz hale gelir.

  4. Önizlemeyi başlatın ve bir resim çekin

    Advanced Extender uygulamasında, yakalama isteklerini RequestProcessorImpl arayüzü aracılığıyla gönderebilirsiniz. Camera2/X, sırasıyla SessionProcessorImpl#startRepeating ve SessionProcessorImpl#startCapture çağırarak önizleme için yinelenen isteği veya hareketsiz yakalama sırasını başlatmanız konusunda sizi bilgilendirir. Bu önizleme ve hareketsiz yakalama isteklerini karşılamak için yakalama istekleri göndermelisiniz.

    Camera2/X ayrıca yakalama isteği parametrelerini SessionProcessorImpl#setParameters aracılığıyla ayarlar. Bu istek parametrelerini (parametreler destekleniyorsa) hem yinelenen hem de tekli isteklerde ayarlamanız gerekir.

    En azından CaptureRequest.JPEG_ORIENTATION ve CaptureRequest.JPEG_QUALITY desteklemelisiniz. extensions-interface 1.3.0, aşağıdaki yöntemlerle gösterilen istek ve sonuç anahtarlarını destekler:

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

    Geliştiriciler getAvailableCaptureRequestKeys listesindeki anahtarları ayarladığında, parametreleri etkinleştirmeniz ve yakalama sonucunun getAvailableCaptureResultKeys listesindeki anahtarları içerdiğinden emin olmanız gerekir.

  5. startTrigger

    CaptureRequest.CONTROL_AF_TRIGGER ve CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER gibi tetikleyicileri başlatmak için SessionProcessorImpl.startTrigger() çağrılır. AdvancedExtenderImpl.getAvailableCaptureRequestKeys() içinde tanıtılmayan tüm yakalama isteği anahtarlarını göz ardı edebilirsiniz.

    startTrigger() extensions-interface 1.3.0'dan beri desteklenmektedir. Uygulamaların, odaklamak için dokun ve uzantılarla flaş uygulamasına olanak tanır.

  6. Temizlemek

    Bir yakalama oturumunu bitirirken, CameraCaptureSession kapatılmadan önce SessionProcessorImpl.onCaptureSessionEnd() çağrılır. Yakalama oturumu kapandıktan sonra deInitSession() temizleme işlemini gerçekleştirir.

Önizleme, hareketsiz yakalama ve görüntü analizi desteği

Uzantıyı hem önizleme hem de hareketsiz yakalama kullanım durumları için uygulamanız gerekir. Ancak gecikme, önizlemeyi sorunsuz bir şekilde gösteremeyecek kadar yüksekse uzantıyı yalnızca hareketsiz çekim için uygulayabilirsiniz.

Temel Genişletici türü için, uzantıyı önizleme için etkinleştirmeden bağımsız olarak, belirli bir uzantı için hem ImageCaptureExtenderImpl hem de PreviewExtenderImpl uygulamanız gerekir. Çoğu zaman bir uygulama, QR kodlarını veya metni bulmak gibi görüntü içeriğini analiz etmek için de bir YUV akışını kullanır. Bu kullanım durumunu daha iyi desteklemek için, CameraCaptureSession yapılandırmak için önizleme, hala yakalama ve bir YUV_420_888 akışının akış kombinasyonunu desteklemelisiniz. Bu, bir işlemci uygularsanız, üç YUV_420_888 akışının akış kombinasyonunu desteklemeniz gerektiği anlamına gelir.

Gelişmiş genişletici için kamera2/x, SessionProcessorImpl.initSession() çağrısına üç çıkış yüzeyini geçer. Bu çıkış yüzeyleri sırasıyla önizleme, hala yakalama ve görüntü analizi içindir. Önizlemenin ve hala çıkış yüzeylerinin geçerli çıkışı gösterdiğinden emin olmalısınız. Ancak, görüntü analizi çıkış yüzeyi için, yalnızca null olmadığında çalıştığından emin olun. Uygulamanız görüntü analizi akışını destekleyemiyorsa, AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() adresindeki boş bir liste döndürebilirsiniz. Bu, görüntü analizi çıkış yüzeyinin her zaman SessionProcessorImpl.initSession() da boş olmasını sağlar.

Video Yakalamasını Destekleyin

Mevcut kamera uzantısı mimarisi yalnızca önizlemeyi destekler ve hala kullanım durumlarını yakalar. Videoyu kaydetmek için MediaCodec veya MediaRecorder yüzeylerindeki uzantının etkinleştirilmesini desteklemiyoruz. Ancak, uygulamaların önizleme çıktısını kaydetmesi mümkündür.

MediaCodec ve MediaRecorder yüzeylerini desteklemek araştırılıyor.

Uzantıya özgü meta veriler

Android 14 ve üstü için, uzantıya özgü meta veriler, kamera uzantısı istemcilerinin uzantıya özgü yakalama isteği ayarlarını ve sonuçlarını ayarlamasını ve almasını sağlar. Özellikle, kamera uzantısı istemcileri, uzatma gücünü kontrol etmek için EXTENSION_STRENGTH Capture Request parametresini ve EXTENSION_CURRENT_TYPE Capture sonucunu, etkin uzantı türünü belirtmek için kullanabilir.

Talepleri yakalama

EXTENSION_STRENGTH Capture Request parametresi, işlem sonrası uzatma etkisinin gücünü kontrol eder. Karşılık gelen yakalama sonucu, bu parametre istemci tarafından açıkça ayarlanmamışsa varsayılan mukavemet değerini içerir. Bu parametre bu uzantı türleri için aşağıdaki gibi uygulanabilir:

  • BOKEH : Bulanıklık miktarını kontrol eder.
  • HDR ve NIGHT : Sızılan görüntülerin miktarını ve son görüntünün parlaklığını kontrol eder.
  • FACE_RETOUCH : Kozmetik geliştirme ve cilt yumuşatma miktarını kontrol eder.

EXTENSION_STRENGTH parametresi için desteklenen aralık 0 ila 100 arasındadır, 0 uzatma işlemini veya basit bir geçişi göstermez ve 100 işleme etkisinin maksimum uzatma mukavemetini gösterir.

EXTENSION_STRENGTH için destek eklemek için, Uzatma Kütüphanesi arayüzünün 1.3.0 sürümünde tanıtılan satıcıya özgü parametre API'lerini kullanın. Daha fazla bilgi için getAvailableCaptureRequestKeys() .

Sonuçları Yakalama

EXTENSION_CURRENT_TYPE yakalama sonucu, uzatma uygulamalarının aktif uzantı türü hakkında istemcileri bilgilendirmesini sağlar.

AUTO türü kullanan uzantılar, sahne koşullarına bağlı olarak HDR ve NIGHT gibi uzatma türleri arasında dinamik olarak geçiş yaptığından, kamera uzantıları uygulamaları, AUTO uzantının seçtiği geçerli uzantı hakkında bilgi görüntülemek için EXTENSION_CURRENT_TYPE kullanabilir.

Gerçek zamanlı hala gecikme tahminini yakalıyor

Android 14 ve üstü için, kamera uzantısı istemcileri gerçek zamanlı olarak getRealtimeStillCaptureLatency() kullanarak sahneye ve çevre koşullarına göre gecikme tahminlerini yakalayabilir. Bu yöntem, statik getEstimatedCaptureLatencyRangeMillis() yönteminden daha doğru tahminler sağlar. Gecikme tahminine dayanarak, uygulamalar uzatma işlemini atlamaya veya kullanıcıları uzun süredir devam eden bir işlem hakkında bilgilendirmek için bir gösterge görüntülemeye karar verebilir.

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

Gerçek zamanlı olarak gecikme tahminlerini yakalamak için aşağıdakileri uygulayın:

İşleme ilerleme durumu geri aramalarını yakalayın

Android 14 ve üstü için, kamera uzantısı istemcileri uzun süren işleme işlemlerini yakalama işlemlerinin ilerlemesi için geri arama alabilir. Uygulamalar, genel kullanıcı deneyimini geliştirmek için kullanıcılara mevcut ilerlemeyi görüntüleyebilir.

Uygulamalar bu özelliği entegre etmek için aşağıdaki kodu kullanabilir:

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

Yakalama işlemini desteklemek için ilerleme geri çağrılarını desteklemek için, genişletme satıcısı uygulamanız, mevcut ilerleme değeri ile aşağıdaki geri aramaları çağırmalıdır:

Postview hala yakalama

Android 14 ve üstü için, kamera uzantıları setPostviewOutputConfiguration kullanarak bir postview (önizleme resmi) sağlayabilir. Kullanıcı deneyimini geliştirmek için, bir uzatma artan işleme gecikmesi yaşadığında uygulamalar bir Postview görüntüsünü yer tutucu olarak görüntüleyebilir ve son görüntü mevcut olduğunda görüntüyü değiştirebilir. Uygulamalar, aşağıdaki referans kodu kullanarak Postview -Gözlem yakalama isteklerini yapılandırabilir ve yayınlayabilir:

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

Postview PostView hala yakalamayı desteklemek için satıcı uygulamanızın aşağıdakileri uygulaması gerekir:

SurfaceView çıktısını destekleyin

Android 14 ve üstü için, kamera uzantısı istemcileri, istekleri tekrarlamak için önizleme çıktısı için bir SurfaceView örneği kaydederek güç ve performans optimize edilmiş önizleme yollarını kullanabilir.

SurfaceView çıktısını desteklemek için, satıcı uzantısı uygulamanızın SurfaceView örneklerine önizleme akışı ve çıktı yapabilmelidir. Bunun desteklendiğini doğrulamak için SurfaceViewExtensionPreviewTest.java CTS modülünü çalıştırın.

Satıcıya özgü oturum türleri

Özellik, satıcı uzantısı uygulamalarının varsayılan değer yerine dahili kamera yakalama oturumunda ayarlanacak bir satıcı özel oturum türü seçmesini sağlar.

Özellik tamamen çerçeve ve satıcı yığını içinde çalışır ve müşteri/kamuya açık görünür API etkisi yoktur.

Satıcıya özgü bir oturum türü seçmek için, uzatma kitaplıklarınız için aşağıdakileri uygulayın: * ExtenderStateListener.onSessionType() için * Camera2SessionConfigImpl.getSessionType() Gelişmiş uzantılar için

Uzatma Arayüzü Sürüm Geçmişi

Aşağıdaki tabloda kamera uzantısı arayüzü sürüm geçmişini göstermektedir. Satıcı kütüphanesini her zaman en son sürümle uygulamalısınız.

Sürüm Eklenen özellikler
1.0.0
  • Sürüm doğrulaması
    • ExtensionVersionImpl
  • Temel Genişletici
    • PreviewExtenderImpl
    • ImageCaptureExtenderImpl
    • Processor
      • PreviewImageProcessorImpl
      • CaptureProcessorImpl
      • RequestUpdateProcessorImpl
1.1.0
  • Kütüphane Başlatma
    • InitializerImpl
  • Desteklenen kararları ortaya çıkarın
    • PreviewExtenderImpl.getSupportedResolutions
    • ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0
  • AdvancedExtender
    • AdvancedExtenderImpl
    • SessionProcessorImpl
  • Tahmini yakalama gecikmesini alın
    • ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0
  • Desteklenen Yakalama İsteği Anahtarlarını Ortaya Çıkarın/Sonuçlar
    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys ve getAvailableCaptureResultKeys
    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys ve getAvailableCaptureResultKeys
    • Yeni process() PreviewImageProcessorImpl ve CaptureProcessorImpl ProcessResultImpl alan çağrı
    • Destek tetik türü isteği
      • AdvancedExtenderImpl.startTrigger
1.4.0
  • Uzantıya özgü meta veriler
  • Dinamik hala gecikme tahminlerini yakalar
  • İşleme ilerleme durumu geri aramalarını yakalayın
  • Postview hala yakalama
  • SurfaceView çıktısı için destek
  • Satıcıya özgü oturum türleri

Referans uygulaması

Aşağıdaki referans OEM satıcı kütüphanesi uygulamaları frameworks/ex .

  • advancedSample : Advanced Extender'ın temel uygulaması.

  • sample : Temel genişleticinin temel uygulaması.

  • service_based_sample : Bir Service kamera uzantılarının nasıl barındırılacağını gösteren bir uygulama. Bu uygulama aşağıdaki bileşenleri içerir:

    • oem_library : Kamera2 ve kamerax uzantıları API'leri için bir kamera uzantıları OEM kütüphanesi, Extensions-Interface uygulayan. Bu, çağrıları Extensions-Interface hizmete ileten bir geçit görevi görür. Bu kütüphane aynı zamanda hizmetle iletişim kurmak için AIDL dosyaları ve sarıcı sınıfları sağlar.

      Gelişmiş genişletici varsayılan olarak etkinleştirilir. Temel genişleticiyi etkinleştirmek için, ExtensionsVersionImpl#isAdvancedExtenderImplemented false döndürmek için değiştirin.

    • extensions_service : Uzantılar hizmetinin örnek bir uygulaması. Uygulamanızı buraya ekleyin. Hizmette uygulanacak arayüz, Extensions-Interface benzer. Örneğin, IAdvancedExtenderImpl.Stub uygulanması, AdvancedExtenderImpl ile aynı işlemleri gerçekleştirir. ImageWrapper ve TotalCaptureResultWrapper Image ve TotalCaptureResult parsellenebilir hale getirmek için gereklidir.

Satıcı kitaplığını bir cihaza ayarlayın

OEM satıcı kütüphanesi bir uygulamaya yerleştirilmemiştir; Cihazdan çalışma zamanında kamera2/x ile yüklenir. Camerax'ta, <uses-library> Tag, androidx.camera.extensions.impl kütüphanesinin, camera-extensions kütüphanesinin AndroidManifest.xml dosyasında tanımlanan ve kamerax'ın bir bağımlılığı olduğunu ve çalışma zamanında yüklenmesi gerektiğini bildirir. Kamera2'de, çerçeve androidx.camera.extensions.impl <uses-library> yüklediğini bildiren bir uzantılar hizmeti yükler.

Bu, OEM satıcı kütüphanesini otomatik olarak yüklemek için uzantılar kullanan üçüncü taraf uygulamaların izin verir. OEM kütüphanesi isteğe bağlı olarak işaretlenmiştir, böylece uygulamalar cihazda kütüphaneye sahip olmayan cihazlarda çalışabilir. Kamera2/X, bir uygulama, cihaz üreticisi OEM kütüphanesini uygulama tarafından keşfedilebilmesi için cihaza yerleştirdiği sürece bir kamera uzantısı kullanmaya çalıştığında bu davranışı otomatik olarak işler.

OEM kütüphanesini bir cihaza ayarlamak için aşağıdakileri yapın:

  1. Aşağıdaki biçimi kullanarak <uses-library> etiketi tarafından gereken bir izin dosyası ekleyin: /etc/permissions/ ANY_FILENAME .xml . Örneğin, /etc/permissions/camera_extensions.xml . Bu dizindeki dosyalar, <uses-library> adlı kütüphanenin cihazdaki gerçek dosya yoluna eşlemesini sağlar.

  2. Dosyaya gerekli bilgileri eklemek için aşağıdaki örneği kullanın.

    • name androidx.camera.extensions.impl olmalıdır, çünkü Camerax'ın aradığı kütüphane.
    • file , uzantılar uygulamasını içeren dosyanın mutlak yoludur (örneğin, /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>

Android 12 veya daha yüksekte, Camerax uzantılarını destekleyen cihazların ro.camerax.extensions.enabled özelliğine sahip olması gerekir, bu da bir cihazın uzantıları destekleyip desteklemediğini sorgulamaya izin veren true olarak ayarlanmıştır. Bunu yapmak için, cihaza aşağıdaki satırı ekleyin Dosya yapın:

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

Doğrulama

Geliştirme aşamasında OEM satıcı kütüphanesinin uygulanmasını test etmek için, çeşitli satıcı uzantılarından geçen androidx-main/camera/integration-tests/extensionstestapp/ adresindeki örnek uygulamayı kullanın.

Uygulamanızı tamamladıktan sonra, satıcı kitaplığının doğru uygulandığını doğrulamak için otomatik ve manuel testleri çalıştırmak için kamera uzantıları doğrulama aracını kullanın.

Kamera uzantılarına karşı genişletilmiş sahne modu

Bokeh uzantısı için, kamera uzantılarını kullanarak açığa çıkarmanın yanı sıra, CONTROL_EXTENDED_SCENE_MODE tuşundan etkinleştirilen genişletilmiş sahne modunu kullanarak uzantıyı ortaya çıkarabilirsiniz. Daha fazla uygulama detayı için bkz. Kamera Bokeh .

Genişletilmiş sahne modu, kamera2 uygulamaları için kamera uzantılarına kıyasla daha az kısıtlamaya sahiptir. Örneğin, esnek akış kombinasyonlarını destekleyen ve istek parametrelerini yakalayan normal bir CameraCaptureSession örneğinde genişletilmiş sahne modunu etkinleştirebilirsiniz. Buna karşılık, kamera uzantıları yalnızca sabit bir akış türü kümesini destekler ve yakalama isteği parametreleri için sınırlı desteğe sahiptir.

Genişletilmiş sahne modunun bir dezavantajı, bunu yalnızca kamera halına uygulayabilmenizdir, bu da uygulama geliştiricileri için mevcut tüm dikey kontrollerde çalışmanın doğrulanması gerektiği anlamına gelir.

Bokeh'i hem genişletilmiş sahne modunu hem de kamera uzantılarını kullanarak maruz bırakmanızı öneririz, çünkü uygulamalar Bokeh'i etkinleştirmek için belirli bir API kullanmayı tercih edebilir. Önce genişletilmiş sahne modunu kullanmanızı öneririz, çünkü bu, bokeh uzantısını etkinleştirmek için uygulamaların en esnek yoludur. Ardından, genişletilmiş sahne moduna göre kamera uzantıları arayüzünü uygulayabilirsiniz. Örneğin, kamera halına bokeh uygulamak zorsa, görüntüleri işlemek için uygulama katmanında çalışan bir post işlemci gerektirdiğinden, kamera uzantıları arabirimini kullanarak bokeh uzantısını uygulamanızı öneririz.

Sık sorulan sorular (SSS)

API seviyelerinde herhangi bir kısıtlama var mı?

Evet. Bu, OEM satıcı kütüphanesi uygulamasının gerektirdiği Android API özellik setine bağlıdır. Örneğin, ExtenderStateListener.onPresetSession() bir temel etiket kümesi ayarlamak için SessionConfiguration.setSessionParameters() çağrısını kullanır. Bu çağrı yalnızca API Seviye 28 ve üstünde mevcuttur. Belirli arabirim yöntemleri hakkında ayrıntılar için bkz. API Referans Belgeleri .