پسوند OpenXR XR_ANDROID_light_estimation

رشته نام

XR_ANDROID_light_estimation

نوع پسوند

پسوند نمونه

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

701

تجدید نظر

1

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

OpenXR 1.0

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

17-01-2025

وضعیت 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;

توضیحات اعضا

برای به دست آوردن اطلاعات تخمین نور برای نقشه مکعبی روشنایی محیط، نور محیط، هارمونیک‌های کروی و نور جهت‌دار اولیه، برنامه‌ها می‌توانند نمونه‌هایی از ساختارهای زیر را زنجیره‌ای کنند، XrEnvironmentLightingCubemapANDROID ، XrAmbientLightANDROID ، XrSphericalHarmonicsANDROID و XrDirectional on. 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 است که نشان دهنده زمانی است که نقشه مکعب گرفته شده است. برای درون یابی بین نقشه های مکعبی مفید است.

استفاده معتبر (ضمنی)

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

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,
};


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 (سالار خان)
    • اضافه شدن پشتیبانی از cubemap روشنایی محیط
  • بازبینی 1، 16/09/2024 (Cairn Overturf)
    • توضیحات پسوند اولیه