XR_ANDROID_recommended_settings
Name String
XR_ANDROID_recommended_settings
ประเภทส่วนขยาย
ส่วนขยายอินสแตนซ์
หมายเลขต่อที่ลงทะเบียนไว้
455
การแก้ไข
1
สถานะการให้สัตยาบัน
ไม่ได้รับการให้สัตยาบัน
ทรัพยากร Dependency ของส่วนขยายและเวอร์ชัน
วันที่แก้ไขล่าสุด
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— ระบุรูปแบบอินพุตที่ใช้อินพุตจากตัวควบคุม XRXR_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) สำหรับอุปกรณ์ OSTactiveInputModalitiesคือบิตมาสก์ของ XrInputModalityFlagsANDROID ที่ระบุรูปแบบอินพุตที่ใช้ภายในสภาพแวดล้อมเริ่มต้นก่อนเปิดแอปพลิเคชัน
การใช้งานที่ถูกต้อง (โดยนัย)
- ต้องเปิดใช้ส่วนขยาย
XR_ANDROID_recommended_settingsก่อนใช้ XrRecommendedSettingsANDROID -
typeต้องเป็นXR_TYPE_RECOMMENDED_SETTINGS_ANDROID -
nextต้องเป็นNULLหรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง -
blendModeต้องเป็นค่า XrEnvironmentBlendMode ที่ถูกต้อง -
activeInputModalitiesต้องเป็นชุดค่าผสมที่ถูกต้องของค่า XrInputModalityFlagBitsANDROID -
activeInputModalitiesต้องไม่ใช่0
การแจกแจงสถานะสภาพแวดล้อมที่รองรับ
แอปพลิเคชันสามารถระบุโหมดการผสมและสถานะรูปแบบการป้อนข้อมูลที่ระบบรองรับได้ด้วย xrEnumerateEnvironmentBlendModes และขยาย XrSystemProperties ด้วยโครงสร้าง XrSystemInputModalityPropertiesANDROID เมื่อเรียกใช้ xrGetSystemProperties
โครงสร้าง XrSystemInputModalityPropertiesANDROID มีคำจำกัดความดังนี้
typedef struct XrSystemInputModalityPropertiesANDROID {
XrStructureType type;
void* next;
XrInputModalityFlagsANDROID supportedInputModalities;
} XrSystemInputModalityPropertiesANDROID;
คำอธิบายสมาชิก
typeคือ XrStructureType ของโครงสร้างนี้nextคือNULLหรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้supportedInputModalitiesคือ XrInputModalityFlagsANDROID อย่างน้อย 1 รายการที่ระบุรูปแบบอินพุตที่ระบบรองรับ
การใช้งานที่ถูกต้อง (โดยนัย)
- ต้องเปิดใช้ส่วนขยาย
XR_ANDROID_recommended_settingsก่อนใช้ XrSystemInputModalityPropertiesANDROID -
typeต้องเป็นXR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID -
nextต้องเป็นNULLหรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
ดูการตั้งค่าที่แนะนำ (สถานะสภาพแวดล้อมเริ่มต้นก่อนเปิดตัว)
XrResult xrGetRecommendedSettingsANDROID(
XrInstance instance,
XrSystemId systemId,
XrRecommendedSettingsANDROID* output);
คำอธิบายพารามิเตอร์
instanceคือแฮนเดิล XrInstance ที่สร้างไว้ก่อนหน้านี้ด้วย xrCreateInstancesystemIdคือXrSystemIdที่ดึงข้อมูลมาก่อนหน้านี้จาก xrGetSystemoutputเป็นตัวชี้ไปยังโครงสร้าง XrRecommendedSettingsANDROID ซึ่งแสดงผลพร้อมกับสถานะสภาพแวดล้อมเริ่มต้น
การใช้งานที่ถูกต้อง (โดยนัย)
- ต้องเปิดใช้ส่วนขยาย
XR_ANDROID_recommended_settingsก่อนเรียกใช้ xrGetRecommendedSettingsANDROID -
instanceต้องเป็นแฮนเดิล XrInstance ที่ถูกต้อง -
outputต้องเป็นตัวชี้ไปยังโครงสร้าง XrRecommendedSettingsANDROID
รหัสการคืนสินค้า
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_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_NAMEXR_ANDROID_recommended_settings_SPEC_VERSIONการขยาย XrStructureType :
XR_TYPE_RECOMMENDED_SETTINGS_ANDROIDXR_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)
- เวอร์ชันเริ่มต้น