XR_ANDROID_trackables_image

Name String

XR_ANDROID_trackables_image

Loại phần mở rộng

Tiện ích Instance

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

710

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_EXT_future

XR_ANDROID_trackables

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

2025-04-08

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
Daniel Guttenberg, Qualcomm
Mark Vadasi, Qualcomm
Markus Birkner, Qualcomm
Maximilian Mayer, Qualcomm

Tổng quan

Tiện ích này cho phép theo dõi hình ảnh phẳng theo quy định của các nhóm hình ảnh tham chiếu đầu vào.

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

typedef struct XrSystemImageTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsImageTracking;
    XrBool32           supportsPhysicalSizeEstimation;
    uint32_t           maxTrackedImageCount;
    uint32_t           maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;

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

  • typeXrStructureType của cấu trúc này.
  • nextNULL 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 ).
  • supportsImageTracking 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 hình ảnh hay không.
  • supportsPhysicalSizeEstimation 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 hình ảnh hay không.
  • maxTrackedImageCount là tổng số hình ảnh tối đa mà bạn có thể theo dõi cùng lúc.
  • maxLoadedImageCount là tổng số hình ảnh tham chiếu tối đa mà bạn có thể tải trên tất cả các cơ sở dữ liệu.

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

Nếu hỗ trợ tính năng theo dõi hình ảnh, thì thời gian chạy phải hỗ trợ maxTrackedImageCount hình ảnh được theo dõi tại bất kỳ thời điểm nào.

Nếu hỗ trợ tính năng theo dõi hình ảnh, thì thời gian chạy phải hỗ trợ maxLoadedImageCount hình ảnh đã tải bất cứ lúc nào.

Nếu một thời gian chạy hỗ trợ ước tính kích thước hình ảnh, thì ứng dụng có thể đặt XrTrackableImageDatabaseEntryANDROID :: physicalWidth 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 XrTrackableImageDatabaseEntryANDROID :: physicalWidth 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)

Tạo cơ sở dữ liệu

Ứng dụng có thể tạo một đối tượng XrTrackableImageDatabaseANDROID bằng cách tạo một hoặc nhiều cấu trúc XrTrackableImageDatabaseEntryANDROID và truyền các cấu trúc đó đến hàm xrCreateTrackableImageDatabaseAsyncANDROID thông qua cấu trúc XrTrackableImageDatabaseCreateInfoANDROID.

Ứng dụng phải cung cấp ít nhất một XrTrackableImageDatabaseEntryANDROID khi tạo một đối tượng XrTrackableImageDatabaseANDROID.

XrTrackableImageDatabaseANDROID là một đối tượng xử lý đại diện cho một tập hợp các hình ảnh tham chiếu đã xử lý mà có thể được phát hiện và theo dõi trong môi trường.

XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)

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

typedef struct XrTrackableImageDatabaseEntryANDROID {
    XrStructureType                        type;
    const void*                            next;
    XrTrackableImageTrackingModeANDROID    trackingMode;
    float                                  physicalWidth;
    uint32_t                               imageWidth;
    uint32_t                               imageHeight;
    XrTrackableImageFormatANDROID          format;
    uint32_t                               bufferSize;
    const uint8_t*                         buffer;
} XrTrackableImageDatabaseEntryANDROID;

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

  • typeXrStructureType của cấu trúc này.
  • nextNULL 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.
  • trackingModeXrTrackableImageTrackingModeANDROID cho biết chế độ mong muốn để theo dõi.
  • physicalWidth cho biết chiều rộng của hình ảnh tính bằng mét. Nếu bằng 0, kích thước hình ảnh sẽ được ước tính trực tuyến.
  • imageWidth cho biết chiều rộng của hình ảnh tính bằng pixel.
  • imageHeight cho biết chiều cao của hình ảnh tính bằng pixel.
  • format là một XrTrackableImageFormatANDROID cho biết định dạng của dữ liệu hình ảnh trong buffer .
  • bufferSize cho biết độ dài byte của buffer .
  • buffer là vùng đệm uint8_t chứa dữ liệu điểm ảnh của hình ảnh tham khảo. Nội dung của buffer phải hợp lệ trong suốt thời gian hoạt động không đồng bộ tạo cơ sở dữ liệu, được bắt đầu bằng xrCreateTrackableImageDatabaseAsyncANDROID và hoàn tất bằng xrCreateTrackableImageDatabaseCompleteANDROID .

