XR_ANDROID_trackables_marker

이름 문자열

XR_ANDROID_trackables_marker

확장 프로그램 유형

인스턴스 확장 프로그램

등록된 확장 프로그램 번호

708

버전

1

비준 상태

비준되지 않음

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

XR_ANDROID_trackables

지원 중단 상태

  • XR_EXT_spatial_marker_tracking 확장 프로그램에 의해 지원 중단됨

최종 수정일

2025-07-23

IP 상태

알려진 IP 클레임이 없습니다.

도움을 주신 분들

Christopher Doer, Google
Diego Tipaldi, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Ken Mackay, Google
Daniel Guttenberg, Qualcomm

개요

이 확장 프로그램을 사용하면 물리적 마커 추적이 가능하며 애플리케이션이 XR 콘텐츠를 물리적 마커에 효율적으로 연결할 수 있습니다.

이 확장 프로그램은 잘 알려진 마커 유형, 특히 ArUco 및 April 태그를 지원합니다. 런타임이 마커 크기 추정을 선택적으로 지원할 수 있도록 합니다.

권한

Android 애플리케이션은 이 확장 프로그램이 XR_ANDROID_trackables에 종속되고 환경의 지오메트리를 노출하므로 매니페스트에 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 를 호출할 때 XrSystemProperties를 XrSystemMarkerTrackingPropertiesANDROID 구조로 확장하여 시스템이 마커 추적을 지원하는지 검사할 수 있습니다 . 런타임은 supportsMarkerTracking이 XR_FALSE인 경우에만 마커 추적기 생성에 대해 XR_ERROR_FEATURE_UNSUPPORTED를 반환해야 합니다 .

런타임이 마커 추적을 지원하는 경우 maxMarkerCount는 1 이상이어야 합니다.

유효한 사용 (암시적)

마커 추적

이 확장 프로그램은 XR_TRACKABLE_TYPE_MARKER_ANDROID를 XrTrackableTypeANDROID 에 추가합니다 .

애플리케이션은 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를 반환해야 합니다.

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를 추가하여 유효한 구성을 설정해야 합니다 . 그렇지 않고 추적기 유형이 위와 같이 설정되었지만 구성 구조가 없거나 유효하지 않은 경우 런타임은 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다 .

런타임이 마커 크기 추정을 지원하는 경우 애플리케이션은 XrTrackableMarkerDatabaseANDROID :: entries에서 XrTrackableMarkerDatabaseEntryANDROID :: edgeSize를 0로 설정하여 크기 추정 사용을 나타낼 수 있습니다. 그렇지 않으면 애플리케이션은 해야 합니다. XrTrackableMarkerDatabaseEntryANDROID :: edgeSize를 양수 값으로 설정하거나 런타임은 해야 합니다. XR_ERROR_VALIDATION_FAILURE를 반환합니다.

런타임은 필터링해야 합니다. xrGetAllTrackablesANDROID의 출력을 trackingMode 및 XrTrackableMarkerDatabaseEntryANDROID :: edgeSize와 일치하도록

유효한 사용 (암시적)

XrTrackableMarkerTrackingModeANDROID 열거형은 지원되는 마커 추적 모드를 설명합니다.

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입니다. 애플리케이션은 entryCount 0을 설정하여 dictionary의 모든 마커를 추적할 수 있습니다 .
  • entries는 XrTrackableMarkerDatabaseEntryANDROID 배열을 가리키는 포인터입니다. 각 포인터에는 추적할 마커의 구성이 포함되어 있습니다.

유효한 사용 (암시적)

XrTrackableMarkerDictionaryANDROID 열거형은 지원되는 마커 딕셔너리를 설명합니다.

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를 반환해야 합니다 .

유효한 사용 (암시적)

마커 가져오기

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

XrResult xrGetTrackableMarkerANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableMarkerANDROID*                   markerOutput);

매개변수 설명

`XrTrackableANDROID`의 추적 가능한 유형이 `XR_TRACKABLE_TYPE_MARKER_ANDROID`가 아니거나 `XrTrackableTrackerANDROID`의 추적 가능한 유형이 `XR_TRACKABLE_TYPE_MARKER_ANDROID`가 아닌 경우 런타임은 `반드시` `XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID`를 반환해야 합니다 .

유효한 사용 (암시적)

반환 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_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) 지점에 있습니다.

유효한 사용 (암시적)

추적 가능한 마커를 가져오는 코드 예

다음 코드 예는 추적 가능한 마커를 가져오는 방법을 보여줍니다.

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));

새 명령어

새 구조

새 열거형

새 열거형 상수

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • XrStructureType 확장 :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • XrTrackableTypeANDROID 확장 :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

문제

버전 기록

  • 버전 1, 2025-07-23 (Levana Chen)

    • 초기 확장 프로그램 설명.