Name String

XR_ANDROID_recommended_settings

Loại tiện ích

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

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

455

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-16

Cộng tác viên

Spencer Quin, Google
Jared Finder, Google
Kevin Moule, Google
Nihav Jain, Google
Levana Chen, Google
Alvin Shi, Google
Salar Khan, Google

Tổng quan

Môi trường mặc định của người dùng có thể ở nhiều trạng thái bằng cách kết hợp chế độ hoà trộn và phương thức nhập. Tiện ích này cung cấp các chế độ cài đặt được đề xuất cho người dùng, tương ứng với trạng thái của môi trường mặc định của người dùng trước khi khởi chạy ứng dụng, để đảm bảo quá trình chuyển đổi diễn ra suôn sẻ.

Cấu trúc và Enum

Các bit XrInputModalityFlagsANDROID xác định các phương thức nhập khác nhau mà có thể đang được sử dụng.

typedef XrFlags64 XrInputModalityFlagsANDROID;

Các bit hợp lệ cho XrInputModalityFlagsANDROID được xác định bằng XrInputModalityFlagBitsANDROID , được chỉ định như sau:

// Flag bits for XrInputModalityFlagsANDROID
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_HEAD_BIT_ANDROID = 0x00000001;
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID = 0x00000002;
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_HANDS_BIT_ANDROID = 0x00000004;
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_MOUSE_BIT_ANDROID = 0x00000008;
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID = 0x00000010;

Nội dung mô tả cờ

  • XR_INPUT_MODALITY_HEAD_BIT_ANDROID — Cho biết phương thức nhập đang sử dụng tính năng theo dõi cử động đầu.
  • XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID — Cho biết phương thức nhập đang sử dụng bất kỳ dữ liệu đầu vào nào của bộ điều khiển XR.
  • XR_INPUT_MODALITY_HANDS_BIT_ANDROID — Cho biết phương thức nhập đang sử dụng tính năng theo dõi cử động của tay.
  • XR_INPUT_MODALITY_MOUSE_BIT_ANDROID — Cho biết phương thức nhập đang sử dụng thao tác đầu vào bằng chuột.
  • XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID — Cho biết phương thức nhập kết hợp theo dõi ánh mắt và theo dõi cử động của tay.

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

typedef struct XrRecommendedSettingsANDROID {
    XrStructureType                type;
    void*                          next;
    XrEnvironmentBlendMode         blendMode;
    float                          passthroughOpacity;
    XrInputModalityFlagsANDROID    activeInputModalities;
} XrRecommendedSettingsANDROID;

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.
  • blendMode là một XrEnvironmentBlendMode cho biết chế độ kết hợp của môi trường mặc định ngay trước khi khởi chạy ứng dụng.
  • passthroughOpacity là một float cho biết độ mờ của chế độ truyền qua của môi trường mặc định ngay trước khi khởi chạy ứng dụng. Thời gian chạy phải đặt giá trị này thành (1.0 - dimming_value) cho các thiết bị OST.
  • activeInputModalities là một mặt nạ bit của XrInputModalityFlagsANDROID cho biết các phương thức nhập đang được sử dụng trong môi trường mặc định ngay trước khi khởi chạy ứng dụng.

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

Liệt kê các trạng thái môi trường được hỗ trợ

Ứng dụng có thể xác định chế độ kết hợp và trạng thái phương thức nhập nào được hệ thống hỗ trợ bằng xrEnumerateEnvironmentBlendModes và mở rộng XrSystemProperties bằng cấu trúc XrSystemInputModalityPropertiesANDROID khi gọi xrGetSystemProperties .

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

typedef struct XrSystemInputModalityPropertiesANDROID {
    XrStructureType                type;
    void*                          next;
    XrInputModalityFlagsANDROID    supportedInputModalities;
} XrSystemInputModalityPropertiesANDROID;

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.
  • supportedInputModalities là một hoặc nhiều XrInputModalityFlagsANDROID cho biết các phương thức nhập mà hệ thống hỗ trợ.

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

Sử dụng chế độ cài đặt đề xuất (trạng thái môi trường mặc định trước khi phát hành)

XrResult xrGetRecommendedSettingsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrRecommendedSettingsANDROID*               output);

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

  • instance là một tay điều khiển XrInstance được tạo trước đó bằng xrCreateInstance .
  • systemId là một XrSystemId được tìm nạp trước đó từ xrGetSystem .
  • output là con trỏ trỏ đến cấu trúc XrRecommendedSettingsANDROID được xuất ra cùng với trạng thái môi trường mặc định.

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

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_SYSTEM_INVALID

Mã ví dụ cho chế độ cài đặt đề xuất

Mã ví dụ sau đây minh hoạ cách lấy các phương thức nhập được hỗ trợ, lấy chế độ cài đặt đề xuất và xác nhận rằng chế độ cài đặt được báo cáo được hệ thống hỗ trợ.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // previously initialized from xrGetSystem
XrViewConfigurationType viewType;  // previously initialized to select desired view configuration

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetRecommendedSettingsANDROID xrGetRecommendedSettingsANDROID; // previously initialized

XrSystemInputModalityPropertiesANDROID props = {
  .type = XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID
};
XrSystemProperties base = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &props
};
CHK_XR(xrGetSystemProperties(instance, systemId, &base));

uint32_t blendModeCount = 0;
CHK_XR(
 xrEnumerateEnvironmentBlendModes(instance, systemId, viewType, 0, &blendModeCount, nullptr));
std::vector<XrEnvironmentBlendMode> supportedBlendModes(blendModeCount);
CHK_XR(
  xrEnumerateEnvironmentBlendModes(
    instance, systemId, viewType, blendModeCount, &blendModeCount, supportedBlendModes.data()));

XrRecommendedSettingsANDROID output = {
  .type = XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
};

XrResult result = xrGetRecommendedSettingsANDROID(instance, systemId, &output);

if (result == XR_SUCCESS) {
  // We now know the current state of the default environment as recommended settings

  bool correctBlendMode = false;
  for(XrEnvironmentBlendMode blendMode : supportedBlendModes) {
    if (blendMode == output.blendMode) {
      correctBlendMode = true;
      break;
    }
  }
  assert(correctBlendMode);
  assert((~props.supportedInputModalities & output.activeInputModalities) == 0);
}

Lệnh mới

Cấu trúc mới

Enum mới

Mặt nạ bit mới

Hằng số enum mới

  • XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAME
  • XR_ANDROID_recommended_settings_SPEC_VERSION

  • Mở rộng XrStructureType :

    • XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
    • XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID

Vấn đề

Nhật ký phiên bản

  • Bản sửa đổi 3, ngày 16 tháng 3 năm 2026 (Salar Khan)

    • Được chuyển sang chế độ công khai, đặt các bit cờ cho phương thức nhập và đổi tên tiện ích thành XR_ANDROID_recommended_settings .

  • Bản sửa đổi 2, ngày 28 tháng 3 năm 2025 (Salar Khan)

    • Thay đổi thành ANDROIDX và thêm passthroughOpacity.

  • Bản sửa đổi 1, 18/2/2025 (Salar Khan)

    • Phiên bản đầu tiên.