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

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

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

หน้านี้อธิบายวิธีใช้งานและเปิดใช้งานไลบรารีผู้จำหน่าย 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 ที่เกี่ยวข้อง API ของ Camera2 และ CameraX Extensions รายงานไปยังแอปว่าส่วนขยายไม่พร้อมใช้งาน

มาดูวิธีที่ 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 สำหรับส่วนขยาย Extender มีสองประเภท: Basic Extender และ Advanced Extender คุณต้องใช้ Extender ประเภทเดียวสำหรับส่วนขยายทั้งหมด สำหรับข้อมูลเพิ่มเติม โปรดดูที่ Basic Extender กับ Advanced Extender

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

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

    • NightImageCaptureExtenderImpl.java
    • NightPreviewExtenderImpl.java

    และสำหรับประเภท Advanced Extender:

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

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

  5. เริ่มต้น Extender ด้วยข้อมูลกล้อง:

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

  6. ข้อมูลแบบสอบถาม:

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

  7. เปิดใช้งานส่วนขยายบน Extender:

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

    สำหรับประเภท Advanced 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

Extender พื้นฐานกับ 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 เริ่มต้นและส่งคืนการกำหนดค่าเซสชันของกล้อง 2 ที่กำหนดเองสำหรับการสร้างเซสชันการจับภาพ
  • onCaptureSessionStart จะถูกเรียกใช้ทันทีหลังจากกำหนดค่า CameraCaptureSession แล้ว
  • onCaptureSessionEnd จะถูกเรียกใช้ก่อนที่ CameraCaptureSession จะถูกปิด
เหมาะสำหรับ ส่วนขยายที่ใช้ในกล้อง HAL หรือในโปรเซสเซอร์ที่ประมวลผลภาพ YUV
  • มีการใช้งานที่ใช้ Camera2 สำหรับส่วนขยาย
  • ต้องการการกำหนดค่าสตรีมแบบกำหนดเอง เช่น สตรีม RAW
  • ต้องการลำดับการจับแบบโต้ตอบ
เวอร์ชัน API ที่รองรับ ส่วนขยาย Camera2: Android 13 หรือสูงกว่า
ส่วนขยาย 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

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector ผูก ToLifecycle (เจ้าของวงจรชีวิต, ตัวเลือกกล้อง, การแสดงตัวอย่าง, ... )

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

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

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

คลาส Extender ที่จะนำไปใช้
กลางคืน NightPreviewExtenderImpl.java

NightImageCaptureExtenderImpl.java

เอชดีอาร์ 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 ขั้นตอนของแอป 1 บน Basic Extender

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

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

App Flow 2: ค้นหาข้อมูล

BasicExtenderAppFlow2

รูปที่ 4 ขั้น ตอนของแอป 2 บน Basic Extender

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

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

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

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

    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
    • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

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

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

BasicExtenderAppFlow3

รูปที่ 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 และมีวิธีการที่สำคัญสามวิธี:

  • 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 ส่ง ตัวอย่างเช่น หากส่งคืนรายการอินสแตนซ์ CaptureStageImpl สามรายการ Camera2/X จะส่งคำขอจับภาพสามคำขอพร้อมพารามิเตอร์การจับที่สอดคล้องกันโดยใช้ captureBurst API

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

  4. CaptureProcessorImpl เขียนอิมเมจผลลัพธ์ (รูปแบบ 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
เอชดีอาร์ advanced/HdrAdvancedExtenderImpl.java
อัตโนมัติ advanced/AutoAdvancedExtenderImpl.java
โบเก้ advanced/BokehAdvancedExtenderImpl.java
รีทัชใบหน้า advanced/BeautyAdvancedExtenderImpl.java

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

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

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

ขั้นสูงAppFlow1

รูปที่ 8 ขั้นตอนของแอป 1 บน Advanced Extender

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

App Flow 2: ค้นหาข้อมูล

ขั้นสูงAppFlow2

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

ขั้นสูงAppFlow3

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

แผนภาพด้านบนแสดงขั้นตอนหลักในการเริ่มแสดงตัวอย่างและยังคงจับภาพสำหรับประเภท 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: คุณสามารถเพิ่มพื้นผิวเอาท์พุตลงใน CameraCaptureSession ได้โดยตรงด้วยการใช้ SurfaceOutputConfigImpl ซึ่งจะกำหนดค่าพื้นผิวเอาต์พุตที่ให้มาให้กับไปป์ไลน์ของกล้อง และอนุญาตให้กล้อง HAL ประมวลผลภาพได้
    • การประมวลผลพื้นผิว ImageReader ระดับกลาง (RAW, YUV ฯลฯ): เพิ่มพื้นผิว ImageReader ระดับกลางให้กับ CameraCaptureSession ด้วยอินสแตนซ์ ImageReaderOutputConfigImpl

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

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

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

  3. onCaptureSessionStart และ RequestProcessorImpl

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

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

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

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

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

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

    ในการใช้งาน 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

  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() จะดำเนินการล้างข้อมูล

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

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

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

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

สนับสนุนการจับวิดีโอ

สถาปัตยกรรมส่วนขยายกล้องปัจจุบันรองรับเฉพาะตัวอย่างและยังคงจับกรณีการใช้งาน เราไม่สนับสนุนการเปิดใช้งานส่วนขยายบนพื้นผิว 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();

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

การจับภาพความคืบหน้าการประมวลผลการโทรกลับ

สำหรับ 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
    }
  }
