ชิ้นงานกล้อง

ผู้ผลิตอุปกรณ์สามารถแสดงส่วนขยาย เช่น โบเก้ โหมดกลางคืน และ HDR แก่นักพัฒนาแอปบุคคลที่สามผ่านอินเทอร์เฟซส่วนขยายกล้องที่จัดทำโดย ไลบรารีของผู้ให้บริการ OEM นักพัฒนาแอปสามารถใช้ Camera2 Extensions API และ CameraX Extensions API เพื่อเข้าถึงส่วนขยายที่ติดตั้งใช้งานในไลบรารีของผู้ให้บริการ OEM

ดูรายการส่วนขยายที่รองรับซึ่งเหมือนกันใน Camera2 และ CameraX ได้ที่ CameraX Extensions API หากต้องการเพิ่มส่วนขยาย ให้รายงานข้อบกพร่องด้วยเครื่องมือติดตามปัญหา

หน้านี้จะอธิบายวิธีติดตั้งใช้งานและเปิดใช้ไลบรารีของผู้ให้บริการ OEM ในอุปกรณ์

สถาปัตยกรรม

แผนภาพต่อไปนี้อธิบายสถาปัตยกรรมของอินเทอร์เฟซส่วนขยายกล้องหรือ extensions-interface

รูปที่ 1 แผนภาพสถาปัตยกรรมส่วนขยายกล้อง

ดังที่แสดงในไดอะแกรม หากต้องการรองรับส่วนขยายกล้อง คุณต้อง ใช้ extensions-interface ที่จัดทำโดยไลบรารีของผู้ให้บริการ OEM ไลบรารีของผู้ให้บริการ OEM ช่วยให้ API 2 รายการทำงานได้ ได้แก่ 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

คลาสตัวขยายการรีทัชใบหน้า (ใช้หากส่วนขยายการรีทัชใบหน้ารองรับ)

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

ยูทิลิตี (ไม่บังคับ ลบได้)

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

คุณไม่จำเป็นต้องระบุการติดตั้งใช้งานสำหรับส่วนขยายทุกรายการ หากไม่ได้ใช้ส่วนขยาย ให้ตั้งค่า isExtensionAvailable() เพื่อแสดงผล false หรือ นำคลาส Extender ที่เกี่ยวข้องออก API ของส่วนขยาย Camera2 และ CameraX จะรายงานต่อแอปว่าส่วนขยายไม่พร้อมใช้งาน

มาดูวิธีที่ Camera2 และ CameraX Extensions API โต้ตอบกับ ไลบรารีของผู้ให้บริการเพื่อเปิดใช้ส่วนขยายกัน แผนภาพต่อไปนี้แสดงโฟลว์แบบครบวงจรโดยใช้ส่วนขยาย Night เป็นตัวอย่าง

รูปที่ 2 การติดตั้งใช้งานส่วนขยายกลางคืน

1. การยืนยันเวอร์ชัน:

   การเรียกใช้ Camera2/X ExtensionVersionImpl.checkApiVersion() เพื่อให้มั่นใจว่าเวอร์ชัน extensions-interface ที่ OEM นำมาใช้จะเข้ากันได้กับ Camera2/X เวอร์ชันที่รองรับ

2. การเริ่มต้นใช้งานไลบรารีของผู้ให้บริการ:

   InitializerImpl มีเมธอด init() ที่เริ่มต้นไลบรารีของผู้ให้บริการ Camera2/X จะทำการเริ่มต้นให้เสร็จสมบูรณ์ก่อนที่จะเข้าถึงคลาส Extender

3. สร้างอินสแตนซ์ของคลาส Extender:

   สร้างอินสแตนซ์ของคลาส Extender สำหรับส่วนขยาย โดยตัวขยายมี 2 ประเภท ได้แก่ ตัวขยายพื้นฐานและตัวขยายขั้นสูง คุณต้องใช้ Extender ประเภทใดประเภทหนึ่งกับส่วนขยายทั้งหมด ดูข้อมูลเพิ่มเติมได้ที่ ตัวขยายสัญญาณพื้นฐานเทียบกับตัวขยายสัญญาณขั้นสูง

   Camera2/X จะสร้างอินสแตนซ์และโต้ตอบกับคลาส Extender เพื่อดึงข้อมูลและเปิดใช้ส่วนขยาย สำหรับส่วนขยายที่กำหนด Camera2/X สามารถ สร้างอินสแตนซ์ของคลาส Extender ได้หลายครั้ง ดังนั้น อย่าทำการเริ่มต้นที่ซับซ้อนในเครื่องมือสร้างหรือการเรียก init() ดำเนินการที่ต้องใช้ทรัพยากรมากเฉพาะเมื่อเซสชันกล้องกำลังจะเริ่ม เช่น เมื่อมีการเรียกใช้ onInit() ใน Basic Extender หรือมีการเรียกใช้ initSession() ใน Advanced Extender

   สำหรับส่วนขยายกลางคืน ระบบจะสร้างอินสแตนซ์ของคลาส Extender ต่อไปนี้สำหรับ ประเภท Extender พื้นฐาน

   • NightImageCaptureExtenderImpl.java
   • NightPreviewExtenderImpl.java

   และสำหรับประเภท Advanced Extender ให้ทำดังนี้

   • NightAdvancedExtenderImpl.java

