הרחבות למצלמה

יצרני מכשירים יכולים לחשוף הרחבות כגון בוקה, מצב לילה ו-HDR למפתחים של צד שלישי דרך ממשק הרחבות למצלמה המסופק על ידי ספריית ספקי ה-OEM. מפתחים יכולים להשתמש ב- Camera2 Extensions API וב- CameraX Extensions API כדי לגשת לתוספים המיושמים בספריית ספקי OEM.

לרשימה של הרחבות נתמכות, שהיא זהה בכל Camera2 ו-CameraX, ראה CameraX Extensions API . אם ברצונך להוסיף הרחבה, שלח באג באמצעות ה- Issue Tracker .

דף זה מתאר כיצד ליישם ולהפעיל את ספריית ספקי OEM במכשירים.

ארכיטקטורה

התרשים הבא מתאר את הארכיטקטורה של ממשק הרחבות למצלמה או extensions-interface :

איור 1. דיאגרמת ארכיטקטורת הרחבות מצלמה

כפי שמוצג בתרשים, כדי לתמוך בהרחבות מצלמה, עליך ליישם את extensions-interface שסופק על ידי ספריית ספקי ה-OEM. ספריית ספקי ה-OEM שלך מאפשרת שני ממשקי API: CameraX Extensions API ו- Camera2 Extensions API , המשמשים את יישומי CameraX ו-Camera2, בהתאמה, כדי לגשת לתוספי ספקים.

הטמעת ספריית ספקי OEM

כדי להטמיע את ספריית ספקי ה-OEM, העתק את קבצי camera-extensions-stub לפרויקט של ספריית מערכת. קבצים אלה מגדירים את ממשק הרחבות למצלמה.

הערה: עליך לשמור את הקבצים תחת חבילות androidx.camera.extensions.impl Java. לעיון, עיין בפרויקט לדוגמה .

קבצי 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

שיעורי הרחבת Bokeh (הטמיע את זה אם הרחבת Bokeh נתמכת)

• 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 Extensions מדווחים לאפליקציה שהתוסף אינו זמין.

הערה: מכיוון שספריית הספקים של OEM פועלת כחלק מתהליך אפליקציה של צד שלישי, ספריית הספק לא חייבת לדרוש הרשאות מיוחדות (כגון הרשאות מערכת).

בואו נעבור על האופן שבו ממשקי ה-API של Camera2 ו-CameraX Extensions מקיימים אינטראקציה עם ספריית הספק כדי לאפשר הרחבה. התרשים הבא ממחיש את הזרימה מקצה לקצה באמצעות הרחבת Night כדוגמה:

איור 2. יישום הארכת לילה

הערה: מטעמי נוחות, אנו מתייחסים לממשקי ה-API של Camera2 ו-CameraX Extensions כ- Camera2/X .

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

   ולסוג המתקדם המתקדם:

   • NightAdvancedExtenderImpl.java

4. בדוק את זמינות התוספים:

   לפני הפעלת התוסף, isExtensionAvailable() בודק אם התוסף זמין במזהה המצלמה שצוין דרך מופע 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 כדי לקבוע אם ניתן להפעיל את התוסף ומה היכולות שעליו להפעיל.

הערה: checkApiVersion() לא אמורה להחזיר גרסת extensions-interface שהיא עדכנית יותר מהגרסה הנתמכת Camera2/X. לדוגמה, אם Camera2/X תומכת ב-1.3.0 וספריית ספקי ה-OEM תומכת ב-1.4.0, היא אמורה להחזיר 1.3.0 במקום 1.4.0.

תאימות גרסאות עיקריות

אם הגרסאות העיקריות של ממשק התוסף שונות בין 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 או השתמשו ב-post processor המסוגל לעבד זרמי 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 נתמכת	הרחבות למצלמה 2: אנדרואיד 13 ומעלה הרחבות CameraX: camera-extensions 1.1.0 ומעלה	הרחבות למצלמה 2: אנדרואיד 12L ומעלה הרחבות CameraX: camera-extensions 1.2.0-alpha03 ומעלה

