XR_ANDROID_light_estimation

מחרוזת שם

XR_ANDROID_light_estimation

סוג התוסף

הרחבת המכונה

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

701

Revision

1

סטטוס האישור

לא אושר

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

OpenXR 1.0

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

2025-03-13

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

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

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

ג'ארד פיינדר, Google
קיירן אוברטרף, Google
ספנסר קווין, Google
לבנה צ'ן, Google
ניחב ג'יין, Google
סלאר חאן, Google
סקוט צ'אנג, Google

סקירה כללית

ההרחבה הזו מאפשרת לאפליקציה לבקש נתונים שמייצגים את התאורה של הסביבה האמיתית מסביב לאוזניות. האפליקציה יכולה להשתמש במידע הזה כדי להאיר אובייקטים וירטואליים באותם תנאים כמו הסצנה בעולם האמיתי שבה הם ממוקמים.

הרשאות

באפליקציות ל-Android חובה לציין את ההרשאה android.permission.SCENE_UNDERSTANDING_COARSE במניפסט, כי התוסף הזה חושף מידע על התאורה בסביבה. ההרשאה android.permission.SCENE_UNDERSTANDING_COARSE נחשבת להרשאה מסוכנת. האפליקציה חייבת לבקש את ההרשאה בזמן הריצה כדי להשתמש בפונקציות האלה:

(רמת ההגנה: מסוכן)

בדיקת יכולות המערכת

המבנה XrSystemLightEstimationPropertiesANDROID מוגדר כך:

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 הוא מצביע ל-handle שבו מוחזר XrLightEstimatorANDROID שנוצר.

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

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

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

שימוש תקף (משתמע)

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST

המבנה XrLightEstimatorCreateInfoANDROID מתאר את המידע ליצירת נקודת אחיזה XrLightEstimatorANDROID.

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrLightEstimatorCreateInfoANDROID;

תיאורי חברים

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. לא מוגדרים מבנים כאלה ב-OpenXR או בתוסף הזה.

שימוש תקף (משתמע)

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

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

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

הפונקציה xrDestroyLightEstimatorANDROID משחררת את 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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

המבנה XrLightEstimateGetInfoANDROID מוגדר כך:

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const 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;

תיאורי חברים

בכל מבנה light estimate, אם הערך של state הוא XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID, כל שאר השדות במבנה הם שרירותיים, כלומר הערכים שלהם לא מוגדרים.

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

  • ‫colorCorrection הוא XrVector3f עם ערכים במרחב גמא. אם הרינדור מתבצע במרחב צבעי גמא, צריך להכפיל אותם לפי רכיבים מול הצבע הסופי המחושב אחרי הרינדור. אם הרינדור מתבצע במרחב לינארי, קודם צריך להמיר את הערכים למרחב לינארי על ידי העלאה לחזקה של 2.2, ואז להכפיל את הרכיבים לפי הצבע הסופי המחושב אחרי הרינדור.

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

שימוש תקף (משתמע)

המבנה 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 מקדמים של הרמוניות ספריות.

הפונקציה coefficients משמשת בפונקציה מיוחדת שמקבלת כקלט כיוון ומחזירה את צבע האור שמגיע מהכיוון הזה. פרטים נוספים זמינים במאמר הזה .

שימוש תקף (משתמע)

הספירה XrSphericalHarmonicsKindANDROID מזהה בזמן הריצה את סוג ההרמוניות הספריות שהאפליקציה מבקשת.

typedef enum XrSphericalHarmonicsKindANDROID {
    XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID = 0,
    XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID = 1,
    XR_SPHERICAL_HARMONICS_KIND_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSphericalHarmonicsKindANDROID;

המשמעויות של ערכי ה-enumeration:

תיאור ה-Enum

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

המקדמים של ההרמוניות הספריות מייצגים את פונקציית הבהירות של האור בסביבה, לא כולל התרומה של האור הראשי.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

המקדמים ההרמוניים הכדוריים מייצגים את פונקציית הקרינה של התאורה הסביבתית, כולל התרומה מהאור הראשי.

המבנה XrDirectionalLightANDROID מכיל נתוני הערכת תאורה.

typedef struct XrDirectionalLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     direction;
} XrDirectionalLightANDROID;

תיאורי חברים

שימוש תקף (משתמע)

הספירה XrLightEstimateStateANDROID מציינת את מצב הערכת התאורה שמוחזרת על ידי זמן הריצה.

typedef enum XrLightEstimateStateANDROID {
    XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID = 0,
    XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID = 1,
    XR_LIGHT_ESTIMATE_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrLightEstimateStateANDROID;

המשמעויות של ערכי ה-enumeration:

תיאור ה-Enum

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

הערכת התאורה תקינה

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

הערכת התאורה לא תקינה

קוד לדוגמה להערכת תאורה

בדוגמת הקוד הבאה אפשר לראות איך מקבלים את כל הכמויות האפשריות של הערכת התאורה בזמן הריצה

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // 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 sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &sphericalHarmonics,
};

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

סוגי אובייקטים חדשים

פקודות חדשות

מבנים חדשים

New Enums

New Enum Constants

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • הרחבה של XrObjectType :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • הרחבה של XrStructureType :

    • XR_TYPE_AMBIENT_LIGHT_ANDROID
    • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
    • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
    • XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID

בעיות

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

  • גרסה 1, ‏16.09.2024 (Cairn Overturf)

    • תיאור ראשוני של התוסף