4. ตรวจสอบความพร้อมใช้งานของส่วนขยาย

   ก่อนเปิดใช้ส่วนขยาย isExtensionAvailable() จะตรวจสอบว่าส่วนขยายพร้อมใช้งานในรหัสกล้องที่ระบุผ่านอินสแตนซ์ Extender หรือไม่

5. เริ่มต้นตัวขยายสัญญาณด้วยข้อมูลกล้อง

   Camera2/X จะเรียก init() ในอินสแตนซ์ Extender และส่งรหัสกล้อง และ CameraCharacteristics ไปให้

6. ข้อมูลการค้นหา:

   เรียกใช้คลาส Extender เพื่อดึงข้อมูล เช่น ความละเอียดที่รองรับ ค่าเวลาในการตอบสนองโดยประมาณของการจับภาพนิ่ง และคีย์คำขอจาก Extender เพื่อเตรียมพร้อมสำหรับการเปิดใช้ส่วนขยาย

7. เปิดใช้ส่วนขยายในตัวขยาย:

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

   สำหรับประเภท Extender ขั้นสูง 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 มี 2 ประเภท ได้แก่ Basic Extender และ Advanced Extender เราได้รองรับ Advanced Extender ตั้งแต่ extensions-interface 1.2.0

ใช้ Basic Extender สำหรับส่วนขยายที่ประมวลผลรูปภาพใน HAL ของกล้องหรือ ใช้ Post Processor ที่ประมวลผลสตรีม YUV ได้

ใช้ Advanced Extender สำหรับส่วนขยายที่ต้องปรับแต่งการกำหนดค่าสตรีม Camera2 และส่งคำขอจับภาพตามต้องการ

ดูการเปรียบเทียบได้ในตารางต่อไปนี้

โฟลว์ของแอป

ตารางต่อไปนี้แสดงโฟลว์ของแอป 3 ประเภทและการเรียก Camera Extensions API ที่เกี่ยวข้อง แม้ว่า Camera2/X จะมี API เหล่านี้ แต่คุณต้องติดตั้งใช้งานไลบรารีของผู้ให้บริการอย่างถูกต้องเพื่อรองรับโฟลว์เหล่านี้ ซึ่งเราจะอธิบายรายละเอียดเพิ่มเติมในส่วนถัดไป

Basic Extender

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

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

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

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

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

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

ขั้นตอนการทำงานของแอป 1: ตรวจสอบความพร้อมให้บริการของส่วนขยาย

รูปที่ 3 โฟลว์แอป 1 ใน Basic Extender

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

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

ขั้นตอนการทำงานของแอป 2: ค้นหาข้อมูล

รูปที่ 4 โฟลว์ของแอป 2 ใน Basic Extender

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

• ยังคงบันทึกช่วงเวลาในการจับภาพ: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange แสดงช่วงของ เวลาในการจับภาพเพื่อให้แอปประเมินว่าเหมาะสมที่จะ เปิดใช้ส่วนขยายสำหรับสถานการณ์ปัจจุบันหรือไม่

• ขนาดที่รองรับสำหรับพื้นผิวการแสดงตัวอย่างและการจับภาพ: ImageCaptureExtenderImpl.getSupportedResolutions และ PreviewExtenderImpl.getSupportedResolutions จะแสดงรายการรูปแบบรูปภาพและ ขนาดที่รองรับสำหรับรูปแบบและขนาดของพื้นผิว

• คีย์คำขอและผลลัพธ์ที่รองรับ: Camera2/X จะเรียกใช้เมธอดต่อไปนี้เพื่อดึงคีย์คำขอและคีย์ผลลัพธ์ของการจับภาพที่รองรับจากการติดตั้งใช้งานของคุณ

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
  • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

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

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

รูปที่ 5 โฟลว์ของแอป 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 และมีเมธอดที่สำคัญ 3 อย่างดังนี้

• 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

1. Camera2/X ใช้พื้นผิวรูปแบบ YUV_420_888 สำหรับการจับภาพนิ่งเพื่อกำหนดค่า เซสชันการจับภาพ Camera2/X เตรียม CaptureProcessorImpl โดยการเรียกใช้

   • CaptureProcessorImpl.onImageFormatUpdate() ด้วย YUV_420_888
   • CaptureProcessorImpl.onResolutionUpdate() ที่มีขนาดรูปภาพอินพุต
   • CaptureProcessorImpl.onOutputSurface() ที่มีเอาต์พุตเป็นYUV_420_888 พื้นผิว

2. ImageCaptureExtenderImpl.getCaptureStages จะแสดงรายการของ CaptureStageImpl โดยแต่ละองค์ประกอบจะแมปกับอินสแตนซ์ CaptureRequest ที่มีพารามิเตอร์การจับภาพ ซึ่งส่งโดย Camera2/X เช่น หากแสดงรายการอินสแตนซ์ 3 รายการ Camera2/X จะส่งคำขอจับภาพ 3 รายการพร้อมพารามิเตอร์การจับภาพที่เกี่ยวข้องโดยใช้ API captureBurst CaptureStageImpl

3. ระบบจะรวมรูปภาพที่ได้รับและอินสแตนซ์ TotalCaptureResult เข้าด้วยกัน แล้วส่งไปยัง CaptureProcessorImpl เพื่อประมวลผล

