תוספים למצלמה

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

לרשימה של תוספים נתמכים, שזהים בכל המצלמה2 ו- CameraX, API של CameraX. אם רוצים להוסיף תוסף, לדווח על באג מעקב אחר בעיות

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

ארכיטקטורה

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

איור 1. תרשים הארכיטקטורה של תוספי המצלמה

כפי שמוצג בתרשים, כדי לתמוך בתוספי המצלמה, צריך להטמיע את extensions-interface שסופקה על ידי ספריית הספקים של ה-OEM. שלך ספריית הספקים של ה-OEM מאפשרת שני ממשקי API: CameraX extensions API וגם API לתוספים של Camera2, שמשמשות את אפליקציות 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

מחלקות הרחבה של Bokeh (יש להטמיע אותו אם יש תמיכה בתוסף Bokeh)

• BokehImageCaptureExtenderImpl.java
• BokehPreviewExtenderImpl.java
• advanced/BokehAdvancedExtenderImpl.java

סיווגי מאריך לילה (יש להטמיע אותו אם יש תמיכה בתוסף Night)

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

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

איור 2. הטמעת תוסף לילה

1. אימות הגרסה:

   Camera2/X מתקשר אל ExtensionVersionImpl.checkApiVersion() כדי לוודא הגרסה extensions-interface שהוטמעה על ידי ה-OEM (יצרן הציוד המקורי) תואמת ל- Camera2/X והגרסאות הנתמכות.

2. אתחול ספריית הספקים:

   ב-InitializerImpl יש שיטה init() שמאתחלת את ספריית הספקים. Camera2/X מסיים את האתחול לפני גישה למחלקות Extender.

3. סיווגי הרחבה מיידית של אפליקציות:

   יצירת אובייקטים של מחלקות המורחבות של התוסף. יש שני הרחבות סוגים: Basic Extender ו-Advanced Extender. עליך ליישם סוג ההרחבה לכל התוספים. מידע נוסף זמין במאמר הבא: Basic Extender לעומת Advanced Extender.

   Camera2/X יוצר ויוצר אינטראקציה עם מחלקות ה-Extender כדי לאחזר מידע ולהפעיל את התוסף. עבור תוסף נתון, Camera2/X יכול ליצור מופע של מחלקות הרחבה מספר פעמים. לכן, אסור אתחול בסגנון גבוה ב-constructor או בקריאה init(). מבצעים את הפעולות הבאות: עבודה כבדה רק כשסשן המצלמה עומד הפעלה, למשל כשקוראים לפונקציה onInit() ב-Basic Extender או הפונקציה initSession() נקראת ב-Advanced Extender.

   עבור התוסף Night, מחלקות ה-Extender הבאות נוצרות עבור סוג ההגדלה הבסיסית:

   • NightImageCaptureExtenderImpl.java
   • NightPreviewExtenderImpl.java

   ובסוג Advanced Extender:

   • NightAdvancedExtenderImpl.java

4. בדיקת הזמינות של התוסף:

   לפני הפעלת התוסף, isExtensionAvailable() בודק אם התוסף זמין במזהה המצלמה שצוין דרך Extender מכונה.

5. הפעלת ה-Extender באמצעות פרטי המצלמה:

   Camera2/X מתקשר ל-init() במופע של Extender ומעביר את המצלמה אליו המזהה ו-CameraCharacteristics.

6. פרטי השאילתה:

   הפעלת המחלקה Extender כדי לאחזר מידע כמו נתמך של פתרונות, עדיין לתעד את זמן האחזור המשוער, ולתעד מפתחות של בקשות הרחבה כהכנה להפעלת התוסף.

7. מפעילים את התוסף ב-Extender:

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

   עם Advanced Extender, Camera2/X מקיים אינטראקציה עם SessionProcessorImpl כדי להפעיל את התוסף. Camera2/X מאחזרת את למופע של SessionProcessorImpl בקריאה ל-createSessionProcessor() הרחבה.

בקטעים הבאים מתואר תהליך התוסף בפירוט רב יותר.

אימות גרסה

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

תאימות לגרסאות ראשיות

אם הגרסאות הראשיות של ממשק התוספים שונות בין מצלמה2/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 מפעילה את תהליך האתחול. האותות של ה-method InitializerImpl.init() לספריית ה-OEM (יצרן הציוד המקורי) שאפליקציה מסוימת מנסה כדי להשתמש בתוספים.

