หน้านี้ได้รับการแปลโดย Cloud Translation API

ส่วนขยายกล้อง

ผู้ผลิตอุปกรณ์สามารถแสดงเอฟเฟกต์พิเศษ เช่น โบเก้ โหมดกลางคืน และ 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 เรียกใช้ `startRepeating` และ `startCapture` บน `SessionProcessorImpl` เพื่อส่งสัญญาณให้ OEM เริ่มคำขอซ้ำสำหรับการแสดงตัวอย่าง และเริ่มลำดับการจับภาพนิ่งตามลำดับ
ตะขอในท่อส่งกล้อง	`onPresetSession` จัดเตรียมพารามิเตอร์เซสชัน `onEnableSession` ส่งคำขอเพียงครั้งเดียวหลังจากกำหนดค่า `CameraCaptureSession` แล้ว `onDisableSession` ส่งคำขอเดียวก่อนที่ `CameraCaptureSession` จะปิด	`initSession` เริ่มต้นและส่งคืนการกำหนดค่าเซสชันของ camera2 ที่กำหนดเองสำหรับการสร้างเซสชันการจับภาพ `onCaptureSessionStart` ถูกเรียกใช้ทันทีหลังจากกำหนดค่า `CameraCaptureSession` `onCaptureSessionEnd` ถูกเรียกใช้ก่อนที่ `CameraCaptureSession` จะปิด
เหมาะสำหรับ	ส่วนขยายที่ใช้ในกล้อง HAL หรือในโปรเซสเซอร์ที่ประมวลผลภาพ YUV	มีการใช้งานแบบ Camera2 สำหรับเอฟเฟกต์ ต้องการการกำหนดค่าสตรีมแบบกำหนดเอง เช่น สตรีม RAW ต้องการลำดับการจับภาพแบบโต้ตอบ
เวอร์ชัน 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

	ส่วนขยาย Camera2	ส่วนขยาย CameraX
ความพร้อมใช้งานของส่วนขยายข้อความค้นหา	`CameraExtensionCharacteristics . getSupportedExtensions`	`ExtensionsManager. isExtensionAvailable`
สอบถามข้อมูล	`CameraExtensionCharacteristics. getExtensionSupportedSizes` `CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis` `CameraExtensionCharacteristics. getAvailableCaptureRequestKeys` `CameraExtensionCharacteristics. getAvailableCaptureResultKeys`	`ExtensionsManager. getEstimatedCaptureLatencyRange` CameraX จัดการข้อมูลที่เหลือภายในไลบรารี
ดูตัวอย่างและถ่ายภาพนิ่งโดยเปิดใช้งานส่วนขยาย	`CameraDevice. createExtensionSession` `cameraExtensionsSession. setRepeatingRequest` `cameraExtensionsSession. capture`	`val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector` bindToLifecycle (เจ้าของวงจรชีวิต, ตัวเลือกกล้อง, ตัวอย่าง, ...)

สอบถามข้อมูล

CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys

ExtensionsManager. getEstimatedCaptureLatencyRange

CameraX จัดการข้อมูลที่เหลือภายในไลบรารี

ดูตัวอย่างและถ่ายภาพนิ่งโดยเปิดใช้งานส่วนขยาย

CameraDevice. createExtensionSession

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector

bindToLifecycle (เจ้าของวงจรชีวิต, ตัวเลือกกล้อง, ตัวอย่าง, ...)

ตัวขยายพื้นฐาน

อินเทอร์เฟซ Basic Extender ช่วยให้สามารถเชื่อมต่อกับหลายตำแหน่งในไปป์ไลน์ของกล้องได้ ส่วนขยายแต่ละประเภทมีคลาส Extender ที่สอดคล้องกันซึ่ง OEM จำเป็นต้องใช้

ตารางต่อไปนี้แสดงรายการคลาส Extender ที่ OEMS ต้องใช้สำหรับแต่ละส่วนขยาย:

	คลาส Extender ที่จะนำไปใช้
กลางคืน	`NightPreviewExtenderImpl.java` `NightImageCaptureExtenderImpl.java`
HDR	`HdrPreviewExtenderImpl.java` `HdrImageCaptureExtenderImpl.java`
รถยนต์	`AutoPreviewExtenderImpl.java` `AutoImageCaptureExtenderImpl.java`
โบเก้	`BokehPreviewExtenderImpl.java` `BokehImageCaptureExtenderImpl.java`
รีทัชใบหน้า	`BeautyPreviewExtenderImpl.java` `BeautyImageCaptureExtenderImpl.java`

เราใช้ PreviewExtenderImpl และ ImageCaptureExtenderImpl เป็นตัวยึดตำแหน่งในตัวอย่างต่อไปนี้ แทนที่สิ่งเหล่านี้ด้วยชื่อของไฟล์จริงที่คุณกำลังใช้งาน

