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ştiricilere sunabilir. Geliştiriciler, OEM tedarikçi kitaplığında uygulanan uzantılara erişmek için Camera2 Extensions API ve CameraX Extensions API'yi kullanabilir.

Camera2 ve CameraX'te aynı olan desteklenen uzantıların listesi için CameraX Extensions API başlıklı makaleyi inceleyin. Uzantı eklemek istiyorsanız Sorun İzleyici ile hata kaydı oluşturun.

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

Mimari

Aşağıdaki şemada, Camera Extensions arayüzünün veya extensions-interface'nın mimarisi açıklanmaktadır:

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

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

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

OEM tedarikçi 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ılı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 uzantısı sınıfları (Gece uzantısı destekleniyorsa uygulayın)

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

Otomatik genişletici sınıflar (Otomatik uzantı 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şu genişletici sınıfları (Yüz rötuşu 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 uygulama sağlamanız gerekmez. Bir uzantı uygulamıyorsanız isExtensionAvailable() değerini false döndürecek şekilde ayarlayın veya ilgili Extender sınıflarını kaldırın. Camera2 ve CameraX Extensions API'leri, uzantının kullanılamadığını uygulamaya bildirir.

Camera2 ve CameraX Extensions API'lerinin, uzantıyı etkinleştirmek için tedarikçi kitaplığıyla nasıl etkileşime girdiğini inceleyelim. Aşağıdaki diyagramda, örnek olarak Night uzantısı kullanılarak uçtan uca akış gösterilmektedir:

Şekil 2. Gece uzantısı uygulaması

1. Sürüm doğrulama:

   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() çağrılarını yapar.

2. Tedarikçi kitaplığı başlatma:

   InitializerImpl, tedarikçi 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. Genişletici sınıfları örneklendirme:

   Uzantı için Extender sınıflarını oluşturur. İki tür uzatma vardır: Temel Uzatma ve Gelişmiş Uzatma. Tüm uzantılar için bir Genişletici türü uygulamanız gerekir. Daha fazla bilgi için Temel Uzatma ve Gelişmiş Uzatma başlıklı makaleyi inceleyin.

   Camera2/X, bilgileri almak ve uzantıyı etkinleştirmek için Extender sınıflarını oluşturur ve bunlarla etkileşime girer. Belirli bir uzantı için Camera2/X, Extender sınıflarını birden çok kez başlatabilir. Bu nedenle, oluşturucuda veya init() çağrısında ağır başlatma işlemleri yapmayın. Yalnızca kamera oturumu başlamak üzereyken (ör. Basic Extender'da onInit() veya Advanced Extender'da initSession() çağrıldığında) ağır işlemleri yapın.

   Gece uzantısı için aşağıdaki Extender sınıfları, Basic Extender türü için oluşturulur:

   • NightImageCaptureExtenderImpl.java
   • NightPreviewExtenderImpl.java

   Gelişmiş uzatma türü için:

   • NightAdvancedExtenderImpl.java

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

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

5. Genişleticiyi kamera bilgileriyle başlatma:

   Camera2/X, Extender örneğinde init() işlevini çağırır ve kamera kimliğini (cameraID) ve CameraCharacteristics değerini bu işlevin bağımsız değişkeni olarak iletir.

6. Sorgu bilgileri:

   Uzantıyı etkinleştirmeye hazırlanırken desteklenen çözünürlükler, tahmini gecikmeyi yakalama ve uzantıdan istek anahtarlarını yakalama gibi bilgileri almak için Extender sınıfını çağırır.

7. Uzantıyı genişleticide etkinleştirme:

   Extender sınıfı, sınıfın etkinleştirilmesi için gereken tüm arayüzleri sağlar. Bu API, yakalama isteği parametrelerini yerleştirme veya bir post işlemciyi etkinleştirme gibi OEM uygulamalarını Camera2 ardışık düzenine bağlamak için bir mekanizma sunar.

   Gelişmiş Uzatma türünde, Camera2/X, uzantıyı etkinleştirmek için SessionProcessorImpl ile etkileşime girer. Camera2/X, Extender üzerinde createSessionProcessor() ç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 tedarikçi kitaplığı, çalışma zamanında cihazdan yüklenirken Camera2/X kitaplığın extensions-interface sürümüyle uyumlu olup olmadığını doğrular. extensions-interface, anlamsal sürüm oluşturma (ör. 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 ExtensionVersionImpl.checkApiVersion() sürümüyle extensions-interface çağrı yapar. Camera2/X, uzantının etkinleştirilip etkinleştirilemeyeceğini ve hangi özelliklerin çağrılması gerektiğini belirlemek için OEM kitaplığı tarafından bildirilen sürümü kullanır.

Ana sürüm uyumluluğu

extension-interface'in ana sürümleri Camera2/X ile tedarikçi kitaplığı arasında farklıysa uyumsuz olarak 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şturulan OEM tedarikçi kitaplıklarıyla geriye dönük uyumluluk sağlar. Örneğin, Camera2/X extensions-interface 1.3.0'ı destekliyorsa 1.0.0, 1.1.0 ve 1.2.0'ı uygulayan OEM satıcı kitaplıkları hâlâ uyumludur. Bu, belirli bir tedarikçi kitaplığı 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 tedarikçi kitaplıklarıyla ileri uyumluluk, OEM olarak size bağlıdır. Uzantıları uygulamak için bazı özelliklere ihtiyacınız varsa uzantıları belirli bir sürümden itibaren etkinleştirebilirsiniz. Bu durumda, Camera2/X kitaplık sürümü şartları karşıladığında desteklenen extensions-interface sürümünü 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.

Tedarikçi kitaplığı başlatma

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

Camera2/X, OEM kitaplığı OnExtensionsInitializedCallback.onSuccess()'yı çağırarak başlatma işleminin tamamlandığını bildirene kadar sürüm kontrolü dışında OEM kitaplığına başka çağrı yapmaz.

extensions-interface 1.1.0 itibarıyla InitializerImpl uygulamanız gerekir. OEM tedarikçi kitaplığı extensions-interface 1.0.0'ı uyguluyorsa Camera2/X, kitaplık başlatma adımını atlar.

Temel uzatma aparatı ve gelişmiş uzatma aparatı karşılaştırması

İki tür extensions-interface uygulama vardır: Temel Genişletici ve Gelişmiş Genişletici. Gelişmiş Genişletici, extensions-interface 1.2.0 sürümünden beri desteklenmektedir.

Kamera HAL'sinde görüntü işleyen veya YUV akışlarını işleyebilen bir son işlemci kullanan uzantılar için Basic Extender'ı uygulayın.

Camera2 akış yapılandırmasını özelleştirmesi ve gerektiğinde yakalama istekleri göndermesi gereken uzantılar için Advanced Extender'ı uygulayın.

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

Uygulama akışları

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

Basic Extender

Basic Extender arayüzü, kamera ardışık düzenindeki çeşitli yerlere kancalar sağlar. Her uzantı türünün, OEM'lerin uygulaması gereken karşılık gelen Extender sınıfları vardır.

Aşağıdaki tabloda, OEM'lerin her uzantı için uygulaması gereken Extender sınıfları listelenmiştir:

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

Basic Extender'ın özellikleri şunlardır:

• CameraCaptureSession ( onPresetSession) yapılandırılırken oturum parametrelerini ekleyin.
• Yakalama oturumu başlatma ve kapatma etkinlikleri hakkında sizi bilgilendirir ve döndürülen parametrelerle (onEnableSession, onDisableSession) HAL'yi bilgilendirmek için tek bir istek gönderir.
• İsteğe yakalama parametreleri ekleyin (PreviewExtenderImpl.getCaptureStage, ImageCaptureExtenderImpl.getCaptureStages).
• YUV_420_888 akışını işleyebilen önizleme ve fotoğraf çekimi için işlemciler ekleyin.

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

1. uygulama akışı: Uzantının kullanılabilirliğini kontrol etme

Şekil 3. Temel genişleticideki 1. uygulama akışı

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

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 etmek üzere attığı ilk adımdır. Bunun nedeni, bazı uzantıların yalnızca belirli kamera kimliklerinde desteklenmesidir.

Uygulama akışı 2: Bilgi sorgulama

Şekil 4. Temel uzatıcıda 2. uygulama akışı

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

• Still capture latency range: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange, uzantının mevcut senaryo için etkinleştirilmesinin uygun olup olmadığını değerlendirmek üzere uygulamanın yakalama gecikmesi aralığını döndürür.

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

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

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
  • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X, daha fazla bilgi sorgulamadan önce bu Extender sınıflarında her zaman önce init() işlevini çağırır.

Uygulama akışı 3: Uzantı etkin durumdayken önizleme/durağan görüntü yakalama (HAL uygulaması)

Şekil 5. Temel uzantıda 3. uygulama akışı

Yukarıdaki şema, işlemci içermeyen bir uzantıyla önizleme ve hareketsiz görüntü yakalama özelliğini etkinleştirmenin ana akışını gösterir. Bu, uzantının kamera HAL'si tarafından işlendiği anlamına gelir.

Bu akışta Camera2/X önce init(), ardından onInit'i çağırır. Bu işlem, belirtilen uzantılarla bir kamera oturumunun başlamak üzere olduğunu bildirir. Ağır yükleme başlatma işlemini onInit() içinde yapabilirsiniz.

CameraCaptureSession yapılandırılırken Camera2/X, oturum parametrelerini almak için onPresetSession çağrısında bulunur. Çekim oturumu başarıyla yapılandırıldıktan sonra Camera2/X, çekim parametrelerini içeren bir CaptureStageImpl örneği döndürerek onEnableSession öğesini çağırır. Camera2/X, HAL'yi bilgilendirmek için bu yakalama parametreleriyle tek bir isteği hemen gönderir. Benzer şekilde, yakalama oturumu kapatılmadan önce Camera2/X, onDisableSession işlevini ç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 görüntü yakalama isteği, ImageCaptureExtenderImpl.getCaptureStages() tarafından döndürülen parametreleri içerir.

Son olarak, kamera oturumu bittikten sonra Camera2/X onDeInit() işlevini çağırır. onDeinit() ile kaynakları serbest bırakabilirsiniz.

Önizleme işlemcisi

Kamera HAL'sine ek olarak, işlemcide de uzantılar uygulayabilirsiniz.

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

• PROCESSOR_TYPE_NONE: İşlemci yok. Resimler, kamera HAL'sinde işlenir.

• PROCESSOR_TYPE_REQUEST_UPDATE_ONLY: İşlemci türü, TotalCaptureResult'e göre yeni yakalama isteği parametreleriyle tekrarlanan isteği güncellemenize olanak tanır.

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

• PROCESSOR_TYPE_IMAGE_PROCESSOR: Bu tür, YUV_420_888 görüntüleri işlemek ve çıkışı PRIVATE yüzeyine yazmak için bir işleyici uygulamanıza olanak tanır.

  PreviewExtenderImpl.getProcessor içinde bir PreviewImageProcessorImpl örneği uygulamanız ve döndürmeniz gerekir. İşlemci, YUV_420_888 giriş resimlerinin işlenmesinden sorumludur. Çıkışı, önizlemenin PRIVATE biçiminde yazmalıdır. Camera2/X, önizleme için CameraCaptureSession yapılandırmak üzere PRIVATE yerine YUV_420_888 yüzeyini kullanır.

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

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

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

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

• onResolutionUpdate(Size size) giriş resminin boyutunu ayarlar.

• onImageFormatUpdate(int imageFormat), giriş resminin resim biçimini ayarlar. Şu anda yalnızca YUV_420_888 olabilir.

Görüntü yakalama işlemcisi

Hareketsiz yakalama için ImageCaptureExtenderImpl.getCaptureProcessor kullanarak CaptureProcessorImpl örneği döndürerek bir işlemci uygulayabilirsiniz. İşlemci, yakalanan YUV_420_888 resimlerin ve TotalCaptureResult örneklerin listesini işlemekten ve çıkışı bir YUV_420_888 yüzeye yazmaktan sorumludur.

Hareketsiz görüntü yakalama isteğini göndermeden önce önizlemenin etkinleştirildiğini ve çalıştığını güvenle varsayabilirsiniz.

Aşağıdaki şemada akışı görebilirsiniz:

Şekil 7. CaptureProcessorImpl ile akış yakalamaya devam etme

1. Camera2/X, yakalama oturumunu yapılandırmak için hareketsiz yakalamada YUV_420_888 biçimli bir yüzey kullanır. Camera2/X, CaptureProcessorImpl öğesini şu işlevi çağırarak hazırlar:

   • YUV_420_888 ile CaptureProcessorImpl.onImageFormatUpdate().
   • CaptureProcessorImpl.onResolutionUpdate() ile giriş resmi boyutu.
   • CaptureProcessorImpl.onOutputSurface() çıkış YUV_420_888 yüzeyiyle.

2. ImageCaptureExtenderImpl.getCaptureStages, CaptureStageImpl listesini döndürür. Her öğe, Camera2/X tarafından gönderilen yakalama parametrelerine sahip bir CaptureRequest örneğiyle eşlenir. Örneğin, üç CaptureStageImpl örneğinin listesini döndürürse Camera2/X, captureBurst API'sini kullanarak ilgili yakalama parametreleriyle üç yakalama isteği gönderir.

3. Alınan resimler ve TotalCaptureResult örnekleri birlikte paketlenir ve işlenmek üzere CaptureProcessorImpl'e gönderilir.

4. CaptureProcessorImpl, sonucu onOutputSurface() çağrısıyla belirtilen çıkış yüzeyine (YUV_420_888 biçiminde) yazar. Camera2/X, gerekirse bu dosyayı JPEG resimlerine dönüştürür.

İstek anahtarlarını ve sonuçlarını yakalamayı destekleme

Uygulamalar, kamera önizlemesi ve çekiminin yanı sıra yakınlaştırma, flaş parametrelerini ayarlayabilir veya dokunarak odaklanma özelliğini tetikleyebilir. Bu parametreler, uzantı uygulamanızla uyumlu olmayabilir.

Uygulamanızın desteklediği parametreleri kullanıma sunmanıza olanak tanımak için extensions-interface 1.3.0 sürümüne 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'ı uzantıyı işlerse Camera2/X, yakalama sonuçlarını CameraCaptureSession.CaptureCallback içinde alır. Ancak işlemci uygulanırsa Camera2/X, yakalama sonuçlarını ProcessResultImpl içinde alır. Bu sonuçlar, PreviewImageProcessorImpl ve CaptureProcessorImpl içindeki process() yöntemine iletilir. Yakalanan sonucu ProcessResultImpl aracılığıyla Camera2/X'e bildirmek sizin sorumluluğunuzdadır.

Örnek olarak aşağıdaki CaptureProcessorImpl arayüzünün tanımına bakın. extensions-interface 1.3.0 veya sonraki sürümlerde ikinci process() çağrısı başlatı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, odaklanmak için dokunma, flaş ve pozlama telafisi gibi yaygın kamera işlemleri için hem yakalama isteği hem de yakalama sonucu için aşağıdaki anahtarların desteklenmesini öneririz:

• Yakınlaştırma:
  • CaptureRequest#CONTROL_ZOOM_RATIO
  • CaptureRequest#SCALER_CROP_REGION
• Odaklamak için dokunma:
  • CaptureRequest#CONTROL_AF_MODE
  • CaptureRequest#CONTROL_AF_TRIGGER
  • CaptureRequest#CONTROL_AF_REGIONS
  • CaptureRequest#CONTROL_AE_REGIONS
  • CaptureRequest#CONTROL_AWB_REGIONS
• Flash:
  • 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 tüm anahtarları açıkça destekler. 1.3.0 sürümünde hem CameraX hem de Camera2, döndürülen listeyi dikkate alır ve yalnızca listede yer alan anahtarları destekler.extensions-interface Örneğin, 1.3.0 uygulamasında yalnızca CaptureRequest#CONTROL_ZOOM_RATIO ve CaptureRequest#SCALER_CROP_REGION işlevlerini döndürmeye karar verirseniz bu, uygulamada yalnızca yakınlaştırmanın desteklendiği, dokunarak odaklama, flaş ve pozlama telafisinin ise kullanılamayacağı anlamına gelir.

Advanced Extender

Gelişmiş Genişletici, Camera2 API'ye dayalı bir tedarikçi uygulaması türüdür. Bu Extender türü extensions-interface 1.2.0 sürümünde eklendi. Uzantılar, cihaz üreticisine bağlı olarak uygulama katmanında uygulanabilir. Bu durum aşağıdaki faktörlere bağlıdır:

• Ö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ış kullanın.

• Camera2 istekleri gönderme özelliği: Önceki isteklerin sonuçlarına göre parametrelerle yakalama istekleri gönderebilen karmaşık bir etkileşim mantığını destekler.

Advanced Extender, akış yapılandırmasını özelleştirebilmeniz ve gerektiğinde yakalama istekleri gönderebilmeniz için bir sarmalayıcı veya ara katman sağlar.

Uygulanacak dosyalar

Gelişmiş genişletici uygulamasına geçmek için ExtensionVersionImpl içindeki isAdvancedExtenderImplemented() yöntemi true değerini döndürmelidir. OEM'ler, her uzantı türü için ilgili Extender sınıflarını uygulamalıdır. Gelişmiş Genişletici uygulama dosyaları advanced paketinde bulunur.

Aşağıdaki örnekte yer tutucu olarak AdvancedExtenderImpl kullanılmıştır. Bu ifadeyi, uyguladığınız uzantının Extender dosyasının adıyla değiştirin.

Üç uygulama akışını elde etmek için Camera2/X'in extensions-interface'ı nasıl çağırdığına bakalım.

1. uygulama akışı: Uzantıların kullanılabilirliğini kontrol etme

Şekil 8. Gelişmiş Genişletici'de 1. uygulama akışı

Öncelikle, uygulama belirtilen uzantının desteklenip desteklenmediğini kontrol eder.

Uygulama akışı 2: Bilgi sorgulama

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

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

• Tahmini hareketsiz görüntü yakalama gecikmesi: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange(), uzantının mevcut senaryo için etkinleştirilmesinin uygun olup olmadığını değerlendirmek üzere uygulamanın yakalama gecikmesi aralığını döndürür.

• Önizleme ve fotoğraf çekme için desteklenen çözünürlükler:

  • AdvancedExtenderImpl.getSupportedPreviewOutputResolutions(), önizleme yüzeyi biçimi ve boyutu için desteklenen boyut listelerine yönelik bir resim biçimi haritası döndürür. OEM'ler en az PRIVATE biçimini desteklemelidir.

  • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions(), fotoğraf çekme yüzeyi için desteklenen biçimi ve boyutları döndürür. OEM'ler hem JPEG hem de YUV_420_888 biçiminde çıkışı desteklemelidir.

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

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

  • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
  • AdvancedExtenderImpl.getAvailableCaptureResultKeys

Daha fazla bilgi için Destek yakalama isteği anahtarları ve sonuçları başlıklı makaleyi inceleyin.

Uygulama akışı 3: Uzantı etkin durumdayken önizleme/durağan görüntü yakalama

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

Yukarıdaki şemada, Gelişmiş Uzatıcı türü için önizlemeyi başlatma ve fotoğraf çekme ile ilgili ana akış gösterilmektedir. Her adımı inceleyelim.

1. SessionProcessorImpl örneği

   Temel Gelişmiş Genişletici uygulaması, SessionProcessorImpl içinde yer alır. Bu, özelleştirilmiş oturum yapılandırması sağlamaktan ve önizleme ve hareketsiz yakalama isteğini başlatmak için yakalama istekleri göndermekten sorumludur. AdvancedExtenderImpl.createSessionProcessor() örneğini döndürmek için SessionProcessorImpl çağrılır.

2. initSession

   SessionProcessorImpl.initSession() uzantı için oturumu başlatır. Burada kaynak ayırır ve CameraCaptureSession hazırlamak için bir oturum yapılandırması döndürürsünüz.

   Giriş parametreleri için Camera2/X, önizleme, fotoğraf çekme ve isteğe bağlı YUV görüntü analizi için çıkış yüzeyi yapılandırmalarını belirtir. Bu çıkış yüzeyi yapılandırması (OutputSurfaceImpl), AdvancedExtenderImpl içinde aşağıdaki yöntemlerle alınan yüzeyi, boyutu ve resim biçimini içerir:

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

   Camera2SessionConfigImpl örneği döndürmeniz gerekir. Bu örnek, Camera2OutputConfigImpl örneklerinin listesinden ve CameraCaptureSession yapılandırması için kullanılan oturum parametrelerinden oluşur. Camera2/X tarafından iletilen çıkış yüzeylerine doğru kamera görüntülerini çıkış olarak verme sorumluluğu size aittir. Çıkışı etkinleştirmek için kullanabileceğiniz seçeneklerden bazıları şunlardır:

   • Kamera HAL'de işleme: Çıkış yüzeylerini doğrudan CameraCaptureSession'ye SurfaceOutputConfigImpl uygulamasıyla ekleyebilirsiniz. Bu, sağlanan çıkış yüzeyini kamera ardışık düzenine göre yapılandırır ve kamera HAL'ının görüntüyü işlemesine olanak tanır.

   • Ara ImageReader yüzeyini (RAW, YUV vb.) işleme: Ara ImageReader yüzeylerini ImageReaderOutputConfigImpl örneğiyle CameraCaptureSession'ye ekleyin.

     Ara görüntüleri işlemeniz ve sonuç görüntüsünü çıkış yüzeyine yazmanız gerekir.

   • Camera2 yüzey paylaşımını kullanma: Başka bir yüzeyle yüzey paylaşımı yapmak için başka bir Camera2OutputConfigImpl örneğinin getSurfaceSharingOutputConfigs() yöntemine herhangi bir Camera2OutputConfigImpl örneği ekleyin. Yüzey biçimi ve boyutu aynı olmalıdır.

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

3. onCaptureSessionStart ve RequestProcessorImpl

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

   RequestProcessImpl API'leri, isteklerin yürütülmesi açısından Camera2 CameraCaptureSession API'lerine benzer. Farklar şunlardır:

   • Hedef yüzey, Camera2OutputConfigImpl örneğinin kimliğiyle belirtilir.
   • ImageReader resmini alma özelliği.

   Resim almak için ImageProcessorImpl örneğini kaydetmek üzere belirtilen Camera2OutputConfigImpl kimliğiyle RequestProcessorImpl.setImageProcessor() işlevini çağırabilirsiniz.

   RequestProcessImpl örneği, Camera2/X çağrılarından sonra geçersiz hale geliyor SessionProcessorImpl.onCaptureSessionEnd().

4. Önizlemeyi başlatma ve fotoğraf çekme

   Gelişmiş uzantı uygulamasında, RequestProcessorImpl arayüzü üzerinden yakalama istekleri gönderebilirsiniz. Camera2/X, sırasıyla SessionProcessorImpl#startRepeating ve SessionProcessorImpl#startCapture çağrılarını yaparak önizleme için tekrarlanan isteği veya hareketsiz görüntü yakalama dizisini başlatmanızı bildirir. Bu önizleme ve hareketsiz görüntü yakalama isteklerini karşılamak için yakalama istekleri göndermeniz gerekir.

   Camera2/X, yakalama isteği parametrelerini de SessionProcessorImpl#setParameters üzerinden ayarlar. Bu istek parametrelerini (parametreler destekleniyorsa) hem tekrarlanan hem de tek isteklerde ayarlamanız gerekir.

   En az CaptureRequest.JPEG_ORIENTATION ve CaptureRequest.JPEG_QUALITY'ı desteklemeniz gerekir. extensions-interface 1.3.0, aşağıdaki yöntemlerle kullanıma sunulan istek ve sonuç anahtarlarını destekler:

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

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

5. startTrigger

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

   startTrigger(), extensions-interface 1.3.0 sürümünden beri desteklenmektedir. Uygulamaların, uzantılarla dokunarak odaklanma ve flaş özelliklerini kullanmasını sağlar.

6. Temizleme

   Bir yakalama oturumu tamamlandığında, kapatma işleminden önce SessionProcessorImpl.onCaptureSessionEnd() çağrılır. CameraCaptureSession Yakalama oturumu kapatıldıktan sonra deInitSession() temizleme işlemini gerçekleştirir.

Önizleme, fotoğraf çekme ve görüntü analizini destekler.

Uzantıyı hem önizleme hem de hareketsiz yakalama kullanım alanları için uygulamalısınız. Ancak gecikme süresi önizlemeyi sorunsuz bir şekilde göstermeyecek kadar yüksekse uzantıyı yalnızca hareketsiz yakalama için uygulayabilirsiniz.

Temel uzatma türünde, uzantının önizleme için etkinleştirilip etkinleştirilmediğine bakılmaksızın, belirli bir uzantı için hem ImageCaptureExtenderImpl hem de PreviewExtenderImpl öğesini uygulamanız gerekir. Uygulamalar genellikle QR kodlarını veya metinleri bulma gibi görüntü içeriklerini analiz etmek için de YUV akışını kullanır. Bu kullanım alanını daha iyi desteklemek için , önizleme, hareketsiz görüntü yakalama ve YUV_420_888 akışının CameraCaptureSession yapılandırması için akış kombinasyonunu desteklemeniz gerekir. Bu, bir işlemci uygulamanız durumunda üç YUV_420_888 akışının akış kombinasyonunu desteklemeniz gerektiği anlamına gelir.

Gelişmiş Uzatıcı'da Camera2/X, SessionProcessorImpl.initSession() çağrısına üç çıkış yüzeyi iletir. Bu çıkış yüzeyleri sırasıyla önizleme, anlık görüntü ve görüntü analizi için kullanılır. Önizleme ve hareketsiz görüntü yakalama çıkış yüzeylerinin geçerli çıkışı gösterdiğinden emin olmanız gerekir. Ancak görüntü analizi çıkış yüzeyi için yalnızca boş olmayan durumlarda çalıştığından emin olun. Uygulamanız resim analizi akışını desteklemiyorsa AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() içinde boş bir liste döndürebilirsiniz. Bu, SessionProcessorImpl.initSession()'da görüntü analizi çıkış yüzeyinin her zaman boş olmasını sağlar.

Video yakalamayı destekleme

Mevcut kamera uzantısı mimarisi yalnızca önizleme ve fotoğraf çekme kullanım alanlarını destekler. Videonun kaydedilmesi için uzantının MediaCodec veya MediaRecorder yüzeylerinde etkinleştirilmesini desteklemiyoruz. Ancak uygulamaların önizleme çıkışını kaydetmesi mümkündür.

MediaCodec ve MediaRecorder yüzeylerinin desteklenmesi araştırılmaktadır.

Uzantıya özgü meta veriler

Android 14 ve sonraki sürümlerde, uzantıya özgü meta veriler sayesinde kamera uzantısı istemcileri, uzantıya özgü çekim isteği ayarlarını ve sonuçlarını ayarlayıp alabilir. Daha net bir ifadeyle, kamera uzantısı istemcileri, uzantı gücünü kontrol etmek için EXTENSION_STRENGTH yakalama isteği parametresini ve etkinleştirilen uzantı türünü belirtmek için EXTENSION_CURRENT_TYPE yakalama sonucunu kullanabilir.

İstekleri yakalama

EXTENSION_STRENGTH Yakalama isteği parametresi, uzantıdaki son işlem efektinin gücünü kontrol eder. İstemci tarafından açıkça ayarlanmamışsa bu parametrenin karşılık gelen yakalama sonucu varsayılan güç değerini içerir. Bu parametre, aşağıdaki uzantı türleri için şu şekilde uygulanabilir:

• BOKEH: Bulanıklık miktarını kontrol eder.
• HDR ve NIGHT: Birleştirilen resimlerin miktarını ve son resmin parlaklığını kontrol eder.
• FACE_RETOUCH: Görüntü iyileştirme ve cilt yumuşatma miktarını kontrol eder.

EXTENSION_STRENGTH parametresi için desteklenen aralık 0 ile 100 arasındadır. 0, uzantı işleme veya basit geçiş olmadığını, 100 ise işleme etkisinin maksimum uzantı gücünü gösterir.

EXTENSION_STRENGTH desteği eklemek için uzantı kitaplığı arayüzünün 1.3.0 sürümünde kullanıma sunulan tedarikçiye özel parametre API'lerini kullanın. Daha fazla bilgi için getAvailableCaptureRequestKeys() konusuna bakın.

Sonuçları yakalama

EXTENSION_CURRENT_TYPE Yakalanan sonuç, uzantı uygulamalarının etkin uzantı türü hakkında istemcileri bilgilendirmesine olanak tanır.

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

Anlık görüntü yakalama için gerçek zamanlı gecikme süresi tahmini

Android 14 ve sonraki sürümlerde, kamera uzantısı istemcileri getRealtimeStillCaptureLatency() kullanarak sahneye ve ortam koşullarına göre gerçek zamanlı hareketsiz görüntü yakalama gecikmesi tahminlerini sorgulayabilir. Bu yöntem, statik getEstimatedCaptureLatencyRangeMillis() yöntemine kıyasla daha doğru tahminler sağlar. Uygulamalar, gecikme tahminine göre uzantı işlemeyi atlamaya veya kullanıcılara uzun süren bir işlem hakkında bildirim göndermeye 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();

Anlık görüntü yakalama gecikmesiyle ilgili gerçek zamanlı tahminleri desteklemek için aşağıdakileri uygulayın:

• Temel uzantılar: ImageCaptureExtenderImpl.getRealtimeCaptureLatency()
• Gelişmiş uzantılar: SessionProcessorImpl.getRealtimeCaptureLatency

İşleme ilerleme durumunu yakalama geri çağırmaları

Android 14 ve sonraki sürümlerde, kamera uzantısı istemcileri uzun süren fotoğraf çekimi işleme işlemlerinin ilerleme durumuyla ilgili geri çağırma işlemleri alabilir. Uygulamalar, genel kullanıcı deneyimini iyileştirmek için mevcut ilerleme durumunu kullanıcılara gösterebilir.

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

Uzantı satıcısı uygulamanız, yakalama işleme ilerleme durumu geri çağırmalarını desteklemek için aşağıdaki geri çağırmaları mevcut ilerleme durumu değeriyle çağırmalıdır:

• Temel uzantılar: ProcessResultImpl.onCaptureProcessProgressed()
• Gelişmiş uzantılar: CaptureCallback.onCaptureProcessProgressed()

Görüntüleme sonrası hareketsiz görüntü yakalama

Android 14 ve sonraki sürümlerde kamera uzantıları, setPostviewOutputConfiguration kullanarak bir son görünüm (önizleme resmi) sağlayabilir. Uygulamalar, kullanıcı deneyimini iyileştirmek için bir uzantı artan işleme gecikmesi yaşadığında görüntüleme sonrası resmini yer tutucu olarak gösterebilir ve son resim kullanılabilir olduğunda bu resmi değiştirebilir. Uygulamalar aşağıdaki referans kodunu kullanarak görüntüleme sonrası 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();
…
}

Görüntüleme sonrası hareketsiz görüntü yakalamayı desteklemek için tedarikçi uygulamanızda aşağıdakiler uygulanmalıdır:

• Temel uzantılar: CaptureProcessorImpl.onPostviewOutputSurface ve CaptureProcessorImpl.processWithPostview

• Gelişmiş uzantılar: SessionProcessorImpl.startCaptureWithPostview

SurfaceView çıkışını destekleme

Android 14 ve sonraki sürümlerde, kamera uzantısı istemcileri, tekrarlanan istekler için önizleme çıktısı amacıyla bir SurfaceView örneği kaydederek güç ve performans açısından optimize edilmiş önizleme oluşturma yollarını kullanabilir.

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

Tedarikçiye özel oturum türleri

Bu özellik, satıcı uzantısı uygulamalarının varsayılan değer yerine dahili kamera yakalama oturumunda ayarlanacak satıcıya özel bir oturum türü seçmesine olanak tanır.

Bu özellik tamamen çerçeve ve tedarikçi yığını içinde çalışır ve müşteriye/herkese açık API üzerinde herhangi bir etkisi yoktur.

Tedarikçiye özel bir oturum türü seçmek için uzantı kitaplıklarınızda aşağıdakileri uygulayın: * Temel uzantılar için ExtenderStateListener.onSessionType() * Gelişmiş uzantılar için Camera2SessionConfigImpl.getSessionType()

Uzantılar arayüzünün sürüm geçmişi

Aşağıdaki tabloda, Kamera Uzantısı arayüzünün sürüm geçmişi gösterilmektedir. Satıcı kitaplığını her zaman en son sürümle uygulamalısınız.

Referans uygulama

Aşağıdaki referans OEM satıcı kitaplığı uygulamaları frameworks/ex'da kullanılabilir.

• advancedSample: Gelişmiş Uzatma Aparatı'nın temel uygulamasıdır.

• sample: Basic Extender'ın temel uygulaması.

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

  • oem_library: Extensions-Interface'yi uygulayan Camera2 ve CameraX Uzantıları API'leri için bir Kamera Uzantıları OEM kitaplığı. Bu, Extensions-Interface'dan gelen aramaları hizmete yönlendiren bir geçiş görevi görür. Bu kitaplık, hizmetle iletişim kurmak için AIDL dosyaları ve sarmalayıcı sınıfları da sağlar.

    Gelişmiş uzatma varsayılan olarak etkindir. Temel Uzatıcı'yı etkinleştirmek için ExtensionsVersionImpl#isAdvancedExtenderImplemented değerini false olarak değiştirin.

  • extensions_service: Uzantı Hizmeti'nin örnek bir uygulaması. Uygulamanızı buraya ekleyin. Hizmette uygulanacak arayüz, Extensions-Interface ile benzerdir. Örneğin, IAdvancedExtenderImpl.Stub işlevinin uygulanması, AdvancedExtenderImpl ile aynı işlemleri gerçekleştirir. ImageWrapper ve TotalCaptureResultWrapper, Image ve TotalCaptureResult öğelerinin paketlenebilir olması için gereklidir.

Cihazda tedarikçi kitaplığını ayarlama

OEM satıcı kitaplığı bir uygulamaya yerleştirilmez. Çalışma zamanında Camera2/X tarafından cihazdan yüklenir. CameraX'te <uses-library> etiketi, camera-extensions kitaplığının AndroidManifest.xml dosyasında tanımlanan androidx.camera.extensions.impl kitaplığının CameraX'in bağımlılığı olduğunu ve çalışma zamanında yüklenmesi gerektiğini belirtir. Camera2'de çerçeve, çalışma zamanında <uses-library>aynı androidx.camera.extensions.impl kitaplığı yüklediğini de bildiren bir uzantı hizmeti yükler.

Bu, uzantıları kullanan üçüncü taraf uygulamalarının OEM tedarikçi kitaplığını otomatik olarak yüklemesine olanak tanır. OEM kitaplığı isteğe bağlı olarak işaretlenir. Böylece uygulamalar, kitaplığın yüklü olmadığı cihazlarda çalışabilir. Cihaz üreticisi, OEM kitaplığını cihazda uygulama tarafından keşfedilebilecek şekilde yerleştirdiği sürece Camera2/X, bir uygulama kamera uzantısını kullanmaya çalıştığında bu davranışı otomatik olarak işler.

OEM kitaplığını bir cihazda ayarlamak için aşağıdakileri yapın:

1. Aşağıdaki biçimi kullanarak <uses-library> etiketi için gerekli olan bir izin dosyası ekleyin: /etc/permissions/ANY_FILENAME.xml. Örneğin, /etc/permissions/camera_extensions.xml. Bu dizindeki dosyalar, <uses-library> içinde belirtilen kitaplığın cihazdaki gerçek dosya yoluyla eşlemesini sağlar.

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

   • CameraX'in aradığı kitaplık olduğu için name androidx.camera.extensions.impl olmalıdır.
   • file, uzantı 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 sonraki sürümlerde, CameraX uzantılarını destekleyen cihazlarda ro.camerax.extensions.enabled özelliği true olarak ayarlanmalıdır. Bu, bir cihazın uzantıları destekleyip desteklemediğinin sorgulanmasına olanak tanır. Bunu yapmak için cihazın make dosyasına aşağıdaki satırı ekleyin:

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

Doğrulama

OEM tedarikçi kitaplığı uygulamanızı geliştirme aşamasında test etmek için androidx-main/camera/integration-tests/extensionstestapp/ adresindeki örnek uygulamayı kullanın. Bu uygulama, çeşitli tedarikçi uzantılarıyla çalışır.

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

Genişletilmiş sahne modu ve kamera uzantıları

Bokeh uzantısını, kamera uzantılarını kullanarak kullanıma sunmanın yanı sıra CONTROL_EXTENDED_SCENE_MODE tuşuyla etkinleştirilen genişletilmiş sahne modunu kullanarak da kullanıma sunabilirsiniz. Uygulama süreciyle ilgili daha fazla bilgi için Kamera bokeh efekti başlıklı makaleyi inceleyin.

Genişletilmiş sahne modunda, camera2 uygulamaları için kamera uzantılarına kıyasla daha az kısıtlama vardır. Örneğin, esnek akış kombinasyonlarını ve yakalama isteği parametrelerini destekleyen 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ü grubunu destekler ve yakalama isteği parametreleri için sınırlı destek sunar.

Genişletilmiş sahne modunun dezavantajı, yalnızca kamera HAL'de uygulanabilmesidir. Bu nedenle, uygulama geliştiricilerin kullanımına sunulan tüm ortogonal kontrollerde çalıştığı doğrulanmalıdır.

Uygulamalar bokeh'i etkinleştirmek için belirli bir API'yi kullanmayı tercih edebileceğinden, bokeh'i hem genişletilmiş sahne modu hem de CameraExtensions ile kullanıma sunmanızı öneririz. Uygulamaların bokeh uzantısını etkinleştirmesi için en esnek yöntem olduğundan önce genişletilmiş sahne modunu kullanmanızı öneririz. Ardından, genişletilmiş sahne moduna göre kamera uzantıları arayüzünü uygulayabilirsiniz. Örneğin, görüntüleri işlemek için uygulama katmanında çalışan bir işlem sonrası işlemci gerektirdiğinden kamera HAL'ında bokeh uygulamak zorsa bokeh uzantısını Camera Extensions arayüzünü kullanarak uygulamanızı öneririz.

Sık sorulan sorular (SSS)

API düzeyleriyle ilgili herhangi bir kısıtlama var mı?

Evet. Bu, OEM tedarikçi kitaplığı uygulaması tarafından gerekli olan Android API özellik setine bağlıdır. Örneğin, ExtenderStateListener.onPresetSession(), temel bir etiket grubu ayarlamak için SessionConfiguration.setSessionParameters() çağrısını kullanır. Bu çağrı yalnızca API düzeyi 28 ve sonraki sürümlerde kullanılabilir. Belirli arayüz yöntemleriyle ilgili ayrıntılar için API referans belgelerine bakın.