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

개요

이 확장 프로그램은 기본 Geospatial 확장 프로그램을 기반으로 하는 Geospatial Anchor 및 Surface Anchor를 제공합니다. 지리 공간 앵커는 특정 위도, 경도, 고도에서 지구를 기준으로 공간에 배치되는 앵커입니다. 표면 앵커는 시각적 위치 확인 서비스에서 알려진 표면을 기준으로 특정 위도, 경도, 고도에 배치되는 지구 기준 앵커입니다. 지구에 대한 런타임의 위치 정확도가 개선됨에 따라 앵커의 포즈가 그에 맞게 조정됩니다.

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

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

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

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • maxSurfaceAnchorCount는 생성할 수 있는 최대 표면 앵커 수를 나타내는 uint32_t입니다.

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

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

XrSystemGeospatialPropertiesANDROID :: supportsGeospatial가 XR_TRUE가 아닌 경우 maxSurfaceAnchorCount는 0이어야 합니다(MUST).

올바른 사용 (암시적)

앵커의 평면 추적

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

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

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • 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에 지정된 XrGeospatialTrackerANDROID가 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 상태가 아닌 경우 런타임은 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID를 반환해야 합니다(must).

올바른 사용 (암시적)

반품 코드

성공

  • 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_POSE_INVALID
  • 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입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • 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 열거형은 앵커가 상대적인 표면 유형을 지정합니다.

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

enum 설명

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를 반환해야 합니다(must). XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker에 지정된 XrGeospatialTrackerANDROID가 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 상태가 아닌 경우 런타임은 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID를 반환해야 합니다(must). 지정된 위치에 표면 데이터가 없는 경우 작업이 결과 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_POSE_INVALID
  • 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입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • geospatialTracker은 사용할 XrGeospatialTrackerANDROID입니다.
  • surfaceAnchorType은 앵커의 XrSurfaceAnchorTypeANDROID입니다.
  • eastUpSouthOrientation는 +X=동쪽, +Y=위쪽, +Z=남쪽인 좌표계에 대한 방향입니다.
  • latitude은 위도(도)이며 -89.9에서 +89.9 사이입니다.
  • longitude은 경도(도 단위, -180~+180)입니다.
  • altitudeRelativeToSurface는 surfaceAnchorType로 지정된 표면을 기준으로 한 고도(미터)입니다.

올바른 사용 (암시적)

  • XrSurfaceAnchorCreateInfoANDROID를 사용하기 전에 XR_ANDROID_geospatial_anchor 확장 프로그램을 사용 설정해야 합니다.
  • type은(는) XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID여야 합니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.
  • 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입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • futureResult는 생성 작업의 XrResult입니다. futureResult가 XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID인 경우 next 체인의 구조에서 실패에 관한 자세한 정보를 제공할 수 있습니다.
  • anchorEntityId는 생성된 앵커의 XrSpatialEntityIdEXT입니다. futureResult가 XR_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

올바른 사용 (암시적)

  • XrSurfaceAnchorCreateCompletionANDROID를 사용하기 전에 XR_ANDROID_geospatial_anchor 확장 프로그램을 사용 설정해야 합니다(must).
  • type은(는) XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID여야 합니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.
  • 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.
}

새 명령어

새로운 구조

새 enum

새 enum 상수

  • 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 (벤 킹)

    • 초안