إضافة XR_ANDROID_performance_metrics OpenXR

سلسلة الاسم

XR_ANDROID_performance_metrics

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

466

تاريخ آخر تعديل

2024-09-06

حالة عنوان IP

ما مِن مطالبات معروفة بعناوين IP.

التبعيات المتعلّقة بالإصدارات والإضافات

OpenXR 1.0

المساهمون

ديمتري كوتوف، Google

ليفانا تشين، من Google

جاريد فايندر، Google

سبنسر كوين، Google

نظرة عامة

توفّر هذه الإضافة واجهات برمجة تطبيقات لتعداد ومقاييس الأداء المختلفة للتحقّق من جهاز الواقع الممتد الحالي والمركّب وتطبيق الواقع الممتد. يمكن للمطوّرين إجراء تحليل للأداء وإجراء تحسين مستهدف لتطبيق الواقع المعزّز باستخدام عدادات مقاييس الأداء التي يتم جمعها. يجب ألّا يغيّر التطبيق سلوكه استنادًا إلى عمليات قراءة العداد.

يتم تنظيم عدادات مقاييس الأداء في قيم مُحدَّدة مسبقًا XrPath ضمن المسار الجذر /perfmetrics_android. يمكن للتطبيق الاستعلام عن العدادات المتاحة من خلال xrEnumeratePerformanceMetricsCounterPathsANDROID. في ما يلي قائمة بمسارات عداد مقاييس الأداء التي قد يتم توفيرها على أجهزة Android:

  • ‎/perfmetrics_android/app/cpu_frametime (بالملّي ثانية، عدد عشري) - الوقت الذي استغرقه العميل لمعالجة لقطة.
  • ‎/perfmetrics_android/app/gpu_frametime (بالملي ثانية، عدد عشري) - الوقت الفعلي الذي يقضيه العميل في انتظار اكتمال عمل وحدة معالجة الرسومات لكل لقطة ملاحظات:
    • يمكن أن يعني وقت الانتظار الطويل أنّ وحدة معالجة الرسومات كانت مشغولة بمهام أخرى، وليس بالضرورة أنّ هذا العميل يُجري الكثير من المهام على وحدة معالجة الرسومات.
    • يمكن أن يكون وقت انتظار وحدة معالجة الرسومات صفرًا إذا كان التقديم قد اكتمل بالفعل عند فحصه من قِبل أداة الدمج.
  • ‎/perfmetrics_android/app/cpu_utilization (النسبة المئوية، عدد عشري) - إجمالي معدّل استخدام وحدة المعالجة المركزية (CPU) للتطبيق بالمتوسط على مدار الوقت
    • يمكن أن يكون هذا المقياس أعلى من% 100 على المعالجات متعددة النوى.
  • ‎/perfmetrics_android/app/gpu_utilization (نسبة مئوية) - إجمالي معدّل استخدام وحدة معالجة الرسومات للتطبيق على مدار الوقت
  • ‎/perfmetrics_android/app/motion_to_photon_latency (ملي ثانية، عدد عشري) - الوقت المستغرَق من حدث الحركة الذي بدأه المستخدم إلى تعديل الصورة الفعلية المقابل على الشاشة
  • ‎/perfmetrics_android/compositor/cpu_frametime (بالملّي ثانية، عدد عشري) - الوقت الذي استغرقه المُركِّب لمعالجة لقطة.
  • ‎/perfmetrics_android/compositor/gpu_frametime (بالملي ثانية، عدد عشري) - الوقت الذي يستغرقه المُركِّب بالساعات العادية في انتظار اكتمال عمل وحدة معالجة الرسومات لكل لقطة.
  • ‎/perfmetrics_android/compositor/dropped_frame_count (عدد صحيح) - إجمالي عدد اللقطات التي تم إسقاطها من جميع التطبيقات
  • ‎/perfmetrics_android/compositor/frames_per_second (float) - عدد لقطات أداة الدمج التي يتم رسمها على الجهاز في الثانية
  • ‎/perfmetrics_android/device/cpu_utilization_average (النسبة المئوية، عدد عشري) - يتم احتساب متوسط معدّل استخدام وحدة المعالجة المركزية (CPU) على الجهاز على مستوى جميع النوى ومتوسطه بمرور الوقت.
  • ‎/perfmetrics_android/device/cpu_utilization_worst (نسبة مئوية، عدد عشري) - معدّل استخدام وحدة المعالجة المركزية (CPU) للجهاز للنواة الأسوأ أداءً متوسّطًا على مدار الوقت
  • ‫‎/perfmetrics_android/device/cpu0_utilization إلى ‎/perfmetrics_android/device/cpuX_utilization (نسبة مئوية، عدد أعداد صحيحة، X هو عدد نوى وحدة المعالجة المركزية مطروحًا منه واحد) - معدل استخدام وحدة المعالجة المركزية للجهاز لكل نواة وحدة معالجة مركزية في المتوسط على مدار الوقت
  • ‫/perfmetrics_android/device/cpu_frequency (بوحدة ميغاهرتز، عدد عشري) - معدّل تكرار وحدة المعالجة المركزية للجهاز بالمتوسط على جميع النوى والمتوسط بمرور الوقت
  • ‎/perfmetrics_android/device/gpu_utilization (نسبة مئوية، عدد عشري) - متوسط معدّل استخدام وحدة معالجة الرسومات في الجهاز بمرور الوقت

بعد إنشاء جلسة، يمكن للتطبيق استخدام 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;

ثوابِت التعداد الجديدة

تمّت إضافة ما يلي إلى التعداد XrStructureType:

  • XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

عمليات التعداد الجديدة

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 هو عنصر مصنّف من 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 طلب بحث في counter مقاييس الأداء.

يجب أن يفعّل التطبيق نظام مقاييس الأداء من خلال استدعاء 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