Android XR for OpenXR | Android Developers

Android XR SDK가 개발자 프리뷰 4에 도달했으며 여러분의 의견을 기다리고 있습니다. 다양한 기능을 사용해 보고 지원 페이지를 방문하여 문의하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

XR_ANDROID_trackables_qr_code

이름 문자열

XR_ANDROID_trackables_qr_code

확장 프로그램 유형

인스턴스 확장 프로그램

등록된 확장 프로그램 번호

709

버전

비준 상태

비준되지 않음

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

XR_ANDROID_trackables

지원 중단 상태

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

최종 수정일

2025-02-05

IP 상태

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

도움을 주신 분들

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

개요

이 확장 프로그램을 사용하면 실제 QR 코드 추적 및 QR 코드 데이터 디코딩이 가능합니다.

권한

Android 애플리케이션은 이 확장 프로그램이 XR_ANDROID_trackables에 종속되고 환경의 지오메트리를 노출하므로 매니페스트에 android.permission.SCENE_UNDERSTANDING_COARSE 권한을 나열해야 합니다. android.permission.SCENE_UNDERSTANDING_COARSE 권한은 위험한 권한으로 간주됩니다.

(보호 수준: 위험)

시스템 기능 검사

XrSystemQrCodeTrackingPropertiesANDROID 구조는 다음과 같이 정의됩니다.

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint16_t           maxQrCodeCount;
} XrSystemQrCodeTrackingPropertiesANDROID;

회원 설명

type은 이 구조의 XrStructureType입니다.
next는 NULL이거나 구조 체인의 다음 구조를 가리키는 포인터입니다. 이러한 구조는 핵심 OpenXR 또는 이 확장 프로그램에 정의되어 있지 않습니다.
supportsQrCodeTracking은 현재 시스템이 QR 코드 추적 기능을 제공하는지 나타내는 XrBool32입니다.
supportsQrCodeSizeEstimation은 현재 시스템이 QR 코드 크기 추정을 제공하는지 나타내는 XrBool32입니다.
maxQrCodeCount는 동시에 추적할 수 있는 최대 QR 코드 수입니다.

애플리케이션은 xrGetSystemProperties 를 호출할 때 XrSystemQrCodeTrackingPropertiesANDROID 구조로 XrSystemProperties를 확장하여 시스템이 QR 코드 추적을 지원하는지 검사할 수 있습니다 . 런타임은 supportsQrCodeTracking이 XR_FALSE인 경우에만 QR 코드 트래커 생성에 대해 XR_ERROR_FEATURE_UNSUPPORTED를 반환해야 합니다 .

런타임이 QR 코드 추적을 지원하는 경우 maxQrCodeCount는 1 이상이어야 합니다. 런타임이 QR 코드 추적을 지원하지 않는 경우 maxQrCodeCount는 0이어야 합니다.

유효한 사용 (암시적)

XR_ANDROID_trackables_qr_code 확장 프로그램을 사용하기 전에 XrSystemQrCodeTrackingPropertiesANDROID를 사용 설정해야 합니다.
type 여야 합니다XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
next 는 NULL이거나 구조 체인의 다음 구조를 가리키는 유효한 포인터여야 합니다

QR 코드 추적

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

애플리케이션은 xrCreateTrackableTrackerANDROID를 호출하고 XrTrackableTrackerCreateInfoANDROID :: trackableType에서 추적 가능한 유형으로 XR_TRACKABLE_TYPE_QR_CODE_ANDROID를 지정하여 XrTrackableTrackerANDROID를 만들 수 있습니다.

런타임은 해야 합니다. XR_ERROR_FEATURE_UNSUPPORTED를 반환합니다. XrTrackableTrackerCreateInfoANDROID :: trackableType가 XR_TRACKABLE_TYPE_QR_CODE_ANDROID이고 XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking가 xrGetSystemProperties를 통해 XR_FALSE를 반환하는 경우

XrTrackableQrCodeConfigurationANDROID 구조는 다음과 같이 정의됩니다.

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType                type;
    void*                          next;
    XrQrCodeTrackingModeANDROID    trackingMode;
    float                          qrCodeEdgeSize;
} XrTrackableQrCodeConfigurationANDROID;

회원 설명

type은 이 구조의 XrStructureType입니다.
next는 NULL이거나 구조 체인의 다음 구조를 가리키는 포인터입니다. 이러한 구조는 핵심 OpenXR 또는 이 확장 프로그램에 정의되어 있지 않습니다.
trackingMode는 추적에 원하는 모드를 나타내는 XrQrCodeTrackingModeANDROID입니다.
qrCodeEdgeSize는 QR 코드 가장자리의 크기를 미터 단위로 나타냅니다. 0이면 런타임이 QR 코드 크기를 온라인으로 추정합니다.

