XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

Loại phần mở rộng

Tiện ích Instance

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

708

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

2025-07-23

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
Diego Tipaldi, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Ken Mackay, Google
Daniel Guttenberg, Qualcomm

Tổng quan

Tiện ích này cho phép theo dõi điểm đánh dấu thực và cho phép các ứng dụng đính kèm nội dung XR vào điểm đánh dấu thực một cách hiệu quả.

Tiện ích này hỗ trợ các loại điểm đánh dấu phổ biến, cụ thể là ArUco và April Tags. Tính năng này cho phép các thời gian chạy hỗ trợ ước tính kích thước của điểm đánh dấu (không bắt buộc).

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, tức là các ứng dụng phải yêu cầu quyền này một cách rõ ràng.

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

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

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

typedef struct XrSystemMarkerTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsMarkerTracking;
    XrBool32           supportsMarkerSizeEstimation;
    uint16_t           maxMarkerCount;
} XrSystemMarkerTrackingPropertiesANDROID;

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. Để biết thêm thông tin chi tiết về chuỗi cấu trúc, hãy xem cấu trúc đang được mở rộng ( XrSystemProperties ).
  • supportsMarkerTracking 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 điểm đánh dấu hay không.
  • supportsMarkerSizeEstimation 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 điểm đánh dấu hay không.
  • maxMarkerCount là số lượng điểm đánh dấu tối đa mà thời gian chạy có thể 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 điểm đánh dấu hay không bằng cách mở rộng XrSystemProperties bằng cấu trúc XrSystemMarkerTrackingPropertiesANDROID khi gọi xrGetSystemProperties . Thời gian chạy phải trả về XR_ERROR_FEATURE_UNSUPPORTED để tạo trình theo dõi điểm đánh dấu nếu và chỉ khi supportsMarkerTracking là XR_FALSE .

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

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

Điểm đánh dấu theo dõi

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

Ứng dụng tạo một XrTrackableTrackerANDROID bằng cách gọi xrCreateTrackableTrackerANDROID và chỉ định XR_TRACKABLE_TYPE_MARKER_ANDROID làm loại có thể theo dõi trong XrTrackableTrackerCreateInfoANDROID :: trackableType cũng như thiết lập một cấu hình hợp lệ bằng cách thêm XrTrackableMarkerConfigurationANDROID vào chuỗi tiếp theo của XrTrackableTrackerCreateInfoANDROID .

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

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

typedef struct XrTrackableMarkerConfigurationANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrTrackableMarkerTrackingModeANDROID       trackingMode;
    uint32_t                                   databaseCount;
    const XrTrackableMarkerDatabaseANDROID*    databases;
} XrTrackableMarkerConfigurationANDROID;

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.
  • trackingMode là một XrTrackableMarkerTrackingModeANDROID cho biết chế độ theo dõi mong muốn.
  • databaseCount là một uint32_t mô tả số lượng phần tử trong mảng databases.
  • databases là con trỏ đến một mảng XrTrackableMarkerDatabaseANDROID , mỗi mảng chứa các điểm đánh dấu mong muốn từ một từ điển nhất định để theo dõi.

Ứng dụng phải đặt một cấu hình hợp lệ bằng cách thêm XrTrackableMarkerConfigurationANDROID vào chuỗi XrTrackableTrackerCreateInfoANDROID :: next khi gọi xrCreateTrackableTrackerANDROID với XrTrackableTrackerCreateInfoANDROID :: trackableType được đặt thành XR_TRACKABLE_TYPE_MARKER_ANDROID . Nếu không, nếu loại trình theo dõi được đặt như trên nhưng cấu trúc cấu hình không có hoặc không hợp lệ, thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .

Nếu một thời gian chạy hỗ trợ tính năng ước tính kích thước điểm đánh dấu, thì ứng dụng có thể đặt XrTrackableMarkerDatabaseEntryANDROID :: edgeSize thành 0 trong XrTrackableMarkerDatabaseANDROID :: entries để 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 XrTrackableMarkerDatabaseEntryANDROID :: edgeSize thành một giá trị dương hoặc 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 và XrTrackableMarkerDatabaseEntryANDROID :: edgeSize .

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

Enum XrTrackableMarkerTrackingModeANDROID mô tả các chế độ theo dõi được hỗ trợ của điểm đánh dấu.

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;

