Tiện ích OpenXR XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

Loại phần mở rộng

Tiện ích phiên bản

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

460

Bản sửa đổi

1

Phần mở rộng và các phần phụ thuộc vào phiên bản

XR_ANDROID_trackables

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

2025-02-05

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.

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

XrSystemQrCodeTrackingPropertiesANDROID

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

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint32_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ỏ 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à 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 có thể được theo dõi cùng một lúc.

Một ứ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 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ì thời gian chạy đó phải hỗ trợ maxQrCodeCount mã QR được theo dõi tại bất kỳ thời điểm nào.

Nếu một 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 0 để cho biết việc sử dụng tính năng ước tính kích thước. Nếu không, ứng dụng phải đặt XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize thành một giá trị dương hoặc XR_ERROR_VALIDATION_FAILURE sẽ được trả về.

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

  • Bạn phải bật tiện ích XR_ANDROID_trackables_qr_code trước khi sử dụng XrSystemQrCodeTrackingPropertiesANDROID
  • type phải là XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc

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 một 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.

XrTrackableQrCodeConfigurationANDROID

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

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType               type;
    const 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ỏ 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ế độ 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, kích thước mã QR sẽ được ước tính trực tuyến.

Ứng dụng phải đặt 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 để cho biết việc sử dụng tính năng ước tính kích thước. Nếu không, ứng dụng phải đặt XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize thành một giá trị dương hoặc XR_ERROR_VALIDATION_FAILURE sẽ được trả về.

Thời gian chạy phải lọc đầu ra từ xrGetAllTrackablesANDROID để khớp với trackingMode và qrCodeEdgeSize.

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

  • Bạn phải bật tiện ích XR_ANDROID_trackables_qr_code trước khi sử dụng XrTrackableQrCodeConfigurationANDROID
  • type phải là XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
  • trackingMode phải là một giá trị XrQrCodeTrackingModeANDROID hợp lệ

XrQrCodeTrackingModeANDROID

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_STATIC_ANDROID = 0,
    XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_QR_CODE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrQrCodeTrackingModeANDROID;

| Enum | Description | Enum | Description XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID ' | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | Mã QR là mã động và có thể di chuyển. |

Nhận mã QR

xrGetTrackableQrCodeANDROID

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ố

  • tracker là XrTrackableTrackerANDROID cần truy vấn.
  • getInfo là XrTrackableGetInfoANDROID có thông tin dùng để lấy mã QR có thể theo dõi.
  • qrCodeOutput là một con trỏ đến cấu trúc XrTrackableQrCodeANDROID mà trong đó Mã QR có thể theo dõi được trả về.

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)

  • Bạn phải bật tiện ích XR_ANDROID_trackables_qr_code trước khi gọi xrGetTrackableQrCodeANDROID
  • tracker phải là một mã nhận dạng XrTrackableTrackerANDROID hợp lệ
  • getInfo phải là con trỏ đến một cấu trúc XrTrackableGetInfoANDROID hợp lệ
  • qrCodeOutput phải là một con trỏ đến cấu trúc XrTrackableQrCodeANDROID

XrTrackableQrCodeANDROID

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ỏ 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.
  • 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 trỏ đến bên phải mã QR và Z trỏ đến đáy của mã QR.
  • 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 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.
  • buffer là con trỏ đến một mảng char để ghi dữ liệu mã QR đã giải mã. Ứng dụng có thể truyền một nullptr để xác định kích thước bộ đệm cần thiết hoặc nếu không yêu cầu dữ liệu mã QR giải mã. 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)

  • Bạn phải bật tiện ích XR_ANDROID_trackables_qr_code trước khi sử dụng XrTrackableQrCodeANDROID
  • type phải là XR_TYPE_TRACKABLE_QR_CODE_ANDROID
  • next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
  • trackingState phải là một giá trị XrTrackingStateANDROID hợp lệ
  • Nếu bufferCapacityInput không phải là 0, thì buffer phải là con trỏ đến một mảng gồm các giá trị bufferCapacityInput char

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);
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    qrCodes[i].type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID;
    qrCodes[i].next = nullptr;
    qrCodes[i].bufferCountOutput = 0;
    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));

Hằng số Enum mới

Liệt kê XrStructureType được mở rộng bằng:

  • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_ANDROID

Liệt kê XrTrackableTypeANDROID được mở rộng bằng:

  • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Enum mới

  • XrQrCodeTrackingModeANDROID

Cấu trúc mới

  • XrSystemQrCodeTrackingPropertiesANDROID
  • XrTrackableQrCodeConfigurationANDROID
  • XrTrackableQrCodeANDROID

Hàm mới

  • xrGetTrackableQrCodeANDROID

Vấn đề

Nhật ký 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.

OpenXR™ và biểu trưng OpenXR là các nhãn hiệu thuộc sở hữu của The Khronos Group Inc. và được đăng ký làm nhãn hiệu ở Trung Quốc, Liên minh Châu Âu, Nhật Bản và Vương quốc Anh.