XR_EXT_spatial_image_tracking

رشته نام

XR_EXT_spatial_image_tracking

نوع افزونه

افزونه نمونه

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

783

بازبینی

1

وضعیت تصویب

تصویب‌نشده

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

XR_EXT_spatial_entity

همیاران

دنیل گوتنبرگ، Qualcomm
نیهاو جین، Google
جرد فایندر، Google
ژیپنگ لیو، ByteDance

نمای کلی

این افزونه قابلیت ردیابی تصویر را برای افزونه XR_EXT_spatial_entity ارائه می‌دهد. این ابزار به برنامه‌ها امکان می‌دهد تصاویر مسطح خاصی را که با مجموعه‌ای از تصاویر مرجع ورودی مشخص شده‌اند شناسایی و ردیابی کنند.

تصویر ردیابی‌شده به‌عنوان یک موجودیت فضایی با (یا «دارای») مؤلفه‌های زیر نشان داده می‌شود:

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

برنامه‌ها معمولاً از افزونه ردیابی تصویر فضایی در الگوی زیر استفاده می‌کنند:

  • یک برنامه ابتدا یک یا چند دسته XrSpatialImageTrackingDatabaseEXT را براساس مجموعه‌های داده‌های تصویر مرجع پیش‌بارگذاری‌شده ایجاد می‌کند.
  • سپس برنامه یک دسته XrSpatialContextEXT براساس دسته‌های XrSpatialImageTrackingDatabaseEXT که قبلاً ایجاد شده‌اند ایجاد می‌کند.
  • سپس برنامه داده‌های تصویر مرجع را آزاد می‌کند تا مصرف حافظه خود را کاهش دهد.
  • برنامه تصاویر را طبق الگوهای دسترسی به نهاد فضایی کاوش و پُرسمان می‌کند.
  • برنامه می‌تواند مجموعه‌های دیگری از تصاویر مرجع را بار کند و XrSpatialImageTrackingDatabaseEXT دیگری ایجاد کند و متعاقباً XrSpatialContextEXT را از آن‌ها ایجاد کند تا مجموعه تصاویر قابل‌شناسایی و قابل‌ردیابی را به‌طور پویا در زمان اجرا گسترش دهد.
  • برنامه می‌تواند دسته‌های XrSpatialImageTrackingDatabaseEXT را ازبین ببرد تا مجموعه تصاویر قابل‌تشخیص و قابل‌ردیابی را به‌طور پویا در زمان اجرا کاهش دهد.
  • برنامه می‌تواند دسته‌های XrSpatialContextEXT را ازبین ببرد تا مجموعه تصاویر قابل‌شناسایی و قابل‌ردیابی را به‌طور پویا در زمان اجرا کاهش دهد.

پشتیبانی زمان اجرا

زمان اجرا باید پشتیبانی خود را از قابلیت ردیابی تصویر بااستفاده از xrEnumerateSpatialCapabilitiesEXT با فهرست کردن قابلیت زیر تبلیغ کند:

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

پیکربندی

برای فعال کردن تشخیص و ردگیری تصاویر مسطح، برنامه می‌تواند ساختارهای XrSpatialCapabilityConfigurationImageTrackingEXT را در XrSpatialContextCreateInfoEXT :: capabilityConfigs هنگام فراخوانی تابع xrCreateSpatialContextAsyncEXT ارسال کند و آرایه‌های ساختارهای< XrSpatialImageTrackingDatabaseEXT را در هر XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases ارسال کند.

ساخت مجموعه تصویر ورودی

برای مشخص کردن تصاویر مرجع برای شناسایی و ردیابی، برنامه باید حداقل یک مجموعه از تصاویر مرجع ورودی ایجاد کند. مجموعه‌ای از تصاویر مرجع ورودی با دسته XrSpatialImageTrackingDatabaseEXT نشان داده می‌شود و حداقل یک تصویر دارد.

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

دستگیره XrSpatialImageTrackingDatabaseEXT نشان‌دهنده منابعی برای کشف و به‌روزرسانی تعدادی تصویر فضایی در محیط کاربر است. برنامه‌ها می‌توانند از این دسته برای کشف و به‌روزرسانی تصاویر فضایی بااستفاده از توابع دیگر در این افزونه استفاده کنند.

