XR_ANDROID_spatial_discovery_raycast

رشته نام

XR_ANDROID_spatial_discovery_raycast

نوع افزونه

افزونه نمونه

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

787

بازبینی

1

وضعیت تصویب

تصویب‌نشده

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

XR_EXT_spatial_entity

تاریخ آخرین تغییر

2025-08-12

وضعیت IP

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

همیاران

Brian Chen،‏ Google
Levana Chen،‏ Google
Kyle Chen،‏ Google
Nihav Jain،‏ Google
Spencer Quin،‏ Google
Natalie Fleury،‏ Meta
Yuichi Taguchi،‏ Meta
Jimmy Alamparambil،‏ ByteDance
Zhipeng Liu،‏ ByteDance

نمای کلی

این افزونه برپایه XR_EXT_spatial_entity ساخته شده است و عملکرد پرتوتابی را برای قابلیت‌های فضایی موجود، مانند XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT ، برای کشف موجودیت‌های فضایی ارائه می‌دهد.

این افزونه همچنین قابلیت فضایی جدیدی برای پرتوتابی دربرابر میان‌گیر عمق معرفی می‌کند.

اجازه‌ها

اجازه‌های لازم بسته به قابلیت‌هایی که برنامه Android استفاده می‌کند. اگر از XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID استفاده شود، برنامه باید اجازه android.permission.SCENE_UNDERSTANDING_FINE را داشته باشد. اگر از XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT استفاده شود، برنامه باید اجازه android.permission.SCENE_UNDERSTANDING_COARSE را داشته باشد. ‫android.permission.SCENE_UNDERSTANDING_FINE همچنین به‌معنای اجازه android.permission.SCENE_UNDERSTANDING_COARSE است، اگر برنامه از هر دو قابلیت استفاده کند، برنامه نیازی به درخواست جداگانه هر دو اجازه ندارد.

هر دو android.permission.SCENE_UNDERSTANDING_COARSE و android.permission.SCENE_UNDERSTANDING_FINE اجازه‌های خطرناک محسوب می‌شوند.

(سطح محافظت: خطرناک)

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

اگر زمان اجرا از کشف موجودیت‌های فضایی ازطریق پرتوتابی پشتیبانی می‌کند، باید این موضوع را با شمارش XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID در xrEnumerateSpatialCapabilityComponentTypesEXT برای قابلیت‌هایی که از کشف با پرتوتابی پشتیبانی می‌کنند نشان دهد.

اگر زمان اجرا از پرتوتابی درمقابل میان‌گیر عمق پشتیبانی می‌کند، باید XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID را در xrEnumerateSpatialCapabilitiesEXT فهرست کند.

کشف نهادهای فضایی با پرتوتابی

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

typedef struct XrSpatialRaycastInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrVector3f         origin;
    XrVector3f         direction;
    float              maxDistance;
} XrSpatialRaycastInfoANDROID;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫space همان XrSpace است که حالت XrSpatialRaycastResultDataANDROID در آن قرار خواهد گرفت.
  • ‫time یک XrTime است که در آن حالت XrSpatialRaycastResultDataANDROID تعریف شده است.
  • ‫origin یک XrVector3f است که مبدأ پرتو را توصیف می‌کند.
  • direction یک XrVector3f است که جهت پرتو را توصیف می‌کند.
  • maxDistance فاصله‌ای به متر است که برنامه می‌تواند به‌طور اختیاری برای محدود کردن کاوش نهادهایی که در فاصله مشخص‌شده از origin ، در امتداد direction قرار دارند، مشخص کند.

برنامه می‌تواند XrSpatialRaycastInfoANDROID را در زنجیره XrSpatialDiscoverySnapshotCreateInfoEXT :: next اضافه کند تا موجودیت‌های فضایی را که با پرتو تعریف‌شده در این ساختار تلاقی دارند کشف کند.

اگر برنامه‌ای از XrSpatialRaycastInfoANDROID با XrSpatialContextEXT استفاده کند که بدون فعال کردن XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID برای هر قابلیتی پیکربندی شده باشد، زمان اجرا باید XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT را از xrCreateSpatialDiscoverySnapshotAsyncEXT یا xrCreateSpatialRaycastSnapshotANDROID برگرداند.

زمان اجرا باید شامل داده‌های مؤلفه و شناسه‌های فقط آن موجودیت‌های فضایی در XrSpatialSnapshotEXT باشد که از قابلیت‌های پشتیبانی‌کننده از مؤلفه XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID می‌آیند.

اگر برنامه‌ای maxDistance را روی مقدار مثبت تنظیم کند، زمان اجرا نباید هیچ نهاد فضایی ضربه‌خورده‌ای را در عکس آنی که بیش‌از maxDistance از panme:origin در امتداد direction فاصله دارد لحاظ کند. اگر maxDistance روی ۰ یا مقدار منفی تنظیم شده باشد، زمان اجرا باید پرتو را نامحدود درنظر بگیرد.

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

