XR_ANDROID_geospatial

이름 문자열

XR_ANDROID_geospatial

확장 프로그램 유형

인스턴스 확장 프로그램

등록된 내선 번호

790

버전

1

승인 상태

비준되지 않음

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

XR_EXT_future

최종 수정일

2025-12-18

IP 상태

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

도움을 주신 분들

존 울먼, Google
벤 킹, Google
니하브 자인, Google
제러드 파인더, Google

개요

이 확장 프로그램은 Google의 Geospatial API에 대한 Geospatial 추적을 제공합니다. 이 API는 정확한 지리적 위치와 방향을 제공하며 애플리케이션이 지구를 기준으로 콘텐츠를 배치할 수 있도록 합니다. 이를 위해 모션 추적, GPS 및 기타 센서, Google의 시각적 위치 확인 시스템 (VPS)을 함께 사용합니다. VPS는 기기 카메라의 이미지를 스트리트 뷰 이미지와 비교하여 정확한 위치와 방향을 파악합니다. Geospatial API는 종종 1미터 미만의 위치 정확도 (GPS보다 훨씬 우수함)와 1도 미만의 방향 정확도를 제공합니다.

이 확장 프로그램의 API를 성공적으로 사용하려면 (확장 프로그램 지원 확인 제외) 애플리케이션이 XR_ANDROID_google_cloud_auth와 같은 메커니즘을 통해 사용자 인증 정보를 성공적으로 설정해야 합니다. 설정 및 오류 결과에 관한 자세한 내용은 인증 확장 프로그램 문서를 참고하세요.

권한

Android 애플리케이션은 이 확장 프로그램을 사용하려면 매니페스트에 android.permission.ACCESS_FINE_LOCATION 권한이 나열되어 있어야 합니다. android.permission.ACCESS_FINE_LOCATION 권한은 위험한 권한으로 간주됩니다. 애플리케이션은 런타임에 권한을 요청하여 다음 함수를 사용해야 합니다(must).

(보호 수준: 위험)

시스템 기능 검사

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

typedef struct XrSystemGeospatialPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGeospatial;
} XrSystemGeospatialPropertiesANDROID;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • supportsGeospatial는 XrBool32이며 현재 시스템이 지리 공간 기능을 지원하는지 여부를 나타냅니다.

애플리케이션은 xrGetSystemProperties를 호출할 때 XrSystemGeospatialPropertiesANDROID 구조를 XrSystemProperties에 연결하여 시스템이 지리 공간 기능을 지원하는지 검사할 수 있습니다.

런타임이 supportsGeospatial에 대해 XR_FALSE를 반환하는 경우 시스템은 지리 공간 기능을 지원하지 않으므로 xrCreateGeospatialTrackerANDROID에서 XR_ERROR_FEATURE_UNSUPPORTED를 반환해야 합니다(MUST). supportsGeospatial가 XR_FALSE인 경우 애플리케이션은 지리 공간 기능을 사용하지 않아야 합니다.

올바른 사용 (암시적)

Geospatial 추적기 핸들 만들기

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

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

XrResult xrCreateGeospatialTrackerANDROID(
    XrSession                                   session,
    const XrGeospatialTrackerCreateInfoANDROID* createInfo,
    XrGeospatialTrackerANDROID*                 geospatialTrackerOutput);

파라미터 설명

애플리케이션은 xrCreateGeospatialTrackerANDROID를 호출하여 XrGeospatialTrackerANDROID 핸들을 만들 수 있습니다. 반환된 XrGeospatialTrackerANDROID 핸들은 이후 API 호출에서 사용할 수 있습니다. 애플리케이션이 필요한 권한을 얻지 못한 경우 런타임은 XR_ERROR_PERMISSION_INSUFFICIENT를 반환해야 합니다(MUST). 특정 XrSession에 대해 한 번에 하나의 XrGeospatialTrackerANDROID만 존재할 수 있습니다. 애플리케이션은 이 함수를 다시 호출하기 전에 이전 XrGeospatialTrackerANDROID 객체가 소멸되었는지 확인해야 합니다(MUST). 그렇지 않으면 런타임은 XR_ERROR_LIMIT_REACHED를 반환해야 합니다(MUST). 추적기가 성공적으로 생성되면 처음에는 XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID 상태가 되며 애플리케이션은 추적기를 사용하기 전에 상태가 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID로 변경될 때까지 기다려야 합니다. XrEventDataGeospatialTrackerStateChangedANDROID를 참고하세요. 애플리케이션이 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 상태가 아닌 XrGeospatialTrackerANDROID를 이를 필요로 하는 함수에 전달하는 경우 런타임은 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID를 반환해야 합니다(must).

