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;
توضیحات عضو
typeXrStructureType این ساختار است.-
nextبرابر باNULLیا اشارهگری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است. برای جزئیات بیشتر درباره زنجیره ساختار، به ساختاری که درحال گسترش است ( XrSystemProperties ) مراجعه کنید. -
supportsMarkerTrackingیکXrBool32است که نشان میدهد آیا سیستم فعلی قابلیت ردیابی نشانگر را ارائه میدهد یا نه. -
supportsMarkerSizeEstimationیکXrBool32است که نشان میدهد آیا سیستم فعلی تخمین اندازه نشانگر را ارائه میدهد یا نه. maxMarkerCountحداکثر تعداد نشانگرهایی است که زمان اجرا میتواند بهطور همزمان ردیابی کند.
برنامه میتواند با گسترش دادن XrSystemProperties با ساختار XrSystemMarkerTrackingPropertiesANDROID هنگام فراخوانی xrGetSystemProperties بررسی کند که آیا سیستم قادر به ردیابی نشانگر است یا نه. زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED را برای ایجاد ردیاب نشانگر برگرداند اگر و فقط اگر supportsMarkerTracking XR_FALSE باشد.
اگر زمان اجرا از ردیابی نشانگر پشتیبانی کند، maxMarkerCount باید حداقل ۱ باشد.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_markerباید قبلاز استفاده از XrSystemMarkerTrackingPropertiesANDROID فعال شود -
typeبایدXR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROIDباشد -
nextبایدNULLیا اشارهگر معتبری به ساختار بعدی در زنجیره ساختار باشد
نشانگرهای ردیابی
این افزونه 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;
توضیحات عضو
typeXrStructureType این ساختار است.-
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 مطابقت داشته باشد.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_markerباید قبلاز استفاده از XrTrackableMarkerConfigurationANDROID فعال شود -
typeبایدXR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROIDباشد -
nextبایدNULLیا اشارهگر معتبری به ساختار بعدی در زنجیره ساختار باشد -
trackingModeباید مقدار XrTrackableMarkerTrackingModeANDROID معتبری باشد -
databasesباید اشارهگری به آرایهای از ساختارهایdatabaseCountمعتبر XrTrackableMarkerDatabaseANDROID باشد - پارامتر
databaseCountباید بزرگتر از0باشد
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توصیف میکند. برنامه میتواندentryCount0را برای ردیابی همه نشانگرها درdictionaryتنظیم کند.-
entriesاشارهگری به آرایهای از XrTrackableMarkerDatabaseEntryANDROID است که هرکدام حاوی پیکربندی نشانگری برای ردیابی است.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_markerباید قبلاز استفاده از XrTrackableMarkerDatabaseANDROID فعال شود -
dictionaryباید مقدار XrTrackableMarkerDictionaryANDROID معتبری باشد - اگر
entryCountبرابر با0نباشد،entriesباید اشارهگری به آرایهای از ساختارهایentryCountXrTrackableMarkerDatabaseEntryANDROID باشد
شمارشگر 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را برگرداند.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_markerباید پیشاز استفاده از XrTrackableMarkerDatabaseEntryANDROID فعال شود
دریافت نشانگرها
تابع 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_ANDROID_trackables_markerباید قبلاز فراخوانی xrGetTrackableMarkerANDROID فعال شود -
trackerباید شناسه XrTrackableTrackerANDROID معتبری باشد -
getInfoباید اشارهگری به ساختار معتبر XrTrackableGetInfoANDROID باشد -
markerOutputباید اشارهگری به ساختار XrTrackableMarkerANDROID باشد
کدهای برگشتی
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_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;
توضیحات عضو
typeXrStructureType این ساختار است.-
nextبرابر باNULLیا اشارهگری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است. -
trackingStateXrTrackingStateANDROID نشانگر است. lastUpdatedTimeXrTimeآخرین بهروزرسانی نشانگر است.-
dictionaryXrTrackableMarkerDictionaryANDROID نشانگر است. markerIdشناسه نشانگر است که در واژهنامه ارائه شده است.-
centerPoseعبارت است از XrPosef نشانگر واقع در XrTrackableGetInfoANDROID ::baseSpace. نشانگر در صفحه XZ قرار دارد که X به سمت راست نشانگر و Z به پایین آن اشاره میکند و Y بهعنوان بردار نرمال از نشانگر خارج میشود. -
extentsابعاد XrExtent2Df نشانگر است. مرز چارگوش محصورکننده در نقاطcenterPose+/- (extents/ 2) است.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_markerباید پیشاز استفاده از XrTrackableMarkerANDROID فعال شود -
typeبایدXR_TYPE_TRACKABLE_MARKER_ANDROIDباشد -
nextبایدNULLیا اشارهگر معتبری به ساختار بعدی در زنجیره ساختار باشد -
trackingStateباید مقدار XrTrackingStateANDROID معتبری باشد -
dictionaryباید مقدار XrTrackableMarkerDictionaryANDROID معتبری باشد
کد نمونه برای دریافت نشانگرهای قابلردیابی
کد نمونه زیر نحوه دریافت نشانگرهای قابلردیابی را نشان میدهد.
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));
فرمانهای جدید
سازههای جدید
- XrTrackableMarkerANDROID
- XrTrackableMarkerDatabaseANDROID
- XrTrackableMarkerDatabaseEntryANDROID
درحال گسترش دادن XrSystemProperties :
درحال گسترش دادن XrTrackableTrackerCreateInfoANDROID :
Enums جدید
ثابتهای شمارشی جدید
XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAMEXR_ANDROID_trackables_marker_SPEC_VERSIONدرحال گسترش دادن XrStructureType :
XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_MARKER_ANDROIDXR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID
درحال گسترش دادن XrTrackableTypeANDROID :
XR_TRACKABLE_TYPE_MARKER_ANDROID
مشکلات
سابقه نسخه
بازبینی ۱، ۲۰۲۵/۰۷/۲۳ (لوانا چن)
- توضیحات اولیه افزونه.