ส่วนขยาย XR_ANDROID_light_estimation ของ OpenXR

สตริงชื่อ

XR_ANDROID_light_estimation

ประเภทชิ้นงาน

การขยายเวลาอินสแตนซ์

หมายเลขต่อที่จดทะเบียน

701

การแก้ไข

1

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

OpenXR 1.0

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

2024-09-18

สถานะ IP

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

ผู้เขียน

Jared Finder จาก Google

Cairn Overturf จาก Google

Spencer Quin จาก Google

Levana Chen จาก Google

Nihav Jain จาก Google

ภาพรวม

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

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

แอปพลิเคชันสามารถตรวจสอบว่าระบบรองรับการประเมินแสงหรือไม่โดยเชื่อมโยงโครงสร้าง XrSystemLightEstimationPropertiesANDROID กับ XrSystemProperties เมื่อเรียกใช้ xrGetSystemProperties

typedef struct XrSystemLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsLightEstimation;
} XrSystemLightEstimationPropertiesANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• supportsLightEstimation คือ XrBool32 ซึ่งระบุว่าระบบปัจจุบันรองรับการประเมินแสงหรือไม่

แอปพลิเคชันสามารถตรวจสอบว่าระบบรองรับการประเมินแสงหรือไม่โดยการขยาย XrSystemProperties ด้วยโครงสร้าง XrSystemLightEstimationPropertiesANDROID เมื่อเรียกใช้ xrGetSystemProperties

หากระบบไม่รองรับการประเมินแสง ระบบจะแสดงผล XR_FALSE สำหรับ supportsLightEstimation และ XR_ERROR_FEATURE_UNSUPPORTED จาก xrCreateLightEstimatorANDROID

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_light_estimation ก่อนใช้ XrSystemLightEstimationPropertiesANDROID
• type ต้องเป็น XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง

สร้างแฮนเดิลเครื่องมือประเมินแสง

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

แฮนเดิล XrLightEstimatorANDROID แสดงถึงเครื่องมือประเมินแสง แฮนเดิลนี้สามารถใช้เพื่อเข้าถึงข้อมูลการประมาณแสงโดยใช้ฟังก์ชันอื่นๆ ในส่วนขยายนี้ได้

ฟังก์ชัน xrCreateLightEstimatorANDROID มีคำจำกัดความดังนี้

XrResult xrCreateLightEstimatorANDROID(
    XrSession                                   session,
    XrLightEstimatorCreateInfoANDROID*          createInfo,
    XrLightEstimatorANDROID*                    outHandle);

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

• session คือ XrSession ที่สร้างเครื่องมือประเมินแสง
• createInfo เป็นพอยน์เตอร์ไปยังโครงสร้าง XrLightEstimatorCreateInfoANDROID ที่มีพารามิเตอร์ที่จะใช้สร้างเครื่องมือประเมินแสง
• outHandle คือพอยน์เตอร์ไปยังแฮนเดิลที่แสดงXrLightEstimatorANDROID ที่สร้างขึ้น

แอปพลิเคชันสามารถใช้ฟังก์ชัน xrCreateLightEstimatorANDROID เพื่อสร้างเครื่องมือประเมินแสง

• xrCreateLightEstimatorANDROID จะแสดงผลเป็น XR_ERROR_FEATURE_UNSUPPORTED หากระบบไม่รองรับการประเมินแสง
• xrCreateLightEstimatorANDROID จะแสดงXR_ERROR_PERMISSION_INSUFFICIENTหากแอปพลิเคชันที่เรียกใช้ไม่ได้รับสิทธิ์ที่จําเป็น

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

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_light_estimation ก่อนเรียกใช้ xrCreateLightEstimatorANDROID
• session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
• createInfo ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrLightEstimatorCreateInfoANDROID
• outHandle ต้องเป็นพอยน์เตอร์ไปยังแฮนเดิล XrLightEstimatorANDROID

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

