XR_ANDROID_spatial_discovery_bounds

Name String

XR_ANDROID_spatial_discovery_bounds

ประเภทส่วนขยาย

ส่วนขยายอินสแตนซ์

หมายเลขต่อที่ลงทะเบียนไว้

762

การแก้ไข

1

สถานะการให้สัตยาบัน

ไม่ได้รับการให้สัตยาบัน

ทรัพยากร Dependency ของส่วนขยายและเวอร์ชัน

XR_EXT_spatial_entity

ผู้เขียน

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

ภาพรวม

ส่วนขยายนี้จะเพิ่มคำจำกัดความสำหรับขอบเขตเชิงพื้นที่ที่ช่วยให้แอปพลิเคชันกรองเอนทิตีเชิงพื้นที่ที่ค้นพบเมื่อเรียกใช้ xrCreateSpatialDiscoverySnapshotAsyncEXT

ขอบเขตเชิงพื้นที่

โครงสร้าง XrSpatialBoundsSpherefANDROID มีคำจำกัดความดังนี้

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

คำอธิบายสมาชิก

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• space คือ XrSpace ที่กำหนดท่าทางสำหรับขอบเขตไว้
• time คือ XrTime ที่กำหนดท่าทางสำหรับขอบเขต
• sphere คือ XrSpheref ซึ่งอธิบายปริมาตรทรงกลมที่รันไทม์ต้องจำกัดการค้นหาเอนทิตีเชิงพื้นที่

ความสามารถเชิงพื้นที่ที่รองรับ XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID (ตามที่ระบุโดย xrEnumerateSpatialCapabilityFeaturesEXT) ช่วยให้แอปพลิเคชันจำกัดการค้นพบไว้เฉพาะเอนทิตีเชิงพื้นที่ที่มีตำแหน่งหรือขอบเขตอยู่ภายในหรือตัดกับ sphere โดยเชื่อมโยง XrSpatialBoundsSpherefANDROID กับ XrSpatialDiscoverySnapshotCreateInfoEXT :: next สำหรับสแนปชอตการค้นพบที่ความสามารถที่เกี่ยวข้องรองรับ XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID หากโครงสร้างนี้ปรากฏในเชน next รันไทม์ต้องไม่รวมเอนทิตีเชิงพื้นที่ที่มีตำแหน่งหรือขอบเขตอยู่นอก sphere โดยสิ้นเชิง

โปรดทราบว่าการรวม XrSpatialBoundsSpherefANDROID ไว้ในเชนถัดไปของ XrSpatialDiscoverySnapshotCreateInfoEXT จะทำหน้าที่เป็นเงื่อนไข "AND" กับตัวกรองอื่นๆ ที่ระบุ เอนทิตีที่มาจากความสามารถเชิงพื้นที่ซึ่งไม่รองรับ XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID ต้องไม่รวมอยู่ในภาพรวมการค้นพบ ลักษณะการทำงานนี้แตกต่างจากข้อกำหนดอื่นๆ ของ OpenXR ซึ่งรันไทม์จะละเว้นโครงสร้างที่ไม่รู้จักหรือไม่รองรับในเชนตัวชี้ถัดไป นอกจากนี้ ตามที่อธิบายไว้ในส่วนความไม่ซ้ำกันของโครงสร้าง Next Chain รันไทม์จะประมวลผลเฉพาะโครงสร้าง XrSpatialBoundsSpherefANDROID ที่เกิดขึ้นครั้งแรกใน Next Chain

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_spatial_discovery_bounds ก่อนใช้ XrSpatialBoundsSpherefANDROID
• type ต้องเป็น XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• space ต้องเป็นแฮนเดิล XrSpace ที่ถูกต้อง

โครงสร้าง XrSpatialBoundsBoxfANDROID มีคำจำกัดความดังนี้

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

คำอธิบายสมาชิก

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• space คือ XrSpace ที่กำหนดท่าทางสำหรับขอบเขตไว้
• time คือ XrTime ที่กำหนดท่าทางสำหรับขอบเขต
• box คือ XrBoxf ซึ่งอธิบายปริมาตรของกล่องที่รันไทม์ต้องจำกัดการค้นหาเอนทิตีเชิงพื้นที่

ความสามารถเชิงพื้นที่ที่รองรับ XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID (ตามที่แจกแจงโดย xrEnumerateSpatialCapabilityFeaturesEXT) ช่วยให้แอปพลิเคชันจำกัดการค้นหาไว้เฉพาะเอนทิตีเชิงพื้นที่ที่มีตำแหน่งหรือขอบเขตอยู่ภายในหรือตัดกับ box โดยเชื่อมโยง XrSpatialBoundsBoxfANDROID กับ XrSpatialDiscoverySnapshotCreateInfoEXT :: next สำหรับสแนปชอตการค้นพบที่ความสามารถที่เกี่ยวข้องรองรับ XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID หากโครงสร้างนี้ปรากฏในเชน next รันไทม์ต้องไม่รวมเอนทิตีเชิงพื้นที่ที่มีตำแหน่งหรือขอบเขตอยู่นอก box โดยสิ้นเชิง

