Kamera uzantıları

Cihaz üreticileri, OEM tedarikçi 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. Uzatma eklemek istiyorsanız Sorun Takip Aracı'nda bir 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 diyagramda, Kamera Uzantıları arayüzünün veya extensions-interface'ün mimarisi açıklanmaktadır:

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

Diyagramda gösterildiği gibi, kamera uzantılarını desteklemek için OEM tedarikçi kitaplığı tarafından sağlanan extensions-interface öğesini uygulamanız gerekir. OEM tedarikçi 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 tedarikçi 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 uzaması sınıfları (Gece uzaması destekleniyorsa uygulayın)

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

Otomatik uzatma sınıfları (otomatik uzatma 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 bir uygulama sağlamanız gerekmez. Uzatma 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 uzantı API'leri, uygulamaya uzantının kullanılamadığını bildirir.

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

Şekil 2. Gece ek süre uygulaması

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

   OEM tarafından uygulanan extensions-interface sürümünün Camera2/X tarafından desteklenen sürümlerle uyumlu olmasını sağlamak için Camera2/X, ExtensionVersionImpl.checkApiVersion() çağrısı yapar.

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

   InitializerImpl, tedarikçi kitaplığını başlatan init() yöntemine sahiptir. Camera2/X, Extender sınıflarına erişmeden önce başlatmayı tamamlar.

3. Uzatıcı sınıflarını oluşturma:

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

   Camera2/X, bilgi almak ve uzantıyı etkinleştirmek için Extender sınıflarını oluşturur ve bu sınıflarla etkileşim kurar. Camera2/X, belirli bir uzantı için Extender sınıflarını birden çok kez örnekleyebilir. Bu nedenle, oluşturucuda veya init() çağrısında ağır iş yükünü oluşturan ilklendirmeyi yapmayın. Ağır işleri yalnızca kamera oturumu başlamak üzereyken yapın (ör. Temel Uzatıcı'da onInit() çağrıldığında veya Gelişmiş Uzatıcı'da initSession() çağrıldığında).

   Gece uzantısı için Temel Uzatıcı türüne aşağıdaki Uzatıcı sınıfları örneklenir:

   • NightImageCaptureExtenderImpl.java
   • NightPreviewExtenderImpl.java

   Gelişmiş Uzatıcı türü için:

   • NightAdvancedExtenderImpl.java

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

   Uzantıyı etkinleştirmeden önce isExtensionAvailable(), Uzatıcı örneği aracılığıyla uzantının belirtilen kamera kimliğinde kullanılıp kullanılamayacağını kontrol eder.

5. Uzatıcıyı kamera bilgileriyle başlatma:

   Camera2/X, Extender örneğinde init()'ü çağırır ve kamera kimliğini ve CameraCharacteristics'yi iletir.

6. Sorgu bilgileri:

   Desteklenen çözünürlükler gibi bilgileri almak, tahmini gecikmeyi yakalamaya devam etmek ve uzantıyı etkinleştirmeye hazırlanmak için Extender sınıfını çağırır.

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

   Extender sınıfı, sınıfı etkinleştirmek için gereken tüm arayüzleri sağlar. OEM uygulamasını Camera2 ardışık düzenine bağlamak için bir mekanizma sunar (ör. yakalama isteği parametrelerini ekleme veya bir son işlemci etkinleştirme).

   Gelişmiş Uzatıcı türü için Camera2/X, uzantıyı etkinleştirmek üzere SessionProcessorImpl ile etkileşim kurar. Camera2/X, Uzatıcı'da createSessionProcessor()'ı çağırarak SessionProcessorImpl örneğini alır.

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

Sürüm doğrulaması

Camera2/X, çalışma zamanında OEM tedarikçi kitaplığını cihazdan yüklerken kitaplığın extensions-interface sürümüyle uyumlu olup olmadığını doğrular. extensions-interface, anlamsal sürüm oluşturma veya MAJOR.MINOR.PATCH (ör. 1.1.0 veya 1.2.0) kullanır. Ancak sürüm doğrulaması sırasında yalnızca büyük ve küçük sürümler kullanılır.

Sürümü doğrulamak için Camera2/X, desteklenen extensions-interface sürümüyle ExtensionVersionImpl.checkApiVersion() çağrısı yapar. Ardından Camera2/X, uzantının etkinleştirilip etkinleştirilemeyeceğini ve hangi özellikleri ç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 büyük sürümleri Camera2/X ile tedarikçi kitaplığı arasında farklıysa uyumlu değil 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'u destekliyorsa 1.0.0, 1.1.0 ve 1.2.0'yi uygulayan OEM tedarikçi kitaplıkları uyumlu olmaya devam eder. Bu, tedarikçi kitaplığının belirli bir sürümünü uyguladıktan sonra Camera2/X'in kitaplığın gelecekteki extension-interface sürümleriyle geriye dönük uyumlu olmasını sağladığı anlamına da gelir.

İleriye dönük uyumluluk

Yeni extensions-interface sürümlerinin tedarikçi kitaplıklarıyla ileriye dönük uyumluluğu, OEM olan 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ştirmek isteyebilirsiniz. Bu durumda, Camera2/X kitaplığı sürümü koşulları 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 uyumlu olmayan bir sürümü döndürebilirsiniz.

Tedarikçi firma 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ı kullanmaya çalıştığı bilgisini gönderir.

OEM tedarikçi kitaplığı, başlatmanın tamamlandığını bildirmek için OnExtensionsInitializedCallback.onSuccess() çağrısı yapana kadar Camera2/X, OEM kitaplığına (sürüm kontrolü dışında) başka çağrıda bulunmaz.

extensions-interface 1.1.0 sürümünden itibaren InitializerImpl'u uygulamanız gerekir. OEM tedarikçi kitaplığı extensions-interface 1.0.0'ı uygularsa Camera2/X, kitaplık ilklendirme adımını atlar.

Temel Uzatma Aparatı ve Gelişmiş Uzatma Aparatı karşılaştırması

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

Kamera HAL'inde resimleri işleyen uzantılar için Temel Uzatıcı'yı uygulayın veya YUV akışlarını işleyebilecek bir son işlemci kullanın.

Camera2 yayın yapılandırmasını özelleştirmesi ve gerektiğinde yakalama istekleri göndermesi gereken uzantılar için Gelişmiş Uzatıcı'yı uygulayın.

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

	Temel Uzatma Aparatı	Gelişmiş Uzatma Aparatı
Yayın yapılandırmaları	Düzeltildi Önizleme: PRIVATE veya YUV_420_888 (işlemci varsa) Sabit görüntü yakalama: JPEG veya YUV_420_888 (işlemci varsa)	OEM tarafından özelleştirilebilir.
Kayıt isteği gönderiliyor	Yalnızca Camera2/X fotoğraf çekme isteği gönderebilir. Bu isteklerin parametrelerini ayarlayabilirsiniz. Görüntü yakalama için işlemci sağlandığında Camera2/X birden fazla yakalama isteği gönderebilir ve tüm resimleri ve yakalama sonuçlarını işlemciye gönderebilir.	camera2 yakalama isteğini yürütmek, sonuçları ve resmi almak için size bir RequestProcessorImpl örneği sağlanır. Camera2/X, OEM'ye sırasıyla önizleme için tekrarlanan isteği başlatması ve fotoğraf çekme sırasını başlatması gerektiğini bildirmek üzere SessionProcessorImpl üzerinde startRepeating ve startCapture'yi çağırır.
Kamera ardışık düzenindeki 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 camera2 oturum 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.
Uygun olduğu yerler	Kamera HAL'inde veya YUV resimlerini işleyen bir işlemcide uygulanan uzantılar.	Uzantılar için Camera2 tabanlı uygulamalara sahiptir. RAW akışı gibi özelleştirilmiş bir akış yapılandırması gerekir. Etkileşimli yakalama sırası gerekir.
Desteklenen API sürümü	Camera2 Extensions: Android 13 veya sonraki sürümler CameraX Extensions: camera-extensions 1.1.0 veya sonraki sürümler	Camera2 Extensions: Android 12L veya sonraki sürümler CameraX Extensions: camera-extensions 1.2.0-alpha03 veya sonraki sürümler

Uygulama akışları

Aşağıdaki tabloda üç tür uygulama akışı ve bunların 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 tedarikçi kitaplığını düzgün şekilde uygulamanız gerekir. Bu konuyu sonraki bir bölümde daha ayrıntılı olarak açıklıyoruz.

	Camera2 uzantıları	CameraX uzantıları
Sorgu uzantısının kullanılabilirliği	CameraExtensionCharacteristics .getSupportedExtensions	ExtensionsManager. isExtensionAvailable
Sorgu bilgileri	CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys	ExtensionsManager. getEstimatedCaptureLatencyRange Bilgilerin geri kalanı kitaplıkta CameraX tarafından işlenir.
Uzatma etkinken önizleme ve fotoğraf çekme	CameraDevice. createExtensionSession cameraExtensionsSession. setRepeatingRequest cameraExtensionsSession. capture	val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector bindToLifecycle(lifecycleOwner, cameraSelector, preview, ...)

Temel Uzatma Aparatı

Temel Uzatıcı arayüzü, kamera ardışık düzenindeki çeşitli yerlere bağlantı 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:

	Uygulamanız gereken genişletici sınıflar
Gece	NightPreviewExtenderImpl.java NightImageCaptureExtenderImpl.java
HDR	HdrPreviewExtenderImpl.java HdrImageCaptureExtenderImpl.java
Auto	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ılmaktadır. Bunları, uyguladığınız gerçek dosyaların adlarıyla değiştirin.

Temel Uzatıcı aşağıdaki özelliklere sahiptir:

• CameraCaptureSession ( onPresetSession) öğesini yapılandırırken oturum parametrelerini ekleyin.
• Kayıt oturumunun başlangıç ve kapanış etkinlikleri hakkında sizi bilgilendirir ve döndürülen parametreleri (onEnableSession, onDisableSession) HAL'e bildirmek için tek bir istek gönderir.
• İstek için yakalama parametrelerini ekleyin (PreviewExtenderImpl.getCaptureStage, ImageCaptureExtenderImpl.getCaptureStages).
• Önizleme ve yakalama için YUV_420_888 akışını işleyebilecek işlemciler ekleyin.

Camera2/X'in, yukarıda belirtilen üç uygulama akışını gerçekleştirmek için extensions-interface'ü nasıl çağırdığını görelim.

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

Şekil 3. Temel Uzatıcı'da 1. uygulama akışı

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

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

Uygulama akışı 2: Sorgu bilgileri

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

Uygulamalar, uzantının kullanılıp kullanılamayacağını belirledikten sonra uzantıyı etkinleştirmeden önce aşağıdaki bilgileri sorgulamalıdır.

• Hareketsiz görüntü yakalama gecikmesi aralığı: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange, uygulamanın mevcut senaryoda 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, resim biçimlerinin ve yüzey biçimi ile boyutu için desteklenen boyutların 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 sorgu göndermeden önce bu Extender sınıflarında her zaman önce init()'yi çağırır.

Uygulama akışı 3: Uzatma etkinken önizleme/sabit resim yakalama (HAL uygulaması)

Şekil 5. Temel Uzatıcı'da uygulama akışı 3

Yukarıdaki şema, işlemci içermeyen bir uzantı ile önizlemeyi ve fotoğraf çekmeyi etkinleştirmenin ana akışını göstermektedir. Bu, kamera HAL'inin uzantıyı işlediği anlamına gelir.

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

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

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

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

Önizleme işleyicisi

Kamera HAL'ine ek olarak, uzantıları bir işlemciye de uygulayabilirsiniz.

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

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

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

  PreviewExtenderImpl.getProcessor, TotalCaptureResult örneğini işleyen ve tekrarlanan isteği güncellemek için CaptureStageImpl örneği 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 resimlerini işlemek ve çıkışı PRIVATE yüzeyine yazmak için bir işlemci uygulamanıza olanak tanır.

  PreviewExtenderImpl.getProcessor'da bir PreviewImageProcessorImpl örneği uygulamanız ve döndürmeniz gerekir. İşlemci, YUV_420_888 giriş resimlerini işlemekten sorumludur. Çıktı, önizleme PRIVATE biçimine yazılmalıdır. Camera2/X, CameraCaptureSession'yi önizleme için yapılandırmak üzere PRIVATE yerine YUV_420_888 yüzeyi kullanır.

  Akış için aşağıdaki görsele bakın:

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

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

• onOutputSurface(Surface surface, int imageFormat), işlemci için çı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 görüntü yakalama için ImageCaptureExtenderImpl.getCaptureProcessor kullanarak bir CaptureProcessorImpl örneği döndürerek bir işleyici uygulayabilirsiniz. İşleyen, yakalanan YUV_420_888 resim ve TotalCaptureResult örnekleri listesini işlemekten ve çıkışı bir YUV_420_888 yüzeye yazmaktan sorumludur.

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

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

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

1. Camera2/X, yakalama oturumunu yapılandırmak için sabit görüntü yakalama için YUV_420_888 biçimli bir yüzey kullanır. Camera2/X, aşağıdakileri çağırarak CaptureProcessorImpl'ü hazırlar:

   • YUV_420_888 ile CaptureProcessorImpl.onImageFormatUpdate().
   • CaptureProcessorImpl.onResolutionUpdate() ile giriş resmi boyutunu belirtin.
   • CaptureProcessorImpl.onOutputSurface() çıkış YUV_420_888yüzeyiyle

2. ImageCaptureExtenderImpl.getCaptureStages, her bir öğenin Camera2/X tarafından gönderilen yakalama parametrelerine sahip bir CaptureRequest örneğiyle eşlendiği CaptureStageImpl öğelerinin bir listesini döndürür. Ö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 görüntüler ve TotalCaptureResult örnekleri birlikte gruplandırılır ve işlenmek üzere CaptureProcessorImpl'a gönderilir.

4. CaptureProcessorImpl, sonuç görselini (YUV_420_888 biçimi) onOutputSurface() çağrısı tarafından belirtilen çıkış yüzeyine yazar. Camera2/X, gerekirse bu dosyaları JPEG resimlerine dönüştürür.

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

Uygulamalar, kamera önizlemesi ve çekime ek olarak yakınlaştırma, flaş parametreleri ayarlayabilir veya dokunarak odaklama özelliğini tetikleyebilir. Bu parametreler, uzantı uygulamanızla uyumlu olmayabilir.

Uygulamanızın desteklediği parametreleri göstermenize olanak tanımak için extensions-interface 1.3.0 sürümüne aşağıdaki yöntemler eklendi:

• 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'i uzantıyı işlerse Camera2/X, yakalama sonuçlarını CameraCaptureSession.CaptureCallback içinde alır. Ancak işlemci uygulanırsa Camera2/X, ProcessResultImpl bölümündeki yakalama sonuçlarını alır ve bu sonuçlar PreviewImageProcessorImpl bölümündeki process() yöntemine ve CaptureProcessorImpl bölümüne iletilir. ProcessResultImpl üzerinden yakalama sonucunu Camera2/X'e bildirme sorumluluğu size aittir.

Ö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ı ç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 pozlama telafisi gibi yaygın kamera işlemleri için hem çekim isteği hem de çekim sonucu için aşağıdaki anahtarları desteklemenizi öneririz:

• Yakınlaştırma:
  • CaptureRequest#CONTROL_ZOOM_RATIO
  • CaptureRequest#SCALER_CROP_REGION
• Dokunarak odaklama:
  • 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 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 bu listedeki 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, uygulamada yalnızca yakınlaştırmanın destekleneceği, dokunarak odaklama, flaş ve pozlama telafisine ise izin verilmeyeceği anlamına gelir.

Gelişmiş Uzatma Aparatı

Gelişmiş Uzatıcı, Camera2 API'ye dayalı bir tedarikçi uygulaması türüdür. Bu Uzatıcı türü extensions-interface 1.2.0'a eklenmiştir. Cihaz üreticisine bağlı olarak uzantılar uygulama katmanına uygulanabilir. Bu, aşağıdaki faktörlere bağlıdır:

• Özel yayın yapılandırması: RAW yayın gibi özel yayınlar yapılandırın veya farklı fiziksel kamera kimlikleri için birden fazla yayın 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.

Gelişmiş Uzatıcı, yayın yapılandırmasını özelleştirebilmeniz ve istek üzerine yakalama istekleri gönderebilmeniz için bir sarmalayıcı veya ara katman sağlar.

Uygulanacak dosyalar

Gelişmiş Uzatıcı uygulamasına geçmek için ExtensionVersionImpl içindeki isAdvancedExtenderImplemented() yöntemi true döndürmelidir. OEM'ler her uzantı türü için ilgili Extender sınıflarını uygulamalıdır. Gelişmiş Uzatıcı uygulama dosyaları advanced paketindedir.

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

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

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

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

Şekil 8. Gelişmiş Uzatıcı'da 1. uygulama akışı

Uygulama ilk olarak, belirtilen uzantının desteklenip desteklenmediğini kontrol eder.

Uygulama akışı 2: Sorgu bilgileri

Şekil 9. Gelişmiş Uzatıcı'da uygulama akışı 2

Uygulama, AdvancedExtenderImpl.init() çağrısını yaptıktan sonra AdvancedExtenderImpl'daki aşağıdaki bilgileri sorgulayabilir:

• Tahmini fotoğraf yakalama gecikmesi: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange(), uygulamanın mevcut senaryoda uzantıyı etkinleştirmenin uygun olup olmadığını değerlendirmesi için 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 boyutlar listesine resim biçimi haritası döndürür. OEM'ler en az PRIVATE biçimini desteklemelidir.

  • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions(), sabit görüntü 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ışı için desteklenen boyutları 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, 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 Destek kaydı istek anahtarları ve sonuçları başlıklı makaleyi inceleyin.

Uygulama akışı 3: Uzatma etkinken önizleme/sabit resim çekme

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

Yukarıdaki şemada, Gelişmiş Uzatıcı türü için önizlemeyi başlatma ve sabit görüntü yakalama ana akışı gösterilmektedir. Her bir adımı inceleyelim.

1. SessionProcessorImpl örneği

   Temel Gelişmiş Uzatıcı uygulaması SessionProcessorImpl'tedir. Bu uygulama, özelleştirilmiş oturum yapılandırması sağlamaktan ve önizlemeyi başlatmak ve hâlâ yakalama isteği göndermek için yakalama istekleri göndermekten sorumludur. SessionProcessorImpl örneğini döndürmek için AdvancedExtenderImpl.createSessionProcessor() çağrılır.

2. initSession

   SessionProcessorImpl.initSession(), uzantı için oturumu başlatır. Burada, CameraCaptureSession hazırlamak için kaynakları ayarlar ve 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üzey yapılandırması (OutputSurfaceImpl), AdvancedExtenderImpl'da aşağıdaki yöntemlerle alınan yüzeyi, boyutu ve resim biçimini içerir:

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

   Camera2OutputConfigImpl örnekleri listesinin ve CameraCaptureSession'yi yapılandırmak için kullanılan oturum parametrelerinin yer aldığı bir Camera2SessionConfigImpl örneği döndürmeniz gerekir. Camera2/X tarafından iletilen çıkış yüzeylerine doğru kamera görüntülerini göndermekten siz sorumlusunuz. Çıkışı etkinleştirmek için kullanabileceğiniz bazı seçenekler şunlardır:

   • Kamera HAL'inde işleme: SurfaceOutputConfigImpluygulamasıyla çıkış yüzeylerini doğrudan CameraCaptureSession'e ekleyebilirsiniz. Bu işlem, sağlanan çıkış yüzeyini kamera ardışık düzenine yapılandırır ve kamera HAL'inin resmi işlemesine olanak tanır.

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

     Ara resimleri işlemeniz ve sonuç resmini çıkış yüzeyine yazmanız gerekir.

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

   SurfaceOutputConfigImpl ve ImageReaderOutputConfigImpl dahil tüm Camera2OutputConfigImpl öğelerinin, hedef yüzeyi belirtmek ve resmi ImageReaderOutputConfigImpl'den 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()'ü çağrdığında, Camera2/X, Camera2 istek sarmalayıcısı RequestProcessImpl ile SessionProcessorImpl.onCaptureSessionStart()'yi çağırır. Camera2/X, RequestProcessImpl'ü uygular. Bu sayede ImageReaderOutputConfigImpl kullanılıyorsa çekim isteklerini yürütebilir ve görüntüleri alabilirsiniz.

   RequestProcessImpl API'leri, istek yürütme açısından Camera2CameraCaptureSession API'lerine benzer. Farklar şunlardır:

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

   Resim almak için bir ImageProcessorImpl örneğini kaydetmek üzere belirli bir Camera2OutputConfigImpl kimliğiyle RequestProcessorImpl.setImageProcessor()'ü arayabilirsiniz.

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

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

   Gelişmiş Uzatıcı 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 veya fotoğraf çekme sırasını tekrarlamaya başlamanız gerektiğini bildirir. Bu önizleme ve fotoğraf çekme isteklerini karşılamak için çekim istekleri göndermeniz gerekir.

   Camera2/X, yakalama isteği parametrelerini SessionProcessorImpl#setParameters üzerinden de ayarlar. Bu istek parametrelerini (parametreler destekliyorsa) hem yinelenen 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 sunulan istek ve sonuç anahtarlarını destekler:

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

   Geliştiriciler getAvailableCaptureRequestKeys listesindeki anahtarları ayarlarken 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()'te reklamı yapılmayan tüm yakalama isteği anahtarlarını yoksayabilirsiniz.

   startTrigger(), extensions-interface 1.3.0 sürümünden beri desteklenmektedir. Bu özellik, uygulamaların uzantılarla dokunarak odaklama ve yanıp sönme özelliklerini uygulamasını sağlar.

6. Temizleme

   Bir yakalama oturumu sona erdiğinde, CameraCaptureSession kapatılmadan önce SessionProcessorImpl.onCaptureSessionEnd() çağrılır. Kayıt oturumu kapatıldıktan sonra deInitSession() temizlemeyi gerçekleştirir.

Önizleme, fotoğraf çekme ve görüntü analizi desteği

Uzantı hem önizleme hem de sabit resim yakalama kullanım alanları için uygulanmalıdır. Ancak gecikme süresi, önizlemeyi sorunsuz bir şekilde gösterecek kadar yüksekse uzantıyı yalnızca fotoğraf çekmek için uygulayabilirsiniz.

Temel Uzatıcı türü için, uzantının önizleme için etkinleştirilmesinden bağımsız olarak, belirli bir uzantı için hem ImageCaptureExtenderImpl hem de PreviewExtenderImpl uygulamanız gerekir. Uygulamalar, görüntü içeriğini analiz etmek için genellikle YUV akışı da kullanır (ör. QR kodu veya metin bulma). Bu kullanım alanını daha iyi desteklemek için önizleme, fotoğraf yakalama ve CameraCaptureSession yapılandırmaya yönelik bir YUV_420_888 akış kombinasyonunu desteklemeniz gerekir. Bu, bir işlemci uygularsanız üç YUV_420_888 akışının birleşimini desteklemeniz gerektiği anlamına gelir.

Gelişmiş Uzatıcı için Camera2/X, SessionProcessorImpl.initSession() çağrısına üç çıkış yüzeyi iletir. Bu çıkış yüzeyleri sırasıyla önizleme, fotoğraf yakalama ve görüntü analizi içindir. Önizleme ve sabit 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 görüntü analizi akışını desteklemiyorsa AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() içinde boş bir liste döndürebilirsiniz. Bu, resim analizi çıkış yüzeyinin SessionProcessorImpl.initSession() içinde her zaman null olmasını sağlar.

Video yakalamayı destekleme

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

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

Uzantıya özgü meta veriler

Android 14 ve sonraki sürümlerde, uzantıya özgü meta veriler, kamera uzantısı istemcilerinin uzantıya özgü yakalama isteği ayarlarını ve sonuçlarını ayarlamasına ve almasına olanak tanır. Daha açık belirtmek gerekirse, kamera uzantısı istemcileri, uzantı gücünü kontrol etmek için EXTENSION_STRENGTH capture istek parametresini ve etkin uzantı türünü belirtmek için EXTENSION_CURRENT_TYPE capture sonucunu kullanabilir.

İstekleri yakalama

EXTENSION_STRENGTH yakalama isteği parametresi, uzantı son işleme efektinin gücünü kontrol eder. Bu parametre istemci tarafından açıkça ayarlanmamışsa ilgili yakalama sonucu, varsayılan güç değerini içerir. Bu parametre, aşağıdaki uzantı türleri için aşağıdaki şekilde uygulanabilir:

• BOKEH: Bulanıklığın miktarını kontrol eder.
• HDR ve NIGHT: Birleştirilen resimlerin miktarını ve nihai resmin parlaklığını kontrol eder.
• FACE_RETOUCH: Kozmetik iyileştirme ve cilt pürüzsüzleştirme 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ü belirtir.

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 yakalama sonucu, 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.

Gerçek zamanlı fotoğraf çekme gecikmesi tahmini

Android 14 ve sonraki sürümlerde kamera uzantısı istemcileri, getRealtimeStillCaptureLatency() kullanarak sahneye ve çevre koşullarına göre gerçek zamanlı hareketsiz görüntü yakalama gecikmesi tahminlerini sorgulayabilir. Bu yöntem, statik getEstimatedCaptureLatencyRangeMillis() yönteminden daha doğru tahminler sağlar. Uygulamalar, gecikme tahminine göre uzantı işlemeyi atlamaya veya uzun süren bir işlem hakkında kullanıcıları bilgilendirmek için bir gösterge göstermeye 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ı fotoğraf yakalama gecikmesi tahminlerini desteklemek için aşağıdakileri uygulayın:

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

İşleme ilerleme durumu geri aramalarını yakalama

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 arama alabilir. Uygulamalar, genel kullanıcı deneyimini iyileştirmek için mevcut ilerlemeyi 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
    }
  }