לא מתבצעות קריאות אחרות לספריית ה-OEM (מלבד בדיקת גרסאות) על ידי Camera2/X עד שספריית הספקים של ה-OEM (יצרן הציוד המקורי) תקרא OnExtensionsInitializedCallback.onSuccess() כדי להודיע על השלמת האתחול.

עליך ליישם InitializerImpl החל מ-extensions-interface 1.1.0. Camera2/X מדלג על אתחול הספרייה אם ספריית הספקים של ה-OEM מוטמעת בגרסה 1.0.0 של extensions-interface.

הרחבה בסיסית לעומת הרחבה מתקדמת

יש שני סוגים של הטמעה של extensions-interface: Basic Extender ו מגדיל טווח מתקדם. התוסף המתקדם נתמך מאז extensions-interface 1.2.0

להטמיע הרחבה בסיסית לתוספים שמעבדים תמונות במצלמת HAL או משתמשים במעבד פוסט שמסוגל לעבד זרמי YUV.

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

לצורך ההשוואה, עיינו בטבלה הבאה:

תהליכי אפליקציה

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

הרחבה בסיסית

ממשק Extender בסיסי מספק קטעי הוק (hooks) לכמה מקומות במצלמה צינור עיבוד נתונים. לכל סוג תוסף יש סיווגי תוספים תואמים שדרושים ליצרני ציוד מקורי (OEM) ליישם.

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

אנחנו משתמשים ב-PreviewExtenderImpl וב-ImageCaptureExtenderImpl כ-placeholder בדוגמה הבאה. צריך להחליף אותם בשמות של שאתם מטמיעים.

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

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

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

תהליך ראשון של אפליקציה: בדיקת זמינות של תוסף

איור 3. תהליך 1 של האפליקציה בהרחבה בסיסית

בתהליך הזה, Camera2/X קורא ישירות ל-method של isExtensionAvailable() של גם PreviewExtenderImpl וגם ImageCaptureExtenderImpl בלי להתקשר init() כדי להפעיל את התוספים, שתי המחלקות של התוספים צריכות להחזיר true.

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

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

איור 4. תהליך 2 של אפליקציה בהרחבה בסיסית

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

• טווח זמן אחזור לתיעוד נתונים: הפונקציה ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange מחזירה את הטווח של את זמן האחזור ללכידה כדי שהאפליקציה תעריך אם כדאי להפעיל את התוסף בתרחיש הנוכחי.

• גדלים נתמכים של התצוגה המקדימה ופלטפורמת הצילום: ImageCaptureExtenderImpl.getSupportedResolutions והקבוצה PreviewExtenderImpl.getSupportedResolutions מחזיר רשימה של פורמטים של תמונות הגדלים הנתמכים עבור הפורמט והגודל של פני השטח.

• מפתחות נתמכים של בקשות ותוצאות: Camera2/X מפעיל את השיטות הבאות כדי לאחזר את הצילום הנתמך מפתחות של בקשות ומפתחות תוצאות מההטמעה שלך:

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
  • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X תמיד מבצע קריאה ל-init() במחלקות המורחבות האלה לפני שליחת שאילתות אפשר לקבל מידע נוסף.

תהליך 3 של האפליקציה: תצוגה מקדימה/צילום סטילס עם תוסף מופעל (הטמעת HAL)

איור 5. תהליך 3 של האפליקציה בהרחבה בסיסית

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

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

כשמגדירים את CameraCaptureSession, אפליקציית Camera2/X מופעלת onPresetSession כדי לקבל את הפרמטרים של הסשן. לאחר סשן הצילום הוגדר בהצלחה, Camera2/X מפעיל את onEnableSession מחזיר CaptureStageImpl שמכיל את הפרמטרים להקלטה. מצלמה2/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. המעבד (CPU) אחראי לעיבוד תמונות קלט של 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 במקרה הצורך.

התמיכה והמפתחות של הבקשות לתיעוד נתונים

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

השיטות הבאות נוספו לגרסה 1.3.0 של extensions-interface כדי לאפשר כדי לחשוף את הפרמטרים שבהם ההטמעה תומכת:

• הפונקציה ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() תחזיר את הערך לתעד מפתחות בקשות שנתמכים על ידי ההטמעה.
• הפונקציה ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() תחזיר את הערך לתעד מפתחות של התוצאות שנכללים בתוצאת הצילום.

