Android XR SDK זמין עכשיו בתצוגה מקדימה למפתחים. אנו רוצים את המשוב שלך! אפשר לפנות אלינו דרך דף התמיכה.

דף זה תורגם על ידי Cloud Translation API.

תוסף OpenXR‏ XR_ANDROID_performance_metrics

מחרוזת שם

XR_ANDROID_performance_metrics

סוג התוסף

תוסף למכונה

מספר תוסף רשום

466

תאריך השינוי האחרון

2024-09-06

סטטוס כתובת ה-IP

לא ידוע על תלונות על הפרת זכויות יוצרים בנושא כתובת IP.

תלות בתוספים ובגרסאות

OpenXR 1.0

שותפים ביצירת התוכן

דמיטרי קוטוב (Dmitry Kotov), Google

לבנה צ'ן, Google

Jared Finder, ‏ Google

ספנסר קווין (Spencer Quin), Google

סקירה כללית

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

ספירות מדדי הביצועים מאורגנות לפי ערכים מוגדרים מראש של XrPath, בנתיב הבסיס /perfmetrics_android. אפליקציה יכולה לשלוח שאילתה למונהנים הזמינים באמצעות xrEnumeratePerformanceMetricsCounterPathsANDROID. ריכזנו כאן רשימה של נתיבים למערכי נתונים של מדדי הביצועים שעשויים להינתן במכשירי Android:

‎/perfmetrics_android/app/cpu_frametime (אלפיות שנייה, float) – הזמן שחלף על השעון בזמן שהלקוח עיבד פריים.
‎/perfmetrics_android/app/gpu_frametime (אלפיות שנייה, float) – הזמן בפועל שהלקוח המתין להשלמת העבודה ב-GPU לכל פריים. הערות:
- זמן המתנה ארוך יכול להצביע על כך שה-GPU היה עסוק במשימות אחרות, ולא בהכרח על כך שהלקוח הזה מבצע יותר מדי משימות ב-GPU.
- זמן ההמתנה ל-GPU יכול להיות אפס אם הטרנספורמציה כבר הושלמה כשהיא נבדקה על ידי המאגר.
/perfmetrics_android/app/cpu_utilization (אחוז, ערך צף) – שיעור ניצול המעבד הכולל של האפליקציה בממוצע לאורך זמן.
- הערך יכול להיות גבוה מ-100% במעבדים עם כמה ליבות.
‎/perfmetrics_android/app/gpu_utilization (אחוז) – שיעור ניצול ה-GPU הכולל של האפליקציה בממוצע לאורך זמן.
/perfmetrics_android/app/motion_to_photon_latency (אלפיות שנייה, float) – משך הזמן שחלף מאירוע תנועה ביוזמת המשתמש ועד לעדכון התמונה הפיזית התואמת במסך.
/perfmetrics_android/compositor/cpu_frametime (אלפיות שנייה, float) – הזמן שחלף על צג השעון שבו הרכיב המשלב השתמש כדי לעבד פריים.
‎/perfmetrics_android/compositor/gpu_frametime (אלפיות שנייה, float) – הזמן שחלף לפי שעון המערכת שהמרכז הקולי הקדיש להמתנה להשלמת העבודה ב-GPU לכל פריים.
/perfmetrics_android/compositor/dropped_frame_count (מספר שלם) – המספר הכולל של פריימים שהוחמצו מכל האפליקציות.
/perfmetrics_android/compositor/frames_per_second (float) – מספר הפריימים של ה-compositor שצוירו במכשיר בשנייה.
/perfmetrics_android/device/cpu_utilization_average (אחוז, ערך צף) – שיעור ניצול המעבד במכשיר בממוצע בכל הליבות, וממוצע לאורך זמן.
‎/perfmetrics_android/device/cpu_utilization_worst (אחוז, ערך צף) – שיעור ניצול המעבד (CPU) במכשיר של הליבה עם הביצועים הגרועים ביותר, בממוצע לאורך זמן.
/perfmetrics_android/device/cpu0_utilization עד /perfmetrics_android/device/cpuX_utilization (אחוז, ערך צף, X הוא מספר ליבות המעבד פחות אחת) – שיעור ניצול המעבד במכשיר לכל ליבה בממוצע לאורך זמן.
‎/perfmetrics_android/device/cpu_frequency (מגה-הרץ, float) – תדירות המעבד במכשיר בממוצע בכל הליבות ובממוצע לאורך זמן.
‎/perfmetrics_android/device/gpu_utilization (אחוז, מספר צף) – שיעור ניצול ה-GPU במכשיר בממוצע לאורך זמן.

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