ایجاد پایگاه داده ردیابی تصویر فضایی

تابع xrCreateSpatialImageTrackingDatabaseAsyncEXT به‌صورت زیر تعریف می‌شود:

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

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

  • ‫session یک XrSession است که در آن پایگاه داده ردیابی تصویر فضایی فعال خواهد بود.
  • createInfo همان XrSpatialImageTrackingDatabaseCreateInfoEXT است که برای مشخص کردن پارامترهای پایگاه داده ردیابی تصویر فضایی استفاده می‌شود.
  • ‫future اشاره‌گری به XrFutureEXT است.

برنامه می‌تواند بااستفاده از تابع xrCreateSpatialImageTrackingDatabaseAsyncEXT، دسته XrSpatialImageTrackingDatabaseEXT ایجاد کند و مجموعه‌های تصاویر مرجع ورودی پایگاه داده ردگیری تصویر را با createInfo پیکربندی کند.

اگر XrSpatialReferenceImageEXT :: format هرکدام از تصاویر مرجع ورودی توسط xrEnumerateSpatialReferenceImageFormatsEXT شمارش نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT را برگرداند.

اگر آرایه planes از XrSpatialReferenceImageEXT مربوط به هرکدام از تصاویر مرجع ورودی را نتوان براساس فراداده تصویر مرجع XrSpatialReferenceImageEXT ارزیابی کرد، زمان اجرا باید XR_ERROR_SPATIAL_IMAGE_INVALID_EXT را برگرداند.

اگر آرایه planes از XrSpatialReferenceImageEXT :: برای هریک از تصاویر مرجع ورودی دقیقاً به تعداد کانال‌های رنگی XrSpatialReferenceImageEXT :: format صفحه ارائه ندهد، زمان اجرا باید XR_ERROR_SPATIAL_IMAGE_INVALID_EXT را برگرداند.

اگر زمان اجرا سیستم اجازه‌ای را برای کنترل دسترسی برنامه به قابلیت ردیابی تصویر اعمال کند، درصورتی‌که این اجازه‌ها به این برنامه اعطا نشده باشد، زمان اجرا باید XR_ERROR_PERMISSION_INSUFFICIENT را برگرداند.

این تابع یک عملیات ناهمگام را شروع می‌کند و یک XrFutureEXT متناظر ایجاد می‌کند که با xrPollFutureEXT و توابع مرتبط قابل‌استفاده است. مقدار برگشتی این تابع فقط نشان می‌دهد که آیا پارامترها برای زمان‌بندی عملیات ناهمگام قابل‌قبول بوده‌اند یا نه. تابع تکمیل مربوطه xrCreateSpatialImageTrackingDatabaseCompleteEXT است که وقتی آینده‌ای از این تابع در وضعیت READY باشد قابل‌استفاده است و خروجی‌های آن توسط آن تابع در ساختار تکمیل XrCreateSpatialImageTrackingDatabaseCompletionEXT پر می‌شود.

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

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ناموفق

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

ساختار XrSpatialImageTrackingDatabaseCreateInfoEXT به‌صورت زیر تعریف می‌شود:

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • spatialReferenceImageCount تعداد عناصر در آرایه spatialReferenceImages است.
  • ‫spatialReferenceImages آرایه‌ای از XrSpatialReferenceImageEXT است.

ساختار XrSpatialImageTrackingDatabaseCreateInfoEXT اطلاعات لازم برای ایجاد دسته XrSpatialImageTrackingDatabaseEXT را شرح می‌دهد.

هر XrSpatialImageTrackingDatabaseEXT باید با حداقل یک XrSpatialReferenceImageEXT در آرایه XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages ایجاد شود.

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

تابع xrCreateSpatialImageTrackingDatabaseCompleteEXT به‌صورت زیر تعریف می‌شود:

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

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

xrCreateSpatialImageTrackingDatabaseCompleteEXT عملیات ناهمگامی را که توسط xrCreateSpatialImageTrackingDatabaseAsyncEXT شروع شده است تکمیل می‌کند.