Nội dung mô tả về các phần tử liệt kê

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID – Theo dõi các điểm đánh dấu động. Chế độ này có độ chính xác cao nhất và hoạt động trên cả điểm đánh dấu tĩnh và điểm đánh dấu đang di chuyển, nhưng cũng có mức tiêu thụ điện cao nhất.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID – Theo dõi các điểm đánh dấu tĩnh. Chế độ này chủ yếu hữu ích cho những điểm đánh dấu được biết là tĩnh, dẫn đến mức tiêu thụ điện năng thấp hơn so với chế độ động.

Cấu trúc XrTrackableMarkerDatabaseANDROID xác định một từ điển và các mã nhận dạng điểm đánh dấu tương ứng cần được theo dõi.

typedef struct XrTrackableMarkerDatabaseANDROID {
    XrTrackableMarkerDictionaryANDROID              dictionary;
    uint32_t                                        entryCount;
    const XrTrackableMarkerDatabaseEntryANDROID*    entries;
} XrTrackableMarkerDatabaseANDROID;

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

  • dictionary là XrTrackableMarkerDictionaryANDROID mà tất cả entries đều thuộc về.
  • entryCount là một uint32_t mô tả số lượng phần tử trong mảng entries. Ứng dụng có thể đặt entryCount 0 để theo dõi tất cả các điểm đánh dấu trong dictionary .
  • entries là một con trỏ đến mảng XrTrackableMarkerDatabaseEntryANDROID , mỗi con trỏ chứa cấu hình của một điểm đánh dấu cần theo dõi.

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

Liệt kê XrTrackableMarkerDictionaryANDROID mô tả các từ điển điểm đánh dấu được hỗ trợ.

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;

Cấu trúc XrTrackableMarkerDatabaseEntryANDROID định cấu hình một mã nhận dạng điểm đánh dấu duy nhất của từ điển.

typedef struct XrTrackableMarkerDatabaseEntryANDROID {
    int32_t    id;
    float      edgeSize;
} XrTrackableMarkerDatabaseEntryANDROID;

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

  • id là mã nhận dạng điểm đánh dấu như trong từ điển.
  • edgeSize biểu thị kích thước của cạnh điểm đánh dấu tính bằng mét. Nếu thời gian chạy hỗ trợ tính năng ước tính kích thước điểm đánh dấu, thì ứng dụng có thể đặt giá trị này thành 0 và kích thước điểm đánh dấu sẽ được ước tính trực tuyến. Nếu giá trị này được đặt thành 0 nhưng thời gian chạy không hỗ trợ tính năng ước tính kích thước điểm đánh dấu, thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .

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

Nhận điểm đánh dấu

Hàm xrGetTrackableMarkerANDROID được xác định như sau:

XrResult xrGetTrackableMarkerANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableMarkerANDROID*                   markerOutput);

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_MARKER_ANDROID hoặc nếu loại có thể theo dõi của XrTrackableTrackerANDROID không phải là XR_TRACKABLE_TYPE_MARKER_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_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrTrackableMarkerANDROID {
    XrStructureType                       type;
    void*                                 next;
    XrTrackingStateANDROID                trackingState;
    XrTime                                lastUpdatedTime;
    XrTrackableMarkerDictionaryANDROID    dictionary;
    int32_t                               markerId;
    XrPosef                               centerPose;
    XrExtent2Df                           extents;
} XrTrackableMarkerANDROID;

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 điểm đánh dấu.
  • lastUpdatedTime là XrTime của lần cập nhật gần đây nhất cho điểm đánh dấu.
  • dictionary là XrTrackableMarkerDictionaryANDROID của điểm đánh dấu.
  • markerId là mã nhận dạng điểm đánh dấu như trong từ điển.
  • centerPose là XrPosef của điểm đánh dấu nằm trong XrTrackableGetInfoANDROID :: baseSpace . Điểm đánh dấu nằm trong mặt phẳng XZ, với X chỉ sang bên phải của điểm đánh dấu và Z chỉ xuống dưới cùng, còn Y đi ra khỏi điểm đánh dấu dưới dạng đường pháp tuyến.
  • extents là kích thước XrExtent2Df của điểm đánh dấu. Ranh giới của khung hình chữ nhật nằm ở các điểm: centerPose +/- ( extents / 2).

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

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

Đoạn mã ví dụ sau đây minh hoạ cách lấy các điểm đánh dấu 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_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));

Lệnh mới

Cấu trúc mới

Enum mới

Hằng số Enum mới

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • Mở rộng XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • Mở rộng XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Vấn đề

Danh sách phiên bản

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

    • Nội dung mô tả ban đầu của tiện ích.