אם המצלמה עם HAL מעבדת את התוסף, Camera2/X מאחזרת את הצילום התוצאה תהיה CameraCaptureSession.CaptureCallback. אבל אם המעבד מוטמע, Camera2/X מאחזרת את תוצאות הצילום ProcessResultImpl , שמועבר אל process() method ב- PreviewImageProcessorImpl וגם CaptureProcessorImpl. באחריותך לדווח תוצאת הצילום באמצעות ProcessResultImpl עד Camera2/X.

אפשר לראות דוגמה להגדרה של הממשק ב-CaptureProcessorImpl. בגרסה 1.3.0 ואילך של extensions-interface, מופעלת הקריאה השנייה של 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

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

מגדיל טווח מתקדם

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

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

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

Advanced Extender מספק wrapper או שכבת ביניים, כדי שתוכלו להתאים אישית את ההגדרה של השידור ולשלוח בקשות תיעוד לפי דרישה.

קבצים להטמעה

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

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

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

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

איור 8. תהליך ראשון של אפליקציה ב-Advanced Extender

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

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

איור 9. תהליך 2 של אפליקציה ב-Advanced Extender

לאחר הקריאה אל AdvancedExtenderImpl.init(), האפליקציה יכולה לשלוח שאילתה בהמשך למידע על AdvancedExtenderImpl:

• זמן אחזור משוער של צילום עדיין: הפונקציה AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() מחזירה את הטווח של זמן האחזור של תיעוד האפליקציה כדי להעריך אם הוא מתאים להפעיל את התוסף בתרחיש הנוכחי.

• רזולוציות נתמכות לתצוגה מקדימה ולצילום תמונות סטילס:

  • AdvancedExtenderImpl.getSupportedPreviewOutputResolutions() מחזיר מפה של פורמט התמונה לרשימת הגדלים הנתמכים עבור פורמט של פלטפורמת התצוגה המקדימה. ועד גודל. יצרני ציוד מקורי חייבים לתמוך לפחות בפורמט PRIVATE.

  • הפונקציה AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() תחזיר את הערך פורמטים וגדלים נתמכים בשביל משטח צילום עדיין. יצרני ציוד מקורי חייבים לתמוך בשני הפלט של הפורמט 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).

2. initSession

   SessionProcessorImpl.initSession() מאתחל את הסשן של התוסף. כאן מקצים משאבים ומחזירים הגדרות של סשן CameraCaptureSession בהכנה.

   לפרמטרים של הקלט, Camera2/X מציין את ההגדרות של משטח הפלט לתצוגה מקדימה, צילום סטילס וניתוח אופציונלי של תמונות YUV. הפלט הזה הגדרת פני השטח (OutputSurfaceImpl) מכילה את פני השטח, הגודל והתמונה שמאוחזרות באמצעות השיטות הבאות ב-AdvancedExtenderImpl:

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

   עליך להחזיר מופע Camera2SessionConfigImpl, שכולל רשימה של Camera2OutputConfigImpl מופעים והפרמטרים של הסשנים שבהם נעשה שימוש להגדרה של CameraCaptureSession. אתם אחראים: פלט של תמונות המצלמה הנכונות לפלטפורמות הפלט שמועברות על ידי מצלמה2/X. יש כמה אפשרויות להפעלת הפלט:

   • עיבוד ב-HAL במצלמה: אפשר להוסיף ישירות את פלטפורמות הפלט אל 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 wrapper RequestProcessImpl. Camera2/X מוטמע RequestProcessImpl, שמאפשר לבצע את בקשות ההקלטה, לאחזר תמונות אם נעשה שימוש ב-ImageReaderOutputConfigImpl.

   ממשקי ה-API של RequestProcessImpl דומים ל-מצלמה2 ממשקי API של 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() נתמך החל מגרסה 1.3.0 של extensions-interface. הוא שמאפשר לאפליקציות להטמיע אפשרות 'הקשה למיקוד' ו-Flash באמצעות תוספים.

6. פינוי מקום

   בסיום סשן צילום, הפעלת SessionProcessorImpl.onCaptureSessionEnd() לפני הסגירה CameraCaptureSession. אחרי שסשן הצילום נסגר, הניקוי יתבצע על ידי deInitSession().

תמיכה בתצוגה מקדימה, בצילום סטילס ובניתוח תמונות

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