زمان اجرا نباید به هیچ اشاره‌گر XrSpatialReferenceImagePlaneEXT :: buffer که توسط آرایه ورودی XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages برای این فراخوانی xrCreateSpatialImageTrackingDatabaseAsyncEXT ارائه شده است، پس‌از تکمیل آن دسترسی داشته باشد. برنامه می‌تواند هر داده XrSpatialReferenceImagePlaneEXT :: buffer را پس‌از تکمیل xrCreateSpatialImageTrackingDatabaseAsyncEXT آزاد کند تا ردپای حافظه آن کاهش یابد.

اگر future در وضعیت آماده نباشد، زمان اجرا باید XR_ERROR_FUTURE_PENDING_EXT را برگرداند. اگر future قبلاً تکمیل یا لغو شده باشد، زمان اجرا باید XR_ERROR_FUTURE_INVALID_EXT را برگرداند.

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

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ناموفق

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

ساختار XrCreateSpatialImageTrackingDatabaseCompletionEXT به‌صورت زیر تعریف می‌شود:

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

توضیحات عضو

کدهای برگشتی آتی

مقادیر futureResult:

موفقیت‌آمیز بود

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ناموفق

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

اگر futureResult کد موفقیت باشد، database باید نام کاربری معتبری باشد. اگر database معتبر باشد، فقط در چرخه حیات xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session یا تا زمانی که برنامه database را با xrDestroySpatialImageTrackingDatabaseEXT ازبین ببرد، هرکدام که زودتر اتفاق بیفتد، معتبر باقی می‌ماند.

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

Destroy the Spatial Image Tracking Database

تابع xrDestroySpatialImageTrackingDatabaseEXT به‌صورت زیر تعریف می‌شود:

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

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

برنامه می‌تواند تابع xrDestroySpatialImageTrackingDatabaseEXT را فراخوانی کند تا پس‌از اتمام تکالیف به‌روزرسانی و کشف تصویر فضایی، دسته database و منابع زیربنایی را آزاد کند.

برنامه می‌تواند تابع xrDestroySpatialImageTrackingDatabaseEXT را قبل‌از فراخوانی xrDestroySpatialContextEXT فراخوانی کند. زمان اجرا نباید دیگر تصاویر مدیریت‌شده توسط این XrSpatialImageTrackingDatabaseEXT تخریب‌شده را گزارش کند. زمان اجرا باید به گزارش کردن تصاویری که توسط پایگاه‌های داده دیگر مدیریت می‌شوند ادامه دهد.

زمان اجرا باید اطمینان حاصل کند که عکس‌های آنی اکتشافی که توسط xrCreateSpatialDiscoverySnapshotCompleteEXT برگردانده می‌شوند حاوی تصاویر مربوط به دسته‌های XrSpatialImageTrackingDatabaseEXT تخریب‌شده یا نامعتبر نباشند، حتی اگر دسته پس‌از فراخوانی xrCreateSpatialDiscoverySnapshotAsyncEXT توسط برنامه تخریب شده باشد. با توجه به اینکه داده‌های موجود در عکس آنی فضایی تغییرناپذیر است، برنامه باید هر دسته XrSpatialSnapshotEXT را که قبل‌از نابود کردن database ایجاد شده است نابود کند، درغیراین‌صورت برنامه ممکن است هنگام استفاده از xrQuerySpatialComponentDataEXT دسته‌های نامعتبر XrSpatialImageTrackingDatabaseEXT دریافت کند.

برنامه می‌تواند تابع xrDestroySpatialContextEXT را برای رها کردن دسته XrSpatialContextEXT قبل‌از تخریب هرکدام از دسته‌های XrSpatialImageTrackingDatabaseEXT که XrSpatialContextEXT با آن‌ها ایجاد شده است فراخوانی کند. زمان اجرا نباید به‌طور ضمنی این دسته‌های XrSpatialImageTrackingDatabaseEXT را هنگام نابود شدن XrSpatialContextEXT نابود کند.

مدیریت طول عمر XrSpatialContextEXT و XrSpatialImageTrackingDatabaseEXT به‌طور مستقل به برنامه‌ها امکان می‌دهد تا از دسته‌های XrSpatialImageTrackingDatabaseEXT که قبلاً ایجاد شده‌اند مجدداً استفاده کنند، بدون اینکه نیاز باشد فرایند پرهزینه ایجاد را دوباره انجام دهند.

