תוסף OpenXR‏ XR_ANDROID_light_estimation

מחרוזת שם

XR_ANDROID_light_estimation

סוג התוסף

הרחבת המכונה

מספר שלוחה רשום

701

Revision

1

תלות בתוסף ובגרסה

OpenXR 1.0

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

2025-01-17

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

לא ידוע על תלונות בנושא קניין רוחני.

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

Jared Finder, Google

קאירן אוברטורף, Google

ספנסר קווין, Google

לבנה צ'ן, Google

Nihav Jain, 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)

ה-handle‏ 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 אם לא ניתנו לאפליקציה הקוראת ההרשאות הנדרשות.

אפשר להשתמש בהמשך ב-handle של מעריך האור שמוחזר בקריאות ל-API. אם אפליקציה רוצה לציין לסביבת זמן הריצה שהיא סיימה את הגישה לנתוני הערכת התאורה, עליה להרוס את נקודת האחיזה באמצעות xrDestroyLightEstimatorANDROID.

שימוש תקין (מרומז)

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • 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);

תיאורים של פרמטרים

שימוש תקין (מרומז)

Thread Safety

  • הגישה אל estimator ואל כל הכינויים של הילדים חייבת להיות מסונכרנת חיצונית

קודי החזרה

הצלחה

  • XR_SUCCESS

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

גישה לנתוני הערכת תאורה

הפונקציה xrGetLightEstimateANDROID מוגדרת כך: 

XrResult xrGetLightEstimateANDROID(
    XrLightEstimatorANDROID                     estimator,
    const XrLightEstimateGetInfoANDROID*        input,
    XrLightEstimateANDROID*                     output);

תיאורים של פרמטרים

שימוש תקין (מרומז)

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • 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, ולכן ערכי 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 שמייצג את הרוחב והגובה של התמונה של כל צד של המפה הקובייתית.
  • ‫rotation הוא XrQuaternionf שמייצג את הסיבוב של מפת הקובייה.
  • ‫centerExposureTime היא XrTime שמייצגת את השעה שבה צולמה מפת הקוביות. שימושי לאינטרפולציה בין מיפויים של קובייה.

שימוש תקין (מרומז)

  • XR_ANDROID_light_estimation התוסף חייב להיות מופעל לפני השימוש ב-XrEnvironmentLightingCubemapANDROID
  • הערך של type חייב להיות XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
  • next must be NULL or a valid pointer to the next structure in a structure chain
  • state must be a valid XrLightEstimateStateANDROID value
  • 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

New Enums

מבנים חדשים

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

בעיות

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

  • גרסה 2, ‏ 17 בינואר 2025 (סלאר חאן)
    • הוספנו תמיכה במפת קוביות של תאורה סביבתית
  • ‫Revision 1, 2024-09-16 (Cairn Overturf)
    • תיאור ראשוני של התוסף

‫OpenXR™‎ והלוגו של OpenXR הם סימנים מסחריים בבעלות The Khronos Group Inc. ‎ והם רשומים כסימן מסחרי בסין, באיחוד האירופי, ביפן ובבריטניה.