XR_ANDROID_geospatial

מחרוזת שם

XR_ANDROID_geospatial

סוג התוסף

הרחבת המכונה

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

790

Revision

1

סטטוס האישור

לא אושר

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

XR_EXT_future

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

2025-12-18

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

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

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

John Ullman, Google
Ben King, Google
Nihav Jain, Google
Jared Finder, Google

סקירה כללית

התוסף הזה מספק מעקב גיאו-מרחבי עבור Geospatial API של Google, שמאפשר מיקום גיאוגרפי מדויק וקביעת אוריינטציה, ומאפשר לאפליקציה למקם תוכן ביחס לכדור הארץ. השילוב הזה מתבצע באמצעות מעקב תנועה, GPS וחיישנים אחרים, וגם באמצעות מערכת מיקום חזותי (VPS) של Google. מערכת VPS משווה בין תמונות ממצלמת המכשיר לבין תמונות Street View כדי לקבוע מיקום מדויק ואת הכיוון. ‫Geospatial API מספק לרוב דיוק מיקום ברמת תת-מטר (סדרי גודל טובים יותר מ-GPS) ודיוק אוריינטציה ברמת תת-מעלה.

כדי להשתמש בממשקי ה-API בתוסף הזה (מלבד בדיקת התמיכה בתוסף), האפליקציה חייבת להגדיר בהצלחה פרטי אימות באמצעות מנגנון כלשהו, כמו XR_ANDROID_google_cloud_auth . בתיעוד של תוסף האימות מופיעים פרטים נוספים על ההגדרה ועל תוצאות השגיאות.

הרשאות

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

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

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

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

typedef struct XrSystemGeospatialPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGeospatial;
} XrSystemGeospatialPropertiesANDROID;

תיאורי חברים

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

אפליקציה יכולה לבדוק אם המערכת תומכת בתכונות גיאו-מרחביות על ידי שרשור מבנה XrSystemGeospatialPropertiesANDROID אל XrSystemProperties כשקוראים ל-xrGetSystemProperties .

אם סביבת זמן ריצה מחזירה XR_FALSE עבור supportsGeospatial , המערכת לא תומכת בתכונות גיאו-מרחביות, ולכן הפונקציה must מחזירה XR_ERROR_FEATURE_UNSUPPORTED מהפונקציה xrCreateGeospatialTrackerANDROID . באפליקציה צריך להימנע משימוש בפונקציות גיאוספציאליות כשהערך של supportsGeospatial הוא XR_FALSE .

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

יצירת שם של כלי למעקב גיאוגרפי

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

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

XrResult xrCreateGeospatialTrackerANDROID(
    XrSession                                   session,
    const XrGeospatialTrackerCreateInfoANDROID* createInfo,
    XrGeospatialTrackerANDROID*                 geospatialTrackerOutput);

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

  • ‫session הוא XrSession שבו הגשש הגיאוספציאלי יהיה פעיל.
  • ‫createInfo הוא מצביע למבנה XrGeospatialTrackerCreateInfoANDROID שמציין פרמטרים ראשוניים של מעקב גיאוגרפי.
  • ‫geospatialTrackerOutput הוא מצביע ל-handle שבו מוחזר XrGeospatialTrackerANDROID שנוצר.

אפליקציה יכולה ליצור נקודת אחיזה של XrGeospatialTrackerANDROID על ידי קריאה ל-xrCreateGeospatialTrackerANDROID . אפשר להשתמש בהמשך ב-handle‏ XrGeospatialTrackerANDROID שמוחזר בקריאות ל-API. אם האפליקציה לא קיבלה את ההרשאות הנדרשות, סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_PERMISSION_INSUFFICIENT . יכול להיות רק XrGeospatialTrackerANDROID אחד בכל פעם עבור XrSession מסוים . האפליקציה חייבת לוודא שכל האובייקטים הקודמים של XrGeospatialTrackerANDROID הושמדו לפני הפעלת הפונקציה הזו שוב, אחרת זמן הריצה חייב להחזיר את הערך XR_ERROR_LIMIT_REACHED . אם יצירת אמצעי המעקב תצליח, הוא יעבור בהתחלה למצב XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , והאפליקציה חייבת להמתין עד שהמצב ישתנה ל-XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID לפני השימוש באמצעי המעקב. מידע נוסף זמין במאמר בנושא XrEventDataGeospatialTrackerStateChangedANDROID . אם האפליקציה מעבירה XrGeospatialTrackerANDROID שלא נמצא במצב XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID לפונקציה שדורשת אותו, זמן הריצה חייב להחזיר XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

