XR_ANDROID_trackables_image
Name String
XR_ANDROID_trackables_image
Loại tiện ích
Phần mở rộng thực thể
Số máy lẻ đã đăng ký
710
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_EXT_future
và
XR_ANDROID_trackables
Ngày sửa đổi gần đây nhất
2025-04-08
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
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 chỉ định của các nhóm hình ảnh tham khảo đầu vào.
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 XrSystemImageTrackingPropertiesANDROID được định nghĩa 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ả về thành viên
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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. Để 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 ).supportsImageTrackinglà mộtXrBool32cho biết liệu hệ thống hiện tại có cung cấp tính năng theo dõi hình ảnh hay không.supportsPhysicalSizeEstimationlà mộtXrBool32cho 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.maxTrackedImageCountlà tổng số hình ảnh tối đa có thể được theo dõi cùng một lúc.maxLoadedImageCountlà tổng số hình ảnh tham khảo tối đa có thể được tải trên tất cả cơ sở dữ liệu.
Ứ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 cho việc tạo trình theo dõi hình ảnh khi và chỉ khi supportsImageTracking là XR_FALSE .
Nếu một môi trường thời gian chạy hỗ trợ tính năng theo dõi hình ảnh, thì môi trường đó 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 một môi trường thời gian chạy hỗ trợ tính năng theo dõi hình ảnh, thì môi trường đó phải hỗ trợ maxLoadedImageCount hình ảnh đã tải tại bất kỳ thời điểm nào.
Nếu một môi trường thời gian chạy hỗ trợ tính năng ướ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, nếu không thì XR_ERROR_VALIDATION_FAILURE sẽ được trả về.
Cách sử dụng hợp lệ (Ngầm ẩn)
- Bạn phải bật tiện ích
XR_ANDROID_trackables_imagetrước khi sử dụng XrSystemImageTrackingPropertiesANDROID -
typephải làXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID -
nextphải làNULLhoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
Tạo cơ sở dữ liệu
Ứng dụng có thể tạo một tay điều khiển XrTrackableImageDatabaseANDROID bằng cách tạo một hoặc nhiều cấu trúc XrTrackableImageDatabaseEntryANDROID rồi 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 tay điều khiển XrTrackableImageDatabaseANDROID.
XrTrackableImageDatabaseANDROID là một handle đại diện cho một tập hợp các hình ảnh tham khảo đã xử lý 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 định nghĩa 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ả về thành viên
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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.trackingModelà một XrTrackableImageTrackingModeANDROID cho biết chế độ theo dõi mong muốn.physicalWidthcho 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.imageWidthcho biết chiều rộng của hình ảnh tính bằng pixel.imageHeightcho biết chiều cao của hình ảnh tính bằng pixel.formatlà một XrTrackableImageFormatANDROID cho biết định dạng của dữ liệu hình ảnh trongbuffer.bufferSizecho biết độ dài byte củabuffer.bufferlà vùng đệmuint8_tchứa dữ liệu điểm ảnh của hình ảnh tham khảo. Nội dung củabufferphả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 :: supportsPhysicalSizeEstimation là XR_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 , imageHeight và format của mục nhập.
Cách sử dụng hợp lệ (Ngầm ẩn)
- Bạn phải bật tiện ích
XR_ANDROID_trackables_imagetrước khi sử dụng XrTrackableImageDatabaseEntryANDROID -
typephải làXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID -
nextphải làNULLhoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc -
trackingModephải là một giá trị XrTrackableImageTrackingModeANDROID hợp lệ -
formatphải là một giá trị XrTrackableImageFormatANDROID hợp lệ -
bufferphải là con trỏ trỏ đến một mảng gồmbufferSizegiá trịuint8_t - Tham số
bufferSizephải lớn hơn0
Cấu trúc XrTrackableImageDatabaseCreateInfoANDROID được định nghĩa như sau:
typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
XrStructureType type;
const void* next;
uint32_t entryCount;
const XrTrackableImageDatabaseEntryANDROID* entries;
} XrTrackableImageDatabaseCreateInfoANDROID;
Nội dung mô tả về thành viên
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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.entryCountlà mộtuint32_tchỉ định số lượng phần tử trong mảngentries.entrieslà một mảng gồm các cấu trúc XrTrackableImageDatabaseEntryANDROID.
Cách sử dụng hợp lệ (Ngầm ẩn)
- Bạn phải bật tiện ích
XR_ANDROID_trackables_imagetrước khi sử dụng XrTrackableImageDatabaseCreateInfoANDROID -
typephải làXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID -
nextphải làNULLhoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc -
entriesphải là một con trỏ đến một mảng gồmentryCountcấu trúc XrTrackableImageDatabaseEntryANDROID hợp lệ - Tham số
entryCountphải lớn hơn0
Cấu trúc XrCreateTrackableImageDatabaseCompletionANDROID được định nghĩa như sau:
typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrTrackableImageDatabaseANDROID database;
} XrCreateTrackableImageDatabaseCompletionANDROID;
Nội dung mô tả về thành viên
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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.futureResultlà XrResult của thao tác không đồng bộ.databaselà tên người dùng XrTrackableImageDatabaseANDROID đã tạo.
Mã trả về trong tương lai
Giá trị futureResult:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
Cách sử dụng hợp lệ (Ngầm ẩn)
- Bạn phải bật tiện ích
XR_ANDROID_trackables_imagetrước khi sử dụng XrCreateTrackableImageDatabaseCompletionANDROID -
typephải làXR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID -
nextphải làNULLhoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc -
futureResultphải là một giá trị XrResult hợp lệ -
databasephải là một tên người dùng XrTrackableImageDatabaseANDROID hợp lệ
Hàm xrCreateTrackableImageDatabaseAsyncANDROID được định nghĩa như sau:
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
Nội dung mô tả về tham số
sessionlà một tay điều khiển cho XrSession đã tạo trước đó bằng xrCreateSession .createInfolà con trỏ đến cấu trúc XrTrackableImageDatabaseCreateInfoANDROID.futurelà con trỏ đếnXrFutureEXTđã tạo.
Cách sử dụng hợp lệ (Ngầm ẩn)
- Bạn phải bật tiện ích
XR_ANDROID_trackables_imagetrước khi gọi xrCreateTrackableImageDatabaseAsyncANDROID -
sessionphải là một tên người dùng XrSession hợp lệ -
createInfophải là một con trỏ đến cấu trúc XrTrackableImageDatabaseCreateInfoANDROID hợp lệ -
futurephải là một con trỏ đến giá trịXrFutureEXT
Mã trả về
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Hàm xrCreateTrackableImageDatabaseCompleteANDROID được định nghĩa như sau:
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
Nội dung mô tả về tham số
sessionlà một tay điều khiển cho XrSession đã tạo trước đó bằng xrCreateSession .futurelàXrFutureEXTcủa tương lai cần hoàn thành.completionlà con trỏ đến cấu trúc XrCreateTrackableImageDatabaseCompletionANDROID chứa kết quả của thao tác.
Cách sử dụng hợp lệ (Ngầm ẩn)
- Tiện ích
XR_ANDROID_trackables_imagephải được bật trước khi gọi xrCreateTrackableImageDatabaseCompleteANDROID -
sessionphải là một tên người dùng XrSession hợp lệ -
completionphải là con trỏ đến cấu trúc XrCreateTrackableImageDatabaseCompletionANDROID
Mã trả về
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Hàm xrDestroyTrackableImageDatabaseANDROID được định nghĩa như sau:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
Nội dung mô tả về tham số
databaselà tên người dùng XrTrackableImageDatabaseANDROID cần huỷ.
Cách sử dụng hợp lệ (Ngầm ẩn)
- Tiện ích
XR_ANDROID_trackables_imagephải được bật trước khi gọi xrDestroyTrackableImageDatabaseANDROID -
databasephải là một tên người dùng XrTrackableImageDatabaseANDROID hợp lệ
Độ an toàn cho chuỗi
- Quyền truy cập vào
databasevà mọi tay điều khiển con phải được đồng bộ hoá bên ngoài
Mã trả về
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
Hình ảnh theo dõi
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 :: trackableType là XR_TRACKABLE_TYPE_IMAGE_ANDROID và XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking trả về XR_FALSE thông qua xrGetSystemProperties .
Cấu trúc XrTrackableImageConfigurationANDROID được định nghĩa như sau:
typedef struct XrTrackableImageConfigurationANDROID {
XrStructureType type;
const void* next;
uint32_t databaseCount;
const XrTrackableImageDatabaseANDROID* databases;
} XrTrackableImageConfigurationANDROID;
Nội dung mô tả về thành viên
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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.databaseCountlà mộtuint32_tchỉ định số lượng phần tử trongdatabasesdatabaseslà một mảng XrTrackableImageDatabaseANDROID chỉ định cơ sở dữ liệu để tạo trình theo dõi.
Ứng dụng phải đặ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.
Cách sử dụng hợp lệ (Ngầm ẩn)
- Bạn phải bật tiện ích
XR_ANDROID_trackables_imagetrước khi sử dụng XrTrackableImageConfigurationANDROID -
typephải làXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID -
nextphải làNULLhoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc -
databasesphải là một con trỏ đến một mảng gồmdatabaseCounttay điều khiển XrTrackableImageDatabaseANDROID hợp lệ - Tham số
databaseCountphải lớn hơn0
Enum XrTrackableImageTrackingModeANDROID mô tả các chế độ theo dõi hình ảnh được hỗ trợ.
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ề giá trị 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 năng 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 giúp giảm mức tiêu thụ điện năng 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.
Enum XrTrackableImageFormatANDROID mô tả các định dạng hình ảnh được hỗ trợ.
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ề giá trị 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 định nghĩa như sau:
XrResult xrAddTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Nội dung mô tả về tham số
trackerlà tay điều khiển XrTrackableTrackerANDROID để thêmdatabasevào.databaselà tên người dùng XrTrackableImageDatabaseANDROID để thêm vàotracker.
Khi thêm XrTrackableImageDatabaseANDROID vào trình theo dõi, bạn phải xem xét các hình ảnh tham khảo của cơ sở dữ liệu đó để 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.
Cách sử dụng hợp lệ (Ngầm ẩn)
- Bạn phải bật tiện ích
XR_ANDROID_trackables_imagetrước khi gọi xrAddTrackableImageDatabaseANDROID -
trackerphải là một tay điều khiển XrTrackableTrackerANDROID hợp lệ -
databasephải là một tên người dùng XrTrackableImageDatabaseANDROID hợp lệ - Cả
databasevàtrackerđều phải được tạo, phân bổ hoặc truy xuất từ cùng một XrSession
Mã trả về
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Hàm xrRemoveTrackableImageDatabaseANDROID được định nghĩa như sau:
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Nội dung mô tả về tham số
trackerlà tên người dùng XrTrackableTrackerANDROID để xoádatabase.databaselà tên người dùng XrTrackableImageDatabaseANDROID cần xoá khỏitracker.
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 hoạt động trong cơ sở dữ liệu đó nữa. Tay điều khiển XrTrackableImageDatabaseANDROID đã xoá không được bị huỷ ngầm trong thao tác này.
Cách sử dụng hợp lệ (Ngầm ẩn)
- Bạn phải bật tiện ích
XR_ANDROID_trackables_imagetrước khi gọi xrRemoveTrackableImageDatabaseANDROID -
trackerphải là một tên người dùng XrTrackableTrackerANDROID hợp lệ -
databasephải là một tên người dùng XrTrackableImageDatabaseANDROID hợp lệ - Cả
databasevàtrackerđều phải được tạo, phân bổ hoặc truy xuất từ cùng một XrSession
Mã trả về
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Đang tải hình ảnh
Hàm xrGetTrackableImageANDROID được định nghĩa như sau:
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
Nội dung mô tả về tham số
trackerlà XrTrackableTrackerANDROID cần truy vấn.getInfolà XrTrackableGetInfoANDROID có thông tin dùng để lấy mã QR có thể theo dõi.trackablelà con trỏ đến cấu trúc XrTrackableImageANDROID mà hình ảnh 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_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 .
Cách sử dụng hợp lệ (Ngầm ẩn)
- Tiện ích
XR_ANDROID_trackables_imagephải được bật trước khi gọi xrGetTrackableImageANDROID -
trackerphải là một tên người dùng XrTrackableTrackerANDROID hợp lệ -
getInfophải là một con trỏ đến cấu trúc XrTrackableGetInfoANDROID hợp lệ -
trackablephải là con trỏ đến cấu trúc XrTrackableImageANDROID
Mã trả về
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_ERROR_VALIDATION_FAILURE
Cấu trúc XrTrackableImageANDROID được định nghĩa 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ả về thành viên
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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.trackingStatelà XrTrackingStateANDROID của hình ảnh.lastUpdatedTimelàXrTimecủa lần cập nhật hình ảnh gần đây nhất.databaselà tên người dùng XrTrackableImageDatabaseANDROID mà hình ảnh này được theo dõi.databaseEntryIndexlà chỉ mục liên kết với mảngdatabasecủa XrTrackableImageDatabaseCreateInfoANDROID ::entries.centerPoselà XrPosef của hình ảnh nằm trong XrTrackableGetInfoANDROID ::baseSpace. Hình ảnh nằm trong mặt phẳng XZ với X hướng về bên phải của hình ảnh và Z hướng về phía dưới cùng của hình ảnh.extentslà kích thước XrExtent2Df của hình ảnh. Ranh giới của hộp bao quanh nằm ở các điểm:centerPose+/- (extents/ 2).
Cách sử dụng hợp lệ (Ngầm ẩn)
- Bạn phải bật tiện ích
XR_ANDROID_trackables_imagetrước khi sử dụng XrTrackableImageANDROID -
typephải làXR_TYPE_TRACKABLE_IMAGE_ANDROID -
nextphải làNULLhoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc -
trackingStatephải là một giá trị XrTrackingStateANDROID hợp lệ -
databasephải là một tên người dùng XrTrackableImageDatabaseANDROID hợp lệ
Xử lý lỗi
Ứng dụng phải thăm dò sự kiện XrEventDataImageTrackingLostANDROID bằng xrPollEvent và không được bỏ qua sự kiện đó.
Cấu trúc XrEventDataImageTrackingLostANDROID được định nghĩa như sau:
typedef struct XrEventDataImageTrackingLostANDROID {
XrStructureType type;
const void* next;
XrTime time;
} XrEventDataImageTrackingLostANDROID;
Nội dung mô tả về thành viên
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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.timeXrTime
Việc nhận được sự kiện XrEventDataImageTrackingLostANDROID cho biết rằng tính năng theo dõi hình ảnh đã gặp 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 huỷ tất cả các tay điều khiển XrTrackableImageDatabaseANDROID và tạo lại các tay điều khiển đó nếu muốn tiếp tục theo dõi hình ảnh. Ứng dụng cũng phải huỷ tất cả các tay điều khiển XrTrackableTrackerANDROID liên quan đến tính năng theo dõi hình ảnh và tạo lại các tay điều khiển đó nếu muốn tiếp tục theo dõi hình ảnh.
Cách sử dụng hợp lệ (Ngầm ẩn)
- Tiện ích
XR_ANDROID_trackables_imagephải được bật trước khi sử dụng XrEventDataImageTrackingLostANDROID -
typephải làXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID -
nextphải làNULLhoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
Mã ví dụ để lấy hình ảnh có thể theo dõi
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
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
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
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
Cấu trúc mới
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
Mở rộng XrSystemProperties :
Enum mới
Hằng số enum mới
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_ANDROID_trackables_image_SPEC_VERSIONMở 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_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_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 về tiện ích.