โปรดทราบว่าการรวม XrSpatialBoundsBoxfANDROID ไว้ในเชนถัดไปของ XrSpatialDiscoverySnapshotCreateInfoEXT จะทำหน้าที่เป็นเงื่อนไข "AND" ร่วมกับตัวกรองอื่นๆ ที่ระบุ เอนทิตีที่มาจากความสามารถเชิงพื้นที่ซึ่งไม่รองรับ XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID ต้องไม่รวมอยู่ในภาพรวมการค้นพบ ลักษณะการทำงานนี้แตกต่างจากข้อกำหนดอื่นๆ ของ OpenXR ซึ่งรันไทม์จะละเว้นโครงสร้างที่ไม่รู้จักหรือไม่รองรับในเชนตัวชี้ถัดไป นอกจากนี้ ตามที่อธิบายไว้ในส่วนความไม่ซ้ำกันของโครงสร้างเชนถัดไป รันไทม์จะประมวลผลเฉพาะการปรากฏครั้งแรกของโครงสร้าง XrSpatialBoundsBoxfANDROID ในเชนถัดไป

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_spatial_discovery_bounds ก่อนใช้ XrSpatialBoundsBoxfANDROID
• type ต้องเป็น XR_TYPE_SPATIAL_BOUNDS_BOXF_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• space ต้องเป็นแฮนเดิล XrSpace ที่ถูกต้อง

โครงสร้าง XrSpatialBoundsFrustumfANDROID มีคำจำกัดความดังนี้

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

คำอธิบายสมาชิก

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• space คือ XrSpace ที่กำหนดท่าทางสำหรับขอบเขตไว้
• time คือ XrTime ที่กำหนดท่าทางสำหรับขอบเขต
• frustum คือ XrFrustumf ซึ่งอธิบายปริมาตรของฟรัสตัมที่รันไทม์ต้องจำกัดการค้นหาเอนทิตีเชิงพื้นที่

ความสามารถเชิงพื้นที่ที่รองรับ XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID (ตามที่ระบุโดย xrEnumerateSpatialCapabilityFeaturesEXT) ช่วยให้แอปพลิเคชันจำกัดการค้นพบไว้เฉพาะเอนทิตีเชิงพื้นที่ที่มีตำแหน่งหรือขอบเขตอยู่ภายในหรือตัดกับ frustum โดยเชื่อมโยง XrSpatialBoundsFrustumfANDROID กับ XrSpatialDiscoverySnapshotCreateInfoEXT :: next สำหรับสแนปชอตการค้นพบที่ความสามารถที่เกี่ยวข้องรองรับ XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID หากโครงสร้างนี้ปรากฏในเชน next รันไทม์ต้องไม่รวมเอนทิตีเชิงพื้นที่ที่มีตำแหน่งหรือขอบเขตอยู่นอก frustum โดยสิ้นเชิง

โปรดทราบว่าการรวม XrSpatialBoundsFrustumfANDROID ไว้ในเชนถัดไปของ XrSpatialDiscoverySnapshotCreateInfoEXT จะทำหน้าที่เป็นเงื่อนไข "AND" กับตัวกรองอื่นๆ ที่ระบุ เอนทิตีที่มาจากความสามารถเชิงพื้นที่ซึ่งไม่รองรับ XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID ต้องไม่รวมอยู่ในภาพรวมการค้นพบ ลักษณะการทำงานนี้แตกต่างจากข้อกำหนดอื่นๆ ของ OpenXR ซึ่งรันไทม์จะละเว้นโครงสร้างที่ไม่รู้จักหรือไม่รองรับในเชนตัวชี้ถัดไป นอกจากนี้ ตามที่อธิบายไว้ในส่วนความไม่ซ้ำกันของโครงสร้างเชนถัดไป รันไทม์จะประมวลผลเฉพาะโครงสร้าง XrSpatialBoundsFrustumfANDROID ที่เกิดขึ้นครั้งแรกในเชนถัดไปเท่านั้น

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_spatial_discovery_bounds ก่อนใช้ XrSpatialBoundsFrustumfANDROID
• type ต้องเป็น XR_TYPE_SPATIAL_BOUNDS_FRUSTUMF_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• space ต้องเป็นแฮนเดิล XrSpace ที่ถูกต้อง

ตัวอย่าง

โค้ดต่อไปนี้แสดงวิธีใช้ขอบเขตเชิงพื้นที่เพื่อกรองการค้นพบเอนทิตีเชิงพื้นที่

// 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));

โครงสร้างใหม่

• การขยาย XrSpatialDiscoverySnapshotCreateInfoEXT :

  • XrSpatialBoundsBoxfANDROID
  • XrSpatialBoundsFrustumfANDROID
  • XrSpatialBoundsSpherefANDROID

ค่าคงที่ Enum ใหม่

• XR_ANDROID_SPATIAL_DISCOVERY_BOUNDS_EXTENSION_NAME
• XR_ANDROID_spatial_discovery_bounds_SPEC_VERSION

• การขยาย 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

• การขยาย XrStructureType :

  • XR_TYPE_SPATIAL_BOUNDS_BOXF_ANDROID
  • XR_TYPE_SPATIAL_BOUNDS_FRUSTUMF_ANDROID
  • XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID

ปัญหา

• เหตุใดการรองรับขอบเขตเชิงพื้นที่จึงขึ้นอยู่กับคำจำกัดความของ XrSpatialCapabilityFeatureEXT

  • แก้ไขแล้ว
  • คำตอบ: ความสามารถเชิงพื้นที่บางอย่างไม่สามารถรองรับขอบเขตเชิงพื้นที่ได้ ตัวอย่างเช่น เอนทิตีคอนเทนเนอร์ส่วนกลางสมมติที่ไม่มีตำแหน่งเชิงพื้นที่หรือขอบเขตของตัวเอง แต่ช่วยรวบรวมและจัดระเบียบเอนทิตีอื่นๆ ภายในเท่านั้น ค่า XrSpatialCapabilityFeatureEXT ที่แจกแจงตามความสามารถจะช่วยแจ้งให้แอปทราบเกี่ยวกับการรองรับการกรองขอบเขตเชิงมิติพื้นที่

ประวัติเวอร์ชัน

• การแก้ไข 1, 03-05-2025 (Nihav Jain, Google)

  • คำอธิบายส่วนขยายเริ่มต้น