برای مثال، ازبین بردن یک XrSpatialContextEXT و سپس بازآفرینی یک XrSpatialContextEXT دیگر با همان XrSpatialImageTrackingDatabaseEXT امکان توقف موقت و ازسرگیری ردیابی تصویر را بدون نیاز به انجام یک روش مقداردهی اولیه دیگر فراهم می‌کند.

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

ایمنی رشته‌ای

  • دسترسی به database و هرگونه دسته فرزند باید به‌صورت خارجی همگام‌سازی شود

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS

ناموفق

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

پشتیبانی از قالب تصویر ورودی

برنامه‌ها باید xrEnumerateSpatialReferenceImageFormatsEXT را فراخوانی کنند تا فهرست قالب‌های تصویر مرجع ورودی پشتیبانی‌شده را دریافت کنند.

تابع xrEnumerateSpatialReferenceImageFormatsEXT به‌صورت زیر تعریف می‌شود:

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

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

  • ‫instance دسته‌ای برای XrInstance است.
  • systemId XrSystemId است که قالب‌های تصویر مرجع ورودی آن شمارش خواهد شد.
  • ‫capability همان XrSpatialCapabilityEXT است که قالب‌های تصویر مرجع ورودی برای آن شمارش خواهد شد.
  • formatCapacityInput ظرفیت آرایه formats است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • formatCountOutput تعداد قالب‌ها یا ظرفیت موردنیاز درصورتی است که formatCapacityInput کافی نباشد.
  • ‫formats آرایه‌ای از XrSpatialReferenceImageFormatEXT است. اگر formatCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای شرح مفصل بازیابی اندازه formats موردنیاز، بخش پارامترهای اندازه میان‌گیر را ببینید.

برنامه می‌تواند فهرست قالب‌های تصویر مرجع ورودی را که توسط XrSystemId داده‌شده برای XrSpatialCapabilityEXT داده‌شده پشتیبانی می‌شود بااستفاده از xrEnumerateSpatialReferenceImageFormatsEXT شمارش کند.

زمان اجرا نباید قالب‌های افزونه‌هایی را که برای instance فعال نیستند شمارش کند.

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

  • افزونه XR_EXT_spatial_image_tracking باید قبل‌از فراخوانی xrEnumerateSpatialReferenceImageFormatsEXT فعال شود
  • instance باید شناسه XrInstance معتبری باشد
  • capability باید مقدار XrSpatialCapabilityEXT معتبری باشد
  • formatCountOutput باید اشاره‌گری به مقدار uint32_t باشد
  • اگر formatCapacityInput 0 نباشد، formats باید اشاره‌گری به آرایه‌ای از مقادیر formatCapacityInput XrSpatialReferenceImageFormatEXT باشد

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS

ناموفق

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

برای مشاهده فهرست کامل همه قالب‌های تصویر مرجع که هر افزونه‌ای از آن‌ها پشتیبانی می‌کند، XrSpatialReferenceImageFormatEXT را ببینید.

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

شمارش XrSpatialReferenceImageFormatEXT قالب‌های تصویر مرجع ورودی را که زمان اجرا ممکن است پشتیبانی کند شناسایی می‌کند.

حداقل مقدار XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT و مقدار XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT باید پشتیبانی شود.

شمارنده‌ها معنی زیر را دارند:

