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).
올바른 사용 (암시적)
- XrSystemGeospatialAnchorPropertiesANDROID를 사용하기 전에
XR_ANDROID_geospatial_anchor확장 프로그램을 사용 설정해야 합니다. -
type은(는)XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID여야 합니다. -
next는NULL또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.
앵커의 평면 추적
XrGeospatialTrackerAnchorTrackingInfoANDROID 구조는 다음과 같이 정의됩니다.
typedef struct XrGeospatialTrackerAnchorTrackingInfoANDROID {
XrStructureType type;
const void* next;
XrBool32 shouldTrackPlanes;
} XrGeospatialTrackerAnchorTrackingInfoANDROID;
회원 설명
type는 이 구조의 XrStructureType입니다.next는NULL또는 구조 체인의 다음 구조에 대한 포인터입니다.shouldTrackPlanes는 위치정보 추적기가 평면을 추적하여 표면 고정 앵커의 위치를 개선할지 여부를 나타내는XrBool32입니다.
평면 추적을 사용 설정하면 표면 고정 앵커의 위치를 개선할 수 있습니다.
애플리케이션에서 평면 추적을 사용 설정하여 표면 앵커 포즈를 개선하려는 경우 xrCreateGeospatialTrackerANDROID를 호출할 때 XrGeospatialTrackerAnchorTrackingInfoANDROID 구조를 XrGeospatialTrackerCreateInfoANDROID에 연결할 수 있습니다.
올바른 사용 (암시적)
- XrGeospatialTrackerAnchorTrackingInfoANDROID를 사용하기 전에
XR_ANDROID_geospatial_anchor확장 프로그램을 사용 설정해야 합니다. -
type은(는)XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID여야 합니다. -
next는NULL또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.
지리 공간 앵커
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).
올바른 사용 (암시적)
- xrCreateGeospatialAnchorANDROID를 호출하기 전에
XR_ANDROID_geospatial_anchor확장 프로그램을 사용 설정해야 합니다. -
spatialContext는 유효한 XrSpatialContextEXT 핸들이어야 합니다. -
createInfo는 유효한 XrGeospatialAnchorCreateInfoANDROID 구조에 대한 포인터여야 합니다. -
anchorEntityId는XrSpatialEntityIdEXT값에 대한 포인터여야 합니다.
반품 코드
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROIDXR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROIDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_POSE_INVALIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_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에 대한 포인터입니다.
올바른 사용 (암시적)
- XrGeospatialAnchorCreateInfoANDROID를 사용하기 전에
XR_ANDROID_geospatial_anchor확장 프로그램을 사용 설정해야 합니다. -
type은(는)XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID여야 합니다. -
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를 반환해야 합니다.
올바른 사용 (암시적)
- xrCreateSurfaceAnchorAsyncANDROID를 호출하기 전에
XR_ANDROID_geospatial_anchor확장 프로그램을 사용 설정해야 합니다. -
spatialContext는 유효한 XrSpatialContextEXT 핸들이어야 합니다. -
createInfo: 유효한 XrSurfaceAnchorCreateInfoANDROID 구조체에 대한 포인터여야 합니다. -
future는XrFutureEXT값에 대한 포인터여야 합니다.
반품 코드
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROIDXR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROIDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_POSE_INVALIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_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);
파라미터 설명
spatialContext는 생성에 사용되는 XrSpatialContextEXT입니다.future는 xrCreateSurfaceAnchorAsyncANDROID에서 반환하는XrFutureEXT입니다.completion는 결과를 수신하는 XrSurfaceAnchorCreateCompletionANDROID에 대한 포인터입니다.
올바른 사용 (암시적)
- xrCreateSurfaceAnchorCompleteANDROID를 호출하기 전에
XR_ANDROID_geospatial_anchor확장 프로그램을 사용 설정해야 합니다. -
spatialContext는 유효한 XrSpatialContextEXT 핸들이어야 합니다. -
completion는 XrSurfaceAnchorCreateCompletionANDROID 구조에 대한 포인터여야 합니다(must).
반품 코드
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHEDXR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROIDXR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROIDXR_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.
}
새 명령어
- xrCreateGeospatialAnchorANDROID
- xrCreateSurfaceAnchorAsyncANDROID
- xrCreateSurfaceAnchorCompleteANDROID
새로운 구조
- XrGeospatialAnchorCreateInfoANDROID
- XrSurfaceAnchorCreateCompletionANDROID
- XrSurfaceAnchorCreateInfoANDROID
새 enum
새 enum 상수
XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAMEXR_ANDROID_geospatial_anchor_SPEC_VERSIONXrResult 확장:
XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
XrStructureType 확장:
XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROIDXR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROIDXR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROIDXR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROIDXR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID
문제
버전 기록
버전 1, 2025-10-30 (벤 킹)
- 초안