پسوند OpenXR XR_ANDROID_light_estimation

رشته نام

XR_ANDROID_light_estimation

نوع پسوند

پسوند نمونه

شماره برنامه افزودنی ثبت شده

701

تجدید نظر

1

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

OpenXR 1.0

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

18-09-2024

وضعیت IP

هیچ ادعای IP شناخته شده ای وجود ندارد.

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

جارد فایندر، گوگل

Cairn Overturf، گوگل

اسپنسر کوین، گوگل

لوانا چن، گوگل

نیهاو جین، گوگل

نمای کلی

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

قابلیت سیستم را بررسی کنید

هنگامی که xrGetSystemProperties را فراخوانی می کند، یک برنامه کاربردی می تواند بررسی کند که آیا سیستم از تخمین نور پشتیبانی می کند یا خیر .

typedef struct XrSystemLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsLightEstimation;
} XrSystemLightEstimationPropertiesANDROID;

توضیحات اعضا

  • type XrStructureType این ساختار است.
  • next NULL یا اشاره گر به ساختار بعدی در زنجیره ساختار است. چنین ساختاری در هسته OpenXR یا این پسوند تعریف نشده است.
  • supportsLightEstimation یک XrBool32 است که نشان می دهد آیا سیستم فعلی از تخمین نور پشتیبانی می کند یا خیر.

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

دسته برآوردگر نور برگشتی ممکن است متعاقباً در فراخوانی های API استفاده شود. اگر برنامه ای بخواهد به زمان اجرا نشان دهد که دسترسی به داده های تخمین نور انجام شده است ، باید دسته را با استفاده از 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;

توضیحات اعضا

برای به دست آوردن اطلاعات تخمین نور برای نور محیط، هارمونیک‌های کروی و نور جهت‌دار اولیه، برنامه‌ها می‌توانند نمونه‌هایی از ساختارهای زیر، 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 ستون است. 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 ها معانی زیر را دارند:

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 ها معانی زیر را دارند:

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 (Cairn Overturf)
    • توضیحات پسوند اولیه