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

สตริงชื่อ

XR_ANDROID_light_estimation

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

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

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

701

การแก้ไข

1

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

OpenXR 1.0

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

2025-01-17

สถานะ IP

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

ผู้เขียน

Jared Finder จาก Google

Cairn Overturf จาก Google

Spencer Quin จาก Google

Levana Chen จาก Google

Nihav Jain จาก Google

Salar Khan จาก Google

Scott Chung จาก Google

ภาพรวม

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

หมายเหตุ:

รันไทม์จะสร้างข้อมูลการประมาณแสงและแชร์กับแอปพลิเคชันโดยใช้ XrLightEstimatorANDROID

ข้อควรระวัง:

สิทธิ์

แอปพลิเคชัน Android ต้องมีสิทธิ์ android.permission.SCENE_UNDERSTANDING ที่แสดงในไฟล์ Manifest เนื่องจากส่วนขยายนี้จะแสดงข้อมูลการจัดแสงเกี่ยวกับสภาพแวดล้อม สิทธิ์ android.permission.SCENE_UNDERSTANDING ถือเป็นสิทธิ์ที่อันตราย แอปพลิเคชันต้อง ขอสิทธิ์ในรันไทม์เพื่อใช้ฟังก์ชันต่อไปนี้

• xrCreateLightEstimatorANDROID

(ระดับการป้องกัน: อันตราย)

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

แอปพลิเคชันสามารถตรวจสอบว่าระบบรองรับการประเมินแสงหรือไม่โดยเชื่อมโยงโครงสร้าง 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, XrEnvironmentLightingCubemapANDROID และ XrDirectionalLightANDROID
• state คือ XrLightEstimateStateANDROID ที่แสดงสถานะของการประมาณแสง
• lastUpdatedTime คือ XrTime ที่แสดงเวลาที่คำนวณค่าประมาณครั้งล่าสุด

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

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

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

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

typedef struct XrEnvironmentLightingCubemapANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    const float*                   cubemapRightImage;
    const float*                   cubemapLeftImage;
    const float*                   cubemapTopImage;
    const float*                   cubemapBottomImage;
    const float*                   cubemapFrontImage;
    const float*                   cubemapBackImage;
    uint32_t                       resolution;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrEnvironmentLightingCubemapANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง โครงสร้างที่ใช้ได้ ได้แก่ XrSphericalHarmonicsANDROID, XrAmbientLightANDROID และ XrDirectionalLightANDROID
• state คือ XrLightEstimateStateANDROID ที่แสดงสถานะของการประมาณแสง
• cubemapRightImage คือ float* ที่แสดงบัฟเฟอร์ R32G32B32_SFLOAT ของด้านขวาของคิวบ์แมป โปรดทราบว่านี่คือ HDR ดังนั้นค่าของประเภท Float จึงมีค่ามากกว่า 1.0 ได้
• cubemapLeftImage คือ float* ที่แสดงบัฟเฟอร์ R32G32B32_SFLOAT ของด้านซ้ายของคิวบ์แมป โปรดทราบว่านี่คือ HDR ดังนั้นค่าตัวเลขทศนิยมจึงมีค่ามากกว่า 1.0 ได้
• cubemapTopImage คือ float* ที่แสดงบัฟเฟอร์ R32G32B32_SFLOAT ของด้านข้างบนของคิวบ์แมป โปรดทราบว่านี่คือ HDR ดังนั้นค่าตัวเลขทศนิยมจึงมีค่ามากกว่า 1.0 ได้
• cubemapBottomImage คือ float* ที่แสดงบัฟเฟอร์ R32G32B32_SFLOAT ของด้านด้านล่างของคิวบ์แมป โปรดทราบว่านี่คือ HDR ดังนั้นค่าของประเภท Float จึงมีค่ามากกว่า 1.0 ได้
• cubemapFrontImage คือ float* ที่แสดงบัฟเฟอร์ R32G32B32_SFLOAT ของด้านด้านหน้าของคิวบ์แมป โปรดทราบว่านี่คือ HDR ดังนั้นค่าตัวเลขทศนิยมจึงมีค่ามากกว่า 1.0 ได้
• resolution คือ uint32_t ที่แสดงถึงความกว้างและความสูงของรูปภาพด้านข้างแต่ละด้านของคิวบ์แมป โปรดทราบว่านี่คือ HDR ดังนั้นค่าตัวเลขทศนิยมจึงมีค่ามากกว่า 1.0 ได้
• rotation คือ XrQuaternionf ที่แสดงการหมุนของคิวบ์แมป
• centerExposureTime คือ XrTime ที่แสดงเวลาที่จับภาพคิวบ์แมป มีประโยชน์สำหรับการหาค่าระหว่างภาพลูกบาศก์

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_light_estimation ก่อนใช้ XrEnvironmentLightingCubemapANDROID
• type ต้องเป็น XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• state ต้องเป็นค่า XrLightEstimateStateANDROID ที่ถูกต้อง
• cubemapRightImage ต้องเป็นพอยน์เตอร์ไปยังค่า Float ที่ถูกต้อง
• cubemapLeftImage ต้องเป็นพอยน์เตอร์ไปยังค่า Float ที่ถูกต้อง
• cubemapTopImage ต้องเป็นพอยน์เตอร์ไปยังค่า Float ที่ถูกต้อง
• cubemapBottomImage ต้องเป็นพอยน์เตอร์ไปยังค่า Float ที่ถูกต้อง
• cubemapFrontImage ต้องเป็นพอยน์เตอร์ไปยังค่า Float ที่ถูกต้อง
• cubemapBackImage ต้องเป็นพอยน์เตอร์ไปยังค่า Float ที่ถูกต้อง

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

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

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง โครงสร้างที่ใช้ได้มีดังนี้ XrSphericalHarmonicsANDROID, XrEnvironmentLightingCubemapANDROID และ 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, XrEnvironmentLightingCubemapANDROID และ 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;

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

Enum	คำอธิบาย
XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID	สัมประสิทธิ์ฮาร์โมนิกทรงกลมแสดงฟังก์ชันการแผ่รังสีของแสงโดยรอบ โดยไม่รวมการมีส่วนร่วมจากแสงหลัก
XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID	สัมประสิทธิ์ฮาร์โมนิกทรงกลมแสดงฟังก์ชันการแผ่รังสีของแสงแวดล้อม รวมถึงการมีส่วนร่วมจากแสงหลัก

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

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

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

Enum	คำอธิบาย
XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID	ค่าแสงโดยประมาณถูกต้อง
XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID	ค่าประมาณของแสงไม่ถูกต้อง

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

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

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


XrEnvironmentLightingCubemapANDROID lightingCubemap {
    .type = XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID,
    .next = &ambientLight,
}

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

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight,
  // lightingCubemap, 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
• XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID

Enum ใหม่

• XrSphericalHarmonicsKindANDROID
• XrLightEstimateStateANDROID

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

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

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

• xrCreateLightEstimatorANDROID
• xrDestroyLightEstimatorANDROID
• xrGetLightEstimateANDROID

ปัญหา

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

• แก้ไขครั้งที่ 2, 17-01-2025 (Salar Khan)
  • เพิ่มการรองรับคิวบ์แมปสำหรับการจัดแสงสภาพแวดล้อม
• การแก้ไข 1, 16-09-2024 (Cairn Overturf)
  • คำอธิบายส่วนขยายเริ่มต้น