XR_EXT_spatial_marker_tracking

Name String

XR_EXT_spatial_marker_tracking

Loại tiện ích

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

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

744

Bản sửa đổi

1

Trạng thái phê chuẩn

Đã 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

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 được xây dựng 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ó (hoặc "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ợ cho nhiều tính 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ỳ tính 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 định nghĩa như sau:

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

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 phải là XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT .
• enabledComponentCount là một uint32_t có số phần tử trong enabledComponents .
• enabledComponents là một con trỏ tới một mảng các thành phần để bật cho chức 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 liệt kê bằng xrEnumerateSpatialCapabilitiesEXT .

Cách 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à một giá trị XrSpatialCapabilityEXT hợp lệ
• enabledComponents phải là một 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 nhỏ

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

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

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 phải là XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT .
• enabledComponentCount là một uint32_t có số phần tử trong enabledComponents .
• enabledComponents là một con trỏ tới một mảng các thành phần để bật cho chức năng này.

Nếu có hỗ trợ mã Micro QR, thì thời gian chạy phải bật tính năng theo dõi mã Micro QR 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 liệt kê bằng xrEnumerateSpatialCapabilitiesEXT .

Cách 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à một giá trị XrSpatialCapabilityEXT hợp lệ
• enabledComponents phải là một 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 định nghĩa 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ả 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 phải là XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT .
• enabledComponentCount là một uint32_t có số phần tử trong enabledComponents .
• enabledComponents là một con trỏ tới một mảng các thành phần để bật cho chức năng này.
• arUcoDict là từ điển điểm đánh dấu cần phát hiện.

Nếu điểm đánh dấu ArUco được hỗ trợ, thì 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 trong 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 liệt kê bằng xrEnumerateSpatialCapabilitiesEXT .

Cách sử dụng hợp lệ (Ngầm ẩ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à một giá trị XrSpatialCapabilityEXT hợp lệ
• enabledComponents phải là một 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

Phép liệt kê XrSpatialMarkerArucoDictEXT được định nghĩa như sau:

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 và được hỗ trợ:

Nội dung mô tả về giá trị 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 điểm đánh dấu Aruco 4 x 4 pixel với 100 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT — Từ điển điểm đánh dấu Aruco 4 x 4 pixel với 250 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT — Từ điển điểm đánh dấu Aruco 4 x 4 pixel với 1.000 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT — Từ điển điểm đánh dấu Aruco 5 x 5 pixel với 50 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT — Từ điển điểm đánh dấu Aruco 5 x 5 pixel với 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 điểm đánh dấu Aruco 5 x 5 pixel với 1000 mã nhận dạng.
• 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 6 x 6 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 1000 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 có 50 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT — Từ điển điểm đánh dấu Aruco 7 x 7 pixel có 100 mã nhận dạng.
• XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT — Từ điển điểm đánh dấu Aruco 7 x 7 pixel với 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 với 1000 mã nhận dạng.

AprilTags

Cấu trúc XrSpatialCapabilityConfigurationAprilTagEXT được định nghĩa 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ả 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 phải là XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT .
• enabledComponentCount là một uint32_t có số phần tử trong enabledComponents .
• enabledComponents là một con trỏ tới một mảng các thành phần để bật cho chức 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ì 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 trong 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 liệt kê bằng xrEnumerateSpatialCapabilitiesEXT .

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

• Tiện ích XR_EXT_spatial_marker_tracking phải được bật 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à một giá trị XrSpatialCapabilityEXT hợp lệ
• enabledComponents phải là một con trỏ đến một mảng gồm enabledComponentCount giá trị XrSpatialComponentTypeEXT hợp lệ
• aprilDict phải là một giá trị XrSpatialMarkerAprilTagDictEXT hợp lệ
• Tham số enabledComponentCount phải lớn hơn 0

Phép liệt kê XrSpatialMarkerAprilTagDictEXT được định nghĩa như sau:

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 và được hỗ trợ:

Nội dung mô tả về giá trị 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 hai 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

Ứ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ông gian mà mọi tiện ích hỗ trợ.

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

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

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

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.
• markerSideLength là kích thước tính bằng mét của tất cả điểm đánh dấu.

Nếu XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT được liệt kê bằng xrEnumerateSpatialCapabilityFeaturesEXT cho một chức năng nhất định và nếu ứng dụng liên kết XrSpatialMarkerSizeEXT với cấu trúc cấu hình tương ứng của chức năng đó, thì thời gian chạy phải giả định rằng tất 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ào chuỗi next của XrSpatialCapabilityConfigurationQrCodeEXT , XrSpatialCapabilityConfigurationMicroQrCodeEXT , XrSpatialCapabilityConfigurationArucoMarkerEXT hoặc XrSpatialCapabilityConfigurationAprilTagEXT .

Cách 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 định nghĩa như sau:

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

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.
• optimizeForStaticMarker cho biết liệu tất 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 liệt kê bằng xrEnumerateSpatialCapabilityFeaturesEXT cho một chức năng nhất định và nếu ứng dụng liên kết XrSpatialMarkerStaticOptimizationEXT với cấu trúc cấu hình tương ứng của chức năng đó, thì thời gian chạy phải giả định rằng tất 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ào chuỗi next của XrSpatialCapabilityConfigurationQrCodeEXT , XrSpatialCapabilityConfigurationMicroQrCodeEXT , XrSpatialCapabilityConfigurationArucoMarkerEXT hoặc XrSpatialCapabilityConfigurationAprilTagEXT .

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

• Tiện ích XR_EXT_spatial_marker_tracking phải được bật 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

Môi trường 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 thành phần được đảm bảo của tất cả thực thể mà các chức năng đó phát hiện được, đồng thời phải liệt kê các thành phần đó 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 định nghĩa như sau:

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

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

• capability là XrSpatialCapabilityEXT đã phát hiện đ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ã nhận dạng 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 trường hợp 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 cũng phải đặt mã 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ã 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ã vùng đệm của data thành XR_NULL_SPATIAL_BUFFER_ID_EXT .

Cách 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à một 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 định nghĩa như sau:

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

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

Cách sử dụng hợp lệ (Ngầm ẩ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 markerCount cấu trúc 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ố chức năng, thì ứng dụng có thể bật chức 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 phái sinh XrSpatialCapabilityConfigurationBaseHeaderEXT của chức 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ó 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 điểm đánh dấu được biểu thị bằng thực thể mà thành phần đó nằm trê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.

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 bên phải và trục Y phải hướng lên trên cùng 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ẽ xuất hiện từ 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}, độ xoay {0, 0, 0, 1} (không xoay) và phạm vi {1, 1} là điểm đánh dấu có kích thước 1 mét x 1 mét, nằm ở giữa {0, 0, 0} và có vectơ pháp tuyến của mặt trước hướng về phía +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 đây phải có mặt phẳng X-Y bên trong tài liệu và trục Z hướng về phía người xem. Gốc toạ độ 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 đầu 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 chức năng theo dõi mã QR

Mã ví dụ sau đây minh hoạ cách định cấu hình chức năng theo dõi mã QR khi tạo 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á thực thể không gian và dữ liệu thành phần truy vấ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 bối cảnh đó.

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, 29/7/2024 (Ron Bessems, Meta)

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