ส่วนขยาย XR_ANDROID_raycast OpenXR

สตริงชื่อ

XR_ANDROID_raycast

ประเภทชิ้นงาน

การขยายอินสแตนซ์

หมายเลขต่อที่จดทะเบียน

464

การแก้ไข

1

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

XR_ANDROID_trackables

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

2024-10-02

สถานะ IP

ไม่มีการอ้างสิทธิ์ IP ที่ทราบ

ผู้เขียน

Spencer Quin จาก Google

Nihav Jain จาก Google

John Pursey จาก Google

Jared Finder จาก Google

Levana Chen จาก Google

Kenny Vercaemer จาก Google

ภาพรวม

ส่วนขยายนี้ช่วยให้แอปพลิเคชันทำการเรย์แคสต์กับสิ่งที่ติดตามได้ในสภาพแวดล้อม เรย์แคสต์มีประโยชน์ในการตรวจจับวัตถุในสภาพแวดล้อมที่เรย์จะตัดกัน เช่น

• วิธีระบุตําแหน่งที่วัตถุที่ลอยอยู่จะตกลงเมื่อปล่อยโดยใช้การแรย์แคสต์แนวตั้ง
• เพื่อระบุจุดที่ผู้ใช้กําลังมองอยู่โดยใช้เรย์แคสต์ที่หันไปข้างหน้า

ค้นหาความสามารถของ Raycast ที่รองรับ

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

XrResult xrEnumerateRaycastSupportedTrackableTypesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    trackableTypeCapacityInput,
    uint32_t*                                   trackableTypeCountOutput,
    XrTrackableTypeANDROID*                     trackableTypes);

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

• instance คือ XrInstance ที่ดึงข้อมูล systemId ออกมา
• systemId คือ XrSystemId ที่กำลังแสดงรายการประเภทที่ติดตามได้ซึ่งรองรับการแรย์แคสต์
• trackableTypeCapacityInput คือความจุของ trackableTypes หรือ 0 เพื่อดึงข้อมูลความจุที่จําเป็น
• trackableTypeCountOutput คือพอยน์เตอร์ไปยังจํานวนอาร์เรย์ หรือพอยน์เตอร์ไปยังความจุที่จําเป็นในกรณีที่trackableTypeCapacityInputไม่เพียงพอ
  • trackableTypes เป็นพอยน์เตอร์ไปยังอาร์เรย์ XrTrackableTypeANDROID แต่สามารถเป็น NULL ได้หาก trackableTypeCapacityInput เป็น 0
• ดูรายละเอียดเกี่ยวกับการดึงข้อมูลtrackableTypesขนาดที่ต้องการได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

xrEnumerateRaycastSupportedTrackableTypesANDROID จะแสดงรายการประเภทที่ติดตามได้ซึ่งรองรับการแรย์แคสต์ตามเซสชันปัจจุบัน

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_raycast ก่อนเรียกใช้ xrEnumerateRaycastSupportedTrackableTypesANDROID
• instance ต้องเป็นตัวแฮนเดิล XrInstance ที่ถูกต้อง
• trackableTypeCountOutput ต้องเป็นพอยน์เตอร์ไปยังค่า uint32_t
• หาก trackableTypeCapacityInput ไม่ใช่ 0 trackableTypes ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า trackableTypeCapacityInput XrTrackableTypeANDROID

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

สำเร็จ

• XR_SUCCESS

ไม่สำเร็จ

• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SYSTEM_INVALID
• XR_ERROR_FUNCTION_UNSUPPORTED

ทำการแรย์แคสต์

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

XrResult xrRaycastANDROID(
    XrSession                                   session,
    const XrRaycastInfoANDROID*                 rayInfo,
    XrRaycastHitResultsANDROID*                 results);

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

• session คือ XrSession ที่ใช้เรย์แคสต์
• rayInfo คือ XrRaycastInfoANDROID ที่อธิบายเรย์ที่จะแคสต์
• results เป็นพอยน์เตอร์ไปยัง XrRaycastHitResultsANDROID ที่ได้รับผลลัพธ์ของการแรย์แคสต์

แอปพลิเคชันสามารถทำการเรย์แคสต์ได้โดยเรียกใช้ xrRaycastANDROID

