Tiện ích OpenXR XR_ANDROID_raycast

Chuỗi tên

XR_ANDROID_raycast

Loại phần mở rộng

Tiện ích thực thể

Số điện thoại mở rộng đã đăng ký

464

Bản sửa đổi

1

Phần mở rộng và phần phụ thuộc phiên bản

XR_ANDROID_trackables

Ngày sửa đổi gần đây nhất

2024-10-02

Trạng thái IP

Không có thông báo xác nhận quyền sở hữu đối với tài sản trí tuệ nào.

Cộng tác viên

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Tổng quan

Tiện ích này cho phép ứng dụng thực hiện các phép chiếu tia đối với các đối tượng có thể theo dõi trong môi trường. Raycasts có thể hữu ích để phát hiện các đối tượng trong môi trường mà tia sáng sẽ giao nhau. Ví dụ:

  • Để xác định vị trí một đối tượng nổi sẽ rơi khi bị thả, hãy sử dụng tính năng truyền tia dọc.
  • Để xác định vị trí người dùng đang nhìn, hãy sử dụng tính năng truyền tia về phía trước.

Truy vấn các tính năng được hỗ trợ của raycast

Hàm xrEnumerateRaycastSupportedTrackableTypesANDROID được xác định như sau:

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

Nội dung mô tả tham số

  • instance là XrInstance mà từ đó systemId được truy xuất.
  • systemId là XrSystemId có các loại có thể theo dõi được hỗ trợ cho tính năng chiếu tia đang được liệt kê.
  • trackableTypeCapacityInput là dung lượng của trackableTypes hoặc 0 để truy xuất dung lượng bắt buộc.
  • trackableTypeCountOutput là con trỏ đến số lượng mảng hoặc con trỏ đến dung lượng cần thiết trong trường hợp trackableTypeCapacityInput không đủ.
    • trackableTypes là con trỏ đến một mảng XrTrackableTypeANDROID, nhưng có thể là NULL nếu trackableTypeCapacityInput là 0.
  • Hãy xem phần Tham số kích thước bộ đệm để biết nội dung mô tả chi tiết về việc truy xuất kích thước trackableTypes bắt buộc.

xrEnumerateRaycastSupportedTrackableTypesANDROID liệt kê các loại có thể theo dõi hỗ trợ tính năng truyền tia theo phiên hiện tại.

Cách sử dụng hợp lệ (ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

  • 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

Thực hiện raycast

Hàm xrRaycastANDROID được xác định là:

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

Nội dung mô tả tham số

Ứng dụng có thể thực hiện các phép chiếu tia bằng cách gọi xrRaycastANDROID.

Cách sử dụng hợp lệ (ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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

Cấu trúc XrRaycastInfoANDROID được xác định là: 

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;

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • maxResults là số lượng kết quả tối đa uint32_t cần trả về.
  • trackerCount là số uint32_t của mảng trackers.
  • trackers là mảng XrTrackableTrackerANDROID mà tia được truyền nên được kiểm thử.
  • origin là XrVector3f mà tia sáng được chiếu từ đó.
  • trajectory là XrVector3f mà tia sáng nhắm đến.
  • space là XrSpace mà tia sáng được chiếu vào.
  • time là XrTime mà tia sáng được chiếu vào.

Cấu trúc XrRaycastInfoANDROID mô tả tia sẽ chiếu.

Cách sử dụng hợp lệ (ngầm ẩn)

Cấu trúc XrRaycastHitResultsANDROID được xác định là: 

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • resultsCapacityInput là dung lượng của mảng results hoặc 0 để cho biết yêu cầu truy xuất dung lượng cần thiết.
  • resultsCountOutput là con trỏ đến số lượng results đã ghi hoặc con trỏ đến dung lượng cần thiết trong trường hợp resultsCapacityInput không đủ.
  • results là con trỏ trỏ đến một mảng cấu trúc XrRaycastHitResultANDROID. Giá trị này có thể là NULL nếu resultsCapacityInput là 0.
  • Hãy xem phần Tham số kích thước bộ nhớ đệm để biết nội dung mô tả chi tiết về việc truy xuất kích thước results bắt buộc.

XrRaycastHitResultsANDROID chứa mảng các lần nhấn của một raycast.

Môi trường thời gian chạy phải đặt resultsCountOutput nhỏ hơn hoặc bằng XrRaycastInfoANDROID::maxResults.

Cách sử dụng hợp lệ (ngầm ẩn)

Cấu trúc XrRaycastHitResultANDROID được xác định là: 

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

Nội dung mô tả thành viên

  • type là XrTrackableTypeANDROID của đối tượng có thể theo dõi mà tia sáng trúng.
  • trackable là XrTrackableANDROID mà tia sáng đã chạm vào hoặc XR_NULL_TRACKABLE_ANDROID nếu type có thể theo dõi là XR_TRACKABLE_TYPE_DEPTH_ANDROID.
  • pose là XrPosef mà raycast đã đánh trúng.

XrRaycastHitResultANDROID chứa thông tin chi tiết về một lần nhấn raycast.

XrRaycastHitResultANDROID::pose cho một lần nhấn vào mặt phẳng phải sao cho X và Z song song với mặt phẳng và trục Y vuông góc với mặt phẳng.

Loại lượt truy cập có thể theo dõi

Nội dung mô tả

XR_TRACKABLE_TYPE_PLANE_ANDROID

Đánh vào các bề mặt ngang và/hoặc dọc để xác định độ sâu và hướng chính xác của một điểm.

XR_TRACKABLE_TYPE_DEPTH_ANDROID

Sử dụng thông tin độ sâu từ toàn bộ cảnh để xác định độ sâu và hướng chính xác của một điểm.

Cách sử dụng hợp lệ (ngầm ẩn)

Mã ví dụ cho tính năng chiếu tia

Mã ví dụ sau đây minh hoạ cách thực hiện các phép chiếu tia.

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]
}

Hằng số enum mới

Bổ sung enum XrStructureType:

  • XR_TYPE_RAYCAST_INFO_ANDROID
  • XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

Cấu trúc mới

Hàm mới

Vấn đề

Nhật ký phiên bản

  • Bản sửa đổi 1, ngày 2 tháng 10 năm 2024 (Kenny Vercaemer)
    • Nội dung mô tả ban đầu của tiện ích

OpenXR™ và biểu trưng OpenXR là các nhãn hiệu thuộc sở hữu của The Khronos Group Inc. và được đăng ký dưới dạng nhãn hiệu ở Trung Quốc, Liên minh Châu Âu, Nhật Bản và Vương quốc Anh.