XR_ANDROID_spatial_discovery_bounds

رشته نام

XR_ANDROID_spatial_discovery_bounds

نوع افزونه

افزونه نمونه

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

762

بازبینی

1

وضعیت تصویب

تصویب‌نشده

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

XR_EXT_spatial_entity

همیاران

Nihav Jain،‏ Google
Natalie Fleury،‏ Meta
Yuichi Taguchi،‏ Meta
Yin Li،‏ Microsoft
Ron Bessems،‏ Meta
Karthik Kadappan،‏ Magic Leap
Jimmy Alamparambil،‏ ByteDance
Zhipeng Liu،‏ ByteDance
Jun Yan،‏ ByteDance

نمای کلی

این افزونه تعاریفی را برای مرزهای فضایی اضافه می‌کند که به برنامه‌ها اجازه می‌دهد هنگام فراخوانی xrCreateSpatialDiscoverySnapshotAsyncEXT، موجودیت‌های فضایی کشف‌شده را فیلتر کنند.

مرزهای فضایی

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

typedef struct XrSpatialBoundsSpherefANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrSpheref          sphere;
} XrSpatialBoundsSpherefANDROID;

توضیحات عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
• ‫space همان XrSpace است که هرگونه ژست برای مرزها در آن تعریف می‌شود.
• time یک XrTime است که در آن حالت‌های مرزها تعریف شده است.
• sphere یک XrSpheref است که حجم کروی را توصیف می‌کند که زمان اجرا باید کشف موجودیت‌های فضایی را در آن محدود کند.

قابلیت‌های فضایی که از XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID پشتیبانی می‌کنند (همان‌طور که توسط xrEnumerateSpatialCapabilityFeaturesEXT شمارش شده است) به برنامه اجازه می‌دهند تا با زنجیر کردن XrSpatialBoundsSpherefANDROID به XrSpatialDiscoverySnapshotCreateInfoEXT :: next ، کاوش را به موجودیت‌های فضایی که مکان یا مرزهای آن‌ها درون یا متقاطع با sphere است محدود کند. برای عکس آنی اکتشافی که در آن قابلیت مربوطه از XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID پشتیبانی می‌کند، اگر این ساختار در زنجیره next وجود داشته باشد، زمان اجرا نباید شامل هیچ موجودیت فضایی باشد که مکان یا حدود آن کاملاً خارج از sphere باشد.

توجه به این نکته مهم است که گنجاندن XrSpatialBoundsSpherefANDROID در زنجیره بعدی XrSpatialDiscoverySnapshotCreateInfoEXT به‌عنوان شرط «AND» با سایر فیلترهای ارائه‌شده عمل می‌کند. نهادهایی که از قابلیت‌های فضایی می‌آیند و از XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID پشتیبانی نمی‌کنند نباید در عکس آنی کاوش گنجانده شوند. این رفتار با بقیه مشخصات OpenXR متفاوت است که در آن ساختارهای ناشناخته یا پشتیبانی‌نشده در زنجیره اشاره‌گر بعدی توسط زمان اجرا نادیده گرفته می‌شوند. همچنین، همان‌طور که در بخش یکتایی ساختار زنجیره بعدی توضیح داده شده است، زمان اجرا فقط اولین رخداد ساختار XrSpatialBoundsSpherefANDROID را در زنجیره بعدی پردازش می‌کند.

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

• افزونه XR_ANDROID_spatial_discovery_bounds باید قبل‌از استفاده از XrSpatialBoundsSpherefANDROID فعال شود
• type باید XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد
• space باید شناسه مجازی XrSpace معتبر باشد

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

typedef struct XrSpatialBoundsBoxfANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrBoxf             box;
} XrSpatialBoundsBoxfANDROID;

توضیحات عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
• ‫space همان XrSpace است که هرگونه ژست برای مرزها در آن تعریف می‌شود.
• time یک XrTime است که در آن حالت‌های مرزها تعریف شده است.
• ‫box یک XrBoxf است که حجم جعبه‌ای را توصیف می‌کند که زمان اجرا باید کشف نهادهای فضایی را در آن محدود کند.

قابلیت‌های فضایی که از XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID پشتیبانی می‌کنند (همان‌طور که توسط xrEnumerateSpatialCapabilityFeaturesEXT شمارش شده است) به برنامه اجازه می‌دهند تا با زنجیر کردن XrSpatialBoundsBoxfANDROID به XrSpatialDiscoverySnapshotCreateInfoEXT :: next ، کاوش را به نهادهای فضایی که مکان یا مرزهای آن‌ها درون یا متقاطع با box است محدود کند. برای عکس آنی اکتشافی که در آن قابلیت مربوطه از XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID پشتیبانی می‌کند، اگر این ساختار در زنجیره next وجود داشته باشد، زمان اجرا نباید شامل هیچ موجودیت فضایی باشد که مکان یا حدود آن کاملاً خارج از box باشد.

توجه به این نکته مهم است که گنجاندن XrSpatialBoundsBoxfANDROID در زنجیره بعدی XrSpatialDiscoverySnapshotCreateInfoEXT به‌عنوان شرط «AND» با سایر فیلترهای ارائه‌شده عمل می‌کند. نهادهایی که از قابلیت‌های فضایی می‌آیند و از XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID پشتیبانی نمی‌کنند نباید در عکس آنی کاوش گنجانده شوند. این رفتار با بقیه مشخصات OpenXR متفاوت است که در آن ساختارهای ناشناخته یا پشتیبانی‌نشده در زنجیره اشاره‌گر بعدی توسط زمان اجرا نادیده گرفته می‌شوند. همچنین، همان‌طور که در بخش یکتایی ساختار زنجیره بعدی توضیح داده شده است، زمان اجرا فقط اولین رخداد ساختار XrSpatialBoundsBoxfANDROID را در زنجیره بعدی پردازش خواهد کرد.

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