הערה: אם ExtensionVersionImpl.isAdvancedExtenderImplemented() מחזירה true , עליך ליישם את כל ההרחבות ב-Advanced Extender. אם isAdvancedExtenderImplemented() מחזירה false , עליך ליישם את כל ההרחבות ב-Basic Extender.

אפליקציה זורמת

הטבלה הבאה מציגה שלושה סוגים של זרימת אפליקציות וקריאות ה-API של תוספי המצלמה המתאימות להם. בעוד ש-Camera2/X מספקים ממשקי API אלה, עליך ליישם כראוי את ספריית הספקים כדי לתמוך בזרימות אלו, אותן אנו מתארים ביתר פירוט בסעיף מאוחר יותר.

	הרחבות למצלמה 2	הרחבות 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(lifecycleOwner, cameraSelector, תצוגה מקדימה, ...)

מאריך בסיסי

ממשק ה-Basic Extender מספק ווים למספר מקומות בצנרת המצלמה. לכל סוג הרחבה יש מחלקות Extender תואמות שיצרני OEM צריכים ליישם.

הטבלה הבאה מפרטת את מחלקות ה-Extender ש-OEM צריכים ליישם עבור כל הרחבה:

	מרחיבים שיעורים ליישום
לַיְלָה	NightPreviewExtenderImpl.java NightImageCaptureExtenderImpl.java
HDR	HdrPreviewExtenderImpl.java HdrImageCaptureExtenderImpl.java
אוטומטי	AutoPreviewExtenderImpl.java AutoImageCaptureExtenderImpl.java
בוקה	BokehPreviewExtenderImpl.java BokehImageCaptureExtenderImpl.java
ריטוש פנים	BeautyPreviewExtenderImpl.java BeautyImageCaptureExtenderImpl.java

אנו משתמשים PreviewExtenderImpl וב- ImageCaptureExtenderImpl כמצייני מקום בדוגמה הבאה. החלף את אלה בשמות הקבצים שאתה מיישם בפועל.

הערה: מחלקות Extender אלה עשויות להתבצע מספר פעמים לפי הצורך בתוך Camera2/X.

ל-Basic Extender יש את היכולות הבאות:

• הזרקת פרמטרי הפעלה בעת הגדרת CameraCaptureSession ( onPresetSession ).
• הודע לך על אירועי ההתחלה והסגירה של הפעלת הלכידה ושלח בקשה בודדת להודיע ​​ל-HAL עם הפרמטרים המוחזרים ( onEnableSession , onDisableSession ).
• הזרקת פרמטרי לכידה עבור הבקשה ( PreviewExtenderImpl.getCaptureStage , ImageCaptureExtenderImpl.getCaptureStages ).
• הוסף מעבדים לתצוגה מקדימה ועדיין לכידה שמסוגלת לעבד זרם YUV_420_888 .

הערה: עליך ליישם גם תצוגה מקדימה וגם לכידה עבור ההרחבות שברצונך להפעיל. לדוגמה, אם ברצונך להפעיל את התוסף Night, עליך ליישם גם NightPreviewExtenderImpl.java וגם NightCaptureExtenderImpl.java .

בואו נראה כיצד Camera2/X מפעיל את extensions-interface כדי להשיג את שלושת זרימות האפליקציה שהוזכרו לעיל.

הערה: Camera2/X מאתחל תמיד את ספריית הספק ( InitializerImpl.init() ) לפני תחילת כל אחת מזרימות האפליקציות הללו.

זרימת אפליקציה 1: בדוק את זמינות התוספים

איור 3. זרימת אפליקציה 1 ב-Basic Extender

בזרימה זו, Camera2/X קורא ישירות לשיטת isExtensionAvailable() של PreviewExtenderImpl ושל ImageCaptureExtenderImpl מבלי לקרוא ל- init() . שתי מחלקות ה-Extender חייבות להחזיר 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() . יתר על כן, בקשת לכידת ה-still מכילה את הפרמטרים המוחזרים על ידי ImageCaptureExtenderImpl.getCaptureStages() .

לבסוף, Camera2/X מפעיל את onDeInit() לאחר סיום הפעלת המצלמה. אתה יכול לשחרר משאבים ב- onDeinit() .