4. CaptureProcessorImpl จะเขียนรูปภาพผลลัพธ์ (รูปแบบ YUV_420_888) ไปยัง เอาต์พุต Surface ที่ระบุโดยการเรียกใช้ 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() ครั้งที่ 2 ดังนี้

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 หรือเวอร์ชันก่อนหน้า API ของ CameraX Extensions จะรองรับคีย์ทั้งหมดข้างต้นอย่างชัดเจน สำหรับ extensions-interface 1.3.0 ทั้ง CameraX และ Camera2 จะใช้รายการที่ส่งคืน และรองรับเฉพาะคีย์ที่อยู่ในรายการนั้น ตัวอย่างเช่น หากคุณตัดสินใจที่จะส่งคืนเฉพาะ CaptureRequest#CONTROL_ZOOM_RATIO และ CaptureRequest#SCALER_CROP_REGION ในการติดตั้งใช้งานเวอร์ชัน 1.3.0 นั่นหมายความว่าแอปจะรองรับเฉพาะการซูมเท่านั้น ส่วนการแตะเพื่อโฟกัส แฟลช และการชดเชยแสงจะไม่อนุญาต

Advanced Extender

Advanced Extender เป็นการติดตั้งใช้งานของผู้ให้บริการประเภทหนึ่งที่อิงตาม Camera2 API มีการเพิ่ม Extender ประเภทนี้ใน extensions-interface 1.2.0 ส่วนขยายอาจได้รับการติดตั้งใช้งานในเลเยอร์แอป ทั้งนี้ขึ้นอยู่กับผู้ผลิตอุปกรณ์ และปัจจัยต่อไปนี้

• การกำหนดค่าสตรีมที่กำหนดเอง: กำหนดค่าสตรีมที่กำหนดเอง เช่น สตรีม RAW หรือมีสตรีมหลายรายการสำหรับรหัสกล้องจริงที่แตกต่างกัน

• ความสามารถในการส่งคำขอ Camera2: รองรับตรรกะการโต้ตอบที่ซับซ้อน ซึ่งสามารถส่งคำขอจับภาพพร้อมพารามิเตอร์ตามผลลัพธ์ของ คำขอก่อนหน้า

Advanced Extender มี Wrapper หรือเลเยอร์กลางเพื่อให้คุณ ปรับแต่งการกำหนดค่าสตรีมและส่งคำขอจับภาพได้ตามต้องการ

ไฟล์ที่จะติดตั้งใช้งาน

หากต้องการเปลี่ยนไปใช้การติดตั้งใช้งาน Advanced Extender วิธี isAdvancedExtenderImplemented() ใน ExtensionVersionImpl ต้องแสดงผล true สำหรับส่วนขยายแต่ละประเภท OEM ต้องใช้คลาส Extender ที่เกี่ยวข้อง ไฟล์การติดตั้งใช้งาน Advanced Extender อยู่ในแพ็กเกจขั้นสูง

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

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

ขั้นตอนการทำงานของแอป 1: ตรวจสอบความพร้อมให้บริการของส่วนขยาย

รูปที่ 8 โฟลว์แอป 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

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

1. อินสแตนซ์ SessionProcessorImpl

   การติดตั้งใช้งาน Advanced Extender หลักอยู่ใน SessionProcessorImpl ซึ่ง มีหน้าที่ในการกำหนดค่าเซสชันที่กำหนดเองและส่ง คำขอแคปเจอร์เพื่อเริ่มการแสดงตัวอย่างและคำขอแคปเจอร์ภาพนิ่ง AdvancedExtenderImpl.createSessionProcessor() จะเรียกใช้เพื่อแสดงผลอินสแตนซ์ SessionProcessorImpl