สำเร็จ

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ไม่สำเร็จ

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_LIMIT_REACHED

โครงสร้าง XrLightEstimatorCreateInfoANDROID อธิบายข้อมูลในการสร้างตัวแฮนเดิล XrLightEstimatorANDROID

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrLightEstimatorCreateInfoANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_light_estimation ก่อนใช้ XrLightEstimatorCreateInfoANDROID
• type ต้องเป็น XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง

ฟังก์ชัน xrDestroyLightEstimatorANDROID จะปล่อยestimatorและทรัพยากรที่เกี่ยวข้อง

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

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

• estimator คือ XrLightEstimatorANDROID ที่สร้างขึ้นก่อนหน้านี้โดย xrCreateLightEstimatorANDROID

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_light_estimation ก่อนเรียกใช้ xrDestroyLightEstimatorANDROID
• estimator ต้องเป็นแฮนเดิล XrLightEstimatorANDROID ที่ถูกต้อง

ความปลอดภัยของชุดข้อความ

• การเข้าถึง estimator และตัวแฮนเดิลย่อยต้องได้รับการซิงค์จากภายนอก

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

สำเร็จ

• XR_SUCCESS

ไม่สำเร็จ

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

เข้าถึงข้อมูลการประมาณแสง

ฟังก์ชัน xrGetLightEstimateANDROID มีคำจำกัดความดังนี้

XrResult xrGetLightEstimateANDROID(
    XrLightEstimatorANDROID                     estimator,
    const XrLightEstimateGetInfoANDROID*        input,
    XrLightEstimateANDROID*                     output);

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

• estimator: แฮนเดิลของ XrLightEstimatorANDROID ที่สร้างขึ้นก่อนหน้านี้ด้วย xrCreateLightEstimatorANDROID
• input: ตัวชี้ไปยังโครงสร้าง XrLightEstimateGetInfoANDROID
• output: ตัวชี้ไปยังโครงสร้าง XrLightEstimateANDROID

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_light_estimation ก่อนเรียกใช้ xrGetLightEstimateANDROID
• estimator ต้องเป็นแฮนเดิล XrLightEstimatorANDROID ที่ถูกต้อง
• input ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrLightEstimateGetInfoANDROID ที่ถูกต้อง
• output ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrLightEstimateANDROID

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

สำเร็จ

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ไม่สำเร็จ

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_TIME_INVALID

XrLightEstimateGetInfoANDROID อธิบายข้อมูลที่จําเป็นสําหรับรับข้อมูลการประมาณแสง

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            space;
    XrTime             time;
} XrLightEstimateGetInfoANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• space คือ XrSpace ที่กําหนดพื้นที่อ้างอิงซึ่งแสดงทิศทางของแสงที่แสดงผลและฮาร์โมนิกทรงกลม
• time คือ XrTime ที่อธิบายเวลาที่แอปพลิเคชันต้องการค้นหาค่าประมาณของแสง

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_light_estimation ก่อนใช้ XrLightEstimateGetInfoANDROID
• type ต้องเป็น XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• space ต้องเป็นแฮนเดิล XrSpace ที่ถูกต้อง

โครงสร้าง XrLightEstimateANDROID มีข้อมูลการประมาณแสง

typedef struct XrLightEstimateANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrTime                         lastUpdatedTime;
} XrLightEstimateANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง โครงสร้างที่ใช้ได้ ได้แก่ XrAmbientLightANDROID, XrSphericalHarmonicsANDROID และ XrDirectionalLightANDROID
• state คือ XrLightEstimateStateANDROID ที่แสดงสถานะของการประมาณแสง
• lastUpdatedTime คือ XrTime ที่แสดงเวลาที่คำนวณค่าประมาณครั้งล่าสุด