XrGeospatialTrackerANDROID 핸들은 결국 xrDestroyGeospatialTrackerANDROID 함수를 통해 해제되어야 합니다.

올바른 사용 (암시적)

반품 코드

성공

  • 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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrGeospatialTrackerCreateInfoANDROID;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.

올바른 사용 (암시적)

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

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

파라미터 설명

애플리케이션은 xrDestroyGeospatialTrackerANDROID 함수를 사용하여 Geospatial 추적기 및 기본 리소스를 해제할 수 있습니다.

올바른 사용 (암시적)

스레드 안전

  • geospatialTracker 및 모든 하위 핸들에 대한 액세스는 외부에서 동기화되어야 합니다(must).

반품 코드

성공

  • XR_SUCCESS

실패

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

지리 공간 추적기 상태

XrGeospatialTrackerStateANDROID 열거형은 다음과 같이 정의됩니다.

typedef enum XrGeospatialTrackerStateANDROID {
    XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID = 0,
    XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID = 1,
    XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID = 2,
    XR_GEOSPATIAL_TRACKER_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGeospatialTrackerStateANDROID;

XrGeospatialTrackerStateANDROID 열거형은 Geospatial 추적기의 다양한 상태를 식별합니다.

열거형에는 다음 값이 있습니다.

enum 설명

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Geospatial Tracker가 실행되고 있지 않습니다.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Geospatial 추적기가 실행 중이며 사용할 수 있습니다.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Geospatial Tracker를 초기화할 수 없으며 사용할 수 없습니다.

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

typedef struct XrEventDataGeospatialTrackerStateChangedANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrGeospatialTrackerANDROID         geospatialTracker;
    XrGeospatialTrackerStateANDROID    state;
    XrResult                           initializationResult;
    XrTime                             time;
} XrEventDataGeospatialTrackerStateChangedANDROID;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • geospatialTracker는 상태가 변경된 XrGeospatialTrackerANDROID입니다.
  • state는 새로운 XrGeospatialTrackerStateANDROID입니다.
  • initializationResult는 state가 XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID인 경우 오류 결과이고, 그렇지 않으면 XR_SUCCESS입니다.
  • time는 상태 변경이 발생한 XrTime입니다.

XrEventDataGeospatialTrackerStateChangedANDROID 구조는 Geospatial 추적기 상태가 변경될 때 전송됩니다. 애플리케이션에 유효한 XrGeospatialTrackerANDROID가 있는 경우 이 이벤트를 폴링해야 합니다(SHOULD). 추적기에 대해 수신된 첫 번째 이벤트에는 state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID가 있습니다. 런타임에서 결정한 시간이 지나면 상태가 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 또는 XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID로 변경되어야 합니다(must). 이 전환에는 임의의 시간이 소요됩니다. state가 XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID로 변경되면 이 추적기에 대해 수신된 마지막 이벤트여야 하며 initializationResult 필드에 오류 코드가 포함됩니다. 오류가 발생하기까지 몇 초 정도 걸릴 수 있습니다. 이 경우 애플리케이션은 추적기를 폐기해야 합니다(should). state가 XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID로 변경되면 이전에 생성된 모든 Geospatial Anchor는 영구적으로 추적을 중지해야 하며 애플리케이션에서 폐기해야 합니다. 상태는 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID와 XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID 사이에서 임의로 여러 번 전환될 수 있습니다.

올바른 사용 (암시적)

지리 공간적 포즈

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

typedef struct XrGeospatialPoseANDROID {
    XrQuaternionf    eastUpSouthOrientation;
    double           latitude;
    double           longitude;
    double           altitude;
} XrGeospatialPoseANDROID;

회원 설명

  • eastUpSouthOrientation는 +X=동쪽, +Y=위쪽, +Z=남쪽인 좌표계를 기준으로 방향을 정의하는 XrQuaternionf입니다.
  • latitude은 위도(도)이며 -90에서 +90 사이입니다.
  • longitude은 경도(도 단위, -180~+180)입니다.
  • altitude는 WGS84 타원체 위의 고도(미터)입니다.

XrGeospatialPoseANDROID 구조는 WGS84 타원체를 사용하여 지구를 기준으로 한 위치와 방향을 나타냅니다.

올바른 사용 (암시적)

  • XrGeospatialPoseANDROID를 사용하기 전에 XR_ANDROID_geospatial 확장 프로그램을 사용 설정해야 합니다.
  • latitude는 유효한 double 값이어야 합니다.
  • longitude는 유효한 double 값이어야 합니다.
  • altitude는 유효한 double 값이어야 합니다.

