XR_EXT_spatial_marker_tracking

Name String

XR_EXT_spatial_marker_tracking

Loại phần mở rộng

Tiện ích Instance

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

744

Bản sửa đổi

1

Trạng thái phê chuẩn

Được phê duyệt

Phần mở rộng và các phần phụ thuộc của phiên bản

XR_EXT_spatial_entity

Cộng tác viên

Ron Bessems, Meta
Nihav Jain, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Tổng quan

Tiện ích này dựa trên XR_EXT_spatial_entity và cho phép các ứng dụng phát hiện cũng như theo dõi điểm đánh dấu trong môi trường của chúng. Điểm đánh dấu là mã 2D có thể bao gồm mã QR, mã QR siêu nhỏ, điểm đánh dấu ArUco hoặc AprilTag.

Điểm đánh dấu được theo dõi được biểu thị dưới dạng một thực thể không gian có các thành phần sau:

• XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
• XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Hỗ trợ thời gian chạy

Thời gian chạy phải quảng cáo khả năng hỗ trợ của nó đối với nhiều chức năng theo dõi điểm đánh dấu bằng cách sử dụng xrEnumerateSpatialCapabilitiesEXT bằng cách liệt kê bất kỳ chức năng nào sau đây:

• XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT
• XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT
• XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT
• XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

Cấu hình

Để bật tính năng phát hiện một loại điểm đánh dấu, ứng dụng phải truyền cấu trúc cấu hình tương ứng đến xrCreateSpatialContextAsyncEXT .

Cấu hình loại điểm đánh dấu

mã QR

Cấu trúc XrSpatialCapabilityConfigurationQrCodeEXT được xác định là:

typedef struct XrSpatialCapabilityConfigurationQrCodeEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationQrCodeEXT;

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

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• capability phải là XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT .
• enabledComponentCount là một uint32_t có số lượng phần tử trong enabledComponents .
• enabledComponents là một con trỏ trỏ đến một mảng các thành phần cần bật cho khả năng này.

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

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

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

• Bạn phải bật tiện ích XR_EXT_spatial_marker_tracking trước khi sử dụng XrSpatialCapabilityConfigurationQrCodeEXT
• type phải là XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_QR_CODE_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc . Xem thêm: XrSpatialMarkerSizeEXT , XrSpatialMarkerStaticOptimizationEXT
• capability phải là giá trị XrSpatialCapabilityEXT hợp lệ
• enabledComponents phải là con trỏ đến một mảng gồm enabledComponentCount giá trị XrSpatialComponentTypeEXT hợp lệ
• Tham số enabledComponentCount phải lớn hơn 0

Mã QR siêu nhỏ

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

typedef struct XrSpatialCapabilityConfigurationMicroQrCodeEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationMicroQrCodeEXT;

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

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• capability phải là XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT .
• enabledComponentCount là một uint32_t có số lượng phần tử trong enabledComponents .
• enabledComponents là một con trỏ trỏ đến một mảng các thành phần cần bật cho khả năng này.

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

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

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

• Bạn phải bật tiện ích XR_EXT_spatial_marker_tracking trước khi sử dụng XrSpatialCapabilityConfigurationMicroQrCodeEXT
• type phải là XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_MICRO_QR_CODE_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc . Xem thêm: XrSpatialMarkerSizeEXT , XrSpatialMarkerStaticOptimizationEXT
• capability phải là giá trị XrSpatialCapabilityEXT hợp lệ
• enabledComponents phải là con trỏ đến một mảng gồm enabledComponentCount giá trị XrSpatialComponentTypeEXT hợp lệ
• Tham số enabledComponentCount phải lớn hơn 0

Điểm đánh dấu ArUco

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

typedef struct XrSpatialCapabilityConfigurationArucoMarkerEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialMarkerArucoDictEXT         arUcoDict;
} XrSpatialCapabilityConfigurationArucoMarkerEXT;

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

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• capability phải là XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT .
• enabledComponentCount là một uint32_t có số lượng phần tử trong enabledComponents .
• enabledComponents là một con trỏ trỏ đến một mảng các thành phần cần bật cho khả năng này.
• arUcoDict là từ điển điểm đánh dấu cần phát hiện.

Nếu được hỗ trợ, thời gian chạy phải bật tính năng theo dõi điểm đánh dấu ArUco khi cấu trúc XrSpatialCapabilityConfigurationArucoMarkerEXT được truyền vào XrSpatialContextCreateInfoEXT :: capabilityConfigs khi gọi xrCreateSpatialContextAsyncEXT .

Thời gian chạy phải trả về XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT từ xrCreateSpatialContextAsyncEXT nếu cấu trúc XrSpatialCapabilityConfigurationArucoMarkerEXT nằm trong XrSpatialContextCreateInfoEXT :: capabilityConfigs nhưng XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT không được xrEnumerateSpatialCapabilitiesEXT liệt kê .

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

• Bạn phải bật tiện ích XR_EXT_spatial_marker_tracking trước khi sử dụng XrSpatialCapabilityConfigurationArucoMarkerEXT
• type phải là XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ARUCO_MARKER_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc . Xem thêm: XrSpatialMarkerSizeEXT , XrSpatialMarkerStaticOptimizationEXT
• capability phải là giá trị XrSpatialCapabilityEXT hợp lệ
• enabledComponents phải là con trỏ đến một mảng gồm enabledComponentCount giá trị XrSpatialComponentTypeEXT hợp lệ
• arUcoDict phải là một giá trị XrSpatialMarkerArucoDictEXT hợp lệ
• Tham số enabledComponentCount phải lớn hơn 0

Liệt kê XrSpatialMarkerArucoDictEXT được xác định là:

typedef enum XrSpatialMarkerArucoDictEXT {
    XR_SPATIAL_MARKER_ARUCO_DICT_4X4_50_EXT = 1,
    XR_SPATIAL_MARKER_ARUCO_DICT_4X4_100_EXT = 2,
    XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT = 3,
    XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT = 4,
    XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT = 5,
    XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT = 6,
    XR_SPATIAL_MARKER_ARUCO_DICT_5X5_250_EXT = 7,
    XR_SPATIAL_MARKER_ARUCO_DICT_5X5_1000_EXT = 8,
    XR_SPATIAL_MARKER_ARUCO_DICT_6X6_50_EXT = 9,
    XR_SPATIAL_MARKER_ARUCO_DICT_6X6_100_EXT = 10,
    XR_SPATIAL_MARKER_ARUCO_DICT_6X6_250_EXT = 11,
    XR_SPATIAL_MARKER_ARUCO_DICT_6X6_1000_EXT = 12,
    XR_SPATIAL_MARKER_ARUCO_DICT_7X7_50_EXT = 13,
    XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT = 14,
    XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT = 15,
    XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT = 16,
    XR_SPATIAL_MARKER_ARUCO_DICT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialMarkerArucoDictEXT;

Từ điển ArUco được xác định trước được hỗ trợ:

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

• XR_SPATIAL_MARKER_ARUCO_DICT_4X4_50_EXT – Từ điển điểm đánh dấu Aruco 4 x 4 pixel có 50 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_4X4_100_EXT – Từ điển gồm 100 mã nhận dạng cho điểm đánh dấu Aruco 4 x 4 pixel.
• XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT – Từ điển gồm 250 mã nhận dạng cho điểm đánh dấu Aruco 4 x 4 pixel.
• XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT – Từ điển gồm 1.000 mã nhận dạng cho điểm đánh dấu Aruco 4 x 4 pixel.
• XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT – Từ điển gồm 50 mã nhận dạng cho điểm đánh dấu Aruco 5 x 5 pixel.
• XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT – Từ điển điểm đánh dấu Aruco 5x5 pixel có 100 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_5X5_250_EXT – Từ điển điểm đánh dấu Aruco 5 x 5 pixel với 250 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_5X5_1000_EXT – Từ điển gồm 1.000 mã nhận dạng và 5 x 5 pixel cho điểm đánh dấu Aruco.
• XR_SPATIAL_MARKER_ARUCO_DICT_6X6_50_EXT – Từ điển điểm đánh dấu Aruco 6 x 6 pixel với 50 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_6X6_100_EXT – Từ điển điểm đánh dấu Aruco 6x6 pixel với 100 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_6X6_250_EXT – Từ điển điểm đánh dấu Aruco 6 x 6 pixel với 250 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_6X6_1000_EXT – Từ điển điểm đánh dấu Aruco 6 x 6 pixel với 1.000 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_7X7_50_EXT – Từ điển điểm đánh dấu Aruco 7 x 7 pixel với 50 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT – Từ điển gồm 100 mã nhận dạng và 7 x 7 pixel của điểm đánh dấu Aruco.
• XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT – Từ điển điểm đánh dấu Aruco 7 x 7 pixel có 250 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT – Từ điển điểm đánh dấu Aruco 7 x 7 pixel có 1.000 mã nhận dạng.

AprilTags

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

typedef struct XrSpatialCapabilityConfigurationAprilTagEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialMarkerAprilTagDictEXT      aprilDict;
} XrSpatialCapabilityConfigurationAprilTagEXT;

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

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• capability phải là XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT .
• enabledComponentCount là một uint32_t có số lượng phần tử trong enabledComponents .
• enabledComponents là một con trỏ trỏ đến một mảng các thành phần cần bật cho khả năng này.
• aprilDict là từ điển điểm đánh dấu cần phát hiện.

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