הערה: למצלמה2/X יכולות להיות מספר הפעלות מצלמה פתוחות ונסגרות בין onInit() ל- 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 שולח שלוש בקשות לכידה עם פרמטרי לכידה מתאימים באמצעות ה-API captureBurst .

   הערה: getCaptureStages() רשאית להחזיר יותר ממופע CaptureStageImpl אחד רק כאשר getCaptureProcessor() מחזיר מופע.

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#JPEG_QUALITY ו- CaptureRequest#JPEG_ORIENTATION נתמכים תמיד ללא קשר לשאלה אם הם נוספו לרשימה.

עבור פעולות מצלמה נפוצות כמו זום, הקשה לפוקוס, פלאש ופיצוי חשיפה, אנו ממליצים לתמוך במקשים הבאים הן עבור בקשת צילום והן עבור תוצאת צילום:

• תקריב:
  • 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

עבור מרחיבים בסיסיים שמטמיעים 1.2.0 או גרסאות קודמות, ה-API של CameraX Extensions תומך במפורש בכל המפתחות שלעיל. עבור extensions-interface 1.3.0, גם CameraX וגם Camera2 מכבדות את הרשימה המוחזרת ותומכות רק במפתחות הכלולים בה. לדוגמה, אם תחליט להחזיר רק CaptureRequest#CONTROL_ZOOM_RATIO ו- CaptureRequest#SCALER_CROP_REGION ביישום 1.3.0, אז זה אומר שרק זום נתמך עבור האפליקציה בעוד שהקשה להתמקד, הבזק ופיצוי חשיפה אינם מותרים.

הערה: הרחבות Camera2 תומכות בהגדרת פרמטרים JPEG_QUALITY ו- JPEG_ORIENTATION בלבד באנדרואיד 12 וב-Android 12L. החל מ-Android 13, ה-API של Camera2 Extensions תומך בפרמטרים אחרים כגון זום או פלאש כל עוד המפתחות הללו מוחזרים על ידי ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys בספריית ספקי ה-OEM שלך המיישמת extensions-interface 1.3.0 ומעלה.

מאריך מתקדם

Advanced Extender הוא סוג של הטמעת ספק המבוססת על Camera2 API. סוג Extender זה התווסף extensions-interface 1.2.0. בהתאם ליצרן המכשיר, הרחבות עשויות להיות מיושמות בשכבת האפליקציה, אשר תלויה בגורמים הבאים:

• תצורת סטרימינג מותאם אישית: הגדר זרמים מותאמים אישית כמו זרם RAW או בעל מספר זרמים עבור מזהי מצלמה פיזיים שונים.

• יכולת לשלוח בקשות Camera2: תמכו בלוגיקת אינטראקציה מסובכת שיכולה לשלוח בקשות לכידה עם פרמטרים המבוססים על התוצאות של בקשות קודמות.

Advanced Extender מספק מעטפת, או שכבת ביניים, כך שתוכל להתאים אישית את תצורת הזרם ולשלוח בקשות לכידה לפי דרישה.

הערה: ה-API של Camera2 Extensions תומך ב-Advanced Extender מאז Android 12L. עבור CameraX Extensions API, Advanced Extender נתמך מאז CameraX 1.2.0-alpha03.

קבצים ליישום

כדי לעבור למימוש Advanced Extender, השיטה isAdvancedExtenderImplemented() ב- ExtensionVersionImpl חייבת להחזיר true . עבור כל סוג הרחבה, יצרני OEM חייבים ליישם את מחלקות ה-Extender המתאימות. קבצי היישום Advanced Extender נמצאים בחבילה המתקדמת .

	מרחיבים שיעורים ליישום
לַיְלָה	advanced/NightAdvancedExtenderImpl.java
HDR	advanced/HdrAdvancedExtenderImpl.java
אוטומטי	advanced/AutoAdvancedExtenderImpl.java
בוקה	advanced/BokehAdvancedExtenderImpl.java
ריטוש פנים	advanced/BeautyAdvancedExtenderImpl.java

אנו משתמשים AdvancedExtenderImpl כמציין מיקום בדוגמה הבאה. החלף אותו בשם של קובץ ה-Extender עבור ההרחבה שאתה מיישם.

