XR_ANDROID_global_passthrough_dimming

رشته نام

XR_ANDROID_global_passthrough_dimming

نوع افزونه

افزونه نمونه

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

797

بازبینی

1

وضعیت تصویب

تصویب‌نشده

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

OpenXR 1.0

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

2026-03-10

وضعیت IP

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

همیاران

Brian Chen،‏ Google
Kyle Chen،‏ Google
Nihav Jain،‏ Google
Spencer Quin،‏ Google

نمای کلی

با معرفی دستگاه‌های نوری شفاف، مهم است که نه‌تنها به برنامه‌ها اجازه داده شود تا تاریکی حالت شفاف را تنظیم کنند تا بهترین ترکیب با بافت برنامه را به کاربر ارائه دهند، بلکه به سیستم نیز اجازه داده شود تا به دلایل ایمنی، حالت شفاف را روشن‌تر کند.

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

بررسی قابلیت سیستم

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

typedef struct XrSystemGlobalDimmingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGlobalDimming;
} XrSystemGlobalDimmingPropertiesANDROID;

توضیحات عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• ‫supportsGlobalDimming یک XrBool32 است که نشان می‌دهد آیا سیستم فعلی از تار کردن سراسری پشتیبانی می‌کند یا نه.

برنامه می‌تواند با زنجیر کردن ساختار XrSystemGlobalDimmingPropertiesANDROID به XrSystemProperties هنگام فراخوانی xrGetSystemProperties بررسی کند که آیا سیستم از تاریک‌سازی سراسری پشتیبانی می‌کند یا نه.

اگر زمان اجرا XR_FALSE را برای supportsGlobalDimming برگرداند، زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED را هنگام فراخوانی xrGetGlobalDimmingLevelANDROID برگرداند.

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

• افزونه XR_ANDROID_global_passthrough_dimming باید پیش‌از استفاده از XrSystemGlobalDimmingPropertiesANDROID فعال شود
• type باید XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

شمارش سطوح تاریک‌سازی سراسری پشتیبانی‌شده

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

XrResult xrEnumerateSupportedGlobalDimmingLevelsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedGlobalDimmingLevelCapacityInput,
    uint32_t*                                   supportedGlobalDimmingLevelCountOutput,
    float*                                      supportedGlobalDimmingLevels);

توضیحات عضو

• instance نمونه‌ای است که systemId از آن بازیابی شده است.
• systemId XrSystemId است که سطوح پشتیبانی‌شده آن شمارش خواهد شد.
• supportedGlobalDimmingLevelCapacityInput ظرفیت آرایه supportedGlobalDimmingLevels است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
• ‫supportedGlobalDimmingLevelCountOutput اشاره‌گری به تعداد supportedGlobalDimmingLevels نوشته‌شده است، یا اشاره‌گری به ظرفیت موردنیاز درصورتی‌که supportedGlobalDimmingLevelCapacityInput کافی نباشد.
• ‫supportedGlobalDimmingLevels اشاره‌گری به آرایه‌ای از سطوح پشتیبانی‌شده است، اما اگر supportedGlobalDimmingLevelCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.

اگر مقدار برگردانده‌شده supportedGlobalDimmingLevelCountOutput برابر با ۰ باشد، همه سطوح تاریک‌سازی سراسری بین ۰٫۰ و ۱٫۰ پشتیبانی می‌شود.

xrEnumerateSupportedGlobalDimmingLevelsANDROID سطوح کم‌نور کردن سراسری را که XrSystemId پشتیبانی می‌کند برمی‌شمارد. سطوح پشتیبانی‌شده نباید درطول عمر XrInstance آن تغییر کند. فهرست برگردانده‌شده از سطوح باید به‌ترتیب صعودی مرتب شده باشد.

زمان‌های اجرا باید همیشه محتوای میان‌گیر یکسانی را از این شمارش برای systemId داده‌شده و برای طول عمر instance برگردانند.

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