หากต้องการรับข้อมูลการประมาณแสงสำหรับแสงโดยรอบ ฮาร์โมนิกทรงกลม และแสงทิศทางหลัก แอปพลิเคชันสามารถต่ออินสแตนซ์ของโครงสร้างต่อไปนี้ XrAmbientLightANDROID, XrSphericalHarmonicsANDROID และ XrDirectionalLightANDROID ตามลำดับไปยัง XrLightEstimateANDROID::next

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_light_estimation ก่อนใช้ XrLightEstimateANDROID
• type ต้องเป็น XR_TYPE_LIGHT_ESTIMATE_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง ดูข้อมูลเพิ่มเติมได้ที่ XrAmbientLightANDROID, XrDirectionalLightANDROID, XrSphericalHarmonicsANDROID
• state ต้องเป็นค่า XrLightEstimateStateANDROID ที่ถูกต้อง

โครงสร้าง XrAmbientLightANDROID มีข้อมูลการประมาณแสงเกี่ยวกับแสงแวดล้อมในฉาก

typedef struct XrAmbientLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     colorCorrection;
} XrAmbientLightANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง โครงสร้างที่ใช้ได้มีดังนี้ XrSphericalHarmonicsANDROID และ XrDirectionalLightANDROID
• state คือ XrLightEstimateStateANDROID ที่แสดงสถานะของการประมาณแสง
• intensity คือ XrVector3 ที่แสดงถึงระดับความเข้มของแสงแวดล้อม องค์ประกอบแต่ละอย่างของเวกเตอร์จะสอดคล้องกับช่องสีแดง เขียว และน้ำเงิน
• colorCorrection คือ XrVector3 ที่มีค่าในพื้นที่แกมมา คูณสีของภาพที่ได้รับการแก้ไขแกมมาด้วยค่าเหล่านี้

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_light_estimation ก่อนใช้ XrAmbientLightANDROID
• type ต้องเป็น XR_TYPE_AMBIENT_LIGHT_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• state ต้องเป็นค่า XrLightEstimateStateANDROID ที่ถูกต้อง

โครงสร้าง XrSphericalHarmonicsANDROID มี SphericalHarmonics ที่แสดงถึงการจัดแสงของฉาก

typedef struct XrSphericalHarmonicsANDROID {
    XrStructureType                    type;
    void*                              next;
    XrLightEstimateStateANDROID        state;
    XrSphericalHarmonicsKindANDROID    kind;
    float                              coefficients[9][3];
} XrSphericalHarmonicsANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง โครงสร้างที่ใช้ได้คือ XrAmbientLightANDROID และ XrDirectionalLightANDROID
• state คือ XrLightEstimateStateANDROID ที่แสดงสถานะของการประมาณแสง
• kind คือ XrSphericalHarmonicsKindANDROID ที่แอปพลิเคชันขอ
• coefficients คืออาร์เรย์ float แบบ 2 มิติที่มีมิติข้อมูล 9 แถวและ 3 คอลัมน์ 3 คอลัมน์ที่สอดคล้องกับช่องสี ได้แก่ สีแดง เขียว และน้ำเงิน แต่ละช่องจะมีสัมประสิทธิ์ฮาร์โมนิกทรงกลม 9 รายการ

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_light_estimation ก่อนใช้ XrSphericalHarmonicsANDROID
• type ต้องเป็น XR_TYPE_SPHERICAL_HARMONICS_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• state ต้องเป็นค่า XrLightEstimateStateANDROID ที่ถูกต้อง
• kind ต้องเป็นค่า XrSphericalHarmonicsKindANDROID ที่ถูกต้อง

โครงสร้าง XrDirectionalLightANDROID มีข้อมูลการประมาณแสง

