XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

Loại tiện ích

Phần mở rộng thực thể

Số máy lẻ đã đăng ký

709

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa được phê chuẩn

Phần phụ thuộc của tiện ích và phiên bản

XR_ANDROID_trackables

Trạng thái ngừng sử dụng

  • Không dùng nữa theo tiện ích XR_EXT_spatial_marker_tracking

Ngày sửa đổi gần đây nhất

05/02/2025

Trạng thái IP

Không có tuyên bố nào về tài sản trí tuệ.

Cộng tác viên

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

Tổng quan

Tiện ích này cho phép theo dõi mã QR thực tế và giải mã dữ liệu mã QR.

Quyền

Ứng dụng Android phải có quyền android.permission.SCENE_UNDERSTANDING_COARSE trong tệp kê khai vì tiện ích này phụ thuộc vào XR_ANDROID_trackables và hiển thị hình học của môi trường. Quyền android.permission.SCENE_UNDERSTANDING_COARSE được coi là quyền nguy hiểm.

(mức độ bảo vệ: nguy hiểm)

Kiểm tra chức năng của hệ thống

Cấu trúc XrSystemQrCodeTrackingPropertiesANDROID được định nghĩa như sau:

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

Nội dung mô tả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • supportsQrCodeTracking là một XrBool32 cho biết liệu hệ thống hiện tại có cung cấp chức năng theo dõi mã QR hay không.
  • supportsQrCodeSizeEstimation là một XrBool32 cho biết liệu hệ thống hiện tại có cung cấp thông tin ước tính về kích thước mã QR hay không.
  • maxQrCodeCount là tổng số mã QR tối đa có thể được theo dõi cùng một lúc.

Ứng dụng có thể kiểm tra xem hệ thống có khả năng theo dõi mã QR hay không bằng cách mở rộng XrSystemProperties bằng cấu trúc XrSystemQrCodeTrackingPropertiesANDROID khi gọi xrGetSystemProperties . Thời gian chạy phải trả về XR_ERROR_FEATURE_UNSUPPORTED để tạo trình theo dõi mã QR khi và chỉ khi supportsQrCodeTracking là XR_FALSE .

Nếu thời gian chạy hỗ trợ tính năng theo dõi mã QR, thì maxQrCodeCount phải có giá trị tối thiểu là 1. Nếu thời gian chạy không hỗ trợ tính năng theo dõi mã QR, thì maxQrCodeCount phải là 0.

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã QR theo dõi

Tiện ích này thêm XR_TRACKABLE_TYPE_QR_CODE_ANDROID vào XrTrackableTypeANDROID .

Ứng dụng có thể tạo XrTrackableTrackerANDROID bằng cách gọi xrCreateTrackableTrackerANDROID và chỉ định XR_TRACKABLE_TYPE_QR_CODE_ANDROID làm loại có thể theo dõi trong XrTrackableTrackerCreateInfoANDROID :: trackableType để theo dõi mã QR.

Thời gian chạy phải trả về XR_ERROR_FEATURE_UNSUPPORTED nếu XrTrackableTrackerCreateInfoANDROID :: trackableType là XR_TRACKABLE_TYPE_QR_CODE_ANDROID và XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking trả về XR_FALSE thông qua xrGetSystemProperties .

Cấu trúc XrTrackableQrCodeConfigurationANDROID được định nghĩa như sau:

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

Nội dung mô tả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • trackingMode là một XrQrCodeTrackingModeANDROID cho biết chế độ theo dõi mong muốn.
  • qrCodeEdgeSize cho biết kích thước của cạnh mã QR tính bằng mét. Nếu bằng 0, thì thời gian chạy sẽ ước tính kích thước mã QR trực tuyến.

Ứng dụng phải đặt cấu hình hợp lệ bằng cách thêm XrTrackableQrCodeConfigurationANDROID vào chuỗi tiếp theo của XrTrackableTrackerCreateInfoANDROID . Nếu không, thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .

Nếu thời gian chạy hỗ trợ tính năng ước tính kích thước mã QR, thì ứng dụng có thể đặt XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize thành 0.0 để cho biết việc sử dụng tính năng ước tính kích thước.

Nếu thời gian chạy không hỗ trợ tính năng ước tính kích thước mã QR, thì ứng dụng phải đặt XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize thành một giá trị dương, nếu không, thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .

Thời gian chạy phải lọc kết quả từ xrGetAllTrackablesANDROID để khớp với trackingMode . Nếu XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize không được đặt thành 0.0, thì thời gian chạy chỉ được trả về mã QR khớp với kích thước này. Nếu XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize được đặt thành 0.0, thì thời gian chạy phải trả về tất cả mã QR có kích thước ước tính.

