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

نمای کلی

این افزونه ردیابی نشانگر فیزیکی را فعال می‌کند و به برنامه‌ها امکان می‌دهد محتوای «واقعیت گسترده» را به‌طور کارآمد به نشانگرهای فیزیکی پیوست کنند.

این افزونه از انواع نشانگرهای شناخته‌شده، به‌ویژه 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 باید حداقل ۱ باشد.

استفاده معتبر (ضمنی)

نشانگرهای ردیابی

این افزونه XR_TRACKABLE_TYPE_MARKER_ANDROID را به XrTrackableTypeANDROID اضافه می‌کند.

برنامه با فراخوانی xrCreateTrackableTrackerANDROID و مشخص کردن XR_TRACKABLE_TYPE_MARKER_ANDROID به‌عنوان نوع قابل‌ردیابی در XrTrackableTrackerCreateInfoANDROID :: trackableType و همچنین تنظیم پیکربندی معتبر با افزودن XrTrackableMarkerConfigurationANDROID به زنجیره بعدی XrTrackableTrackerCreateInfoANDROID، یک XrTrackableTrackerANDROID ایجاد می‌کند.

اگر XrTrackableTrackerCreateInfoANDROID :: trackableType برابر با XR_TRACKABLE_TYPE_MARKER_ANDROID باشد و XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking ازطریق xrGetSystemProperties مقدار XR_FALSE را برگرداند، زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED را برگرداند.

ساختار 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 مطابقت داشته باشد.

استفاده معتبر (ضمنی)

‫XrTrackableMarkerTrackingModeANDROID enum حالت‌های ردیابی پشتیبانی‌شده نشانگرها را شرح می‌دهد.

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 است که هرکدام حاوی پیکربندی نشانگری برای ردیابی است.

استفاده معتبر (ضمنی)

شمارشگر 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);

شرح پارامترها

  • ‫tracker همان XrTrackableTrackerANDROID برای پُرسمان است.
  • ‫getInfo همان XrTrackableGetInfoANDROID است که اطلاعات استفاده‌شده برای دریافت نشانگر قابل‌ردیابی را دارد.
  • ‫markerOutput اشاره‌گری به ساختار XrTrackableMarkerANDROID است که در آن نشانگر قابل‌ردیابی برگردانده می‌شود.

اگر نوع قابل‌ردیابی XrTrackableANDROID XR_TRACKABLE_TYPE_MARKER_ANDROID نباشد، یا اگر نوع قابل‌ردیابی XrTrackableTrackerANDROID XR_TRACKABLE_TYPE_MARKER_ANDROID نباشد، زمان اجرا باید XR_ERROR_MISMATCHING_TRACKABLE_TYPE_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 جدید

ثابت‌های شمارشی جدید

  • 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

مشکلات

سابقه نسخه

  • بازبینی ۱،‏ ۲۰۲۵/۰۷/۲۳ (لوانا چن)

    • توضیحات اولیه افزونه.