XR_ANDROID_spatial_discovery_raycast

رشته نام

XR_ANDROID_spatial_discovery_raycast

نوع افزونه

افزونه نمونه

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

۷۸۷ عدد

بازنگری

۱

وضعیت تصویب

تصویب نشده

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

XR_EXT_spatial_entity

آخرین تاریخ اصلاح

۲۰۲۵-۰۸-۱۲

وضعیت آی‌پی

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

مشارکت‌کنندگان

برایان چن، گوگل
لوانا چن، گوگل
کایل چن، گوگل
نیهاو جین، گوگل
اسپنسر کوئین، گوگل
ناتالی فلوری، متا
یویچی تاگوچی، متا
جیمی آلمپارامبیل، بایت‌دنس
ژیپنگ لیو، ByteDance

نمای کلی

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

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

مجوزها

مجوزهای مورد نیاز بسته به قابلیت‌هایی که برنامه اندروید استفاده می‌کند. اگر از 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 مجوزهای خطرناک محسوب می‌شوند.

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

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

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

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

کشف موجودیت‌های مکانی با استفاده از raycasting

ساختار 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 روی 0 یا مقدار منفی تنظیم شود، زمان اجرا باید پرتو را بدون مرز در نظر بگیرد.

کاربرد معتبر (ضمنی)

کامپوننت نتیجه Raycast

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

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

توضیحات اعضا

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

کامپوننت XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID فقط در XrSpatialSnapshotEXT ایجاد شده از xrCreateSpatialDiscoverySnapshotAsyncEXT وجود خواهد داشت که در آن XrSpatialRaycastInfoANDROID در زنجیره next XrSpatialDiscoverySnapshotCreateInfoEXT :: یا در 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 است.

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

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

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

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

کاربرد معتبر (ضمنی)

پیکربندی

اگر XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID برای برخی قابلیت‌ها در XrSpatialCapabilityComponentTypesEXT :: componentTypes شمارش شده باشد، برنامه می‌تواند با قرار دادن مقدار enum در لیست 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 را توصیف می‌کند. این مقدار باید بزرگتر از 0 باشد.
  • 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 برای ایجاد یک snapshot به‌روزرسانی، لحاظ کند.

کاربرد معتبر (ضمنی)

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

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

  • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

پخش همزمان پرتو

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

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

توضیحات پارامتر

اگرچه xrCreateSpatialDiscoverySnapshotAsyncEXT برای اکثر موارد استفاده کافی است، اما برای برنامه‌هایی که به نتایج raycast فوری نیاز دارند، کند تلقی می‌شود. xrCreateSpatialRaycastSnapshotANDROID یک raycasting همزمان را برای ایجاد یک snapshot آغاز می‌کند که به برنامه‌ها اجازه می‌دهد بلافاصله شروع به پرس‌وجو از نتایج raycast کنند.

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

اگر برنامه فهرستی از انواع مؤلفه‌های مکانی را در XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes ارائه ندهد، زمان اجرا باید شامل تمام موجودیت‌های مکانی در snapshot باشد که دارای مجموعه‌ای از مؤلفه‌هایی هستند که در 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 و Plane Tracking

کد نمونه زیر نحوه ایجاد یک زمینه مکانی با قابلیت‌هایی که از قابلیت 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

کد مثال زیر نحوه ایجاد 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

مسائل

تاریخچه نسخه

  • نسخه ۱، ۲۰۲۵-۰۷-۱۵ (برایان چن)

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