XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

ประเภทส่วนขยาย

ส่วนขยายอินสแตนซ์

หมายเลขต่อที่ลงทะเบียนไว้

797

การแก้ไข

1

สถานะการให้สัตยาบัน

ไม่ได้รับการให้สัตยาบัน

ทรัพยากร Dependency ของส่วนขยายและเวอร์ชัน

OpenXR 1.0

วันที่แก้ไขล่าสุด

2026-03-10

สถานะ IP

ไม่มีการอ้างสิทธิ์ IP ที่ทราบ

ผู้เขียน

Brian Chen, Google
Kyle Chen, Google
Nihav Jain, Google
Spencer Quin, Google

ภาพรวม

เมื่อมีการเปิดตัวอุปกรณ์แบบมองทะลุผ่านเลนส์ สิ่งสำคัญคือไม่เพียงแต่อนุญาตให้แอปพลิเคชันปรับความมืดของโหมดส่งผ่านเพื่อผสมผสานกับบริบทของแอปให้ดีที่สุดสำหรับผู้ใช้เท่านั้น แต่ยังต้องอนุญาตให้ระบบเพิ่มความสว่างของโหมดส่งผ่านเพื่อความปลอดภัยด้วย

ส่วนขยายนี้มีฟังก์ชัน 2 อย่างสำหรับแอปในการตั้งค่าและรับระดับการหรี่แสงปัจจุบัน รวมถึงเหตุการณ์ที่จะประกาศเมื่อระดับการหรี่แสงเปลี่ยนไป

ตรวจสอบความสามารถของระบบ

โครงสร้าง 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

รหัสการคืนสินค้า

สำเร็จ

• 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

รหัสการคืนสินค้า

สำเร็จ

• 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

ค่าคงที่ Enum ใหม่

• 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, 2025-10-07 (Brian Chen)

  • คำอธิบายส่วนขยายเริ่มต้น