XR_ANDROID_light_estimation

Name String

XR_ANDROID_light_estimation

نوع الإضافة

إضافة مثيل

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

701

المراجعة

1

حالة التصديق

لم تتم المصادقة

الاعتماديات على الإضافات والإصدارات

OpenXR 1.0

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

2025-03-13

حالة عنوان IP

ما مِن مطالبات معروفة بشأن الملكية الفكرية.

المساهمون

"جاريد فايندر"، Google
"كيرن أوفرتيرف"، Google
"سبنسر كوين"، Google
"ليفانا تشين"، Google
"نيهاف جاين"، Google
"سالار خان"، Google
"سكوت تشونغ"، Google

نظرة عامة

يتيح هذا الامتداد للتطبيق طلب بيانات تمثّل الإضاءة في البيئة الواقعية المحيطة بسماعة الرأس. يمكن للتطبيق استخدام هذه المعلومات لإضاءة الكائنات الافتراضية في الظروف نفسها التي يظهر فيها المشهد من العالم الحقيقي.

الأذونات

يجب أن تتضمّن تطبيقات Android الإذن android.permission.SCENE_UNDERSTANDING_COARSE في ملف البيان الخاص بها، لأنّ هذه الإضافة تعرض معلومات الإضاءة حول البيئة. يُعدّ الإذن android.permission.SCENE_UNDERSTANDING_COARSE إذنًا خطيرًا. يجب أن يطلب التطبيق الإذن أثناء التشغيل لاستخدام الوظائف التالية:

(مستوى الحماية: خطير)

فحص إمكانات النظام

يتم تعريف بنية XrSystemLightEstimationPropertiesANDROID على النحو التالي:

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 لإنشاء أداة تقدير الإضاءة.

  • يجب أن تعرض وقت التشغيل XR_ERROR_FEATURE_UNSUPPORTED إذا كان النظام لا يتيح تقدير الإضاءة.
  • يجب أن تعرض بيئة التشغيل القيمة XR_ERROR_PERMISSION_INSUFFICIENT إذا لم يتم منح الأذونات المطلوبة للتطبيق الذي يستدعيها.

إذا أراد أحد التطبيقات إعلام وقت التشغيل بأنّه انتهى من الوصول إلى بيانات تقدير الإضاءة، يجب إتلاف المؤشر من خلال xrDestroyLightEstimatorANDROID .

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

رموز الإرجاع

ناجحة

  • 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 أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو في هذه الإضافة.

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

يتم تعريف الدالة xrDestroyLightEstimatorANDROID على النحو التالي:

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

أوصاف المَعلمات

تؤدي الدالة xrDestroyLightEstimatorANDROID إلى تحرير 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_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 أو مؤشر إلى البنية التالية في سلسلة البنية.
  • space هو XrSpace الذي يحدّد المساحة المرجعية التي يتم فيها التعبير عن اتجاه الضوء والتوافقيات الكروية.
  • ‫time هو XrTime الذي يصف الوقت الذي يريد فيه التطبيق طلب تقدير الإضاءة.

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

يحتوي البنية XrLightEstimateANDROID على بيانات تقدير الإضاءة:

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

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

بالنسبة إلى كل بنية تقدير إضاءة، إذا كانت قيمة 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 أو مؤشر إلى البنية التالية في سلسلة البنية. تشمل البِنى الصالحة 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 أو مؤشر إلى البنية التالية في سلسلة البنية. تشمل البِنى الصالحة XrAmbientLightANDROID وXrDirectionalLightANDROID .
  • ‫state هو XrLightEstimateStateANDROID الذي يمثّل حالة تقدير الإضاءة.
  • ‫kind هو XrSphericalHarmonicsKindANDROID الذي يطلبه التطبيق.
  • ‫coefficients هو صفيف float ثنائي الأبعاد يتضمّن 9 صفوف و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;

تحمل قيم التعداد المعاني التالية:

وصف التعداد

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;

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

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

يشير التعداد 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;

تحمل قيم التعداد المعاني التالية:

وصف التعداد

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

أنواع العناصر الجديدة

الأوامر الجديدة

المنشآت الجديدة

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

ثوابت التعداد الجديدة

  • 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، ‎16-09-2024 (Cairn Overturf)

    • الوصف الأوّلي للإضافة