XR_ANDROID_raycast OpenXR 확장 프로그램

이름 문자열

XR_ANDROID_raycast

확장 프로그램 유형

인스턴스 연장

등록된 부속 번호

464

버전

1

확장 프로그램 및 버전 종속 항목

XR_ANDROID_trackables

최종 수정일

2024-10-02

IP 상태

알려진 IP 소유권 주장이 없습니다.

도움을 주신 분들

스펜서 퀸, Google

니하브 자인, Google

존 퍼시, Google

재러드 파인더, Google

레바나 첸, Google

케니 베르카머, Google

개요

이 확장 프로그램을 사용하면 애플리케이션이 환경에서 추적 가능한 항목에 대해 레이캐스트를 실행할 수 있습니다. 레이캐스트는 광선이 교차하는 환경의 객체를 감지하는 데 유용할 수 있습니다. 예를 들면 다음과 같습니다.

  • 수직 레이캐스트를 사용하여 물체가 떨어질 때 떨어질 위치를 확인합니다.
  • 전면 방향 레이캐스트를 사용하여 사용자가 보고 있는 위치를 확인합니다.

지원되는 레이캐스트 기능 쿼리

xrEnumerateRaycastSupportedTrackableTypesANDROID 함수는 다음과 같이 정의됩니다.

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

매개변수 설명

  • instance는 systemId이 가져온 XrInstance입니다.
  • systemId는 레이캐스팅에 지원되는 추적 가능한 유형이 열거되는 XrSystemId입니다.
  • trackableTypeCapacityInput는 trackableTypes의 용량이거나 필요한 용량을 검색하기 위한 0입니다.
  • trackableTypeCountOutput는 배열의 개수에 대한 포인터이거나 trackableTypeCapacityInput가 충분하지 않은 경우 필요한 용량에 대한 포인터입니다.
    • trackableTypes는 XrTrackableTypeANDROID 배열에 대한 포인터이지만 trackableTypeCapacityInput이 0인 경우 NULL일 수 있습니다.
  • 필요한 trackableTypes 크기를 검색하는 방법에 관한 자세한 설명은 버퍼 크기 매개변수 섹션을 참고하세요.

xrEnumerateRaycastSupportedTrackableTypesANDROID는 현재 세션의 레이캐스트를 지원하는 추적 가능한 유형을 열거합니다.

유효한 사용 (암시적)

반품 코드

성공

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

매개변수 설명

애플리케이션은 xrRaycastANDROID를 호출하여 레이캐스트를 실행할 수 있습니다.

유효한 사용 (암시적)

반품 코드

성공

  • 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는 trackers 배열의 uint32_t 개수입니다.
  • trackers는 캐스트된 광선이 테스트되어야 하는 XrTrackableTrackerANDROID 배열입니다.
  • origin는 광선이 투사되는 XrVector3f입니다.
  • trajectory는 광선이 타겟팅되는 XrVector3f입니다.
  • space은 광선이 투사되는 XrSpace입니다.
  • time은 광선이 투사되는 XrTime입니다.

XrRaycastInfoANDROID 구조는 투사할 광선을 설명합니다.

  • XrRaycastInfoANDROID::trackers 배열에는 다양한 유형의 추적기가 포함될 수 있습니다.
  • XrRaycastInfoANDROID::trackers 배열은 동일한 유형의 추적기를 여러 개 포함할 수 없습니다. 그러지 않으면 런타임은 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다.

유효한 사용 (암시적)

  • XrRaycastInfoANDROID를 사용하기 전에 XR_ANDROID_raycast 확장 프로그램을 사용 설정해야 합니다.
  • type는 XR_TYPE_RAYCAST_INFO_ANDROID여야 합니다.
  • next는 NULL이거나 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.
  • trackers는 유효한 trackerCount XrTrackableTrackerANDROID 핸들의 배열에 대한 포인터여야 합니다.
  • 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 구조 배열에 대한 포인터입니다. resultsCapacityInput이 0인 경우 NULL일 수 있습니다.
  • 필요한 results 크기를 검색하는 방법에 관한 자세한 설명은 버퍼 크기 매개변수 섹션을 참고하세요.

XrRaycastHitResultsANDROID에는 레이캐스트의 히트 배열이 포함됩니다.

런타임은 resultsCountOutput를 XrRaycastInfoANDROID::maxResults 이하로 설정해야 합니다.

유효한 사용 (암시적)

XrRaycastHitResultANDROID 구조는 다음과 같이 정의됩니다. 

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

회원 설명

  • type는 레이캐스트가 맞은 추적 가능한 항목의 XrTrackableTypeANDROID입니다.
  • trackable는 레이캐스트가 충돌한 XrTrackableANDROID이거나 추적 가능한 type가 XR_TRACKABLE_TYPE_DEPTH_ANDROID인 경우 XR_NULL_TRACKABLE_ANDROID입니다.
  • pose는 레이캐스트가 맞은 XrPosef입니다.

XrRaycastHitResultANDROID에는 레이캐스트 히트의 세부정보가 포함되어 있습니다.

평면 충돌의 XrRaycastHitResultANDROID::pose는 X와 Z가 평면에 평행하고 Y축이 평면에 수직이 되도록 해야 합니다.

추적 가능한 조회 유형

설명

XR_TRACKABLE_TYPE_PLANE_ANDROID

가로 또는 세로 표면을 히트하여 점의 정확한 깊이와 방향을 결정합니다.

XR_TRACKABLE_TYPE_DEPTH_ANDROID

전체 장면의 깊이 정보를 사용하여 지점의 올바른 깊이와 방향을 결정합니다.

유효한 사용 (암시적)

레이캐스팅 코드 예

다음 예시 코드는 레이캐스트를 실행하는 방법을 보여줍니다.

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

새로운 구조

새로운 함수

문제

버전 기록

  • 버전 1, 2024년 10월 2일 (케니 베르카이머)
    • 초기 확장 프로그램 설명