• หากเรย์แคสต์ตัดกับวัตถุที่ติดตามได้มากกว่า XrRaycastHitResultsANDROID::maxResults รันไทม์ต้องแสดงผลลัพธ์การตีที่ใกล้กับ XrRaycastHitResultsANDROID::origin ของเรย์มากที่สุด
• หากเรย์แคสต์ตัดกับสิ่งที่ติดตามได้ประเภท XR_TRACKABLE_TYPE_ANDROID_PLANE ซึ่งอยู่ภายใต้ระนาบอื่น รันไทม์ต้องแสดงผลลัพธ์การตีกลับสำหรับระนาบที่ครอบคลุมเท่านั้น
• รันไทม์ต้องแสดงผลลัพธ์ Hit ตามลําดับจากใกล้ที่สุดไปจนถึงไกลที่สุดจาก XrRaycastInfoANDROID::origin ตามเวกเตอร์ XrRaycastInfoANDROID::trajectory
• รันไทม์ต้องแสดงผล XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID หากไม่มีการจัดเรียงประเภทที่ติดตามได้ซึ่งสอดคล้องกับตัวแฮนเดิล XrTrackableTrackerANDROID ใน XrRaycastInfoANDROID::trackers โดย xrEnumerateRaycastSupportedTrackableTypesANDROID

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_raycast ก่อนเรียกใช้ xrRaycastANDROID
• session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
• rayInfo ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrRaycastInfoANDROID ที่ถูกต้อง
• results ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrRaycastHitResultsANDROID

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

สำเร็จ

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ไม่สำเร็จ

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_POSE_INVALID
• XR_ERROR_TIME_INVALID
• XR_ERROR_FEATURE_UNSUPPORTED

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

typedef struct XrRaycastInfoANDROID {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            maxResults;
    uint32_t                            trackerCount;
    const XrTrackableTrackerANDROID*    trackers;
    XrVector3f                          origin;
    XrVector3f                          trajectory;
    XrSpace                             space;
    XrTime                              time;
} XrRaycastInfoANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• maxResults คือจำนวนผลลัพธ์สูงสุด uint32_t รายการที่จะแสดง
• trackerCount คือจํานวน uint32_t ของอาร์เรย์ trackers
• trackers คืออาร์เรย์ XrTrackableTrackerANDROID ที่ควรทดสอบกับเรย์แคสต์
• origin คือ XrVector3f ที่ปล่อยรังสี
• trajectory คือ XrVector3f ที่กําหนดเป้าหมายเป็นรังสี
• space คือ XrSpace ที่ปล่อยรังสี
• time คือ XrTime ที่ปล่อยรังสี

โครงสร้าง XrRaycastInfoANDROID จะอธิบายเรย์ที่จะแคสต์

• อาร์เรย์ XrRaycastInfoANDROID::trackers อาจมีอุปกรณ์ติดตามประเภทต่างๆ
• อาร์เรย์ XrRaycastInfoANDROID::trackers ต้องไม่มีเครื่องมือติดตามหลายรายการประเภทเดียวกัน มิฉะนั้นรันไทม์ต้องแสดงXR_ERROR_VALIDATION_FAILURE

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_raycast ก่อนใช้ XrRaycastInfoANDROID
• type ต้องเป็น XR_TYPE_RAYCAST_INFO_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• trackers ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของตัวแฮนเดิล trackerCountXrTrackableTrackerANDROID ที่ถูกต้อง
• space ต้องเป็นแฮนเดิล XrSpace ที่ถูกต้อง
• พารามิเตอร์ trackerCount ต้องมากกว่า 0
• ทั้ง space และองค์ประกอบของ trackers ต้องสร้างขึ้น กำหนด หรือดึงมาจาก XrSession เดียวกัน

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

typedef struct XrRaycastHitResultsANDROID {
    XrStructureType               type;
    void*                         next;
    uint32_t                      resultsCapacityInput;
    uint32_t                      resultsCountOutput;
    XrRaycastHitResultANDROID*    results;
} XrRaycastHitResultsANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• resultsCapacityInput คือความจุของอาร์เรย์ results หรือ 0 เพื่อบ่งบอกคําขอดึงข้อมูลความจุที่จําเป็น
• resultsCountOutput คือพอยน์เตอร์ไปยังจํานวน results ที่เขียน หรือพอยน์เตอร์ไปยังความจุที่จําเป็นในกรณีที่ resultsCapacityInput ไม่เพียงพอ
• results คือตัวชี้ไปยังอาร์เรย์ของโครงสร้าง XrRaycastHitResultANDROID สามารถเป็น NULL ได้หาก resultsCapacityInput เป็น 0
• ดูรายละเอียดเกี่ยวกับการดึงข้อมูลresultsขนาดที่ต้องการได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

