XR_ANDROID_spatial_discovery_raycast

ชื่อสตริง

XR_ANDROID_spatial_discovery_raycast

ประเภทส่วนขยาย

ส่วนขยายอินสแตนซ์

หมายเลขส่วนขยายที่จดทะเบียน

787

การแก้ไข

1

สถานะการให้สัตยาบัน

ยังไม่ให้สัตยาบัน

การขึ้นอยู่กับส่วนขยายและเวอร์ชัน

XR_EXT_spatial_entity

วันที่แก้ไขล่าสุด

2025-08-12

สถานะ IP

ไม่มีการอ้างสิทธิ์ 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 ด้วย หากแอปพลิเคชันใช้ความสามารถทั้ง 2 อย่าง แอปพลิเคชันไม่จำเป็นต้องขอสิทธิ์ทั้ง 2 อย่างแยกกัน

ทั้ง 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 หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • space คือ XrSpace ที่จะวางท่าทางของ XrSpatialRaycastResultDataANDROID
  • time คือ XrTime ที่กำหนดท่าทางของ XrSpatialRaycastResultDataANDROID
  • origin คือ XrVector3f ที่อธิบายต้นทางของรังสี
  • direction คือ XrVector3f ที่อธิบายทิศทางของรังสี
  • maxDistance คือระยะทางเป็นเมตรที่แอปพลิเคชันสามารถ ระบุได้โดยไม่บังคับเพื่อจำกัดการค้นหาเอนทิตีที่อยู่ภายในระยะทางที่ระบุจาก origin ตาม direction

แอปพลิเคชัน สามารถ รวม XrSpatialRaycastInfoANDROID ไว้ในห่วงโซ่ next ของ XrSpatialDiscoverySnapshotCreateInfoEXT เพื่อค้นหาเอนทิตีเชิงพื้นที่ที่ตัดกับรังสีที่กำหนดไว้ในโครงสร้างนี้

หากแอปพลิเคชันใช้ 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 เป็นค่าบวก รันไทม์ต้อง ไม่รวมเอนทิตีเชิงพื้นที่ที่พบในสแนปชอตซึ่งอยู่ห่างจาก panme:origin ตาม direction มากกว่า maxDistance หากตั้งค่า maxDistance เป็น 0 หรือค่าลบ รันไทม์ต้อง ถือว่ารังสีไม่มีขอบเขต

การใช้งานที่ถูกต้อง (โดยนัย)

คอมโพเนนต์ผลลัพธ์การแคสต์รังสี

โครงสร้าง 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_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 หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • raycastResultCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ raycastResults
  • raycastResults คืออาร์เรย์ของ XrSpatialRaycastResultDataANDROID

หากต้องการค้นหาคอมโพเนนต์ผลลัพธ์การแคสต์รังสีของเอนทิตีเชิงพื้นที่ใน XrSpatialSnapshotEXT ให้รวม XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID ไว้ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes และเพิ่ม XrSpatialComponentRaycastResultListANDROID ลงในห่วงโซ่ next ของ XrSpatialComponentDataQueryResultEXT

รันไทม์ต้อง แสดงผล XR_ERROR_VALIDATION_FAILURE จาก xrQuerySpatialComponentDataEXT หาก XrSpatialComponentRaycastResultListANDROID อยู่ในห่วงโซ่ next ของ XrSpatialComponentDataQueryResultEXT แต่ 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 สำหรับความสามารถบางอย่าง แอปพลิเคชันสามารถ เปิดใช้ได้โดยรวมค่า Enum ไว้ในรายการ XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents คอมโพเนนต์นี้ไม่จำเป็นต้องมีการกำหนดค่าพิเศษเพื่อรวมไว้ในห่วงโซ่ถัดไปของ XrSpatialCapabilityConfigurationBaseHeaderEXT

รันไทม์ต้อง แสดงผล XR_ERROR_VALIDATION_FAILURE จาก xrCreateSpatialUpdateSnapshotEXT หากแอปพลิเคชันรวม XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID ไว้ใน XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes คอมโพเนนต์นี้ใช้ได้กับสแนปชอตการค้นหาเท่านั้น

ความสามารถเชิงพื้นที่ในการแคสต์รังสีความลึก

การกำหนดค่า

โครงสร้าง XrSpatialCapabilityConfigurationDepthRaycastANDROID มีคำจำกัดความดังนี้

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

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • 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

การแคสต์รังสีแบบซิงโครนัส

ฟังก์ชัน xrCreateSpatialRaycastSnapshotANDROID มีคำจำกัดความดังนี้

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

คำอธิบายพารามิเตอร์

แม้ว่า xrCreateSpatialDiscoverySnapshotAsyncEXT จะเพียงพอสำหรับกรณีการใช้งานส่วนใหญ่ แต่ถือว่าช้าสำหรับแอปพลิเคชันที่ต้องการผลลัพธ์การแคสต์รังสีทันที xrCreateSpatialRaycastSnapshotANDROID จะเริ่มการแคสต์รังสีแบบซิงโครนัสเพื่อสร้างสแนปชอต ซึ่งช่วยให้แอปพลิเคชันเริ่มค้นหาผลลัพธ์การแคสต์รังสีได้ทันที

รันไทม์ต้อง แสดงผล XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT หากไม่ได้เปิดใช้ XrSpatialComponentTypeEXT รายการใดรายการหนึ่งใน XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes สำหรับความสามารถเชิงพื้นที่ที่ส่งไปยัง XrSpatialContextCreateInfoEXT :: capabilityConfigs เมื่อสร้าง spatialContext

หากแอปพลิเคชันไม่ได้ระบุรายการประเภทคอมโพเนนต์เชิงพื้นที่ใน XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes รันไทม์ต้อง รวมเอนทิตีเชิงพื้นที่ทั้งหมดไว้ในสแนปชอตที่มีชุดคอมโพเนนต์ที่แจกแจงไว้ใน XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents สำหรับความสามารถที่รองรับการแคสต์รังสีซึ่งกำหนดค่าไว้สำหรับ spatialContext รันไทม์ต้อง รวมข้อมูลสำหรับคอมโพเนนต์ที่เปิดใช้ทั้งหมดของความสามารถที่รองรับการแคสต์รังสีซึ่งกำหนดค่าไว้สำหรับ 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 หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน Core OpenXR หรือส่วนขยายนี้
  • componentTypeCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ componentTypes
  • componentTypes คืออาร์เรย์ของ XrSpatialComponentTypeEXT
  • raycastInfo คือโครงสร้าง XrSpatialRaycastInfoANDROID ที่อธิบายข้อมูลของรังสี

การใช้งานที่ถูกต้อง (โดยนัย)

โค้ดตัวอย่าง

กำหนดค่าความสามารถในการแคสต์รังสีความลึกและการติดตามระนาบ

โค้ดตัวอย่างต่อไปนี้แสดงวิธีสร้างบริบทเชิงพื้นที่ที่มีความสามารถที่รองรับฟังก์ชันการแคสต์รังสี สำหรับตัวอย่างนี้ เราจะใช้ 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);

สร้างสแนปชอตการแคสต์รังสี

โค้ดตัวอย่างต่อไปนี้แสดงวิธีสร้างสแนปชอตการแคสต์รังสีแบบซิงโครนัส

// 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);

คำสั่งใหม่

โครงสร้างใหม่

ค่าคงที่ Enum ใหม่

  • 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, 2025-07-15 (Brian Chen)

    • คำอธิบายส่วนขยายเริ่มต้น