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
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ó 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
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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 ).supportsImageTrackinglà mộtXrBool32cho 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.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 mà bạn có thể theo dõi cùng lúc.maxLoadedImageCountlà 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 supportsImageTracking là XR_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)
- 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 đố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
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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.trackingModelà XrTrackableImageTrackingModeANDROID cho biết chế độ mong muốn để theo dõi.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 .
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ỏ đến một mảng gồm các giá trịbufferSizeuint8_t - Tham số
bufferSizephải lớn hơn0
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
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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.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.
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à 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 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
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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.futureResultlà XrResult của thao tác không đồng bộ.databaselà đối tượ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
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à giá trị XrResult hợp lệ -
databasephải là một đối tượng XrTrackableImageDatabaseANDROID hợp lệ
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ố
sessionlà một đối tượng xử lý cho XrSession được tạo trước đó bằng xrCreateSession .createInfolà một con trỏ đến cấu trúc XrTrackableImageDatabaseCreateInfoANDROID.futurelà một con trỏ đếnXrFutureEXTđã tạo .
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 xrCreateTrackableImageDatabaseAsyncANDROID -
sessionphải là một đối tượng XrSession hợp lệ -
createInfophải là con trỏ đến một cấu trúc XrTrackableImageDatabaseCreateInfoANDROID hợp lệ -
futurephải là 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 xác định như sau:
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
Nội dung mô tả về tham số
sessionlà một đối tượng xử lý cho XrSession được tạo trước đó bằng xrCreateSession .futurelàXrFutureEXTcủa tương lai cần hoàn thành.completionlà con trỏ đến một cấu trúc XrCreateTrackableImageDatabaseCompletionANDROID chứa kết quả của thao tác.
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 xrCreateTrackableImageDatabaseCompleteANDROID -
sessionphải là một đối tượ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 xác định như sau:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
Nội dung mô tả về tham số
databaselà handle XrTrackableImageDatabaseANDROID cần hủy bỏ.
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 đối tượng XrTrackableImageDatabaseANDROID hợp lệ
Độ an toàn cho luồng
- Quyền truy cập vào
databasevà mọi đối tượng 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
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 :: trackableType là XR_TRACKABLE_TYPE_IMAGE_ANDROID và XrSystemImageTrackingPropertiesANDROID :: 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
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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.databaseCountlà mộtuint32_tchỉ định số lượng phần tử trongdatabasesdatabaseslà 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)
- 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à con trỏ đến một mảng gồmdatabaseCountgiá trị nhận dạng XrTrackableImageDatabaseANDROID hợp lệ - Tham số
databaseCountphải lớn hơn0
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ố
trackerlà đối tượng XrTrackableTrackerANDROID để thêmdatabasevào.databaselà đối tượng XrTrackableImageDatabaseANDROID cần thêm vàotracker.
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)
- Tiện ích
XR_ANDROID_trackables_imagephải được bật trước khi gọi xrAddTrackableImageDatabaseANDROID -
trackerphải là một đối tượng XrTrackableTrackerANDROID hợp lệ -
databasephải là một đối tượng XrTrackableImageDatabaseANDROID hợp lệ - Cả
databasevàtrackerphả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 xác định như sau:
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Nội dung mô tả về tham số
trackerlà đối tượng XrTrackableTrackerANDROID để xoádatabase.databaselà đối tượ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 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)
- Bạn phải bật tiện ích
XR_ANDROID_trackables_imagetrước khi gọi xrRemoveTrackableImageDatabaseANDROID -
trackerphải là một đối tượng XrTrackableTrackerANDROID hợp lệ -
databasephải là một đối tượng XrTrackableImageDatabaseANDROID hợp lệ - Cả
databasevàtrackerphả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
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ố
trackerlà XrTrackableTrackerANDROID để truy vấn.getInfolà XrTrackableGetInfoANDROID có thông tin dùng để lấy mã QR có thể theo dõi.trackablelà một con trỏ đến cấu trúc XrTrackableImageANDROID, trong đó 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 .
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 đối tượng XrTrackableTrackerANDROID hợp lệ -
getInfophải là con trỏ đến một 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 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
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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.trackingStatelà XrTrackingStateANDROID của hình ảnh.lastUpdatedTimelàXrTimecủa lần cập nhật gần đây nhất cho hình ảnh.databaselà đối tượng XrTrackableImageDatabaseANDROID mà hình ảnh này được theo dõi.databaseEntryIndexlà chỉ mục ánh xạ vào mảng XrTrackableImageDatabaseCreateInfoANDROID ::entriescủadatabase.centerPoselà XrPosef 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.extentslà 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)
- Tiện ích
XR_ANDROID_trackables_imagephải được bật trướ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 đối tượng XrTrackableImageDatabaseANDROID hợp lệ
Xử lý lỗi
Ứng dụng phải thăm dò sự kiện XrEventDataImageTrackingLostANDROID bằng cách sử dụng xrPollEvent và khô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
typelà XrStructureType của cấu trúc này.nextlàNULLhoặ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.timeXrTime
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)
- Bạn phải bật tiện ích
XR_ANDROID_trackables_imagetrướ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
Đ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
- 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 của tiện ích.