XrRaycastHitResultsANDROID มีอาร์เรย์ของ Hit ของ Raycast

รันไทม์ต้องตั้งค่า resultsCountOutput ให้น้อยกว่าหรือเท่ากับ XrRaycastInfoANDROID::maxResults

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_raycast ก่อนใช้ XrRaycastHitResultsANDROID
• type ต้องเป็น XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• results ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของโครงสร้าง resultsCapacityInput XrRaycastHitResultANDROID
• พารามิเตอร์ resultsCapacityInput ต้องมากกว่า 0

โครงสร้าง XrRaycastHitResultANDROID ได้รับการกําหนดดังนี้

typedef struct XrRaycastHitResultANDROID {
    XrTrackableTypeANDROID    type;
    XrTrackableANDROID        trackable;
    XrPosef                   pose;
} XrRaycastHitResultANDROID;

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

• type คือ XrTrackableTypeANDROID ของสิ่งที่ติดตามได้ซึ่งเรย์แคสต์ตี
• trackable คือ XrTrackableANDROID ที่ Raycast ตี หรือ XR_NULL_TRACKABLE_ANDROID หาก type ที่ติดตามได้คือ XR_TRACKABLE_TYPE_DEPTH_ANDROID
• pose คือ XrPosef ที่ Raycast ตี

XrRaycastHitResultANDROID มีรายละเอียดของการตีกลับด้วย Raycast

XrRaycastHitResultANDROID::pose สำหรับการชนกับเครื่องบินต้องเป็นค่าที่ X และ Z คู่ขนานกับเครื่องบิน และแกน Y ตั้งฉากกับเครื่องบิน

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_raycast ก่อนใช้ XrRaycastHitResultANDROID
• type ต้องเป็นค่า XrTrackableTypeANDROID ที่ถูกต้อง

ตัวอย่างโค้ดสำหรับเรย์แคสติ้ง

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

XrSession session; // previously initialized
XrTime updateTime; // previously initialized
XrSpace appSpace;  // space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrPosef headPose;  // latest pose of the HMD.
XrTrackableTrackerANDROID planeTracker; // tracker for plane trackables.
XrTrackableTrackerANDROID depthTracker; // tracker for depth trackables.

// Perform a raycast against multiple trackers.
XrTrackableTrackerANDROID trackers[] = {
  &planeTracker,
  &depthTracker,
};
XrRaycastInfoANDROID rayInfo = {XR_TYPE_RAYCAST_INFO_ANDROID};
rayInfo.trackerCount = sizeof(trackers) / sizeof(XrTrackableTrackerANDROID);
rayInfo.trackers = trackers;
rayInfo.origin = headPose.position;
rayInfo.trajectory = CalculateForwardDirectionFromHeadPose(headPose);
rayInfo.space = appSpace;
rayInfo.time = updateTime;

uint32_t totalHitResults = 0;
constexpr uint32 NUM_DESIRED_RESULTS = 2;
XrRaycastHitResultANDROID hitResult[NUM_DESIRED_RESULTS];
XrRaycastHitResultsANDROID hitResults = {XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID};
hitResults.maxResults = NUM_DESIRED_RESULTS;
hitResults.resultsCapacityInput = NUM_DESIRED_RESULTS;
hitResults.results = hitResult;
XrResult result = xrRaycastANDROID(session, &rayInfo, &hitResults);

if (result == XR_SUCCESS && hitResults.resultsCountOutput >= 1) {
  // Hit results are returned in closest-to-farthest order in
  // hitResults.results[0] .. hitResults.results[hitResults.resultsCountOutput - 1]
}

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

เพิ่มรายการต่อไปนี้ในอนุกรม XrStructureType

• XR_TYPE_RAYCAST_INFO_ANDROID
• XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

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

• XrRaycastInfoANDROID
• XrRaycastHitResultANDROID
• XrRaycastHitResultsANDROID

ฟังก์ชันใหม่

• xrEnumerateRaycastSupportedTrackableTypesANDROID
• xrRaycastANDROID

ปัญหา

ประวัติเวอร์ชัน

• การแก้ไข 1, 2024-10-02 (Kenny Vercaemer)
  • คำอธิบายส่วนขยายเริ่มต้น

OpenXR™ และโลโก้ OpenXR เป็นเครื่องหมายการค้าของ The Khronos Group Inc. และจดทะเบียนเป็นเครื่องหมายการค้าในจีน สหภาพยุโรป ญี่ปุ่น และสหราชอาณาจักร