הפניה ל-Struct של camera3_capture_result

שדות נתונים
הפניה ל-Struct של camera3_capture_result

#include < camera3.h >

שדות נתונים

uint32_t  frame_number
 
const camera_metadata_t *  result
 
uint32_t  num_output_buffers
 
const camera3_stream_buffer_t *  output_buffers
 
const camera3_stream_buffer_t *  input_buffer
 
uint32_t  partial_result
 

תיאור מפורט

camera3_capture_result_t:

התוצאה של צילום יחיד/עיבוד מחדש יחיד על ידי מכשיר ה-HAL של המצלמה. התוצאה נשלחת למסגרת באופן אסינכררוני באמצעות process_capture_result(), בתגובה לבקשת צילום אחת שנשלחת ל-HAL באמצעות process_capture_request(). ה-HAL עשוי לבצע מספר קריאות ל-process_capture_result() לכל בקשה.

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

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

>= CAMERA_DEVICE_API_VERSION_3_2:

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

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

שיקולי ביצועים:

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

דוגמה אופיינית לשימוש היא חישוב מצב המיקוד האוטומטי באמצע צינור עיבוד הנתונים. שליחת המצב חזרה למסגרת באופן מיידי מאפשרת לנו לשפר את הביצועים ב-50% ולשפר את הרספונסיביות של המיקוד האוטומטי.

ההגדרה מופיעה בשורה 2251 בקובץ camera3.h .

מסמכי תיעוד של שדה

uint32_t frame_number

מספר המסגרת הוא מספר שלם שמוסיף את עצמו ומוגדר על ידי המסגרת בבקשה שנשלחת כדי לזהות באופן ייחודי את הצילום הזה. הוא משמש גם לזיהוי הבקשה בהתראות אסינכררוניות שנשלחות אל camera3_callback_ops_t.notify()‎ .

ההגדרה מופיעה בשורה 2258 בקובץ camera3.h .

const camera3_stream_buffer_t * input_buffer

>= CAMERA_DEVICE_API_VERSION_3_2:

הידית של מאגר הנתונים של מקור הקלט לצילום הזה. יכול להיות שהוא עדיין לא נוצל בזמן ש-HAL קורא ל-process_capture_result();‏. המסגרת תחכה למחסומי הסנכרון של השחרור ש-HAL מספק לפני שימוש חוזר במאגר.

ה-HAL צריך לטפל במחסומי הסנכרון באותו אופן שבו הוא מטפל ב-output_buffers.

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

שיקולי ביצועים:

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

ההגדרה מופיעה בשורה 2361 בקובץ camera3.h .

uint32_t num_output_buffers

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

ההגדרה מופיעה בשורה 2296 בקובץ camera3.h .

const camera3_stream_buffer_t * output_buffers

הלחצנים של מאגרי הנתונים של שידור הפלט לצילום הזה. יכול להיות שהם עדיין לא יאוכלסו בזמן שה-HAL קורא ל-process_capture_result();‏. המסגרת תחכה למחסומי הסנכרון של השחרור שסופקו על ידי ה-HAL לפני קריאת המאגרים.

ה-HAL חייב להגדיר את הגדרת הסנכרון של שחרור מאגר הנתונים של הסטרימינג ל-fd סנכרון תקין, או ל--1 אם המאגר כבר מלא.

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

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

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

>= CAMERA_DEVICE_API_VERSION_3_2:

יכול להיות שמאגרי Gralloc של פריים מסוים יישלחו למסגרת לפני ההודעה המתאימה של SHUTTER-notify.

שיקולי ביצועים:

מאגרים שנשלחים למסגרת לא יישלחו לשכבת האפליקציה עד שיתקבל חותמת זמן של תחילת החשיפה באמצעות קריאה של notify()‏ SHUTTER. מומלץ מאוד לשלוח את הקריאה הזו בהקדם האפשרי.

ההגדרה מופיעה בשורה 2335 בקובץ camera3.h .

uint32_t partial_result

>= CAMERA_DEVICE_API_VERSION_3_2:

כדי לנצל את התוצאות החלקיות, ה-HAL צריך להגדיר את המטא-נתונים הסטטיים android.request.partialResultCount למספר התוצאות החלקיות שיישלח לכל פריים.

בכל תוצאת צילום חדשה עם תוצאה חלקית, צריך להגדיר את השדה הזה (partial_result) לערך ייחודי שכולל את הערכים בין 1 ל-android.request.partialResultCount.

ב-HALs שלא רוצים להשתמש בתכונה הזו, אסור להגדיר את android.request.partialResultCount או את partial_result לערך שאינו 1.

צריך להגדיר את הערך הזה ל-0 כשתוצאת הצילום מכילה מאגרים בלבד ולא מטא-נתונים.

ההגדרה מופיעה בשורה 2381 בקובץ camera3.h .

const camera_metadata_t * result

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

רק קריאה אחת ל-process_capture_result() עם frame_number נתון יכולה לכלול את המטא-נתונים של התוצאה. בכל שאר הקריאות לאותו frame_number, צריך להגדיר את הערך הזה כ-NULL.

אם הייתה שגיאה ביצירת המטא-נתונים של התוצאה, ה-result צריך להיות מאגר מטא-נתונים ריק, וצריך להפעיל את notify() עם ERROR_RESULT.

>= CAMERA_DEVICE_API_VERSION_3_2:

מספר קריאות ל-process_capture_result() עם frame_number נתון עשויות לכלול את המטא-נתונים של התוצאה.

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

אם נקרא לפונקציה notify עם הערך ERROR_RESULT, המסגרת תתעלם מכל התוצאות החלקיות הנוספות של אותו פריים.

ההגדרה מופיעה בשורה 2285 בקובץ camera3.h .

התיעוד של המבנה הזה נוצר מהקובץ הבא: