ผู้ผลิตอุปกรณ์สามารถแสดงเอฟเฟกต์พิเศษ เช่น โบเก้ โหมดกลางคืน และ HDR แก่นักพัฒนาบุคคลที่สามผ่านอินเทอร์เฟซ Camera Extensions ที่มีให้โดยไลบรารีของผู้จำหน่าย OEM นักพัฒนาสามารถใช้ Camera2 Extensions และ CameraX Extensions API เพื่อเปิดใช้งานเอฟเฟกต์ ซึ่งถูกนำไปใช้เป็นส่วนขยายในไลบรารีของผู้จำหน่าย OEM บนอุปกรณ์
สำหรับรายการส่วนขยายที่รองรับซึ่งเหมือนกันใน Camera2 และ CameraX โปรดดูที่ CameraX Extensions API หากคุณต้องการเพิ่มส่วนขยาย ให้แจ้งข้อบกพร่อง ที่นี่
หน้านี้อธิบายวิธีการใช้และเปิดใช้งานไลบรารีของผู้จำหน่าย OEM บนอุปกรณ์
สถาปัตยกรรม
ไดอะแกรมต่อไปนี้อธิบายสถาปัตยกรรมของอินเทอร์เฟซ Camera Extensions หรือ extensions-interface
:
รูปที่ 1 แผนภาพสถาปัตยกรรมส่วนขยายกล้อง
ดังที่แสดงในไดอะแกรม เพื่อรองรับส่วนขยายของกล้อง คุณต้องติดตั้ง extensions-interface
ให้มาโดยไลบรารีของผู้จำหน่าย OEM ไลบรารีผู้จำหน่าย OEM ของคุณเปิดใช้งาน API สองชุด: CameraX Extensions API และ Camera2 Extensions API ซึ่งใช้โดยแอป CameraX และ Camera2 ตามลำดับ เพื่อเข้าถึงส่วนขยายของผู้จำหน่าย
ใช้ไลบรารีผู้จำหน่าย OEM
ในการใช้ไลบรารีของผู้จำหน่าย OEM ให้คัดลอกไฟล์ camera-extensions-stub
ลงในโปรเจ็กต์ไลบรารีระบบ ไฟล์เหล่านี้กำหนดอินเทอร์เฟซของส่วนขยายกล้อง
ไฟล์ camera-extensions-stub
แบ่งออกเป็นประเภทต่อไปนี้:
ไฟล์อินเทอร์เฟซที่จำเป็น (ห้ามแก้ไข)
-
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
การใช้งานบังคับ (เพิ่มการใช้งานของคุณ)
-
ExtensionVersionImpl.java
-
InitializerImpl.java
คลาสตัวขยายโบเก้ (ใช้งานได้หากรองรับส่วนขยายโบเก้)
-
BokehImageCaptureExtenderImpl.java
-
BokehPreviewExtenderImpl.java
-
advanced/BokehAdvancedExtenderImpl.java
คลาสตัวขยายเวลากลางคืน (ใช้งานได้หากรองรับส่วนขยายกลางคืน)
-
NightImageCaptureExtenderImpl.java
-
NightPreviewExtenderImpl.java
-
advanced/NightAdvancedExtenderImpl.java
คลาสตัวขยายอัตโนมัติ (ใช้งานได้หากรองรับส่วนขยายอัตโนมัติ)
-
AutoImageCaptureExtenderImpl.java
-
AutoPreviewExtenderImpl.java
-
advanced/AutoAdvancedExtenderImpl.java
คลาสตัวขยาย HDR (ใช้งานได้หากรองรับส่วนขยาย HDR)
-
HdrImageCaptureExtenderImpl.java
-
HdrPreviewExtenderImpl.java
-
advanced/HdrAdvancedExtenderImpl.java
คลาสตัวขยาย Face Retouch (ใช้งานได้หากรองรับส่วนขยาย Face Retouch)
-
BeautyImageCaptureExtenderImpl.java
-
BeautyPreviewExtenderImpl.java
-
advanced/BeautyAdvancedExtenderImpl.java
ยูทิลิตี้ (ไม่จำเป็น สามารถลบได้)
-
advanced/Camera2OutputConfigImplBuilder.java
-
advanced/Camera2SessionConfigImplBuilder.java
คุณไม่จำเป็นต้องจัดเตรียมการใช้งานสำหรับทุกส่วนขยาย หากคุณไม่ได้ใช้ส่วนขยาย ให้ตั้งค่า isExtensionAvailable()
เพื่อคืนค่า false
หรือลบคลาส Extender ที่เกี่ยวข้อง Camera2 และ CameraX Extensions API จะรายงานไปยังแอปว่าส่วนขยายไม่พร้อมใช้งาน
มาดูวิธีที่ Camera2 และ CameraX Extensions API โต้ตอบกับไลบรารีของผู้ขายเพื่อเปิดใช้งานส่วนขยาย แผนภาพต่อไปนี้แสดงโฟลว์แบบ end-to-end โดยใช้ส่วนขยาย Night เป็นตัวอย่าง:
รูปที่ 2 การใช้งานส่วนขยายกลางคืน
การตรวจสอบเวอร์ชัน:
Camera2/X เรียก
ExtensionVersionImpl.checkApiVersion()
เพื่อให้แน่ใจว่าเวอร์ชันextensions-interface
ที่ใช้ OEM นั้นเข้ากันได้กับรุ่นที่รองรับ Camera2/Xการเริ่มต้นไลบรารีผู้จำหน่าย:
InitializerImpl
มีเมธอดinit()
ที่เริ่มต้นไลบรารีผู้ขาย Camera2/X เสร็จสิ้นการเริ่มต้นก่อนที่จะเข้าถึงคลาส Extenderสร้างอินสแตนซ์คลาส Extender:
สร้างอินสแตนซ์คลาส Extender สำหรับส่วนขยาย มี Extender สองประเภท: Basic Extender และ Advanced Extender คุณต้องใช้ประเภท Extender หนึ่งประเภทสำหรับส่วนขยายทั้งหมด สำหรับข้อมูลเพิ่มเติม โปรดดูที่ Basic Extender เทียบกับ Advanced Extender
Camera2/X สร้างอินสแตนซ์และโต้ตอบกับคลาส Extender เพื่อดึงข้อมูลและเปิดใช้งานส่วนขยาย สำหรับส่วนขยายที่กำหนด Camera2/X สามารถยกตัวอย่างคลาส Extender ได้หลายครั้ง ด้วยเหตุนี้ อย่าทำการเริ่มต้นแบบยกของหนักใน Constructor หรือการเรียก
init()
ดำเนินการยกของหนักเฉพาะเมื่อเซสชันกล้องกำลังจะเริ่มต้น เช่น เมื่อonInit()
ใน Basic Extender หรือinitSession()
ใน Advanced Extenderสำหรับส่วนขยาย Night คลาส Extender ต่อไปนี้จะสร้างอินสแตนซ์สำหรับประเภท Basic Extender:
-
NightImageCaptureExtenderImpl.java
-
NightPreviewExtenderImpl.java
และสำหรับประเภท Advanced Extender:
-
NightAdvancedExtenderImpl.java
-
ตรวจสอบความพร้อมของส่วนขยาย:
ก่อนเปิดใช้งานส่วนขยาย
isExtensionAvailable()
จะตรวจสอบว่าส่วนขยายมีอยู่ใน ID กล้องที่ระบุผ่านอินสแตนซ์ของ Extender หรือไม่เริ่มต้น Extender ด้วยข้อมูลกล้อง:
Camera2/X เรียก
init()
บนอินสแตนซ์ Extender และส่งผ่าน ID ของกล้องและCameraCharacteristics
ข้อมูลแบบสอบถาม:
เรียกใช้คลาส Extender เพื่อดึงข้อมูล เช่น ความละเอียดที่รองรับ ยังคงบันทึกเวลาแฝงโดยประมาณ และดักจับคีย์คำขอจาก Extender เพื่อเตรียมพร้อมสำหรับการเปิดใช้งานส่วนขยาย
เปิดใช้งานส่วนขยายบน Extender:
คลาส Extender มีอินเทอร์เฟซทั้งหมดที่จำเป็นในการเปิดใช้งานคลาส มีกลไกในการขอการนำ OEM ไปใช้งานในไปป์ไลน์ Camera2 เช่น การฉีดพารามิเตอร์คำขอจับภาพหรือการเปิดใช้งานตัวประมวลผลภายหลัง
สำหรับประเภทตัวขยายขั้นสูง Camera2/X จะโต้ตอบกับ
SessionProcessorImpl
เพื่อเปิดใช้งานส่วนขยาย Camera2/X ดึงอินสแตนซ์SessionProcessorImpl
โดยการเรียกcreateSessionProcessor()
บน Extender
ส่วนต่อไปนี้จะอธิบายโฟลว์ส่วนขยายโดยละเอียดยิ่งขึ้น
การตรวจสอบเวอร์ชัน
เมื่อโหลดไลบรารีของผู้จำหน่าย OEM จากอุปกรณ์ขณะรันไทม์ Camera2/X จะตรวจสอบว่าไลบรารีเข้ากันได้กับเวอร์ชัน extensions-interface
หรือไม่ extensions-interface
ใช้การกำหนดเวอร์ชันเชิงความหมายหรือ MAJOR.MINOR.PATCH ตัวอย่างเช่น 1.1.0 หรือ 1.2.0 อย่างไรก็ตาม จะใช้เฉพาะเวอร์ชันหลักและเวอร์ชันรองเท่านั้นในระหว่างการตรวจสอบเวอร์ชัน
ในการตรวจสอบเวอร์ชัน Camera2/X จะเรียก ExtensionVersionImpl.checkApiVersion()
ด้วยเวอร์ชัน extensions-interface
ที่รองรับ จากนั้น Camera2/X จะใช้เวอร์ชันที่รายงานโดยไลบรารี OEM เพื่อพิจารณาว่าสามารถเปิดใช้งานส่วนขยายได้หรือไม่และควรเรียกใช้ความสามารถใด
ความเข้ากันได้ของเวอร์ชันหลัก
หากเวอร์ชันหลักของ ส่วนต่อขยาย-อินเทอร์เฟซ แตกต่างกันระหว่าง Camera2/X และไลบรารีของผู้จำหน่าย จะถือว่า ใช้งานร่วมกันไม่ได้ และส่วนขยายนั้นถูกปิดใช้งาน
ความเข้ากันได้ย้อนหลัง
ตราบใดที่เวอร์ชันหลักเหมือนกัน Camera2/X จะรับประกัน ความเข้ากันได้แบบย้อนหลัง กับไลบรารีของผู้จำหน่าย OEM ที่สร้างด้วย extensions-interface
เวอร์ชันก่อนหน้า ตัวอย่างเช่น หาก Camera2/X รองรับ extensions-interface
1.3.0 ไลบรารีของผู้จำหน่าย OEM ที่ใช้งาน 1.0.0, 1.1.0 และ 1.2.0 จะยังเข้ากันได้ นอกจากนี้ยังหมายความว่าหลังจากที่คุณใช้เวอร์ชันเฉพาะของไลบรารีของผู้ขาย Camera2/X จะทำให้แน่ใจว่าไลบรารี่จะเข้ากันได้กับเวอร์ชัน extension-interface
ที่กำลังจะมีขึ้น
ความเข้ากันได้ไปข้างหน้า
ความเข้ากันได้กับไลบรารีของผู้จำหน่ายของ extensions-interface
ขึ้นอยู่กับคุณ OEM หากคุณต้องการคุณลักษณะบางอย่างเพื่อใช้งานส่วนขยาย คุณอาจต้องการเปิดใช้งานส่วนขยายที่เริ่มต้นจากเวอร์ชันใดเวอร์ชันหนึ่ง ในกรณีนี้ คุณสามารถส่งคืนเวอร์ชัน extensions-interface
ที่รองรับได้เมื่อเวอร์ชันไลบรารี Camera2/X ตรงตามข้อกำหนด หากเวอร์ชัน Camera2/X ไม่รองรับ คุณสามารถส่งคืนเวอร์ชันที่เข้ากันไม่ได้ เช่น 99.0.0 เพื่อปิดใช้งานส่วนขยาย
การเริ่มต้นห้องสมุดผู้จัดจำหน่าย
หลังจากตรวจสอบเวอร์ชันของ extensions-interface
ใช้งานโดยไลบรารี OEM แล้ว Camera2/X จะเริ่มกระบวนการเริ่มต้น InitializerImpl.init()
วิธีการส่งสัญญาณไปยังไลบรารี OEM ว่าแอปกำลังพยายามใช้ส่วนขยาย
Camera2/X ไม่มีการเรียกอื่นใดไปยังไลบรารี OEM (นอกเหนือจากการตรวจสอบเวอร์ชัน) จนกว่าไลบรารีของผู้จำหน่าย OEM จะเรียก OnExtensionsInitializedCallback.onSuccess()
เพื่อแจ้งการเสร็จสิ้นของการเริ่มต้น
คุณต้องใช้ InitializerImpl
ของ extensions-interface
1.1.0 Camera2/X ข้ามขั้นตอนการเริ่มต้นไลบรารีหากไลบรารีของผู้จำหน่าย OEM ใช้ extensions-interface
1.0.0
Basic Extender กับ Advanced Extender
การใช้งาน extensions-interface
มีสองประเภท: Basic Extender และ Advanced Extender รองรับ Advanced Extender ตั้งแต่ extensions-interface
1.2.0
ใช้ Basic Extender สำหรับส่วนขยายที่ประมวลผลภาพในกล้อง HAL หรือใช้ตัวประมวลผลภายหลังที่สามารถประมวลผลสตรีม YUV
ใช้ Advanced Extender สำหรับส่วนขยายที่ต้องการปรับแต่งการกำหนดค่าสตรีม Camera2 และส่งคำขอจับภาพตามต้องการ
ดูตารางต่อไปนี้สำหรับการเปรียบเทียบ:
ตัวขยายพื้นฐาน | ตัวขยายขั้นสูง | |
---|---|---|
การกำหนดค่าสตรีม | แก้ไขแล้ว ดูตัวอย่าง: PRIVATE หรือ YUV_420_888 (หากมีโปรเซสเซอร์)ภาพนิ่ง: JPEG หรือ YUV_420_888 (หากมีโปรเซสเซอร์) | ปรับแต่งโดย OEM |
กำลังส่งคำขอจับ | มีเพียง Camera2/X เท่านั้นที่สามารถส่งคำขอจับภาพได้ คุณสามารถตั้งค่าพารามิเตอร์ให้กับคำขอเหล่านี้ได้ เมื่อมีการจัดเตรียมโปรเซสเซอร์สำหรับการจับภาพ Camera2/X สามารถส่งคำขอจับภาพได้หลายรายการ และส่งภาพทั้งหมดและผลการจับภาพไปยังโปรเซสเซอร์ | มีอินสแตนซ์ RequestProcessorImpl ให้คุณดำเนินการตามคำขอจับภาพของ camera2 และรับผลลัพธ์และรูปภาพ Camera2/X เรียกใช้ |
ตะขอในท่อส่งกล้อง |
|
|
เหมาะสำหรับ | ส่วนขยายที่ใช้ในกล้อง HAL หรือในโปรเซสเซอร์ที่ประมวลผลภาพ YUV |
|
เวอร์ชัน API ที่รองรับ | ส่วนขยาย Camera2: Android T (รุ่นทดลอง AOSP) หรือสูงกว่า ส่วนขยาย CameraX: ส่วนขยาย camera-extensions 1.1.0 หรือสูงกว่า | ส่วนขยาย Camera2: Android 12L หรือสูงกว่า ส่วนขยาย CameraX: ส่วนขยาย camera-extensions 1.2.0-alpha03 หรือสูงกว่า |
การไหลของแอป
ตารางต่อไปนี้แสดงโฟลว์แอปสามประเภทและการเรียกใช้ Camera Extensions API ที่เกี่ยวข้อง แม้ว่า Camera2/X จะให้บริการ API เหล่านี้ คุณต้องใช้ไลบรารีของผู้ขายอย่างเหมาะสมเพื่อรองรับโฟลว์เหล่านี้ ซึ่งเราจะอธิบายรายละเอียดเพิ่มเติมในส่วนต่อๆ ไป
ส่วนขยาย Camera2 | ส่วนขยาย CameraX | |
---|---|---|
ความพร้อมใช้งานของส่วนขยายข้อความค้นหา | CameraExtensionCharacteristics . getSupportedExtensions | ExtensionsManager. isExtensionAvailable |
สอบถามข้อมูล | CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys | ExtensionsManager. getEstimatedCaptureLatencyRange CameraX จัดการข้อมูลที่เหลือภายในไลบรารี |
ดูตัวอย่างและถ่ายภาพนิ่งโดยเปิดใช้งานส่วนขยาย | CameraDevice. createExtensionSession | val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector bindToLifecycle (เจ้าของวงจรชีวิต, ตัวเลือกกล้อง, ตัวอย่าง, ...) |
ตัวขยายพื้นฐาน
อินเทอร์เฟซ Basic Extender ช่วยให้สามารถเชื่อมต่อกับหลายตำแหน่งในไปป์ไลน์ของกล้องได้ ส่วนขยายแต่ละประเภทมีคลาส Extender ที่สอดคล้องกันซึ่ง OEM จำเป็นต้องใช้
ตารางต่อไปนี้แสดงรายการคลาส Extender ที่ OEMS ต้องใช้สำหรับแต่ละส่วนขยาย:
คลาส Extender ที่จะนำไปใช้ | |
---|---|
กลางคืน | NightPreviewExtenderImpl.java |
HDR | HdrPreviewExtenderImpl.java
|
รถยนต์ | AutoPreviewExtenderImpl.java
|
โบเก้ | BokehPreviewExtenderImpl.java
|
รีทัชใบหน้า | BeautyPreviewExtenderImpl.java
|
เราใช้ PreviewExtenderImpl
และ ImageCaptureExtenderImpl
เป็นตัวยึดตำแหน่งในตัวอย่างต่อไปนี้ แทนที่สิ่งเหล่านี้ด้วยชื่อของไฟล์จริงที่คุณกำลังใช้งาน
Basic Extender มีความสามารถดังต่อไปนี้:
- ฉีดพารามิเตอร์เซสชันเมื่อกำหนดค่า
CameraCaptureSession
(onPresetSession
) - แจ้งให้คุณทราบถึงเหตุการณ์เริ่มต้นและปิดเซสชันการจับภาพ และส่งคำขอเดียวเพื่อแจ้ง HAL ด้วยพารามิเตอร์ที่ส่งคืน (
onEnableSession
,onDisableSession
) - ฉีดพารามิเตอร์การดักจับสำหรับคำขอ (
PreviewExtenderImpl.getCaptureStage
,ImageCaptureExtenderImpl.getCaptureStages
) - เพิ่มโปรเซสเซอร์เพื่อดูตัวอย่างและยังคงจับภาพที่สามารถประมวลผลสตรีม
YUV_420_888
ได้
มาดูกันว่า Camera2/X เรียกใช้ extensions-interface
เพื่อให้บรรลุโฟลว์แอพทั้งสามที่กล่าวถึงข้างต้นอย่างไร
ขั้นตอนของแอป 1: ตรวจสอบความพร้อมใช้งานของส่วนขยาย
รูปที่ 3. App flow 1 บน Basic Extender
ในโฟลว์นี้ Camera2/X เรียก isExtensionAvailable()
โดยตรงของทั้ง PreviewExtenderImpl
และ ImageCaptureExtenderImpl
โดยไม่ต้องเรียก init()
คลาส Extender ทั้งสองต้องคืนค่า true
เพื่อเปิดใช้งานส่วนขยาย
นี่มักจะเป็นขั้นตอนแรกสำหรับแอปที่จะตรวจสอบว่าส่วนขยายที่ระบุนั้นรองรับ ID กล้องที่ระบุหรือไม่ก่อนที่จะเปิดใช้งานส่วนขยาย เนื่องจากส่วนขยายบางตัวรองรับเฉพาะ ID ของกล้องบางตัวเท่านั้น
ขั้นตอนของแอป 2: ข้อมูลการสืบค้น
รูปที่ 4. App flow 2 บน Basic Extender
หลังจากพิจารณาแล้วว่าส่วนขยายใช้งานได้หรือไม่ แอปควรสืบค้นข้อมูลต่อไปนี้ก่อนเปิดใช้งานส่วนขยาย
ยังคงจับภาพช่วงแฝง:
ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
ส่งคืนช่วงของเวลาแฝงในการจับภาพสำหรับแอปเพื่อประเมินว่าเหมาะสมหรือไม่ที่จะเปิดใช้งานส่วนขยายสำหรับสถานการณ์ปัจจุบันขนาดที่รองรับสำหรับพื้นผิวการแสดงตัวอย่างและการจับภาพ:
ImageCaptureExtenderImpl.getSupportedResolutions
และPreviewExtenderImpl.getSupportedResolutions
จะแสดงรายการรูปแบบภาพและขนาดที่รองรับรูปแบบพื้นผิวและขนาดคีย์คำขอและผลลัพธ์ที่รองรับ: Camera2/X เรียกใช้เมธอดต่อไปนี้เพื่อดึงคีย์คำขอการจับภาพที่รองรับและคีย์ผลลัพธ์จากการใช้งานของคุณ:
-
ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
-
ImageCaptureExtenderImpl.getAvailableCapturetResultKeys
-
Camera2/X จะเรียก init()
ก่อนเสมอในคลาส Extender เหล่านี้ก่อนที่จะสอบถามข้อมูลเพิ่มเติม
ขั้นตอนของแอป 3: ดูตัวอย่าง/บันทึกภาพนิ่งโดยเปิดใช้ส่วนขยาย (การใช้งาน HAL)
รูปที่ 5. App flow 3 บน Basic Extender
ไดอะแกรมด้านบนแสดงขั้นตอนหลักของการเปิดใช้งานการแสดงตัวอย่างและยังคงจับภาพด้วยส่วนขยายโดยไม่มีตัวประมวลผล ซึ่งหมายความว่า HAL ของกล้องจะประมวลผลส่วนขยาย
ในโฟลว์นี้ Camera2/X จะเรียกใช้ init()
ก่อน จากนั้นจึง onInit
ซึ่งจะแจ้งให้คุณทราบว่าเซสชันของกล้องกำลังจะเริ่มต้นด้วยส่วนขยายที่ระบุ คุณสามารถเริ่มต้นการยกของหนักได้ใน onInit()
เมื่อกำหนดค่า CameraCaptureSession
นั้น Camera2/X จะเรียกใช้ onPresetSession
เพื่อรับพารามิเตอร์เซสชัน หลังจากตั้งค่าเซสชันการจับภาพสำเร็จแล้ว Camera2/X จะเรียกใช้ onEnableSession
ส่งคืนอินสแตนซ์ CaptureStageImpl
ที่มีพารามิเตอร์การจับภาพ Camera2/X จะส่งคำขอเพียงครั้งเดียวพร้อมพารามิเตอร์การจับภาพเหล่านี้เพื่อแจ้ง HAL ในทำนองเดียวกัน ก่อนปิดเซสชันการจับภาพ Camera2/X จะเรียกใช้ onDisableSession
แล้วส่งคำขอเดียวพร้อมพารามิเตอร์การจับภาพที่ส่งคืน
คำขอที่เกิดซ้ำโดย Camera2/X มีพารามิเตอร์คำขอที่ส่งกลับโดย PreviewExtenderImpl.getCaptureStage()
นอกจากนี้ คำขอจับภาพยังคงประกอบด้วยพารามิเตอร์ที่ส่งคืนโดย ImageCaptureExtenderImpl.getCaptureStages()
สุดท้าย Camera2/X จะเรียกใช้ onDeInit()
หลังจากเซสชันกล้องเสร็จสิ้น คุณสามารถปล่อยทรัพยากรใน onDeinit()
ตัวประมวลผลตัวอย่าง
นอกจากกล้อง HAL แล้ว คุณยังสามารถใช้ส่วนขยายในโปรเซสเซอร์ได้อีกด้วย
ใช้ PreviewExtenderImpl.getProcessorType
เพื่อระบุประเภทโปรเซสเซอร์ตามที่อธิบายไว้ด้านล่าง:
PROCESSOR_TYPE_NONE
: ไม่มีโปรเซสเซอร์ ภาพจะถูกประมวลผลในกล้อง HALPROCESSOR_TYPE_REQUEST_UPDATE_ONLY
: ประเภทตัวประมวลผลช่วยให้คุณอัปเดตคำขอที่ทำซ้ำด้วยพารามิเตอร์คำขอการจับภาพใหม่ตามTotalCaptureResult
ล่าสุดPreviewExtenderImpl.getProcessor
ต้องส่งคืนอินสแตนซ์RequestUpdateProcessorImpl
ที่ประมวลผลอินสแตนซ์TotalCaptureResult
และส่งคืนอินสแตนซ์CaptureStageImpl
เพื่ออัปเดตคำขอที่เกิดซ้ำPreviewExtenderImpl.getCaptureStage()
ควรสะท้อนถึงผลลัพธ์ของการประมวลผลและส่งคืนCaptureStageImpl
ล่าสุดด้วยPROCESSOR_TYPE_IMAGE_PROCESSOR
: ประเภทนี้อนุญาตให้คุณใช้โปรเซสเซอร์เพื่อประมวลผลภาพYUV_420_888
และเขียนเอาต์พุตไปยังพื้นผิวPRIVATE
คุณต้องปรับใช้และส่งคืนอินสแตนซ์
PreviewImageProcessorImpl
ในPreviewExtenderImpl.getProcessor
โปรเซสเซอร์มีหน้าที่ในการประมวลผลภาพอินพุตYUV_420_888
ควรเขียนผลลัพธ์เป็นรูปแบบPRIVATE
ของการแสดงตัวอย่าง Camera2/X ใช้พื้นผิวYUV_420_888
แทนPRIVATE
เพื่อกำหนดค่าCameraCaptureSession
สำหรับการแสดงตัวอย่างดูภาพประกอบต่อไปนี้สำหรับโฟลว์:
รูปที่ 6. แสดงตัวอย่างโฟลว์ด้วย PreviewImageProcessorImpl
อินเทอร์เฟซ PreviewImageProcessorImpl
ขยาย ProcessImpl
และมีสามวิธีที่สำคัญ:
onOutputSurface(Surface surface, int imageFormat)
กำหนดพื้นผิวเอาต์พุตสำหรับโปรเซสเซอร์ สำหรับPreviewImageProcessorImpl
นั้นimageFormat
เป็นรูปแบบพิกเซล เช่นPixelFormat.RGBA_8888
onResolutionUpdate(Size size)
กำหนดขนาดของอิมเมจอินพุตonImageFormatUpdate(int imageFormat)
กำหนดรูปแบบภาพของภาพที่นำเข้า ปัจจุบันสามารถเป็นYUV_420_888
เท่านั้น
ตัวประมวลผลการจับภาพ
สำหรับการจับภาพนิ่ง คุณสามารถใช้ตัวประมวลผลได้โดยการส่งคืนอินสแตนซ์ CaptureProcessorImpl
โดยใช้ ImageCaptureExtenderImpl.getCaptureProcessor
โปรเซสเซอร์มีหน้าที่ประมวลผลรายการ YUV_420_888
ที่จับได้และอินสแตนซ์ TotalCaptureResult
และเขียนเอาต์พุตไปยังพื้นผิว YUV_420_888
คุณสามารถสันนิษฐานได้อย่างปลอดภัยว่ามีการเปิดใช้และเรียกใช้การแสดงตัวอย่างก่อนที่จะส่งคำขอจับภาพนิ่ง
ดูการไหลในแผนภาพด้านล่าง:
รูปที่ 7 ยังคงจับโฟลว์ด้วย CaptureProcessorImpl
Camera2/X ใช้พื้นผิวรูปแบบ
YUV_420_888
สำหรับการถ่ายภาพนิ่งเพื่อกำหนดค่าเซสชันการจับภาพ Camera2/X เตรียมCaptureProcessorImpl
โดยโทร:-
CaptureProcessorImpl.onImageFormatUpdate()
ด้วยYUV_420_888
-
CaptureProcessorImpl.onResolutionUpdate()
พร้อมขนาดภาพที่ป้อนเข้า -
CaptureProcessorImpl.onOutputSurface()
พร้อมพื้นผิวเอาต์พุตYUV_420_888
-
ImageCaptureExtenderImpl.getCaptureStages
ส่งคืนรายการของCaptureStageImpl
โดยที่แต่ละองค์ประกอบจะจับคู่กับอินสแตนซ์CaptureRequest
ด้วยพารามิเตอร์การจับภาพที่ส่งโดย Camera2/X ตัวอย่างเช่น หากส่งคืนรายการอินสแตนซ์ของCaptureStageImpl
สามรายการ Camera2/X จะส่งคำขอจับภาพสามรายการพร้อมพารามิเตอร์การจับภาพที่เกี่ยวข้องโดยใช้captureBurst
APIรูปภาพที่ได้รับและอินสแตนซ์
TotalCaptureResult
จะรวมกันและส่งไปยังCaptureProcessorImpl
เพื่อประมวลผลCaptureProcessorImpl
เขียนผลลัพธ์ Image (รูปแบบYUV_420_888
) ไปยังพื้นผิวเอาต์พุตที่ระบุโดยการonOutputSurface()
Camera2/X แปลงเป็นภาพ JPEG หากจำเป็น
รองรับคีย์คำขอจับภาพและผลลัพธ์
นอกจากการแสดงตัวอย่างและจับภาพของกล้องแล้ว แอปยังสามารถตั้งค่าการซูม พารามิเตอร์แฟลช หรือทริกเกอร์การแตะเพื่อโฟกัสได้ พารามิเตอร์เหล่านี้อาจเข้ากันไม่ได้กับการใช้งานส่วนขยายของคุณ
มีการเพิ่มเมธอดต่อไปนี้ใน extensions-interface
1.3.0 เพื่อให้คุณสามารถเปิดเผยพารามิเตอร์ที่การใช้งานของคุณรองรับ:
-
ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys()
ส่งคืนคีย์คำขอจับภาพที่สนับสนุนโดยการใช้งานของคุณ -
ImageCaptureExtenderImpl.getAvailableCaptureResultKeys()
ส่งคืนคีย์ผลลัพธ์การจับภาพที่มีอยู่ในผลการจับภาพ
หาก HAL ของกล้องประมวลผลส่วนขยาย Camera2/X จะดึงผลการจับภาพใน CameraCaptureSession.CaptureCallback
อย่างไรก็ตาม หากมีการใช้โปรเซสเซอร์ Camera2/X จะดึงผลการจับภาพใน ProcessResultImpl
ซึ่งถูกส่งไปยังเมธอด process()
ใน PreviewImageProcessorImpl
และ CaptureProcessorImpl
คุณมีหน้าที่รับผิดชอบในการรายงานผลการจับภาพผ่าน ProcessResultImpl
ไปยัง Camera2/X
ดูคำจำกัดความของอินเทอร์เฟซ CaptureProcessorImpl
ด้านล่างเป็นตัวอย่าง ใน extensions-interface
1.3.0 หรือสูงกว่า เรียก process()
ที่สอง:
Interface CaptureProcessorImpl extends ProcessorImpl {
// invoked when extensions-interface version < 1.3.0
void process(Map<Integer, Pair<Image, TotalCaptureResult>> results);
// invoked when extensions-interface version >= 1.3.0
void process(Map<Integer, Pair<Image, TotalCaptureResult>> results,
ProcessResultImpl resultCallback, Executor executor);
}
สำหรับการใช้งานกล้องทั่วไป เช่น การซูม การแตะเพื่อโฟกัส แฟลช และการชดเชยแสง เราขอแนะนำให้สนับสนุนปุ่มต่อไปนี้สำหรับทั้งคำขอจับภาพและผลการจับภาพ:
- ซูม:
-
CaptureRequest#CONTROL_ZOOM_RATIO
-
CaptureRequest#SCALER_CROP_REGION
-
- แตะเพื่อโฟกัส:
-
CaptureRequest#CONTROL_AF_MODE
-
CaptureRequest#CONTROL_AF_TRIGGER
-
CaptureRequest#CONTROL_AF_REGIONS
-
CaptureRequest#CONTROL_AE_REGIONS
-
CaptureRequest#CONTROL_AWB_REGIONS
-
- แฟลช:
-
CaptureRequest#CONTROL_AE_MODE
-
CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
-
CaptureRequest#FLASH_MODE
-
- การชดเชยแสง:
-
CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION
-
สำหรับ Basic Extenders ที่ใช้ 1.2.0 หรือเวอร์ชันก่อนหน้า CameraX Extensions API จะสนับสนุนคีย์ทั้งหมดข้างต้นอย่างชัดเจน สำหรับ extensions-interface
1.3.0 ทั้ง CameraX และ Camera2 จะปฏิบัติตามรายการที่ส่งคืนและรองรับเฉพาะคีย์ที่อยู่ในนั้น ตัวอย่างเช่น หากคุณตัดสินใจที่จะส่งคืนเฉพาะ CaptureRequest#CONTROL_ZOOM_RATIO
และ CaptureRequest#SCALER_CROP_REGION
ในการใช้งาน 1.3.0 นั่นหมายความว่าแอปรองรับการซูมเท่านั้น ในขณะที่ระบบไม่อนุญาตการแตะเพื่อโฟกัส แฟลช และการชดเชยแสง
ตัวขยายขั้นสูง
Advanced Extender เป็นประเภทของการใช้งานของผู้จำหน่ายตาม Camera2 API เพิ่มประเภท Extender นี้ใน extensions-interface
1.2.0 ทั้งนี้ขึ้นอยู่กับผู้ผลิตอุปกรณ์ ส่วนขยายอาจถูกนำไปใช้ในเลเยอร์แอป ซึ่งขึ้นอยู่กับปัจจัยต่อไปนี้:
การกำหนดค่าสตรีมแบบกำหนดเอง: กำหนดค่าสตรีมแบบกำหนดเอง เช่น สตรีม RAW หรือมีหลายสตรีมสำหรับ ID กล้องจริงที่แตกต่างกัน
ความสามารถในการส่งคำขอ Camera2: รองรับตรรกะการโต้ตอบที่ซับซ้อนซึ่งสามารถส่งคำขอจับภาพด้วยพารามิเตอร์ตามผลลัพธ์ของคำขอก่อนหน้า
Advanced Extender จัดเตรียม wrapper หรือเลเยอร์ระดับกลาง เพื่อให้คุณสามารถปรับแต่งการกำหนดค่าสตรีมและส่งคำขอดักจับได้ตามต้องการ
ไฟล์ที่จะนำไปใช้
หากต้องการเปลี่ยนไปใช้ Advanced Extender isAdvancedExtenderImplemented()
ใน ExtensionVersionImpl
ต้องคืนค่า true
สำหรับส่วนขยายแต่ละประเภท OEM ต้องใช้คลาส Extender ที่สอดคล้องกัน ไฟล์การใช้งาน Advanced Extender อยู่ในแพ็คเกจ ขั้นสูง
คลาส Extender ที่จะนำไปใช้ | |
---|---|
กลางคืน | advanced/NightAdvancedExtenderImpl.java |
HDR | advanced/HdrAdvancedExtenderImpl.java |
รถยนต์ | advanced/AutoAdvancedExtenderImpl.java |
โบเก้ | advanced/BokehAdvancedExtenderImpl.java |
รีทัชใบหน้า | advanced/BeautyAdvancedExtenderImpl.java |
เราใช้ AdvancedExtenderImpl
เป็นตัวยึดตำแหน่งในตัวอย่างต่อไปนี้ แทนที่ด้วยชื่อไฟล์ Extender สำหรับส่วนขยายที่คุณกำลังใช้งาน
มาดูกันว่า Camera2/X เรียกใช้ extensions-interface
เพื่อให้เกิดโฟลว์แอพทั้งสามได้อย่างไร
ขั้นตอนของแอป 1: ตรวจสอบความพร้อมใช้งานของส่วนขยาย
รูปที่ 8 App flow 1 บน Advanced Extender
ขั้นแรก แอปจะตรวจสอบว่ารองรับส่วนขยายที่ระบุหรือไม่
ขั้นตอนของแอป 2: ข้อมูลการสืบค้น
รูปที่ 9. App flow 2 บน Advanced Extender
หลังจากเรียก AdvancedExtenderImpl.init()
แล้ว แอปสามารถสืบค้นข้อมูลต่อไปนี้ใน AdvancedExtenderImpl
:
เวลาแฝงของการดักจับโดยประมาณ:
AdvancedExtenderImpl.getEstimatedCaptureLatencyRange()
ส่งคืนช่วงของเวลาแฝงในการดักจับสำหรับแอปเพื่อประเมินว่าเหมาะสมหรือไม่ที่จะเปิดใช้งานส่วนขยายสำหรับสถานการณ์ปัจจุบันความละเอียดที่รองรับสำหรับการแสดงตัวอย่างและการถ่ายภาพนิ่ง:
AdvancedExtenderImpl.getSupportedPreviewOutputResolutions()
ส่งคืนแผนที่ของรูปแบบรูปภาพไปยังรายการขนาดที่รองรับสำหรับรูปแบบและขนาดพื้นผิวการแสดงตัวอย่าง OEM ต้องรองรับรูปแบบPRIVATE
เป็นอย่างน้อยAdvancedExtenderImpl.getSupportedCaptureOutputResolutions()
ส่งคืนรูปแบบและขนาดที่รองรับสำหรับพื้นผิวการจับภาพนิ่ง OEM ต้องรองรับทั้งเอาต์พุตรูปแบบJPEG
และYUV_420_888
AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions()
ส่งคืนขนาดที่รองรับสำหรับสตรีมYUV_420_888
เพิ่มเติมสำหรับการวิเคราะห์รูปภาพ หากพื้นผิว YUV ของการวิเคราะห์ไม่ได้รับการสนับสนุนgetSupportedYuvAnalysisResolutions()
ควรคืนnull
หรือรายการว่าง
คีย์/ผลลัพธ์คำขอจับภาพที่พร้อมใช้งาน (เพิ่มใน
extensions-interface
1.3.0): Camera2/X เรียกใช้วิธีต่อไปนี้เพื่อดึงคีย์คำขอจับภาพที่รองรับและคีย์ผลลัพธ์จากการใช้งานของคุณ:-
AdvancedExtenderImpl.getAvailableCaptureRequestKeys
-
AdvancedExtenderImpl.getAvailableCaptureResultKeys
-
สำหรับข้อมูลเพิ่มเติม โปรดดู การสนับสนุนคีย์คำขอจับภาพและผลลัพธ์
ขั้นตอนของแอป 3: ดูตัวอย่าง/จับภาพนิ่งโดยเปิดใช้ส่วนขยาย
รูปที่ 10. App flow 3 บน Advanced Extender
ไดอะแกรมด้านบนแสดงโฟลว์หลักสำหรับการเริ่มแสดงตัวอย่างและยังคงจับภาพสำหรับประเภท Advanced Extender มาดูแต่ละขั้นตอนกัน
อินสแตนซ์
SessionProcessorImpl
การใช้งาน Advanced Extender หลักอยู่ใน
SessionProcessorImpl
ซึ่งรับผิดชอบในการจัดหาการกำหนดค่าเซสชันที่กำหนดเองและส่งคำขอจับภาพเพื่อเริ่มต้นการแสดงตัวอย่างและยังคงบันทึกคำขอAdvancedExtenderImpl.createSessionProcessor()
ถูกเรียกใช้เพื่อส่งคืนอินสแตนซ์SessionProcessorImpl
initSession
SessionProcessorImpl.initSession()
เริ่มต้นเซสชันสำหรับส่วนขยาย นี่คือที่ที่คุณจัดสรรทรัพยากรและส่งคืนการกำหนดค่าเซสชันสำหรับการเตรียมCameraCaptureSession
สำหรับพารามิเตอร์อินพุต Camera2/X จะระบุการกำหนดค่าพื้นผิวเอาต์พุตสำหรับการแสดงตัวอย่าง ถ่ายภาพนิ่ง และการวิเคราะห์ภาพ YUV ที่เป็นตัวเลือก การกำหนดค่าพื้นผิวเอาต์พุตนี้ (
OutputSurfaceImpl
) มีพื้นผิว ขนาด และรูปแบบภาพที่ดึงข้อมูลโดยวิธีการต่อไปนี้ในAdvancedExtenderImpl
:-
getSupportedPreviewOutputResolutions()
-
getSupportedCaptureOutputResolutions()
-
getSupportedYuvAnalysisResolutions()
คุณต้องส่งคืนอินสแตนซ์
Camera2SessionConfigImpl
ซึ่งประกอบด้วยรายการของอินสแตนซ์Camera2OutputConfigImpl
และพารามิเตอร์เซสชันที่ใช้สำหรับการกำหนดค่าCameraCaptureSession
คุณมีหน้าที่รับผิดชอบในการส่งออกภาพของกล้องที่ถูกต้องไปยังพื้นผิวที่ส่งออกโดย Camera2/X ต่อไปนี้คือตัวเลือกบางส่วนเพื่อเปิดใช้งานเอาต์พุต:- การประมวลผลในกล้อง HAL: คุณสามารถเพิ่มพื้นผิวเอาต์พุตไปยัง
CameraCaptureSession
ได้โดยตรงด้วยการใช้งานSurfaceOutputConfigImpl
สิ่งนี้จะกำหนดค่าพื้นผิวเอาต์พุตที่ให้มากับไปป์ไลน์ของกล้องและช่วยให้ HAL ของกล้องประมวลผลภาพได้ การประมวลผลพื้นผิว
ImageReader
ระดับกลาง (RAW, YUV ฯลฯ): เพิ่มพื้นผิวImageReader
ระดับกลางไปยังCameraCaptureSession
ด้วยอินสแตนซ์ImageReaderOutputConfigImpl
คุณต้องประมวลผลภาพระดับกลางและเขียนภาพผลลัพธ์ลงบนพื้นผิวเอาต์พุต
- ใช้การแชร์พื้นผิวของ Camera2: ใช้การแชร์พื้นผิวกับพื้นผิวอื่นโดยเพิ่มอินสแตนซ์
Camera2OutputConfigImpl
ใดๆ ลงในgetSurfaceSharingOutputConfigs()
ของอินสแตนซ์Camera2OutputConfigImpl
อื่น รูปแบบพื้นผิวและขนาดต้องเหมือนกัน
Camera2OutputConfigImpl
ทั้งหมดรวมถึงSurfaceOutputConfigImpl
และImageReaderOutputConfigImpl
ต้องมี ID ที่ไม่ซ้ำกัน (getId()
) ซึ่งใช้เพื่อระบุพื้นผิวเป้าหมายและดึงภาพจากImageReaderOutputConfigImpl
-
onCaptureSessionStart
และRequestProcessorImpl
เมื่อ
CameraCaptureSession
เริ่มทำงานและเฟรมเวิร์กของ Camera เรียกใช้onConfigured()
จากนั้น Camera2/X จะเรียกใช้SessionProcessorImpl.onCaptureSessionStart()
ด้วยตัวห่อหุ้มคำขอ Camera2RequestProcessImpl
Camera2/X ใช้RequestProcessImpl
ซึ่งช่วยให้คุณ ดำเนินการตามคำขอจับภาพ และ ดึงภาพ หากใช้ImageReaderOutputConfigImpl
RequestProcessImpl
API นั้นคล้ายกับ Camera2CameraCaptureSession
API ในแง่ของการดำเนินการตามคำขอ ความแตกต่างคือ:- พื้นผิวเป้าหมายถูกระบุโดย ID ของอินสแตนซ์
Camera2OutputConfigImpl
- ความสามารถในการดึงภาพของ
ImageReader
คุณสามารถเรียก
RequestProcessorImpl.setImageProcessor()
ด้วยCamera2OutputConfigImpl
ID ที่ระบุ เพื่อลงทะเบียนอินสแตนซ์ImageProcessorImpl
เพื่อรับรูปภาพอินสแตนซ์
RequestProcessImpl
ไม่ถูกต้องหลังจาก Camera2/X เรียกSessionProcessorImpl.onCaptureSessionEnd()
- พื้นผิวเป้าหมายถูกระบุโดย ID ของอินสแตนซ์
เริ่มการแสดงตัวอย่างและถ่ายภาพ
ในการใช้งาน Advanced Extender คุณสามารถส่งคำขอดักจับผ่านอินเทอร์เฟซ
RequestProcessorImpl
Camera2/X แจ้งให้คุณเริ่มคำขอแสดงตัวอย่างซ้ำหรือลำดับการจับภาพนิ่งโดยเรียกSessionProcessorImpl#startRepeating
และSessionProcessorImpl#startCapture
ตามลำดับ คุณควรส่งคำขอจับภาพเพื่อตอบสนองคำขอดูตัวอย่างและภาพนิ่งเหล่านี้Camera2/X ยังตั้งค่าพารามิเตอร์คำขอจับภาพผ่าน
SessionProcessorImpl#setParameters
คุณต้องตั้งค่าพารามิเตอร์คำขอเหล่านี้ (หากรองรับพารามิเตอร์) ทั้งคำขอซ้ำและคำขอเดี่ยวคุณต้องสนับสนุนอย่างน้อย
CaptureRequest.JPEG_ORIENTATION
และCaptureRequest.JPEG_QUALITY
extensions-interface
1.3.0 รองรับคำขอและคีย์ผลลัพธ์ซึ่งแสดงโดยวิธีการต่อไปนี้:-
AdvancedExtenderImpl.getAvailableCaptureRequestKeys()
-
AdvancedExtenderImpl.getAvailableCaptureResultKeys()
เมื่อนักพัฒนาตั้งค่าคีย์ในรายการ
getAvailableCaptureRequestKeys
คุณต้องเปิดใช้งานพารามิเตอร์และตรวจสอบให้แน่ใจว่าผลการดักจับมีคีย์ในรายการgetAvailableCaptureResultKeys
-
startTrigger
SessionProcessorImpl.startTrigger()
ถูกเรียกใช้เพื่อเริ่มต้นทริกเกอร์ เช่นCaptureRequest.CONTROL_AF_TRIGGER
และCaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER
คุณสามารถเพิกเฉยคีย์คำขอดักจับที่ไม่ได้โฆษณาในAdvancedExtenderImpl.getAvailableCaptureRequestKeys()
startTrigger()
ได้รับการสนับสนุนตั้งแต่extensions-interface
1.3.0 ช่วยให้แอพใช้การแตะเพื่อโฟกัสและแฟลชพร้อมส่วนขยายทำความสะอาด
เมื่อสิ้นสุดเซสชันการจับภาพ
SessionProcessorImpl.onCaptureSessionEnd()
จะถูกเรียกใช้ก่อนปิดCameraCaptureSession
หลังจากปิดเซสชันการดักจับแล้วdeInitSession()
จะดำเนินการล้างข้อมูล
รองรับการแสดงตัวอย่าง ถ่ายภาพนิ่ง และวิเคราะห์ภาพ
คุณควรใช้ส่วนขยายสำหรับทั้งการแสดงตัวอย่างและยังคงบันทึกกรณีการใช้งาน อย่างไรก็ตาม หากเวลาแฝงสูงเกินไปที่จะแสดงตัวอย่างได้อย่างราบรื่น คุณสามารถใช้เอฟเฟกต์สำหรับการถ่ายภาพนิ่งเท่านั้น
สำหรับประเภท Basic Extender โดยไม่คำนึงถึงการเปิดใช้งานเอฟเฟกต์สำหรับการแสดงตัวอย่าง คุณต้องติดตั้งทั้ง ImageCaptureExtenderImpl
และ PreviewExtenderImpl
สำหรับส่วนขยายที่กำหนด Often, an app also uses a YUV stream to analyze the image content such as finding QR codes or text. To better support this use case , you should support the stream combination of preview, still capture, and a YUV_420_888
stream for configuring CameraCaptureSession
. This means that if you implement a processor, then you have to support the stream combination of three YUV_420_888
streams.
For Advanced Extender, Camera2/X passes three output surfaces to the SessionProcessorImpl.initSession()
call. These output surfaces are for preview , still capture, and image analysis, respectively. You must ensure that preview and still capture output surfaces show the valid output. However, for the image analysis output surface, ensure it's working only when it's non-null. If your implementation can't support the image analysis stream, you can return an empty list in AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions()
. This ensures the image analysis output surface is always null in SessionProcessorImpl.initSession()
.
Support video capture
The current Camera Extension architecture supports only the preview and still capture use cases. We don't support enabling the extension on the MediaCodec
or MediaRecorder
surfaces for recording the video. However, it's possible for apps to record the preview output.
Supporting MediaCodec
and MediaRecorder
surfaces is under investigation.
Extensions interface version history
The following table shows the Camera Extension interface version history. You should always implement the vendor library with the latest version.
Version | Added features |
---|---|
1.0.0 |
|
1.1.0 |
|
1.2.0 |
|
1.3.0 |
|
Reference implementation
For a reference OEM vendor library implementation, see camera-testlib-extensions
. Note that this implementation performs passthroughs without actually implementing the effects.
Set up the vendor library on a device
The OEM vendor library isn't built into an app; it's loaded from the device at runtime by Camera2/X. In CameraX, the <uses-library>
tag declares that the androidx.camera.extensions.impl
library, which is defined in the AndroidManifest.xml
file of the camera-extensions
library, is a dependency of CameraX and must be loaded at runtime. In Camera2, the framework loads an extensions service that also declares that the <uses-library>
loads the same androidx.camera.extensions.impl
library at runtime.
This allows third-party apps using extensions to automatically load the OEM vendor library. The OEM library is marked as optional so apps can run on devices that don't have the library on the device. Camera2/X handles this behavior automatically when an app tries to use a camera extension as long as the device manufacturer places the OEM library on the device so that it can be discovered by the app.
To set up the OEM library on a device, do the following:
- Add a permission file, which is required by the
<uses-library>
tag, using the following format:/etc/permissions/ ANY_FILENAME .xml
. For example,/etc/permissions/camera_extensions.xml
. The files in this directory provide a mapping of the library named in<uses-library>
to the actual file path on the device. Use the example below to add the required information to the file.
-
name
must beandroidx.camera.extensions.impl
as that's the library that CameraX searches for. -
file
is the absolute path of the file that contains the extensions implementation (for example,/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>
-
In Android 12 or higher, devices supporting CameraX extensions must have the ro.camerax.extensions.enabled
property set to true
, which allows for querying whether a device supports extensions. To do this, add the following line in the device make file:
PRODUCT_VENDOR_PROPERTIES += \
ro.camerax.extensions.enabled=true \
Validation
To test your implementation of the OEM vendor library during the development stage, use the example app at androidx-main/camera/integration-tests/extensionstestapp/
, which runs through various vendor extensions.
After you complete your implementation, use the Camera Extensions Validation Tool to run automated and manual tests to verify that the vendor library is implemented correctly.
Frequently asked questions (FAQs)
Are there any restrictions on API levels?
Yes. This depends on the Android API feature set that's required by the OEM vendor library implementation. For example, ExtenderStateListener.onPresetSession()
uses the SessionConfiguration.setSessionParameters()
call to set a baseline set of tags. This call is available only on API level 28 and higher. For details on specific interface methods, see the API reference documentation .