• افزونه XR_ANDROID_global_passthrough_dimming باید قبل‌از فراخوانی xrEnumerateSupportedGlobalDimmingLevelsANDROID فعال شود
• instance باید شناسه XrInstance معتبری باشد
• supportedGlobalDimmingLevelCountOutput باید اشاره‌گری به مقدار uint32_t باشد
• اگر supportedGlobalDimmingLevelCapacityInput 0 نباشد، supportedGlobalDimmingLevels باید اشاره‌گری به آرایه‌ای از مقادیر supportedGlobalDimmingLevelCapacityInput float باشد

کدهای برگشتی

موفقیت‌آمیز بود

• XR_SUCCESS

ناموفق

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SYSTEM_INVALID
• XR_ERROR_VALIDATION_FAILURE

پیکربندی سطح کم‌نور کردن سراسری

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

typedef struct XrGlobalDimmingFrameEndInfoANDROID {
    XrStructureType    type;
    const void*        next;
    float              globalDimmingLevel;
} XrGlobalDimmingFrameEndInfoANDROID;

شرح پارامترها

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• globalDimmingLevel مقداری بین ۰٫۰ (شفاف) و ۱٫۰ (مات) است. زمان اجرا ممکن است این مقدار را به نزدیک‌ترین سطح کم‌نور کردن سراسری پشتیبانی‌شده نگاشت کند. برنامه می‌تواند این مقدار را روی ‎-۱٫۰ تنظیم کند تا نشان دهد که سطح کم‌نور شدن فعلی ترجیح داده می‌شود.

مقدار globalDimmingLevel درصد نوری را که مسدود می‌شود مشخص می‌کند، که در آن مقدار ۰٫۰ با ۰٪ مسدود شدن نور و ۱٫۰ با ۱۰۰٪ مسدود شدن نور مطابقت دارد. درصد نور مسدودشده می‌تواند به‌طور کلی به‌صورت زیر نشان داده شود:

100% - Light Transmittance%

درصد انتقال نور، طبق ISO 8980-3:2022، می‌تواند به‌عنوان نسبت شار تابشی منتقل‌شده به شار تابشی فرودی در طول موج‌های نور مرئی (۳۸۰ نانومتر تا ۷۸۰ نانومتر) اندازه‌گیری شود.

‫XrGlobalDimmingFrameEndInfoANDROID ساختاری است که برنامه می‌تواند در XrFrameEndInfo زنجیره‌ای کند تا سطح تاریک‌سازی سراسری ترجیحی را درخواست کند.

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

زمان اجرا کنترل سطح تاریک‌سازی سراسری را دراختیار خواهد داشت و ممکن است به‌دلایل ایمنی سطح تاریک‌سازی سراسری ترجیحی را نادیده بگیرد.

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

• افزونه XR_ANDROID_global_passthrough_dimming باید پیش‌از استفاده از XrGlobalDimmingFrameEndInfoANDROID فعال شود
• type باید XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

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

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

شرح پارامترها

• session یک دسته XrSession معتبر است.
• dimmingLevel اشاره‌گری به سطح تاریک‌سازی فعلی است.

dimmingLevel برگردانده‌شده باید بین ۰٫۰ و ۱٫۰ باشد که ۰٫۰ به‌معنای کاملاً شفاف و ۱٫۰ به‌معنای کاملاً کم‌نور است.

اگر سطح کم‌نور شدن تنظیم نشده باشد، زمان اجرا باید سطح کم‌نور شدن را روی ۰٫۰ تنظیم کند وقتی حالت مستقیم فعال است و روی ۱٫۰ وقتی حالت مستقیم غیرفعال است.

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

• افزونه XR_ANDROID_global_passthrough_dimming باید قبل‌از فراخوانی xrGetGlobalDimmingLevelANDROID فعال شود
• session باید یک دسته XrSession معتبر باشد
• dimmingLevel باید اشاره‌گری به مقدار float باشد