…
}

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

Postview ยังคงจับภาพ

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

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

เพื่อสนับสนุน PostView ยังคงจับภาพการใช้งานผู้ขายของคุณจะต้องใช้สิ่งต่อไปนี้:

สนับสนุนเอาต์พุต SurfaceView

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

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

ประเภทเซสชันเฉพาะของผู้ขาย

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

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

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

ประวัติความเป็นมาของส่วนขยาย

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

เวอร์ชัน เพิ่มคุณสมบัติ
1.0.0
  • การยืนยันเวอร์ชัน
    • ExtensionVersionImpl
  • Extender พื้นฐาน
    • PreviewExtenderImpl
    • ImageCaptureExtenderImpl
    • Processor
      • PreviewImageProcessorImpl
      • CaptureProcessorImpl
      • RequestUpdateProcessorImpl
1.1.0
  • การเริ่มต้นห้องสมุด
    • InitializerImpl
  • เปิดเผยมติที่รองรับ
    • PreviewExtenderImpl.getSupportedResolutions
    • ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0
  • ขั้นสูง
    • AdvancedExtenderImpl
    • SessionProcessorImpl
  • รับแฝงการจับภาพโดยประมาณ
    • ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0
  • เปิดเผยปุ่มร้องขอการจับภาพที่รองรับ/ปุ่มผลลัพธ์
    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys และ getAvailableCaptureResultKeys
    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys และ getAvailableCaptureResultKeys
    • process() การโทรที่ใช้ ProcessResultImpl ใน PreviewImageProcessorImpl และ CaptureProcessorImpl
    • สนับสนุนคำขอประเภททริกเกอร์
      • AdvancedExtenderImpl.startTrigger
1.4.0
  • ข้อมูลเมตาเฉพาะส่วนขยาย
  • ไดนามิกยังคงจับประมาณเวลาแฝง
  • การจับภาพความคืบหน้าการประมวลผลการโทรกลับ
  • Postview ยังคงจับภาพ
  • รองรับเอาต์พุต SurfaceView
  • ประเภทเซสชันเฉพาะของผู้ขาย

การดำเนินการอ้างอิง

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

  • advancedSample : การใช้งานขั้นพื้นฐานของ Extender ขั้นสูง

  • sample : การใช้งานพื้นฐานของตัวขยายพื้นฐาน

  • service_based_sample : การใช้งานที่แสดงให้เห็นถึงวิธีการโฮสต์ส่วนขยายกล้องใน Service การใช้งานนี้มีส่วนประกอบต่อไปนี้:

    • oem_library : ส่วนขยายกล้อง OEM ไลบรารีสำหรับ CAMERAN2 และ APIs ส่วนขยายกล้องและกล้อง APIs ที่ใช้ Extensions-Interface สิ่งนี้ทำหน้าที่เป็น passthrough ที่ส่งต่อการโทรจาก Extensions-Interface ไปยังบริการ ไลบรารีนี้ยังมีไฟล์ AIDL และคลาส wrapper เพื่อสื่อสารกับบริการ

      Extender ขั้นสูงถูกเปิดใช้งานโดยค่าเริ่มต้น ในการเปิดใช้งานตัวขยายพื้นฐานให้เปลี่ยน ExtensionsVersionImpl#isAdvancedExtenderImplemented เพื่อส่งคืน false

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

ตั้งค่าไลบรารีผู้ขายบนอุปกรณ์

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

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

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

การตรวจสอบ

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

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

โหมด Extended Scene กับส่วนขยายของกล้อง

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

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

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

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

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

มีข้อ จำกัด เกี่ยวกับระดับ API หรือไม่?

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