شرح‌های شمارشی

  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT — میان‌گیر RGBA. این قالب هیچ تضمینی درباره چیدمان داده‌های پیکسل در حافظه ارائه نمی‌دهد. پیکسل‌ها باید بااستفاده از فراداده ارائه‌شده توسط ساختارهای XrSpatialReferenceImagePlaneEXT مربوطه قابل‌دسترسی باشند. هر کانال رنگ پیکسل اندازه ۸ بیتی دارد که اندازه هر پیکسل را ۳۲ بیت می‌کند.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT — میان‌گیر RGB. این قالب هیچ تضمینی درباره چیدمان داده‌های پیکسل در حافظه ارائه نمی‌دهد. پیکسل‌ها باید بااستفاده از فراداده ارائه‌شده توسط ساختارهای XrSpatialReferenceImagePlaneEXT مربوطه قابل‌دسترسی باشند. هر کانال رنگ پیکسل اندازه ۸ بیتی دارد که اندازه هر پیکسل را ۲۴ بیت می‌کند.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT — میان‌گیر YUV که نمونه فرعی خلوص رنگ الگوی ۴:۲:۰ است. این قالب هیچ تضمینی درباره چیدمان داده‌های پیکسل در حافظه ارائه نمی‌دهد. پیکسل‌ها باید بااستفاده از فراداده ارائه‌شده توسط ساختارهای XrSpatialReferenceImagePlaneEXT مربوطه قابل‌دسترسی باشند. هر کانال رنگ پیکسل RGB رمزگشایی‌شده دارای اندازه ۸ بیت است که اندازه هر پیکسل را به ۲۴ بیت می‌رساند.

تنظیمات ردیابی تصویر فضایی

این افزونه ساختارهای اختیاری‌ای را ارائه می‌دهد که برنامه می‌تواند از آن‌ها برای پیکربندی قابلیت ردیابی تصویر استفاده کند.

بهینه‌سازی تصویر ثابت

ساختار XrSpatialImageStaticOptimizationEXT به‌صورت زیر تعریف می‌شود:

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • optimizeForStaticImage یک XrBool32 است که نشان می‌دهد تصاویر حرکت می‌کنند یا نه. مقدار XR_TRUE نشان می‌دهد که تصاویر حرکت نمی‌کنند.

اگر XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT توسط xrEnumerateSpatialCapabilityFeaturesEXT برای قابلیت XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT شمارش شود، برنامه می‌تواند XrSpatialImageStaticOptimizationEXT را به زنجیره XrSpatialImageTrackingDatabaseCreateInfoEXT :: next یا XrSpatialReferenceImageEXT :: next زنجیر کند.

اگر برنامه XrSpatialImageStaticOptimizationEXT را به ساختار XrSpatialImageTrackingDatabaseCreateInfoEXT زنجیر کند، زمان اجرا باید فرض کند که همه تصاویر آن XrSpatialImageTrackingDatabaseEXT ثابت هستند اگر optimizeForStaticImage روی XR_TRUE تنظیم شده باشد. به‌طور مشابه، اگر optimizeForStaticImage روی XR_FALSE تنظیم شده باشد، زمان اجرا باید فرض کند که همه تصاویر آن XrSpatialImageTrackingDatabaseEXT ثابت نیستند.

اگر برنامه XrSpatialImageStaticOptimizationEXT را به ساختار XrSpatialReferenceImageEXT زنجیر کند، زمان اجرا باید فرض کند که این تصویر مرجع ایستا است اگر optimizeForStaticImage روی XR_TRUE تنظیم شده باشد. به‌طور مشابه، اگر optimizeForStaticImage روی XR_FALSE تنظیم شده باشد، زمان اجرا باید فرض کند که این تصویر مرجع ثابت نیست. زنجیر کردن ساختار XrSpatialImageStaticOptimizationEXT به ساختار XrSpatialReferenceImageEXT بر زنجیر کردن آن به ساختار XrSpatialImageTrackingDatabaseCreateInfoEXT اولویت دارد.

اگر XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT توسط xrEnumerateSpatialCapabilityFeaturesEXT برای قابلیت XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT شمارش نشده باشد و برنامه ساختار XrSpatialImageStaticOptimizationEXT را به هریک از زنجیره‌های بعدی قابل‌اجرا زنجیر کند، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را از xrCreateSpatialImageTrackingDatabaseAsyncEXT برگرداند.

این کار ممکن است به زمان اجرا اجازه دهد تا حالت و اندازه دقیق‌تری تولید کند.

این کار ممکن است به زمان اجرا اجازه دهد مصرف برق را کاهش دهد.

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

عرض تصویر مرجع

ساختار XrSpatialImageSizeEXT به‌صورت زیر تعریف می‌شود:

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • physicalWidth مقدار float است که نشان‌دهنده پهنای فیزیکی برحسب متر برای تنظیم است.