כדי להפעיל את הפונקציונליות של התוסף הזה, האפליקציה צריכה להעביר את שם התוסף ל-xrCreateInstance באמצעות הפרמטר XrInstanceCreateInfo::enabledExtensionNames, כפי שמפורט בקטע תוספים.

סוגי דגלים חדשים

typedef XrFlags64 XrPerformanceMetricsCounterFlagsANDROID;

// Flag bits for XrPerformanceMetricsCounterFlagsANDROID
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_ANY_VALUE_VALID_BIT_ANDROID = 0x00000001;
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID = 0x00000002;
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID = 0x00000004;

קבועים חדשים של טיפוס בן מנייה (enum)

המניין XrStructureType הורחב עם:

XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

Enums חדשים

typedef enum XrPerformanceMetricsCounterUnitANDROID {
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_GENERIC_ANDROID = 0,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_PERCENTAGE_ANDROID = 1,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_MILLISECONDS_ANDROID = 2,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_BYTES_ANDROID = 3,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_HERTZ_ANDROID = 4
} XrPerformanceMetricsCounterUnitANDROID;

מבנים חדשים

המבנה XrPerformanceMetricsStateANDROID מוגדר כך:

typedef struct XrPerformanceMetricsStateANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           enabled;
} XrPerformanceMetricsStateANDROID;

תיאורי חברים

type הוא XrStructureType של המבנה הזה.
next הוא NULL או הפניה למבנה הבא בשרשרת המבנים. לא מוגדרים מבנים כאלה ב-OpenXR או בהרחבה הזו.
כשמקבלים את המצב, הערך של enabled מוגדר ל-XR_TRUE כדי לציין שהמערכת של מדדי הביצועים מופעלת, או ל-XR_FALSE במקרה אחר. כשמגדירים את המצב, צריך להגדיר XR_TRUE כדי להפעיל את המערכת למדדי הביצועים ו-XR_FALSE כדי להשבית אותה.

הערך XrPerformanceMetricsStateANDROID מסופק כקלט כשקוראים ל-xrSetPerformanceMetricsStateANDROID כדי להפעיל או להשבית את מערכת מדדי הביצועים. הפרמטר XrPerformanceMetricsStateANDROID מאוכלס כפרמטר פלט כשקוראים ל-xrGetPerformanceMetricsStateANDROID כדי לבדוק אם מערכת מדדי הביצועים מופעלת.

שימוש תקין (מרומז)

חובה להפעיל את התוסף XR_ANDROID_performance_metrics לפני שמשתמשים ב-XrPerformanceMetricsStateANDROID
הערך של type חייב להיות XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
next חייב להיות NULL או מצביע חוקי למבנה הבא בשרשרת המבנים

המבנה XrPerformanceMetricsCounterANDROID מוגדר כך:

typedef struct XrPerformanceMetricsCounterANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrPerformanceMetricsCounterFlagsANDROID    counterFlags;
    XrPerformanceMetricsCounterUnitANDROID     counterUnit;
    uint32_t                                   uintValue;
    float                                      floatValue;
} XrPerformanceMetricsCounterANDROID;

תיאורי חברים

type הוא XrStructureType של המבנה הזה.
next הוא NULL או הפניה למבנה הבא בשרשרת המבנים. לא מוגדרים מבנים כאלה ב-OpenXR או בהרחבה הזו.
counterFlags הוא מסיכת ביט של XrPerformanceMetricsCounterFlagsANDROID שמתארת את התוקף של חברי הערך.
counterUnit הוא enum של XrPerformanceMetricsCounterUnitANDROID שמתאר את יחידת המדידה.
uintValue הוא ערך המונה בפורמט uint32_t. הוא תקף אם counterFlags מכיל את XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID.
floatValue הוא ערך המונה בפורמט float. הוא תקף אם counterFlags מכיל את XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID.

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

שימוש תקין (מרומז)

חובה להפעיל את התוסף XR_ANDROID_performance_metrics לפני שמשתמשים ב-XrPerformanceMetricsCounterANDROID
הערך של type חייב להיות XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID
next חייב להיות NULL או מצביע חוקי למבנה הבא בשרשרת המבנים
הערך של counterFlags חייב להיות 0 או שילוב תקין של ערכים של XrPerformanceMetricsCounterFlagsANDROID
counterUnit חייב להיות ערך חוקי של XrPerformanceMetricsCounterUnitANDROID

פונקציות חדשות

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

XrResult xrEnumeratePerformanceMetricsCounterPathsANDROID(
    XrInstance                                  instance,
    uint32_t                                    counterPathCapacityInput,
    uint32_t*                                   counterPathCountOutput,
    XrPath*                                     counterPaths);

