XR_EXT_spatial_image_tracking

Name String

XR_EXT_spatial_image_tracking

Loại tiện ích

Phần mở rộng thực thể

Số máy lẻ đã đăng ký

783

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_spatial_entity

Cộng tác viên

Daniel Guttenberg, Qualcomm
Nihav Jain, Google
Jared Finder, Google
Zhipeng Liu, ByteDance

Tổng quan

Tiện ích này cung cấp khả năng theo dõi hình ảnh cho tiện ích XR_EXT_spatial_entity. Tính năng này cho phép các ứng dụng phát hiện và theo dõi hình ảnh phẳng cụ thể theo chỉ định của các nhóm hình ảnh tham khảo đầu vào.

Hình ảnh được theo dõi được biểu thị dưới dạng một thực thể không gian có (hoặc "có") các thành phần sau:

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Các ứng dụng thường sử dụng tiện ích theo dõi hình ảnh không gian theo mẫu sau:

  • Trước tiên, ứng dụng sẽ tạo một hoặc nhiều handle XrSpatialImageTrackingDatabaseEXT dựa trên các tập dữ liệu hình ảnh tham khảo được tải trước.
  • Sau đó, ứng dụng sẽ tạo một tay điều khiển XrSpatialContextEXT dựa trên các tay điều khiển XrSpatialImageTrackingDatabaseEXT đã tạo trước đó.
  • Sau đó, ứng dụng sẽ giải phóng dữ liệu hình ảnh tham khảo để giảm mức sử dụng bộ nhớ.
  • Ứng dụng khám phá và truy vấn hình ảnh theo các mẫu truy cập thực thể không gian.
  • Ứng dụng có thể tải thêm các nhóm hình ảnh tham khảo và tạo thêm XrSpatialImageTrackingDatabaseEXT, sau đó tạo XrSpatialContextEXT từ các nhóm đó để mở rộng nhóm hình ảnh có thể phát hiện và theo dõi một cách linh động trong thời gian chạy.
  • Ứng dụng có thể huỷ các tay điều khiển XrSpatialImageTrackingDatabaseEXT để giảm tập hợp hình ảnh có thể phát hiện và theo dõi một cách linh động trong thời gian chạy.
  • Ứng dụng có thể huỷ các tay điều khiển XrSpatialContextEXT để giảm tập hợp hình ảnh có thể phát hiện và theo dõi một cách linh động trong thời gian chạy.

Hỗ trợ thời gian chạy

Thời gian chạy phải quảng cáo khả năng hỗ trợ tính năng theo dõi hình ảnh bằng xrEnumerateSpatialCapabilitiesEXT bằng cách liệt kê khả năng sau:

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Cấu hình

Để bật tính năng phát hiện và theo dõi hình ảnh phẳng, ứng dụng có thể truyền cấu trúc XrSpatialCapabilityConfigurationImageTrackingEXT trong XrSpatialContextCreateInfoEXT :: capabilityConfigs khi gọi hàm xrCreateSpatialContextAsyncEXT và truyền mảng cấu trúc< XrSpatialImageTrackingDatabaseEXT trong mỗi XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases .

Tạo nhóm hình ảnh đầu vào

Để chỉ định hình ảnh tham khảo cần phát hiện và theo dõi, ứng dụng phải tạo ít nhất một nhóm hình ảnh tham khảo đầu vào. Một tập hợp hình ảnh tham khảo đầu vào được biểu thị bằng một handle XrSpatialImageTrackingDatabaseEXT và chứa ít nhất một hình ảnh.

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

Phần điều khiển XrSpatialImageTrackingDatabaseEXT đại diện cho các tài nguyên để khám phá và cập nhật một số hình ảnh không gian trong môi trường của người dùng. Ứng dụng có thể sử dụng tên người dùng này để khám phá và cập nhật hình ảnh không gian bằng các hàm khác trong tiện ích này.

Tạo cơ sở dữ liệu theo dõi hình ảnh không gian

Hàm xrCreateSpatialImageTrackingDatabaseAsyncEXT được định nghĩa như sau:

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

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

  • session là một XrSession, trong đó cơ sở dữ liệu theo dõi hình ảnh không gian sẽ hoạt động.
  • createInfo là XrSpatialImageTrackingDatabaseCreateInfoEXT dùng để chỉ định các tham số cơ sở dữ liệu theo dõi hình ảnh không gian.
  • future là con trỏ đến XrFutureEXT .

