XR_ANDROID_spatial_discovery_bounds

Name String

XR_ANDROID_spatial_discovery_bounds

Loại tiện ích

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

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

762

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

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

Tổng quan

Tiện ích này thêm định nghĩa cho ranh giới không gian, cho phép các ứng dụng lọc thực thể không gian được phát hiện khi gọi xrCreateSpatialDiscoverySnapshotAsyncEXT .

Ranh giới không gian

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

typedef struct XrSpatialBoundsSpherefANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrSpheref          sphere;
} XrSpatialBoundsSpherefANDROID;

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.
• space là XrSpace mà mọi tư thế cho ranh giới đều được xác định trong đó.
• time là một XrTime mà tại đó các tư thế cho ranh giới được xác định.
• sphere là một XrSpheref mô tả thể tích hình cầu mà trong đó thời gian chạy phải ràng buộc việc khám phá các thực thể không gian.

Các chức năng không gian hỗ trợ XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID (được liệt kê bằng xrEnumerateSpatialCapabilityFeaturesEXT ) cho phép ứng dụng hạn chế việc khám phá đối với các thực thể không gian có vị trí hoặc ranh giới nằm trong hoặc giao nhau với sphere bằng cách liên kết XrSpatialBoundsSpherefANDROID với XrSpatialDiscoverySnapshotCreateInfoEXT :: next . Đối với ảnh chụp nhanh khám phá trong đó chức năng hiện hành hỗ trợ XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID , nếu cấu trúc này có trong chuỗi next , thì thời gian chạy phải không bao gồm bất kỳ thực thể không gian nào có vị trí hoặc ranh giới hoàn toàn nằm ngoài sphere .

Điều quan trọng cần lưu ý là việc đưa XrSpatialBoundsSpherefANDROID vào chuỗi tiếp theo của XrSpatialDiscoverySnapshotCreateInfoEXT đóng vai trò là điều kiện "AND" (VÀ) với các bộ lọc khác được cung cấp. Các thực thể đến từ những chức năng không gian không hỗ trợ XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID không được có trong ảnh chụp nhanh về hoạt động khám phá. Hành vi này khác với phần còn lại của thông số kỹ thuật OpenXR, trong đó các cấu trúc không được nhận dạng hoặc không được hỗ trợ trong chuỗi con trỏ tiếp theo sẽ bị thời gian chạy bỏ qua. Ngoài ra, như mô tả trong phần Tính duy nhất của cấu trúc chuỗi tiếp theo, thời gian chạy sẽ chỉ xử lý lần xuất hiện đầu tiên của cấu trúc XrSpatialBoundsSpherefANDROID trong chuỗi tiếp theo.

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

• Bạn phải bật tiện ích XR_ANDROID_spatial_discovery_bounds trước khi sử dụng XrSpatialBoundsSpherefANDROID
• type phải là XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID
• 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
• space phải là một tên người dùng XrSpace hợp lệ

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

typedef struct XrSpatialBoundsBoxfANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrBoxf             box;
} XrSpatialBoundsBoxfANDROID;

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.
• space là XrSpace mà mọi tư thế cho ranh giới đều được xác định trong đó.
• time là một XrTime mà tại đó các tư thế cho ranh giới được xác định.
• box là một XrBoxf mô tả thể tích hộp mà trong đó thời gian chạy phải ràng buộc việc khám phá các thực thể không gian.

Các chức năng không gian hỗ trợ XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID (được liệt kê bằng xrEnumerateSpatialCapabilityFeaturesEXT ) cho phép ứng dụng hạn chế việc khám phá đối với các thực thể không gian có vị trí hoặc ranh giới nằm trong hoặc giao nhau với box bằng cách liên kết XrSpatialBoundsBoxfANDROID với XrSpatialDiscoverySnapshotCreateInfoEXT :: next . Đối với ảnh chụp nhanh khám phá trong đó chức năng hiện hành hỗ trợ XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID , nếu cấu trúc này có trong chuỗi next , thì thời gian chạy phải không bao gồm bất kỳ thực thể không gian nào có vị trí hoặc ranh giới hoàn toàn nằm ngoài box .

Điều quan trọng cần lưu ý là việc đưa XrSpatialBoundsBoxfANDROID vào chuỗi tiếp theo của XrSpatialDiscoverySnapshotCreateInfoEXT đóng vai trò là điều kiện "AND" (VÀ) với các bộ lọc khác được cung cấp. Các thực thể đến từ những chức năng không gian không hỗ trợ XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID không được có trong ảnh chụp nhanh về hoạt động khám phá. Hành vi này khác với phần còn lại của thông số kỹ thuật OpenXR, trong đó các cấu trúc không được nhận dạng hoặc không được hỗ trợ trong chuỗi con trỏ tiếp theo sẽ bị thời gian chạy bỏ qua. Ngoài ra, như mô tả trong phần Tính duy nhất của cấu trúc chuỗi tiếp theo, thời gian chạy sẽ chỉ xử lý lần xuất hiện đầu tiên của cấu trúc XrSpatialBoundsBoxfANDROID trong chuỗi tiếp theo.

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

• Tiện ích XR_ANDROID_spatial_discovery_bounds phải được bật trước khi sử dụng XrSpatialBoundsBoxfANDROID
• type phải là XR_TYPE_SPATIAL_BOUNDS_BOXF_ANDROID
• 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
• space phải là một tên người dùng XrSpace hợp lệ

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

typedef struct XrSpatialBoundsFrustumfANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrFrustumf         frustum;
} XrSpatialBoundsFrustumfANDROID;

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.
• space là XrSpace mà mọi tư thế cho ranh giới đều được xác định trong đó.
• time là một XrTime mà tại đó các tư thế cho ranh giới được xác định.
• frustum là một XrFrustumf mô tả thể tích hình cụt mà trong đó thời gian chạy phải ràng buộc việc khám phá các thực thể không gian.

Các chức năng không gian hỗ trợ XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID (được liệt kê theo xrEnumerateSpatialCapabilityFeaturesEXT ) cho phép ứng dụng hạn chế việc khám phá đối với các thực thể không gian có vị trí hoặc ranh giới nằm trong hoặc giao nhau với frustum bằng cách liên kết XrSpatialBoundsFrustumfANDROID với XrSpatialDiscoverySnapshotCreateInfoEXT :: next . Đối với ảnh chụp nhanh khám phá trong đó chức năng hiện hành hỗ trợ XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID , nếu cấu trúc này có trong chuỗi next , thì thời gian chạy phải không bao gồm bất kỳ thực thể không gian nào có vị trí hoặc ranh giới hoàn toàn nằm ngoài frustum .

Điều quan trọng cần lưu ý là việc đưa XrSpatialBoundsFrustumfANDROID vào chuỗi tiếp theo của XrSpatialDiscoverySnapshotCreateInfoEXT đóng vai trò là điều kiện "VÀ" với các bộ lọc khác được cung cấp. Các thực thể đến từ những chức năng không gian không hỗ trợ XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID không được có trong ảnh chụp nhanh về hoạt động khám phá. Hành vi này khác với phần còn lại của thông số kỹ thuật OpenXR, trong đó các cấu trúc không được nhận dạng hoặc không được hỗ trợ trong chuỗi con trỏ tiếp theo sẽ bị thời gian chạy bỏ qua. Ngoài ra, như mô tả trong phần Tính duy nhất của cấu trúc chuỗi tiếp theo, thời gian chạy sẽ chỉ xử lý lần xuất hiện đầu tiên của cấu trúc XrSpatialBoundsFrustumfANDROID trong chuỗi tiếp theo.

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

• Bạn phải bật tiện ích XR_ANDROID_spatial_discovery_bounds trước khi sử dụng XrSpatialBoundsFrustumfANDROID
• type phải là XR_TYPE_SPATIAL_BOUNDS_FRUSTUMF_ANDROID
• 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
• space phải là một tên người dùng XrSpace hợp lệ

Ví dụ

Đoạn mã sau đây minh hoạ cách sử dụng ranh giới không gian để lọc kết quả khám phá thực thể không gian.

// previously initialized & configured with the XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT capability.
XrSpatialContextEXT spatialContext;

// Enumerate supported features for XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT capability
uint32_t featureCount = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, 0, &featureCount, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> fooFeatures(featureCount);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, featureCount, &featureCount, fooFeatures.data()));

// Check if spatial sphere bounds filter is supported
const auto supportsFeature = [&fooFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(fooFeatures.begin(), fooFeatures.end(), feature) != fooFeatures.end();
};

const bool supportsSphereBoundsFilter = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID);

// We want to look for entities in a sphere around the head with a radius of 2m.
XrSpatialBoundsSpherefANDROID sphereBounds {
  .type = XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID,
  .space = viewSpace,
  .time = predictedDisplayTime,
  .sphere = {
    .center = {
      .orientation = {
        .w = 1.0f,
      },
    },
    .radius = 2.0f,
  },
};

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

XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{
  .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
  .next = supportsSphereBoundsFilter ? &sphereBounds : nullptr,
  .componentTypeCount = snapshotComponents.size(),
  .componentTypes = snapshotComponents.data(),
};

XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

Cấu trúc mới

• Mở rộng XrSpatialDiscoverySnapshotCreateInfoEXT :

  • XrSpatialBoundsBoxfANDROID
  • XrSpatialBoundsFrustumfANDROID
  • XrSpatialBoundsSpherefANDROID

Hằng số enum mới

• XR_ANDROID_SPATIAL_DISCOVERY_BOUNDS_EXTENSION_NAME
• XR_ANDROID_spatial_discovery_bounds_SPEC_VERSION

• Mở rộng XrSpatialCapabilityFeatureEXT :

  • XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID
  • XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID
  • XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

• Mở rộng XrStructureType :

  • XR_TYPE_SPATIAL_BOUNDS_BOXF_ANDROID
  • XR_TYPE_SPATIAL_BOUNDS_FRUSTUMF_ANDROID
  • XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID

Vấn đề

• Tại sao việc hỗ trợ ranh giới không gian lại phụ thuộc vào định nghĩa XrSpatialCapabilityFeatureEXT?

  • Đã giải quyết
  • Đáp: Không phải chức năng không gian nào cũng có thể hỗ trợ ranh giới không gian. Ví dụ về điều này là một thực thể vùng chứa chung giả định không có bất kỳ vị trí hoặc ranh giới không gian nào của riêng nó mà chỉ giúp thu thập và sắp xếp các thực thể khác bên trong nó. Các giá trị XrSpatialCapabilityFeatureEXT được liệt kê theo chức năng giúp thông báo cho ứng dụng về khả năng hỗ trợ lọc ranh giới không gian.

Danh sách phiên bản

• Bản sửa đổi 1, ngày 3 tháng 5 năm 2025 (Nihav Jain, Google)

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