חובה לשחרר בסופו של דבר את ה-handle‏ XrGeospatialTrackerANDROID באמצעות הפונקציה xrDestroyGeospatialTrackerANDROID.

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • 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
  • XR_ERROR_VALIDATION_FAILURE

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

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

תיאורי חברים

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.

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

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

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

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

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

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

Thread Safety

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

קודי החזרה

הצלחה

  • XR_SUCCESS

Failure

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

מצב של כלי מעקב גיאו-מרחבי

הספירה XrGeospatialTrackerStateANDROID מוגדרת כך:

typedef enum XrGeospatialTrackerStateANDROID {
    XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID = 0,
    XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID = 1,
    XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID = 2,
    XR_GEOSPATIAL_TRACKER_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGeospatialTrackerStateANDROID;

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

הערכים האפשריים הם:

תיאור ה-Enum

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

הכלי למיקום גיאוגרפי לא פועל.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

מכשיר המעקב הגיאו-מרחבי פועל ואפשר להשתמש בו.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

הפעלת הכלי למיקום גיאוגרפי נכשלה, ולא ניתן יהיה להשתמש בו.

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

typedef struct XrEventDataGeospatialTrackerStateChangedANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrGeospatialTrackerANDROID         geospatialTracker;
    XrGeospatialTrackerStateANDROID    state;
    XrResult                           initializationResult;
    XrTime                             time;
} XrEventDataGeospatialTrackerStateChangedANDROID;

תיאורי חברים

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫geospatialTracker הוא XrGeospatialTrackerANDROID שהמצב שלו השתנה.
  • ‫state הוא XrGeospatialTrackerStateANDROID החדש .
  • ‫initializationResult היא תוצאת השגיאה אם state היא XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , אחרת XR_SUCCESS .
  • ‫time הוא XrTime שבו התרחש שינוי המצב.

המבנה XrEventDataGeospatialTrackerStateChangedANDROID נשלח כשמצב הגשש הגיאו-מרחבי משתנה. אם לאפליקציה יש XrGeospatialTrackerANDROID תקין , מומלץ לבצע סקר כדי לזהות את האירוע הזה. האירוע הראשון שמתקבל לגבי כלי מעקב יכלול את הערך state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . אחרי פרק זמן שנקבע בזמן הריצה, הסטטוס חייב להשתנות ל-XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID או ל-XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID . המעבר הזה יימשך פרק זמן לא קבוע. אם הערך של state משתנה ל-XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , זה חייב להיות האירוע האחרון שמתקבל עבור כלי המעקב הזה, ובשדה initializationResult יופיע קוד השגיאה. יכול להיות שיחלפו כמה שניות עד שתופיע שגיאה. במקרה כזה, האפליקציה צריכה להשמיד את מכשיר המעקב. אם state משתנה ל-XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , כל העוגנים הגיאוספציאליים שנוצרו קודם חייבים להפסיק את המעקב לצמיתות וצריכים להימחק על ידי האפליקציה. המצב יכול להשתנות שוב ושוב בין XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID ל-XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID מספר פעמים לא מוגבל.

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

Geospatial Pose

המבנה XrGeospatialPoseANDROID מוגדר באופן הבא:

typedef struct XrGeospatialPoseANDROID {
    XrQuaternionf    eastUpSouthOrientation;
    double           latitude;
    double           longitude;
    double           altitude;
} XrGeospatialPoseANDROID;

תיאורי חברים

  • ‫eastUpSouthOrientation הוא XrQuaternionf שמגדיר את הכיוון ביחס למערכת קואורדינטות שבה ‎+X=East, +Y=Up and +Z=South.
  • ‫latitude הוא קו הרוחב במעלות, בין ‎-90 לבין ‎+90.
  • ‫longitude הוא קו האורך במעלות, בין ‎-180 לבין ‎+180.
  • ‫altitude הוא הגובה מעל פני הים במטרים ביחס לאליפסואיד WGS84.

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

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

  • ‫ התוסף XR_ANDROID_geospatial חייב להיות מופעל לפני שמשתמשים ב-XrGeospatialPoseANDROID
  • הערך של latitude חייב להיות ערך תקין של double
  • הערך של longitude חייב להיות ערך תקין של double
  • הערך של altitude חייב להיות ערך תקין של double