Ứng dụng có thể tạo một handle XrSpatialImageTrackingDatabaseEXT bằng hàm xrCreateSpatialImageTrackingDatabaseAsyncEXT và định cấu hình các nhóm hình ảnh tham khảo đầu vào của cơ sở dữ liệu theo dõi hình ảnh bằng createInfo .

Thời gian chạy phải trả về XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT nếu XrSpatialReferenceImageEXT :: format của bất kỳ hình ảnh tham khảo đầu vào nào không được liệt kê bằng xrEnumerateSpatialReferenceImageFormatsEXT .

Thời gian chạy phải trả về XR_ERROR_SPATIAL_IMAGE_INVALID_EXT nếu không thể đánh giá mảng XrSpatialReferenceImageEXT :: planes của bất kỳ hình ảnh tham khảo đầu vào nào theo siêu dữ liệu hình ảnh tham khảo của XrSpatialReferenceImageEXT .

Thời gian chạy phải trả về XR_ERROR_SPATIAL_IMAGE_INVALID_EXT nếu mảng XrSpatialReferenceImageEXT :: planes của bất kỳ hình ảnh tham khảo đầu vào nào không cung cấp chính xác số lượng mặt phẳng như XrSpatialReferenceImageEXT :: format có các kênh màu.

Nếu một môi trường thời gian chạy thực thi hệ thống cấp quyền để kiểm soát quyền truy cập của ứng dụng vào chức năng theo dõi hình ảnh, thì môi trường thời gian chạy đó phải trả về XR_ERROR_PERMISSION_INSUFFICIENT nếu ứng dụng này chưa được cấp các quyền đó.

Hàm này bắt đầu một thao tác không đồng bộ và tạo một XrFutureEXT tương ứng, có thể sử dụng với xrPollFutureEXT và các hàm liên quan. Giá trị trả về của hàm này chỉ cho biết liệu các tham số có được chấp nhận để lên lịch cho hoạt động không đồng bộ hay không. Hàm hoàn thành tương ứng là xrCreateSpatialImageTrackingDatabaseCompleteEXT , có thể sử dụng khi một tương lai từ hàm này ở trạng thái READY, với kết quả được hàm đó điền sẵn trong cấu trúc hoàn thành XrCreateSpatialImageTrackingDatabaseCompletionEXT .

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

Cấu trúc XrSpatialImageTrackingDatabaseCreateInfoEXT được định nghĩa như sau:

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • spatialReferenceImageCount là số phần tử trong mảng spatialReferenceImages.
  • spatialReferenceImages là một mảng của XrSpatialReferenceImageEXT .

Cấu trúc XrSpatialImageTrackingDatabaseCreateInfoEXT mô tả thông tin để tạo một tay điều khiển XrSpatialImageTrackingDatabaseEXT.

Mỗi XrSpatialImageTrackingDatabaseEXT phải được tạo bằng ít nhất một XrSpatialReferenceImageEXT trong mảng XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

Cách sử dụng hợp lệ (Ngầm ẩn)

Hàm xrCreateSpatialImageTrackingDatabaseCompleteEXT được định nghĩa như sau:

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

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

xrCreateSpatialImageTrackingDatabaseCompleteEXT hoàn tất thao tác không đồng bộ do xrCreateSpatialImageTrackingDatabaseAsyncEXT bắt đầu.

Môi trường thời gian chạy không được truy cập vào bất kỳ con trỏ XrSpatialReferenceImagePlaneEXT :: buffer nào do mảng đầu vào XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages cung cấp cho lệnh gọi xrCreateSpatialImageTrackingDatabaseAsyncEXT này sau khi lệnh gọi hoàn tất. Ứng dụng có thể giải phóng mọi dữ liệu XrSpatialReferenceImagePlaneEXT :: buffer sau khi hoàn tất xrCreateSpatialImageTrackingDatabaseAsyncEXT để giảm mức sử dụng bộ nhớ.