בוא נראה כיצד Camera2/X מפעיל את extensions-interface כדי להשיג את שלושת זרימות האפליקציה.

הערה: Camera2/X מאתחל תמיד את ספריית הספק ( InitializerImpl.init() ) לפני תחילת כל אחת מזרימות האפליקציות הללו.

זרימת אפליקציה 1: בדוק את זמינות התוספים

איור 8. זרימת אפליקציה 1 ב-Advanced Extender

ראשית, האפליקציה בודקת אם התוסף הנתון נתמך.

הערה: האפליקציה לא צריכה לקרוא AdvancedExtenderImpl.init() לפני שתקרא isExtensionAvailable() .

זרימת אפליקציה 2: שאילתת מידע

איור 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: תצוגה מקדימה/צילום עדיין עם הרחבה מופעלת

איור 10. זרימת אפליקציה 3 ב-Advanced Extender

הדיאגרמה שלמעלה מציגה את הזרימה העיקרית להתחלת תצוגה מקדימה ועדיין לכידה עבור סוג Advanced Extender. בואו נעבור על כל שלב.

1. מופע SessionProcessorImpl

   יישום הליבה Advanced Extender נמצא ב- SessionProcessorImpl , אשר אחראי על אספקת תצורת הפעלה מותאמת אישית ושליחת בקשות לכידה כדי להתחיל את בקשת התצוגה המקדימה ועדיין הלכידה. AdvancedExtenderImpl.createSessionProcessor() מופעל כדי להחזיר את המופע SessionProcessorImpl .

   הערה: הפעלת מצלמה יכולה להשתמש במופע SessionProcessorImpl מספר פעמים. כתוצאה מכך, היישום חייב להיות מסוגל לתמוך במספר initSession() ו- deInitSession() עבור מופע אחד 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/X יוצרת ומנהלת עבורך את מופעי ImageReader . אתה יכול להגדיר מופע ImageProcessorImpl כדי לאחזר את התמונה.
   • השתמש בשיתוף משטח של Camera2: השתמש בשיתוף משטח עם משטח אחר על ידי הוספת כל מופע Camera2OutputConfigImpl לשיטת getSurfaceSharingOutputConfigs() של מופע Camera2OutputConfigImpl אחר. פורמט וגודל פני השטח חייבים להיות זהים.

   כל Camera2OutputConfigImpl כולל SurfaceOutputConfigImpl ו- ImageReaderOutputConfigImpl חייב להיות בעל מזהה ייחודי ( getId() ), המשמש לציון משטח היעד ולאחזור התמונה מ- ImageReaderOutputConfigImpl .

3. onCaptureSessionStart ו- RequestProcessorImpl

   כאשר CameraCaptureSession מתחיל והמסגרת של Camera מפעילה את 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. התחל את התצוגה המקדימה וצלם תמונה

   ביישום 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 .

עבור Advanced Extender, Camera2/X מעביר שלושה משטחי פלט לקריאה SessionProcessorImpl.initSession() . משטחי פלט אלה מיועדים לתצוגה מקדימה, לכידת סטילס וניתוח תמונה, בהתאמה. עליך לוודא שמשטחי פלט של תצוגה מקדימה ועדיין לכידת מציגים את הפלט החוקי. עם זאת, עבור משטח הפלט של ניתוח התמונה, ודא שהוא פועל רק כאשר הוא אינו ריק. אם היישום שלך אינו יכול לתמוך בזרם ניתוח התמונות, תוכל להחזיר רשימה ריקה ב- AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() . זה מבטיח שמשטח הפלט של ניתוח התמונה יהיה תמיד null ב- SessionProcessorImpl.initSession() .

הערה: אינך נדרש להחיל את ההרחבה בזרם ניתוח התמונות. יתר על כן, ה-API של Camera2 Extensions מאפשר רק להגדיר שני משטחים: תצוגה מקדימה ולכידת סטילס.

תומך בצילום וידאו