הספירה XrGeospatialPoseFlagBitsANDROID מוגדרת כך:

// Flag bits for XrGeospatialPoseFlagsANDROID
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID = 0x00000001;
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID = 0x00000002;

הספירה XrGeospatialPoseFlagBitsANDROID מציינת דגלים למיקומים גיאומרחביים.

המשמעויות של הביטים של הדגל:

תיאורי הסימונים

  • ‫XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID – מציין שהחבר ב-orientation מכיל נתונים תקינים
  • ‫XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID – מציין שהמיקום של חבר המועדון מכיל נתונים תקינים

הסוג XrGeospatialPoseFlagsANDROID הוא מסיכת ביטים של XrGeospatialPoseFlagBitsANDROID .

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

המרת XrPosef ל-Geospatial Pose

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

XrResult xrLocateGeospatialPoseFromPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseFromPoseLocateInfoANDROID* locateInfo,
    XrGeospatialPoseResultANDROID*              geospatialPoseResult);

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

הפונקציה xrLocateGeospatialPoseFromPoseANDROID ממירה תנוחה ב-XrGeospatialPoseFromPoseLocateInfoANDROID :: space לתנוחה גיאו-מרחבית. אם המצב של geospatialTracker הוא לא XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , סביבת זמן הריצה חייבת להחזיר XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . אם הפונקציה מחזירה XR_SUCCESS , השדה XrGeospatialPoseResultANDROID :: poseFlags של geospatialPoseResult קובע אילו שדות פלט תקפים. אם הערך של XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID לא מוגדר ב-XrGeospatialPoseResultANDROID :: poseFlags , האפליקציה לא יכולה לקרוא את השדות XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy או XrGeospatialPoseResultANDROID :: verticalAccuracy ב-XrGeospatialPoseResultANDROID . אם הערך XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID לא מוגדר ב-XrGeospatialPoseResultANDROID :: poseFlags , האפליקציה לא יכולה לקרוא את XrGeospatialPoseANDROID :: eastUpSouthOrientation או את XrGeospatialPoseResultANDROID :: orientationYawAccuracy . אם לא מגדירים את XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID, אסור להגדיר גם את XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID.

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

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialPoseFromPoseLocateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrPosef            pose;
} XrGeospatialPoseFromPoseLocateInfoANDROID;

תיאורי חברים

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫space הוא XrSpace שבו מוגדר pose.
  • ‫time הוא XrTime שלפיו יש להעריך את pose .
  • ‫pose הוא XrPosef ב-space להמרה לתנוחה גיאו-מרחבית.

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

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

typedef struct XrGeospatialPoseResultANDROID {
    XrStructureType                 type;
    void*                           next;
    XrGeospatialPoseFlagsANDROID    poseFlags;
    XrGeospatialPoseANDROID         geospatialPose;
    double                          horizontalAccuracy;
    double                          verticalAccuracy;
    double                          orientationYawAccuracy;
} XrGeospatialPoseResultANDROID;

תיאורי חברים

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫poseFlags הוא מסיכת ביטים של XrGeospatialPoseFlagsANDROID שמציינת את התוקף של רכיבי המיקום.
  • ‫geospatialPose היא התוצאה של XrGeospatialPoseANDROID .
  • ‫horizontalAccuracy הוא הדיוק האופקי המשוער של מיקום התנוחה הגיאוספציאלית, שמוגדר כרדיוס במטרים של המעגל ברמת סמך של 68% סביב קו הרוחב וקו האורך הנתונים.
  • ‫verticalAccuracy הוא הערך המשוער של הדיוק האנכי של מיקום התנוחה הגיאוספציאלית, שמוגדר כמרחק במטרים ברמת סמך של 68% סביב הגובה הנתון. במילים אחרות, יש סיכוי של 68% שהגובה האמיתי נמצא בטווח [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ].
  • ‫orientationYawAccuracy הוא הדיוק המשוער של זווית הסבסוב של כיוון המיקום הגיאוגרפי, שמוגדר כרדיוס במעלות של רמת סמך של 68% סביב הכיוון הנתון.

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

המרת מיקום גיאו-מרחבי ל-XrPosef

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

XrResult xrLocateGeospatialPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseLocateInfoANDROID*    locateInfo,
    XrSpaceLocation*                            location);

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

