XR_ANDROID_trackables_image
رشته نام
XR_ANDROID_trackables_image
نوع افزونه
افزونه نمونه
شماره داخلی ثبتشده
710
بازبینی
1
وضعیت تصویب
تصویبنشده
وابستگیهای افزونه و نسخه
XR_EXT_future
و
XR_ANDROID_trackables
تاریخ آخرین تغییر
2025-04-08
وضعیت IP
هیچ ادعای مالکیت فکری شناختهشدهای وجود ندارد.
همیاران
Christopher Doer، Google
Levana Chen، Google
Jared Finder، Google
Spencer Quin، Google
Nihav Jain، Google
Diego Tipaldi، Google
Daniel Guttenberg، Qualcomm
Mark Vadasi، Qualcomm
Markus Birkner، Qualcomm
Maximilian Mayer، Qualcomm
نمای کلی
این افزونه امکان ردیابی تصاویر مسطح را طبق مجموعههای تصاویر مرجع ورودی فراهم میکند.
اجازهها
برنامههای Android باید اجازه android.permission.SCENE_UNDERSTANDING_COARSE را در مانیفست خود فهرست کنند زیرا این افزونه به XR_ANDROID_trackables وابسته است و هندسه محیط را نشان میدهد. اجازه android.permission.SCENE_UNDERSTANDING_COARSE یک اجازه خطرناک محسوب میشود.
(سطح محافظت: خطرناک)
بازرسی کردن قابلیت سیستم
ساختار XrSystemImageTrackingPropertiesANDROID بهصورت زیر تعریف میشود:
typedef struct XrSystemImageTrackingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsImageTracking;
XrBool32 supportsPhysicalSizeEstimation;
uint32_t maxTrackedImageCount;
uint32_t maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;
توضیحات عضو
typeXrStructureType این ساختار است.-
nextبرابر باNULLیا اشارهگری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است. برای جزئیات بیشتر درباره زنجیره ساختار، به ساختاری که درحال گسترش است ( XrSystemProperties ) مراجعه کنید. supportsImageTrackingیکXrBool32است که نشان میدهد آیا سیستم فعلی قابلیت ردیابی تصویر را ارائه میدهد یا نه.supportsPhysicalSizeEstimationیکXrBool32است که نشان میدهد آیا سیستم فعلی تخمین اندازه تصویر را ارائه میدهد یا نه.maxTrackedImageCountحداکثر تعداد کل تصاویری است که میتوان بهطور همزمان ردیابی کرد.maxLoadedImageCountحداکثر تعداد کل تصاویر مرجعی است که میتواند در همه پایگاههای داده بار شود.
برنامه میتواند با گسترش دادن XrSystemProperties با ساختار XrSystemImageTrackingPropertiesANDROID هنگام فراخوانی xrGetSystemProperties بررسی کند که آیا سیستم قادر به ردیابی تصویر است یا نه. زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED را برای ایجاد ردیاب تصویر برگرداند اگر و فقط اگر supportsImageTracking XR_FALSE باشد.
اگر زمان اجرا از ردیابی تصویر پشتیبانی کند، باید از maxTrackedImageCount تصویر ردیابیشده در هر زمان مشخص پشتیبانی کند.
اگر زمان اجرا از ردیابی تصویر پشتیبانی کند، باید از maxLoadedImageCount تصویر بارشده در هر زمان مشخص پشتیبانی کند.
اگر زمان اجرا از تخمین اندازه تصویر پشتیبانی کند، برنامه میتواند XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0 را برای نشان دادن استفاده از تخمین اندازه تنظیم کند. درغیراینصورت، برنامه باید XrTrackableImageDatabaseEntryANDROID :: physicalWidth را روی مقدار مثبت تنظیم کند، درغیراینصورت XR_ERROR_VALIDATION_FAILURE برگردانده خواهد شد.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید قبلاز استفاده از XrSystemImageTrackingPropertiesANDROID فعال شود -
typeبایدXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDباشد -
nextبایدNULLیا اشارهگر معتبری به ساختار بعدی در زنجیره ساختار باشد
درحال ایجاد پایگاههای داده
برنامه میتواند با ایجاد یک یا چند ساختار XrTrackableImageDatabaseEntryANDROID و ارسال آنها به تابع xrCreateTrackableImageDatabaseAsyncANDROID ازطریق ساختار XrTrackableImageDatabaseCreateInfoANDROID، یک دسته XrTrackableImageDatabaseANDROID ایجاد کند.
برنامه باید حداقل یک XrTrackableImageDatabaseEntryANDROID هنگام ایجاد دسته XrTrackableImageDatabaseANDROID ارائه دهد.
XrTrackableImageDatabaseANDROID شناسهای است که مجموعهای از تصاویر مرجع پردازششده را نشان میدهد که میتوانند در محیط شناسایی و ردیابی شوند.
XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)
ساختار XrTrackableImageDatabaseEntryANDROID بهصورت زیر تعریف میشود:
typedef struct XrTrackableImageDatabaseEntryANDROID {
XrStructureType type;
const void* next;
XrTrackableImageTrackingModeANDROID trackingMode;
float physicalWidth;
uint32_t imageWidth;
uint32_t imageHeight;
XrTrackableImageFormatANDROID format;
uint32_t bufferSize;
const uint8_t* buffer;
} XrTrackableImageDatabaseEntryANDROID;
توضیحات عضو
typeXrStructureType این ساختار است.-
nextبرابر باNULLیا اشارهگری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است. -
trackingModeیک XrTrackableImageTrackingModeANDROID است که حالت مطلوب برای ردگیری را نشان میدهد. physicalWidthنشاندهنده عرض تصویر به متر است. اگر صفر باشد، اندازه تصویر بهصورت آنلاین تخمین زده میشود.imageWidthنشاندهنده عرض تصویر به پیکسل است.imageHeightنشاندهنده ارتفاع تصویر به پیکسل است.-
formatیک XrTrackableImageFormatANDROID است که قالب دادههای تصویر را درbufferنشان میدهد. bufferSizeنشاندهنده طول بایتbufferاست.bufferمیانگیرuint8_tاست که حاوی دادههای پیکسل تصویر مرجع است. محتویاتbufferباید برای مدت عملیات ناهمگام ایجاد پایگاه داده معتبر باشد، که توسط xrCreateTrackableImageDatabaseAsyncANDROID شروع میشود و توسط xrCreateTrackableImageDatabaseCompleteANDROID تکمیل میشود.
اگر XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation برابر با XR_TRUE باشد، برنامه میتواند physicalWidth را روی ۰ تنظیم کند تا تخمین اندازه آنلاین را درخواست کند.
اگر bufferSize با اندازه موردانتظار براساس imageWidth، imageHeight، و format ورودی مطابقت نداشته باشد، زمان اجرا ممکن است XR_ERROR_VALIDATION_FAILURE را از xrCreateTrackableImageDatabaseAsyncANDROID برگرداند.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید قبلاز استفاده از XrTrackableImageDatabaseEntryANDROID فعال شود -
typeبایدXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROIDباشد -
nextبایدNULLیا اشارهگر معتبری به ساختار بعدی در زنجیره ساختار باشد -
trackingModeباید مقدار XrTrackableImageTrackingModeANDROID معتبری باشد -
formatباید مقدار XrTrackableImageFormatANDROID معتبری باشد -
bufferباید اشارهگری به آرایهای از مقادیرbufferSizeuint8_tباشد - پارامتر
bufferSizeباید بزرگتر از0باشد
ساختار XrTrackableImageDatabaseCreateInfoANDROID بهصورت زیر تعریف میشود:
typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
XrStructureType type;
const void* next;
uint32_t entryCount;
const XrTrackableImageDatabaseEntryANDROID* entries;
} XrTrackableImageDatabaseCreateInfoANDROID;
توضیحات عضو
typeXrStructureType این ساختار است.-
nextبرابر باNULLیا اشارهگری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است. -
entryCountیکuint32_tاست که تعداد عناصر را در آرایهentriesمشخص میکند. -
entriesآرایهای از ساختارهای XrTrackableImageDatabaseEntryANDROID است.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید پیشاز استفاده از XrTrackableImageDatabaseCreateInfoANDROID فعال شود -
typeبایدXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDباشد -
nextبایدNULLیا اشارهگر معتبری به ساختار بعدی در زنجیره ساختار باشد -
entriesباید اشارهگری به آرایهای از ساختارهای معتبرentryCountXrTrackableImageDatabaseEntryANDROID باشد - پارامتر
entryCountباید بزرگتر از0باشد
ساختار XrCreateTrackableImageDatabaseCompletionANDROID بهصورت زیر تعریف میشود:
typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrTrackableImageDatabaseANDROID database;
} XrCreateTrackableImageDatabaseCompletionANDROID;
توضیحات عضو
typeXrStructureType این ساختار است.-
nextبرابر باNULLیا اشارهگری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است. -
futureResultعبارت است از XrResult عملیات ناهمگام. -
databaseدسته XrTrackableImageDatabaseANDROID ایجادشده است.
کدهای برگشتی آتی
مقادیر futureResult:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید قبلاز استفاده از XrCreateTrackableImageDatabaseCompletionANDROID فعال شود -
typeبایدXR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROIDباشد -
nextبایدNULLیا اشارهگر معتبری به ساختار بعدی در زنجیره ساختار باشد -
futureResultباید مقدار XrResult معتبری باشد -
databaseباید یک دسته XrTrackableImageDatabaseANDROID معتبر باشد
تابع xrCreateTrackableImageDatabaseAsyncANDROID بهصورت زیر تعریف میشود:
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
شرح پارامترها
sessionدستگیرهای برای XrSession است که قبلاً با xrCreateSession ایجاد شده است.-
createInfoاشارهگری به ساختار XrTrackableImageDatabaseCreateInfoANDROID است. -
futureاشارهگری بهXrFutureEXTایجادشده است.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید قبلاز فراخوانی xrCreateTrackableImageDatabaseAsyncANDROID فعال شود -
sessionباید یک دسته XrSession معتبر باشد -
createInfoباید اشارهگری به ساختار معتبر XrTrackableImageDatabaseCreateInfoANDROID باشد -
futureباید اشارهگری به مقدارXrFutureEXTباشد
کدهای برگشتی
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
تابع xrCreateTrackableImageDatabaseCompleteANDROID بهصورت زیر تعریف میشود:
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
شرح پارامترها
sessionدستگیرهای برای XrSession است که قبلاً با xrCreateSession ایجاد شده است.futureXrFutureEXTآینده برای تکمیل است.-
completionاشارهگری به ساختار XrCreateTrackableImageDatabaseCompletionANDROID است که حاوی نتیجه عملیات است.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید قبلاز فراخوانی xrCreateTrackableImageDatabaseCompleteANDROID فعال شود -
sessionباید یک دسته XrSession معتبر باشد -
completionباید اشارهگری به ساختار XrCreateTrackableImageDatabaseCompletionANDROID باشد
کدهای برگشتی
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
تابع xrDestroyTrackableImageDatabaseANDROID بهصورت زیر تعریف میشود:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
شرح پارامترها
-
databaseدسته XrTrackableImageDatabaseANDROID برای نابود کردن است.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید قبلاز فراخوانی xrDestroyTrackableImageDatabaseANDROID فعال شود -
databaseباید یک دسته XrTrackableImageDatabaseANDROID معتبر باشد
ایمنی رشتهای
- دسترسی به
databaseو هرگونه دسته فرزند باید بهصورت خارجی همگامسازی شود
کدهای برگشتی
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
تصاویر ردیابی
این افزونه XR_TRACKABLE_TYPE_IMAGE_ANDROID را به XrTrackableTypeANDROID اضافه میکند.
برنامه میتواند با فراخوانی xrCreateTrackableTrackerANDROID و مشخص کردن XR_TRACKABLE_TYPE_IMAGE_ANDROID بهعنوان نوع قابلردیابی در XrTrackableTrackerCreateInfoANDROID :: trackableType، یک XrTrackableTrackerANDROID برای ردیابی تصاویر ایجاد کند.
اگر XrTrackableTrackerCreateInfoANDROID :: trackableType برابر با XR_TRACKABLE_TYPE_IMAGE_ANDROID باشد و XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking ازطریق xrGetSystemProperties مقدار XR_FALSE را برگرداند، زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED را برگرداند.
ساختار XrTrackableImageConfigurationANDROID بهصورت زیر تعریف میشود:
typedef struct XrTrackableImageConfigurationANDROID {
XrStructureType type;
const void* next;
uint32_t databaseCount;
const XrTrackableImageDatabaseANDROID* databases;
} XrTrackableImageConfigurationANDROID;
توضیحات عضو
typeXrStructureType این ساختار است.-
nextبرابر باNULLیا اشارهگری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است. databaseCountیکuint32_tاست که تعداد عناصر را درdatabasesمشخص میکند-
databasesآرایهای از XrTrackableImageDatabaseANDROID است که پایگاههای دادهای را که ردیاب با آنها ایجاد میشود مشخص میکند.
برنامه باید با افزودن XrTrackableImageConfigurationANDROID به زنجیره next از XrTrackableTrackerCreateInfoANDROID، پیکربندی معتبری تنظیم کند. درغیراینصورت، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند.
برنامه باید حداقل یک ساختار XrTrackableImageDatabaseANDROID ارائه دهد تا ردیاب با آن ایجاد شود.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید قبلاز استفاده از XrTrackableImageConfigurationANDROID فعال شود -
typeبایدXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDباشد -
nextبایدNULLیا اشارهگر معتبری به ساختار بعدی در زنجیره ساختار باشد -
databasesباید اشارهگری به آرایهای ازdatabaseCountشناسه XrTrackableImageDatabaseANDROID معتبر باشد - پارامتر
databaseCountباید بزرگتر از0باشد
XrTrackableImageTrackingModeANDROID enum حالتهای ردیابی پشتیبانیشده تصاویر را توصیف میکند.
typedef enum XrTrackableImageTrackingModeANDROID {
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;
شرحهای شمارشی
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID— این حالت بالاترین دقت را دارد و امکان ردیابی تصاویر متحرک با تأخیر کم را فراهم میکند. همچنین بیشترین مصرف برق را دارد.XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID— از این حالت باید برای تصاویری استفاده شود که ثابت یا نیمهثابت هستند. این حالت در مقایسه با حالت پویا منجر به مصرف برق کمتری میشود. اگر تصویر ثابتی درحال جابهجایی باشد، با تأخیر بسیار بیشتری نسبتبه استفاده از حالت پویا بهروزرسانی خواهد شد.
شمارش XrTrackableImageFormatANDROID قالبهای پشتیبانیشده تصاویر را شرح میدهد.
typedef enum XrTrackableImageFormatANDROID {
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;
شرحهای شمارشی
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID— قالب تصویر RGBA با ۸ بیت در هر کانال رنگ و دادههای شفافیت.
تابع xrAddTrackableImageDatabaseANDROID بهصورت زیر تعریف میشود:
XrResult xrAddTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
شرح پارامترها
-
trackerدسته XrTrackableTrackerANDROID برای افزودنdatabaseبه آن است. -
databaseدسته XrTrackableImageDatabaseANDROID برای افزودن بهtrackerاست.
وقتی XrTrackableImageDatabaseANDROID به ردیاب اضافه میشود، تصاویر مرجع آن پایگاه داده باید برای شناسایی و ردیابی درنظر گرفته شوند، علاوهبر هر پایگاه داده دیگری که قبلاً با xrAddTrackableImageDatabaseANDROID یا ازطریق ساختار XrTrackableImageConfigurationANDROID هنگام ایجاد اولیه ردیاب اضافه شده است.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید قبلاز فراخوانی xrAddTrackableImageDatabaseANDROID فعال شود -
trackerباید شناسه XrTrackableTrackerANDROID معتبری باشد -
databaseباید یک دسته XrTrackableImageDatabaseANDROID معتبر باشد - هر دو
databaseوtrackerباید از همان XrSession ایجاد، اختصاص، یا بازیابی شده باشند
کدهای برگشتی
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
تابع xrRemoveTrackableImageDatabaseANDROID بهصورت زیر تعریف میشود:
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
شرح پارامترها
trackerدسته XrTrackableTrackerANDROID برای برداشتنdatabaseاز آن است.-
databaseدسته XrTrackableImageDatabaseANDROID برای برداشتن ازtrackerاست.
وقتی XrTrackableImageDatabaseANDROID از XrTrackableTrackerANDROID برداشته میشود، ساختارهای XrTrackableImageDatabaseEntryANDROID آن پایگاه داده نباید دیگر برای شناسایی و ردگیری درنظر گرفته شوند. هر ورودی فعال ردیابیشده در آن پایگاه داده باید دیگر گزارش نشود. دسته XrTrackableImageDatabaseANDROID برداشتهشده نباید بهعنوان بخشی از این عملیات بهطور ضمنی ازبین برود.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید قبلاز فراخوانی xrRemoveTrackableImageDatabaseANDROID فعال شود -
trackerباید شناسه XrTrackableTrackerANDROID معتبری باشد -
databaseباید یک دسته XrTrackableImageDatabaseANDROID معتبر باشد - هر دو
databaseوtrackerباید از همان XrSession ایجاد، اختصاص، یا بازیابی شده باشند
کدهای برگشتی
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
درحال دریافت تصاویر
تابع xrGetTrackableImageANDROID بهصورت زیر تعریف میشود:
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
شرح پارامترها
-
trackerهمان XrTrackableTrackerANDROID برای پُرسمان است. -
getInfoهمان XrTrackableGetInfoANDROID است که اطلاعات استفادهشده برای دریافت رمزینه پاسخسریع قابلردیابی را دارد. -
trackableاشارهگری به ساختار XrTrackableImageANDROID است که تصویر قابلردیابی در آن برگردانده میشود.
اگر نوع قابلردیابی XrTrackableANDROID XR_TRACKABLE_TYPE_IMAGE_ANDROID نباشد، یا اگر نوع قابلردیابی XrTrackableTrackerANDROID XR_TRACKABLE_TYPE_IMAGE_ANDROID نباشد، زمان اجرا باید XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID را برگرداند.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید قبلاز فراخوانی xrGetTrackableImageANDROID فعال شود -
trackerباید شناسه XrTrackableTrackerANDROID معتبری باشد -
getInfoباید اشارهگری به ساختار معتبر XrTrackableGetInfoANDROID باشد -
trackableباید اشارهگری به ساختار XrTrackableImageANDROID باشد
کدهای برگشتی
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_ERROR_VALIDATION_FAILURE
ساختار XrTrackableImageANDROID بهصورت زیر تعریف میشود:
typedef struct XrTrackableImageANDROID {
XrStructureType type;
const void* next;
XrTrackingStateANDROID trackingState;
XrTime lastUpdatedTime;
XrTrackableImageDatabaseANDROID database;
uint32_t databaseEntryIndex;
XrPosef centerPose;
XrExtent2Df extents;
} XrTrackableImageANDROID;
توضیحات عضو
typeXrStructureType این ساختار است.-
nextبرابر باNULLیا اشارهگری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است. trackingStateXrTrackingStateANDROID تصویر است.lastUpdatedTimeXrTimeآخرین بهروزرسانی تصویر است.-
databaseدسته XrTrackableImageDatabaseANDROID است که این تصویر از آن ردیابی شده است. databaseEntryIndexنمایهای است که به XrTrackableImageDatabaseCreateInfoANDROID ::entriesآرایهdatabaseنگاشت میشود.centerPoseXrPosef تصویر واقع در XrTrackableGetInfoANDROID ::baseSpaceاست. تصویر در صفحه XZ قرار دارد که X به سمت راست تصویر و Z به پایین آن اشاره میکند.extentsابعاد XrExtent2Df تصویر است. مرز چارگوش محصورکننده در نقاطcenterPose+/- (extents/ 2) است.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید قبلاز استفاده از XrTrackableImageANDROID فعال شود -
typeبایدXR_TYPE_TRACKABLE_IMAGE_ANDROIDباشد -
nextبایدNULLیا اشارهگر معتبری به ساختار بعدی در زنجیره ساختار باشد -
trackingStateباید مقدار XrTrackingStateANDROID معتبری باشد -
databaseباید یک دسته XrTrackableImageDatabaseANDROID معتبر باشد
رسیدگی به موارد ناموفق
برنامه باید رویداد XrEventDataImageTrackingLostANDROID را بااستفاده از xrPollEvent نظرسنجی کند و نباید آن را نادیده بگیرد.
ساختار XrEventDataImageTrackingLostANDROID بهصورت زیر تعریف میشود:
typedef struct XrEventDataImageTrackingLostANDROID {
XrStructureType type;
const void* next;
XrTime time;
} XrEventDataImageTrackingLostANDROID;
توضیحات عضو
typeXrStructureType این ساختار است.-
nextبرابر باNULLیا اشارهگری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است. timeXrTime
دریافت رویداد XrEventDataImageTrackingLostANDROID نشان میدهد که ردگیری تصویر دچار مشکل شده است و خطای داخلی باعث نامعتبر شدن منابع موجود شده است. برنامه باید همه دستههای XrTrackableImageDatabaseANDROID را ازبین ببرد و اگر میخواهد ردیابی تصویر را ادامه دهد، آنها را دوباره ایجاد کند. برنامه همچنین باید همه دستههای XrTrackableTrackerANDROID مربوط به ردیابی تصویر را ازبین ببرد و اگر میخواهد ردیابی تصویر را ادامه دهد، آنها را دوباره ایجاد کند.
استفاده معتبر (ضمنی)
- افزونه
XR_ANDROID_trackables_imageباید قبلاز استفاده از XrEventDataImageTrackingLostANDROID فعال شود -
typeبایدXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDباشد -
nextبایدNULLیا اشارهگر معتبری به ساختار بعدی در زنجیره ساختار باشد
کد نمونه برای دریافت تصاویر قابلردیابی
کد نمونه زیر نحوه دریافت تصاویر قابلردیابی را نشان میدهد.
XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.
XrSystemId systemId; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties; // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT; // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID; // 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
XrSystemImageTrackingPropertiesANDROID imageProperty {
.type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
.next = nullptr,
};
XrSystemProperties systemProperties {
.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
// image tracking is not supported.
return;
}
uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.
XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
{
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
.next = nullptr,
.trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
.physicalWidth = 0.1f, // The width of the image in meters.
.imageWidth = 640,
.imageHeight = 480,
.format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
.bufferSize = imageBufferSize, // RGBA buffer size in bytes.
.buffer = imageBuffer, // RGBA data.
}
};
XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
.next = nullptr,
.entryCount = 1,
.entries = imageDatabaseEntries
};
XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));
bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = imageDatabaseFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
futureReady = true;
keepLooping = false;
} else {
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
}
XrTrackableImageDatabaseANDROID imageDatabase;
if (futureReady) {
XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
.type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
.next = nullptr,
};
CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
CHK_XR(imageDatabaseCompletion.futureResult);
imageDatabase = imageDatabaseCompletion.database;
}
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &imageDatabase
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.
// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
while (1) {
uint32_t trackableCountOutput = 0;
CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));
std::vector<XrTrackableANDROID> allImageTrackables;
allImageTrackables.resize(trackableCountOutput);
CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));
for (XrTrackableANDROID trackable : allImageTrackables) {
XrTrackableGetInfoANDROID imageGetInfo {
.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
.next = nullptr,
.trackable = trackable,
.baseSpace = appSpace,
.time = updateTime
};
XrTrackableImageANDROID trackableImage{
.type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
};
CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));
// Use XrTrackableImageANDROID data.
(void)trackableImage.trackingState;
(void)trackableImage.lastUpdatedTime;
(void)trackableImage.centerPose;
(void)trackableImage.extents;
if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
// Knowing which image the index of 0 maps to, use the specific image database
// entry (e.g. rendering A for image A).
}
// indices 1+N comparisons for another specific image database entry.
}
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));
کد نمونه برای مدیریت پایگاههای داده تصویر در زمان اجرا
کد نمونه زیر نحوه اصلاح مجموعه تصاویر درحال ردیابی را نشان میدهد.
XrSession session; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID; // Previously initialized.
// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.
// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 2,
.databases = imageDatabases
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.
// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &anotherImageDatabase
};
XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &anotherImageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));
// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.
کد نمونه برای واکنش به خطاهای ردیابی تصویر
نمونه کد زیر نشان میدهد که چگونه با نظرسنجی برای رویداد XrEventDataImageTrackingLostANDROID، خرابی را مدیریت کنید.
XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT; // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.
// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
.type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
switch (event.type) {
case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
const XrEventDataImageTrackingLostANDROID& eventdata =
*reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);
// All existing databases and trackers need to be destroyed.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));
// To resume image tracking, the database(s) and the tracker need to be re-created.
XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
.next = nullptr,
.entryCount = 1,
.entries = imageDatabaseEntries
};
XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));
while (true) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = imageDatabaseFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
break;
} else {
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
}
XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
.type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
.next = nullptr,
};
CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
CHK_XR(imageDatabaseCompletion.futureResult);
imageDatabase = imageDatabaseCompletion.database;
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &imageDatabase
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
break;
}
}
}
انواع شیء جدید
فرمانهای جدید
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
سازههای جدید
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
درحال گسترش دادن XrSystemProperties :
Enums جدید
ثابتهای شمارشی جدید
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_ANDROID_trackables_image_SPEC_VERSIONدرحال گسترش دادن XrObjectType :
XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
درحال گسترش دادن XrResult :
XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
درحال گسترش دادن XrStructureType :
XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
درحال گسترش دادن XrTrackableTypeANDROID :
XR_TRACKABLE_TYPE_IMAGE_ANDROID
مشکلات
سابقه نسخه
بازبینی ۱، ۲۰۲۵/۰۴/۰۸ (دانیل گوتنبرگ)
- توضیحات اولیه افزونه.