XR_ANDROID_light_estimation OpenXR एक्सटेंशन

Name String

XR_ANDROID_light_estimation

एक्सटेंशन टाइप

इंस्टेंस एक्सटेंशन

रजिस्टर किया गया एक्सटेंशन नंबर

701

बदलाव

1

एक्सटेंशन और वर्शन की डिपेंडेंसी

OpenXR 1.0

पिछली बार बदलाव करने की तारीख

2024-09-18

आईपी स्टेटस

आईपी पर कोई दावा नहीं किया गया है.

योगदान देने वाले

जेरेड फ़ाइंडर, Google

केर्न ओवरटर्फ़, Google

स्पेंसर क्विन, Google

लेवाना चेन, Google

निहाव जैन, Google

खास जानकारी

इस एक्सटेंशन की मदद से, ऐप्लिकेशन को हेडसेट के आस-पास के वातावरण की रोशनी का डेटा पाने का अनुरोध करने की अनुमति मिलती है. इस जानकारी का इस्तेमाल, वर्चुअल ऑब्जेक्ट को रेंडर करते समय किया जा सकता है, ताकि उन्हें उसी तरह से रोशन किया जा सके जिस तरह से उन्हें सीन में रखा गया है.

सिस्टम की क्षमता की जांच करना

कोई ऐप्लिकेशन यह जांच कर सकता है कि सिस्टम में लाइट का अनुमान लगाने की सुविधा काम करती है या नहीं. इसके लिए, xrGetSystemProperties को कॉल करते समय, XrSystemLightEstimationPropertiesANDROID स्ट्रक्चर को XrSystemProperties से जोड़ें. 

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

पैसे चुकाकर बने सदस्यों के ब्यौरे

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर है. OpenXR के मुख्य वर्शन या इस एक्सटेंशन में, इस तरह के स्ट्रक्चर तय नहीं किए गए हैं.
  • supportsLightEstimation एक XrBool32 है, जो यह बताता है कि मौजूदा सिस्टम में लाइट का अनुमान लगाने की सुविधा काम करती है या नहीं.

कोई ऐप्लिकेशन यह जांच कर सकता है कि सिस्टम, लाइट का अनुमान लगाने की सुविधा के साथ काम कर सकता है या नहीं. इसके लिए, xrGetSystemProperties को कॉल करते समय, XrSystemProperties को XrSystemLightEstimationPropertiesANDROID स्ट्रक्चर के साथ एक्सटेंड करें.

अगर सिस्टम में लाइट का अनुमान लगाने की सुविधा काम नहीं करती है, तो यह supportsLightEstimation के लिए XR_FALSE और xrCreateLightEstimatorANDROID से XR_ERROR_FEATURE_UNSUPPORTED दिखाएगा.

मान्य इस्तेमाल (इंप्लिसिट)

लाइट का अनुमान लगाने वाला हैंडल बनाना

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 दिखाएगा.

लाइट का अनुमान लगाने वाले टूल के हैंडल का इस्तेमाल, एपीआई कॉल में बाद में किया जा सकता है. अगर कोई ऐप्लिकेशन रनटाइम को यह बताना चाहता है कि उसने लाइट का अनुमान लगाने वाले डेटा को ऐक्सेस कर लिया है, तो उसे xrDestroyLightEstimatorANDROID का इस्तेमाल करके हैंडल को नष्ट करना होगा.

मान्य इस्तेमाल (इंप्लिसिट)

रिटर्न कोड

सफलता

  • 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 के मुख्य वर्शन या इस एक्सटेंशन में, इस तरह के स्ट्रक्चर तय नहीं किए गए हैं.

मान्य इस्तेमाल (इंप्लिसिट)

xrDestroyLightEstimatorANDROID फ़ंक्शन, estimator और उससे जुड़े सभी संसाधनों को रिलीज़ करता है. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

पैरामीटर की जानकारी

मान्य इस्तेमाल (इंप्लिसिट)

थ्रेड की सुरक्षा

  • estimator और किसी भी चाइल्ड हैंडल का ऐक्सेस, बाहरी तौर पर सिंक होना ज़रूरी है

रिटर्न कोड

सफलता

  • XR_SUCCESS

प्रोसेस पूरी नहीं हो सकी

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

लाइट के अनुमान का डेटा ऐक्सेस करना

xrGetLightEstimateANDROID फ़ंक्शन को इस तरह से परिभाषित किया गया है: 

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

पैरामीटर की जानकारी

मान्य इस्तेमाल (इंप्लिसिट)

रिटर्न कोड

सफलता

  • 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 है जो उस समय के बारे में बताता है जब ऐप्लिकेशन को रोशनी के अनुमान के बारे में क्वेरी करनी है.

मान्य इस्तेमाल (इंप्लिसिट)

XrLightEstimateANDROID स्ट्रक्चर में, रोशनी के अनुमान का डेटा शामिल होता है. 

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

पैसे चुकाकर बने सदस्यों के ब्यौरे

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर है. मान्य स्ट्रक्चर ये हैं: XrAmbientLightANDROID, XrSphericalHarmonicsANDROID, और XrDirectionalLightANDROID.
  • state, XrLightEstimateStateANDROID है, जो लाइट के अनुमान की स्थिति दिखाता है.
  • lastUpdatedTime वह XrTime है जो यह दिखाता है कि अनुमान को आखिरी बार कब कैलकुलेट किया गया था.

ऐंबियंट लाइट, स्फ़ीरिकल हार्मोनिक्स, और प्राइमरी डायरेक्टिव लाइट के लिए लाइट के अनुमान की जानकारी पाने के लिए, ऐप्लिकेशन XrLightEstimateANDROID::next पर, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID, और XrDirectionalLightANDROID के उदाहरणों को चेन कर सकते हैं.

मान्य इस्तेमाल (इंप्लिसिट)

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 है. घटक के हिसाब से, अपने गामा सुधारे गए रेंडर के रंग को इन वैल्यू से गुणा करें.

मान्य इस्तेमाल (इंप्लिसिट)

XrSphericalHarmonicsANDROID स्ट्रक्चर में स्फ़ीरीय हार्मोनिक्स होते हैं, जो सीन की लाइटिंग दिखाते हैं. 

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 ऐरे है. इसमें 9 पंक्तियां और 3 कॉलम हैं. ये तीन कॉलम, कलर चैनल के हिसाब से लाल, हरे, और नीले रंग के होते हैं. हर चैनल में नौ गोलाकार हार्मोनिक गुणांक होते हैं.

मान्य इस्तेमाल (इंप्लिसिट)

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 है.

मान्य इस्तेमाल (इंप्लिसिट)

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

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

नए Enums

नए स्ट्रक्चर

नए फ़ंक्शन

समस्याएं

वर्शन का इतिहास

  • पहला बदलाव, 16-09-2024 (कैर्न ओवरटर्फ़)
    • एक्सटेंशन के बारे में शुरुआती जानकारी