Thời gian chạy phải trả về XR_ERROR_FUTURE_PENDING_EXT nếu future không ở trạng thái sẵn sàng. Thời gian chạy phải trả về XR_ERROR_FUTURE_INVALID_EXT nếu future đã hoàn tất hoặc bị huỷ.

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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

Cấu trúc XrCreateSpatialImageTrackingDatabaseCompletionEXT được định nghĩa như sau:

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

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

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

Giá trị futureResult:

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

Nếu futureResult là mã thành công, thì database phải là một tay điều khiển hợp lệ. Nếu database hợp lệ, thì giá trị này chỉ hợp lệ trong vòng đời của xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session hoặc cho đến khi ứng dụng huỷ database bằng xrDestroySpatialImageTrackingDatabaseEXT , tuỳ theo điều kiện nào xảy ra trước.

Cách sử dụng hợp lệ (Ngầm ẩn)

Huỷ Cơ sở dữ liệu theo dõi hình ảnh không gian

Hàm xrDestroySpatialImageTrackingDatabaseEXT được định nghĩa như sau:

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

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

Ứng dụng có thể gọi hàm xrDestroySpatialImageTrackingDatabaseEXT để giải phóng tay điều khiển database và các tài nguyên cơ bản khi hoàn tất các nhiệm vụ khám phá và cập nhật hình ảnh không gian.

Ứng dụng có thể gọi hàm xrDestroySpatialImageTrackingDatabaseEXT trước khi gọi xrDestroySpatialContextEXT . Thời gian chạy không được báo cáo hình ảnh do XrSpatialImageTrackingDatabaseEXT đã bị huỷ này quản lý nữa. Thời gian chạy phải tiếp tục báo cáo hình ảnh do các cơ sở dữ liệu khác quản lý.

Thời gian chạy phải đảm bảo rằng ảnh chụp nhanh khám phá do xrCreateSpatialDiscoverySnapshotCompleteEXT trả về không chứa hình ảnh liên quan đến các tay điều khiển XrSpatialImageTrackingDatabaseEXT đã bị huỷ hoặc không hợp lệ, ngay cả khi tay điều khiển đó bị huỷ sau khi ứng dụng gọi xrCreateSpatialDiscoverySnapshotAsyncEXT . Vì dữ liệu trong ảnh chụp nhanh không gian là không thể thay đổi, nên ứng dụng phải huỷ mọi tay điều khiển XrSpatialSnapshotEXT được tạo trước khi huỷ database , nếu không, ứng dụng có thể nhận được tay điều khiển XrSpatialImageTrackingDatabaseEXT không hợp lệ khi sử dụng xrQuerySpatialComponentDataEXT .

Ứng dụng có thể gọi hàm xrDestroySpatialContextEXT để giải phóng tay điều khiển XrSpatialContextEXT trước khi huỷ bất kỳ tay điều khiển XrSpatialImageTrackingDatabaseEXT nào mà XrSpatialContextEXT được tạo bằng. Thời gian chạy không được ngầm huỷ các tay điều khiển XrSpatialImageTrackingDatabaseEXT này khi XrSpatialContextEXT bị huỷ.

Việc quản lý vòng đời của XrSpatialContextEXT và XrSpatialImageTrackingDatabaseEXT một cách độc lập cho phép các ứng dụng sử dụng lại các tay điều khiển XrSpatialImageTrackingDatabaseEXT đã tạo trước đó mà không cần thực hiện lại quy trình tạo tốn kém.

Ví dụ: việc huỷ một XrSpatialContextEXT rồi sau đó tạo lại một XrSpatialContextEXT khác có cùng XrSpatialImageTrackingDatabaseEXT sẽ cho phép tạm dừng và tiếp tục theo dõi hình ảnh mà không cần thực hiện một quy trình khởi chạy khác.

Cách sử dụng hợp lệ (Ngầm ẩn)

Độ an toàn cho chuỗi

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

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Hỗ trợ định dạng hình ảnh đầu vào

Ứng dụng nên gọi xrEnumerateSpatialReferenceImageFormatsEXT để lấy danh sách các định dạng hình ảnh tham khảo đầu vào được hỗ trợ.

