XR_ANDROID_geospatial_anchor

이름 문자열

XR_ANDROID_geospatial_anchor

확장 프로그램 유형

인스턴스 확장

등록된 내선 번호

798

버전

1

비준 상태

비준되지 않음

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

XR_ANDROID_geospatial

XR_EXT_future

XR_EXT_spatial_entity

XR_EXT_spatial_anchor

최종 수정일

2025-10-30

IP 상태

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

도움을 주신 분들

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

개요

이 확장 프로그램은 기본 지리 공간 확장 프로그램을 기반으로 하는 지리 공간 앵커와 표면 앵커를 제공합니다. 지리 공간 앵커는 지정된 위도, 경도, 고도에서 지구를 기준으로 공간에 배치된 앵커입니다. 표면 앵커는 시각적 위치 서비스에서 인식하는 표면을 기준으로 지정된 위도, 경도, 고도에 배치되는 지구 상대 앵커입니다. 지구에 대한 런타임의 위치 정확도가 향상되면 앵커의 포즈가 그에 따라 조정됩니다.

지리 공간 앵커의 시스템 기능

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

typedef struct XrSystemGeospatialAnchorPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSurfaceAnchorCount;
} XrSystemGeospatialAnchorPropertiesANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • nextNULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다. 이러한 구조는 핵심 OpenXR이나 이 확장 프로그램에 정의되어 있지 않습니다.
  • maxSurfaceAnchorCount는 생성할 수 있는 최대 표면 고정점을 나타내는 uint32_t입니다.

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

XrSystemGeospatialPropertiesANDROID :: supportsGeospatialXR_TRUE인 경우 maxSurfaceAnchorCount은 런타임이 지원하는 최대 표면 앵커 수를 나타냅니다. 이 경우 한도는 0보다 커야 합니다.

XrSystemGeospatialPropertiesANDROID :: supportsGeospatialXR_TRUE이 아닌 경우 maxSurfaceAnchorCount은 0이어야 합니다.

유효한 사용 (암시적)

앵커의 평면 추적

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

typedef struct XrGeospatialTrackerAnchorTrackingInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrBool32           shouldTrackPlanes;
} XrGeospatialTrackerAnchorTrackingInfoANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • nextNULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다.
  • shouldTrackPlanes는 지리공간 추적기가 평면을 추적하여 표면에 고정된 앵커의 위치를 개선하는지 여부를 나타내는 XrBool32입니다.

평면 추적을 사용 설정하여 표면에 고정된 앵커의 위치를 개선할 수 있습니다.

애플리케이션이 평면 추적을 사용 설정하여 표면 앵커 포즈를 개선하려는 경우 xrCreateGeospatialTrackerANDROID를 호출할 때 XrGeospatialTrackerAnchorTrackingInfoANDROID 구조체를 XrGeospatialTrackerCreateInfoANDROID에 연결할 수 있습니다 .

유효한 사용 (암시적)

지리정보 앵커

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

XrResult xrCreateGeospatialAnchorANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrGeospatialAnchorCreateInfoANDROID*  createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId);

매개변수 설명

  • spatialContext은 앵커를 만들 XrSpatialContextEXT입니다. 컨텍스트는 XR_SPATIAL_CAPABILITY_ANCHOR_EXT로 구성되어야 합니다. 그렇지 않으면 런타임이 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다.
  • createInfo는 앵커 생성 매개변수가 포함된 XrGeospatialAnchorCreateInfoANDROID에 대한 포인터입니다.
  • anchorEntityId는 앵커 엔티티 ID가 반환되는 XrSpatialEntityIdEXT에 대한 포인터입니다.

XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker에 지정된 XrGeospatialTrackerANDROIDXR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 상태가 아니면 런타임은 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID을 반환해야 합니다 .

유효한 사용 (암시적)

반환 코드

성공

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

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

typedef struct XrGeospatialAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrGeospatialPoseANDROID       geospatialPose;
} XrGeospatialAnchorCreateInfoANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • nextNULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다.
  • geospatialTracker는 앵커를 만드는 데 사용할 XrGeospatialTrackerANDROID입니다.
  • geospatialPose는 앵커의 위치와 방향을 정의하는 XrGeospatialPoseANDROID에 대한 포인터입니다.

유효한 사용 (암시적)

표면 앵커

표면 앵커는 지형이나 지붕과 같은 표면을 기준으로 배치되는 앵커입니다.

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

typedef enum XrSurfaceAnchorTypeANDROID {
    XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID = 1,
    XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID = 2,
    XR_SURFACE_ANCHOR_TYPE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSurfaceAnchorTypeANDROID;

XrSurfaceAnchorTypeANDROID 열거형은 앵커가 상대적인 표면 유형을 지정합니다.

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

열거형 설명

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

지면을 기준으로 배치된 앵커의 유형입니다.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

건물이 없는 경우 옥상 또는 지면을 기준으로 배치된 앵커의 유형입니다.

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

XrResult xrCreateSurfaceAnchorAsyncANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSurfaceAnchorCreateInfoANDROID*     createInfo,
    XrFutureEXT*                                future);

매개변수 설명

  • spatialContext은 앵커를 만들 XrSpatialContextEXT입니다.
  • createInfo는 앵커 생성 매개변수가 포함된 XrSurfaceAnchorCreateInfoANDROID에 대한 포인터입니다.
  • future는 비동기 작업의 결과를 보유할 XrFutureEXT에 대한 포인터입니다.

