XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

Loại tiện ích

Phần mở rộng thực thể

Số máy lẻ đã đăng ký

797

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa được phê chuẩn

Phần phụ thuộc của tiện ích và phiên bản

OpenXR 1.0

Ngày sửa đổi gần đây nhất

2026-03-10

Trạng thái IP

Không có tuyên bố nào về tài sản trí tuệ.

Cộng tác viên

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

Tổng quan

Khi các thiết bị quang học nhìn xuyên thấu được ra mắt, điều quan trọng là không chỉ cho phép các ứng dụng điều chỉnh độ tối của chế độ truyền qua để mang lại sự kết hợp tốt nhất với bối cảnh ứng dụng cho người dùng, mà còn cho phép hệ thống làm sáng chế độ truyền qua vì lý do an toàn.

Tiện ích này cung cấp hai hàm để ứng dụng đặt và lấy mức độ mờ hiện tại, cũng như một sự kiện để phát sóng khi mức độ mờ thay đổi.

Kiểm tra chức năng của hệ thống

Cấu trúc XrSystemGlobalDimmingPropertiesANDROID được định nghĩa như sau:

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

Nội dung mô tả về thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
• supportsGlobalDimming là một XrBool32 , cho biết liệu hệ thống hiện tại có hỗ trợ tính năng làm mờ toàn cục hay không.

Ứng dụng có thể kiểm tra xem hệ thống có hỗ trợ tính năng làm mờ toàn cục hay không bằng cách liên kết cấu trúc XrSystemGlobalDimmingPropertiesANDROID với XrSystemProperties khi gọi xrGetSystemProperties .

Nếu thời gian chạy trả về XR_FALSE cho supportsGlobalDimming , thì thời gian chạy phải trả về XR_ERROR_FEATURE_UNSUPPORTED khi xrGetGlobalDimmingLevelANDROID được gọi.

Cách sử dụng hợp lệ (Ngầm ẩn)

• Tiện ích XR_ANDROID_global_passthrough_dimming phải được bật trước khi sử dụng XrSystemGlobalDimmingPropertiesANDROID
• type phải là XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc

Liệt kê các mức độ làm mờ toàn cục được hỗ trợ

Cấu trúc xrEnumerateSupportedGlobalDimmingLevelsANDROID được định nghĩa như sau:

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

Nội dung mô tả về thành viên

• instance là thực thể mà systemId được truy xuất.
• systemId là XrSystemId có các cấp độ được hỗ trợ sẽ được liệt kê.
• supportedGlobalDimmingLevelCapacityInput là dung lượng của mảng supportedGlobalDimmingLevels hoặc 0 để cho biết yêu cầu truy xuất dung lượng cần thiết.
• supportedGlobalDimmingLevelCountOutput là con trỏ đến số lượng supportedGlobalDimmingLevels được ghi hoặc con trỏ đến dung lượng cần thiết trong trường hợp supportedGlobalDimmingLevelCapacityInput không đủ.
• supportedGlobalDimmingLevels là con trỏ đến một mảng các cấp được hỗ trợ, nhưng có thể là NULL nếu supportedGlobalDimmingLevelCapacityInput là 0.

Nếu supportedGlobalDimmingLevelCountOutput được trả về là 0, thì tất cả các mức độ mờ chung từ 0 đến 1 đều được hỗ trợ.

xrEnumerateSupportedGlobalDimmingLevelsANDROID liệt kê các mức độ làm mờ chung mà XrSystemId hỗ trợ. Các cấp độ được hỗ trợ không được thay đổi trong suốt thời gian hoạt động của XrInstance . Danh sách cấp độ được trả về phải được sắp xếp theo thứ tự tăng dần.

Thời gian chạy phải luôn trả về nội dung vùng đệm giống hệt nhau từ kiểu liệt kê này cho systemId đã cho và trong suốt thời gian hoạt động của instance .

Cách sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_ANDROID_global_passthrough_dimming trước khi gọi xrEnumerateSupportedGlobalDimmingLevelsANDROID
• instance phải là một tên người dùng XrInstance hợp lệ
• supportedGlobalDimmingLevelCountOutput phải là con trỏ đến giá trị uint32_t
• Nếu supportedGlobalDimmingLevelCapacityInput không phải là 0 , thì supportedGlobalDimmingLevels phải là con trỏ đến một mảng gồm các giá trị supportedGlobalDimmingLevelCapacityInput float

Mã trả về

Thành công

• XR_SUCCESS

Không thành công

• 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

Định cấu hình mức độ giảm độ sáng tổng thể

Cấu trúc XrGlobalDimmingFrameEndInfoANDROID được định nghĩa như sau:

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

Nội dung mô tả về tham số

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
• globalDimmingLevel là một giá trị nằm trong khoảng từ 0 (trong suốt) đến 1 (mờ đục). Thời gian chạy có thể liên kết giá trị này với mức làm mờ toàn cục được hỗ trợ gần nhất. Ứng dụng có thể đặt giá trị này thành -1.0 để cho biết rằng mức độ mờ hiện tại được ưu tiên.