2. initSession

   SessionProcessorImpl.initSession() จะเริ่มต้นเซสชันสำหรับส่วนขยาย ส่วนนี้คือที่ที่คุณจัดสรรทรัพยากรและส่งคืนการกำหนดค่าเซสชันเพื่อ เตรียม CameraCaptureSession

   สำหรับพารามิเตอร์อินพุต Camera2/X จะระบุการกำหนดค่าพื้นผิวเอาต์พุต สำหรับการแสดงตัวอย่าง การจับภาพนิ่ง และการวิเคราะห์รูปภาพ YUV ที่ไม่บังคับ การกำหนดค่าเอาต์พุต พื้นผิวนี้ (OutputSurfaceImpl) มีพื้นผิว ขนาด และรูปแบบรูปภาพ ที่ดึงข้อมูลโดยใช้วิธีการต่อไปนี้ใน AdvancedExtenderImpl

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

   คุณต้องส่งคืนอินสแตนซ์ Camera2SessionConfigImpl ซึ่งประกอบด้วยรายการอินสแตนซ์ Camera2OutputConfigImpl และพารามิเตอร์เซสชันที่ใช้ ในการกําหนดค่า CameraCaptureSession คุณมีหน้าที่ ส่งออกรูปภาพกล้องที่ถูกต้องไปยังพื้นผิวเอาต์พุตที่ส่งผ่านโดย Camera2/X ตัวเลือกบางอย่างในการเปิดใช้เอาต์พุตมีดังนี้

   • การประมวลผลใน HAL ของกล้อง: คุณเพิ่มเอาต์พุต Surface ลงใน CameraCaptureSession ได้โดยตรงด้วยการติดตั้งใช้งาน SurfaceOutputConfigImpl ซึ่งจะกำหนดค่าพื้นผิวเอาต์พุตที่ระบุให้กับไปป์ไลน์กล้อง และอนุญาตให้ HAL ของกล้องประมวลผลรูปภาพ

   • การประมวลผลพื้นผิว ImageReader ระดับกลาง (RAW, YUV ฯลฯ): เพิ่มพื้นผิว ImageReader ระดับกลางลงใน CameraCaptureSession ด้วยอินสแตนซ์ ImageReaderOutputConfigImpl

     คุณต้องประมวลผลรูปภาพกลางและเขียนรูปภาพผลลัพธ์ไปยัง พื้นผิวเอาต์พุต

   • ใช้การแชร์พื้นผิว Camera2: ใช้การแชร์พื้นผิวกับพื้นผิวอื่น โดยการเพิ่มอินสแตนซ์ Camera2OutputConfigImpl ใดก็ได้ลงใน เมธอด getSurfaceSharingOutputConfigs() ของอินสแตนซ์ Camera2OutputConfigImpl อื่น รูปแบบและขนาดของพื้นผิวต้องเหมือนกัน

   Camera2OutputConfigImpl ทั้งหมด รวมถึง SurfaceOutputConfigImpl และ ImageReaderOutputConfigImpl ต้องมีรหัสที่ไม่ซ้ำกัน (getId()) ซึ่งใช้เพื่อ ระบุแพลตฟอร์มเป้าหมายและดึงรูปภาพจาก ImageReaderOutputConfigImpl

3. onCaptureSessionStart และ RequestProcessorImpl

   เมื่อ CameraCaptureSession เริ่มทำงานและเฟรมเวิร์กกล้องเรียกใช้ onConfigured() แล้ว Camera2/X จะเรียกใช้ SessionProcessorImpl.onCaptureSessionStart() พร้อมกับโปรแกรมห่อหุ้มคำขอ Camera2 RequestProcessImpl Camera2/X ใช้ RequestProcessImpl ซึ่งช่วยให้คุณดำเนินการตามคำขอจับภาพและ ดึงข้อมูลรูปภาพได้หากใช้ ImageReaderOutputConfigImpl

   API ของ RequestProcessImpl คล้ายกับ API ของ Camera2 CameraCaptureSession ในแง่ของการดำเนินการคำขอ ความแตกต่างมีดังนี้

   • พื้นผิวเป้าหมายจะระบุโดยรหัสของอินสแตนซ์ Camera2OutputConfigImpl
   • ความสามารถในการดึงรูปภาพของ ImageReader

   คุณสามารถโทรหา RequestProcessorImpl.setImageProcessor() พร้อมระบุรหัส Camera2OutputConfigImpl เพื่อลงทะเบียนอินสแตนซ์ ImageProcessorImpl เพื่อรับรูปภาพ

   อินสแตนซ์ RequestProcessImpl จะใช้ไม่ได้หลังจากเรียกใช้ Camera2/X SessionProcessorImpl.onCaptureSessionEnd()

4. เริ่มการแสดงตัวอย่างและถ่ายรูป

   ในการติดตั้งใช้งาน Extender ขั้นสูง คุณสามารถส่งคำขอการจับภาพ ผ่านอินเทอร์เฟซ RequestProcessorImpl ได้ Camera2/X จะแจ้งให้คุณ เริ่มคำขอที่ทำซ้ำสำหรับตัวอย่างหรือลำดับการจับภาพนิ่งโดย เรียกใช้ SessionProcessorImpl#startRepeating และ SessionProcessorImpl#startCapture ตามลำดับ คุณควรส่งคำขอ Capture เพื่อตอบสนองคำขอแสดงตัวอย่างและคำขอจับภาพนิ่งเหล่านี้

   Camera2/X ยังตั้งค่าพารามิเตอร์คำขอจับภาพผ่าน SessionProcessorImpl#setParameters ด้วย คุณต้องตั้งค่าพารามิเตอร์คำขอเหล่านี้ (หากระบบรองรับพารามิเตอร์) ทั้งในคำขอที่ทำซ้ำและคำขอเดียว

   คุณต้องรองรับอย่างน้อย CaptureRequest.JPEG_ORIENTATION และ CaptureRequest.JPEG_QUALITY extensions-interface 1.3.0 รองรับคีย์คำขอ และผลลัพธ์ ซึ่งแสดงโดยเมธอดต่อไปนี้

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

   เมื่อนักพัฒนาแอปตั้งค่าคีย์ในgetAvailableCaptureRequestKeys รายการ คุณต้องเปิดใช้พารามิเตอร์และตรวจสอบว่าผลลัพธ์การจับภาพ มีคีย์ในgetAvailableCaptureResultKeys รายการ

5. startTrigger

   SessionProcessorImpl.startTrigger() จะเรียกใช้เพื่อเริ่มทริกเกอร์ เช่น CaptureRequest.CONTROL_AF_TRIGGER และ CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER คุณสามารถละเว้นคีย์คำขอการจับภาพที่ไม่ได้โฆษณาใน AdvancedExtenderImpl.getAvailableCaptureRequestKeys() ได้

   startTrigger() ได้รับการรองรับตั้งแต่ extensions-interface 1.3.0 ซึ่งช่วยให้แอปใช้การแตะเพื่อโฟกัสและแฟลชกับส่วนขยายได้

