XR_ANDROID_trackables_marker

מחרוזת שם

XR_ANDROID_trackables_marker

סוג התוסף

תוסף למכונה

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

708

גרסה

1

סטטוס האישור

לא אושר

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

XR_ANDROID_trackables

מצב ההוצאה משימוש

  • הוצא משימוש על ידי התוסף XR_EXT_spatial_marker_tracking

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

2025-07-23

סטטוס IP

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

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

Christopher Doer, Google
Diego Tipaldi, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Ken Mackay, Google
Daniel Guttenberg, Qualcomm

סקירה כללית

התוסף הזה מאפשר מעקב אחרי סמנים פיזיים, ומאפשר לאפליקציות לצרף תוכן XR לסמנים פיזיים בצורה יעילה.

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

הרשאות

אפליקציות ל-Android חייבות לכלול את ההרשאה android.permission.SCENE_UNDERSTANDING_COARSE במניפסט שלהן, כי התוסף הזה תלוי ב-XR_ANDROID_trackables וחושף את הגיאומטריה של הסביבה. ההרשאה android.permission.SCENE_UNDERSTANDING_COARSE נחשבת להרשאה מסוכנת, כלומר אפליקציות חייבות לבקש את ההרשאה באופן מפורש.

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

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

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

typedef struct XrSystemMarkerTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsMarkerTracking;
    XrBool32           supportsMarkerSizeEstimation;
    uint16_t           maxMarkerCount;
} XrSystemMarkerTrackingPropertiesANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה. לפרטים נוספים על שרשרת המבנים, אפשר לעיין במבנה המורחב ( XrSystemProperties ).
  • ‫supportsMarkerTracking הוא XrBool32 שמציין אם המערכת הנוכחית מספקת יכולת מעקב אחר סמנים.
  • ‫supportsMarkerSizeEstimation הוא XrBool32 שמציין אם המערכת הנוכחית מספקת הערכה של גודל הסמן.
  • ‫maxMarkerCount הוא המספר המקסימלי של סמנים שסביבת זמן הריצה יכולה לעקוב אחריהם בו-זמנית.

אפליקציה יכולה לבדוק אם המערכת מסוגלת לעקוב אחרי סמנים על ידי הרחבת XrSystemProperties באמצעות המבנה XrSystemMarkerTrackingPropertiesANDROID כשקוראים ל-xrGetSystemProperties . זמן הריצה חייב להחזיר את הערך XR_ERROR_FEATURE_UNSUPPORTED ליצירת מעקב אחר סמנים אם ורק אם הערך של supportsMarkerTracking הוא XR_FALSE .

אם סביבת זמן הריצה תומכת במעקב אחר סמנים, הערך של maxMarkerCount חייב להיות לפחות 1.

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

סמני מעקב

התוסף הזה מוסיף את XR_TRACKABLE_TYPE_MARKER_ANDROID ל-XrTrackableTypeANDROID .

האפליקציה יוצרת XrTrackableTrackerANDROID על ידי קריאה ל-xrCreateTrackableTrackerANDROID וציון XR_TRACKABLE_TYPE_MARKER_ANDROID כסוג שניתן למעקב ב-XrTrackableTrackerCreateInfoANDROID :: trackableType, וגם הגדרת תצורה תקינה על ידי הוספת XrTrackableMarkerConfigurationANDROID לשרשרת הבאה של XrTrackableTrackerCreateInfoANDROID .

זמן הריצה חייב להחזיר את הערך XR_ERROR_FEATURE_UNSUPPORTED אם XrTrackableTrackerCreateInfoANDROID :: trackableType הוא XR_TRACKABLE_TYPE_MARKER_ANDROID ו-XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking מחזיר את הערך XR_FALSE דרך xrGetSystemProperties .

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

typedef struct XrTrackableMarkerConfigurationANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrTrackableMarkerTrackingModeANDROID       trackingMode;
    uint32_t                                   databaseCount;
    const XrTrackableMarkerDatabaseANDROID*    databases;
} XrTrackableMarkerConfigurationANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫trackingMode הוא XrTrackableMarkerTrackingModeANDROID שמציין את המצב הרצוי למעקב.
  • ‫databaseCount הוא uint32_t שמתאר את מספר הרכיבים במערך databases.
  • ‫databases הוא מצביע למערך של XrTrackableMarkerDatabaseANDROID , שכל אחד מהם מכיל את הסמנים הרצויים ממילון נתון למעקב.

