XR_ANDROID_geospatial_anchor

מחרוזת שם

XR_ANDROID_geospatial_anchor

סוג התוסף

הרחבת המכונה

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

798

Revision

1

סטטוס האישור

לא אושר

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

‫XR_ANDROID_geospatial
וגם
XR_EXT_future
וגם
XR_EXT_spatial_entity
וגם
XR_EXT_spatial_anchor

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

2025-10-30

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

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

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

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

סקירה כללית

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

יכולת המערכת לעיגון גיאו-מרחבי

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

typedef struct XrSystemGeospatialAnchorPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSurfaceAnchorCount;
} XrSystemGeospatialAnchorPropertiesANDROID;

תיאורי חברים

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

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

אם הערך של XrSystemGeospatialPropertiesANDROID :: supportsGeospatial הוא XR_TRUE , אז maxSurfaceAnchorCount מציין את המספר המקסימלי של עוגנים שטחיים שזמן הריצה תומך בהם. במקרה הזה, הסף חייב להיות גדול מ-0.

אם XrSystemGeospatialPropertiesANDROID :: supportsGeospatial הוא לא XR_TRUE , אז maxSurfaceAnchorCount חייב להיות 0.

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

מעקב אחר מישור לעוגנים

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

typedef struct XrGeospatialTrackerAnchorTrackingInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrBool32           shouldTrackPlanes;
} XrGeospatialTrackerAnchorTrackingInfoANDROID;

תיאורי חברים

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫shouldTrackPlanes הוא XrBool32 שמציין אם הכלי למעקב גיאוגרפי יעקוב אחרי מטוסים כדי לשפר את המיקום של עוגנים שמוצמדים למשטח.

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

אם האפליקציה רוצה להפעיל מעקב אחרי מישורים כדי לשפר את מיקומי העוגנים על פני השטח, היא יכולה לשרשר מבנה XrGeospatialTrackerAnchorTrackingInfoANDROID אל XrGeospatialTrackerCreateInfoANDROID כשקוראים ל-xrCreateGeospatialTrackerANDROID .

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

עוגנים גיאו-מרחביים

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

XrResult xrCreateGeospatialAnchorANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrGeospatialAnchorCreateInfoANDROID*  createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId);

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

  • ‫spatialContext הוא XrSpatialContextEXT שבו רוצים ליצור את העוגן. צריך להגדיר את ההקשר עבור XR_SPATIAL_CAPABILITY_ANCHOR_EXT, אחרת זמן הריצה צריך להחזיר XR_ERROR_VALIDATION_FAILURE .
  • ‫createInfo הוא מצביע אל XrGeospatialAnchorCreateInfoANDROID שמכיל פרמטרים ליצירת עוגן.
  • ‫anchorEntityId הוא מצביע אל XrSpatialEntityIdEXT שבו מוחזר מזהה ישות העוגן.

אם XrGeospatialTrackerANDROID שצוין ב-XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker לא נמצא במצב XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, זמן הריצה חייב להחזיר XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

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

קודי החזרה

הצלחה

  • 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_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrGeospatialPoseANDROID       geospatialPose;
} XrGeospatialAnchorCreateInfoANDROID;

תיאורי חברים

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫geospatialTracker הוא XrGeospatialTrackerANDROID שמשמש ליצירת העוגן.
  • ‫geospatialPose הוא מצביע אל XrGeospatialPoseANDROID שמגדיר את המיקום והכיוון של העוגן.

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

עוגנים למשטחים

עוגנים למשטחים הם עוגנים שממוקמים ביחס למשטח, כמו שטח או גגות.

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

typedef enum XrSurfaceAnchorTypeANDROID {
    XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID = 1,
    XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID = 2,
    XR_SURFACE_ANCHOR_TYPE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSurfaceAnchorTypeANDROID;

הספירה XrSurfaceAnchorTypeANDROID מציינת את סוג פני השטח שהעוגן יחסי אליו.

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

תיאור ה-Enum

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

סוג העוגן שמוצב ביחס לקרקע.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

סוג העוגן שמוצב ביחס לגג או לקרקע במקומות שבהם אין בניין.

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

XrResult xrCreateSurfaceAnchorAsyncANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSurfaceAnchorCreateInfoANDROID*     createInfo,
    XrFutureEXT*                                future);

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

  • ‫spatialContext הוא XrSpatialContextEXT שבו רוצים ליצור את העוגן.
  • ‫createInfo הוא מצביע אל XrSurfaceAnchorCreateInfoANDROID שמכיל פרמטרים ליצירת עוגן.
  • ‫future הוא מצביע ל-XrFutureEXT שיכיל את התוצאה של הפעולה האסינכרונית.

הפונקציה xrCreateSurfaceAnchorAsyncANDROID מתחילה פעולה אסינכרונית ליצירת עוגן משטח. בניגוד לעוגנים גיאוספציאליים רגילים, בזמן הריצה יכול להיות שהמערכת תאחזר נתוני פני שטח כדי לקבוע את הגובה הנכון. סביבת זמן הריצה חייבת להחזיר XR_ERROR_LIMIT_REACHED אם האפליקציה מנסה ליצור יותר מ-XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount עוגנים של משטחים בכל פעם. אם XrGeospatialTrackerANDROID שצוין ב-XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker לא נמצא במצב XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, זמן הריצה חייב להחזיר XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . יכול להיות שהפעולה תיכשל באופן אסינכרוני עם התוצאה XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID אם אין נתוני משטח למיקום שצוין. זמן הריצה חייב להחזיר XR_ERROR_VALIDATION_FAILURE אם XR_SPATIAL_CAPABILITY_ANCHOR_EXT לא הוגדר עבור spatialContext .

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