Cách sử dụng hợp lệ (Ngầm ẩn)

Enum XrQrCodeTrackingModeANDROID mô tả các chế độ theo dõi được hỗ trợ của mã 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;

Nội dung mô tả về giá trị liệt kê

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID — Theo dõi mã QR động. Chế độ này có độ chính xác cao nhất và hoạt động trên cả mã QR tĩnh và động, nhưng cũng tiêu thụ nhiều điện năng nhất.
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID — Theo dõi mã QR tĩnh. Chế độ này chủ yếu hữu ích cho các mã QR được biết là tĩnh, giúp giảm mức tiêu thụ điện năng so với chế độ động.
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM — Bạn nên sử dụng chế độ này cho mã QR tĩnh. Trái ngược với chế độ tĩnh, chế độ này sẽ chỉ theo dõi mã QR một lần, sau đó cập nhật vị trí của các thực thể được theo dõi chỉ dựa trên vị trí của thiết bị. Do đó, quá trình theo dõi vẫn tiếp tục ngay cả khi mã QR nằm ngoài khung tham chiếu. Điều này giúp giảm thiểu mức tiêu thụ điện năng sau khi mã QR được theo dõi. (Do tiện ích XR_QCOM_trackables_qr_code_operations thêm)

Lấy mã QR

Hàm xrGetTrackableQrCodeANDROID được định nghĩa như sau:

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

Nội dung mô tả về tham số

Thời gian chạy phải trả về XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID nếu loại có thể theo dõi của XrTrackableANDROID không phải là XR_TRACKABLE_TYPE_QR_CODE_ANDROID hoặc nếu loại có thể theo dõi của XrTrackableTrackerANDROID không phải là XR_TRACKABLE_TYPE_QR_CODE_ANDROID .

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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

Cấu trúc XrTrackableQrCodeANDROID được định nghĩa như sau:

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

Nội dung mô tả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • trackingState là XrTrackingStateANDROID của mã QR.
  • lastUpdatedTime là XrTime của lần cập nhật mã QR gần đây nhất. Nếu lastUpdatedTime thay đổi so với lệnh gọi gần nhất, thì tất cả các trường khác có thể đã thay đổi.
  • centerPose là XrPosef của mã QR nằm trong XrTrackableGetInfoANDROID :: baseSpace . Mã QR nằm trong mặt phẳng XZ, trong đó X hướng về bên phải của mã QR, Z hướng về phía dưới và Y hướng ra ngoài mã QR theo hướng vuông góc.
  • extents là kích thước XrExtent2Df của mã QR. Ranh giới của hộp bao quanh nằm ở các điểm: centerPose +/- ( extents / 2).
  • bufferCapacityInput là chức năng của buffer hoặc 0 để truy xuất chức năng cần thiết.
  • bufferCountOutput Nếu bufferCapacityInput là 0 , thì thời gian chạy sẽ ghi kích thước vùng đệm cần thiết vào bufferCountOutput . Nếu không, nó sẽ chứa tổng số phần tử được ghi trong buffer . Nếu dữ liệu mã QR chưa được giải mã, thì thời gian chạy phải đặt bufferCountOutput thành 0.
  • buffer là con trỏ đến một mảng char để ghi dữ liệu mã QR đã giải mã. Nếu ứng dụng không quan tâm đến dữ liệu mã QR đã giải mã, thì ứng dụng có thể truyền nullptr và bỏ qua lệnh gọi thứ hai. Dữ liệu mã QR được trả về dưới dạng chuỗi UTF-8 có ký tự kết thúc rỗng.
  • Hãy xem phần Tham số dung lượng bộ nhớ đệm để biết nội dung mô tả chi tiết về cách truy xuất kích thước buffer cần thiết.

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã ví dụ để lấy mã QR có thể theo dõi

Mã ví dụ sau đây minh hoạ cách lấy mã QR có thể theo dõi.

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

Lệnh mới

Cấu trúc mới

Enum mới

Hằng số enum mới

  • XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
  • XR_ANDROID_trackables_qr_code_SPEC_VERSION

  • Mở rộng XrStructureType :

    • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID

  • Mở rộng XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Vấn đề

Danh sách phiên bản

  • Bản sửa đổi 1, ngày 5 tháng 2 năm 2025 (Levana Chen)

    • Nội dung mô tả ban đầu về tiện ích.