Name String

XR_ANDROID_recommended_settings

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

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

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

455

การแก้ไข

1

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

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

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

OpenXR 1.0

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

2026-03-16

ผู้เขียน

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

ภาพรวม

สภาพแวดล้อมเริ่มต้นของผู้ใช้สามารถอยู่ในสถานะต่างๆ ได้โดยใช้โหมดผสมผสานและรูปแบบการป้อนข้อมูลร่วมกัน ส่วนขยายนี้จะให้การตั้งค่าที่แนะนำสำหรับผู้ใช้ ซึ่งสอดคล้องกับสถานะของสภาพแวดล้อมเริ่มต้นของผู้ใช้ก่อนเปิดแอปพลิเคชัน เพื่อให้การเปลี่ยนผ่านเป็นไปอย่างราบรื่น

โครงสร้างและ Enum

บิต XrInputModalityFlagsANDROID จะระบุรูปแบบการป้อนข้อมูลต่างๆ ที่อาจมีการใช้งานอยู่

typedef XrFlags64 XrInputModalityFlagsANDROID;

บิตที่ถูกต้องสำหรับ XrInputModalityFlagsANDROID กำหนดโดย XrInputModalityFlagBitsANDROID ซึ่งระบุไว้ดังนี้

// 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;

คำอธิบายแฟล็ก

  • XR_INPUT_MODALITY_HEAD_BIT_ANDROID — ระบุรูปแบบการป้อนข้อมูลที่ใช้การติดตามการเคลื่อนไหวของศีรษะ
  • XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID — ระบุรูปแบบอินพุตที่ใช้อินพุตจากตัวควบคุม XR
  • XR_INPUT_MODALITY_HANDS_BIT_ANDROID — ระบุรูปแบบการป้อนข้อมูลที่ใช้การติดตามการเคลื่อนไหวของมือ
  • XR_INPUT_MODALITY_MOUSE_BIT_ANDROID — ระบุรูปแบบอินพุตที่ใช้อินพุตจากเมาส์
  • XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID — ระบุรูปแบบการป้อนข้อมูลที่รวมการติดตามดวงตาและการติดตามการเคลื่อนไหวของมือเข้าด้วยกัน

โครงสร้าง XrRecommendedSettingsANDROID มีคำจำกัดความดังนี้

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

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • blendMode คือ XrEnvironmentBlendMode ที่ระบุโหมดการผสมผสานของสภาพแวดล้อมเริ่มต้นก่อนเปิดแอปพลิเคชัน
  • passthroughOpacity คือ float ที่ระบุความทึบแสงแบบพาสทรูของสภาพแวดล้อมเริ่มต้นก่อนเปิดแอปพลิเคชัน รันไทม์ต้องตั้งค่านี้เป็น (1.0 - dimming_value) สำหรับอุปกรณ์ OST
  • activeInputModalities คือบิตมาสก์ของ XrInputModalityFlagsANDROID ที่ระบุรูปแบบอินพุตที่ใช้ภายในสภาพแวดล้อมเริ่มต้นก่อนเปิดแอปพลิเคชัน

การใช้งานที่ถูกต้อง (โดยนัย)

การแจกแจงสถานะสภาพแวดล้อมที่รองรับ

แอปพลิเคชันสามารถระบุโหมดการผสมและสถานะรูปแบบการป้อนข้อมูลที่ระบบรองรับได้ด้วย xrEnumerateEnvironmentBlendModes และขยาย XrSystemProperties ด้วยโครงสร้าง XrSystemInputModalityPropertiesANDROID เมื่อเรียกใช้ xrGetSystemProperties

โครงสร้าง XrSystemInputModalityPropertiesANDROID มีคำจำกัดความดังนี้

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

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • supportedInputModalities คือ XrInputModalityFlagsANDROID อย่างน้อย 1 รายการที่ระบุรูปแบบอินพุตที่ระบบรองรับ

การใช้งานที่ถูกต้อง (โดยนัย)

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

คำอธิบายพารามิเตอร์

  • instance คือแฮนเดิล XrInstance ที่สร้างไว้ก่อนหน้านี้ด้วย xrCreateInstance
  • systemId คือ XrSystemId ที่ดึงข้อมูลมาก่อนหน้านี้จาก xrGetSystem
  • output เป็นตัวชี้ไปยังโครงสร้าง XrRecommendedSettingsANDROID ซึ่งแสดงผลพร้อมกับสถานะสภาพแวดล้อมเริ่มต้น

การใช้งานที่ถูกต้อง (โดยนัย)

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_recommended_settings ก่อนเรียกใช้ xrGetRecommendedSettingsANDROID
  • instance ต้องเป็นแฮนเดิล XrInstance ที่ถูกต้อง
  • output ต้องเป็นตัวชี้ไปยังโครงสร้าง XrRecommendedSettingsANDROID

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

สำเร็จ

  • XR_SUCCESS

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SYSTEM_INVALID

โค้ดตัวอย่างต่อไปนี้แสดงวิธีรับรูปแบบอินพุตที่รองรับ รับการตั้งค่าที่แนะนำ และยืนยันว่าระบบรองรับการตั้งค่าที่รายงาน

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

คำสั่งใหม่

โครงสร้างใหม่

Enum ใหม่

บิตมาสก์ใหม่

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

  • XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAME
  • XR_ANDROID_recommended_settings_SPEC_VERSION
  • การขยาย XrStructureType :

    • XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
    • XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID

ปัญหา

ประวัติเวอร์ชัน

  • Revision 3, 2026-03-16 (Salar Khan)

    • เลื่อนเป็นสาธารณะ สร้างบิตแฟล็กรูปแบบอินพุต และเปลี่ยนชื่อส่วนขยายเป็น XR_ANDROID_recommended_settings
  • ฉบับแก้ไขครั้งที่ 2, 28-03-2025 (Salar Khan)

    • เปลี่ยนเป็น ANDROIDX และรวม passthroughOpacity
  • การแก้ไขครั้งที่ 1, 18-02-2025 (Salar Khan)

    • เวอร์ชันเริ่มต้น