xrCreateSurfaceAnchorAsyncANDROID 함수는 표면 앵커를 만드는 비동기 작업을 시작합니다. 표준 지리 공간 앵커와 달리 런타임은 지형 데이터를 가져와 올바른 고도를 결정할 수 있습니다. 런타임은 애플리케이션이 한 번에 XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount 표면 앵커를 두 개 이상 만들려고 시도하는 경우 XR_ERROR_LIMIT_REACHED를 반환해야 합니다. XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker에 지정된 XrGeospatialTrackerANDROIDXR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 상태가 아니면 런타임은 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID을 반환해야 합니다 . 지정된 위치에 표면 데이터가 없으면 XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID 결과와 함께 비동기적으로 작업이 실패할 수 있습니다. 런타임은 spatialContext에 대해 XR_SPATIAL_CAPABILITY_ANCHOR_EXT가 구성되지 않은 경우 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다 .

유효한 사용 (암시적)

반환 코드

성공

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

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

typedef struct XrSurfaceAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrSurfaceAnchorTypeANDROID    surfaceAnchorType;
    XrQuaternionf                 eastUpSouthOrientation;
    double                        latitude;
    double                        longitude;
    double                        altitudeRelativeToSurface;
} XrSurfaceAnchorCreateInfoANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • nextNULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다.
  • geospatialTracker은 사용할 XrGeospatialTrackerANDROID입니다.
  • surfaceAnchorType은 앵커의 XrSurfaceAnchorTypeANDROID입니다.
  • eastUpSouthOrientation는 +X=East, +Y=Up, +Z=South인 좌표계에 대한 방향입니다.
  • latitude은 위도(단위: 도, 범위: -89.9~+89.9)입니다.
  • longitude은 경도(도 단위, -180~+180)입니다.
  • altitudeRelativeToSurfacesurfaceAnchorType로 지정된 표면을 기준으로 한 고도(미터)입니다 .

유효한 사용 (암시적)

  • XrSurfaceAnchorCreateInfoANDROID를 사용하기 전에 XR_ANDROID_geospatial_anchor 확장 프로그램을 사용 설정해야 합니다.
  • typeXR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID이어야 합니다.
  • nextNULL이거나 구조 체인의 다음 구조를 가리키는 유효한 포인터여야 합니다.
  • geospatialTracker은 유효한 XrGeospatialTrackerANDROID 핸들이어야 합니다.
  • surfaceAnchorType은 유효한 XrSurfaceAnchorTypeANDROID 값이어야 합니다.
  • latitude은 유효한 double이어야 합니다.
  • longitude은 유효한 double이어야 합니다.
  • altitudeRelativeToSurface은 유효한 double이어야 합니다.

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

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     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_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

XrSurfaceAnchorCreateCompletionANDROID 구조체는 비동기 표면 앵커 생성 결과를 보유합니다.

typedef struct XrSurfaceAnchorCreateCompletionANDROID {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSurfaceAnchorCreateCompletionANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • nextNULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다.
  • futureResult는 생성 작업의 XrResult입니다. futureResultXR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID이면 next 체인의 구조에서 실패에 관한 자세한 정보를 제공할 수 있습니다.
  • anchorEntityId는 생성된 앵커의 XrSpatialEntityIdEXT이거나 futureResultXR_SUCCESS이 아닌 경우 XR_NULL_SPATIAL_ENTITY_ID_EXT입니다 .

향후 반품 코드

futureResult 값:

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

유효한 사용 (암시적)

  • XR_ANDROID_geospatial_anchor 확장 프로그램은 XrSurfaceAnchorCreateCompletionANDROID를 사용하기 전에 사용 설정해야 합니다.
  • typeXR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID이어야 합니다.
  • nextNULL이거나 구조 체인의 다음 구조를 가리키는 유효한 포인터여야 합니다.
  • futureResult은 유효한 XrResult 값이어야 합니다.

지형 앵커 만들기

PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
PFN_xrCreateSurfaceAnchorAsyncANDROID xrCreateSurfaceAnchorAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCreateSurfaceAnchorCompleteANDROID xrCreateSurfaceAnchorCompleteANDROID;
XrInstance instance;
XrSession session;
XrGeospatialTrackerANDROID geospatialTracker;

// Create a spatial context
XrSpatialContextEXT spatialContext{};
{
  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  XrSpatialCapabilityConfigurationAnchorEXT
       anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  // ... wait until future is ready ...

  XrCreateSpatialContextCompletionEXT contextCompletion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &contextCompletion));
  if (contextCompletion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = contextCompletion.spatialContext;
}

XrSurfaceAnchorCreateInfoANDROID anchorCreateInfo{
    XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID};
anchorCreateInfo.surfaceAnchorType = XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID;
anchorCreateInfo.eastUpSouthOrientation = {0, 0, 0, 1};
anchorCreateInfo.latitude = 37.7749;
anchorCreateInfo.longitude = -122.4194;
anchorCreateInfo.altitudeRelativeToSurface = 0;
anchorCreateInfo.geospatialTracker = geospatialTracker;
XrFutureEXT anchorFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSurfaceAnchorAsyncANDROID(spatialContext, &anchorCreateInfo, &anchorFuture));

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

XrSurfaceAnchorCreateCompletionANDROID anchorCompletion{
    XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID};
CHK_XR(xrCreateSurfaceAnchorCompleteANDROID(spatialContext, anchorFuture, &anchorCompletion));
if (anchorCompletion.futureResult == XR_SUCCESS) {
  // Use completion.anchorEntityId.
  XrSpatialEntityIdEXT anchorId = anchorCompletion.anchorEntityId;

  // Query in UpdateSnapshot.
}

새 명령어

새 구조

새 열거형

새 열거형 상수

  • XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_geospatial_anchor_SPEC_VERSION
  • XrResult 확장 :

    • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
  • XrStructureType 확장 :

    • XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID

문제

버전 기록

  • 버전 1, 2025년 10월 30일 (벤 킹)

    • 초안