Thời gian chạy phải trả về XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT từ xrCreateSpatialContextAsyncEXT nếu cấu trúc XrSpatialCapabilityConfigurationAprilTagEXT nằm trong XrSpatialContextCreateInfoEXT :: capabilityConfigs nhưng XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT không được xrEnumerateSpatialCapabilitiesEXT liệt kê .

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

• Bạn phải bật tiện ích XR_EXT_spatial_marker_tracking trước khi sử dụng XrSpatialCapabilityConfigurationAprilTagEXT
• type phải là XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_APRIL_TAG_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc . Xem thêm: XrSpatialMarkerSizeEXT , XrSpatialMarkerStaticOptimizationEXT
• capability phải là giá trị XrSpatialCapabilityEXT hợp lệ
• enabledComponents phải là con trỏ đến một mảng gồm enabledComponentCount giá trị XrSpatialComponentTypeEXT hợp lệ
• aprilDict phải là giá trị XrSpatialMarkerAprilTagDictEXT hợp lệ
• Tham số enabledComponentCount phải lớn hơn 0

Liệt kê XrSpatialMarkerAprilTagDictEXT được xác định là:

typedef enum XrSpatialMarkerAprilTagDictEXT {
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_16H5_EXT = 1,
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_25H9_EXT = 2,
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H10_EXT = 3,
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT = 4,
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialMarkerAprilTagDictEXT;

Từ điển AprilTag được xác định trước được hỗ trợ:

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

• XR_SPATIAL_MARKER_APRIL_TAG_DICT_16H5_EXT – 4 x 4 bit, khoảng cách Hamming tối thiểu giữa 2 mã bất kỳ = 5, 30 mã.
• XR_SPATIAL_MARKER_APRIL_TAG_DICT_25H9_EXT – 5 x 5 bit, khoảng cách Hamming tối thiểu giữa hai mã bất kỳ = 9, 35 mã.
• XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H10_EXT – 6 x 6 bit, khoảng cách Hamming tối thiểu giữa hai mã bất kỳ = 10, 2320 mã.
• XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT – 6 x 6 bit, khoảng cách Hamming tối thiểu giữa hai mã bất kỳ = 11, 587 mã.

Cấu hình điểm đánh dấu không bắt buộc

Các ứng dụng nên gọi xrEnumerateSpatialCapabilityFeaturesEXT để lấy danh sách các tính năng không bắt buộc được hỗ trợ.

Hãy xem XrSpatialCapabilityFeatureEXT để biết danh sách đầy đủ tất cả các tính năng về khả năng không gian mà mọi tiện ích đều hỗ trợ.

Kích thước điểm đánh dấu

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

typedef struct XrSpatialMarkerSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              markerSideLength;
} XrSpatialMarkerSizeEXT;

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

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• markerSideLength là kích thước (tính bằng mét) của tất cả các điểm đánh dấu.

Nếu XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT được xrEnumerateSpatialCapabilityFeaturesEXT liệt kê cho một khả năng nhất định và nếu ứng dụng xâu chuỗi XrSpatialMarkerSizeEXT với cấu trúc cấu hình tương ứng của khả năng đó, thì thời gian chạy phải giả định rằng tất cả các điểm đánh dấu được phát hiện đều có chiều rộng và chiều cao là markerSideLength . Việc cung cấp thông tin này cho thời gian chạy cho phép thời gian chạy trả về tư thế và kích thước chính xác hơn. Cấu trúc này phải được liên kết với chuỗi next của XrSpatialCapabilityConfigurationQrCodeEXT, XrSpatialCapabilityConfigurationMicroQrCodeEXT, XrSpatialCapabilityConfigurationArucoMarkerEXT hoặc XrSpatialCapabilityConfigurationAprilTagEXT .

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

