XR_ANDROID_geospatial_anchor

מחרוזת שם

XR_ANDROID_geospatial_anchor

סוג התוסף

תוסף למכונה

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

798

גרסה

1

סטטוס האישור

לא אושר

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

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

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

2025-10-30

סטטוס IP

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

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

ג'ון אולמן, Google
בן קינג, Google
ניהב ג'יין, Google
ג'ארד פינדר, 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

נכשל

  • 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_POSE_INVALID
  • 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 מציינת את סוג פני השטח שהעוגן קשור אליהם.

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

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

נכשל

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

נכשל

  • 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

נכשל

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

פקודות חדשות

מבנים חדשים

ערכי Enums חדשים

קבועי Enum חדשים

  • 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.10.2025 (בן קינג)

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