XR_ANDROID_spatial_anchor_space

מחרוזת שם

XR_ANDROID_spatial_anchor_space

סוג התוסף

תוסף למכונה

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

796

גרסה

1

סטטוס האישור

לא אושר

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

XR_EXT_spatial_anchor

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

2025-09-15

סטטוס IP

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

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

יושנג צ'אנג, Google
קייל צ'ן, Google
לבנה צ'ן, Google
ניהב ג'יין, Google
ספנסר קווין, Google

סקירה כללית

הפונקציה xrCreateSpatialAnchorEXT שמוגדרת בתוסף XR_EXT_spatial_anchor מאפשרת לאפליקציות ליצור נקודות עיגון במרחב עם נקודת אחיזה (handle) מסוג XrSpatialEntityEXT כדי לייצג אותן. לעומת זאת, התוסף הזה יוצר עוגן מרחבי שמיוצג על ידי נקודת אחיזה של XrSpace. האפשרות הזו שימושית במקרים שבהם האפליקציה רוצה:

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

אי אפשר לשמור עוגנים שנוצרו באמצעות התוסף הזה באמצעות התוסף XR_ANDROID_device_anchor_persistence, ובמקום זאת האפליקציה חייבת להשתמש ב-XR_EXT_spatial_persistence_operations . סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_VALIDATION_FAILURE מ-xrPersistAnchorANDROID אם XrPersistedAnchorSpaceInfoANDROID :: anchor נוצר באמצעות xrCreateSpatialAnchorSpaceANDROID או xrCreateSpatialAnchorSpaceFromIdANDROID .

יצירת XrSpace לעוגן מרחבי

יצירת עוגן מרחבי ומרחב

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

XrResult xrCreateSpatialAnchorSpaceANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpace*                                    anchorSpace);

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

הפונקציה xrCreateSpatialAnchorSpaceANDROID יוצרת נקודת עיגון שמוציאה XrSpatialEntityIdEXT וכינוי XrSpace. לפונקציה xrCreateSpatialAnchorSpaceANDROID יש את אותן דרישות אימות כמו לפונקציה xrCreateSpatialAnchorEXT .

זמן הריצה חייב להחזיר את הערך XR_ERROR_VALIDATION_FAILURE אם XrSpatialContextEXT שהועבר אל xrCreateSpatialAnchorSpaceANDROID לא הוגדר עם XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

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

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

  • ‫ חובה להפעיל את התוסף XR_ANDROID_spatial_anchor_space לפני שקוראים לפונקציה xrCreateSpatialAnchorSpaceANDROID
  • ‫ session חייב להיות כינוי תקין של XrSession
  • spatialContext חייב להיות כינוי תקין של XrSpatialContextEXT
  • ‫ createInfo חייב להיות מצביע למבנה XrSpatialAnchorCreateInfoEXT תקין
  • ‫ anchorEntityId חייב להיות מצביע לערך XrSpatialEntityIdEXT
  • ‫ anchorSpace חייב להיות מצביע לכינוי XrSpace
  • ‫ spatialContext חייב להיווצר, להיות מוקצה או להישלף מ-session

קודי החזרה

הצלחה

  • 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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

יצירת XrSpace מעוגן מרחבי קיים

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

XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorSpace);

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

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

הפונקציה xrCreateSpatialAnchorSpaceFromIdANDROID יוצרת נקודת אחיזה (handle) מסוג XrSpace על ידי ציון XrSpatialEntityIdEXT בשדה XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId.

זמן הריצה חייב להחזיר את הערך XR_ERROR_VALIDATION_FAILURE אם XrSpatialContextEXT שהועבר אל xrCreateSpatialAnchorSpaceFromIdANDROID לא הוגדר עם XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

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

קודי החזרה

הצלחה

  • 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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫anchorEntityId הוא ה-XrSpatialEntityIdEXT של העוגן המרחבי הקיים שממנו יוצרים את ה-XrSpace .

זמן הריצה חייב להחזיר את הערך XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT אם XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId הוא לא מזהה תקין של spatialContext .

זמן הריצה חייב להחזיר את הערך XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID אם XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId הוא לא מזהה ישות תקין של עוגן.

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

מחזור החיים של העוגן

ההורה של נקודת אחיזה מסוג XrSpace הוא XrSession . זה אומר שהכינוי XrSpace שמייצג את נקודת העיגון נשאר תקף גם אחרי ש-xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext או xrCreateSpatialAnchorSpaceANDROID :: spatialContext נהרסים. יצירת XrSpace שמייצג עוגן של ישות מרחבית מאפשרת לאפליקציה להרוס את ה-XrSpatialContextEXT שהוגדר באמצעות XR_SPATIAL_CAPABILITY_ANCHOR_EXT, ועדיין להמשיך לקבל את התנוחה האחרונה של העוגן באמצעות ה-XrSpace שלו עם xrLocateSpaces, כלומר זמן הריצה חייב להמשיך לעקוב אחרי העוגן עד שכל נקודות האחיזה של XrSpace שמייצגות אותו ייהרסו.

קוד לדוגמה

יצירת עוגן מרחבי כ-XrSpace

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

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpace spatialAnchorSpace {XR_NULL_HANDLE}; // XrSpace handle of anchor

// Spatial anchor create info
XrSpatialAnchorCreateInfoEXT createInfo{
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

// Create spatial anchor using the new API
CHK_XR(xrCreateSpatialAnchorSpaceANDROID(session, spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorSpace));

// ...

יצירת XrSpace ממזהה ישות של נקודת עיגון

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

XrSpace anchorSpace = XR_NULL_HANDLE;

// Spatial anchor from XrSpace create info
XrSpatialAnchorSpaceFromIdCreateInfoANDROID createInfoFromId{
  .type = XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID,
  .anchorEntityId = spatialAnchorEntityId,
};

// Create XrSpace handle from spatial anchor ID
CHK_XR(xrCreateSpatialAnchorSpaceFromIdANDROID(session, spatialContext, &createInfoFromId, &anchorSpace));

// ...

פקודות חדשות

מבנים חדשים

קבועי Enum חדשים

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

  • הרחבת XrResult :

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

  • הרחבה של XrStructureType :

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

בעיות

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

  • גרסה 1, 15 בספטמבר 2025 (YuSheng Chang, Kyle Chen)

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