typedef struct XrDirectionalLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     direction;
} XrDirectionalLightANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง โครงสร้างที่ใช้ได้ ได้แก่ XrAmbientLightANDROID, XrSphericalHarmonicsANDROID และ XrDirectionalLightANDROID
• state คือ XrLightEstimateStateANDROID ที่แสดงสถานะของการประมาณแสง
• intensity คือ XrVector3 ที่แสดงถึงระดับความเข้มของแสงทิศทาง องค์ประกอบแต่ละอย่างของเวกเตอร์จะสอดคล้องกับช่องสีแดง เขียว และน้ำเงิน
• direction คือ XrVector3 ที่แสดงทิศทางของแสง

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_light_estimation ก่อนใช้ XrDirectionalLightANDROID
• type ต้องเป็น XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• state ต้องเป็นค่า XrLightEstimateStateANDROID ที่ถูกต้อง

การแจกแจง XrSphericalHarmonicsKindANDROID จะระบุประเภทของฟังก์ชันเชิงกลมที่รันไทม์ต้องการ

typedef enum XrSphericalHarmonicsKindANDROID {
    XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID = 0,
    XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID = 1
} XrSphericalHarmonicsKindANDROID;

ซึ่งแต่ละค่ามีความหมายดังนี้

การแจกแจง XrLightEstimateStateANDROID จะระบุให้รันไทม์ทราบว่าแอปพลิเคชันขอฮาร์โมนิกทรงกลมประเภทใด

typedef enum XrLightEstimateStateANDROID {
    XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID = 0,
    XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID = 1
} XrLightEstimateStateANDROID;

ซึ่งแต่ละค่ามีความหมายดังนี้

ตัวอย่างโค้ดสําหรับการประมาณแสง

โค้ดตัวอย่างต่อไปนี้แสดงวิธีรับปริมาณการประมาณแสงที่เป็นไปได้ทั้งหมดจากรันไทม์

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.

XrLightEstimatorANDROID estimator;
XrLightEstimatorCreateInfoANDROID createInfo = {
    .type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID};
CHK_XR(xrCreateLightEstimatorANDROID(session, &createInfo, &estimator));

// Every frame
XrTime updateTime;  // Time used for the current frame's simulation update.

XrLightEstimateGetInfoANDROID info = {
    .type = XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID,
    .space = appSpace,
    .time = updateTime,
};

XrDirectionalLightANDROID directionalLight = {
    .type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
};

XrSphericalHarmonicsANDROID totalSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID,
    .next = &directionalLight,
};

XrSphericalHarmonicsANDROID ambientSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID,
    .next = &totalSh,
};

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &ambientSh,
};

XrLightEstimateANDROID estimate = {
    .type = XR_TYPE_LIGHT_ESTIMATE_ANDROID,
    .next = &ambientLight,
};

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight if each
  // struct has a valid state field
}

// When you want to disable light estimation
CHK_XR(xrDestroyLightEstimatorANDROID(estimator));

ประเภทออบเจ็กต์ใหม่

• XrLightEstimator

เพิ่มรายการต่อไปนี้ในคําจํากัดความของ XrObjectType

• XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

เพิ่มรายการต่อไปนี้ในอนุกรม XrStructureType

• XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
• XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
• XR_TYPE_LIGHT_ESTIMATE_ANDROID
• XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
• XR_TYPE_SPHERICAL_HARMONICS_ANDROID
• XR_TYPE_AMBIENT_LIGHT_ANDROID

Enum ใหม่

• XrSphericalHarmonicsKindANDROID
• XrLightEstimateStateANDROID

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

• XrLightEstimatorCreateInfoANDROID
• XrLightEstimateGetInfoANDROID
• XrLightEstimateANDROID
• XrDirectionalLightANDROID
• XrSphericalHarmonicsANDROID
• XrAmbientLightANDROID
• XrSystemLightEstimationPropertiesANDROID

ฟังก์ชันใหม่

• xrCreateLightEstimatorANDROID
• xrDestroyLightEstimatorANDROID
• xrGetLightEstimateANDROID

ปัญหา

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

• การแก้ไข 1, 16-09-2024 (Cairn Overturf)
  • คำอธิบายส่วนขยายเริ่มต้น