קודי החזרה

הצלחה

  • 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_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSurfaceAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrSurfaceAnchorTypeANDROID    surfaceAnchorType;
    XrQuaternionf                 eastUpSouthOrientation;
    double                        latitude;
    double                        longitude;
    double                        altitudeRelativeToSurface;
} XrSurfaceAnchorCreateInfoANDROID;

תיאורי חברים

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫geospatialTracker הוא XrGeospatialTrackerANDROID שבו רוצים להשתמש.
  • ‫surfaceAnchorType הוא XrSurfaceAnchorTypeANDROID של נקודת העיגון.
  • ‫eastUpSouthOrientation הוא הכיוון ביחס למערכת קואורדינטות שבה ‎+X=מזרח, ‎+Y=למעלה ו-‎+Z=דרום.
  • ‫latitude הוא קו הרוחב במעלות, בין ‎-89.9 לבין ‎+89.9.
  • ‫longitude הוא קו האורך במעלות, בין ‎-180 לבין ‎+180.
  • ‫altitudeRelativeToSurface הוא הגובה במטרים ביחס לפני השטח שצוינו על ידי surfaceAnchorType .

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

  • התוסף XR_ANDROID_geospatial_anchor חייב להיות מופעל לפני שמשתמשים ב-XrSurfaceAnchorCreateInfoANDROID
  • ‫ type חייב להיות XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
  • ‫ next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים
  • ‫ geospatialTracker חייב להיות נקודת אחיזה תקינה של XrGeospatialTrackerANDROID
  • ‫ surfaceAnchorType חייב להיות ערך תקין של XrSurfaceAnchorTypeANDROID
  • הערך של latitude חייב להיות ערך תקין של double
  • הערך של longitude חייב להיות ערך תקין של double
  • הערך של altitudeRelativeToSurface חייב להיות ערך תקין של double

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

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     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_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

המבנה XrSurfaceAnchorCreateCompletionANDROID מכיל את התוצאה של יצירת עוגן אסינכרוני של משטח.

typedef struct XrSurfaceAnchorCreateCompletionANDROID {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSurfaceAnchorCreateCompletionANDROID;

תיאורי חברים

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫futureResult הוא XrResult של פעולת היצירה. אם הערך של futureResult הוא XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , יכול להיות שמבנה בשרשרת next יספק מידע נוסף על הכשל.
  • ‫anchorEntityId הוא XrSpatialEntityIdEXT של העוגן שנוצר, או XR_NULL_SPATIAL_ENTITY_ID_EXT אם 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_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

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

דוגמה

יצירת עוגן לטופוגרפיה

PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
PFN_xrCreateSurfaceAnchorAsyncANDROID xrCreateSurfaceAnchorAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCreateSurfaceAnchorCompleteANDROID xrCreateSurfaceAnchorCompleteANDROID;
XrInstance instance;
XrSession session;
XrGeospatialTrackerANDROID geospatialTracker;

// Create a spatial context
XrSpatialContextEXT spatialContext{};
{
  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  XrSpatialCapabilityConfigurationAnchorEXT
       anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  // ... wait until future is ready ...

  XrCreateSpatialContextCompletionEXT contextCompletion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &contextCompletion));
  if (contextCompletion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = contextCompletion.spatialContext;
}

XrSurfaceAnchorCreateInfoANDROID anchorCreateInfo{
    XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID};
anchorCreateInfo.surfaceAnchorType = XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID;
anchorCreateInfo.eastUpSouthOrientation = {0, 0, 0, 1};
anchorCreateInfo.latitude = 37.7749;
anchorCreateInfo.longitude = -122.4194;
anchorCreateInfo.altitudeRelativeToSurface = 0;
anchorCreateInfo.geospatialTracker = geospatialTracker;
XrFutureEXT anchorFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSurfaceAnchorAsyncANDROID(spatialContext, &anchorCreateInfo, &anchorFuture));

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

XrSurfaceAnchorCreateCompletionANDROID anchorCompletion{
    XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID};
CHK_XR(xrCreateSurfaceAnchorCompleteANDROID(spatialContext, anchorFuture, &anchorCompletion));
if (anchorCompletion.futureResult == XR_SUCCESS) {
  // Use completion.anchorEntityId.
  XrSpatialEntityIdEXT anchorId = anchorCompletion.anchorEntityId;

  // Query in UpdateSnapshot.
}

פקודות חדשות

מבנים חדשים

New Enums

New Enum Constants

  • XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_geospatial_anchor_SPEC_VERSION

  • הרחבה של XrResult :

    • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID

  • הרחבה של XrStructureType :

    • XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID

בעיות

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

  • גרסה 1, ‏30 באוקטובר 2025 (בן קינג)

    • טיוטה ראשונית.