افزونه XR_ANDROID_performance_metrics OpenXR

رشته نام

XR_ANDROID_performance_metrics

نوع پسوند

پسوند نمونه

شماره برنامه افزودنی ثبت شده

466

آخرین تاریخ اصلاح

06-09-2024

وضعیت IP

هیچ ادعای IP شناخته شده ای وجود ندارد.

وابستگی های افزونه و نسخه

OpenXR 1.0

مشارکت کنندگان

دیمیتری کوتوف، گوگل

لوانا چن، گوگل

جارد فایندر، گوگل

اسپنسر کوین، گوگل

نمای کلی

این برنامه افزودنی APIهایی را برای شمارش و پرس و جوی شمارشگرهای مختلف معیارهای عملکرد دستگاه XR فعلی، کامپوزیتور و برنامه XR فراهم می کند. توسعه دهندگان می توانند تجزیه و تحلیل عملکرد و بهینه سازی هدفمند برنامه XR را با استفاده از شمارنده های معیارهای عملکرد جمع آوری شده انجام دهند. برنامه نباید رفتار خود را بر اساس خواندن شمارنده تغییر دهد.

شمارنده های معیارهای عملکرد در مقادیر از پیش تعریف شده XrPath ، در مسیر ریشه /perfmetrics_android سازماندهی می شوند. یک برنامه کاربردی می تواند شمارنده های موجود را از طریق xrEnumeratePerformanceMetricsCounterPathsANDROID پرس و جو کند. در اینجا فهرستی از مسیرهای شمارشگر معیارهای عملکردی که ممکن است در دستگاه‌های Android ارائه شوند، آمده است:

• /perfmetrics_android/app/cpu_frametime (میلی ثانیه، شناور) - زمان ساعت دیواری که مشتری برای پردازش یک فریم صرف کرده است.
• /perfmetrics_android/app/gpu_frametime (میلی‌ثانیه، شناور) - زمانی که مشتری ساعت دیواری در انتظار تکمیل کار GPU در هر فریم می‌ماند. یادداشت ها:
  • زمان انتظار زیاد می‌تواند به این معنی باشد که GPU مشغول کارهای دیگر بوده است، نه لزوماً این که این کلاینت کارهای GPU زیادی انجام می‌دهد.
  • زمان انتظار GPU می تواند صفر باشد اگر رندر از قبل توسط کامپوزیتور بررسی شده باشد.
• /perfmetrics_android/app/cpu_utilization (درصد، شناور) - میانگین کل نرخ استفاده از CPU برنامه در طول زمان.
  • این می تواند در پردازنده های چند هسته ای بالاتر از 100٪ باشد.
• /perfmetrics_android/app/gpu_utilization (درصد) - میانگین میزان استفاده از GPU برنامه در طول زمان.
• /perfmetrics_android/app/motion_to_photon_latency (میلی‌ثانیه، شناور) - زمان صرف شده از رویداد حرکتی آغاز شده توسط کاربر تا به‌روزرسانی تصویر فیزیکی مربوطه روی نمایشگر.
• /perfmetrics_android/compositor/cpu_frametime (میلی ثانیه، شناور) - زمان کامپوزیتور ساعت دیواری که برای پردازش یک فریم صرف شده است.
• /perfmetrics_android/compositor/gpu_frametime (میلی ثانیه، شناور) - زمان سازنده ساعت دیواری در انتظار تکمیل کار GPU در هر فریم است.
• /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 تعداد هسته‌های CPU منهای یک است) - میانگین میزان استفاده از CPU دستگاه به ازای هر هسته CPU در طول زمان.
• /perfmetrics_android/device/cpu_frequency (MHz، float) - فرکانس CPU دستگاه در همه هسته‌ها به طور متوسط ​​​​و میانگین در طول زمان محاسبه می شود.
• /perfmetrics_android/device/gpu_utilization (درصد، شناور) - میانگین میزان استفاده از GPU دستگاه در طول زمان.

پس از ایجاد یک جلسه، یک برنامه کاربردی می تواند از xrSetPerformanceMetricsStateANDROID برای فعال کردن سیستم معیارهای عملکرد برای آن جلسه استفاده کند. یک برنامه کاربردی می‌تواند از xrQueryPerformanceMetricsCounterANDROID برای پرس‌وجو از شمارنده معیارهای عملکرد در جلسه‌ای که سیستم معیارهای عملکرد فعال است استفاده کند، یا از xrGetPerformanceMetricsStateANDROID برای پرس‌وجویی در صورت فعال بودن سیستم معیارهای عملکرد استفاده کند.

برای فعال کردن عملکرد این برنامه افزودنی، برنامه باید نام برنامه افزودنی را با استفاده از پارامتر XrInstanceCreateInfo::enabledExtensionNames همانطور که در بخش Extensions نشان داده شده است، به xrCreateInstance منتقل کند.

انواع پرچم جدید

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

فهرست های جدید

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 تکمیل می‌شود تا اطلاعات شمارنده معیارهای عملکرد زمان واقعی را جستجو کنید.

استفاده معتبر (ضمنی)

• پسوند 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 است که توسط زمان اجرا پر شده و شامل تمام شمارنده‌های معیارهای عملکرد موجود است، اما اگر counterPathCapacityInput 0 باشد، می‌تواند NULL باشد.
• برای توضیحات مفصل در مورد بازیابی اندازه 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