تخمین نور XR_ANDROID

رشته نام

XR_ANDROID_light_estimation

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

۷۰۱

بازنگری

۱

وضعیت تصویب

تصویب نشده

وابستگی‌های افزونه و نسخه

اوپن‌ایکس‌آر ۱.۰

آخرین تاریخ اصلاح

۲۰۲۵-۰۳-۱۳

وضعیت آی‌پی

هیچ ادعای مالکیت معنوی شناخته‌شده‌ای وجود ندارد.

مشارکت‌کنندگان

جارد فایندر، گوگل
کایرن اوورترف، گوگل
اسپنسر کوئین، گوگل
لوانا چن، گوگل
نیهاو جین، گوگل
سالار خان، گوگل
اسکات چانگ، گوگل

نمای کلی

این افزونه به برنامه اجازه می‌دهد تا داده‌هایی را که نشان‌دهنده‌ی روشنایی محیط واقعی اطراف هدست هستند، درخواست کند. برنامه می‌تواند از این اطلاعات برای روشن کردن اشیاء مجازی تحت شرایط مشابه صحنه‌ی واقعی که در آن قرار گرفته‌اند، استفاده کند.

مجوزها

برنامه‌های اندروید باید مجوز 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 و هر گونه handle مربوط به فرزند آن، باید به صورت خارجی هماهنگ‌سازی شود.

کدهای بازگشت

موفقیت

  • 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 با مقادیری در فضای گاما است. اگر در فضای رنگی گاما رندر می‌شود، آنها را به صورت جزء به جزء در رنگ نهایی محاسبه شده پس از رندر ضرب کنید. اگر در فضای خطی رندر می‌شود، ابتدا مقادیر را با افزایش به توان ۲.۲ به فضای خطی تبدیل کنید، سپس پس از رندر، آنها را به صورت جزء به جزء در رنگ نهایی محاسبه شده ضرب کنید. 

    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 دوبعدی با ابعاد ۹ سطر و ۳ ستون است. این ۳ ستون به ترتیب مربوط به کانال‌های رنگی قرمز، سبز و آبی هستند. هر کانال دارای ۹ ضریب هارمونیک کروی است.

این 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;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. ساختارهای معتبر شامل XrAmbientLightANDROID ، XrSphericalHarmonicsANDROID و XrDirectionalLightANDROID هستند.
  • state ، XrLightEstimateStateANDROID است که وضعیت تخمین نور را نشان می‌دهد.
  • intensity یک XrVector3f است که شدت نور جهت‌دار را نشان می‌دهد. هر جزء از بردار مربوط به کانال‌های قرمز، سبز و آبی است.
  • direction یک XrVector3f است که جهت نور را نشان می‌دهد.

کاربرد معتبر (ضمنی)

شمارش 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));

انواع شیء جدید

دستورات جدید

سازه‌های جدید

Enum های جدید

ثابت‌های شمارشی جدید

  • 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

مسائل

تاریخچه نسخه

  • نسخه ۱، ۲۰۲۴-۰۹-۱۶ (Cairn Overturf)

    • توضیحات اولیه افزونه