הפונקציה xrLocateGeospatialPoseANDROID ממירה מיקום גיאוספציאלי ל-XrSpaceLocation . אם XrGeospatialTrackerANDROID לא פועל, זמן הריצה חייב להחזיר XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . אם הפונקציה מחזירה XR_SUCCESS , השדה XrSpaceLocation :: locationFlags של location קובע אילו שדות פלט תקפים.

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialPoseLocateInfoANDROID {
    XrStructureType            type;
    const void*                next;
    XrSpace                    space;
    XrTime                     time;
    XrGeospatialPoseANDROID    geospatialPose;
} XrGeospatialPoseLocateInfoANDROID;

תיאורי חברים

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫space הוא XrSpace שבו התנוחה שתתקבל תיוצג.
  • ‫time הוא XrTime שבו צריך לאתר את התנוחה.
  • ‫geospatialPose הוא XrGeospatialPoseANDROID להמרה.

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

זמינות של VPS

הספירה XrVPSAvailabilityANDROID מוגדרת כך:

typedef enum XrVPSAvailabilityANDROID {
    XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID = 1,
    XR_VPS_AVAILABILITY_AVAILABLE_ANDROID = 2,
    XR_VPSAVAILABILITY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrVPSAvailabilityANDROID;

הספירה XrVPSAvailabilityANDROID מציינת את הזמינות של VPS.

הערכים האפשריים הם:

תיאור ה-Enum

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

ה-VPS לא זמין בקרבת המיקום שצוין.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

שירות ה-VPS זמין בקרבת המיקום שצוין.

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

XrResult xrCheckVpsAvailabilityAsyncANDROID(
    XrSession                                   session,
    double                                      latitude,
    double                                      longitude,
    XrFutureEXT*                                future);

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

  • ‫session הוא XrSession שמשמש לבדיקה.
  • ‫latitude הוא קו הרוחב במעלות.
  • ‫longitude הוא קו האורך במעלות.
  • ‫future הוא מצביע ל-XrFutureEXT שיכיל את התוצאה של הפעולה האסינכרונית.

הזמינות של שירות מיקום חזותי (VPS) מציינת אם אפשר להשתמש ב-VPS כדי לשפר את הדיוק הגיאוגרפי במיקום מסוים.

הפונקציה xrCheckVpsAvailabilityAsyncANDROID מתחילה בדיקה אסינכרונית של זמינות ה-VPS במיקום נתון. האפליקציה לא צריכה XrGeospatialTrackerANDROID כדי להפעיל את הפונקציה הזו, ויכולה להשתמש בתוצאה של הפעולה הזו כדי להחליט אם ליצור אחת. אם האפליקציה לא קיבלה את ההרשאות הנדרשות, סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_PERMISSION_INSUFFICIENT .

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

  • ‫ חובה להפעיל את התוסף XR_ANDROID_geospatial לפני שמפעילים את xrCheckVpsAvailabilityAsyncANDROID
  • ‫ session חייב להיות מאחז XrSession תקין
  • הערך של latitude חייב להיות ערך תקין של double
  • הערך של longitude חייב להיות ערך תקין של double
  • ‫ future חייב להיות מצביע לערך XrFutureEXT

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCheckVpsAvailabilityCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrVPSAvailabilityCheckCompletionANDROID*    completion);

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

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

המבנה XrVPSAvailabilityCheckCompletionANDROID מוגדר באופן הבא:

typedef struct XrVPSAvailabilityCheckCompletionANDROID {
    XrStructureType             type;
    void*                       next;
    XrResult                    futureResult;
    XrVPSAvailabilityANDROID    availability;
} XrVPSAvailabilityCheckCompletionANDROID;

תיאורי חברים

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫futureResult הוא XrResult של פעולת הבדיקה. אם הערך של futureResult הוא XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , יכול להיות שמבנה בשרשרת next יספק מידע נוסף על הכשל.
  • ‫availability היא התוצאה של XrVPSAvailabilityANDROID . האפליקציה לא יכולה לקרוא את השדה הזה אלא אם הערך של futureResult הוא XR_SUCCESS .

קודי החזרה עתידיים

ערכים של futureResult:

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

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

דוגמה

הגדרת Geospatial Tracker