• Bạn phải bật tiện ích XR_EXT_spatial_marker_tracking trước khi sử dụng XrSpatialMarkerSizeEXT
• type phải là XR_TYPE_SPATIAL_MARKER_SIZE_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc

Tối ưu hoá điểm đánh dấu tĩnh

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

typedef struct XrSpatialMarkerStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticMarker;
} XrSpatialMarkerStaticOptimizationEXT;

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

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• optimizeForStaticMarker cho biết liệu tất cả các điểm đánh dấu trong không gian có dự kiến không di chuyển hay không.

Nếu XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT được xrEnumerateSpatialCapabilityFeaturesEXT liệt kê cho một khả năng nhất định và nếu ứng dụng xâu chuỗi XrSpatialMarkerStaticOptimizationEXT vào cấu trúc cấu hình tương ứng của khả năng đó, thì thời gian chạy phải giả định rằng tất cả các điểm đánh dấu được phát hiện đều là tĩnh nếu optimizeForStaticMarker được đặt thành XR_TRUE . Điều này cho phép thời gian chạy tạo ra tư thế và kích thước chính xác hơn. Cấu trúc này phải được liên kết với chuỗi next của XrSpatialCapabilityConfigurationQrCodeEXT, XrSpatialCapabilityConfigurationMicroQrCodeEXT, XrSpatialCapabilityConfigurationArucoMarkerEXT hoặc XrSpatialCapabilityConfigurationAprilTagEXT .

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

• Bạn phải bật tiện ích XR_EXT_spatial_marker_tracking trước khi sử dụng XrSpatialMarkerStaticOptimizationEXT
• type phải là XR_TYPE_SPATIAL_MARKER_STATIC_OPTIMIZATION_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc

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

Thời gian chạy hỗ trợ XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT, XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT, XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT hoặc XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT phải cung cấp các thành phần không gian sau đây dưới dạng các thành phần được đảm bảo của tất cả các thực thể mà những chức năng đó phát hiện được và phải liệt kê chúng trong xrEnumerateSpatialCapabilityComponentTypesEXT :

• XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
• XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Thành phần điểm đánh dấu

Dữ liệu thành phần

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

typedef struct XrSpatialMarkerDataEXT {
    XrSpatialCapabilityEXT    capability;
    uint32_t                  markerId;
    XrSpatialBufferEXT        data;
} XrSpatialMarkerDataEXT;

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

• capability là XrSpatialCapabilityEXT đã phát hiện ra điểm đánh dấu.
• markerId là giá trị nhận dạng được mã hoá từ điểm đánh dấu. Đối với điểm đánh dấu ArUco và AprilTag, trường này phải hợp lệ và được điền mã nhận dạng đã mã hoá. Đối với mã QR, trường này phải bằng 0.
• data là mã vùng đệm và loại thông tin bổ sung có trong điểm đánh dấu.

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT và XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT hỗ trợ dữ liệu bổ sung. Nếu capability là một trong những giá trị sau –

• Nếu thời gian chạy đã giải mã thành công dữ liệu cho điểm đánh dấu, thì thời gian chạy phải đặt loại vùng đệm data thành XR_SPATIAL_BUFFER_TYPE_UINT8_EXT hoặc XR_SPATIAL_BUFFER_TYPE_STRING_EXT , tuỳ thuộc vào dữ liệu trong điểm đánh dấu. Thời gian chạy phải đặt một mã nhận dạng vùng đệm hợp lệ trong data mà ứng dụng có thể sử dụng với hàm xrGetSpatialBuffer* thích hợp để lấy dữ liệu.
• Nếu thời gian chạy chưa giải mã dữ liệu của điểm đánh dấu, thì thời gian chạy phải đặt mã nhận dạng vùng đệm data thành XR_NULL_SPATIAL_BUFFER_ID_EXT và loại vùng đệm thành XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT .

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT và XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT không hỗ trợ dữ liệu bổ sung và thời gian chạy phải đặt mã nhận dạng vùng đệm của data thành XR_NULL_SPATIAL_BUFFER_ID_EXT .

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

• Bạn phải bật tiện ích XR_EXT_spatial_marker_tracking trước khi sử dụng XrSpatialMarkerDataEXT
• capability phải là giá trị XrSpatialCapabilityEXT hợp lệ
• data phải là một cấu trúc XrSpatialBufferEXT hợp lệ

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

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