6. ล้างข้อมูล

   เมื่อสิ้นสุดเซสชันการจับภาพ SessionProcessorImpl.onCaptureSessionEnd() จะเรียกใช้ก่อนปิด CameraCaptureSession หลังจากปิดเซสชันการจับภาพแล้ว deInitSession() จะทำการล้างข้อมูล

รองรับการแสดงตัวอย่าง การจับภาพนิ่ง และการวิเคราะห์รูปภาพ

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

สำหรับประเภท Extender พื้นฐาน ไม่ว่าคุณจะเปิดใช้ส่วนขยายเพื่อแสดงตัวอย่างหรือไม่ คุณต้องใช้ทั้ง ImageCaptureExtenderImpl และ PreviewExtenderImpl สำหรับส่วนขยายที่กำหนด บ่อยครั้งที่แอปยังใช้สตรีม YUV เพื่อวิเคราะห์ เนื้อหารูปภาพ เช่น การค้นหาคิวอาร์โค้ดหรือข้อความ หากต้องการรองรับกรณีการใช้งานนี้ได้ดียิ่งขึ้น คุณควรสนับสนุนการรวมสตรีมของตัวอย่าง การจับภาพนิ่ง และสตรีม YUV_420_888 สำหรับการกำหนดค่า CameraCaptureSession ซึ่งหมายความว่า หากคุณใช้โปรเซสเซอร์ คุณจะต้องรองรับสตรีม ที่รวมสตรีม YUV_420_888 3 รายการ

สำหรับ Advanced Extender, Camera2/X จะส่งพื้นผิวเอาต์พุต 3 รายการไปยังการเรียก SessionProcessorImpl.initSession() พื้นผิวเอาต์พุตเหล่านี้มีไว้สำหรับการแสดงตัวอย่าง การจับภาพนิ่ง และการวิเคราะห์รูปภาพ ตามลำดับ คุณต้องตรวจสอบว่าพื้นผิวเอาต์พุตของตัวอย่าง และภาพนิ่งแสดงเอาต์พุตที่ถูกต้อง อย่างไรก็ตาม สำหรับพื้นผิวเอาต์พุตการวิเคราะห์รูปภาพ ให้ตรวจสอบว่าพื้นผิวทำงานเฉพาะเมื่อไม่ใช่ค่า Null หากการติดตั้งใช้งานไม่รองรับสตรีมการวิเคราะห์รูปภาพ คุณจะแสดงผลรายการว่างใน AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() ได้ ซึ่งจะช่วยให้มั่นใจได้ว่าพื้นผิวเอาต์พุตการวิเคราะห์รูปภาพจะเป็น Null เสมอใน SessionProcessorImpl.initSession()

รองรับการจับภาพวิดีโอ

สถาปัตยกรรมส่วนขยายกล้องปัจจุบันรองรับเฉพาะ Use Case ของการแสดงตัวอย่างและการจับภาพนิ่ง เราไม่รองรับการเปิดใช้ส่วนขยายใน MediaCodec หรือ MediaRecorder เพื่อบันทึกวิดีโอ อย่างไรก็ตาม แอปอาจบันทึกเอาต์พุตตัวอย่างได้

เรากำลังตรวจสอบการรองรับแพลตฟอร์ม MediaCodec และ MediaRecorder

ข้อมูลเมตาเฉพาะส่วนขยาย

สำหรับ Android 14 ขึ้นไป ข้อมูลเมตาเฉพาะส่วนขยาย ช่วยให้ไคลเอ็นต์ส่วนขยายกล้องตั้งค่าและรับการตั้งค่าคำขอ การจับภาพและผลลัพธ์เฉพาะส่วนขยายได้ โดยเฉพาะอย่างยิ่งไคลเอ็นต์ส่วนขยายกล้อง สามารถใช้EXTENSION_STRENGTHพารามิเตอร์คำขอจับภาพเพื่อควบคุม ความแรงของส่วนขยาย และEXTENSION_CURRENT_TYPEผลลัพธ์การจับภาพเพื่อ ระบุประเภทส่วนขยายที่เปิดใช้

บันทึกคำขอ

พารามิเตอร์คำขอ EXTENSION_STRENGTH การจับภาพ จะควบคุมความแรงของเอฟเฟกต์การประมวลผลภายหลังของส่วนขยาย ผลลัพธ์การจับภาพที่เกี่ยวข้องจะมีค่าความแรงเริ่มต้นหากไคลเอ็นต์ไม่ได้ตั้งค่าพารามิเตอร์นี้อย่างชัดเจน คุณใช้พารามิเตอร์นี้ได้ดังนี้สำหรับส่วนขยายประเภทต่อไปนี้

• BOKEH: ควบคุมระดับการเบลอ
• HDR และ NIGHT: ควบคุมจำนวนรูปภาพที่ผสานและ ความสว่างของรูปภาพสุดท้าย
• FACE_RETOUCH: ควบคุมระดับการปรับปรุงความงามและการปรับผิวให้เรียบเนียน