اگر XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT توسط xrEnumerateSpatialCapabilityFeaturesEXT برای قابلیت XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT شمارش شود، برنامه می‌تواند XrSpatialImageSizeEXT را به XrSpatialImageTrackingDatabaseCreateInfoEXT :: next یا XrSpatialReferenceImageEXT :: next زنجیر کند.

اگر برنامه XrSpatialImageSizeEXT را به ساختار XrSpatialImageTrackingDatabaseCreateInfoEXT زنجیر کند، زمان اجرا باید فرض کند که همه تصاویر آن XrSpatialImageTrackingDatabaseEXT دارای عرض physicalWidth متر و ارتفاعی مطابق با نسبت ابعادی هستند که به‌طور ضمنی ازطریق XrSpatialReferenceImageEXT :: width و XrSpatialReferenceImageEXT :: height ارائه شده است.

اگر برنامه XrSpatialImageSizeEXT را به ساختار XrSpatialReferenceImageEXT زنجیر کند، زمان اجرا باید فرض کند که این تصویر مرجع دارای عرض physicalWidth متر و ارتفاعی مطابق با نسبت ابعادی است که به‌طور ضمنی ازطریق XrSpatialReferenceImageEXT :: width و XrSpatialReferenceImageEXT :: height ارائه شده است. زنجیر کردن ساختار XrSpatialImageSizeEXT به ساختار XrSpatialReferenceImageEXT بر زنجیر کردن آن به ساختار XrSpatialImageTrackingDatabaseCreateInfoEXT اولویت دارد.

این کار ممکن است به زمان اجرا اجازه دهد تا ژست و اندازه دقیق‌تری را برگرداند.

زمان اجرا باید XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT یا XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT یا هر دو را شمارش کند.

اگر XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT توسط xrEnumerateSpatialCapabilityFeaturesEXT شمارش شده باشد، زمان اجرا باید به‌طور خودکار اندازه‌های تصویر را برای تصاویری که برنامه هیچ ساختار XrSpatialImageSizeEXT را به‌عنوان بخشی از زنجیره‌های بعدی قابل‌اجرا ارائه نکرده است، ارائه دهد.

برای اینکه زمان اجرا بتواند اندازه‌های تصویر را به‌طور خودکار و دقیق تولید کند، ممکن است به برخی قابلیت‌ها و پیش‌نیازهای دستگاه نیاز باشد؛ یعنی دوربین‌های استریو، پارامترهای بیرونی و درونی دوربین که به‌طور دقیق کالیبره شده‌اند.

اگر XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT توسط xrEnumerateSpatialCapabilityFeaturesEXT شمارش نشده باشد، برنامه باید ساختارهای XrSpatialImageSizeEXT را به زنجیره‌های بعدی مربوطه پیوند دهد تا همه تصاویر اندازه صریحی داشته باشند، درغیراین‌صورت زمان اجرا باید XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT را از xrCreateSpatialImageTrackingDatabaseAsyncEXT برگرداند.

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

ساختار XrSpatialCapabilityConfigurationImageTrackingEXT به‌صورت زیر تعریف می‌شود:

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫capability یک XrSpatialCapabilityEXT است و باید XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT باشد.
  • enabledComponentCount یک uint32_t است که تعداد عناصر را در enabledComponents مشخص می‌کند.
  • enabledComponents آرایه‌ای از XrSpatialComponentTypeEXT است که مؤلفه‌هایی را که باید برای این قابلیت فعال شوند مشخص می‌کند.
  • imageTrackingDatabaseCount یک unint32_t است که تعداد عناصر را در imageTrackingDatabases مشخص می‌کند.
  • imageTrackingDatabases آرایه‌ای از دسته‌های XrSpatialImageTrackingDatabaseEXT است که پایگاه‌های داده ردگیری تصویر را برای فعال کردن بافت فضایی مشخص می‌کند.

اگر ردیابی تصویر پشتیبانی شود، زمان اجرا باید ردیابی تصویر را فعال کند اگر ساختار XrSpatialCapabilityConfigurationImageTrackingEXT در XrSpatialContextCreateInfoEXT :: capabilityConfigs هنگام فراخوانی xrCreateSpatialContextAsyncEXT ارسال شود.

