XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

Loại phần mở rộng

Tiện ích Instance

Số máy nhánh đã đăng ký

709

Bản sửa đổi

1

Trạng thái phê chuẩn

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

Phần mở rộng và các phần phụ thuộc của 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ó thông báo xác nhận quyền sở hữu nào đã biết về quyền sở hữu 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 và giải mã dữ liệu mã QR.

Quyền

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

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

Kiểm tra khả năng của hệ thống

Cấu trúc XrSystemQrCodeTrackingPropertiesANDROID được xác định như sau:

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con 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 khả 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 kích thước mã QR hay không.
  • maxQrCodeCount là tổng số mã QR tối đa mà bạn có thể theo dõi cùng một lúc.

Một ứng dụng có thể kiểm tra xem hệ thống có thể 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 nếu và chỉ khi supportsQrCodeTracking là XR_FALSE .

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

Sử dụng hợp lệ (Ngầm ẩn)

Theo dõi mã QR

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 xác định như sau:

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con 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à XrQrCodeTrackingModeANDROID cho biết chế độ mong muốn để theo dõi.
  • 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ời gian chạy sẽ ước tính kích thước mã QR trực tuyến.

Ứng dụng phải thiết lập một cấu hình hợp lệ bằng cách thêm XrTrackableQrCodeConfigurationANDROID vào chuỗi XrTrackableTrackerCreateInfoANDROID tiếp theo . 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ợ việc ướ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 đầu ra 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 có 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.

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ề các phần tử 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à mã QR đang di chuyển, nhưng cũng có mức tiêu thụ điện cao 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 những mã QR 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. Khá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 đó, hoạt động 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 dẫn đến mức tiêu thụ điện năng tối thiểu sau khi mã QR được theo dõi. (Do tiện ích XR_QCOM_trackables_qr_code_operations thêm vào)

Tạo mã QR

Hàm xrGetTrackableQrCodeANDROID được xác định 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 .

Sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • 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 xác định 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ả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con 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 đây 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, với X hướng về bên phải mã QR, Z hướng xuống dưới và Y hướng ra ngoài mã QR dưới dạng pháp tuyến.
  • extents là kích thước XrExtent2Df của mã QR. Ranh giới của khung hình chữ nhật nằm ở các điểm: centerPose +/- ( extents / 2).
  • bufferCapacityInput là khả năng của buffer hoặc 0 để truy xuất khả năng bắt buộc.
  • 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à một con trỏ đến một mảng char để ghi dữ liệu mã QR đã giải mã. Nếu không quan tâm đến dữ liệu mã QR đã giải mã, ứng dụng có thể truyền nullptr và bỏ qua lệnh gọi thứ hai trong hai lệnh gọi. Dữ liệu mã QR được trả về dưới dạng chuỗi UTF-8 kết thúc bằng giá trị rỗng.
  • Hãy xem phần Tham số kích thước 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.

Sử dụng hợp lệ (Ngầm ẩn)

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

Đoạn 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 của tiện ích.