ช่วงที่รองรับสำหรับพารามิเตอร์ EXTENSION_STRENGTH อยู่ระหว่าง 0 ถึง 100 โดย 0 หมายถึงไม่มีการประมวลผลส่วนขยายหรือการส่งผ่านแบบง่าย และ 100 หมายถึงความแรงของส่วนขยายสูงสุดของเอฟเฟกต์การประมวลผล

หากต้องการเพิ่มการรองรับ EXTENSION_STRENGTH ให้ใช้ API พารามิเตอร์เฉพาะผู้ให้บริการ ที่เปิดตัวในเวอร์ชัน 1.3.0 ของอินเทอร์เฟซ ไลบรารีส่วนขยาย ดูข้อมูลเพิ่มเติมได้ที่ getAvailableCaptureRequestKeys()

ผลลัพธ์การจับภาพ

ผลลัพธ์ของ EXTENSION_CURRENT_TYPE การจับภาพช่วยให้การติดตั้งใช้งานส่วนขยายแจ้งให้ไคลเอ็นต์ทราบเกี่ยวกับประเภทส่วนขยายที่ใช้งานอยู่

เนื่องจากส่วนขยายที่ใช้ประเภท AUTO จะสลับไปมาระหว่างประเภทส่วนขยายแบบไดนามิก เช่น HDR และ NIGHT โดยขึ้นอยู่กับสภาพฉาก แอปส่วนขยายกล้อง จึงใช้ EXTENSION_CURRENT_TYPE เพื่อแสดงข้อมูลเกี่ยวกับส่วนขยายปัจจุบันที่เลือกโดยส่วนขยาย AUTO ได้

การจับภาพแบบเรียลไทม์ยังคงประมาณเวลาในการตอบสนอง

สำหรับ Android 14 ขึ้นไป ไคลเอ็นต์ส่วนขยายกล้อง จะค้นหาค่าประมาณเวลาในการตอบสนองของการจับภาพนิ่งแบบเรียลไทม์ตามฉากและ สภาพแวดล้อมได้โดยใช้ getRealtimeStillCaptureLatency() วิธีนี้ให้ค่าประมาณที่แม่นยำกว่าวิธีแบบคงที่ getEstimatedCaptureLatencyRangeMillis() แอปสามารถเลือกที่จะข้ามการประมวลผลส่วนขยาย หรือแสดงข้อบ่งชี้เพื่อแจ้งให้ผู้ใช้ทราบเกี่ยวกับการดำเนินการที่ใช้เวลานาน ได้โดยอิงตามค่าประมาณเวลาในการตอบสนอง

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

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

• ส่วนขยายพื้นฐาน ImageCaptureExtenderImpl.getRealtimeCaptureLatency()
• ส่วนขยายขั้นสูง SessionProcessorImpl.getRealtimeCaptureLatency

การเรียกกลับความคืบหน้าในการประมวลผลการจับภาพ

สำหรับ Android 14 ขึ้นไป ไคลเอ็นต์ส่วนขยายกล้อง จะรับการเรียกกลับสำหรับความคืบหน้าของการประมวลผลการจับภาพนิ่งที่ใช้เวลานาน ได้ แอปสามารถแสดงความคืบหน้าปัจจุบันต่อผู้ใช้เพื่อปรับปรุง ประสบการณ์ของผู้ใช้โดยรวม

แอปสามารถใช้โค้ดต่อไปนี้เพื่อผสานรวมฟีเจอร์นี้

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

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

• ส่วนขยายพื้นฐาน: ProcessResultImpl.onCaptureProcessProgressed()
• ส่วนขยายขั้นสูง: CaptureCallback.onCaptureProcessProgressed()

การจับภาพหลังดูโฆษณา

สำหรับ Android 14 ขึ้นไป ส่วนขยายกล้องจะ แสดงภาพหลังการประมวลผล (ภาพตัวอย่าง) โดยใช้ setPostviewOutputConfiguration เพื่อปรับปรุงประสบการณ์ของผู้ใช้ แอปสามารถแสดงรูปภาพหลังการดูเป็นตัวยึดตำแหน่งเมื่อส่วนขยายมีเวลาในการประมวลผลเพิ่มขึ้น และแทนที่รูปภาพเมื่อมีรูปภาพสุดท้าย แอปสามารถกำหนดค่า และออกคำขอการบันทึกหลังการดูได้โดยใช้รหัสอ้างอิงต่อไปนี้

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

การติดตั้งใช้งานของผู้ให้บริการต้องติดตั้งใช้งานสิ่งต่อไปนี้เพื่อรองรับการจับภาพนิ่งหลังการดู

• ส่วนขยายพื้นฐาน CaptureProcessorImpl.onPostviewOutputSurface และ CaptureProcessorImpl.processWithPostview

• ส่วนขยายขั้นสูง SessionProcessorImpl.startCaptureWithPostview

รองรับเอาต์พุต SurfaceView

สำหรับ Android 14 ขึ้นไป ไคลเอ็นต์ส่วนขยายกล้อง สามารถใช้เส้นทางการแสดงตัวอย่างที่เพิ่มประสิทธิภาพด้านพลังงานและประสิทธิภาพได้โดยการลงทะเบียนอินสแตนซ์ SurfaceView สำหรับเอาต์พุตตัวอย่างสำหรับคำขอที่ทำซ้ำ

