إضافة XR_ANDROID_light_estimation OpenXR

Name String

XR_ANDROID_light_estimation

نوع الإضافة

إضافة مثيل

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

701

المراجعة

1

متطلبات الإضافة والإصدار

OpenXR 1.0

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

2025-01-17

حالة عنوان IP

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

المساهمون

Jared Finder, 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 إذا كان النظام لا يتيح تقدير الإضاءة.
  • ستعرض الدالة 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;

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

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

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

يحتوي البنية XrEnvironmentLightingCubemapANDROID على بيانات تقدير الإضاءة بتنسيق cubemap حول إضاءة المشهد. 

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 يمثّل عرض وارتفاع صورة كل جانب من جوانب خريطة المكعب.
  • ‫rotation هي XrQuaternionf تمثّل دوران خريطة المكعب.
  • ‫centerExposureTime هي XrTime تمثّل الوقت الذي تم فيه التقاط خريطة المكعب. مفيد للاستيفاء بين خرائط المكعبات.

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

  • يجب تفعيل الإضافة XR_ANDROID_light_estimation قبل استخدام XrEnvironmentLightingCubemapANDROID
  • يجب أن يكون type XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
  • يجب أن تكون قيمة next هي NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البِنى
  • يجب أن تكون قيمة state must قيمة صالحة 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 (Cairn Overturf)
    • الوصف الأوّلي للإضافة

‫OpenXR™ وشعار OpenXR هما علامتان تجاريتان مملوكتان لشركة The Khronos Group Inc. ومسجّلتان كعلامة تجارية في الصين والاتحاد الأوروبي واليابان والمملكة المتحدة.