typedef struct XrSpatialComponentMarkerListEXT {
    XrStructureType            type;
    void*                      next;
    uint32_t                   markerCount;
    XrSpatialMarkerDataEXT*    markers;
} XrSpatialComponentMarkerListEXT;

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

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
• markerCount là số phần tử trong thành phần markers.
• markers là một mảng XrSpatialMarkerDataEXT .

Ứng dụng có thể truy vấn thành phần điểm đánh dấu của các thực thể không gian trong XrSpatialSnapshotEXT bằng cách thêm XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT vào XrSpatialComponentDataQueryConditionEXT :: componentTypes và thêm XrSpatialComponentMarkerListEXT vào chuỗi con trỏ tiếp theo của XrSpatialComponentDataQueryResultEXT .

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrQuerySpatialComponentDataEXT nếu XrSpatialComponentMarkerListEXT nằm trong chuỗi tiếp theo của XrSpatialComponentDataQueryResultEXT :: next nhưng XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT không có trong XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

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

• Bạn phải bật tiện ích XR_EXT_spatial_marker_tracking trước khi sử dụng XrSpatialComponentMarkerListEXT
• type phải là XR_TYPE_SPATIAL_COMPONENT_MARKER_LIST_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• markers phải là con trỏ đến một mảng gồm các cấu trúc markerCount XrSpatialMarkerDataEXT
• Tham số markerCount phải lớn hơn 0

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho một số khả năng, thì ứng dụng có thể bật khả năng đó bằng cách đưa giá trị liệt kê vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc dẫn xuất XrSpatialCapabilityConfigurationBaseHeaderEXT của khả năng hỗ trợ thành phần này.

Thành phần này không yêu cầu bất kỳ cấu hình đặc biệt nào để được đưa vào chuỗi XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

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

Thành phần 2D có ranh giới cung cấp tâm và phạm vi của điểm đánh dấu do thực thể mà thành phần đó nằm trên biểu thị. Hãy xem phần 2D có ranh giới để biết thêm thông tin về thành phần 2D có ranh giới.

XrSpatialBounded2DDataEXT :: center phải trỏ đến tâm của điểm đánh dấu. Khi nhìn vào mặt trước của điểm đánh dấu, trục X phải hướng sang phải và trục Y phải hướng lên trên của điểm đánh dấu. Thời gian chạy phải tuân theo quy ước hệ toạ độ thuận tay phải, do đó, trục Z sẽ nằm ở mặt trước của điểm đánh dấu. Điều này có nghĩa là một điểm đánh dấu có vị trí {0, 0, 0}, hướng xoay {0, 0, 0, 1} (không xoay) và phạm vi {1, 1} đề cập đến một điểm đánh dấu có kích thước 1 mét x 1 mét, được đặt ở tâm {0, 0, 0} với vectơ pháp tuyến của mặt trước hướng về hướng +Z trong không gian của thành phần.

Dưới đây là hình minh hoạ hướng của điểm đánh dấu.

Hình 25. Điểm đánh dấu mã QR có trục

Mã kiểm thử

Các mã sau phải có mặt phẳng X-Y bên trong tài liệu và trục Z hướng vào người xem. Gốc trục phải xuất hiện ở giữa mỗi điểm đánh dấu. Trục X phải hướng sang phải, trục Y phải hướng lên trên cùng của tài liệu.

Hình 26. Mã QR có văn bản "OpenXR"

Hình 27. AprilTag XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT có mã nhận dạng 42

Hình 28. Điểm đánh dấu ArUco XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT có mã nhận dạng 43

Mã ví dụ

Định cấu hình khả năng theo dõi mã QR

Đoạn mã ví dụ sau đây minh hoạ cách định cấu hình khả năng theo dõi mã QR khi tạo một bối cảnh không gian.

// Check if marker tracking capability is supported
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT) == capabilities.end()) {
  return;
}

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

bool supportsFixedMarkerSize = std::find(capabilityFeatures.begin(), capabilityFeatures.end(), XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT) != capabilityFeatures.end();

// Create a spatial context
XrSpatialContextEXT spatialContext{};

// Enable the 2 guaranteed components of the qr code tracking capability
std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT,
};
XrSpatialCapabilityConfigurationQrCodeEXT markerConfiguration{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_QR_CODE_EXT};
markerConfiguration.capability = XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT;
markerConfiguration.enabledComponentCount = static_cast<uint32_t>(enabledComponents.size());
markerConfiguration.enabledComponents = enabledComponents.data();