การติดตั้งใช้งานส่วนขยายของผู้ให้บริการต้องสามารถสตรีมและแสดงตัวอย่างเอาต์พุตไปยังอินสแตนซ์ SurfaceView เพื่อรองรับเอาต์พุต SurfaceView หากต้องการ ยืนยันว่าระบบรองรับ ให้เรียกใช้SurfaceViewExtensionPreviewTest.java โมดูล CTS

ประเภทเซสชันเฉพาะผู้ให้บริการ

ฟีเจอร์นี้ช่วยให้การติดตั้งใช้งานส่วนขยายของผู้ให้บริการสามารถเลือกประเภทเซสชันที่เฉพาะเจาะจงของผู้ให้บริการที่จะตั้งค่าในเซสชันการจับภาพกล้องภายในแทนค่าเริ่มต้นได้

ฟีเจอร์นี้ทำงานภายในเฟรมเวิร์กและสแต็กของผู้ให้บริการอย่างสมบูรณ์ และไม่มีผลกระทบต่อ API ที่ไคลเอ็นต์/สาธารณะมองเห็น

หากต้องการเลือกประเภทเซสชันที่เฉพาะเจาะจงของผู้ให้บริการ ให้ใช้ข้อมูลต่อไปนี้กับไลบรารีส่วนขยาย * ExtenderStateListener.onSessionType() สำหรับส่วนขยายพื้นฐาน * Camera2SessionConfigImpl.getSessionType() สำหรับส่วนขยายขั้นสูง

ประวัติเวอร์ชันของอินเทอร์เฟซส่วนขยาย

ตารางต่อไปนี้แสดงประวัติเวอร์ชันของอินเทอร์เฟซส่วนขยายกล้อง คุณควรใช้ไลบรารีของผู้ให้บริการที่มีเวอร์ชันล่าสุดเสมอ

การใช้งานอ้างอิง

การติดตั้งใช้งานไลบรารีของผู้ให้บริการ OEM อ้างอิงต่อไปนี้พร้อมใช้งานใน frameworks/ex

• advancedSample: การติดตั้งใช้งานขั้นพื้นฐานของ Advanced Extender

• sample: การติดตั้งใช้งาน Basic Extender ขั้นพื้นฐาน

• service_based_sample: การติดตั้งใช้งานที่แสดงวิธีโฮสต์ ส่วนขยายกล้องใน Service การติดตั้งใช้งานนี้มีคอมโพเนนต์ต่อไปนี้

  • oem_library: ไลบรารี OEM ของส่วนขยายกล้องสำหรับ Camera2 และ CameraX Extensions API ที่ใช้ Extensions-Interface ซึ่งทำหน้าที่เป็นตัวกลางที่ ส่งต่อการเรียกจาก Extensions-Interface ไปยังบริการ ไลบรารีนี้ ยังมีไฟล์ AIDL และคลาส Wrapper เพื่อสื่อสารกับ บริการด้วย

    Advanced Extender จะเปิดใช้อยู่โดยค่าเริ่มต้น หากต้องการเปิดใช้ Basic Extender ให้เปลี่ยน ExtensionsVersionImpl#isAdvancedExtenderImplemented เป็น return false

  • extensions_service: ตัวอย่างการติดตั้งใช้งานบริการส่วนขยาย เพิ่มการใช้งานของคุณ ที่นี่ อินเทอร์เฟซที่จะใช้ในบริการจะคล้ายกับ Extensions-Interface เช่น การใช้ IAdvancedExtenderImpl.Stub จะดำเนินการเหมือนกับ AdvancedExtenderImpl ต้องระบุ ImageWrapper และ TotalCaptureResultWrapper เพื่อให้ Image และ TotalCaptureResult สามารถส่งผ่านได้

ตั้งค่าคลังของผู้ให้บริการในอุปกรณ์

ไลบรารีของผู้ให้บริการ OEM ไม่ได้สร้างไว้ในแอป แต่โหลดจากอุปกรณ์ ที่รันไทม์โดย Camera2/X ใน CameraX แท็ก <uses-library> จะประกาศว่าไลบรารี androidx.camera.extensions.impl ซึ่งกำหนดไว้ในไฟล์ AndroidManifest.xml ของไลบรารี camera-extensions เป็นทรัพยากร Dependency ของ CameraX และต้องโหลดที่รันไทม์ ใน Camera2 เฟรมเวิร์กจะโหลดบริการส่วนขยายที่ประกาศว่า<uses-library>โหลดไลบรารีandroidx.camera.extensions.implเดียวกันในรันไทม์ด้วย

ซึ่งจะช่วยให้แอปของบุคคลที่สามที่ใช้ส่วนขยายโหลดไลบรารีของผู้ให้บริการ OEM ได้โดยอัตโนมัติ ระบบจะทำเครื่องหมายไลบรารี OEM เป็น "ไม่บังคับ" เพื่อให้แอปสามารถทำงานบนอุปกรณ์ที่ไม่มีไลบรารีในอุปกรณ์ได้ Camera2/X จะจัดการลักษณะการทำงานนี้โดยอัตโนมัติเมื่อแอปพยายามใช้ส่วนขยายกล้อง ตราบใดที่ผู้ผลิตอุปกรณ์วางไลบรารี OEM ไว้ใน อุปกรณ์เพื่อให้แอปค้นพบได้