Hàm xrEnumerateSpatialReferenceImageFormatsEXT được định nghĩa như sau:

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

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

  • instance là một tay điều khiển cho XrInstance .
  • systemId là XrSystemId có định dạng hình ảnh tham khảo đầu vào sẽ được liệt kê.
  • capability là XrSpatialCapabilityEXT mà các định dạng hình ảnh tham khảo đầu vào sẽ được liệt kê.
  • formatCapacityInput là dung lượng của mảng formats hoặc 0 để cho biết yêu cầu truy xuất dung lượng cần thiết.
  • formatCountOutput là số lượng định dạng hoặc dung lượng cần thiết trong trường hợp formatCapacityInput không đủ.
  • formats là một mảng XrSpatialReferenceImageFormatEXT . Giá trị này có thể là NULL nếu formatCapacityInput là 0.
  • Hãy xem phần Tham số dung lượng bộ nhớ đệm để biết nội dung mô tả chi tiết về cách truy xuất kích thước formats cần thiết.

Ứng dụng có thể liệt kê danh sách các định dạng hình ảnh tham khảo đầu vào được một XrSystemId nhất định hỗ trợ cho một XrSpatialCapabilityEXT nhất định bằng cách sử dụng xrEnumerateSpatialReferenceImageFormatsEXT .

Thời gian chạy không được liệt kê các định dạng của tiện ích không được bật cho instance .

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Hãy xem XrSpatialReferenceImageFormatEXT để biết danh sách đầy đủ tất cả định dạng hình ảnh tham khảo được bất kỳ tiện ích nào hỗ trợ.

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

Phép liệt kê XrSpatialReferenceImageFormatEXT xác định các định dạng hình ảnh tham khảo đầu vào mà thời gian chạy có thể hỗ trợ.

Phải hỗ trợ ít nhất giá trị XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT và giá trị XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT.

Các giá trị liệt kê có ý nghĩa như sau:

Nội dung mô tả về giá trị liệt kê

  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT — Bộ đệm RGBA. Định dạng này không đảm bảo về bố cục của dữ liệu pixel trong bộ nhớ. Bạn phải truy cập vào các pixel bằng siêu dữ liệu do cấu trúc XrSpatialReferenceImagePlaneEXT tương ứng cung cấp. Mỗi kênh màu pixel có kích thước 8 bit, khiến mỗi pixel có kích thước 32 bit.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT — Bộ đệm RGB. Định dạng này không đảm bảo về bố cục của dữ liệu pixel trong bộ nhớ. Bạn phải truy cập vào các pixel bằng siêu dữ liệu do cấu trúc XrSpatialReferenceImagePlaneEXT tương ứng cung cấp. Mỗi kênh màu pixel có kích thước 8 bit, khiến mỗi pixel có kích thước 24 bit.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT — Bộ đệm YUV là mẫu phụ sắc độ 4:2:0. Định dạng này không đảm bảo về bố cục của dữ liệu pixel trong bộ nhớ. Bạn phải truy cập vào các pixel bằng siêu dữ liệu do cấu trúc XrSpatialReferenceImagePlaneEXT tương ứng cung cấp. Mỗi kênh màu pixel RGB được giải mã có kích thước 8 bit, khiến mỗi pixel có kích thước 24 bit.

Cài đặt theo dõi hình ảnh không gian

Tiện ích này cung cấp các cấu trúc không bắt buộc mà ứng dụng có thể dùng để định cấu hình chức năng theo dõi hình ảnh.

Tối ưu hoá hình ảnh tĩnh

Cấu trúc XrSpatialImageStaticOptimizationEXT được định nghĩa như sau:

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • optimizeForStaticImage là một XrBool32 cho biết hình ảnh có di chuyển hay không. Giá trị XR_TRUE cho biết hình ảnh không di chuyển.

Nếu XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT được liệt kê bằng xrEnumerateSpatialCapabilityFeaturesEXT cho chức năng XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, thì ứng dụng có thể liên kết XrSpatialImageStaticOptimizationEXT với chuỗi XrSpatialImageTrackingDatabaseCreateInfoEXT :: next hoặc XrSpatialReferenceImageEXT :: next .

