XR_ANDROID_spatial_discovery_raycast

Name String

XR_ANDROID_spatial_discovery_raycast

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

787

المراجعة

1

حالة التصديق

لم تتم المصادقة عليها

الاعتماد على الإضافات والإصدارات

XR_EXT_spatial_entity

تاريخ آخر تعديل

2025-08-12

حالة الملكية الفكرية

ما مِن مطالبات معروفة بشأن الملكية الفكرية.

المساهمون

براين تشن، Google
ليفانا تشن، Google
كايل تشن، Google
نيهاف جاين، Google
سبنسر كوين، Google
ناتالي فلوري، Meta
يويتشي تاغوتشي، Meta
جيمي ألامبارامبيل، ByteDance
تشيبينغ ليو، ByteDance

نظرة عامة

تستند هذه الإضافة إلى XR_EXT_spatial_entity وتوفّر وظيفة raycast للإمكانات المكانية الحالية، مثل 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 من الأذونات الخطيرة.

(مستوى الحماية: خطير)

دعم بيئة التشغيل

إذا كان وقت التشغيل يتيح اكتشاف الكيانات المكانية من خلال تقنية Raycasting، يجب أن يشير إلى ذلك من خلال تعداد XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID في xrEnumerateSpatialCapabilityComponentTypesEXT للإمكانات التي تتيح الاكتشاف من خلال تقنية Raycast.

إذا كان وقت التشغيل يتيح استخدام تقنية تتبُّع الأشعة مع مخزن العمق المؤقت، يجب تعداد 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 على 0 أو قيمة سالبة، يجب أن يعتبر وقت التشغيل الشعاع غير محدود.

الاستخدام الصالح (ضمني)

مكوِّن نتيجة 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_ERROR_VALIDATION_FAILURE من xrCreateSpatialUpdateSnapshotEXT إذا كان التطبيق يتضمّن XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID في XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes .

إذا تم تفعيل 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 إلى سلسلة XrSpatialComponentDataQueryResultEXT :: next.

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE من xrQuerySpatialComponentDataEXT إذا كان XrSpatialComponentRaycastResultListANDROID في السلسلة XrSpatialComponentDataQueryResultEXT :: next ولكن لم يتم تضمين XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID في XrSpatialComponentDataQueryConditionEXT :: componentTypes .

يجب أن يعرض وقت التشغيل XR_ERROR_SIZE_INSUFFICIENT من xrQuerySpatialComponentDataEXT إذا كان raycastResultCount أقل من XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

تكون قيم raycastResults المعروضة غير مرتبة. يمكن للتطبيق استخدام XrSpatialRaycastResultDataANDROID :: distanceSquared لترتيب النتائج حسب المسافة.

الاستخدام الصالح (ضمني)

الإعداد

إذا تم تعداد XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID في XrSpatialCapabilityComponentTypesEXT :: componentTypes لبعض الإمكانات، يمكن للتطبيق تفعيلها من خلال تضمين قيمة التعداد في قائمة XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. لا يتطلّب هذا المكوّن أي إعدادات خاصة ليتم تضمينه في السلسلة التالية من XrSpatialCapabilityConfigurationBaseHeaderEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE من xrCreateSpatialUpdateSnapshotEXT إذا كان التطبيق يتضمّن XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID في XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . هذا المكوّن مخصّص للقطات الاستكشاف.

إمكانية استخدام ميزة Depth Raycast Spatial

الإعداد

يتم تعريف بنية 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 .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE إذا لم يكن capability هو XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID .

يكون معرّف الكيانات التي يتم اكتشافها من خلال هذه الإمكانية دائمًا XR_NULL_SPATIAL_ENTITY_ID_EXT . يعني ذلك أيضًا أنّ التطبيق لا يمكنه إنشاء معالِج XrSpatialEntityEXT لهذه الكيانات، وبالتالي لا يمكن تضمينها في XrSpatialUpdateSnapshotCreateInfoEXT :: entities لإنشاء لقطة تحديث

الاستخدام الصالح (ضمني)

المكوّنات المضمونة

يجب أن تتيح بيئة التشغيل التي تتوافق مع XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID المكوّنات المكانية التالية كمكوّنات مضمونة للكيانات التي تم اكتشافها من خلال هذه الإمكانية، ويجب تعدادها في xrEnumerateSpatialCapabilityComponentTypesEXT -

  • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Synchronous Raycast

يتم تعريف الدالة xrCreateSpatialRaycastSnapshotANDROID على النحو التالي:

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

أوصاف المَعلمات

على الرغم من أنّ xrCreateSpatialDiscoverySnapshotAsyncEXT كافية لمعظم حالات الاستخدام، إلا أنّها تُعدّ بطيئة للتطبيقات التي تتطلّب نتائج فورية من Raycast. تبدأ xrCreateSpatialRaycastSnapshotANDROID عملية Raycast متزامنة لإنشاء لقطة، ما يسمح للتطبيقات ببدء طلب نتائج Raycast على الفور.

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT إذا لم يتم تفعيل أي من XrSpatialComponentTypeEXT في XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes للإمكانات المكانية التي تم تمريرها إلى XrSpatialContextCreateInfoEXT :: capabilityConfigs عند إنشاء spatialContext .

إذا لم يوفّر التطبيق قائمة بأنواع المكوّنات المكانية في XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes، يجب أن يتضمّن وقت التشغيل جميع الكيانات المكانية في اللقطة التي تحتوي على مجموعة المكوّنات التي تم تعدادها في XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents لإمكانات raycast المتوافقة التي تم ضبطها لـ spatialContext . يجب أن يتضمّن وقت التشغيل بيانات جميع المكوّنات المفعَّلة لإمكانات تتبُّع الأشعة المتاحة والتي تم ضبطها لـ "spatialContext".

الاستخدام الصالح (ضمني)

رموز الإرجاع

Success

  • 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 التي تصف معلومات الشعاع.

الاستخدام الصالح (ضمني)

مثال على الشفرة

ضبط ميزة "تتبُّع السطح" و"شعاع العمق"

يوضّح الرمز البرمجي في المثال التالي كيفية إنشاء سياق مكاني يتضمّن إمكانات تتيح استخدام وظيفة 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

يوضّح الرمز النموذجي التالي كيفية إنشاء لقطة متزامنة لـ 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

المشاكل

سجلّ الإصدارات

  • المراجعة 1، ‏15-07-2025 (براين تشن)

    • وصف الإضافة الأوّلي