หากต้องการตั้งค่าคลัง OEM ในอุปกรณ์ ให้ทำดังนี้

1. เพิ่มไฟล์สิทธิ์ซึ่งต้องใช้แท็ก <uses-library> โดยใช้รูปแบบต่อไปนี้ /etc/permissions/ANY_FILENAME.xml เช่น /etc/permissions/camera_extensions.xml ไฟล์ในไดเรกทอรีนี้จะแสดงการแมปของไลบรารีที่ระบุชื่อใน <uses-library> กับเส้นทางไฟล์จริงในอุปกรณ์

2. ใช้ตัวอย่างด้านล่างเพื่อเพิ่มข้อมูลที่จำเป็นลงในไฟล์

   • name ต้องเป็น androidx.camera.extensions.impl เนื่องจากเป็นไลบรารีที่ CameraX ค้นหา
   • file คือเส้นทางสัมบูรณ์ของไฟล์ที่มีการติดตั้งใช้งานส่วนขยาย (เช่น /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 ขึ้นไป อุปกรณ์ที่รองรับส่วนขยาย CameraX ต้องตั้งค่าพร็อพเพอร์ตี้ ro.camerax.extensions.enabled เป็น true ซึ่งจะช่วยให้คุณค้นหาได้ว่าอุปกรณ์รองรับส่วนขยายหรือไม่ โดยเพิ่มบรรทัดต่อไปนี้ในไฟล์การสร้างอุปกรณ์

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

การตรวจสอบความถูกต้อง

หากต้องการทดสอบการติดตั้งใช้งานไลบรารีของผู้ให้บริการ OEM ในระหว่าง ขั้นตอนการพัฒนา ให้ใช้แอปตัวอย่างที่ androidx-main/camera/integration-tests/extensionstestapp/ ซึ่งจะเรียกใช้ส่วนขยายของผู้ให้บริการต่างๆ

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

โหมดฉากที่ขยายเทียบกับส่วนขยายกล้อง

สำหรับส่วนขยายโบเก้ นอกเหนือจากการเปิดเผยโดยใช้ส่วนขยายกล้องแล้ว คุณ ยังเปิดเผยส่วนขยายได้โดยใช้โหมดฉากแบบขยาย ซึ่งเปิดใช้ผ่าน ปุ่ม CONTROL_EXTENDED_SCENE_MODE ดูรายละเอียดการใช้งานเพิ่มเติมได้ที่โบเก้ของกล้อง

โหมดฉากแบบขยายมีข้อจำกัดน้อยกว่าเมื่อเทียบกับส่วนขยายกล้องสำหรับแอป camera2 เช่น คุณสามารถเปิดใช้โหมดฉากเพิ่มเติมในอินสแตนซ์ CameraCaptureSession ปกติที่รองรับการผสมสตรีมที่ยืดหยุ่นและพารามิเตอร์คำขอการจับภาพ ในทางตรงกันข้าม ส่วนขยายกล้อง รองรับเฉพาะชุดประเภทสตรีมที่กำหนดไว้และมีการรองรับพารามิเตอร์คำขอ การจับภาพแบบจำกัด

ข้อเสียของโหมดฉากแบบขยายคือคุณจะใช้ได้เฉพาะใน HAL ของกล้อง ซึ่งหมายความว่าต้องได้รับการยืนยันว่าทำงานได้ในการควบคุมที่ตั้งฉากทั้งหมดที่นักพัฒนาแอปใช้ได้

เราขอแนะนำให้แสดงโบเก้โดยใช้ทั้งโหมดฉากเพิ่มเติมและ Camera Extensions เนื่องจากแอปอาจต้องการใช้ API เฉพาะเพื่อเปิดใช้โบเก้ เราขอแนะนำให้ใช้โหมดฉากแบบขยายก่อน เนื่องจากเป็นวิธีที่ยืดหยุ่นที่สุดสำหรับแอปในการเปิดใช้ส่วนขยายโบเก้ จากนั้นคุณจะใช้ อินเทอร์เฟซส่วนขยายกล้องตามโหมดฉากที่ขยายได้ หากการติดตั้งใช้งานโบเก้ใน HAL ของกล้องเป็นเรื่องยาก เช่น เนื่องจากต้องมี โปรแกรมประมวลผลภายหลังที่ทำงานในเลเยอร์แอปเพื่อประมวลผลรูปภาพ เราขอแนะนำให้ติดตั้งใช้งาน ส่วนขยายโบเก้โดยใช้อินเทอร์เฟซส่วนขยายของกล้อง

คำถามที่พบบ่อย

ระดับ API มีข้อจำกัดไหม

ได้ ซึ่งขึ้นอยู่กับชุดฟีเจอร์ Android API ที่การติดตั้งใช้งานไลบรารีของผู้ให้บริการ OEM ต้องใช้ เช่น ExtenderStateListener.onPresetSession() ใช้การเรียก SessionConfiguration.setSessionParameters() เพื่อตั้งค่าพื้นฐานของแท็ก การเรียกนี้ใช้ได้ใน API ระดับ 28 ขึ้นไปเท่านั้น ดูรายละเอียดเกี่ยวกับเมธอดอินเทอร์เฟซที่เฉพาะเจาะจงได้ใน เอกสารอ้างอิง API