האפליקציה חייבת להגדיר תצורה תקינה על ידי הוספת XrTrackableMarkerConfigurationANDROID לשרשרת XrTrackableTrackerCreateInfoANDROID :: next כשקוראים ל-xrCreateTrackableTrackerANDROID עם XrTrackableTrackerCreateInfoANDROID :: trackableType שמוגדר ל-XR_TRACKABLE_TYPE_MARKER_ANDROID . אחרת, אם סוג המעקב מוגדר כמו שצוין למעלה אבל מבנה ההגדרה לא קיים או לא תקין, זמן הריצה חייב להחזיר את הערך XR_ERROR_VALIDATION_FAILURE .

אם סביבת זמן הריצה תומכת בהערכת גודל הסמן, האפליקציה יכולה להגדיר את XrTrackableMarkerDatabaseEntryANDROID :: edgeSize ל-0 ב-XrTrackableMarkerDatabaseANDROID :: entries כדי לציין את השימוש בהערכת הגודל. אחרת, האפליקציה חייבת להגדיר את XrTrackableMarkerDatabaseEntryANDROID :: edgeSize לערך חיובי, או שזמן הריצה חייב להחזיר את XR_ERROR_VALIDATION_FAILURE .

זמן הריצה חייב לסנן את הפלט מ-xrGetAllTrackablesANDROID כך שיתאים ל-trackingMode ול-XrTrackableMarkerDatabaseEntryANDROID :: edgeSize .

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

ה-enum‏ XrTrackableMarkerTrackingModeANDROID מתאר את מצבי המעקב הנתמכים של סמנים.

