תוסף OpenXR‏ XR_ANDROID_light_estimation

מחרוזת שם

XR_ANDROID_light_estimation

סוג התוסף

תוסף למכונה

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

701

גרסה

1

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

OpenXR 1.0

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

2024-09-18

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

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

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

Jared Finder, ‏ Google

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

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

לבנה צ'ן, Google

Nihav Jain, ‏ 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;

תיאורי חברים

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

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

משתני Enum חדשים

מבנים חדשים

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

בעיות

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

  • גרסה 1, 16 בספטמבר 2024 (Cairn Overturf)
    • תיאור ראשוני של התוסף