תיאורי פרמטרים

instance הוא ערך של XrInstance שנוצר קודם לכן באמצעות xrCreateInstance.
counterPathCapacityInput הוא הקיבולת של מערך counterPaths, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
counterPathCountOutput מתמלא בסביבת זמן הריצה במספר ה-counterPaths שנכתבו או בקיבולת הנדרשת במקרה ש-counterPathCapacityInput לא מספיקה.
counterPaths הוא מערך של XrPath שמתמלא בסביבת זמן הריצה, ומכיל את כל המונים של מדדי הביצועים הזמינים. עם זאת, יכול להיות שהוא NULL אם הערך של counterPathCapacityInput הוא 0.
בקטע פרמטרים של גודל מאגר מפורט תיאור של אחזור הגודל הנדרש של counterPaths.

שימוש תקין (מרומז)

חובה להפעיל את התוסף XR_ANDROID_performance_metrics לפני שמפעילים את xrEnumeratePerformanceMetricsCounterPathsANDROID
instance חייב להיות מזהה XrInstance חוקי
counterPathCountOutput חייב להיות הפניה לערך uint32_t
אם הערך של counterPathCapacityInput הוא לא 0, הערך של counterPaths חייב להיות הפניה למערך של counterPathCapacityInput ערכים מסוג XrPath

קודי החזרה

הצלחה

XR_SUCCESS

כישלון

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_VALIDATION_FAILURE
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_SIZE_INSUFFICIENT

הפונקציה xrSetPerformanceMetricsStateANDROID מוגדרת כך:

XrResult xrSetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    const XrPerformanceMetricsStateANDROID*     state);

תיאורי פרמטרים

session הוא ערך של XrSession שנוצר קודם לכן באמצעות xrCreateSession.
state הוא הפניה למבנה XrPerformanceMetricsStateANDROID.

הפונקציה xrSetPerformanceMetricsStateANDROID מפעילה או משביתה את מערכת מדדי הביצועים.

שימוש תקין (מרומז)

חובה להפעיל את התוסף XR_ANDROID_performance_metrics לפני שמפעילים את xrSetPerformanceMetricsStateANDROID
session חייב להיות מזהה XrSession חוקי
state חייב להיות הפניה למבנה תקין של XrPerformanceMetricsStateANDROID

קודי החזרה

הצלחה

XR_SUCCESS
XR_SESSION_LOSS_PENDING

כישלון

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_VALIDATION_FAILURE
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_SESSION_LOST

הפונקציה xrGetPerformanceMetricsStateANDROID מוגדרת כך:

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

תיאורי פרמטרים

session הוא ערך של XrSession שנוצר קודם לכן באמצעות xrCreateSession.
state הוא הפניה למבנה XrPerformanceMetricsStateANDROID.

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

שימוש תקין (מרומז)

חובה להפעיל את התוסף XR_ANDROID_performance_metrics לפני שמפעילים את xrGetPerformanceMetricsStateANDROID
session חייב להיות מזהה XrSession חוקי
state חייב להיות הפניה למבנה XrPerformanceMetricsStateANDROID

קודי החזרה

הצלחה

XR_SUCCESS
XR_SESSION_LOSS_PENDING

כישלון

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_VALIDATION_FAILURE
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_SESSION_LOST

הפונקציה xrQueryPerformanceMetricsCounterANDROID מוגדרת בתור:

XrResult xrQueryPerformanceMetricsCounterANDROID(
    XrSession                                   session,
    XrPath                                      counterPath,
    XrPerformanceMetricsCounterANDROID*         counter);

תיאורי פרמטרים

session הוא ערך של XrSession שנוצר קודם לכן באמצעות xrCreateSession.
counterPath הוא נתיב חוקי של מונה של מדדי ביצועים.
counter הוא הפניה למבנה XrPerformanceMetricsCounterANDROID.

הפונקציה xrQueryPerformanceMetricsCounterANDROID שולחת שאילתה למונה של מדדי הביצועים.

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

שימוש תקין (מרומז)

חובה להפעיל את התוסף XR_ANDROID_performance_metrics לפני שמפעילים את xrQueryPerformanceMetricsCounterANDROID
session חייב להיות מזהה XrSession חוקי
counter חייב להיות הפניה למבנה XrPerformanceMetricsCounterANDROID

קודי החזרה

הצלחה

XR_SUCCESS
XR_SESSION_LOSS_PENDING

כישלון

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_VALIDATION_FAILURE
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_SESSION_LOST
XR_ERROR_PATH_UNSUPPORTED
XR_ERROR_PATH_INVALID