XR_EXT_interaction_profile_battery_state_display

رشته نام

XR_EXT_interaction_profile_battery_state_display

نوع افزونه

افزونه نمونه

شماره داخلی ثبت‌شده

837

بازبینی

1

وضعیت تصویب

تصویب‌شده

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

OpenXR 1.0

تاریخ آخرین تغییر

2025-10-21

وضعیت IP

هیچ ادعای مالکیت فکری شناخته‌شده‌ای وجود ندارد.

همیاران

جان کرنی، Meta
دنیل ویلموت، Valve
دنی رونگرن، Varjo
جیکوب بورنکرانتز، NVIDIA
نیتن نوبر، Valve
لاکلان فورد، Google
نیهاو جین، Google

نمای کلی

‫XR_EXT_interaction_profile_battery_state_display سازوکاری برای برنامه‌ها فراهم می‌کند تا بتوانند اطلاعات وضعیت باتری دستگاه‌های مورداستفاده با نمایه‌های تعامل را از زمان اجرا درخواست کنند. این اطلاعات وضعیت باتری باید فقط برای اهداف نمایشی استفاده شود و زمان اجرا باید اطمینان حاصل کند که این اطلاعات با آنچه در میاناهای کاربر سیستم داخلی استفاده می‌شود مطابقت دارد.

در مواردی که چند دستگاه فیزیکی ورودی را برای کنش‌های مرتبط با مسیر سطح بالا ارائه می‌دهند، مثلاً زمان‌های اجرایی که برای سفارشی‌سازی کاربر یا دسترس‌پذیری، بازنگاشت انجام می‌دهند، آن زمان‌های اجرا باید نهایت تلاش خود را بکنند تا اطلاعات مفید باتری را در یک مقدار واحد ارائه دهند.

به‌طور خاص، انتظار نمی‌رود این اطلاعات بین زمان‌های اجرا یا دستگاه‌ها کالیبره شود و نباید برای تولید هشدار یا تغییر رفتار برنامه استفاده شود.

درحال جستجوی وضعیت باتری

ساختار XrBatteryStateDisplayEXT به‌صورت زیر تعریف می‌شود:

typedef struct XrBatteryStateDisplayEXT {
    XrStructureType                       type;
    void*                                 next;
    XrBatteryStateDisplayStateFlagsEXT    stateFlags;
    float                                 batteryLevel;
} XrBatteryStateDisplayEXT;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • stateFlags اعتبار batteryLevel را با بیت‌ماسک‌های تعریف‌شده در XrBatteryStateDisplayStateFlagBitsEXT توصیف می‌کند
  • ‫batteryLevel سطح باتری (از 0.0f تا 1.0f) دستگاه متصل‌شده توسط کنش یا نهاد مرتبط است.

برای پرس‌وجو درباره سطح باتری، برنامه ساختار XrBatteryStateDisplayEXT را به زنجیره XrInteractionProfileState :: next هنگام فراخوانی xrGetCurrentInteractionProfile زنجیر می‌کند.

اگر xrGetCurrentInteractionProfile مقدار XrInteractionProfileState :: interactionProfile را روی XR_NULL_PATH تنظیم کند، زمان اجرا نباید بیت XR_BATTERY_STATE_DISPLAY_STATE_VALID_BIT_EXT را در stateFlags تنظیم کند.

XR_BATTERY_STATE_DISPLAY_STATE_VALID_BIT_EXT نشان می‌دهد که آیا batteryLevel حاوی داده‌های معتبر است یا نه. اگر بیت XR_BATTERY_STATE_DISPLAY_STATE_VALID_BIT_EXT در stateFlags تنظیم نشده باشد، برنامه نباید batteryLevel را بخواند.

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

عضو XrBatteryStateDisplayEXT :: stateFlags از نوع زیر است و حاوی یک OR بیتی از صفر یا چند بیت تعریف‌شده در XrBatteryStateDisplayStateFlagBitsEXT است.