ארכיטקטורת הרחבת המצלמה הנוכחית תומכת רק בתצוגה מקדימה ועדיין ללכוד מקרי שימוש. אנו לא תומכים בהפעלת התוסף על משטחי MediaCodec או MediaRecorder לצורך הקלטת הווידאו. עם זאת, אפליקציות יכולות להקליט את פלט התצוגה המקדימה.

תמיכה במשטחי MediaCodec ו- MediaRecorder נמצאת בבדיקה.

מטא נתונים ספציפיים לתוסף

עבור אנדרואיד 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 .

אומדן זמן השהיה של צילום עדיין בזמן אמת

עבור אנדרואיד 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

לכידת עיבוד התקדמות התקשרויות

עבור אנדרואיד 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()

Postview עדיין לכידת

עבור אנדרואיד 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();
…
}

כדי לתמוך בלכידת Postview Still, הטמעת הספק שלך חייבת ליישם את הדברים הבאים:

• הרחבות בסיסיות: CaptureProcessorImpl.onPostviewOutputSurface ו- CaptureProcessorImpl.processWithPostview

• הרחבות מתקדמות: SessionProcessorImpl.startCaptureWithPostview

תמיכה בפלט SurfaceView

עבור אנדרואיד 14 ומעלה, לקוחות הרחבות מצלמה יכולים להשתמש בנתיבי עיבוד תצוגה מקדימה מותאמים לעוצמה וביצועים על ידי רישום מופע SurfaceView לפלט תצוגה מקדימה עבור בקשות חוזרות.

כדי לתמוך בפלט SurfaceView , הטמעת תוסף הספק שלך חייבת להיות מסוגלת להזרים ולהוציא תצוגה מקדימה למופעי SurfaceView . כדי לוודא שזה נתמך, הפעל את מודול SurfaceViewExtensionPreviewTest.java CTS.

סוגים ספציפיים של מפגשים לספקים

התכונה מאפשרת למימושים של הרחבות ספקים לבחור סוג הפעלה ספציפי לספק שיוגדר בסשן לכידת המצלמה הפנימית במקום ערך ברירת המחדל.

התכונה פועלת כולה בתוך המסגרת והמחסנית של הספק ואין לה השפעה גלויה על ה-API של הלקוח/הציבור.

כדי לבחור סוג הפעלה ספציפי לספק, יישם את הדברים הבאים עבור ספריות ההרחבות שלך: * ExtenderStateListener.onSessionType() עבור הרחבות בסיסיות * Camera2SessionConfigImpl.getSessionType() עבור הרחבות מתקדמות

היסטוריית גרסאות של ממשק הרחבות

הטבלה הבאה מציגה את היסטוריית הגרסאות של ממשק הרחבת המצלמה. אתה תמיד צריך ליישם את ספריית הספק עם הגרסה העדכנית ביותר.

גִרְסָה	תכונות שנוספו
1.0.0	אימות גרסה ExtensionVersionImpl מאריך בסיסי PreviewExtenderImpl ImageCaptureExtenderImpl Processor PreviewImageProcessorImpl CaptureProcessorImpl RequestUpdateProcessorImpl
1.1.0	אתחול הספרייה InitializerImpl חשוף רזולוציות נתמכות PreviewExtenderImpl.getSupportedResolutions ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0	AdvancedExtender AdvancedExtenderImpl SessionProcessorImpl קבל זמן אחזור משוער לצילום ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0	חשוף את מפתחות בקשת הלכידה/מפתחות התוצאות הנתמכים ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys ו- getAvailableCaptureResultKeys AdvancedExtenderImpl.getAvailableCaptureRequestKeys ו- getAvailableCaptureResultKeys קריאת process() חדשה שלוקחת את ProcessResultImpl ב- PreviewImageProcessorImpl וב- CaptureProcessorImpl תמיכה בבקשת סוג טריגר AdvancedExtenderImpl.startTrigger
1.4.0	מטא נתונים ספציפיים לתוסף אומדני זמן אחזור ללכוד עדיין דינמי לכידת עיבוד התקדמות התקשרויות Postview עדיין לכידת תמיכה בפלט SurfaceView סוגים ספציפיים של מפגשים לספקים

יישום התייחסות

ההטמעות הבאות של ספריית ספקי OEM זמינות frameworks/ex .