Nếu ứng dụng liên kết XrSpatialImageStaticOptimizationEXT với cấu trúc XrSpatialImageTrackingDatabaseCreateInfoEXT, thì thời gian chạy phải giả định rằng tất cả hình ảnh của XrSpatialImageTrackingDatabaseEXT đó đều là hình ảnh tĩnh nếu optimizeForStaticImage được đặt thành XR_TRUE . Tương ứng, thời gian chạy phải giả định rằng tất cả hình ảnh của XrSpatialImageTrackingDatabaseEXT đó không phải là hình ảnh tĩnh nếu optimizeForStaticImage được đặt thành XR_FALSE .

Nếu ứng dụng liên kết XrSpatialImageStaticOptimizationEXT với cấu trúc XrSpatialReferenceImageEXT, thì thời gian chạy phải giả định rằng hình ảnh tham khảo này là tĩnh nếu optimizeForStaticImage được đặt thành XR_TRUE . Tương ứng, thời gian chạy phải giả định rằng hình ảnh tham khảo này không tĩnh nếu optimizeForStaticImage được đặt thành XR_FALSE . Việc liên kết cấu trúc XrSpatialImageStaticOptimizationEXT với cấu trúc XrSpatialReferenceImageEXT sẽ được ưu tiên hơn so với việc liên kết cấu trúc đó với cấu trúc XrSpatialImageTrackingDatabaseCreateInfoEXT.

Nếu XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT không được xrEnumerateSpatialCapabilityFeaturesEXT liệt kê cho chức năng XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT và ứng dụng liên kết cấu trúc XrSpatialImageStaticOptimizationEXT với bất kỳ chuỗi tiếp theo nào có thể áp dụng, thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Điều này có thể cho phép thời gian chạy tạo ra tư thế và kích thước chính xác hơn.

Việc này có thể cho phép thời gian chạy giảm mức tiêu thụ điện năng.

Cách sử dụng hợp lệ (Ngầm ẩn)

Chiều rộng hình ảnh tham khảo

Cấu trúc XrSpatialImageSizeEXT được định nghĩa như sau:

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • physicalWidth là giá trị float thể hiện chiều rộng thực tế tính bằng mét cần đặt.

Nếu XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT được liệt kê bằng xrEnumerateSpatialCapabilityFeaturesEXT cho chức năng XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, thì ứng dụng có thể liên kết XrSpatialImageSizeEXT với XrSpatialImageTrackingDatabaseCreateInfoEXT :: next hoặc XrSpatialReferenceImageEXT :: next .

Nếu ứng dụng liên kết XrSpatialImageSizeEXT với cấu trúc XrSpatialImageTrackingDatabaseCreateInfoEXT, thì thời gian chạy phải giả định rằng tất cả hình ảnh của XrSpatialImageTrackingDatabaseEXT đó đều có chiều rộng là physicalWidth mét và chiều cao theo tỷ lệ khung hình được cung cấp ngầm thông qua XrSpatialReferenceImageEXT :: width và XrSpatialReferenceImageEXT :: height .

Nếu ứng dụng liên kết XrSpatialImageSizeEXT với cấu trúc XrSpatialReferenceImageEXT, thì thời gian chạy phải giả định rằng hình ảnh tham khảo này có chiều rộng là physicalWidth mét và chiều cao theo tỷ lệ khung hình được cung cấp ngầm định thông qua XrSpatialReferenceImageEXT :: width và XrSpatialReferenceImageEXT :: height . Việc liên kết cấu trúc XrSpatialImageSizeEXT với cấu trúc XrSpatialReferenceImageEXT được ưu tiên hơn so với việc liên kết cấu trúc đó với cấu trúc XrSpatialImageTrackingDatabaseCreateInfoEXT.

Việc này có thể cho phép thời gian chạy trả về tư thế và kích thước chính xác hơn.

Thời gian chạy phải liệt kê XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT hoặc XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT hoặc cả hai.

Nếu XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT được liệt kê theo xrEnumerateSpatialCapabilityFeaturesEXT, thì thời gian chạy phải tự động cung cấp kích thước hình ảnh cho những hình ảnh mà ứng dụng không cung cấp bất kỳ cấu trúc XrSpatialImageSizeEXT nào trong bất kỳ chuỗi tiếp theo nào có thể áp dụng.