typedef XrFlags64 XrBatteryStateDisplayStateFlagsEXT;


// Flag bits for XrBatteryStateDisplayStateFlagsEXT
static const XrBatteryStateDisplayStateFlagsEXT XR_BATTERY_STATE_DISPLAY_STATE_VALID_BIT_EXT = 0x00000001;
static const XrBatteryStateDisplayStateFlagsEXT XR_BATTERY_STATE_DISPLAY_STATE_CHARGING_BIT_EXT = 0x00000002;
static const XrBatteryStateDisplayStateFlagsEXT XR_BATTERY_STATE_DISPLAY_STATE_PLUGGED_IN_BIT_EXT = 0x00000004;
static const XrBatteryStateDisplayStateFlagsEXT XR_BATTERY_STATE_DISPLAY_STATE_NO_BATTERY_BIT_EXT = 0x00000008;

بیت‌های پرچم معانی زیر را دارند:

توضیحات پرچم

  • XR_BATTERY_STATE_DISPLAY_STATE_VALID_BIT_EXT — نشان‌دهنده اعتبار XrBatteryStateDisplayEXT :: batteryLevel است
  • XR_BATTERY_STATE_DISPLAY_STATE_CHARGING_BIT_EXT — نشان می‌دهد دستگاه مرتبط با نمایه تعامل درحال شارژ شدن است.
  • XR_BATTERY_STATE_DISPLAY_STATE_PLUGGED_IN_BIT_EXT — نشان می‌دهد دستگاه مرتبط با نمایه تعامل به منبع برق وصل است.
  • XR_BATTERY_STATE_DISPLAY_STATE_NO_BATTERY_BIT_EXT — نشان می‌دهد دستگاه مرتبط با نمایه تعامل منبع تغذیه باتری ندارد.

مثال

// previously initialized
extern XrSession session;
extern XrPath topLevelUserPath;

XrBatteryStateDisplayEXT batteryStateDisplay{XR_TYPE_BATTERY_STATE_DISPLAY_EXT};
XrInteractionProfileState ipState{XR_TYPE_INTERACTION_PROFILE_STATE, &batteryStateDisplay};
CHK_XR(xrGetCurrentInteractionProfile(session, topLevelUserPath, &ipState));
if ((batteryStateDisplay.stateFlags & XR_BATTERY_STATE_DISPLAY_STATE_VALID_BIT_EXT) != 0) {
  // use value of batteryStateDisplay.batteryLevel
}

سازه‌های جدید

Enums جدید

ماسک‌های بیتی جدید

ثابت‌های شمارشی جدید

  • XR_EXT_INTERACTION_PROFILE_BATTERY_STATE_DISPLAY_EXTENSION_NAME
  • XR_EXT_interaction_profile_battery_state_display_SPEC_VERSION

  • درحال گسترش دادن XrStructureType :

    • XR_TYPE_BATTERY_STATE_DISPLAY_EXT

مشکلات

  • آیا برنامه می‌تواند با این افزونه سطح باتری نمایش‌داده‌شده برای دستگاه سربند را پُرسمان کند؟

    • حل‌وفصل شد. نه مستقیماً . این افزونه فقط از برگرداندن سطح باتری نمایش‌داده‌شده برای مسیرهای سطح بالای /user با نمایه‌های تعامل فعلی پشتیبانی می‌کند. اگر برنامه برای نمایه تعامل دستگاه نصب‌شده روی سر ( /user/head ) اتصال‌هایی را پیشنهاد دهد، و اگر زمان اجرا آن نمایه تعامل را فعال کند، زمان اجرا می‌تواند سطح باتری را برای آن مسیر سطح بالای /user برگرداند.

سابقه نسخه

  • بازبینی ۱،‏ ۲۰۲۵-۱۰-۲۱ (John Kearney)

    • پیش‌نویس اولیه.