ساختار XrSpatialCapabilityConfigurationImageTrackingEXT به برنامه امکان می‌دهد تصاویر مرجع را که با دسته‌های XrSpatialImageTrackingDatabaseEXT در imageTrackingDatabases نشان داده شده‌اند، کشف کند.

اگر XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT توسط xrEnumerateSpatialCapabilitiesEXT شمارش نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT را برگرداند.

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

  • افزونه XR_EXT_spatial_image_tracking باید قبل‌از استفاده از XrSpatialCapabilityConfigurationImageTrackingEXT فعال شود
  • type باید XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT باشد
  • ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد
  • capability باید مقدار XrSpatialCapabilityEXT معتبری باشد
  • enabledComponents باید اشاره‌گری به آرایه‌ای از مقادیر معتبر enabledComponentCount XrSpatialComponentTypeEXT باشد
  • imageTrackingDatabases باید اشاره‌گری به آرایه‌ای از imageTrackingDatabaseCount دسته XrSpatialImageTrackingDatabaseEXT معتبر باشد
  • پارامتر enabledComponentCount باید بزرگ‌تر از 0 باشد
  • پارامتر imageTrackingDatabaseCount باید بزرگ‌تر از 0 باشد

تصویر مرجع فضایی

ساختار XrSpatialReferenceImagePlaneEXT به‌صورت زیر تعریف می‌شود:

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

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

  • ‫bufferSize اندازه آرایه buffer است.
  • buffer آرایه‌ای از داده‌های uint8_t است که داده‌های صفحه را نشان می‌دهد.
  • rowStride فاصله بایت بین دو موقعیت شروع ردیف‌های داده پیکسل متوالی است.
  • pixelStride فاصله بایت بین دو پیکسل متوالی است.

زمان اجرا باید طبق الگوهایی که پارامترهای rowStride و pixelStride ارائه می‌دهند به buffer دسترسی داشته باشد.

برنامه باید rowStride و pixelStride را طوری تنظیم کند که فقط پیکسل‌های معنادار این XrSpatialReferenceImagePlaneEXT توسط زمان اجرا استخراج شوند.

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

  • افزونه XR_EXT_spatial_image_tracking باید قبل‌از استفاده از XrSpatialReferenceImagePlaneEXT فعال شود
  • buffer باید اشاره‌گری به آرایه‌ای از مقادیر bufferSize uint8_t باشد
  • پارامتر bufferSize باید بزرگ‌تر از 0 باشد

ساختار XrSpatialReferenceImageEXT به‌صورت زیر تعریف می‌شود:

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

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

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • width پهنای پیکسل تصویر مرجع است.
  • height ارتفاع تصویر مرجع به پیکسل است.
  • ‫format یک XrSpatialReferenceImageFormatEXT است که قالب تصویر را نشان می‌دهد.
  • planeCount تعداد عناصر در آرایه planes است.
  • planes آرایه‌ای از ساختارهای XrSpatialReferenceImagePlaneEXT است که صفحه‌های داده‌های تصویر را نشان می‌دهد.

برنامه می‌تواند یک یا چند ساختار XrSpatialReferenceImageEXT ایجاد کند که هرکدام نشان‌دهنده یک تصویر مرجع ورودی واحد است که باید هنگام ایجاد دسته XrSpatialImageTrackingDatabaseEXT ازطریق XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages به تابع xrCreateSpatialImageTrackingDatabaseAsyncEXT منتقل شود.

داده‌های XrSpatialReferenceImagePlaneEXT :: buffer باید توسط برنامه به‌صورت ترتیب پیکسل چپ به راست و بالا به پایین ارائه شود.

برنامه باید ساختار XrSpatialReferenceImagePlaneEXT را در آرایه XrSpatialReferenceImageEXT :: planes برای هر کانال رنگ XrSpatialReferenceImageEXT :: format ارائه دهد.

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

قطعات تضمین‌شده

زمان اجرایی که از XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT پشتیبانی می‌کند باید مؤلفه‌های فضایی زیر را به‌عنوان مؤلفه‌های تضمین‌شده همه موجودیت‌های کشف‌شده توسط آن قابلیت‌ها ارائه دهد و باید آن‌ها را در xrEnumerateSpatialCapabilityComponentTypesEXT فهرست کند:

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