typedef enum XrTrackableMarkerTrackingModeANDROID {
    XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_TRACKABLE_MARKER_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerTrackingModeANDROID;

תיאורי ערכים מספריים

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID — מעקב אחרי סמנים דינמיים. המצב הזה הוא הכי מדויק ופועל על סמנים סטטיים ונעים, אבל גם צורך הכי הרבה חשמל.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID — מעקב אחרי סמנים סטטיים. המצב הזה שימושי בעיקר לסמנים שידוע שהם סטטיים, והוא מוביל לצריכת חשמל נמוכה יותר בהשוואה למצב הדינמי.

המבנה XrTrackableMarkerDatabaseANDROID מגדיר מילון ומזהי סמנים תואמים למעקב.

typedef struct XrTrackableMarkerDatabaseANDROID {
    XrTrackableMarkerDictionaryANDROID              dictionary;
    uint32_t                                        entryCount;
    const XrTrackableMarkerDatabaseEntryANDROID*    entries;
} XrTrackableMarkerDatabaseANDROID;

תיאורי חברים

  • ‫dictionary הוא XrTrackableMarkerDictionaryANDROID שכל entries שייכים אליו.
  • ‫entryCount הוא uint32_t שמתאר את מספר הרכיבים במערך entries. האפליקציה יכולה להגדיר את entryCount 0 כדי לעקוב אחרי כל הסמנים ב-dictionary .
  • ‫entries הוא מצביע למערך של XrTrackableMarkerDatabaseEntryANDROID , שכל אחד מהם מכיל את ההגדרה של סמן למעקב.

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

ה-enum‏ XrTrackableMarkerDictionaryANDROID מתאר את מילוני הסמנים הנתמכים.

typedef enum XrTrackableMarkerDictionaryANDROID {
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID = 0,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_100_ANDROID = 1,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_250_ANDROID = 2,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_1000_ANDROID = 3,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_50_ANDROID = 4,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_100_ANDROID = 5,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_250_ANDROID = 6,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_1000_ANDROID = 7,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_50_ANDROID = 8,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_100_ANDROID = 9,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_250_ANDROID = 10,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_1000_ANDROID = 11,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_50_ANDROID = 12,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_100_ANDROID = 13,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_250_ANDROID = 14,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_1000_ANDROID = 15,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_16H5_ANDROID = 16,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_25H9_ANDROID = 17,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H10_ANDROID = 18,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H11_ANDROID = 19,
    XR_TRACKABLE_MARKER_DICTIONARY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerDictionaryANDROID;

המבנה XrTrackableMarkerDatabaseEntryANDROID מגדיר מזהה סמן יחיד של מילון.

typedef struct XrTrackableMarkerDatabaseEntryANDROID {
    int32_t    id;
    float      edgeSize;
} XrTrackableMarkerDatabaseEntryANDROID;

תיאורי חברים

  • ‫id הוא מזהה הסמן כפי שמופיע במילון.
  • ‫edgeSize מייצג את גודל קצה הסמן במטרים. אם זמן הריצה תומך בהערכת גודל הסמן, האפליקציה יכולה להגדיר את הערך הזה כאפס וגודל הסמן יוערך אונליין. אם הערך הזה מוגדר כאפס אבל זמן הריצה לא תומך בהערכת גודל הסמן, זמן הריצה חייב להחזיר את הערך XR_ERROR_VALIDATION_FAILURE .

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

איך מקבלים חומרי הדפסה

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

XrResult xrGetTrackableMarkerANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableMarkerANDROID*                   markerOutput);

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

זמן הריצה חייב להחזיר את הערך XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID אם הסוג שניתן למעקב של XrTrackableANDROID הוא לא XR_TRACKABLE_TYPE_MARKER_ANDROID , או אם הסוג שניתן למעקב של XrTrackableTrackerANDROID הוא לא XR_TRACKABLE_TYPE_MARKER_ANDROID .

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrTrackableMarkerANDROID {
    XrStructureType                       type;
    void*                                 next;
    XrTrackingStateANDROID                trackingState;
    XrTime                                lastUpdatedTime;
    XrTrackableMarkerDictionaryANDROID    dictionary;
    int32_t                               markerId;
    XrPosef                               centerPose;
    XrExtent2Df                           extents;
} XrTrackableMarkerANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
  • ‫trackingState הוא ה-XrTrackingStateANDROID של הסמן.
  • ‫lastUpdatedTime הוא XrTime של העדכון האחרון של הסמן.
  • ‫dictionary הוא ה-XrTrackableMarkerDictionaryANDROID של הסמן.
  • ‫markerId הוא מזהה הסמן כפי שמופיע במילון.
  • ‫centerPose הוא ה-XrPosef של הסמן שנמצא ב-XrTrackableGetInfoANDROID :: baseSpace . הסמן נמצא במישור XZ, כאשר ציר X מצביע ימינה מהסמן, ציר Z מצביע לתחתית הסמן וציר Y יוצא מהסמן כנורמל.
  • ‫extents הוא המידות של הסמן ב-XrExtent2Df. הגבול של התיבה התוחמת נמצא בנקודות: ‎centerPose +/- ( extents / 2).

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

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

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

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session;   // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // previously initialized
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // previously initialized
PFN_xrGetTrackableMarkerANDROID xrGetTrackableMarkerANDROID;           // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace;  // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.

// Inspect system capability
XrSystemMarkerTrackingPropertiesANDROID markerProperty {
  .type = XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &markerProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!markerProperty.supportsMarkerTracking) {
    // Marker tracking is not supported.
    return;
}

// Create a trackable tracker for marker tracking.
// If the runtime does not support size estimation, configures marker edge size of 0.1m.
XrTrackableMarkerDatabaseEntryANDROID markerEntries {
  .id = 0,
  .edgeSize = markerProperty.supportsMarkerSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableMarkerDatabaseANDROID markerDatabases {
  .dictionary = XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID,
  .entryCount = 1,
  .entries = &markerEntries,
};
XrTrackableMarkerConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID,
  .databaseCount = 1,
  .databases = &markerDatabases,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_MARKER_ANDROID,
};
XrTrackableTrackerANDROID markerTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &markerTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get markers.
std::vector<XrTrackableANDROID> trackables(markerProperty.maxMarkerCount);
std::vector<XrTrackableMarkerANDROID> markers(markerProperty.maxMarkerCount, {
  .type = XR_TYPE_TRACKABLE_MARKER_ANDROID,
  .next = nullptr,
});
uint32_t markerSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(markerTracker, markerProperty.maxMarkerCount, &markerSize,
                                 trackables.data()));
for (int i = 0; i < markerSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables[i],
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableMarkerANDROID(markerTracker, &getInfo, &markers[i]));
    // Handle markers.
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(markerTracker));

פקודות חדשות

מבנים חדשים

ערכי Enums חדשים

קבועי Enum חדשים

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • הרחבה של XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • הרחבה של XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

בעיות

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

  • גרסה 1, 23.07.2025 (לבנה חן)

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