애플리케이션은 XrTrackableQrCodeConfigurationANDROID를 XrTrackableTrackerCreateInfoANDROID 의 다음 체인에 추가하여 유효한 구성을 설정해야 합니다 . 그렇지 않으면 런타임은 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다 .

런타임이 QR 코드 크기 추정을 지원하는 경우 애플리케이션은 크기 추정 사용을 나타낼 수 있습니다.qrCodeEdgeSize0.0

런타임이 QR 코드 크기 추정을 지원하지 않는 경우 애플리케이션은 반드시 XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize를 양수 값으로 설정해야 합니다. 그렇지 않으면 런타임은 반드시 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다.

런타임은 필터링해야 합니다. xrGetAllTrackablesANDROID의 출력을 필터링하여 trackingMode와 일치시켜야 합니다. XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize가 0.0으로 설정되지 않은 경우 런타임은 이 크기와 일치하는 QR 코드만 반환해야 합니다. XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize가 0.0으로 설정된 경우 런타임은 추정된 크기의 모든 QR 코드를 반환해야 합니다.

유효한 사용 (암시적)

XR_ANDROID_trackables_qr_code 확장 프로그램을 사용하기 전에 XrTrackableQrCodeConfigurationANDROID를 사용 설정해야 합니다.
type 여야 합니다 XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
next 는 NULL이거나 구조 체인의 다음 구조를 가리키는 유효한 포인터여야 **합니다**. XrTrackableQrCodeVersionFilterQCOM도 참고하세요.
trackingMode 는 유효한 XrQrCodeTrackingModeANDROID 값이어야 합니다.

XrQrCodeTrackingModeANDROID 열거형은 QR 코드의 지원되는 추적 모드를 설명합니다.

typedef enum XrQrCodeTrackingModeANDROID {
    XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM = 1000314000,
    XR_QR_CODE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrQrCodeTrackingModeANDROID;

열거형 설명

XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID — 동적 QR 코드 추적. 이 모드는 정확도가 가장 높고 이동 및 정적 QR 코드에서 작동하지만 전력 소비도 가장 높습니다.
XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID — 정적 QR 코드 추적. 이 모드는 정적인 것으로 알려진 QR 코드에 주로 유용하므로 동적 모드에 비해 전력 소비가 적습니다.
XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM — 이 모드는 정적 QR 코드에 사용해야 합니다. 정적 모드와 달리 이 모드는 QR 코드를 한 번만 추적한 다음 기기의 위치를 기반으로 추적된 인스턴스의 위치만 업데이트합니다. 따라서 QR 코드가 참조 프레임의 시야에서 벗어나도 추적이 계속됩니다. 이렇게 하면 QR 코드가 추적된 후 전력 소비가 최소화됩니다. XR_QCOM_trackables_qr_code_operations 확장 프로그램에 의해 추가됨)

QR 코드 가져오기

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

XrResult xrGetTrackableQrCodeANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableQrCodeANDROID*                   qrCodeOutput);

파라미터 설명

tracker는 쿼리할 XrTrackableTrackerANDROID입니다.
getInfo는 추적 가능한 QR 코드를 가져오는 데 사용되는 정보가 포함된 XrTrackableGetInfoANDROID입니다.
qrCodeOutput은 추적 가능한 QR 코드가 반환되는 XrTrackableQrCodeANDROID 구조를 가리키는 포인터입니다.

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

유효한 사용 (암시적)

XR_ANDROID_trackables_qr_code 확장 프로그램을 xrGetTrackableQrCodeANDROID를 호출하기 전에 사용 설정해야 합니다.
tracker 는 유효한 XrTrackableTrackerANDROID 핸들이어야 합니다.
getInfo 는 유효한 XrTrackableGetInfoANDROID 구조를 가리키는 포인터여야 합니다
qrCodeOutput 은 XrTrackableQrCodeANDROID 구조를 가리키는 포인터여야 합니다

반환 코드

성공

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_SIZE_INSUFFICIENT
XR_ERROR_TIME_INVALID
XR_ERROR_VALIDATION_FAILURE

XrTrackableQrCodeANDROID 구조는 다음과 같이 정의됩니다.

typedef struct XrTrackableQrCodeANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrTime                    lastUpdatedTime;
    XrPosef                   centerPose;
    XrExtent2Df               extents;
    uint32_t                  bufferCapacityInput;
    uint32_t                  bufferCountOutput;
    char*                     buffer;
} XrTrackableQrCodeANDROID;

회원 설명