عنصر دوبعدی تصویر

ساختار فهرست مؤلفه برای پُرسمان داده‌ها

ساختار XrSpatialComponentImage2DListEXT به‌صورت زیر تعریف می‌شود:

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

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

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • imageCount تعداد عناصر در آرایه images است.
  • ‫images آرایه‌ای از XrSpatialImage2DDataEXT است.

اگر XrSpatialComponentImage2DListEXT در زنجیره XrSpatialComponentDataQueryResultEXT :: next باشد، اما XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT در XrSpatialComponentDataQueryConditionEXT :: componentTypes گنجانده نشده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را از xrQuerySpatialComponentDataEXT برگرداند.

اگر imageCount کمتر از XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput باشد، زمان اجرا باید XR_ERROR_SIZE_INSUFFICIENT را از xrQuerySpatialComponentDataEXT برگرداند.

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

داده‌های مؤلفه

ساختار XrSpatialImage2DDataEXT به‌صورت زیر تعریف می‌شود:

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

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

  • ‫imageTrackingDatabase همان XrSpatialImageTrackingDatabaseEXT است که تصویر را شناسایی یا ردگیری کرده است.
  • referenceImageIndex نمایه‌ای است که به آرایه XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages از تصاویر مرجع ورودی که imageTrackingDatabase با آن ایجاد شده است نگاشت می‌شود.

برنامه می‌تواند از imageTrackingDatabase استفاده کند تا تشخیص دهد کدام XrSpatialImageTrackingDatabaseEXT که قبلاً ایجاد شده است حاوی تصویر مرجع این ساختار XrSpatialImage2DDataEXT است. برای آن XrSpatialImageTrackingDatabaseEXT، برنامه می‌تواند از referenceImageIndex برای شناسایی XrSpatialReferenceImageEXT این ساختار XrSpatialImage2DDataEXT با مطابقت دادن آن با ترتیب ورودی آرایه XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages استفاده کند.

مجموعه تصاویر مرجع تعریف‌شده توسط مجموعه همه پایگاه‌های داده فعال نباید شامل تصاویر تکراری باشد. گنجاندن تصاویر تکراری ممکن است باعث رفتار نامطلوب در کاوش یا ردیابی شود؛ یعنی نمایه‌های ناسازگار یا چندگانه برگردانده شود.

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

پیکربندی

اگر XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT در XrSpatialCapabilityComponentTypesEXT :: componentTypes برای برخی قابلیت‌ها شمارش شده باشد، برنامه می‌تواند با گنجاندن مقدار شمارشی در فهرست XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents آن را فعال کند. این مؤلفه برای گنجانده شدن در زنجیره بعدی XrSpatialCapabilityConfigurationBaseHeaderEXT به پیکربندی خاصی نیاز ندارد.

عنصر دوبعدی محدودشده

مؤلفه دوبعدی محدودشده، مرکز و حدود تصویر فضایی را که توسط موجودیت قرارگرفته روی آن نمایش داده می‌شود ارائه می‌دهد. برای جزئیات بیشتر درباره مؤلفه دوبعدی محدود، دوبعدی محدود را ببینید.

کد نمونه

کاوش تصاویر فضایی و داده‌های مؤلفه پُرسمان

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

XrInstance instance; // Previously initialized
XrSystemId systemId; // Previously initialized
XrSession session; // Previously initialized

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components
  std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = discoveryFuture;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // For every frame in frame loop

  XrFrameState frameState;  // Previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata = *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

انواع شیء جدید

فرمان‌های جدید

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

Enums جدید

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

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • درحال گسترش دادن XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • درحال گسترش دادن XrResult :

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • درحال گسترش دادن XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

  • درحال گسترش دادن XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

  • درحال گسترش دادن XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

  • درحال گسترش دادن XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
    • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
    • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
    • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

مشکلات

سابقه نسخه

  • نسخه ۱، ۲۰۲۵-۰۴-۲۲ (دنیل گوتنبرگ، Qualcomm)

    • شرح اولیه افزونه