عنصر نتیجه Raycast

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

typedef struct XrSpatialRaycastResultDataANDROID {
    XrPosef    hitPose;
    float      distanceSquared;
} XrSpatialRaycastResultDataANDROID;

توضیحات عضو

  • hitPose یک XrPosef است که نقطه‌ای را که پرتو با موجودیت فضایی تلاقی می‌کند تعریف می‌کند.
  • distanceSquared مجذور فاصله از مبدأ پرتو تا نقطه تقاطع است.

مؤلفه XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID فقط در XrSpatialSnapshotEXT ایجادشده از xrCreateSpatialDiscoverySnapshotAsyncEXT وجود خواهد داشت که در آن XrSpatialRaycastInfoANDROID در زنجیره XrSpatialDiscoverySnapshotCreateInfoEXT :: next یا در XrSpatialSnapshotEXT ایجادشده از xrCreateSpatialRaycastSnapshotANDROID گنجانده شده است.

زمان اجرا نباید این مؤلفه را در هیچ XrSpatialSnapshotEXT که بااستفاده از xrCreateSpatialUpdateSnapshotEXT ایجاد شده است لحاظ کند.

اگر برنامه XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID را در XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes لحاظ کند، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را از xrCreateSpatialUpdateSnapshotEXT برگرداند.

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

‫hitPose مربوط به XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID در XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace در XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time قرار خواهد گرفت. محور Z مثبت، بردار نرمال سطح برخورد است و محور Y منفی تقریباً به‌سمت مبدأ پرتو اشاره می‌کند.

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

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

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

typedef struct XrSpatialComponentRaycastResultListANDROID {
    XrStructureType                       type;
    void*                                 next;
    uint32_t                              raycastResultCount;
    XrSpatialRaycastResultDataANDROID*    raycastResults;
} XrSpatialComponentRaycastResultListANDROID;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • raycastResultCount یک uint32_t است که تعداد عناصر را در آرایه raycastResults توصیف می‌کند.
  • ‫raycastResults آرایه‌ای از XrSpatialRaycastResultDataANDROID است.

برای پرسمان مؤلفه نتیجه پرتوتابی موجودیت‌های فضایی در XrSpatialSnapshotEXT ، XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID را در XrSpatialComponentDataQueryConditionEXT :: componentTypes اضافه کنید و XrSpatialComponentRaycastResultListANDROID را به زنجیره XrSpatialComponentDataQueryResultEXT :: next اضافه کنید.

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

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

raycastResults برگردانده‌شده نامرتب است. برنامه می‌تواند از XrSpatialRaycastResultDataANDROID :: distanceSquared برای مرتب‌سازی نتایج براساس فاصله استفاده کند.

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

پیکربندی

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

اگر برنامه XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID را در XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes لحاظ کند، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را از xrCreateSpatialUpdateSnapshotEXT برگرداند. این مؤلفه مختص عکس‌های آنی کاوش است.

قابلیت فضایی پرتوتابی عمق

پیکربندی

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