XrGeospatialPoseFlagBitsANDROID 열거형은 다음과 같이 정의됩니다.

// Flag bits for XrGeospatialPoseFlagsANDROID
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID = 0x00000001;
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID = 0x00000002;

XrGeospatialPoseFlagBitsANDROID 열거형은 Geospatial 포즈의 플래그를 지정합니다.

플래그 비트의 의미는 다음과 같습니다.

플래그 설명

  • XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID: 방향 멤버에 유효한 데이터가 포함되어 있음을 나타냅니다.
  • XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID: 위치 구성원에 유효한 데이터가 포함되어 있음을 나타냅니다.

XrGeospatialPoseFlagsANDROID 유형은 XrGeospatialPoseFlagBitsANDROID의 비트마스크입니다.

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

XrPosef를 지리 공간 포즈로 변환

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

XrResult xrLocateGeospatialPoseFromPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseFromPoseLocateInfoANDROID* locateInfo,
    XrGeospatialPoseResultANDROID*              geospatialPoseResult);

파라미터 설명

xrLocateGeospatialPoseFromPoseANDROID 함수는 XrGeospatialPoseFromPoseLocateInfoANDROID :: space의 포즈를 지리 공간적 포즈로 변환합니다. geospatialTracker의 상태가 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID가 아닌 경우 런타임은 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID를 반환해야 합니다(MUST). 함수가 XR_SUCCESS를 반환하면 geospatialPoseResult의 XrGeospatialPoseResultANDROID :: poseFlags 필드가 유효한 출력 필드를 결정합니다. XrGeospatialPoseResultANDROID :: poseFlags에 XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID가 설정되지 않은 경우 애플리케이션은 XrGeospatialPoseResultANDROID의 XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy 또는 XrGeospatialPoseResultANDROID :: verticalAccuracy 필드를 읽으면 안 됩니다. XrGeospatialPoseResultANDROID :: poseFlags에 XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID가 설정되지 않은 경우 애플리케이션은 XrGeospatialPoseANDROID :: eastUpSouthOrientation 또는 XrGeospatialPoseResultANDROID :: orientationYawAccuracy를 읽지 않아야 합니다(must). XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID가 설정되지 않은 경우 XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID도 설정되지 않아야 합니다.

정확도가 예상보다 낮으면 기기에서 VPS 위치 파악을 사용하지 않는다는 의미일 수 있습니다. 애플리케이션은 사용자에게 기기를 표지판과 건물에 가리키도록 안내하여 위치 파악을 개선할 수 있습니다.

올바른 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialPoseFromPoseLocateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrPosef            pose;
} XrGeospatialPoseFromPoseLocateInfoANDROID;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • space은 pose가 정의된 XrSpace입니다.
  • time는 pose를 평가할 XrTime입니다.
  • pose는 지리 공간적 포즈로 변환할 space의 XrPosef입니다.

올바른 사용 (암시적)

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

typedef struct XrGeospatialPoseResultANDROID {
    XrStructureType                 type;
    void*                           next;
    XrGeospatialPoseFlagsANDROID    poseFlags;
    XrGeospatialPoseANDROID         geospatialPose;
    double                          horizontalAccuracy;
    double                          verticalAccuracy;
    double                          orientationYawAccuracy;
} XrGeospatialPoseResultANDROID;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • poseFlags는 포즈 구성요소의 유효성을 나타내는 XrGeospatialPoseFlagsANDROID의 비트마스크입니다.
  • geospatialPose는 결과 XrGeospatialPoseANDROID입니다.
  • horizontalAccuracy는 Geospatial 포즈 위치의 예상 수평 정확도로, 지정된 위도와 경도를 중심으로 68% 신뢰 수준의 원 반경(미터)으로 정의됩니다.
  • verticalAccuracy는 지리 공간적 포즈 위치의 예상 수직 정확도로, 지정된 고도 주변의 68% 신뢰 수준의 거리(미터)로 정의됩니다. 즉, 실제 고도가 [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ] 범위에 있을 확률이 68% 입니다.
  • orientationYawAccuracy는 Geospatial 자세 방향의 예상 요 정확도로, 지정된 방향을 중심으로 68% 신뢰 수준의 반경(도)으로 정의됩니다.

올바른 사용 (암시적)

  • XR_ANDROID_geospatial 확장 프로그램은 XrGeospatialPoseResultANDROID를 사용하기 전에 사용 설정해야 합니다.
  • type은(는) XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID여야 합니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.

