XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

نوع الإضافة

إضافة مثيل

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

797

المراجعة

1

حالة التصديق

لم تتم المصادقة عليها

الاعتماد على الإضافات والإصدارات

OpenXR 1.0

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

2026-03-10

حالة الملكية الفكرية

ما مِن مطالبات معروفة بشأن الملكية الفكرية.

المساهمون

براين تشين، Google
كايل تشين، Google
نيهاف جاين، Google
سبنسر كوين، 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، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫supportedGlobalDimmingLevelCountOutput هو مؤشر إلى عدد supportedGlobalDimmingLevels المكتوبة، أو مؤشر إلى السعة المطلوبة في حال عدم كفاية supportedGlobalDimmingLevelCapacityInput.
• ‫supportedGlobalDimmingLevels هو مؤشر إلى مصفوفة من المستويات المتوافقة، ولكن يمكن أن يكون NULL إذا كانت قيمة supportedGlobalDimmingLevelCapacityInput هي 0.

إذا كانت قيمة supportedGlobalDimmingLevelCountOutput المعروضة هي 0، يعني ذلك أنّ جميع مستويات التعتيم الشامل بين 0.0 و1.0 متاحة.

xrEnumerateSupportedGlobalDimmingLevelsANDROID: تعداد مستويات التعتيم العام التي يتيحها XrSystemId . يجب ألا تتغيّر المستويات المتوافقة خلال فترة استخدام XrInstance . يجب ترتيب قائمة المستويات المعروضة تصاعديًا.

يجب أن تعرض بيئات التشغيل دائمًا محتوى مخزن مؤقت متطابق من هذا التعداد لـ systemId المحدّد وطوال مدة صلاحية instance .

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_ANDROID_global_passthrough_dimming قبل استدعاء xrEnumerateSupportedGlobalDimmingLevelsANDROID
• يجب أن يكون instance مقبض XrInstance صالحًا
• يجب أن يكون supportedGlobalDimmingLevelCountOutput مؤشرًا إلى قيمة uint32_t
• إذا لم تكن قيمة supportedGlobalDimmingLevelCapacityInput هي 0، يجب أن تكون قيمة supportedGlobalDimmingLevels مؤشرًا إلى مصفوفة من قيم supportedGlobalDimmingLevelCapacityInput float

رموز الإرجاع

Success

• 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 هي قيمة تتراوح بين 0.0 (شفاف) و1.0 (معتم). قد تربط بيئة التشغيل هذه القيمة بأقرب مستوى تعتيم عام متاح. يمكن للتطبيق ضبط هذه القيمة على ‎-1.0 للإشارة إلى أنّ مستوى التعتيم الحالي هو المفضّل.

تحدّد القيمة globalDimmingLevel النسبة المئوية للضوء الذي يتم حجبه، حيث تشير القيمة 0.0 إلى حجب الضوء بنسبة% 0 وتشير القيمة 1.0 إلى حجب الضوء بنسبة% 100. يمكن تمثيل النسبة المئوية للضوء المحجوب بشكل عام على النحو التالي:

100% - Light Transmittance%

يمكن قياس نسبة نفاذية الضوء، وفقًا لمعيار ISO 8980-3:2022، على أنّها نسبة التدفق الإشعاعي النافذ إلى التدفق الإشعاعي الساقط عند الأطوال الموجية للضوء المرئي (من 380 نانومتر إلى 780 نانومتر).

‫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 المعروضة بين 0.0 و1.0، حيث تشير القيمة 0.0 إلى شفافية كاملة وتشير القيمة 1.0 إلى تعتيم كامل.

إذا لم يتم ضبط مستوى التعتيم، يجب أن يضبط وقت التشغيل مستوى التعتيم على 0.0 عند تفعيل ميزة "الرؤية من خلال النظارة" وعلى 1.0 عند إيقافها.

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_ANDROID_global_passthrough_dimming قبل طلب xrGetGlobalDimmingLevelANDROID
• يجب أن يكون session اسم معرِّف XrSession صالحًا
• يجب أن يكون dimmingLevel مؤشرًا إلى قيمة float

رموز الإرجاع

Success

• 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

المشاكل

سجلّ الإصدارات

• المراجعة 1، في ‎07/10/2025 (براين تشن)

  • وصف الإضافة الأوّلي