Ứng dụng có thể đặt physicalWidth thành 0 để yêu cầu ước tính kích thước trực tuyến nếu XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimationXR_TRUE .

Thời gian chạy có thể trả về XR_ERROR_VALIDATION_FAILURE từ xrCreateTrackableImageDatabaseAsyncANDROID nếu bufferSize không khớp với kích thước dự kiến dựa trên imageWidth , imageHeightformat của mục nhập .

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

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

typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
    XrStructureType                                type;
    const void*                                    next;
    uint32_t                                       entryCount;
    const XrTrackableImageDatabaseEntryANDROID*    entries;
} XrTrackableImageDatabaseCreateInfoANDROID;

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

  • typeXrStructureType của cấu trúc này.
  • nextNULL 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.
  • entryCount là một uint32_t chỉ định số lượng phần tử trong mảng entries.
  • entries là một mảng gồm các cấu trúc XrTrackableImageDatabaseEntryANDROID.

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

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

typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
    XrStructureType                    type;
    void*                              next;
    XrResult                           futureResult;
    XrTrackableImageDatabaseANDROID    database;
} XrCreateTrackableImageDatabaseCompletionANDROID;

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

  • typeXrStructureType của cấu trúc này.
  • nextNULL 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.
  • futureResultXrResult của thao tác không đồng bộ.
  • database là đối tượng XrTrackableImageDatabaseANDROID đã tạo.

Mã trả về trong tương lai

Giá trị futureResult:

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

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

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

XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
    XrSession                                   session,
    const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

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

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_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateTrackableImageDatabaseCompletionANDROID* completion);

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

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_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrDestroyTrackableImageDatabaseANDROID(
    XrTrackableImageDatabaseANDROID             database);

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

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

Độ an toàn cho luồng

  • Quyền truy cập vào database và mọi đối tượng con phải được đồng bộ hoá bên ngoài

Mã trả về

Thành công

  • XR_SUCCESS

Thất bại

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Theo dõi hình ảnh

Tiện ích này thêm XR_TRACKABLE_TYPE_IMAGE_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_IMAGE_ANDROID làm loại có thể theo dõi trong XrTrackableTrackerCreateInfoANDROID :: trackableType để theo dõi hình ảnh.

Thời gian chạy phải trả về XR_ERROR_FEATURE_UNSUPPORTED nếu XrTrackableTrackerCreateInfoANDROID :: trackableTypeXR_TRACKABLE_TYPE_IMAGE_ANDROIDXrSystemImageTrackingPropertiesANDROID :: supportsImageTracking trả về XR_FALSE thông qua xrGetSystemProperties .

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

typedef struct XrTrackableImageConfigurationANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  databaseCount;
    const XrTrackableImageDatabaseANDROID*    databases;
} XrTrackableImageConfigurationANDROID;

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

  • typeXrStructureType của cấu trúc này.
  • nextNULL 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.
  • databaseCount là một uint32_t chỉ định số lượng phần tử trong databases
  • databases là một mảng XrTrackableImageDatabaseANDROID chỉ định các cơ sở dữ liệu để tạo trì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 XrTrackableImageConfigurationANDROID vào chuỗi next của XrTrackableTrackerCreateInfoANDROID . Nếu không, thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .

Ứng dụng phải cung cấp ít nhất một cấu trúc XrTrackableImageDatabaseANDROID để tạo trình theo dõi.

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

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