지리 공간적 포즈를 XrPosef로 변환

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

XrResult xrLocateGeospatialPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseLocateInfoANDROID*    locateInfo,
    XrSpaceLocation*                            location);

파라미터 설명

xrLocateGeospatialPoseANDROID 함수는 지리 공간적 포즈를 XrSpaceLocation으로 변환합니다. XrGeospatialTrackerANDROID가 실행되고 있지 않으면 런타임은 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID를 반환해야 합니다(must). 함수가 XR_SUCCESS를 반환하면 location의 XrSpaceLocation :: locationFlags 필드가 유효한 출력 필드를 결정합니다.

올바른 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialPoseLocateInfoANDROID {
    XrStructureType            type;
    const void*                next;
    XrSpace                    space;
    XrTime                     time;
    XrGeospatialPoseANDROID    geospatialPose;
} XrGeospatialPoseLocateInfoANDROID;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • space는 결과 포즈가 표시되는 XrSpace입니다.
  • time는 포즈를 배치할 XrTime입니다.
  • geospatialPose는 변환할 XrGeospatialPoseANDROID입니다.

올바른 사용 (암시적)

VPS 사용 가능 여부

XrVPSAvailabilityANDROID 열거형은 다음과 같이 정의됩니다.

typedef enum XrVPSAvailabilityANDROID {
    XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID = 1,
    XR_VPS_AVAILABILITY_AVAILABLE_ANDROID = 2,
    XR_VPSAVAILABILITY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrVPSAvailabilityANDROID;

XrVPSAvailabilityANDROID 열거형은 VPS 사용 가능 여부를 나타냅니다.

열거형에는 다음 값이 있습니다.

enum 설명

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

지정된 위치 근처에서는 VPS를 사용할 수 없습니다.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

지정된 위치 근처에서 VPS를 사용할 수 있습니다.

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

XrResult xrCheckVpsAvailabilityAsyncANDROID(
    XrSession                                   session,
    double                                      latitude,
    double                                      longitude,
    XrFutureEXT*                                future);

파라미터 설명

  • session은 확인에 사용할 XrSession입니다.
  • latitude는 위도(도)입니다.
  • longitude는 경도(도)입니다.
  • future는 비동기 작업의 결과를 보유할 XrFutureEXT에 대한 포인터입니다.

시각적 위치 확인 서비스 (VPS) 사용 가능 여부는 특정 위치에서 VPS를 사용하여 지리 공간 정확도를 개선할 수 있는지를 나타냅니다.

xrCheckVpsAvailabilityAsyncANDROID 함수는 특정 위치에서 VPS 사용 가능 여부를 비동기식으로 확인하기 시작합니다. 애플리케이션은 이 함수를 호출하기 위해 XrGeospatialTrackerANDROID가 필요하지 않으며, 이 작업의 결과를 사용하여 생성 여부를 결정할 수 있습니다. 애플리케이션이 필요한 권한을 얻지 못한 경우 런타임은 XR_ERROR_PERMISSION_INSUFFICIENT를 반환해야 합니다(MUST).

올바른 사용 (암시적)

  • xrCheckVpsAvailabilityAsyncANDROID를 호출하기 전에 XR_ANDROID_geospatial 확장 프로그램을 사용 설정해야 합니다.
  • session는 유효한 XrSession 핸들이어야 합니다.
  • latitude는 유효한 double 값이어야 합니다.
  • longitude는 유효한 double 값이어야 합니다.
  • future는 XrFutureEXT 값에 대한 포인터여야 합니다.

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCheckVpsAvailabilityCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrVPSAvailabilityCheckCompletionANDROID*    completion);

파라미터 설명

올바른 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrVPSAvailabilityCheckCompletionANDROID {
    XrStructureType             type;
    void*                       next;
    XrResult                    futureResult;
    XrVPSAvailabilityANDROID    availability;
} XrVPSAvailabilityCheckCompletionANDROID;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • futureResult는 확인 작업의 XrResult입니다. futureResult가 XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID인 경우 next 체인의 구조에서 실패에 관한 자세한 정보를 제공할 수 있습니다.
  • availability는 결과 XrVPSAvailabilityANDROID입니다. futureResult가 XR_SUCCESS가 아니면 애플리케이션은 이 필드를 읽지 않아야 합니다.

향후 반품 코드

futureResult 값:

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

올바른 사용 (암시적)

예

Geospatial Tracker 설정

