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 이상이어야 합니다.

올바른 사용 (암시적)

추적 마커

이 확장 프로그램은 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).

올바른 사용 (암시적)

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

올바른 사용 (암시적)

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

올바른 사용 (암시적)

마커 가져오기

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

올바른 사용 (암시적)

반품 코드

성공

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

새 명령어

새로운 구조

새 enum

새 enum 상수

  • 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 (레바나 첸)

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