XR_ANDROID_light_estimation

Name String

XR_ANDROID_light_estimation

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

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

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

701

การแก้ไข

1

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

ยังไม่ให้สัตยาบัน

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

OpenXR 1.0

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

2025-03-13

สถานะ IP

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

ผู้เขียน

Jared Finder, Google
Cairn Overturf, Google
Spencer Quin, Google
Levana Chen, Google
Nihav Jain, Google
Salar Khan, Google
Scott Chung, Google

ภาพรวม

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

สิทธิ์

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

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

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

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

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

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

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

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

หากรันไทม์แสดงผล XR_FALSE สำหรับ supportsLightEstimation รันไทม์ต้องแสดงผล XR_ERROR_FEATURE_UNSUPPORTED จาก xrCreateLightEstimatorANDROID

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

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

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

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

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

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

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

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

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

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

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

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

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

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

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

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

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

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

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

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

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

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

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

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

ฟังก์ชัน xrDestroyLightEstimatorANDROID จะปล่อย estimator และทรัพยากรพื้นฐาน

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

  • ต้องเปิดใช้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);

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

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

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

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

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

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

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

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

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

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

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

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

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

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

สำหรับโครงสร้างการประมาณแสงทุกรายการ หาก state เป็น XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID ช่องอื่นๆ ทั้งหมดในโครงสร้างจะไม่มีค่า ซึ่งหมายความว่าค่าของช่องเหล่านั้นไม่ได้กำหนดไว้

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

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

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

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

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

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

  • colorCorrection คือ XrVector3f ที่มีค่าในพื้นที่แกมมา หากแสดงผลในพื้นที่สีแกมมา ให้คูณค่าเหล่านั้นตามคอมโพเนนต์กับสีที่คำนวณสุดท้ายหลังการแสดงผล หากแสดงผลในพื้นที่เชิงเส้น ให้แปลงค่าเป็นพื้นที่เชิงเส้นก่อนโดยยกกำลัง 2.2 จากนั้นคูณตามองค์ประกอบกับสีที่คำนวณสุดท้ายหลังการแสดงผล

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

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

โครงสร้าง XrSphericalHarmonicsANDROID มีฮาร์มอนิกทรงกลมที่แสดงถึงแสงของฉาก

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

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

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

coefficients ใช้ในฟังก์ชันพิเศษที่รับทิศทางเป็นอินพุตและแสดงผลสีของแสงที่มาจากทิศทางนั้น ดูรายละเอียดเพิ่มเติมได้ในเอกสารนี้

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

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

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

ค่าการแจงนับมีความหมายดังนี้

คำอธิบาย Enum

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

สัมประสิทธิ์ฮาร์มอนิกทรงกลมแสดงฟังก์ชันการแผ่รังสีของแสงสภาพแวดล้อม โดยไม่รวมการมีส่วนร่วมจากแสงหลัก

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

สัมประสิทธิ์ฮาร์มอนิกทรงกลมแสดงถึงฟังก์ชันการแผ่รังสีของแสงสภาพแวดล้อม รวมถึงการมีส่วนร่วมจากแสงหลัก

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

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

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

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

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

การแจงนับ XrLightEstimateStateANDROID จะระบุสถานะของการประมาณค่าแสงที่รันไทม์ส่งคืน

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

ค่าการแจงนับมีความหมายดังนี้

คำอธิบาย Enum

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

การประมาณการการใช้งานเบาถูกต้อง

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

ค่าประมาณแสงไม่ถูกต้อง

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

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

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // 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 sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

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

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

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

คำสั่งใหม่

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

Enum ใหม่

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

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • การขยาย XrObjectType :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • การขยาย XrStructureType :

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

ปัญหา

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

  • การแก้ไขครั้งที่ 1, 2024-09-16 (Cairn Overturf)

    • คำอธิบายส่วนขยายเริ่มต้น