// only chained if features.markerSideLength is true.
XrSpatialMarkerSizeEXT markerSize{XR_TYPE_SPATIAL_MARKER_SIZE_EXT};
markerSize.markerSideLength = 0.10f;
if (supportsFixedMarkerSize) {
  markerConfiguration.next = &markerSize;
}


std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
  reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&markerConfiguration),
};

XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
XrFutureEXT createContextFuture;
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) {
  return;
}

spatialContext = completion.spatialContext;

// ...
// Discovery entities with the spatial context
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Khám phá các thực thể không gian và dữ liệu thành phần truy vấn

Đoạn mã ví dụ sau đây minh hoạ cách khám phá các thực thể không gian cho một bối cảnh được định cấu hình bằng XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT và truy vấn dữ liệu thành phần của thực thể đó.

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

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

  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 and marker component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    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.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

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

    std::vector<XrSpatialMarkerDataEXT> markers;
    XrSpatialComponentMarkerListEXT markerList{XR_TYPE_SPATIAL_COMPONENT_MARKER_LIST_EXT};
    markers.resize(queryResult.entityIdCountOutput);
    markerList.markerCount = markers.size();
    markerList.markers = markers.data();
    bounded2DList.next = &markerList;

    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) {
        continue;
      }

      // 2D bounds for entity entityIds[i] is bounded2D[i].extents centered on bounded2D[i].center.

      if (markers[i].capability == XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT) {
        // Check if marker data has been decoded.
        if (markers[i].data.bufferId != XR_NULL_SPATIAL_BUFFER_ID_EXT) {
          if (markers[i].data.bufferType == XR_SPATIAL_BUFFER_TYPE_STRING_EXT) {
            // Qr Code data can be queried using
            // XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
            // info.bufferId = markers[i].data.bufferId;
            // xrGetSpatialBufferStringEXT(completion.snapshot, &getInfo, ...)
          } else if (markers[i].data.bufferType == XR_SPATIAL_BUFFER_TYPE_UINT8_EXT) {
            // Qr Code data can be queried using
            // XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
            // info.bufferId = markers[i].data.bufferId;
            // xrGetSpatialBufferUint8(completion.snapshot, &getInfo, ...)
          }
        }
      }
    }

    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
  // ...
}

Cấu trúc mới

• XrSpatialCapabilityConfigurationAprilTagEXT
• XrSpatialCapabilityConfigurationArucoMarkerEXT
• XrSpatialCapabilityConfigurationMicroQrCodeEXT
• XrSpatialCapabilityConfigurationQrCodeEXT
• XrSpatialMarkerDataEXT

• Mở rộng XrSpatialCapabilityConfigurationArucoMarkerEXT , XrSpatialCapabilityConfigurationAprilTagEXT , XrSpatialCapabilityConfigurationQrCodeEXT , XrSpatialCapabilityConfigurationMicroQrCodeEXT :

  • XrSpatialMarkerSizeEXT
  • XrSpatialMarkerStaticOptimizationEXT

• Mở rộng XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentMarkerListEXT

Enum mới

• XrSpatialMarkerAprilTagDictEXT
• XrSpatialMarkerArucoDictEXT

Hằng số Enum mới

• XR_EXT_SPATIAL_MARKER_TRACKING_EXTENSION_NAME
• XR_EXT_spatial_marker_tracking_SPEC_VERSION

• Mở rộng XrSpatialCapabilityEXT :

  • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT
  • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT
  • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT
  • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

• Mở rộng XrSpatialCapabilityFeatureEXT :

  • XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT
  • XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

• Mở rộng XrSpatialComponentTypeEXT :

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

• Mở rộng XrStructureType :

  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_APRIL_TAG_EXT
  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ARUCO_MARKER_EXT
  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_MICRO_QR_CODE_EXT
  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_QR_CODE_EXT
  • XR_TYPE_SPATIAL_COMPONENT_MARKER_LIST_EXT
  • XR_TYPE_SPATIAL_MARKER_SIZE_EXT
  • XR_TYPE_SPATIAL_MARKER_STATIC_OPTIMIZATION_EXT

Danh sách phiên bản

• Bản sửa đổi 1, ngày 29/7/2024 (Ron Bessems, Meta)

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