Để thời gian chạy có thể tự động tạo kích thước hình ảnh một cách chính xác, bạn có thể cần một số chức năng và điều kiện tiên quyết của thiết bị, tức là máy ảnh âm thanh nổi, các thông số bên ngoài và bên trong của máy ảnh được hiệu chỉnh chính xác.

Nếu XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT không được liệt kê bằng xrEnumerateSpatialCapabilityFeaturesEXT, thì ứng dụng phải liên kết các cấu trúc XrSpatialImageSizeEXT vào các chuỗi tiếp theo thích hợp để tất cả hình ảnh đều có kích thước rõ ràng, nếu không, thời gian chạy phải trả về XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT từ xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Cách sử dụng hợp lệ (Ngầm ẩn)

Cấu trúc XrSpatialCapabilityConfigurationImageTrackingEXT được định nghĩa như sau:

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • capability là một XrSpatialCapabilityEXT và phải là XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT .
  • enabledComponentCount là một uint32_t chỉ định số lượng phần tử trong enabledComponents .
  • enabledComponents là một mảng XrSpatialComponentTypeEXT chỉ định các thành phần cần bật cho chức năng này.
  • imageTrackingDatabaseCount là một unint32_t chỉ định số lượng phần tử trong imageTrackingDatabases .
  • imageTrackingDatabases là một mảng các tay điều khiển XrSpatialImageTrackingDatabaseEXT chỉ định cơ sở dữ liệu theo dõi hình ảnh cần bật cho bối cảnh không gian.

Nếu tính năng theo dõi hình ảnh được hỗ trợ, thì thời gian chạy phải bật tính năng theo dõi hình ảnh nếu cấu trúc XrSpatialCapabilityConfigurationImageTrackingEXT được truyền trong XrSpatialContextCreateInfoEXT :: capabilityConfigs khi gọi xrCreateSpatialContextAsyncEXT .

Cấu trúc XrSpatialCapabilityConfigurationImageTrackingEXT cho phép ứng dụng khám phá các hình ảnh tham khảo được biểu thị bằng handle XrSpatialImageTrackingDatabaseEXT trong imageTrackingDatabases .

Thời gian chạy phải trả về XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT nếu XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT không được liệt kê bằng xrEnumerateSpatialCapabilitiesEXT .

Cách sử dụng hợp lệ (Ngầm ẩn)

Hình ảnh tham khảo về không gian

Cấu trúc XrSpatialReferenceImagePlaneEXT được định nghĩa như sau:

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

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

  • bufferSize là kích thước của mảng buffer.
  • buffer là một mảng dữ liệu uint8_t đại diện cho dữ liệu mặt phẳng.
  • rowStride là khoảng cách byte giữa hai vị trí bắt đầu của các hàng dữ liệu pixel liên tiếp.
  • pixelStride là khoảng cách byte giữa hai pixel liên tiếp.

Thời gian chạy phải truy cập vào buffer theo các mẫu mà tham số rowStride và pixelStride cung cấp.

Ứng dụng phải đặt rowStride và pixelStride sao cho thời gian chạy chỉ trích xuất các pixel có ý nghĩa của XrSpatialReferenceImagePlaneEXT này.

Cách sử dụng hợp lệ (Ngầm ẩn)

  • Tiện ích XR_EXT_spatial_image_tracking phải được bật trước khi sử dụng XrSpatialReferenceImagePlaneEXT
  • buffer phải là con trỏ trỏ đến một mảng gồm bufferSize giá trị uint8_t
  • Tham số bufferSize phải lớn hơn 0

Cấu trúc XrSpatialReferenceImageEXT được định nghĩa như sau:

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • width là chiều rộng tính bằng pixel của hình ảnh tham chiếu.
  • height là chiều cao tính bằng pixel của hình ảnh tham khảo.
  • format là một XrSpatialReferenceImageFormatEXT đại diện cho định dạng của hình ảnh.
  • planeCount là số phần tử trong mảng planes.
  • planes là một mảng gồm các cấu trúc XrSpatialReferenceImagePlaneEXT đại diện cho các mặt phẳng của dữ liệu hình ảnh.

Ứng dụng có thể tạo một hoặc nhiều cấu trúc XrSpatialReferenceImageEXT, mỗi cấu trúc đại diện cho một hình ảnh tham chiếu đầu vào duy nhất được truyền vào hàm xrCreateSpatialImageTrackingDatabaseAsyncEXT thông qua XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages khi tạo một tay điều khiển XrSpatialImageTrackingDatabaseEXT.

