XR_ANDROID_spatial_discovery_raycast

Name String

XR_ANDROID_spatial_discovery_raycast

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

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

หมายเลขต่อที่ลงทะเบียนไว้

787

การแก้ไข

1

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

ไม่ได้รับการให้สัตยาบัน

ทรัพยากร Dependency ของส่วนขยายและเวอร์ชัน

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 และมีฟังก์ชันการทำงาน Raycast สำหรับความสามารถเชิงพื้นที่ที่มีอยู่ เช่น XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT เพื่อค้นหาเอนทิตีเชิงพื้นที่

ส่วนขยายนี้ยังเปิดตัวความสามารถเชิงพื้นที่ใหม่สำหรับการทำ Raycasting กับบัฟเฟอร์ความลึกด้วย

สิทธิ์

สิทธิ์ที่จำเป็นจะขึ้นอยู่กับความสามารถที่แอปพลิเคชัน 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 ถือเป็นสิทธิ์ที่เป็นอันตราย

(ระดับการป้องกัน: อันตราย)

การสนับสนุนรันไทม์

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

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_spatial_discovery_raycast ก่อนใช้ XrSpatialRaycastInfoANDROID
• type ต้องเป็น XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• space ต้องเป็นแฮนเดิล XrSpace ที่ถูกต้อง

คอมโพเนนต์ผลลัพธ์ 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 ลบจะชี้ไปยังจุดเริ่มต้นของรังสีโดยประมาณ

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_spatial_discovery_raycast ก่อนที่จะใช้ XrSpatialRaycastResultDataANDROID

โครงสร้างรายการคอมโพเนนต์เพื่อค้นหาข้อมูล

โครงสร้าง 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_ANDROID_spatial_discovery_raycast ก่อนใช้ XrSpatialComponentRaycastResultListANDROID
• type ต้องเป็น XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• raycastResults ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของโครงสร้าง raycastResultCount XrSpatialRaycastResultDataANDROID
• พารามิเตอร์ raycastResultCount ต้องมากกว่า 0

การกำหนดค่า

สามารถเปิดใช้ได้โดยใส่ค่า enum ในรายการ XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents หากมีการแจกแจง XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID ใน XrSpatialCapabilityComponentTypesEXT :: componentTypes สำหรับความสามารถบางอย่าง แอปพลิเคชัน คอมโพเนนต์นี้ไม่จำเป็นต้องมีการกำหนดค่าพิเศษใดๆ เพื่อรวมไว้ในเชนถัดไปของ XrSpatialCapabilityConfigurationBaseHeaderEXT

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

ความสามารถเชิงพื้นที่ของ Raycast ความลึก

การกำหนดค่า

โครงสร้าง 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_ANDROID_spatial_discovery_raycast ก่อนใช้ XrSpatialCapabilityConfigurationDepthRaycastANDROID
• type ต้องเป็น XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• capability ต้องเป็นค่า XrSpatialCapabilityEXT ที่ถูกต้อง
• enabledComponents ต้องเป็นตัวชี้ไปยังอาร์เรย์ของค่า XrSpatialComponentTypeEXT ที่ถูกต้อง enabledComponentCount ค่า
• พารามิเตอร์ enabledComponentCount ต้องมากกว่า 0

องค์ประกอบที่รับประกัน

รันไทม์ที่รองรับ 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);

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

• spatialContext คือ XrSpatialContextEXT ที่สร้างขึ้นก่อนหน้านี้โดยใช้ xrCreateSpatialContextAsyncEXT
• createInfo เป็นตัวชี้ไปยัง XrSpatialRaycastSnapshotCreateInfoANDROID
• snapshot เป็นตัวชี้ไปยัง XrSpatialSnapshotEXT

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

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

หากแอปพลิเคชันไม่ได้ระบุรายการประเภทคอมโพเนนต์เชิงพื้นที่ใน XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes รันไทม์ต้องรวมเอนทิตีเชิงพื้นที่ทั้งหมดในสแนปชอตที่มีชุดคอมโพเนนต์ที่แจกแจงใน XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents สำหรับความสามารถที่รองรับ Raycast ที่กำหนดค่าไว้สำหรับ spatialContext รันไทม์ต้องมีข้อมูลสำหรับคอมโพเนนต์ที่เปิดใช้ทั้งหมดของความสามารถที่รองรับ Raycast ซึ่งกำหนดค่าไว้สำหรับ spatialContext

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_spatial_discovery_raycast ก่อนเรียกใช้ xrCreateSpatialRaycastSnapshotANDROID
• spatialContext ต้องเป็นแฮนเดิล XrSpatialContextEXT ที่ถูกต้อง
• createInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialRaycastSnapshotCreateInfoANDROID ที่ถูกต้อง
• snapshot ต้องเป็นตัวชี้ไปยังแฮนเดิล XrSpatialSnapshotEXT

รหัสการคืนสินค้า

สำเร็จ

• 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 ที่อธิบายข้อมูลของรังสี

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_spatial_discovery_raycast ก่อนใช้ XrSpatialRaycastSnapshotCreateInfoANDROID
• type ต้องเป็น XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• หาก componentTypeCount ไม่ใช่ 0 componentTypes ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า XrSpatialComponentTypeEXT ที่ถูกต้อง componentTypeCount ค่า
• raycastInfo ต้องเป็นพอยเตอร์ไปยังโครงสร้าง XrSpatialRaycastInfoANDROID ที่ถูกต้อง

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

กำหนดค่าความสามารถในการติดตามระนาบและ 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

โค้ดตัวอย่างต่อไปนี้แสดงวิธีสร้างสแนปชอต 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);

คำสั่งใหม่

• xrCreateSpatialRaycastSnapshotANDROID

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

• XrSpatialCapabilityConfigurationDepthRaycastANDROID
• XrSpatialRaycastResultDataANDROID
• XrSpatialRaycastSnapshotCreateInfoANDROID

• การขยาย XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentRaycastResultListANDROID

• การขยาย XrSpatialDiscoverySnapshotCreateInfoEXT :

  • XrSpatialRaycastInfoANDROID

ค่าคงที่ 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, 15-07-2025 (Brian Chen)

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