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입니다.next는NULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다. 이러한 구조는 핵심 OpenXR이나 이 확장 프로그램에 정의되어 있지 않습니다.maxSurfaceAnchorCount는 생성할 수 있는 최대 표면 고정점을 나타내는uint32_t입니다.
애플리케이션은 xrGetSystemProperties를 호출할 때 XrSystemGeospatialAnchorPropertiesANDROID 구조를 XrSystemProperties에 연결하여 시스템의 지리 공간 앵커 기능을 검사할 수 있습니다 .
XrSystemGeospatialPropertiesANDROID :: supportsGeospatial이 XR_TRUE인 경우 maxSurfaceAnchorCount은 런타임이 지원하는 최대 표면 앵커 수를 나타냅니다. 이 경우 한도는 0보다 커야 합니다.
XrSystemGeospatialPropertiesANDROID :: supportsGeospatial이 XR_TRUE이 아닌 경우 maxSurfaceAnchorCount은 0이어야 합니다.
유효한 사용 (암시적)
- 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을 반환해야 합니다 .
유효한 사용 (암시적)
- 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_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 구조여야 합니다(must).
표면 앵커
표면 앵커는 지형이나 지붕과 같은 표면을 기준으로 배치되는 앵커입니다.
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에 지정된 XrGeospatialTrackerANDROID가 XR_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를 반환해야 합니다 .
유효한 사용 (암시적)
- 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_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=East, +Y=Up, +Z=South인 좌표계에 대한 방향입니다.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
유효한 사용 (암시적)
-
XR_ANDROID_geospatial_anchor확장 프로그램은 XrSurfaceAnchorCreateCompletionANDROID를 사용하기 전에 사용 설정해야 합니다. -
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
XrSystemProperties 확장 :
새 열거형
새 열거형 상수
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일 (벤 킹)
- 초안