إضافة XR_ANDROID_light_estimation OpenXR

سلسلة الاسم

XR_ANDROID_light_estimation

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

701

المراجعة

1

التبعيات المتعلّقة بالإصدارات والإضافات

OpenXR 1.0

تاريخ آخر تعديل

2024-09-18

حالة عنوان IP

ما مِن مطالبات معروفة بعناوين IP.

المساهمون

جاريد فايندر، Google

"كايرن أوفرتوف"، Google

سبنسر كوين، Google

ليفانا تشين، Google

نيهاف جاين، 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_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 إذا كان النظام لا يتيح تقدير الإضاءة.
  • سيعرض xrCreateLightEstimatorANDROIDXR_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 المعلومات المطلوبة للحصول على data light estimation. 

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;

أوصاف الأعضاء

للحصول على معلومات تقدير الإضاءة للضوء المحيطي والتجانسات الكروية والضوء الاتجاهي الأساسي، يمكن للتطبيقات ربط نُسخ من الهيكلَين التاليَين، XrAmbientLightANDROID XrSphericalHarmonicsANDROID وXrDirectionalLightANDROID على XrLightEstimateANDROID::next على التوالي.

الاستخدام الصالح (ضمني)

تحتوي بنية 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 أعمدة. الأعمدة الثلاثة التي تقابل قنوات الألوان الأحمر والأخضر والأزرق على التوالي تحتوي كل قناة على 9 معاملات توافقية كروية.

الاستخدام الصالح (ضمني)

تحتوي بنية 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

عمليات التعداد الجديدة

التصاميم الجديدة

الدوالّ الجديدة

المشاكل

سجلّ الإصدارات

  • المراجعة 1، ‎16-09-2024 (كير أوفرتوف)
    • الوصف الأولي للإضافة