typedef struct XrSpatialCapabilityConfigurationDepthRaycastANDROID {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationDepthRaycastANDROID;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫capability یک XrSpatialCapabilityEXT است و باید XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID باشد.
  • enabledComponentCount یک uint32_t است که تعداد عناصر را در آرایه enabledComponents توصیف می‌کند. باید بزرگ‌تر از ۰ باشد.
  • ‫enabledComponents اشاره‌گری به آرایه‌ای از XrSpatialComponentTypeEXT است.

برنامه‌ها می‌توانند قابلیت فضایی XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID را با گنجاندن اشاره‌گری به ساختار XrSpatialCapabilityConfigurationDepthRaycastANDROID در XrSpatialContextCreateInfoEXT :: capabilityConfigs فعال کنند.

اگر capability XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID نباشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند.

شناسه نهادهای کشف‌شده ازطریق این قابلیت همیشه XR_NULL_SPATIAL_ENTITY_ID_EXT است. این همچنین به این معنی است که برنامه نمی‌تواند دسته XrSpatialEntityEXT برای این موجودیت‌ها ایجاد کند، و بنابراین آن‌ها نمی‌توانند در XrSpatialUpdateSnapshotCreateInfoEXT :: entities برای ایجاد عکس آنی به‌روزرسانی گنجانده شوند

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

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

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

  • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Raycast هم‌زمان

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

XrResult xrCreateSpatialRaycastSnapshotANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialRaycastSnapshotCreateInfoANDROID* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

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

درحالی‌که xrCreateSpatialDiscoverySnapshotAsyncEXT برای اکثر موارد استفاده کافی است، برای برنامه‌هایی که به نتایج فوری پرتوتابی نیاز دارند کند محسوب می‌شود. xrCreateSpatialRaycastSnapshotANDROID یک پرتوتابی همگام را برای ایجاد عکس آنی شروع می‌کند که به برنامه‌ها اجازه می‌دهد فوراً پرسمان نتایج پرتوتابی را شروع کنند.

اگر هرکدام از XrSpatialComponentTypeEXT در XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes برای قابلیت‌های فضایی ارسال‌شده به XrSpatialContextCreateInfoEXT :: capabilityConfigs هنگام ایجاد spatialContext فعال نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT را برگرداند.

اگر برنامه فهرست انواع مؤلفه‌های فضایی را در XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes ارائه نکند، زمان اجرا باید همه موجودیت‌های فضایی را در عکس آنی که دارای مجموعه مؤلفه‌های فهرست‌شده در XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents برای قابلیت‌های پشتیبانی‌شده raycast پیکربندی‌شده برای spatialContext هستند لحاظ کند. زمان اجرا باید شامل داده‌های مربوط به همه مؤلفه‌های فعال‌شده قابلیت‌های پشتیبانی‌شده raycast پیکربندی‌شده برای spatialContext باشد.

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

کدهای برگشتی

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

  • 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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialRaycastSnapshotCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    uint32_t                              componentTypeCount;
    const XrSpatialComponentTypeEXT*      componentTypes;
    const XrSpatialRaycastInfoANDROID*    raycastInfo;
} XrSpatialRaycastSnapshotCreateInfoANDROID;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
  • componentTypeCount یک uint32_t است که تعداد عناصر را در آرایه componentTypes توصیف می‌کند.
  • ‫componentTypes آرایه‌ای از XrSpatialComponentTypeEXT است.
  • ‫raycastInfo ساختار XrSpatialRaycastInfoANDROID است که اطلاعات پرتو را توصیف می‌کند.

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

کد نمونه

پیکربندی قابلیت ردیابی صفحه و Depth Raycast

کد نمونه زیر نشان می‌دهد که چگونه یک بافت فضایی با قابلیت‌هایی ایجاد کنید که از عملکرد raycast پشتیبانی می‌کنند. برای این مثال، از XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID و XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT استفاده می‌شود.

// Check runtime supported capabilities
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID) == capabilities.end()) {
  return;
}

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT) == capabilities.end()) {
  return;
}

// Create capability config for depth raycasting
std::vector<XrSpatialComponentTypeEXT> depthRaycastComponents {
  XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID
};

// Create capability config for depth raycasting
XrSpatialCapabilityConfigurationDepthRaycastANDROID depthRaycastConfig {
  .type = XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROID,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID,
  .enabledComponentCount = (uint32_t)depthRaycastComponents.size(),
  .enabledComponents = depthRaycastComponents.data(),
};

// Enumerate runtime supported components for plane tracking capability
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes {
  XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
};

bool isRaycastSupportedViaPlaneTracking;
std::vector<XrSpatialComponentTypeEXT> planeTrackingComponents {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};

CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId,
       XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &capabilityComponentTypes));

planeTrackingComponents.resize(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = (uint32_t)planeTrackingComponents.size();
capabilityComponentTypes.componentTypes = planeTrackingComponents.data();

CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId,
       XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &capabilityComponentTypes));

// Check if raycast is supported by plane tracking
isRaycastSupportedViaPlaneTracking = std::find(planeTrackingComponents.begin(),
planeTrackingComponents.end(), XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID)
!= planeTrackingComponents.end();

// Create capability config for plane tracking
XrSpatialCapabilityConfigurationPlaneTrackingEXT planeTrackingConfig {
  .type = XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT,
  .enabledComponentCount = (uint32_t)planeTrackingComponents.size(),
  .enabledComponents = planeTrackingComponents.data(),
};

// Create spatial context
// Types of raycast is determined by configs included in XrSpatialContextCreateInfoEXT
// For this example, both plane raycast & depth raycast are performed
std::vector<const XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
capabilityConfigs.push_back(reinterpret_cast<const XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&depthRaycastConfig));
if(isRaycastSupportedViaPlaneTracking) capabilityConfigs.push_back(reinterpret_cast<const XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&planeTrackingConfig));

XrSpatialContextCreateInfoEXT contextCreateInfo {
  .type = XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT,
  .next = nullptr,
  .capabilityConfigCount = (uint32_t)capabilityConfigs.size(),
  .capabilityConfigs = capabilityConfigs.data(),
};

CHK_XR(xrCreateSpatialContextAsyncEXT(session, &contextCreateInfo, &future))