…
}

Yakalama işleme ilerleme geri çağırmalarını desteklemek için uzantı tedarikçisi uygulamanız, mevcut ilerleme değeriyle aşağıdaki geri çağırma işlevlerini çağırmalıdır:

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

Görüntüleme sonrası sabit resim yakalama

Android 14 ve sonraki sürümlerde kamera uzantıları, setPostviewOutputConfiguration kullanarak görüntü sonrası (önizleme resmi) sağlayabilir. Uygulamalar, kullanıcı deneyimini iyileştirmek için bir uzantı daha uzun işlem gecikmesi yaşadığında yer tutucu olarak görüntü sonrası bir resim gösterebilir ve nihai resim kullanıma sunulduğunda resmi değiştirebilir. Uygulamalar aşağıdaki referans kodunu kullanarak görüntüleme sonrası yakalama isteklerini yapılandırabilir ve gönderebilir:

{
…
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ı sabit görüntü yakalamayı desteklemek için tedarikçi firma uygulamanızın aşağıdakileri uygulaması gerekir:

• 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 çıkışı SurfaceView örneği kaydederek güç ve performans açısından optimize edilmiş önizleme oluşturma yollarını kullanabilir.

SurfaceView çıkışını desteklemek için tedarikçi firma uzantısı uygulamanızın, önizlemeyi SurfaceView örneklerine aktarıp yayınlayabilmesi gerekir. Bunun desteklendiğini doğrulamak için SurfaceViewExtensionPreviewTest.java CTS modülünü çalıştırın.

Tedarikçi firmaya özel oturum türleri

Bu özellik, tedarikçi uzantısı uygulamalarının varsayılan değer yerine dahili kamera yakalama oturumunda ayarlanacak tedarikçiye özgü bir oturum türü seçmesine olanak tanır.

Bu özellik tamamen çerçeve ve tedarikçi yığınında çalışır ve istemci/herkese açık API üzerinde hiç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ı arayüzü 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. Tedarikçi kitaplığını her zaman en son sürümüyle uygulamanız gerekir.

Sürüm	Eklenen özellikler
1.0.0	Sürüm doğrulaması ExtensionVersionImpl Temel Uzatma Aparatı PreviewExtenderImpl ImageCaptureExtenderImpl Processor PreviewImageProcessorImpl CaptureProcessorImpl RequestUpdateProcessorImpl
1.1.0	Kitaplık başlatma InitializerImpl Desteklenen çözünürlükleri gösterme PreviewExtenderImpl.getSupportedResolutions ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0	AdvancedExtender AdvancedExtenderImpl SessionProcessorImpl Tahmini yakalama gecikmesini alma ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0	Desteklenen yakalama isteği anahtarlarını/sonuç anahtarlarını gösterme ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys ve getAvailableCaptureResultKeys AdvancedExtenderImpl.getAvailableCaptureRequestKeys ve getAvailableCaptureResultKeys PreviewImageProcessorImpl ve CaptureProcessorImpl'de ProcessResultImpl kazanan yeni process() çağrısı Destek tetikleyici türü isteği AdvancedExtenderImpl.startTrigger
1.4.0	Uzantıya özgü meta veriler Dinamik fotoğraf çekme gecikmesi tahminleri İşleme ilerleme durumu geri aramalarını yakalama Görüntüleme sonrası sabit resim yakalama SurfaceView çıkışı için destek Tedarikçi firmaya özel oturum türleri

Referans uygulama

Aşağıdaki referans OEM tedarikçi kitaplığı uygulamaları frameworks/ex'de kullanılabilir.

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

• sample: Temel Uzatma Aparatı'nın temel uygulaması.

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

  • oem_library: Extensions-Interface'ü uygulayan Camera2 ve CameraX Extensions API'leri için bir Camera Extensions OEM kitaplığı. Bu, Extensions-Interface'ten gelen aramaları hizmete yönlendiren bir geçiş işlevi 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ş Uzatıcı varsayılan olarak etkindir. Temel Uzatıcı'yı etkinleştirmek için ExtensionsVersionImpl#isAdvancedExtenderImplemented değerini false olarak değiştirin.

  • extensions_service: Uzantılar Hizmeti'nin örnek bir uygulaması. Uygulamanızı buraya ekleyin. Hizmette uygulanacak arayüz, Extensions-Interface ile benzerdir. Örneğin, IAdvancedExtenderImpl.Stub işlevi uygulandığında AdvancedExtenderImpl ile aynı işlemler gerçekleştirilir. Image ve TotalCaptureResult'in paketlenebilmesi için ImageWrapper ve TotalCaptureResultWrapper gereklidir.

Cihazlarda tedarikçi kitaplığını ayarlama

OEM tedarikçi kitaplığı bir uygulamaya yerleştirilmez. Camera2/X tarafından çalışma zamanında 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 bir 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ığını yüklediğini de belirten bir uzantı hizmeti yükler.

Bu sayede, uzantı kullanan üçüncü taraf uygulamaları OEM tedarikçi kitaplığını otomatik olarak yükleyebilir. OEM kitaplığı, uygulamaların kitaplığın bulunmadığı cihazlarda çalışabilmesi için isteğe bağlı olarak işaretlenir. Cihaz üreticisi, OEM kitaplığını uygulama tarafından bulunabilmesi için cihaza yerleştirdiği sürece, bir uygulama kamera uzantısı kullanmaya çalıştığında Camera2/X bu davranışı otomatik olarak yönetir.

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

1. Aşağıdaki biçimi kullanarak <uses-library> etiketi tarafından zorunlu kılınan bir izin dosyası ekleyin: /etc/permissions/ANY_FILENAME.xml. Örneğin, /etc/permissions/camera_extensions.xml. Bu dizindeki dosyalar, <uses-library> adlı kitaplığın cihazdaki gerçek dosya yoluyla eşlenmesini sağlar.

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

   • CameraX'in aradığı kitaplık name olduğundan 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 mülkü true olarak ayarlanmalıdır. Bu, bir cihazın uzantıları destekleyip desteklemediğini sorgulamanıza olanak tanır. Bunu yapmak için cihaz markası dosyasına aşağıdaki satırı ekleyin:

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

Doğrulama

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

Uygulamanızı tamamladıktan sonra tedarikçi 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 göstermenin yanı sıra CONTROL_EXTENDED_SCENE_MODE anahtarıyla etkinleştirilen genişletilmiş sahne modunu kullanarak da gösterebilirsiniz. Uygulamayla ilgili daha fazla bilgi için Kamera bokeh efekti başlıklı makaleyi inceleyin.

Genişletilmiş sahne modu, camera2 uygulamaları için kamera uzantılarına kıyasla daha az kısıtlamaya sahiptir. Örneğin, esnek yayın 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ü grubunu destekler ve yakalama isteği parametreleri için sınırlı destek sunar.

Genişletilmiş sahne modunun dezavantajı, yalnızca kamera HAL'inde uygulanabilmesidir. Bu, uygulama geliştiricilerine sunulan tüm ortogonal kontrollerde çalışacağı doğrulanmalıdır.

Uygulamalar bokeh'i etkinleştirmek için belirli bir API'yi kullanmayı tercih edebileceğinden, hem genişletilmiş sahne modunu hem de Kamera Uzantıları'nı kullanarak bokeh'i kullanmanızı öneririz. Uygulamaların bokeh uzantısını etkinleştirmesinin en esnek yolu olduğu için önce genişletilmiş sahne modunu kullanmanızı öneririz. Ardından, genişletilmiş sahne moduna dayalı kamera uzantıları arayüzünü uygulayabilirsiniz. Kamera HAL'inde bokeh uygulamak zorsa (ör. resimleri işlemek için uygulama katmanında çalışan bir son işlemci gerektiriyorsa) bokeh uzantısını Kamera Uzantıları 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 gereken Android API özellik grubuna bağlıdır. Örneğin, ExtenderStateListener.onPresetSession(), temel 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 dokümanlarına bakın.