תוסף OpenXR‏ XR_ANDROID_performance_metrics

Name String

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

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

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

הפונקציה 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);

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

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

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

קודי החזרה

הצלחה

  • 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);

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

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

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

קודי החזרה

הצלחה

  • 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);

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

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

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

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

קודי החזרה

הצלחה

  • 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