สตริงชื่อ
XR_ANDROID_light_estimation
ประเภทชิ้นงาน
การขยายเวลาอินสแตนซ์
หมายเลขต่อที่จดทะเบียน
701
การแก้ไข
1
การพึ่งพาส่วนขยายและเวอร์ชัน
วันที่แก้ไขล่าสุด
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
ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrLightEstimatorCreateInfoANDROIDoutHandle
ต้องเป็นพอยน์เตอร์ไปยังแฮนเดิล 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
: ตัวชี้ไปยังโครงสร้าง XrLightEstimateGetInfoANDROIDoutput
: ตัวชี้ไปยังโครงสร้าง 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 และ XrDirectionalLightANDROIDstate
คือ XrLightEstimateStateANDROID ที่แสดงสถานะของการประมาณแสงlastUpdatedTime
คือXrTime
ที่แสดงเวลาที่คำนวณค่าประมาณครั้งล่าสุด
หากต้องการรับข้อมูลการประมาณแสงสำหรับแสงโดยรอบ ฮาร์โมนิกทรงกลม และแสงทิศทางหลัก แอปพลิเคชันสามารถต่ออินสแตนซ์ของโครงสร้างต่อไปนี้ XrAmbientLightANDROID, XrSphericalHarmonicsANDROID และ XrDirectionalLightANDROID ตามลำดับไปยัง XrLightEstimateANDROID::next
การใช้งานที่ถูกต้อง (โดยนัย)
- ต้องเปิดใช้ส่วนขยาย
XR_ANDROID_light_estimation
ก่อนใช้ XrLightEstimateANDROID type
ต้องเป็นXR_TYPE_LIGHT_ESTIMATE_ANDROID
next
ต้องเป็นNULL
หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง ดูข้อมูลเพิ่มเติมได้ที่ XrAmbientLightANDROID, XrDirectionalLightANDROID, XrSphericalHarmonicsANDROIDstate
ต้องเป็นค่า XrLightEstimateStateANDROID ที่ถูกต้อง
โครงสร้าง XrAmbientLightANDROID มีข้อมูลการประมาณแสงเกี่ยวกับแสงแวดล้อมในฉาก
typedef struct XrAmbientLightANDROID {
XrStructureType type;
void* next;
XrLightEstimateStateANDROID state;
XrVector3f intensity;
XrVector3f colorCorrection;
} XrAmbientLightANDROID;
คำอธิบายสมาชิก
type
คือ XrStructureType ของโครงสร้างนี้next
คือNULL
หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง โครงสร้างที่ใช้ได้มีดังนี้ XrSphericalHarmonicsANDROID และ XrDirectionalLightANDROIDstate
คือ 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 และ XrDirectionalLightANDROIDstate
คือ 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 และ XrDirectionalLightANDROIDstate
คือ 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 |
คำอธิบาย |
|
สัมประสิทธิ์ฮาร์โมนิกทรงกลมแสดงฟังก์ชันการแผ่รังสีของแสงแวดล้อม โดยไม่รวมการมีส่วนร่วมจากแสงหลัก |
|
สัมประสิทธิ์ฮาร์โมนิกทรงกลมแสดงฟังก์ชันการแผ่รังสีของแสงแวดล้อม รวมถึงการมีส่วนร่วมจากแสงหลัก |
การแจกแจง XrLightEstimateStateANDROID จะระบุให้รันไทม์ทราบว่าแอปพลิเคชันขอฮาร์โมนิกทรงกลมประเภทใด
typedef enum XrLightEstimateStateANDROID {
XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID = 0,
XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID = 1
} XrLightEstimateStateANDROID;
ซึ่งแต่ละค่ามีความหมายดังนี้
Enum |
คำอธิบาย |
|
ค่าแสงโดยประมาณถูกต้อง |
|
ค่าประมาณของแสงไม่ถูกต้อง |
ตัวอย่างโค้ดสําหรับการประมาณแสง
โค้ดตัวอย่างต่อไปนี้แสดงวิธีรับปริมาณการประมาณแสงที่เป็นไปได้ทั้งหมดจากรันไทม์
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 ใหม่
โครงสร้างใหม่
- XrLightEstimatorCreateInfoANDROID
- XrLightEstimateGetInfoANDROID
- XrLightEstimateANDROID
- XrDirectionalLightANDROID
- XrSphericalHarmonicsANDROID
- XrAmbientLightANDROID
- XrSystemLightEstimationPropertiesANDROID
ฟังก์ชันใหม่
ปัญหา
ประวัติเวอร์ชัน
- การแก้ไข 1, 16-09-2024 (Cairn Overturf)
- คำอธิบายส่วนขยายเริ่มต้น