Giá trị globalDimmingLevel chỉ định tỷ lệ phần trăm ánh sáng bị chặn, trong đó giá trị 0,0 tương ứng với 0% ánh sáng bị chặn và 1,0 tương ứng với 100% ánh sáng bị chặn. Tỷ lệ phần trăm ánh sáng bị chặn có thể được biểu thị chung như sau:

100% - Light Transmittance%

Tỷ lệ phần trăm độ truyền ánh sáng, theo ISO 8980-3:2022 , có thể được đo bằng tỷ lệ giữa quang thông truyền qua và quang thông tới ở các bước sóng của ánh sáng nhìn thấy (380 nm đến 780 nm).

XrGlobalDimmingFrameEndInfoANDROID là một cấu trúc mà ứng dụng có thể liên kết trong XrFrameEndInfo để yêu cầu mức độ làm mờ toàn cục ưu tiên.

Thời gian chạy phải tuân thủ mức độ mờ được yêu cầu nếu mức độ mờ được yêu cầu khác với mức độ mờ hiện tại.

Môi trường thời gian chạy sẽ kiểm soát mức độ làm mờ toàn cục và có thể bỏ qua mức độ làm mờ toàn cục ưu tiên vì lý do an toàn.

Cách sử dụng hợp lệ (Ngầm ẩn)

• Tiện ích XR_ANDROID_global_passthrough_dimming phải được bật trước khi sử dụng XrGlobalDimmingFrameEndInfoANDROID
• type phải là XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc

Hàm xrGetGlobalDimmingLevelANDROID được định nghĩa như sau:

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

Nội dung mô tả về tham số

• session là một tên người dùng XrSession hợp lệ.
• dimmingLevel là con trỏ đến mức độ mờ hiện tại.

dimmingLevel được trả về phải nằm trong khoảng từ 0 đến 1, trong đó 0 nghĩa là hoàn toàn trong suốt và 1 nghĩa là hoàn toàn mờ.

Nếu chưa đặt mức độ mờ, thì thời gian chạy phải đặt mức độ mờ thành 0 khi bật tính năng truyền qua và 1 khi tắt tính năng truyền qua.

Cách sử dụng hợp lệ (Ngầm ẩn)

• Tiện ích XR_ANDROID_global_passthrough_dimming phải được bật trước khi gọi xrGetGlobalDimmingLevelANDROID
• session phải là một tên người dùng XrSession hợp lệ
• dimmingLevel phải là con trỏ đến giá trị float

Mã trả về

Thành công

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Không thành công

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

Sự kiện thay đổi mức độ mờ

Cấu trúc XrEventDataGlobalDimmingLevelChangedANDROID được định nghĩa như sau:

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

Nội dung mô tả về thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
• session là một tên người dùng XrSession hợp lệ.

Ứng dụng có thể truy xuất sự kiện này bằng cách sử dụng xrPollEvent . Sự kiện này sẽ được gửi khi mức độ làm mờ thay đổi do ứng dụng hoặc nút vật lý trên thiết bị.

Sự kiện này sẽ không được gửi khi ứng dụng được lấy làm tâm điểm chuyển sang một ứng dụng khác.

Ứng dụng nên phản hồi sự kiện bằng cách gọi xrGetGlobalDimmingLevelANDROID để nhận mức độ mờ mới và cập nhật XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel cho phù hợp. Việc phản hồi sự kiện đảm bảo thời gian chạy sẽ được báo hiệu khi ứng dụng thay đổi mức độ mờ ưu tiên.

Cách sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_ANDROID_global_passthrough_dimming trước khi sử dụng XrEventDataGlobalDimmingLevelChangedANDROID
• type phải là XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc

Mã ví dụ

Kiểm tra khả năng của hệ thống và liệt kê các mức độ làm mờ toàn cục được hỗ trợ

Mã ví dụ sau đây minh hoạ cách kiểm tra xem tính năng làm mờ toàn cục có được hỗ trợ hay không.

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()));

Sự kiện thay đổi mức độ mờ của cuộc thăm dò ý kiến

Mã ví dụ sau đây minh hoạ cách thăm dò sự kiện thay đổi mức độ mờ.

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()
  }
}

Lệnh mới

• xrEnumerateSupportedGlobalDimmingLevelsANDROID
• xrGetGlobalDimmingLevelANDROID

Cấu trúc mới

• XrEventDataGlobalDimmingLevelChangedANDROID

• Mở rộng XrFrameEndInfo :

  • XrGlobalDimmingFrameEndInfoANDROID

• Mở rộng XrSystemProperties :

  • XrSystemGlobalDimmingPropertiesANDROID

Hằng số enum mới

• XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
• XR_ANDROID_global_passthrough_dimming_SPEC_VERSION

• Mở rộng 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

Vấn đề

Danh sách phiên bản

• Bản sửa đổi 1, ngày 7 tháng 10 năm 2025 (Brian Chen)

  • Nội dung mô tả ban đầu về tiện ích.