Basic Extender มีความสามารถดังต่อไปนี้:

ฉีดพารามิเตอร์เซสชันเมื่อกำหนดค่า CameraCaptureSession ( onPresetSession )
แจ้งให้คุณทราบถึงเหตุการณ์เริ่มต้นและปิดเซสชันการจับภาพ และส่งคำขอเดียวเพื่อแจ้ง HAL ด้วยพารามิเตอร์ที่ส่งคืน ( onEnableSession , onDisableSession )
ฉีดพารามิเตอร์การดักจับสำหรับคำขอ ( PreviewExtenderImpl.getCaptureStage , ImageCaptureExtenderImpl.getCaptureStages )
เพิ่มโปรเซสเซอร์เพื่อดูตัวอย่างและยังคงจับภาพที่สามารถประมวลผลสตรีม YUV_420_888 ได้

มาดูกันว่า Camera2/X เรียกใช้ extensions-interface เพื่อให้บรรลุโฟลว์แอพทั้งสามที่กล่าวถึงข้างต้นอย่างไร

ขั้นตอนของแอป 1: ตรวจสอบความพร้อมใช้งานของส่วนขยาย

BasicExtenderAppFlow1

รูปที่ 3. App flow 1 บน Basic Extender

ในโฟลว์นี้ Camera2/X เรียก isExtensionAvailable() โดยตรงของทั้ง PreviewExtenderImpl และ ImageCaptureExtenderImpl โดยไม่ต้องเรียก init() คลาส Extender ทั้งสองต้องคืนค่า true เพื่อเปิดใช้งานส่วนขยาย

นี่มักจะเป็นขั้นตอนแรกสำหรับแอปที่จะตรวจสอบว่าส่วนขยายที่ระบุนั้นรองรับ ID กล้องที่ระบุหรือไม่ก่อนที่จะเปิดใช้งานส่วนขยาย เนื่องจากส่วนขยายบางตัวรองรับเฉพาะ ID ของกล้องบางตัวเท่านั้น

ขั้นตอนของแอป 2: ข้อมูลการสืบค้น

BasicExtenderAppFlow2

รูปที่ 4. App flow 2 บน Basic Extender

หลังจากพิจารณาแล้วว่าส่วนขยายใช้งานได้หรือไม่ แอปควรสืบค้นข้อมูลต่อไปนี้ก่อนเปิดใช้งานส่วนขยาย

ยังคงจับภาพช่วงแฝง: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange ส่งคืนช่วงของเวลาแฝงในการจับภาพสำหรับแอปเพื่อประเมินว่าเหมาะสมหรือไม่ที่จะเปิดใช้งานส่วนขยายสำหรับสถานการณ์ปัจจุบัน
ขนาดที่รองรับสำหรับพื้นผิวการแสดงตัวอย่างและการจับภาพ: ImageCaptureExtenderImpl.getSupportedResolutions และ PreviewExtenderImpl.getSupportedResolutions จะแสดงรายการรูปแบบภาพและขนาดที่รองรับรูปแบบพื้นผิวและขนาด
คีย์คำขอและผลลัพธ์ที่รองรับ: Camera2/X เรียกใช้เมธอดต่อไปนี้เพื่อดึงคีย์คำขอการจับภาพที่รองรับและคีย์ผลลัพธ์จากการใช้งานของคุณ:
- ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
- ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X จะเรียก init() ก่อนเสมอในคลาส Extender เหล่านี้ก่อนที่จะสอบถามข้อมูลเพิ่มเติม

ขั้นตอนของแอป 3: ดูตัวอย่าง/บันทึกภาพนิ่งโดยเปิดใช้ส่วนขยาย (การใช้งาน HAL)

BasicExtenderAppFlow3

รูปที่ 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 : ไม่มีโปรเซสเซอร์ ภาพจะถูกประมวลผลในกล้อง HAL
PROCESSOR_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
หมายเหตุ: getCaptureStages() ได้รับอนุญาตให้ส่งคืนอินสแตนซ์ CaptureStageImpl มากกว่าหนึ่งอินสแตนซ์เมื่อ getCaptureProcessor() ส่งคืนอินสแตนซ์เท่านั้น
รูปภาพที่ได้รับและอินสแตนซ์ 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: ตรวจสอบความพร้อมใช้งานของส่วนขยาย

AdvancedAppFlow1

รูปที่ 8 App flow 1 บน Advanced Extender

ขั้นแรก แอปจะตรวจสอบว่ารองรับส่วนขยายที่ระบุหรือไม่

ขั้นตอนของแอป 2: ข้อมูลการสืบค้น

AdvancedAppFlow2

รูปที่ 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: ดูตัวอย่าง/จับภาพนิ่งโดยเปิดใช้ส่วนขยาย