PFN_xrCheckVpsAvailabilityAsyncANDROID xrCheckVpsAvailabilityAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCheckVpsAvailabilityCompleteANDROID xrCheckVpsAvailabilityCompleteANDROID;
PFN_xrCreateGeospatialTrackerANDROID xrCreateGeospatialTrackerANDROID;
XrInstance instance = XR_NULL_HANDLE;
XrSystemId systemId = XR_NULL_SYSTEM_ID;
XrSession session = XR_NULL_HANDLE;
double lat = 37.422, lng = -122.084;

// Check for support.
XrSystemGeospatialPropertiesANDROID geospatialSystemProperties{
    XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{XR_TYPE_SYSTEM_PROPERTIES,
                                    &geospatialSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!geospatialSystemProperties.supportsGeospatial) {
  return;
}

// Check VPS Availability.
XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCheckVpsAvailabilityAsyncANDROID(session, lat, lng, &future));

XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
pollInfo.future = future;
pollResult.state = XR_FUTURE_STATE_PENDING_EXT;
while (pollResult.state == XR_FUTURE_STATE_PENDING_EXT) {
  // Do in render loop/state loop.
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
}

XrVPSAvailabilityCheckCompletionANDROID vpsCompletion{
    XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID};
CHK_XR(xrCheckVpsAvailabilityCompleteANDROID(session, future, &vpsCompletion));
if (vpsCompletion.futureResult == XR_SUCCESS) {
  if (vpsCompletion.availability == XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID) {
    // Visual Positioning Service is not available. Accuracy of positions and
    // orientations from Geospatial APIs are expected to be lower at this location.
  } else {
    // Visual Positioning Service is available. Higher accuracy of position and
    // orientation is achievable at this location.
  }
}

// Create Geospatial Tracker.
XrGeospatialTrackerCreateInfoANDROID createInfo{
    XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID};
XrGeospatialTrackerANDROID geospatialTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateGeospatialTrackerANDROID(session, &createInfo, &geospatialTracker));

// In application main event loop:
while (true) {
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  if (xrPollEvent(instance, &event) != XR_SUCCESS) {
    continue;
  }
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID:
      const XrEventDataGeospatialTrackerStateChangedANDROID& eventData =
          *reinterpret_cast<XrEventDataGeospatialTrackerStateChangedANDROID*>(&event);
      switch (eventData.state) {
        case XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID:
          // Destroy existing anchors, if any.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID:
          // Start adding content.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID:
          // Handle eventData.initializationResult error result.
          break;
      }
  }
}

Geospatial Pose API 호출

PFN_xrLocateGeospatialPoseFromPoseANDROID xrLocateGeospatialPoseFromPoseANDROID;
PFN_xrLocateGeospatialPoseANDROID xrLocateGeospatialPoseANDROID;

XrGeospatialTrackerANDROID geospatialTracker;

// Get pose from view space.
XrSpace viewSpace;
XrPosef identityPose = {{0,0,0,1},{0,0,0}};
XrGeospatialPoseFromPoseLocateInfoANDROID poseGetInfo{
    XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID};
XrGeospatialPoseResultANDROID poseResult{
    XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID};
poseGetInfo.space = viewSpace;
poseGetInfo.pose = identityPose;
poseGetInfo.time = 0;  // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseFromPoseANDROID(geospatialTracker, &poseGetInfo, &poseResult));
if ((poseResult.poseFlags & XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID) &&
    (poseResult.poseFlags & XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID)) {
  // poseResult.geospatialPose is valid.
}

// Convert Geospatial pose to an XrSpaceLocation.
XrGeospatialPoseLocateInfoANDROID poseLocateInfo{
    XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID};
XrSpaceLocation location{XR_TYPE_SPACE_LOCATION};
poseLocateInfo.space = viewSpace;
poseLocateInfo.geospatialPose = poseResult.geospatialPose;
poseLocateInfo.time = 0; // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseANDROID(geospatialTracker, &poseLocateInfo, &location));
if ((location.locationFlags & XR_SPACE_LOCATION_ORIENTATION_VALID_BIT) &&
    (location.locationFlags & XR_SPACE_LOCATION_POSITION_VALID_BIT)) {
  // location.pose is valid.
}

새 객체 유형

새 명령어

새로운 구조

새 enum

새 비트마스크

새 enum 상수

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • XrObjectType 확장:

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • XrResult 확장:

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • XrStructureType 확장:

    • XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID
    • XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID

문제

버전 기록

  • 버전 1, 2025-12-18 (벤 킹)

    • 초기 확장 프로그램 설명입니다.