בסוג התוסף הבסיסי (Basic Extender), ללא קשר להפעלת התוסף לתצוגה מקדימה, עליך להטמיע גם את ImageCaptureExtenderImpl וגם את PreviewExtenderImpl לתוסף נתון. לעיתים קרובות, אפליקציה משתמשת גם במקור YUV כדי לנתח תוכן של תמונות, כמו מציאת קודי QR או טקסט. כדי לספק תמיכה טובה יותר בתרחיש לדוגמה הזה , עליך לתמוך בשילוב של סטרימינג של תצוגה מקדימה, צילום סטילס ו מקור נתונים YUV_420_888 להגדרה של CameraCaptureSession. כלומר שאם תטמיעו מעבד, צריך לתמוך בזרם שילוב של שלושה שידורים של YUV_420_888.

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

כדי לתמוך בהערכות לזמן אחזור בזמן אמת, צריך להטמיע הבאים:

• תוספים בסיסיים: ImageCaptureExtenderImpl.getRealtimeCaptureLatency()
• תוספים מתקדמים: SessionProcessorImpl.getRealtimeCaptureLatency

קריאות חוזרות (callback) בהתקדמות עיבוד הצילום

ב-Android מגרסה 14 ואילך: לקוחות של תוספי מצלמה יכול לקבל קריאות חוזרות (callback) לגבי ההתקדמות של עיבוד תיעוד ממושך שעדיין לא הסתיים. ב-AI. אפליקציות יכולות להציג את ההתקדמות הנוכחית למשתמשים כדי לשפר את באופן כללי.

אפליקציות יכולות להשתמש בקוד הבא כדי לשלב את התכונה הזו:

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

כדי לתמוך בקריאות חוזרות (callback) בהתקדמות עיבוד הצילום, ספק התוסף חייבים לקרוא לקריאות החוזרות (callback) הבאות עם ההתקדמות הנוכחית ערך:

• תוספים בסיסיים: ProcessResultImpl.onCaptureProcessProgressed()
• תוספים מתקדמים: CaptureCallback.onCaptureProcessProgressed()

עדיין צילום לאחר הצפייה

ב-Android מגרסה 14 ואילך, תוספי מצלמה לספק תצוגה מקדימה (תמונת תצוגה מקדימה) באמצעות setPostviewOutputConfiguration כדי לשפר את חוויית המשתמש, אפליקציות יכולות להציג תמונה לאחר צפייה (postview) בתור placeholder כשזמן האחזור של תוסף ארוך, ומחליפים את התמונה כשהתמונה הסופית זמינה. האפליקציות יכולות להגדיר ולשלוח בקשות לתיעוד לאחר צפייה (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) עדיין, על ההטמעה של הספק להטמיע את הבאים:

• תוספים בסיסיים: CaptureProcessorImpl.onPostviewOutputSurface וגם CaptureProcessorImpl.processWithPostview

• תוספים מתקדמים: SessionProcessorImpl.startCaptureWithPostview

פלט SurfaceView של תמיכה

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

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

סוגי הסשנים הספציפיים לספקים

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

התכונה פועלת בצורה מלאה במסגרת סטאק הספקים ו-framework, ואין לה השפעה גלויה על הלקוח או על ה-API לציבור.

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

היסטוריית הגרסאות של ממשק התוספים

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

הטמעת קובצי עזר

ההטמעות הבאות של ספריות ספקים של OEM (יצרן ציוד מקורי) זמינות ב- frameworks/ex

• advancedSample: הטמעה בסיסית של Advanced Extender.

• sample: הטמעה בסיסית של Basic Extender.

• service_based_sample: הטמעה שמדגימה איך לארח תוספי מצלמה ב- Service. ההטמעה הזאת כוללת את הרכיבים הבאים:

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

    התכונה 'הרחבה מתקדמת' מופעלת כברירת מחדל. כדי להפעיל את 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, ה-framework טוענת שירות תוספים מצהיר גם שה-<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/ שפועלת באמצעות תוספות ספקים שונות.

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

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

בתוסף ה-Bokeh, בנוסף לחשיפתו באמצעות תוספות למצלמה, אפשר לחשוף את התוסף באמצעות מצב סצנה מורחבת, שמופעל דרך ה CONTROL_EXTENDED_SCENE_MODE מקש. למידע נוסף על הטמעה, אפשר לקרוא את המאמר בוקה ב-מצלמה.

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

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

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

שאלות נפוצות

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

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