• advancedSample : יישום בסיסי של Advanced Extender.

• sample : יישום בסיסי של Basic Extender.

• service_based_sample : יישום המדגים כיצד לארח הרחבות מצלמה Service . יישום זה מכיל את הרכיבים הבאים:

  • oem_library : ספריית OEM של הרחבות מצלמה עבור ממשקי API של הרחבות Camera2 ו-CameraX המיישמת Extensions-Interface . זה פועל כמעבר המעביר שיחות מ- Extensions-Interface לשירות. ספרייה זו מספקת גם קבצי AIDL ושיעורי עטיפה כדי לתקשר עם השירות.

    Advanced Extender מופעל כברירת מחדל. כדי להפעיל את ה-Basic Extender, שנה את ExtensionsVersionImpl#isAdvancedExtenderImplemented כדי להחזיר 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 , היא תלות של 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 , המאפשר לשאול אם מכשיר תומך בהרחבות. לשם כך, הוסף את השורה הבאה בקובץ ה-make של המכשיר:

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

מַתַן תוֹקֵף

כדי לבדוק את היישום שלך של ספריית ספקי ה-OEM במהלך שלב הפיתוח, השתמש באפליקציה לדוגמה ב- androidx-main/camera/integration-tests/extensionstestapp/ , הפועלת דרך הרחבות ספקים שונות.

לאחר השלמת היישום, השתמש בכלי אימות תוספי המצלמה כדי להפעיל בדיקות אוטומטיות וידניות כדי לוודא שספריית הספק מיושמת כהלכה.

מצב סצנה מורחב לעומת הרחבות מצלמה

עבור תוסף הבוקה, בנוסף לחשיפתו באמצעות הרחבות מצלמה, ניתן לחשוף את התוסף באמצעות מצב הסצנה המורחב, המופעל באמצעות מקש CONTROL_EXTENDED_SCENE_MODE . לפרטי יישום נוספים, ראה מצלמה בוקה .

למצב סצנה מורחב יש פחות הגבלות בהשוואה להרחבות מצלמה עבור אפליקציות camera2. לדוגמה, אתה יכול להפעיל מצב סצנה מורחב במופע CameraCaptureSession רגיל התומך בשילובי זרם גמישים ופרמטרים של בקשת לכידה. לעומת זאת, הרחבות מצלמה תומכות רק בקבוצה קבועה של סוגי זרמים ויש להם תמיכה מוגבלת בפרמטרים של בקשת לכידה.

החיסרון של מצב סצנה מורחב הוא שאתה יכול ליישם אותו רק ב-HAL של המצלמה, מה שאומר שהוא חייב להיות מאומת כך שיעבוד בכל הפקדים האורתוגונליים הזמינים למפתחי אפליקציות.

אנו ממליצים לחשוף בוקה גם באמצעות מצב הסצנה המורחב וגם באמצעות הרחבות מצלמה מכיוון שאפליקציות עשויות להעדיף להשתמש בממשק API מסוים כדי לאפשר בוקה. אנו ממליצים תחילה להשתמש במצב הסצנה המורחב מכיוון שזו הדרך הגמישה ביותר עבור אפליקציות לאפשר את סיומת הבוקה. לאחר מכן תוכל ליישם את ממשק הרחבות המצלמה בהתבסס על מצב הסצנה המורחב. אם הטמעת בוקה במצלמה HAL קשה, למשל, מכיוון שהיא דורשת מעבד פוסט הפועל בשכבת האפליקציה כדי לעבד תמונות, אנו ממליצים ליישם את תוסף הבוקה באמצעות ממשק הרחבות למצלמה.

שאלות נפוצות (שאלות נפוצות)

האם יש הגבלות על רמות API?

כן. זה תלוי בערכת תכונות ה-API של Android שנדרשת על ידי יישום ספריית ה-OEM. לדוגמה, ExtenderStateListener.onPresetSession() משתמש בקריאה SessionConfiguration.setSessionParameters() כדי להגדיר קבוצת תגים בסיסית. קריאה זו זמינה רק ברמת API 28 ומעלה. לפרטים על שיטות ממשק ספציפיות, עיין בתיעוד ההפניה ל-API .