• افزونه XR_ANDROID_spatial_discovery_bounds باید قبل‌از استفاده از XrSpatialBoundsBoxfANDROID فعال شود
• type باید XR_TYPE_SPATIAL_BOUNDS_BOXF_ANDROID باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد
• space باید شناسه مجازی XrSpace معتبر باشد

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

typedef struct XrSpatialBoundsFrustumfANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrFrustumf         frustum;
} XrSpatialBoundsFrustumfANDROID;

توضیحات عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
• ‫space همان XrSpace است که هرگونه ژست برای مرزها در آن تعریف می‌شود.
• time یک XrTime است که در آن حالت‌های مرزها تعریف شده است.
• ‫frustum یک XrFrustumf است که حجم هرم ناقصی را توصیف می‌کند که زمان اجرا باید کشف موجودیت‌های فضایی را در آن محدود کند.

قابلیت‌های فضایی که از XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID پشتیبانی می‌کنند (همان‌طور که توسط xrEnumerateSpatialCapabilityFeaturesEXT شمارش شده‌اند) به برنامه اجازه می‌دهند تا با زنجیر کردن XrSpatialBoundsFrustumfANDROID به XrSpatialDiscoverySnapshotCreateInfoEXT :: next ، کاوش را به موجودیت‌های فضایی‌ای محدود کند که مکان یا مرزهای آن‌ها درون frustum قرار دارد یا با آن تلاقی می‌کند. برای عکس آنی اکتشافی که در آن قابلیت مربوطه از XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID پشتیبانی می‌کند، اگر این ساختار در زنجیره next وجود داشته باشد، زمان اجرا نباید شامل هیچ موجودیت فضایی باشد که مکان یا حدود آن کاملاً خارج از frustum باشد.

توجه به این نکته مهم است که گنجاندن XrSpatialBoundsFrustumfANDROID در زنجیره بعدی XrSpatialDiscoverySnapshotCreateInfoEXT به‌عنوان شرط «AND» با سایر فیلترهای ارائه‌شده عمل می‌کند. نهادهایی که از قابلیت‌های فضایی می‌آیند و از XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID پشتیبانی نمی‌کنند نباید در عکس آنی کاوش گنجانده شوند. این رفتار با بقیه مشخصات OpenXR متفاوت است که در آن ساختارهای ناشناخته یا پشتیبانی‌نشده در زنجیره اشاره‌گر بعدی توسط زمان اجرا نادیده گرفته می‌شوند. همچنین، همان‌طور که در بخش یکتایی ساختار زنجیره بعدی توضیح داده شده است، زمان اجرا فقط اولین رخداد ساختار XrSpatialBoundsFrustumfANDROID را در زنجیره بعدی پردازش می‌کند.

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

• افزونه XR_ANDROID_spatial_discovery_bounds باید قبل‌از استفاده از XrSpatialBoundsFrustumfANDROID فعال شود
• type باید XR_TYPE_SPATIAL_BOUNDS_FRUSTUMF_ANDROID باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد
• space باید شناسه مجازی XrSpace معتبر باشد

مثال

کد زیر نشان می‌دهد که چگونه می‌توان از مرزهای فضایی برای فیلتر کردن کشف نهادهای فضایی استفاده کرد.

// previously initialized & configured with the XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT capability.
XrSpatialContextEXT spatialContext;

// Enumerate supported features for XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT capability
uint32_t featureCount = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, 0, &featureCount, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> fooFeatures(featureCount);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, featureCount, &featureCount, fooFeatures.data()));

// Check if spatial sphere bounds filter is supported
const auto supportsFeature = [&fooFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(fooFeatures.begin(), fooFeatures.end(), feature) != fooFeatures.end();
};

const bool supportsSphereBoundsFilter = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID);

// We want to look for entities in a sphere around the head with a radius of 2m.
XrSpatialBoundsSpherefANDROID sphereBounds {
  .type = XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID,
  .space = viewSpace,
  .time = predictedDisplayTime,
  .sphere = {
    .center = {
      .orientation = {
        .w = 1.0f,
      },
    },
    .radius = 2.0f,
  },
};

// We want to look for entities that have the following components.
std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT};

XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{
  .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
  .next = supportsSphereBoundsFilter ? &sphereBounds : nullptr,
  .componentTypeCount = snapshotComponents.size(),
  .componentTypes = snapshotComponents.data(),
};

XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

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

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

  • XrSpatialBoundsBoxfANDROID
  • XrSpatialBoundsFrustumfANDROID
  • XrSpatialBoundsSpherefANDROID

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

• XR_ANDROID_SPATIAL_DISCOVERY_BOUNDS_EXTENSION_NAME
• XR_ANDROID_spatial_discovery_bounds_SPEC_VERSION

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

  • XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID
  • XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID
  • XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

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

  • XR_TYPE_SPATIAL_BOUNDS_BOXF_ANDROID
  • XR_TYPE_SPATIAL_BOUNDS_FRUSTUMF_ANDROID
  • XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID

مشکلات

• چرا پشتیبانی از مرزهای فضایی به تعریف XrSpatialCapabilityFeatureEXT وابسته است؟

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

سابقه نسخه

• بازبینی ۱،‏ ۲۰۲۵-۰۵-۰۳ (نیهاو جین، Google)

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