XR_ANDROID_trackables_marker

מחרוזת שם

XR_ANDROID_trackables_marker

סוג התוסף

הרחבת המכונה

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

708

Revision

1

סטטוס האישור

לא אושר

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

XR_ANDROID_trackables

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

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

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

2025-07-23

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

לא ידוע על תלונות בנושא זכויות יוצרים שקשורות לכתובות 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 . אחרת, אם סוג ה-tracker מוגדר כמו שצוין למעלה אבל מבנה ההגדרה לא קיים או לא תקין, זמן הריצה חייב להחזיר XR_ERROR_VALIDATION_FAILURE .

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

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

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

הספירה 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

Failure

  • 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));

פקודות חדשות

מבנים חדשים

New Enums

New Enum Constants

  • 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 ביולי 2025 (לבנה חן)

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