XR_ANDROID_geospatial

מחרוזת שם

XR_ANDROID_geospatial

סוג התוסף

תוסף למכונה

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

790

גרסה

1

סטטוס האישור

לא אושר

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

XR_EXT_future

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

2025-12-18

סטטוס IP

אין תלונות ידועות על הפרת קניין רוחני.

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

ג'ון אולמן, Google
בן קינג, Google
ניהב ג'יין, Google
ג'ארד פינדר, 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 , המערכת לא תומכת בתכונות גיאוגרפיות, ולכן חייבת להחזיר את הערך XR_ERROR_FEATURE_UNSUPPORTED מ-xrCreateGeospatialTrackerANDROID . האפליקציה צריכה להימנע משימוש בפונקציונליות של מידע גיאוגרפי-מרחבי כש-supportsGeospatial הוא XR_FALSE .

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

יצירת נקודת אחיזה של Geospatial Tracker

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

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

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

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

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

אפליקציה יכולה ליצור נקודת אחיזה (handle) מסוג XrGeospatialTrackerANDROID באמצעות קריאה ל-xrCreateGeospatialTrackerANDROID . אפשר להשתמש בכינוי 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 .

בסופו של דבר, צריך לשחרר את נקודת האחיזה XrGeospatialTrackerANDROID באמצעות הפונקציה xrDestroyGeospatialTrackerANDROID.

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • 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

נכשל

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

מצב המעקב הגיאו-מרחבי

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

הערכים של ה-enumerants הם:

תיאור הטיפוס בן המנייה (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 מספר פעמים באופן שרירותי.

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

תנוחה גיאו-מרחבית

המבנה של XrGeospatialPoseANDROID מוגדר כך:

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

תיאורי חברים

  • ‫eastUpSouthOrientation הוא XrQuaternionf שמגדיר את הכיוון ביחס למערכת קואורדינטות שבה ‎+X=מזרח, ‎+Y=למעלה ו-‎+Z=דרום.
  • ‫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 – מציין שהאיבר position מכיל נתונים תקינים

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

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

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

הפונקציה 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 , השדה poseFlags של geospatialPoseResult ב-XrGeospatialPoseResultANDROID קובע אילו שדות פלט תקינים. אם 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

נכשל

  • 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 , השדה locationFlags של XrSpaceLocation :: location קובע אילו שדות פלט תקינים.

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • 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_POSE_INVALID
  • 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.

הערכים של ה-enumerants הם:

תיאור הטיפוס בן המנייה (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

נכשל

  • 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

נכשל

  • 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

נכשל

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

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

דוגמה

הגדרת מעקב גיאו-מרחבי

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

קריאה לממשקי Geospatial Pose 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.
}

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

פקודות חדשות

מבנים חדשים

ערכי Enums חדשים

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

קבועי Enum חדשים

  • 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, 18 בדצמבר 2025 (בן קינג)

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