תוסף OpenXR‏ XR_ANDROID_light_estimation

Name String

XR_ANDROID_light_estimation

סוג התוסף

תוסף למכונה

מספר תוסף רשום

701

גרסה

1

תלות בתוספים ובגרסאות

OpenXR 1.0

תאריך השינוי האחרון

2025-01-17

סטטוס כתובת ה-IP

לא ידוע על תלונות על הפרת זכויות יוצרים בנושא כתובת IP.

שותפים ביצירת התוכן

Jared Finder, ‏ Google

קארן אוברטורף (Cairn Overturf), Google

ספנסר קווין (Spencer Quin), Google

לונן צ'ן, Google

Nihav Jain, ‏ Google

סאלאר חאן (Salar Khan), Google

סקוט צ'ונג (Scott Chung), 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 הוא הפניה למזהה (handle) שבו מוחזר האובייקט שנוצר של XrLightEstimatorANDROID.

האפליקציה יכולה להשתמש בפונקציה xrCreateLightEstimatorANDROID כדי ליצור מעריך תאורה.

  • הפונקציה xrCreateLightEstimatorANDROID תחזיר את הערך XR_ERROR_FEATURE_UNSUPPORTED אם המערכת לא תומכת במדידה של עוצמת התאורה.
  • הפונקציה xrCreateLightEstimatorANDROID תחזיר את הערך XR_ERROR_PERMISSION_INSUFFICIENT אם לא הוקצו לאפליקציה הקוראת את ההרשאות הנדרשות.

יכול להיות שייעשה שימוש במזהה של מעריך האור החזק שהוחזרו בקריאות API. אם אפליקציה רוצה להצביע לסביבת זמן הריצה שהיא סיימה לגשת לנתוני האומדן של התאורה, היא צריכה להשמיד את ה-handle באמצעות 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;

תיאורי חברים

כדי לקבל מידע על אומדן התאורה של מפת הקוביות של תאורת הסביבה, התאורה הסביבתית, התנאים הסופיים של פונקציית ה-spherical harmonics והתאורה הראשית הישירה, אפליקציות יכולות לשרשר מכונות של המבנים הבאים, 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, כך שערכים של משתני float יכולים להיות גדולים מ-1.0.
  • cubemapLeftImage הוא float* שמייצג את מאגר ה-R32G32B32_SFLOAT של הצד השמאלי של מפת הקוביות. הערך הזה הוא HDR, כך שערכים של משתני float יכולים להיות גדולים מ-1.0.
  • cubemapTopImage הוא float* שמייצג את מאגר ה-R32G32B32_SFLOAT של הצד העליון של מפת הקוביות. הערך הזה הוא HDR, כך שערכים של משתני float יכולים להיות גדולים מ-1.0.
  • cubemapBottomImage הוא float* שמייצג את מאגר ה-R32G32B32_SFLOAT של הצד התחתון של מפת הקוביות. הערך הזה הוא HDR, כך שערכים של משתני float יכולים להיות גדולים מ-1.0.
  • cubemapFrontImage הוא float* שמייצג את מאגר ה-R32G32B32_SFLOAT של הצד הקדמי של מפת הקוביות. הערך הזה הוא HDR, כך שערכים של משתני float יכולים להיות גדולים מ-1.0.
  • resolution הוא uint32_t שמייצג את הרוחב והגובה של התמונה של כל צד של מפת הקוביות. הערה: מדובר ב-HDR, כך שערכי float יכולים להיות גדולים מ-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 מזהה בסביבת זמן הריצה את סוג ה-spherical harmonics שהאפליקציה מבקשת. 

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 מזהה בסביבת זמן הריצה את סוג ה-spherical harmonics שהאפליקציה מבקשת. 

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

משתני Enum חדשים

מבנים חדשים

פונקציות חדשות

בעיות

היסטוריית הגרסאות

  • גרסה 2, 17 בינואר 2025 (Salar Khan)
    • נוספה תמיכה במיפוי קוביות של תאורה סביבתית
  • גרסה 1, 16 בספטמבר 2024 (Cairn Overturf)
    • תיאור ראשוני של התוסף