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

رشته نام

XR_ANDROID_trackables_marker

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

۷۰۸ عدد

بازنگری

۱

وضعیت تصویب

تصویب نشده

وابستگی‌های افزونه و نسخه

XR_ANDROID_trackables

وضعیت منسوخ‌شده

  • توسط افزونه‌ی XR_EXT_spatial_marker_tracking منسوخ شده است

آخرین تاریخ اصلاح

۲۳-۰۷-۲۰۲۵

وضعیت آی‌پی

هیچ ادعای مالکیت معنوی شناخته‌شده‌ای وجود ندارد.

مشارکت‌کنندگان

کریستوفر دوئر، گوگل
دیه‌گو تیپالدی، گوگل
لوانا چن، گوگل
جارد فایندر، گوگل
اسپنسر کوئین، گوگل
نیهاو جین، گوگل
کن مک‌کی، گوگل
دنیل گوتنبرگ، کوالکام

نمای کلی

این افزونه امکان ردیابی نشانگر فیزیکی را فراهم می‌کند و برنامه‌ها را قادر می‌سازد تا محتوای XR را به روشی کارآمد به نشانگرهای فیزیکی متصل کنند.

این افزونه از انواع نشانگرهای شناخته‌شده، به‌ویژه ArUco و April Tags، پشتیبانی می‌کند. این افزونه به زمان‌های اجرا امکان می‌دهد تا به‌صورت اختیاری از تخمین اندازه نشانگر پشتیبانی کنند.

مجوزها

برنامه‌های اندروید باید مجوز 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 یک XrTrackableTrackerANDROID ایجاد می‌کند و همچنین با افزودن XrTrackableMarkerConfigurationANDROID به زنجیره بعدی XrTrackableTrackerCreateInfoANDROID ، یک پیکربندی معتبر برای یک تنظیم تنظیم می‌کند.

اگر 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 به زنجیره next XrTrackableTrackerCreateInfoANDROID :: هنگام فراخوانی xrCreateTrackableTrackerANDROID با تنظیم XrTrackableTrackerCreateInfoANDROID :: trackableType روی XR_TRACKABLE_TYPE_MARKER_ANDROID ، پیکربندی معتبری را تنظیم کند. در غیر این صورت، اگر نوع ردیاب مانند بالا تنظیم شده باشد اما ساختار پیکربندی وجود نداشته باشد یا معتبر نباشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.

اگر یک زمان اجرا از تخمین اندازه نشانگر پشتیبانی کند، برنامه می‌تواند XrTrackableMarkerDatabaseEntryANDROID :: edgeSize در entries XrTrackableMarkerDatabaseANDROID :: روی 0 تنظیم کند تا استفاده از تخمین اندازه را نشان دهد. در غیر این صورت، برنامه باید 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 برای ردیابی تمام نشانگرهای موجود در dictionary 0 تنظیم کند.
  • 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 یک شناسه نشانگر (marker id) واحد از یک دیکشنری را پیکربندی می‌کند.

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

دستورات جدید

سازه‌های جدید

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 (لوانا چن)

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