PFN_xrCheckVpsAvailabilityAsyncANDROID xrCheckVpsAvailabilityAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCheckVpsAvailabilityCompleteANDROID xrCheckVpsAvailabilityCompleteANDROID;
PFN_xrCreateGeospatialTrackerANDROID xrCreateGeospatialTrackerANDROID;
XrInstance instance = XR_NULL_HANDLE;
XrSystemId systemId = XR_NULL_SYSTEM_ID;
XrSession session = XR_NULL_HANDLE;
double lat = 37.422, lng = -122.084;

// Check for support.
XrSystemGeospatialPropertiesANDROID geospatialSystemProperties{
    XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{XR_TYPE_SYSTEM_PROPERTIES,
                                    &geospatialSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!geospatialSystemProperties.supportsGeospatial) {
  return;
}

// Check VPS Availability.
XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCheckVpsAvailabilityAsyncANDROID(session, lat, lng, &future));

XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
pollInfo.future = future;
pollResult.state = XR_FUTURE_STATE_PENDING_EXT;
while (pollResult.state == XR_FUTURE_STATE_PENDING_EXT) {
  // Do in render loop/state loop.
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
}

XrVPSAvailabilityCheckCompletionANDROID vpsCompletion{
    XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID};
CHK_XR(xrCheckVpsAvailabilityCompleteANDROID(session, future, &vpsCompletion));
if (vpsCompletion.futureResult == XR_SUCCESS) {
  if (vpsCompletion.availability == XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID) {
    // Visual Positioning Service is not available. Accuracy of positions and
    // orientations from Geospatial APIs are expected to be lower at this location.
  } else {
    // Visual Positioning Service is available. Higher accuracy of position and
    // orientation is achievable at this location.
  }
}

// Create Geospatial Tracker.
XrGeospatialTrackerCreateInfoANDROID createInfo{
    XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID};
XrGeospatialTrackerANDROID geospatialTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateGeospatialTrackerANDROID(session, &createInfo, &geospatialTracker));

// In application main event loop:
while (true) {
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  if (xrPollEvent(instance, &event) != XR_SUCCESS) {
    continue;
  }
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID:
      const XrEventDataGeospatialTrackerStateChangedANDROID& eventData =
          *reinterpret_cast<XrEventDataGeospatialTrackerStateChangedANDROID*>(&event);
      switch (eventData.state) {
        case XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID:
          // Destroy existing anchors, if any.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID:
          // Start adding content.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID:
          // Handle eventData.initializationResult error result.
          break;
      }
  }
}

קריאה לממשקי ה-API של מיקום גיאוגרפי

PFN_xrLocateGeospatialPoseFromPoseANDROID xrLocateGeospatialPoseFromPoseANDROID;
PFN_xrLocateGeospatialPoseANDROID xrLocateGeospatialPoseANDROID;

XrGeospatialTrackerANDROID geospatialTracker;

// Get pose from view space.
XrSpace viewSpace;
XrPosef identityPose = {{0,0,0,1},{0,0,0}};
XrGeospatialPoseFromPoseLocateInfoANDROID poseGetInfo{
    XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID};
XrGeospatialPoseResultANDROID poseResult{
    XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID};
poseGetInfo.space = viewSpace;
poseGetInfo.pose = identityPose;
poseGetInfo.time = 0;  // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseFromPoseANDROID(geospatialTracker, &poseGetInfo, &poseResult));
if ((poseResult.poseFlags & XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID) &&
    (poseResult.poseFlags & XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID)) {
  // poseResult.geospatialPose is valid.
}

// Convert Geospatial pose to an XrSpaceLocation.
XrGeospatialPoseLocateInfoANDROID poseLocateInfo{
    XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID};
XrSpaceLocation location{XR_TYPE_SPACE_LOCATION};
poseLocateInfo.space = viewSpace;
poseLocateInfo.geospatialPose = poseResult.geospatialPose;
poseLocateInfo.time = 0; // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseANDROID(geospatialTracker, &poseLocateInfo, &location));
if ((location.locationFlags & XR_SPACE_LOCATION_ORIENTATION_VALID_BIT) &&
    (location.locationFlags & XR_SPACE_LOCATION_POSITION_VALID_BIT)) {
  // location.pose is valid.
}

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

פקודות חדשות

מבנים חדשים

New Enums

מסיכות סיביות חדשות

New Enum Constants

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • הרחבה של XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • הרחבה של XrResult :

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • הרחבה של XrStructureType :

    • XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID
    • XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID

בעיות

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

  • גרסה 1, ‏2025-12-18 (בן קינג)

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