AdvancedAppFlow3

รูปที่ 10. App flow 3 บน Advanced Extender

ไดอะแกรมด้านบนแสดงโฟลว์หลักสำหรับการเริ่มแสดงตัวอย่างและยังคงจับภาพสำหรับประเภท Advanced Extender มาดูแต่ละขั้นตอนกัน

อินสแตนซ์ SessionProcessorImpl
การใช้งาน Advanced Extender หลักอยู่ใน SessionProcessorImpl ซึ่งรับผิดชอบในการจัดหาการกำหนดค่าเซสชันที่กำหนดเองและส่งคำขอจับภาพเพื่อเริ่มต้นการแสดงตัวอย่างและยังคงบันทึกคำขอ AdvancedExtenderImpl.createSessionProcessor() ถูกเรียกใช้เพื่อส่งคืนอินสแตนซ์ SessionProcessorImpl
หมายเหตุ: เซสชันกล้องสามารถใช้อินสแตนซ์ SessionProcessorImpl หลายครั้ง ด้วยเหตุนี้ การนำไปใช้งานจะต้องสามารถรองรับการ initSession() และ deInitSession() หลายรายการสำหรับอินสแตนซ์ 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/X สร้างและจัดการอินสแตนซ์ ImageReader ให้คุณ คุณสามารถตั้งค่าอินสแตนซ์ ImageProcessorImpl เพื่อดึงข้อมูลรูปภาพ
- ใช้การแชร์พื้นผิวของ Camera2: ใช้การแชร์พื้นผิวกับพื้นผิวอื่นโดยเพิ่มอินสแตนซ์ Camera2OutputConfigImpl ใดๆ ลงใน getSurfaceSharingOutputConfigs() ของอินสแตนซ์ Camera2OutputConfigImpl อื่น รูปแบบพื้นผิวและขนาดต้องเหมือนกัน
Camera2OutputConfigImpl ทั้งหมดรวมถึง SurfaceOutputConfigImpl และ ImageReaderOutputConfigImpl ต้องมี ID ที่ไม่ซ้ำกัน ( getId() ) ซึ่งใช้เพื่อระบุพื้นผิวเป้าหมายและดึงภาพจาก ImageReaderOutputConfigImpl
onCaptureSessionStart และ RequestProcessorImpl
เมื่อ CameraCaptureSession เริ่มทำงานและเฟรมเวิร์กของ Camera เรียกใช้ onConfigured() จากนั้น Camera2/X จะเรียกใช้ SessionProcessorImpl.onCaptureSessionStart() ด้วยตัวห่อหุ้มคำขอ Camera2 RequestProcessImpl Camera2/X ใช้ RequestProcessImpl ซึ่งช่วยให้คุณ ดำเนินการตามคำขอจับภาพ และ ดึงภาพ หากใช้ ImageReaderOutputConfigImpl
RequestProcessImpl API นั้นคล้ายกับ Camera2 CameraCaptureSession API ในแง่ของการดำเนินการตามคำขอ ความแตกต่างคือ:
- พื้นผิวเป้าหมายถูกระบุโดย ID ของอินสแตนซ์ Camera2OutputConfigImpl
- ความสามารถในการดึงภาพของ ImageReader
คุณสามารถเรียก RequestProcessorImpl.setImageProcessor() ด้วย Camera2OutputConfigImpl ID ที่ระบุ เพื่อลงทะเบียนอินสแตนซ์ ImageProcessorImpl เพื่อรับรูปภาพ
อินสแตนซ์ RequestProcessImpl ไม่ถูกต้องหลังจาก Camera2/X เรียก SessionProcessorImpl.onCaptureSessionEnd()
เริ่มการแสดงตัวอย่างและถ่ายภาพ
ในการใช้งาน 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	Version verification `ExtensionVersionImpl` Basic Extender `PreviewExtenderImpl` `ImageCaptureExtenderImpl` `Processor` `PreviewImageProcessorImpl` `CaptureProcessorImpl` `RequestUpdateProcessorImpl`
1.1.0	Library initialization `InitializerImpl` Expose supported resolutions `PreviewExtenderImpl.getSupportedResolutions` `ImageCaptureExtenderImpl.getSupportedResolutions`
1.2.0	AdvancedExtender `AdvancedExtenderImpl` `SessionProcessorImpl` Get estimated capture latency `ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange`
1.3.0	Expose supported capture request keys/results keys `ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys` and `getAvailableCaptureResultKeys` `AdvancedExtenderImpl.getAvailableCaptureRequestKeys` and `getAvailableCaptureResultKeys` New `process()` call that takes `ProcessResultImpl` in `PreviewImageProcessorImpl` and `CaptureProcessorImpl` Support trigger type request `AdvancedExtenderImpl.startTrigger`

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 be androidx.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 .