typedef enum XrTrackableImageTrackingModeANDROID {
    XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;

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

  • XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID – Chế độ này có độ chính xác cao nhất và cho phép theo dõi hình ảnh chuyển động với độ trễ thấp. Chế độ này cũng có mức tiêu thụ điện cao nhất.
  • XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID – Bạn nên sử dụng chế độ này cho những hình ảnh được biết là tĩnh hoặc bán tĩnh. Chế độ này tiêu thụ ít điện năng hơn so với chế độ động. Nếu một hình ảnh tĩnh đang được di chuyển, thì hình ảnh đó sẽ được cập nhật với độ trễ cao hơn nhiều so với khi sử dụng chế độ động.

Liệt kê XrTrackableImageFormatANDROID mô tả các định dạng được hỗ trợ của hình ảnh.

typedef enum XrTrackableImageFormatANDROID {
    XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
    XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;

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

  • XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID – Định dạng hình ảnh RGBA với dữ liệu màu và độ trong suốt 8 bit cho mỗi kênh.

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

XrResult xrAddTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

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

Khi XrTrackableImageDatabaseANDROID được thêm vào một trình theo dõi, các hình ảnh tham chiếu của cơ sở dữ liệu đó phải được xem xét để phát hiện và theo dõi ngoài mọi cơ sở dữ liệu khác đã được thêm trước đó bằng xrAddTrackableImageDatabaseANDROID hoặc thông qua cấu trúc XrTrackableImageConfigurationANDROID khi tạo trình theo dõi ban đầu.

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrRemoveTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

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

Khi XrTrackableImageDatabaseANDROID bị xoá khỏi XrTrackableTrackerANDROID , các cấu trúc XrTrackableImageDatabaseEntryANDROID của cơ sở dữ liệu đó không được xem xét để phát hiện và theo dõi nữa. Bạn không được báo cáo bất kỳ mục nào đang được theo dõi trong cơ sở dữ liệu đó nữa. Bạn không được huỷ ngầm đối tượng XrTrackableImageDatabaseANDROID đã xoá trong quá trình thực hiện thao tác này.

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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Lấy hình ảnh

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

XrResult xrGetTrackableImageANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableImageANDROID*                    trackable);

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_IMAGE_ANDROID hoặc nếu loại có thể theo dõi của XrTrackableTrackerANDROID không phải là XR_TRACKABLE_TYPE_IMAGE_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_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrTrackableImageANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrTrackingStateANDROID             trackingState;
    XrTime                             lastUpdatedTime;
    XrTrackableImageDatabaseANDROID    database;
    uint32_t                           databaseEntryIndex;
    XrPosef                            centerPose;
    XrExtent2Df                        extents;
} XrTrackableImageANDROID;

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

  • typeXrStructureType của cấu trúc này.
  • nextNULL 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.
  • trackingStateXrTrackingStateANDROID của hình ảnh.
  • lastUpdatedTimeXrTime của lần cập nhật gần đây nhất cho hình ảnh.
  • database là đối tượng XrTrackableImageDatabaseANDROID mà hình ảnh này được theo dõi.
  • databaseEntryIndex là chỉ mục ánh xạ vào mảng XrTrackableImageDatabaseCreateInfoANDROID :: entries của database .
  • centerPoseXrPosef của hình ảnh nằm trong XrTrackableGetInfoANDROID :: baseSpace . Hình ảnh nằm trong mặt phẳng XZ, trong đó X chỉ về bên phải của hình ảnh và Z chỉ về phía dưới cùng của hình ảnh.
  • extents là kích thước XrExtent2Df của hình ảnh. 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)

Xử lý lỗi

Ứng dụng phải thăm dò sự kiện XrEventDataImageTrackingLostANDROID bằng cách sử dụng xrPollEventkhông được bỏ qua sự kiện này.

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

typedef struct XrEventDataImageTrackingLostANDROID {
    XrStructureType    type;
    const void*        next;
    XrTime             time;
} XrEventDataImageTrackingLostANDROID;

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

  • typeXrStructureType của cấu trúc này.
  • nextNULL 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.
  • time XrTime

Việc nhận được sự kiện XrEventDataImageTrackingLostANDROID cho biết tính năng theo dõi hình ảnh đã gặp sự cố và lỗi nội bộ khiến các tài nguyên hiện có không hợp lệ. Ứng dụng phải hủy bỏ tất cả các handle XrTrackableImageDatabaseANDROID và tạo lại các handle đó nếu muốn tiếp tục theo dõi hình ảnh. Ứng dụng cũng phải hủy bỏ tất cả các handle XrTrackableTrackerANDROID liên quan đến tính năng theo dõi hình ảnh và tạo lại các handle đó nếu muốn tiếp tục theo dõi hình ảnh.

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

Mã ví dụ để lấy hình ảnh có thể theo dõi

Đoạn mã ví dụ sau đây minh hoạ cách lấy hình ảnh có thể theo dõi.

XrInstance instance;  // Previously initialized.
XrSession session;    // Previously initialized.
XrSystemId systemId;  // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID;                                        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // 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
XrSystemImageTrackingPropertiesANDROID imageProperty {
  .type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
    // image tracking is not supported.
    return;
}

uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
  {
    .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
    .next = nullptr,
    .trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
    .physicalWidth = 0.1f, // The width of the image in meters.
    .imageWidth = 640,
    .imageHeight = 480,
    .format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
    .bufferSize = imageBufferSize, // RGBA buffer size in bytes.
    .buffer = imageBuffer, // RGBA data.
  }
};

XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
  .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .entryCount = 1,
  .entries = imageDatabaseEntries
};

XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
  XrFuturePollInfoEXT pollInfo{
    .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
    .future = imageDatabaseFuture,
  };
  XrFuturePollResultEXT pollResult{
    .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
  };
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

  if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
    futureReady = true;
    keepLooping = false;
  } else {
    // Throttle the loop to not fully expend this CPU core.
    std::this_thread::yield();
  }
}

XrTrackableImageDatabaseANDROID imageDatabase;

if (futureReady) {
  XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
    .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
    .next = nullptr,
  };

  CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
  CHK_XR(imageDatabaseCompletion.futureResult);
  imageDatabase = imageDatabaseCompletion.database;
}

XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &imageDatabase
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.

// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

while (1) {
  uint32_t trackableCountOutput = 0;

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));

  std::vector<XrTrackableANDROID> allImageTrackables;
  allImageTrackables.resize(trackableCountOutput);

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));

  for (XrTrackableANDROID trackable : allImageTrackables) {
    XrTrackableGetInfoANDROID imageGetInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackable,
      .baseSpace = appSpace,
      .time = updateTime
    };

    XrTrackableImageANDROID trackableImage{
      .type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
    };
    CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));

    // Use XrTrackableImageANDROID data.
    (void)trackableImage.trackingState;
    (void)trackableImage.lastUpdatedTime;
    (void)trackableImage.centerPose;
    (void)trackableImage.extents;

    if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
      // Knowing which image the index of 0 maps to, use the specific image database
      // entry (e.g. rendering A for image A).
    }
    // indices 1+N comparisons for another specific image database entry.
  }

  // Throttle the loop to not fully expend this CPU core.
  std::this_thread::yield();
}

// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

Mã ví dụ để quản lý cơ sở dữ liệu hình ảnh trong thời gian chạy

Đoạn mã ví dụ sau đây minh hoạ cách sửa đổi tập hợp hình ảnh đang được theo dõi.

XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.

// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 2,
  .databases = imageDatabases
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.

CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.

CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.

CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.

// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &anotherImageDatabase
};

XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &anotherImageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));

// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.

Mã ví dụ để phản ứng với lỗi theo dõi hình ảnh

Đoạn mã ví dụ sau đây minh hoạ cách xử lý lỗi bằng cách thăm dò sự kiện XrEventDataImageTrackingLostANDROID.

XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.

// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
  .type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
      const XrEventDataImageTrackingLostANDROID& eventdata =
        *reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);

      // All existing databases and trackers need to be destroyed.
      CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
      CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

      // To resume image tracking, the database(s) and the tracker need to be re-created.

      XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
        .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
        .next = nullptr,
        .entryCount = 1,
        .entries = imageDatabaseEntries
      };

      XrFutureEXT imageDatabaseFuture;
      CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

      while (true) {
        XrFuturePollInfoEXT pollInfo{
          .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
          .future = imageDatabaseFuture,
        };
        XrFuturePollResultEXT pollResult{
          .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
        };
        CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

        if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
          break;
        } else {
          // Throttle the loop to not fully expend this CPU core.
          std::this_thread::yield();
        }
      }

      XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
        .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
        .next = nullptr,
      };

      CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
      CHK_XR(imageDatabaseCompletion.futureResult);
      imageDatabase = imageDatabaseCompletion.database;

      XrTrackableImageConfigurationANDROID imageConfig {
       .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
       .next = nullptr,
       .databaseCount = 1,
       .databases = &imageDatabase
      };

      XrTrackableTrackerCreateInfoANDROID createInfo {
        .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
        .next = &imageConfig,
        .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
      };

      XrTrackableTrackerANDROID imageTrackableTracker;
      CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

      break;
    }
  }
}

Các loại đối tượng mới

Lệnh mới

Cấu trúc mới

Enum mới

Hằng số Enum mới

  • XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAME
  • XR_ANDROID_trackables_image_SPEC_VERSION
  • Mở rộng XrObjectType :

    • XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
  • Mở rộng XrResult :

    • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • Mở rộng XrStructureType :

    • XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID
    • XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
  • Mở rộng XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_IMAGE_ANDROID

Vấn đề

Danh sách phiên bản

  • Bản sửa đổi 1, ngày 8 tháng 4 năm 2025 (Daniel Guttenberg)

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