کدهای برگشتی

موفقیت‌آمیز بود

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ناموفق

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_VALIDATION_FAILURE

رویداد تغییر سطح کم‌نور شدن

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

typedef struct XrEventDataGlobalDimmingLevelChangedANDROID {
    XrStructureType    type;
    const void*        next;
    XrSession          session;
} XrEventDataGlobalDimmingLevelChangedANDROID;

توضیحات عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• session یک دسته XrSession معتبر است.

برنامه می‌تواند این رویداد را بااستفاده از xrPollEvent بازیابی کند. این رویداد زمانی ارسال می‌شود که سطح کم‌نور شدن توسط برنامه‌ها یا دکمه‌های فیزیکی روی دستگاه‌ها تغییر کند.

وقتی برنامه متمرکزشده به برنامه دیگری تغییر کند، این رویداد ارسال نخواهد شد.

برنامه باید با فراخوانی xrGetGlobalDimmingLevelANDROID به رویداد پاسخ دهد تا سطح تاریک‌سازی جدید را دریافت کند و XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel را براساس آن به‌روز کند. پاسخ دادن به رویداد تضمین می‌کند که وقتی برنامه سطح کم‌نور کردن ترجیحی را تغییر می‌دهد، به زمان اجرا علامت داده شود.

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

• افزونه XR_ANDROID_global_passthrough_dimming باید قبل‌از استفاده از XrEventDataGlobalDimmingLevelChangedANDROID فعال شود
• type باید XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

کد نمونه

بررسی قابلیت سیستم و شمارش سطوح کم‌نور کردن سراسری پشتیبانی‌شده

کد نمونه زیر نشان می‌دهد که چگونه می‌توان بررسی کرد که آیا کم‌نور کردن سراسری پشتیبانی می‌شود یا نه.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedGlobalDimmingLevelsANDROID xrEnumerateSupportedGlobalDimmingLevelsANDROID;

XrSystemGlobalDimmingPropertiesANDROID dimmingControlSystemProperties { XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID };

XrSystemProperties systemProperties; // Chain dimmingControlSystemProperties

// ...
// Run xrGetSystemProperties()
// ...

if (!dimmingControlSystemProperties.supportsGlobalDimming) {
  // The system does not support global dimming
  return;
}

// Enumerate supported levels
uint32_t count = 0;
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, nullptr));

std::vector<float> supportedLevels(count);
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, supportedLevels.data()));

رویداد تغییر سطح کم‌نور کردن نظرسنجی

کد نمونه زیر نشان می‌دهد که چگونه می‌توان رویداد تغییر سطح کم‌نور شدن را نظرسنجی کرد.

XrEventDataBuffer event{ XR_TYPE_EVENT_DATA_BUFFER };

// ...
// Run xrPollEvent()
// ...

switch (event.type) {
  // This event will not be sent when focused app switches
  case XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID:
  {
    const XrEventDataGlobalDimmingLevelChangedANDROID &dimmingLevelChangedEvent =
            *reinterpret_cast<XrEventDataGlobalDimmingLevelChangedANDROID *>(&event);

    // Query new dimming level using xrGetGlobalDimmingLevelANDROID()
  }
}

فرمان‌های جدید

• xrEnumerateSupportedGlobalDimmingLevelsANDROID
• xrGetGlobalDimmingLevelANDROID

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

• XrEventDataGlobalDimmingLevelChangedANDROID

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

  • XrGlobalDimmingFrameEndInfoANDROID

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

  • XrSystemGlobalDimmingPropertiesANDROID

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

• XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
• XR_ANDROID_global_passthrough_dimming_SPEC_VERSION

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

  • XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID
  • XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID
  • XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID

مشکلات

سابقه نسخه

• بازبینی ۱، ‎۲۰۲۵-۱۰-۰۷ (Brian Chen)

  • توضیحات اولیه افزونه.