type은 이 구조의 XrStructureType입니다.
next는 NULL이거나 구조 체인의 다음 구조를 가리키는 포인터입니다. 이러한 구조는 핵심 OpenXR 또는 이 확장 프로그램에 정의되어 있지 않습니다.
trackingState는 QR 코드의 XrTrackingStateANDROID입니다.
lastUpdatedTime은 QR 코드의 마지막 업데이트 XrTime입니다. lastUpdatedTime이 마지막 호출에서 변경된 경우 다른 모든 필드가 변경되었을 수 있습니다.
centerPose는 XrTrackableGetInfoANDROID :: baseSpace에 있는 QR 코드의 XrPosef입니다 . QR 코드는 XZ 평면에 있으며 X는 QR 코드의 오른쪽을 가리키고 Z는 QR 코드의 하단을 가리키며 Y는 QR 코드에서 법선으로 나옵니다.
extents는 XrExtent2Df QR 코드의 측정기준입니다. 경계 상자의 경계는 centerPose +/- ( extents / 2) 지점에 있습니다.
bufferCapacityInput은 buffer의 기능이거나 필요한 기능을 가져오는 0입니다.
bufferCountOutput bufferCapacityInput이 0이면 런타임이 필요한 버퍼 크기를 bufferCountOutput에 씁니다 . 그렇지 않으면 buffer에 작성된 총 요소가 포함됩니다 . QR 코드 데이터가 아직 디코딩되지 않은 경우 런타임은 bufferCountOutput을 0으로 설정해야 합니다.
buffer는 디코딩된 QR 코드 데이터를 작성할 char 배열을 가리키는 포인터입니다. 애플리케이션이 디코딩된 QR 코드 데이터를 신경 쓰지 않는 경우 nullptr를 전달하고 두 번째 두 번 호출을 생략할 수 있습니다. QR 코드 데이터는 null로 종료된 UTF-8 문자열로 반환됩니다.
필요한 buffer 크기를 가져오는 방법에 관한 자세한 설명은 버퍼 크기 매개변수 섹션을 참고하세요.

유효한 사용 (암시적)

XrTrackableQrCodeANDROID를 사용하기 전에 XR_ANDROID_trackables_qr_code 확장 프로그램을 사용 설정해야**합니다**.
type 여야 합니다 XR_TYPE_TRACKABLE_QR_CODE_ANDROID
next 는 NULL이거나 구조 체인의 다음 구조를 가리키는 유효한 포인터여야 **합니다**. XrTrackableQrCodeVersionQCOM도 참고하세요.
trackingState 는 유효한 XrTrackingStateANDROID 값이어야 합니다.
bufferCapacityInput이 0이 아닌 경우 buffer는 bufferCapacityInput char 값의 배열을 가리키는 포인터여야 합니다.

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

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

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_xrGetTrackableQrCodeANDROID xrGetTrackableQrCodeANDROID;           // 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
XrSystemQrCodeTrackingPropertiesANDROID qrCodeProperty {
  .type = XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &qrCodeProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!qrCodeProperty.supportsQrCodeTracking) {
    // QR code tracking is not supported.
    return;
}

// Create a trackable tracker for QR code tracking.
// If the runtime does not support size estimation, configures QR code edge size of 0.1m.
XrTrackableQrCodeConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID,
  .qrCodeEdgeSize = qrCodeProperty.supportsQrCodeSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_QR_CODE_ANDROID
};
XrTrackableTrackerANDROID qrCodeTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &qrCodeTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get QR codes.
std::vector<XrTrackableANDROID> trackables(qrCodeProperty.maxQrCodeCount);
std::vector<XrTrackableQrCodeANDROID> qrCodes(qrCodeProperty.maxQrCodeCount, {
  .type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID,
  .next = nullptr,
  .bufferCountOutput = 0,
});
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables.at(i),
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
    if (qrCodes[i].bufferCountOutput > 0) {
        // Allocate the buffer if it is not already allocated.
        if (qrCodes[i].bufferCapacityInput == 0) {
            qrCodes[i].buffer = new char[qrCodes[i].bufferCountOutput];
            qrCodes[i].bufferCapacityInput = qrCodes[i].bufferCountOutput;
            CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
        }
    }
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(qrCodeTracker));

새 명령어

xrGetTrackableQrCodeANDROID

새 구조

XrTrackableQrCodeANDROID
XrSystemProperties 확장 :
- XrSystemQrCodeTrackingPropertiesANDROID
XrTrackableTrackerCreateInfoANDROID 확장 :
- XrTrackableQrCodeConfigurationANDROID

새 열거형

XrQrCodeTrackingModeANDROID

새 열거형 상수

XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
XR_ANDROID_trackables_qr_code_SPEC_VERSION
XrStructureType 확장 :
- XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
- XR_TYPE_TRACKABLE_QR_CODE_ANDROID
- XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
XrTrackableTypeANDROID 확장 :
- XR_TRACKABLE_TYPE_QR_CODE_ANDROID

문제

버전 기록

버전 1, 2025-02-05 (Levana Chen)
- 초기 확장 프로그램 설명.