XR_ANDROID_trackables_marker
이름 문자열
XR_ANDROID_trackables_marker
확장 프로그램 유형
인스턴스 확장 프로그램
등록된 내선 번호
708
버전
1
승인 상태
비준되지 않음
확장 프로그램 및 버전 종속 항목
XR_ANDROID_trackables
지원 중단 상태
XR_EXT_spatial_marker_tracking확장 프로그램에 의해 지원 중단됨
최종 수정일
2025-07-23
IP 상태
알려진 IP 소유권 주장이 없습니다.
도움을 주신 분들
크리스토퍼 도어, Google
디에고 티팔디, Google
레바나 첸, Google
자레드 파인더, Google
스펜서 퀸, Google
니하브 자인, Google
켄 맥케이, Google
다니엘 구텐베르크, Qualcomm
개요
이 확장 프로그램은 실제 마커 추적을 사용 설정하고 애플리케이션이 XR 콘텐츠를 실제 마커에 효율적으로 연결할 수 있도록 합니다.
이 확장 프로그램은 잘 알려진 마커 유형, 특히 ArUco 및 April 태그를 지원합니다. 이를 통해 런타임은 마커 크기 추정을 선택적으로 지원할 수 있습니다.
권한
이 확장 프로그램은 XR_ANDROID_trackables에 종속되고 환경의 도형을 노출하므로 Android 애플리케이션은 매니페스트에 android.permission.SCENE_UNDERSTANDING_COARSE 권한을 나열해야 합니다. android.permission.SCENE_UNDERSTANDING_COARSE 권한은 위험한 권한으로 간주됩니다. 즉, 애플리케이션은 이 권한을 명시적으로 요청해야 합니다.
(보호 수준: 위험)
시스템 기능 검사
XrSystemMarkerTrackingPropertiesANDROID 구조는 다음과 같이 정의됩니다.
typedef struct XrSystemMarkerTrackingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsMarkerTracking;
XrBool32 supportsMarkerSizeEstimation;
uint16_t maxMarkerCount;
} XrSystemMarkerTrackingPropertiesANDROID;
회원 설명
type는 이 구조의 XrStructureType입니다.next는NULL또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다. 구조 체인에 관한 자세한 내용은 확장되는 구조 ( XrSystemProperties)를 참고하세요.supportsMarkerTracking는 현재 시스템에서 마커 추적 기능을 제공하는지 나타내는XrBool32입니다.supportsMarkerSizeEstimation는 현재 시스템에서 마커 크기 추정을 제공하는지 나타내는XrBool32입니다.maxMarkerCount은 런타임이 동시에 추적할 수 있는 최대 마커 수입니다.
애플리케이션은 xrGetSystemProperties를 호출할 때 XrSystemMarkerTrackingPropertiesANDROID 구조로 XrSystemProperties를 확장하여 시스템이 마커 추적을 지원하는지 검사할 수 있습니다. 런타임은 supportsMarkerTracking가 XR_FALSE인 경우에만 마커 추적기 생성에 대해 XR_ERROR_FEATURE_UNSUPPORTED를 반환해야 합니다(MUST).
런타임이 마커 추적을 지원하는 경우 maxMarkerCount은 1 이상이어야 합니다.
올바른 사용 (암시적)
- XrSystemMarkerTrackingPropertiesANDROID를 사용하기 전에
XR_ANDROID_trackables_marker확장 프로그램을 사용 설정해야 합니다. -
type은(는)XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID여야 합니다. -
next는NULL또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.
추적 마커
이 확장 프로그램은 XrTrackableTypeANDROID에 XR_TRACKABLE_TYPE_MARKER_ANDROID를 추가합니다.
애플리케이션은 xrCreateTrackableTrackerANDROID를 호출하고 XrTrackableTrackerCreateInfoANDROID :: trackableType에서 추적 가능한 유형으로 XR_TRACKABLE_TYPE_MARKER_ANDROID를 지정하고 XrTrackableTrackerCreateInfoANDROID의 다음 체인에 XrTrackableMarkerConfigurationANDROID를 추가하여 유효한 구성을 설정하여 XrTrackableTrackerANDROID를 만듭니다.
XrTrackableTrackerCreateInfoANDROID :: trackableType가 XR_TRACKABLE_TYPE_MARKER_ANDROID이고 XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking가 xrGetSystemProperties를 통해 XR_FALSE를 반환하는 경우 런타임은 XR_ERROR_FEATURE_UNSUPPORTED를 반환해야 합니다(must).
XrTrackableMarkerConfigurationANDROID 구조는 다음과 같이 정의됩니다.
typedef struct XrTrackableMarkerConfigurationANDROID {
XrStructureType type;
void* next;
XrTrackableMarkerTrackingModeANDROID trackingMode;
uint32_t databaseCount;
const XrTrackableMarkerDatabaseANDROID* databases;
} XrTrackableMarkerConfigurationANDROID;
회원 설명
type는 이 구조의 XrStructureType입니다.next는NULL또는 구조 체인의 다음 구조에 대한 포인터입니다.trackingMode는 추적에 원하는 모드를 나타내는 XrTrackableMarkerTrackingModeANDROID입니다.databaseCount은databases배열의 요소 수를 설명하는uint32_t입니다.databases는 XrTrackableMarkerDatabaseANDROID 배열의 포인터입니다. 각 배열에는 추적할 지정된 사전의 원하는 마커가 포함되어 있습니다.
애플리케이션은 XrTrackableTrackerCreateInfoANDROID :: trackableType가 XR_TRACKABLE_TYPE_MARKER_ANDROID로 설정된 xrCreateTrackableTrackerANDROID를 호출할 때 XrTrackableTrackerCreateInfoANDROID :: next 체인에 XrTrackableMarkerConfigurationANDROID를 추가하여 유효한 구성을 설정해야 합니다(must). 그 외의 경우 추적기 유형이 위와 같이 설정되어 있지만 구성 구조가 없거나 유효하지 않으면 런타임은 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다(MUST).
런타임이 마커 크기 추정을 지원하는 경우 애플리케이션은 XrTrackableMarkerDatabaseANDROID :: entries에서 XrTrackableMarkerDatabaseEntryANDROID :: edgeSize를 0로 설정하여 크기 추정 사용을 나타낼 수 있습니다. 그렇지 않으면 애플리케이션은 XrTrackableMarkerDatabaseEntryANDROID :: edgeSize를 양수 값으로 설정해야 합니다. 또는 런타임은 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다.
런타임은 xrGetAllTrackablesANDROID의 출력을 필터링하여 trackingMode 및 XrTrackableMarkerDatabaseEntryANDROID :: edgeSize와 일치시켜야 합니다(MUST).
올바른 사용 (암시적)
- XrTrackableMarkerConfigurationANDROID를 사용하기 전에
XR_ANDROID_trackables_marker확장 프로그램을 사용 설정해야 합니다. -
type은(는)XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID여야 합니다. -
next는NULL또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다. -
trackingMode는 유효한 XrTrackableMarkerTrackingModeANDROID 값이어야 합니다. -
databases는 유효한 XrTrackableMarkerDatabaseANDROID 구조databaseCount개의 배열에 대한 포인터여야 합니다(must). -
databaseCount매개변수는0보다 커야 합니다.
XrTrackableMarkerTrackingModeANDROID enum은 지원되는 마커 추적 모드를 설명합니다.
typedef enum XrTrackableMarkerTrackingModeANDROID {
XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID = 0,
XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID = 1,
XR_TRACKABLE_MARKER_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerTrackingModeANDROID;
열거형 설명
XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID— 동적 마커 추적 이 모드는 정확도가 가장 높으며 움직이는 마커와 정적 마커에서 작동하지만 전력 소비도 가장 높습니다.XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID— 정적 마커 추적 이 모드는 주로 정적인 것으로 알려진 마커에 유용하며, 동적 모드에 비해 전력 소비가 적습니다.
XrTrackableMarkerDatabaseANDROID 구조는 추적할 사전과 해당 마커 ID를 정의합니다.
typedef struct XrTrackableMarkerDatabaseANDROID {
XrTrackableMarkerDictionaryANDROID dictionary;
uint32_t entryCount;
const XrTrackableMarkerDatabaseEntryANDROID* entries;
} XrTrackableMarkerDatabaseANDROID;
회원 설명
dictionary는 모든entries가 속한 XrTrackableMarkerDictionaryANDROID입니다.entryCount은entries배열의 요소 수를 설명하는 uint32_t입니다. 애플리케이션은entryCount0를 설정하여dictionary의 모든 마커를 추적할 수 있습니다.entries는 XrTrackableMarkerDatabaseEntryANDROID 배열에 대한 포인터이며, 각 배열에는 추적할 마커의 구성이 포함되어 있습니다.
올바른 사용 (암시적)
- XrTrackableMarkerDatabaseANDROID를 사용하기 전에
XR_ANDROID_trackables_marker확장 프로그램을 사용 설정해야 합니다. -
dictionary은 유효한 XrTrackableMarkerDictionaryANDROID 값이어야 합니다. -
entryCount가0가 아닌 경우entries는entryCountXrTrackableMarkerDatabaseEntryANDROID 구조의 배열에 대한 포인터여야 합니다.
XrTrackableMarkerDictionaryANDROID enum은 지원되는 마커 사전을 설명합니다.
typedef enum XrTrackableMarkerDictionaryANDROID {
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID = 0,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_100_ANDROID = 1,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_250_ANDROID = 2,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_1000_ANDROID = 3,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_50_ANDROID = 4,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_100_ANDROID = 5,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_250_ANDROID = 6,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_1000_ANDROID = 7,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_50_ANDROID = 8,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_100_ANDROID = 9,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_250_ANDROID = 10,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_1000_ANDROID = 11,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_50_ANDROID = 12,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_100_ANDROID = 13,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_250_ANDROID = 14,
XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_1000_ANDROID = 15,
XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_16H5_ANDROID = 16,
XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_25H9_ANDROID = 17,
XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H10_ANDROID = 18,
XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H11_ANDROID = 19,
XR_TRACKABLE_MARKER_DICTIONARY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerDictionaryANDROID;
XrTrackableMarkerDatabaseEntryANDROID 구조는 사전에 있는 단일 마커 ID를 구성합니다.
typedef struct XrTrackableMarkerDatabaseEntryANDROID {
int32_t id;
float edgeSize;
} XrTrackableMarkerDatabaseEntryANDROID;
회원 설명
id는 사전에 제공된 마커 ID입니다.edgeSize는 마커 가장자리의 크기를 미터 단위로 나타냅니다. 런타임이 마커 크기 추정을 지원하는 경우 애플리케이션은 이를 0으로 설정할 수 있으며 마커 크기는 온라인으로 추정됩니다. 이 값이 0으로 설정되어 있지만 런타임에서 마커 크기 추정을 지원하지 않는 경우 런타임은XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다(MUST).
올바른 사용 (암시적)
- XrTrackableMarkerDatabaseEntryANDROID를 사용하기 전에
XR_ANDROID_trackables_marker확장 프로그램을 사용 설정해야 합니다.
마커 가져오기
xrGetTrackableMarkerANDROID 함수는 다음과 같이 정의됩니다.
XrResult xrGetTrackableMarkerANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableMarkerANDROID* markerOutput);
파라미터 설명
tracker는 쿼리할 XrTrackableTrackerANDROID입니다.getInfo는 추적 가능한 마커를 가져오는 데 사용되는 정보가 포함된 XrTrackableGetInfoANDROID입니다.markerOutput는 추적 가능한 마커가 반환되는 XrTrackableMarkerANDROID 구조에 대한 포인터입니다.
XrTrackableANDROID의 추적 가능한 유형이 XR_TRACKABLE_TYPE_MARKER_ANDROID가 아니거나 XrTrackableTrackerANDROID의 추적 가능한 유형이 XR_TRACKABLE_TYPE_MARKER_ANDROID가 아닌 경우 런타임은 XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID를 반환해야 합니다(must).
올바른 사용 (암시적)
- xrGetTrackableMarkerANDROID를 호출하기 전에
XR_ANDROID_trackables_marker확장 프로그램을 사용 설정해야 합니다. -
tracker는 유효한 XrTrackableTrackerANDROID 핸들이어야 합니다. -
getInfo는 유효한 XrTrackableGetInfoANDROID 구조에 대한 포인터여야 합니다. -
markerOutput는 XrTrackableMarkerANDROID 구조에 대한 포인터여야 합니다.
반품 코드
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_ERROR_VALIDATION_FAILURE
XrTrackableMarkerANDROID 구조는 다음과 같이 정의됩니다.
typedef struct XrTrackableMarkerANDROID {
XrStructureType type;
void* next;
XrTrackingStateANDROID trackingState;
XrTime lastUpdatedTime;
XrTrackableMarkerDictionaryANDROID dictionary;
int32_t markerId;
XrPosef centerPose;
XrExtent2Df extents;
} XrTrackableMarkerANDROID;
회원 설명
type는 이 구조의 XrStructureType입니다.next는NULL또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.trackingState은 마커의 XrTrackingStateANDROID입니다.lastUpdatedTime은 마커의 마지막 업데이트XrTime입니다.dictionary는 마커의 XrTrackableMarkerDictionaryANDROID입니다.markerId는 사전에 제공된 마커 ID입니다.centerPose는 XrTrackableGetInfoANDROID ::baseSpace에 있는 마커의 XrPosef입니다. 마커는 XZ 평면에 있으며 X는 마커의 오른쪽을 가리키고 Z는 하단을 가리키며 Y는 마커에서 법선으로 나옵니다.extents는 마커의 XrExtent2Df 크기입니다. 경계 상자의 경계는centerPose+/- (extents/ 2) 지점에 있습니다.
올바른 사용 (암시적)
- XrTrackableMarkerANDROID를 사용하기 전에
XR_ANDROID_trackables_marker확장 프로그램을 사용 설정해야 합니다. -
type은(는)XR_TYPE_TRACKABLE_MARKER_ANDROID여야 합니다. -
next는NULL또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다. -
trackingState는 유효한 XrTrackingStateANDROID 값이어야 합니다. -
dictionary은 유효한 XrTrackableMarkerDictionaryANDROID 값이어야 합니다.
추적 가능한 마커를 가져오는 코드 예시
다음 코드 예는 추적 가능한 마커를 가져오는 방법을 보여줍니다.
XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties; // previously initialized
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // previously initialized
PFN_xrGetTrackableMarkerANDROID xrGetTrackableMarkerANDROID; // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized
XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
// Inspect system capability
XrSystemMarkerTrackingPropertiesANDROID markerProperty {
.type = XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID,
.next = nullptr,
};
XrSystemProperties systemProperties {
.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &markerProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!markerProperty.supportsMarkerTracking) {
// Marker tracking is not supported.
return;
}
// Create a trackable tracker for marker tracking.
// If the runtime does not support size estimation, configures marker edge size of 0.1m.
XrTrackableMarkerDatabaseEntryANDROID markerEntries {
.id = 0,
.edgeSize = markerProperty.supportsMarkerSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableMarkerDatabaseANDROID markerDatabases {
.dictionary = XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID,
.entryCount = 1,
.entries = &markerEntries,
};
XrTrackableMarkerConfigurationANDROID configuration {
.type = XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID,
.next = nullptr,
.trackingMode = XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID,
.databaseCount = 1,
.databases = &markerDatabases,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &configuration,
.trackableType = XR_TRACKABLE_TYPE_MARKER_ANDROID,
};
XrTrackableTrackerANDROID markerTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &markerTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
// Handle permission requests.
}
CHK_XR(res);
// Get markers.
std::vector<XrTrackableANDROID> trackables(markerProperty.maxMarkerCount);
std::vector<XrTrackableMarkerANDROID> markers(markerProperty.maxMarkerCount, {
.type = XR_TYPE_TRACKABLE_MARKER_ANDROID,
.next = nullptr,
});
uint32_t markerSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(markerTracker, markerProperty.maxMarkerCount, &markerSize,
trackables.data()));
for (int i = 0; i < markerSize; i++) {
XrTrackableGetInfoANDROID getInfo {
.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
.next = nullptr,
.trackable = trackables[i],
.baseSpace = appSpace,
.time = updateTime,
};
CHK_XR(xrGetTrackableMarkerANDROID(markerTracker, &getInfo, &markers[i]));
// Handle markers.
}
// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(markerTracker));
새 명령어
새로운 구조
새 enum
새 enum 상수
XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAMEXR_ANDROID_trackables_marker_SPEC_VERSIONXrStructureType 확장:
XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_MARKER_ANDROIDXR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID
-
XR_TRACKABLE_TYPE_MARKER_ANDROID
문제
버전 기록
버전 1, 2025-07-23 (레바나 첸)
- 초기 확장 프로그램 설명입니다.