// Completes creating spatial context
XrCreateSpatialContextCompletionEXT contextCompletion{
XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};

CHK_XR(xrCreateSpatialContextCompleteEXT(session, future, &contextCompletion))

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

کد نمونه زیر نشان می‌دهد که چگونه می‌توان موجودیت‌های فضایی را برای زمینه‌ای که با XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID و XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT پیکربندی شده است کشف کرد و داده‌های مؤلفه آن را پُرسمان کرد.

// Fill in the raycast info.
XrSpatialRaycastInfoANDROID raycastInfo {
  .type        = XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID,
  .next        = nullptr,
  .space       = viewSpace,
  .time        = updateTime,
  .origin      = {0.0f, 0.0f, 0.0f},
  .direction   = {0.0f, 0.0f,-1.0f},
  .maxDistance = 0.0f  // ray is unbounded
};

// Next pointing to the raycast info.
XrSpatialDiscoverySnapshotCreateInfoEXT discoverySnapshotCreateInfo {
  .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
  .next = &raycastInfo
};

// Create snapshot
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT (
spatialContext, &discoverySnapshotCreateInfo, &future));

waitUntilReady(future);

// Complete async operation.
XrCreateSpatialDiscoverySnapshotCompletionInfoEXT
  createSnapshotCompletionInfo {
    .type      = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT,
    .baseSpace = viewSpace,
    .time      = updateTime,
    .future    = future,
  };

XrCreateSpatialDiscoverySnapshotCompletionEXT completion {
  XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};

CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(
           spatialContext, &createSnapshotCompletionInfo,
           &completion));

if(completion.futureResult != XR_SUCCESS) return;

// Query hit result components
std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID
};

XrSpatialComponentDataQueryConditionEXT queryCond {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
  .componentTypeCount = 1,
  .componentTypes     = enabledComponents.data(),
};

XrSpatialComponentDataQueryResultEXT queryResult {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
};

XrResult result = xrQuerySpatialComponentDataEXT(
           completion.snapshot, &queryCond, &queryResult);

// Check query result.
if(result != XR_SUCCESS) return;

// Query again for the hit result list.
std::vector<XrSpatialRaycastResultDataANDROID> raycastResults;
raycastResults.resize(queryResult.entityIdCountOutput);
XrSpatialComponentRaycastResultListANDROID raycastResultList {
  .type               = XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID,
  .raycastResultCount = (uint32_t)raycastResults.size(),
  .raycastResults     = raycastResults.data(),
};

queryResult.next = &raycastResultList;
result = xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult);

// Check query result again.
if(result != XR_SUCCESS) return;

std::vector<XrSpatialEntityEXT> hitEntities;
std::vector<XrPosef> depthHitPoses;
for(uint32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
    // access raycastResults[i] for id & pose
    XrSpatialEntityIdEXT   id   = queryResult.entityIds[i];
    XrPosef                pose = raycastResults[i].hitPose;

    if (id != XR_NULL_SPATIAL_ENTITY_ID_EXT) {
        // hit entities (e.g. planes)
    // get entity handle via entity id
    XrSpatialEntityFromIdCreateInfoEXT entityCreateInfo {
      .type = XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT,
      .entityId = id,
    };

    XrSpatialEntityEXT entity = XR_NULL_HANDLE;
    xrCreateSpatialEntityFromIdEXT(spatialContext, &entityCreateInfo, &entity);

    hitEntities.push_back(entity);
  } else {
    // hit depth
    depthHitPoses.push_back(pose);
  }
}

// Cleanup
xrDestroySpatialSnapshotEXT(completion.snapshot);

ایجاد عکس آنی Raycast

کد نمونه زیر نحوه ایجاد عکس آنی پرتوتابی همگام را نشان می‌دهد.

// fill in create info
XrSpatialRaycastSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID,
  .componentTypeCount = 0,   // include all hit spatial entities
  .componentTypes = nullptr,
  .raycastInfo = &raycastInfo
};

// create raycast snapshot
XrSpatialSnapshotEXT raycastSnapshot = XR_NULL_HANDLE;
CHK_XR(xrCreateSpatialRaycastSnapshotANDROID(
  spatialContext, &createInfo, &raycastSnapshot));

// ...
// query component data as previous example
// ...

// Cleanup
xrDestroySpatialSnapshotEXT(raycastSnapshot);

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

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

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

  • XR_ANDROID_SPATIAL_DISCOVERY_RAYCAST_EXTENSION_NAME
  • XR_ANDROID_spatial_discovery_raycast_SPEC_VERSION

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

    • XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

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

    • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

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

    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROID
    • XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID
    • XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID
    • XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID

مشکلات

سابقه نسخه

  • بازبینی ۱، ‎۲۰۲۵-۰۷-۱۵ (Brian Chen)

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