إضافة XR_ANDROID_light_estimation OpenXR

سلسلة الاسم

XR_ANDROID_light_estimation

نوع الإضافة

إضافة مثيل

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

701

المراجعة

1

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

OpenXR 1.0

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

2025-01-17

حالة عنوان IP

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

المساهمون

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

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

سبنسر كوين، 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;

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

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

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

تحتوي بنية XrEnvironmentLightingCubemapANDROID على بيانات تقدير الإضاءة بتنسيق خريطة مكعّبة عن ملفه الإضاءة المحيطة للمشهد. 

typedef struct XrEnvironmentLightingCubemapANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    const float*                   cubemapRightImage;
    const float*                   cubemapLeftImage;
    const float*                   cubemapTopImage;
    const float*                   cubemapBottomImage;
    const float*                   cubemapFrontImage;
    const float*                   cubemapBackImage;
    uint32_t                       resolution;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrEnvironmentLightingCubemapANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. الهياكل الصالحة هي XrSphericalHarmonicsANDROID و XrAmbientLightANDROID و XrDirectionalLightANDROID.
  • ‫state هو XrLightEstimateStateANDROID الذي يمثّل حالة تقدير الإضاءة.
  • cubemapRightImage هو float* يمثّل مخزن R32G32B32_SFLOAT ل الجانب الأيمن من خريطة المكعب. يُرجى العِلم أنّ هذا تنسيق HDR، لذا يمكن أن تكون القيم العائمة أكبر من 1.0.
  • cubemapLeftImage هو float* يمثّل مخزن R32G32B32_SFLOAT ل الجانب الأيمن من خريطة المكعب. يُرجى العِلم أنّ هذا تنسيق HDR، لذا يمكن أن تكون القيم العائمة أكبر من 1.0.
  • ‫cubemapTopImage هو float* يمثّل مخزن R32G32B32_SFLOAT ل الجانب العلوي من خريطة المكعب. يُرجى العِلم أنّ هذا تنسيق HDR، لذا يمكن أن تكون القيم العائمة أكبر من 1.0.
  • ‫cubemapBottomImage هو float* يمثّل مخزن R32G32B32_SFLOAT ل الجانب السفلي من خريطة المكعب. يُرجى العِلم أنّ هذا تنسيق HDR، لذا يمكن أن تكون القيم العائمة أكبر من 1.0.
  • cubemapFrontImage هو float* يمثّل مخزن R32G32B32_SFLOAT ل الجانب الأمامي من خريطة المكعب. يُرجى العِلم أنّ هذا تنسيق HDR، لذا يمكن أن تكون القيم العائمة أكبر من 1.0.
  • ‫resolution هو uint32_t يمثّل عرض الصورة وارتفاعها لكل جانب من خريطة المكعب. يُرجى العِلم أنّ هذا تنسيق HDR، لذا يمكن أن تكون القيم العائمة أكبر من 1.0.
  • ‫rotation هو XrQuaternionf يمثّل تدوير خريطة المكعب.
  • ‫centerExposureTime هو XrTime يمثّل وقت التقاط ملف cubemap. مفيد لإجراء التداخل بين خرائط المكعبات.

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

  • يجب تفعيل امتداد XR_ANDROID_light_estimation قبل استخدام XrEnvironmentLightingCubemapANDROID.
  • type يجب أن يكون XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
  • next يجب أن يكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية.
  • state يجب أن تكون قيمة XrLightEstimateStateANDROID صالحة
  • cubemapRightImage يجب أن يكون مؤشرًا إلى قيمة عائمة صالحة.
  • cubemapLeftImage يجب أن يكون مؤشرًا إلى قيمة عائمة صالحة.
  • cubemapTopImage يجب أن يكون مؤشرًا إلى قيمة عائمة صالحة.
  • cubemapBottomImage يجب أن يكون مؤشرًا إلى قيمة عائمة صالحة.
  • cubemapFrontImage يجب أن يكون مؤشرًا إلى قيمة عائمة صالحة.
  • cubemapBackImage يجب أن يكون مؤشرًا إلى قيمة عائمة صالحة.

تحتوي بنية XrAmbientLightANDROID على بيانات تقدير الإضاءة حول الضوء المحيط في المشهد. 

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

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

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. الهياكل الصالحة هي XrSphericalHarmonicsANDROID وXrEnvironmentLightingCubemapANDROID وXrDirectionalLightANDROID.
  • ‫state هو XrLightEstimateStateANDROID الذي يمثّل حالة تقدير الإضاءة.
  • intensity هو XrVector3 يمثّل شدة الإضاءة المحيطة. يتوافق كل مكوّن من مكوّنات المتجه مع القنوات الحمراء والخضراء والزرقاء.
  • colorCorrection هو XrVector3 يحتوي على قيم في مساحة جاما. على مستوى المكوّنات، اضرب لون الصورة التي تم تصحيحها باستخدام مقياس جاما بهذه القيم.

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

يحتوي هيكل XrSphericalHarmonicsANDROID على توافقيات كروية تمثّل إضاءة المشهد. 

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

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

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

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


XrEnvironmentLightingCubemapANDROID lightingCubemap {
    .type = XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID,
    .next = &ambientLight,
}

XrLightEstimateANDROID estimate = {
    .type = XR_TYPE_LIGHT_ESTIMATE_ANDROID,
    .next = &lightingCubemap,
};

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight,
  // lightingCubemap, 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
  • XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID

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

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

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

المشاكل

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

  • المراجعة 2، ‎17-01-2025 (سالار خان)
    • تمّت إضافة ميزة "خريطة مكعّبة" لإضاءة البيئة المحيطة
  • المراجعة 1، ‎16-09-2024 (كير أوفرتوف)
    • الوصف الأولي للإضافة