Ứng dụng phải cung cấp dữ liệu XrSpatialReferenceImagePlaneEXT :: buffer theo thứ tự pixel từ trái sang phải và từ trên xuống dưới.

Ứng dụng phải cung cấp cấu trúc XrSpatialReferenceImagePlaneEXT trong mảng XrSpatialReferenceImageEXT :: planes cho mỗi kênh màu của XrSpatialReferenceImageEXT :: format .

Cách sử dụng hợp lệ (Ngầm ẩn)

Thành phần được đảm bảo

Môi trường thời gian chạy hỗ trợ XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT phải cung cấp các thành phần không gian sau đây dưới dạng thành phần được đảm bảo của tất cả thực thể được các chức năng đó phát hiện, đồng thời phải liệt kê các thành phần đó trong xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Thành phần hình ảnh 2D

Cấu trúc danh sách thành phần để truy vấn dữ liệu

Cấu trúc XrSpatialComponentImage2DListEXT được định nghĩa như sau:

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • imageCount là số phần tử trong mảng images.
  • images là một mảng XrSpatialImage2DDataEXT .

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrQuerySpatialComponentDataEXT nếu XrSpatialComponentImage2DListEXT nằm trong chuỗi XrSpatialComponentDataQueryResultEXT :: next, nhưng XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT không có trong XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Thời gian chạy phải trả về XR_ERROR_SIZE_INSUFFICIENT từ xrQuerySpatialComponentDataEXT nếu imageCount nhỏ hơn XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Cách sử dụng hợp lệ (Ngầm ẩn)

Dữ liệu thành phần

Cấu trúc XrSpatialImage2DDataEXT được định nghĩa như sau:

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

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

Ứng dụng có thể sử dụng imageTrackingDatabase để xác định XrSpatialImageTrackingDatabaseEXT nào đã tạo trước đó chứa hình ảnh tham chiếu của cấu trúc XrSpatialImage2DDataEXT này. Đối với XrSpatialImageTrackingDatabaseEXT đó, ứng dụng có thể sử dụng referenceImageIndex để xác định XrSpatialReferenceImageEXT của cấu trúc XrSpatialImage2DDataEXT này bằng cách so khớp với thứ tự đầu vào của mảng XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

Tập hợp hình ảnh tham khảo được xác định bằng tập hợp tất cả cơ sở dữ liệu đang hoạt động không được chứa hình ảnh trùng lặp. Việc thêm hình ảnh trùng lặp có thể gây ra hành vi khám phá hoặc theo dõi bất lợi; tức là trả về nhiều chỉ mục hoặc chỉ mục không nhất quán.

Cách sử dụng hợp lệ (Ngầm ẩn)

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho một số chức năng, thì ứng dụng có thể bật chức năng đó bằng cách đưa giá trị enum vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Thành phần này không yêu cầu bất kỳ cấu hình đặc biệt nào để đưa vào chuỗi XrSpatialCapabilityConfigurationBaseHeaderEXT tiếp theo.

Thành phần 2D có giới hạn

Thành phần 2D có giới hạn cung cấp tâm và phạm vi của hình ảnh không gian được biểu thị bằng thực thể chứa thành phần đó. Hãy xem phần 2D có giới hạn để biết thêm thông tin chi tiết về thành phần 2D có giới hạn.

Mã ví dụ

Khám phá hình ảnh không gian và truy vấn dữ liệu thành phần

Mã ví dụ sau đây minh hoạ cách khám phá các thực thể không gian cho chức năng theo dõi hình ảnh và truy vấn dữ liệu thành phần của thực thể đó.

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

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components
  std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = discoveryFuture;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // For every frame in frame loop

  XrFrameState frameState;  // Previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata = *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

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_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • Mở rộng XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • Mở rộng XrResult :

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • Mở rộng XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

  • Mở rộng XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

  • Mở rộng XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

  • Mở rộng XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
    • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
    • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
    • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

Vấn đề

Danh sách phiên bản

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

    • Nội dung mô tả ban đầu về tiện ích