XR_EXT_spatial_image_tracking

Name String

XR_EXT_spatial_image_tracking

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

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

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

783

การแก้ไข

1

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

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

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

XR_EXT_spatial_entity

ผู้เขียน

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

ภาพรวม

ส่วนขยายนี้ให้ความสามารถในการติดตามรูปภาพสำหรับส่วนขยาย XR_EXT_spatial_entity ซึ่งช่วยให้แอปพลิเคชันตรวจจับและติดตามรูปภาพระนาบที่เฉพาะเจาะจงตามที่ระบุไว้ในชุดรูปภาพอ้างอิงที่ป้อนได้

รูปภาพที่ติดตามจะแสดงเป็นเอนทิตีเชิงพื้นที่ที่มีคอมโพเนนต์ต่อไปนี้

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

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

  • แอปพลิเคชันจะสร้างแฮนเดิล XrSpatialImageTrackingDatabaseEXT อย่างน้อย 1 รายการก่อน โดยอิงตามชุดข้อมูลรูปภาพอ้างอิงที่โหลดไว้ล่วงหน้า
  • จากนั้นแอปพลิเคชันจะสร้างแฮนเดิล XrSpatialContextEXT โดยอิงตามแฮนเดิล XrSpatialImageTrackingDatabaseEXT ที่สร้างไว้ก่อนหน้านี้
  • จากนั้นแอปพลิเคชันจะปล่อยข้อมูลรูปภาพอ้างอิงเพื่อลดการใช้หน่วยความจำ
  • แอปพลิเคชันจะค้นพบและค้นหารูปภาพตามรูปแบบการเข้าถึงเอนทิตีเชิงพื้นที่
  • แอปพลิเคชันสามารถโหลดชุดรูปภาพอ้างอิงเพิ่มเติมและสร้าง XrSpatialImageTrackingDatabaseEXT เพิ่มเติม และสร้าง XrSpatialContextEXT จากรูปภาพเหล่านั้นเพื่อขยายชุดรูปภาพที่ตรวจจับและติดตามได้แบบไดนามิกขณะรันไทม์
  • แอปพลิเคชันสามารถทำลายแฮนเดิล XrSpatialImageTrackingDatabaseEXT เพื่อลดชุดรูปภาพที่ตรวจจับและติดตามได้แบบไดนามิกขณะรันไทม์
  • แอปพลิเคชันสามารถทำลายแฮนเดิล XrSpatialContextEXT เพื่อลดชุดรูปภาพที่ตรวจจับและติดตามได้แบบไดนามิกขณะรันไทม์

การสนับสนุนรันไทม์

รันไทม์ต้องโฆษณาการรองรับความสามารถในการติดตามรูปภาพโดยใช้ xrEnumerateSpatialCapabilitiesEXT โดยระบุความสามารถต่อไปนี้

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

การกำหนดค่า

หากต้องการเปิดใช้การตรวจจับและการติดตามรูปภาพระนาบ แอปพลิเคชันสามารถส่งโครงสร้าง XrSpatialCapabilityConfigurationImageTrackingEXT ใน XrSpatialContextCreateInfoEXT :: capabilityConfigs เมื่อเรียกใช้ฟังก์ชัน xrCreateSpatialContextAsyncEXT และส่งอาร์เรย์ของโครงสร้าง< XrSpatialImageTrackingDatabaseEXT ใน XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases แต่ละรายการ

การสร้างชุดรูปภาพที่ป้อนเข้ามา

หากต้องการระบุรูปภาพอ้างอิงที่จะตรวจจับและติดตาม แอปพลิเคชันต้องสร้างรูปภาพอ้างอิงอินพุตอย่างน้อย 1 ชุด ชุดรูปภาพอ้างอิงอินพุตจะแสดงด้วยแฮนเดิล XrSpatialImageTrackingDatabaseEXT และมีรูปภาพอย่างน้อย 1 รูป

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

แฮนเดิล XrSpatialImageTrackingDatabaseEXT แสดงถึงทรัพยากรสำหรับการค้นพบและอัปเดตรูปภาพเชิงพื้นที่จำนวนหนึ่งในสภาพแวดล้อมของผู้ใช้ แอปพลิเคชันสามารถใช้แฮนเดิลนี้เพื่อค้นหาและอัปเดตรูปภาพเชิงพื้นที่โดยใช้ฟังก์ชันอื่นๆ ในส่วนขยายนี้

สร้างฐานข้อมูลการติดตามรูปภาพเชิงพื้นที่

ฟังก์ชัน xrCreateSpatialImageTrackingDatabaseAsyncEXT มีคำจำกัดความดังนี้

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

คำอธิบายพารามิเตอร์

  • session คือ XrSession ที่ฐานข้อมูลการติดตามรูปภาพเชิงพื้นที่ทำงานอยู่
  • createInfo คือ XrSpatialImageTrackingDatabaseCreateInfoEXT ที่ใช้ระบุพารามิเตอร์ฐานข้อมูลการติดตามรูปภาพเชิงมิติพื้นที่
  • future เป็นตัวชี้ไปยัง XrFutureEXT

แอปพลิเคชันสามารถสร้างแฮนเดิล XrSpatialImageTrackingDatabaseEXT โดยใช้ฟังก์ชัน xrCreateSpatialImageTrackingDatabaseAsyncEXT และกำหนดค่าชุดรูปภาพอ้างอิงอินพุตของฐานข้อมูลการติดตามรูปภาพด้วย createInfo

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT หาก XrSpatialReferenceImageEXT :: format ของรูปภาพอ้างอิงอินพุตใดๆ ไม่ได้แจกแจงโดย xrEnumerateSpatialReferenceImageFormatsEXT

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_IMAGE_INVALID_EXT หากอาร์เรย์ planes ของ XrSpatialReferenceImageEXT :: รูปภาพอ้างอิงอินพุตใดๆ ไม่สามารถประเมินตามข้อมูลเมตาของรูปภาพอ้างอิงของ XrSpatialReferenceImageEXT

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_IMAGE_INVALID_EXT หากอาร์เรย์ XrSpatialReferenceImageEXT :: planes ของรูปภาพอ้างอิงอินพุตใดๆ มีระนาบไม่เท่ากับจำนวนช่องสีที่ XrSpatialReferenceImageEXT :: format มี

หากรันไทม์บังคับใช้ระบบสิทธิ์เพื่อควบคุมการเข้าถึงของแอปพลิเคชันไปยังความสามารถในการติดตามรูปภาพ รันไทม์ต้องแสดงผล XR_ERROR_PERMISSION_INSUFFICIENT หากแอปพลิเคชันนี้ไม่ได้รับสิทธิ์เหล่านั้น

ฟังก์ชันนี้จะเริ่มการดำเนินการแบบอะซิงโครนัสและสร้าง XrFutureEXT ที่เกี่ยวข้อง ซึ่งใช้ได้กับ xrPollFutureEXT และฟังก์ชันที่เกี่ยวข้อง ค่าที่แสดงผลของฟังก์ชันนี้จะระบุเฉพาะว่าพารามิเตอร์ยอมรับได้หรือไม่ในการกำหนดเวลาการดำเนินการแบบอะซิงโครนัส ฟังก์ชันการดำเนินการให้เสร็จสมบูรณ์ที่เกี่ยวข้องคือ xrCreateSpatialImageTrackingDatabaseCompleteEXT ซึ่งใช้ได้เมื่อ Future จากฟังก์ชันนี้อยู่ในสถานะ READY โดยมีเอาต์พุตที่สร้างโดยฟังก์ชันนั้นในโครงสร้างการดำเนินการให้เสร็จสมบูรณ์ XrCreateSpatialImageTrackingDatabaseCompletionEXT

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

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_image_tracking ก่อนเรียกใช้ xrCreateSpatialImageTrackingDatabaseAsyncEXT
  • session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
  • createInfo ต้องเป็นพอยเตอร์ไปยังโครงสร้าง XrSpatialImageTrackingDatabaseCreateInfoEXT ที่ถูกต้อง
  • future ต้องเป็นตัวชี้ไปยังค่า XrFutureEXT

รหัสการคืนสินค้า

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • 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

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

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

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • spatialReferenceImageCount คือจำนวนองค์ประกอบในอาร์เรย์ spatialReferenceImages
  • spatialReferenceImages คืออาร์เรย์ของ XrSpatialReferenceImageEXT

โครงสร้าง XrSpatialImageTrackingDatabaseCreateInfoEXT อธิบายข้อมูลเพื่อสร้างแฮนเดิล XrSpatialImageTrackingDatabaseEXT

XrSpatialImageTrackingDatabaseEXT แต่ละรายการต้องสร้างขึ้นโดยมี XrSpatialReferenceImageEXT อย่างน้อย 1 รายการในอาร์เรย์ XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages

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

ฟังก์ชัน xrCreateSpatialImageTrackingDatabaseCompleteEXT มีคำจำกัดความดังนี้

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

คำอธิบายพารามิเตอร์

xrCreateSpatialImageTrackingDatabaseCompleteEXT จะดำเนินการแบบอะซิงโครนัสที่เริ่มต้นโดย xrCreateSpatialImageTrackingDatabaseAsyncEXT ให้เสร็จสมบูรณ์

รันไทม์ต้องไม่เข้าถึงพอยน์เตอร์ XrSpatialReferenceImagePlaneEXT :: buffer ที่ได้จากอาร์เรย์อินพุต XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages สำหรับการเรียก xrCreateSpatialImageTrackingDatabaseAsyncEXT นี้หลังจากที่ดำเนินการเสร็จสมบูรณ์แล้ว แอปพลิเคชันอาจเพิ่มพื้นที่ว่างให้กับข้อมูล XrSpatialReferenceImagePlaneEXT :: buffer หลังจากที่ xrCreateSpatialImageTrackingDatabaseAsyncEXT ทำงานเสร็จสมบูรณ์เพื่อลดหน่วยความจำที่ใช้

รันไทม์ต้องแสดงผล XR_ERROR_FUTURE_PENDING_EXT หาก future ไม่อยู่ในสถานะพร้อมใช้งาน รันไทม์ต้องแสดงผล XR_ERROR_FUTURE_INVALID_EXT หาก future เสร็จสมบูรณ์หรือถูกยกเลิกไปแล้ว

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

รหัสการคืนสินค้า

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • 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

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

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

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • futureResult คือ XrResult ของการดำเนินการสร้างฐานข้อมูลการติดตามรูปภาพเชิงพื้นที่
  • database คือ XrSpatialImageTrackingDatabaseEXT ที่สร้างขึ้นโดยใช้ข้อมูลและการกำหนดค่าใน xrCreateSpatialImageTrackingDatabaseAsyncEXT :: createInfo

รหัสการคืนสินค้าในอนาคต

ค่า futureResult:

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • 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

หาก futureResult เป็นรหัสความสำเร็จ database ต้องเป็นแฮนเดิลที่ถูกต้อง หาก database ถูกต้อง จะยังคงถูกต้องภายในวงจรของ xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session หรือจนกว่าแอปพลิเคชันจะทำลาย database ด้วย xrDestroySpatialImageTrackingDatabaseEXT แล้วแต่ว่าอย่างใดจะเกิดขึ้นก่อน

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

ทำลายฐานข้อมูลการติดตามรูปภาพเชิงพื้นที่

ฟังก์ชัน xrDestroySpatialImageTrackingDatabaseEXT มีคำจำกัดความดังนี้

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

คำอธิบายพารามิเตอร์

แอปพลิเคชันสามารถเรียกใช้ฟังก์ชัน xrDestroySpatialImageTrackingDatabaseEXT เพื่อปล่อยแฮนเดิล database และทรัพยากรที่เกี่ยวข้องเมื่อการค้นหารูปภาพเชิงพื้นที่และงานอัปเดตเสร็จสิ้น

แอปพลิเคชันสามารถเรียกใช้ฟังก์ชัน xrDestroySpatialImageTrackingDatabaseEXT ก่อนเรียกใช้ xrDestroySpatialContextEXT รันไทม์ต้องไม่รายงานรูปภาพที่จัดการโดย XrSpatialImageTrackingDatabaseEXT ที่ถูกทำลายนี้อีกต่อไป รันไทม์ต้องรายงานรูปภาพที่จัดการโดยฐานข้อมูลอื่นๆ ต่อไป

รันไทม์ต้องตรวจสอบว่าสแนปชอตการค้นพบที่แสดงผลโดย xrCreateSpatialDiscoverySnapshotCompleteEXT ไม่มีรูปภาพที่เกี่ยวข้องกับแฮนเดิล XrSpatialImageTrackingDatabaseEXT ที่ถูกทำลายหรือไม่ถูกต้อง แม้ว่าแฮนเดิลจะถูกทำลายหลังจากแอปพลิเคชันเรียกใช้ xrCreateSpatialDiscoverySnapshotAsyncEXT ก็ตาม เนื่องจากข้อมูลในสแนปชอตเชิงพื้นที่เปลี่ยนแปลงไม่ได้ แอปพลิเคชันควรทำลายแฮนเดิล XrSpatialSnapshotEXT ที่สร้างขึ้นก่อนที่จะทำลาย database มิฉะนั้นแอปพลิเคชันอาจได้รับแฮนเดิล XrSpatialImageTrackingDatabaseEXT ที่ไม่ถูกต้องเมื่อใช้ xrQuerySpatialComponentDataEXT

แอปพลิเคชันสามารถเรียกใช้ฟังก์ชัน xrDestroySpatialContextEXT เพื่อปล่อยแฮนเดิล XrSpatialContextEXT ก่อนที่จะทำลายแฮนเดิล XrSpatialImageTrackingDatabaseEXT ที่สร้าง XrSpatialContextEXT ขึ้นมา รันไทม์ต้องไม่ทำลายแฮนเดิล XrSpatialImageTrackingDatabaseEXT เหล่านี้โดยนัยเมื่อทำลาย XrSpatialContextEXT

การจัดการอายุการใช้งานของ XrSpatialContextEXT และ XrSpatialImageTrackingDatabaseEXT อย่างเป็นอิสระช่วยให้แอปพลิเคชันสามารถนำแฮนเดิล XrSpatialImageTrackingDatabaseEXT ที่สร้างไว้ก่อนหน้านี้มาใช้ซ้ำได้โดยไม่ต้องทำตามขั้นตอนการสร้างที่มีค่าใช้จ่ายสูงอีกครั้ง

ตัวอย่างเช่น การทำลาย XrSpatialContextEXT แล้วสร้าง XrSpatialContextEXT ขึ้นมาใหม่ด้วย XrSpatialImageTrackingDatabaseEXT เดียวกันจะช่วยให้หยุดชั่วคราวและกลับมาติดตามรูปภาพต่อได้โดยไม่ต้องทำตามขั้นตอนการเริ่มต้นอีกครั้ง

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

ความปลอดภัยของชุดข้อความ

  • การเข้าถึง database และแฮนเดิลย่อยต้องซิงค์กับภายนอก

รหัสการคืนสินค้า

สำเร็จ

  • XR_SUCCESS

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

การรองรับรูปแบบรูปภาพที่ป้อนเข้ามา

แอปพลิเคชันควรเรียกใช้ xrEnumerateSpatialReferenceImageFormatsEXT เพื่อดูรายการรูปแบบรูปภาพอ้างอิงอินพุตที่รองรับ

ฟังก์ชัน xrEnumerateSpatialReferenceImageFormatsEXT มีคำจำกัดความดังนี้

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

คำอธิบายพารามิเตอร์

  • instance เป็นแฮนเดิลของ XrInstance
  • systemId คือ XrSystemId ที่จะแจกแจงรูปแบบรูปภาพอ้างอิงอินพุต
  • capability คือ XrSpatialCapabilityEXT ซึ่งจะมีการแจกแจงรูปแบบรูปภาพอ้างอิงอินพุต
  • formatCapacityInput คือความจุของอาร์เรย์ formats หรือ 0 เพื่อระบุคำขอให้ดึงข้อมูลความจุที่จำเป็น
  • formatCountOutput คือจำนวนรูปแบบ หรือความจุที่จำเป็นในกรณีที่ formatCapacityInput ไม่เพียงพอ
  • formats คืออาร์เรย์ของ XrSpatialReferenceImageFormatEXT สามารถเป็น NULL ได้หาก formatCapacityInput เป็น 0
  • ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด formats ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถแจกแจงรายการรูปแบบรูปภาพอ้างอิงอินพุตที่ XrSystemId หนึ่งๆ รองรับสำหรับ XrSpatialCapabilityEXT หนึ่งๆ โดยใช้ xrEnumerateSpatialReferenceImageFormatsEXT

รันไทม์ต้องไม่แจกแจงรูปแบบของส่วนขยายที่ไม่ได้เปิดใช้สำหรับ instance

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

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_image_tracking ก่อนเรียกใช้ xrEnumerateSpatialReferenceImageFormatsEXT
  • instance ต้องเป็นแฮนเดิล XrInstance ที่ถูกต้อง
  • capability ต้องเป็นค่า XrSpatialCapabilityEXT ที่ถูกต้อง
  • formatCountOutput ต้องเป็นตัวชี้ไปยังค่า uint32_t
  • หาก formatCapacityInput ไม่ใช่ 0 formats ต้องเป็นพอยเตอร์ไปยังอาร์เรย์ของค่า formatCapacityInput XrSpatialReferenceImageFormatEXT

รหัสการคืนสินค้า

สำเร็จ

  • XR_SUCCESS

ความล้มเหลว

  • 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

ดูรายการรูปแบบรูปภาพอ้างอิงทั้งหมดที่ส่วนขยายรองรับได้ที่ XrSpatialReferenceImageFormatEXT

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;

การแจงนับ XrSpatialReferenceImageFormatEXT จะระบุรูปแบบรูปภาพอ้างอิงอินพุตที่รันไทม์อาจรองรับ

ต้องรองรับค่า XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT และค่า XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT เป็นอย่างน้อย

ค่าแจงนับมีความหมายดังนี้

คำอธิบาย Enumerant

  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT — บัฟเฟอร์ RGBA รูปแบบนี้ไม่รับประกันเกี่ยวกับเลย์เอาต์ของข้อมูลพิกเซลในหน่วยความจำ พิกเซลต้องเข้าถึงได้โดยใช้ข้อมูลเมตาที่ได้จากโครงสร้าง XrSpatialReferenceImagePlaneEXT ที่เกี่ยวข้อง ช่องสีของพิกเซลแต่ละช่องมีขนาด 8 บิต ทำให้พิกเซลแต่ละพิกเซลมีขนาด 32 บิต
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT — บัฟเฟอร์ RGB รูปแบบนี้ไม่รับประกันเกี่ยวกับเลย์เอาต์ของข้อมูลพิกเซลในหน่วยความจำ พิกเซลต้องเข้าถึงได้โดยใช้ข้อมูลเมตาที่ได้จากโครงสร้าง XrSpatialReferenceImagePlaneEXT ที่เกี่ยวข้อง ช่องสีของแต่ละพิกเซลมีขนาด 8 บิต ทำให้แต่ละพิกเซลมีขนาด 24 บิต
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT — บัฟเฟอร์ YUV ที่มีการสุ่มตัวอย่างโครมาแบบ 4:2:0 รูปแบบนี้ไม่รับประกันเกี่ยวกับเลย์เอาต์ของข้อมูลพิกเซลในหน่วยความจำ พิกเซลต้องเข้าถึงได้โดยใช้ข้อมูลเมตาที่ได้จากโครงสร้าง XrSpatialReferenceImagePlaneEXT ที่เกี่ยวข้อง ช่องสีพิกเซล RGB ที่ถอดรหัสแล้วแต่ละช่องมีขนาด 8 บิต ทำให้แต่ละพิกเซลมีขนาด 24 บิต

การตั้งค่าการติดตามรูปภาพเชิงพื้นที่

ส่วนขยายนี้มีโครงสร้างที่ไม่บังคับซึ่งแอปพลิเคชันสามารถใช้เพื่อกำหนดค่าความสามารถในการติดตามรูปภาพได้

การเพิ่มประสิทธิภาพภาพนิ่ง

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

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

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • optimizeForStaticImage คือ XrBool32 ที่ระบุว่ารูปภาพเคลื่อนไหวหรือไม่ ค่า XR_TRUE บ่งบอกว่ารูปภาพไม่เคลื่อนไหว

หาก XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT มีการแจกแจงโดย xrEnumerateSpatialCapabilityFeaturesEXT สำหรับความสามารถ XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT แอปพลิเคชันสามารถเชื่อมโยง XrSpatialImageStaticOptimizationEXT กับเชน XrSpatialImageTrackingDatabaseCreateInfoEXT :: next หรือ XrSpatialReferenceImageEXT :: next

หากแอปพลิเคชันเชื่อมโยง XrSpatialImageStaticOptimizationEXT กับโครงสร้าง XrSpatialImageTrackingDatabaseCreateInfoEXT รันไทม์ต้องถือว่ารูปภาพทั้งหมดของ XrSpatialImageTrackingDatabaseEXT นั้นเป็นแบบคงที่หากตั้งค่า optimizeForStaticImage เป็น XR_TRUE ดังนั้น รันไทม์ต้องถือว่ารูปภาพทั้งหมดของ XrSpatialImageTrackingDatabaseEXT นั้นไม่คงที่หากตั้งค่า optimizeForStaticImage เป็น XR_FALSE

หากแอปพลิเคชันเชื่อมโยง XrSpatialImageStaticOptimizationEXT กับโครงสร้าง XrSpatialReferenceImageEXT รันไทม์ต้องถือว่ารูปภาพอ้างอิงนี้เป็นแบบคงที่หากตั้งค่า optimizeForStaticImage เป็น XR_TRUE ดังนั้น รันไทม์ต้องถือว่ารูปภาพอ้างอิงนี้ไม่ใช่แบบคงที่หากตั้งค่า optimizeForStaticImage เป็น XR_FALSE การเชื่อมโยงโครงสร้าง XrSpatialImageStaticOptimizationEXT กับโครงสร้าง XrSpatialReferenceImageEXT จะมีความสำคัญเหนือกว่าการเชื่อมโยงกับโครงสร้าง XrSpatialImageTrackingDatabaseCreateInfoEXT

หาก XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT ไม่ได้แจกแจงโดย xrEnumerateSpatialCapabilityFeaturesEXT สำหรับความสามารถ XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT และแอปพลิเคชันเชื่อมโยงโครงสร้าง XrSpatialImageStaticOptimizationEXT กับเชนถัดไปที่เกี่ยวข้อง รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE จาก xrCreateSpatialImageTrackingDatabaseAsyncEXT

ซึ่งอาจช่วยให้รันไทม์สร้างท่าทางและขนาดที่แม่นยำยิ่งขึ้น

ซึ่งอาจช่วยให้รันไทม์ลดการใช้พลังงานได้

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

ความกว้างของรูปภาพอ้างอิง

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

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

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • physicalWidth คือค่า float ที่แสดงความกว้างทางกายภาพเป็นเมตรที่จะตั้งค่า

หาก XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT มีการแจกแจงโดย xrEnumerateSpatialCapabilityFeaturesEXT สำหรับความสามารถ XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT แอปพลิเคชันสามารถเชื่อมโยง XrSpatialImageSizeEXT กับ XrSpatialImageTrackingDatabaseCreateInfoEXT :: next หรือ XrSpatialReferenceImageEXT :: next

หากแอปพลิเคชันเชื่อมโยง XrSpatialImageSizeEXT กับโครงสร้าง XrSpatialImageTrackingDatabaseCreateInfoEXT รันไทม์ต้องถือว่ารูปภาพทั้งหมดของ XrSpatialImageTrackingDatabaseEXT นั้นมีความกว้าง physicalWidth เมตร และมีความสูงตามสัดส่วนภาพที่ระบุโดยนัยผ่าน XrSpatialReferenceImageEXT :: width และ XrSpatialReferenceImageEXT :: height

หากแอปพลิเคชันเชื่อมโยง XrSpatialImageSizeEXT กับโครงสร้าง XrSpatialReferenceImageEXT รันไทม์ต้องถือว่ารูปภาพอ้างอิงนี้มีความกว้าง physicalWidth เมตรและความสูงตามสัดส่วนภาพที่ระบุโดยนัยผ่าน XrSpatialReferenceImageEXT :: width และ XrSpatialReferenceImageEXT :: height การเชื่อมโยงโครงสร้าง XrSpatialImageSizeEXT กับโครงสร้าง XrSpatialReferenceImageEXT จะมีความสำคัญเหนือกว่าการเชื่อมโยงกับโครงสร้าง XrSpatialImageTrackingDatabaseCreateInfoEXT

ซึ่งอาจช่วยให้รันไทม์แสดงท่าทางและขนาดที่แม่นยำยิ่งขึ้น

รันไทม์ต้องแจกแจง XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT หรือ XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT หรือทั้ง 2 อย่าง

หาก XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT มีการแจกแจงโดย xrEnumerateSpatialCapabilityFeaturesEXT รันไทม์ต้องระบุขนาดรูปภาพโดยอัตโนมัติสำหรับรูปภาพที่แอปพลิเคชันไม่ได้ระบุโครงสร้าง XrSpatialImageSizeEXT ไว้เป็นส่วนหนึ่งของเชนถัดไปที่เกี่ยวข้อง

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

หาก XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT ไม่ได้แจกแจงโดย xrEnumerateSpatialCapabilityFeaturesEXT แอปพลิเคชันต้องลิงก์โครงสร้าง XrSpatialImageSizeEXT เข้ากับเชนถัดไปที่เกี่ยวข้อง เพื่อให้รูปภาพทั้งหมดมีขนาดที่ชัดเจน มิฉะนั้นรันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT จาก xrCreateSpatialImageTrackingDatabaseAsyncEXT

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

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

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

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • capability เป็น XrSpatialCapabilityEXT และต้องเป็น XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT
  • enabledComponentCount เป็น uint32_t ที่ระบุจำนวนเอลิเมนต์ใน enabledComponents
  • enabledComponents คืออาร์เรย์ของ XrSpatialComponentTypeEXT ที่ระบุคอมโพเนนต์ที่จะเปิดใช้สำหรับความสามารถนี้
  • imageTrackingDatabaseCount เป็น unint32_t ที่ระบุจำนวนเอลิเมนต์ใน imageTrackingDatabases
  • imageTrackingDatabases คืออาร์เรย์ของแฮนเดิล XrSpatialImageTrackingDatabaseEXT ที่ระบุฐานข้อมูลการติดตามรูปภาพที่จะเปิดใช้สำหรับบริบทเชิงพื้นที่

หากรองรับการติดตามรูปภาพ รันไทม์ต้องเปิดใช้การติดตามรูปภาพหากมีการส่งโครงสร้าง XrSpatialCapabilityConfigurationImageTrackingEXT ใน XrSpatialContextCreateInfoEXT :: capabilityConfigs เมื่อเรียกใช้ xrCreateSpatialContextAsyncEXT

โครงสร้าง XrSpatialCapabilityConfigurationImageTrackingEXT ช่วยให้แอปพลิเคชันค้นพบรูปภาพอ้างอิงที่แฮนเดิล XrSpatialImageTrackingDatabaseEXT แสดงใน imageTrackingDatabases

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT หาก XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT ไม่ได้แจกแจงโดย xrEnumerateSpatialCapabilitiesEXT

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

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_image_tracking ก่อนใช้ XrSpatialCapabilityConfigurationImageTrackingEXT
  • type ต้องเป็น XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
  • next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • capability ต้องเป็นค่า XrSpatialCapabilityEXT ที่ถูกต้อง
  • enabledComponents ต้องเป็นตัวชี้ไปยังอาร์เรย์ของค่า XrSpatialComponentTypeEXT ที่ถูกต้อง enabledComponentCount ค่า
  • imageTrackingDatabases ต้องเป็นตัวชี้ไปยังอาร์เรย์ของแฮนเดิล imageTrackingDatabaseCount XrSpatialImageTrackingDatabaseEXT ที่ถูกต้อง
  • พารามิเตอร์ enabledComponentCount ต้องมากกว่า 0
  • พารามิเตอร์ imageTrackingDatabaseCount ต้องมากกว่า 0

รูปภาพอ้างอิงเชิงพื้นที่

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

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

คำอธิบายพารามิเตอร์

  • bufferSize คือขนาดของอาร์เรย์ buffer
  • buffer คืออาร์เรย์ของข้อมูล uint8_t ที่แสดงข้อมูลระนาบ
  • rowStride คือระยะห่างเป็นไบต์ระหว่างตำแหน่งเริ่มต้น 2 ตำแหน่งของแถวข้อมูลพิกเซลที่ต่อเนื่องกัน
  • pixelStride คือระยะห่างของไบต์ระหว่างพิกเซลที่อยู่ติดกัน 2 พิกเซล

รันไทม์ต้องเข้าถึง buffer ตามรูปแบบที่พารามิเตอร์ rowStride และ pixelStride ระบุไว้

แอปพลิเคชันต้องตั้งค่า rowStride และ pixelStride เพื่อให้รันไทม์ดึงเฉพาะพิกเซลที่มีความหมายของ XrSpatialReferenceImagePlaneEXT นี้

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

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_image_tracking ก่อนใช้ XrSpatialReferenceImagePlaneEXT
  • buffer ต้องเป็นตัวชี้ไปยังอาร์เรย์ของค่า bufferSize uint8_t
  • พารามิเตอร์ bufferSize ต้องมากกว่า 0

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

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

คำอธิบายพารามิเตอร์

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • width คือความกว้างเป็นพิกเซลของรูปภาพอ้างอิง
  • height คือความสูงของรูปภาพอ้างอิงในหน่วยพิกเซล
  • format คือ XrSpatialReferenceImageFormatEXT ที่แสดงรูปแบบของรูปภาพ
  • planeCount คือจำนวนองค์ประกอบในอาร์เรย์ planes
  • planes คืออาร์เรย์ของโครงสร้าง XrSpatialReferenceImagePlaneEXT ที่แสดงระนาบของข้อมูลรูปภาพ

แอปพลิเคชันสามารถสร้างโครงสร้าง XrSpatialReferenceImageEXT อย่างน้อย 1 โครงสร้าง โดยแต่ละโครงสร้างจะแสดงรูปภาพอ้างอิงอินพุตเดียวที่จะส่งไปยังฟังก์ชัน xrCreateSpatialImageTrackingDatabaseAsyncEXT ผ่าน XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages เมื่อสร้างแฮนเดิล XrSpatialImageTrackingDatabaseEXT

แอปพลิเคชันต้องระบุข้อมูล XrSpatialReferenceImagePlaneEXT :: buffer ในการจัดเรียงพิกเซลจากซ้ายไปขวาและจากบนลงล่าง

แอปพลิเคชันต้องระบุโครงสร้าง XrSpatialReferenceImagePlaneEXT ในอาร์เรย์ XrSpatialReferenceImageEXT :: planes สำหรับแต่ละช่องสีของ XrSpatialReferenceImageEXT :: format

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

องค์ประกอบที่รับประกัน

รันไทม์ที่รองรับ XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT ต้องระบุคอมโพเนนต์เชิงพื้นที่ต่อไปนี้เป็นคอมโพเนนต์ที่รับประกันของเอนทิตีทั้งหมดที่ค้นพบโดยความสามารถเหล่านั้น และต้องแจกแจงคอมโพเนนต์เหล่านั้นใน xrEnumerateSpatialCapabilityComponentTypesEXT

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

องค์ประกอบรูปภาพ 2 มิติ

โครงสร้างรายการคอมโพเนนต์สำหรับข้อมูลการค้นหา

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

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

คำอธิบายพารามิเตอร์

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • imageCount คือจำนวนองค์ประกอบในอาร์เรย์ images
  • images คืออาร์เรย์ของ XrSpatialImage2DDataEXT

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE จาก xrQuerySpatialComponentDataEXT หาก XrSpatialComponentImage2DListEXT อยู่ในเชน XrSpatialComponentDataQueryResultEXT :: next แต่ XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT ไม่รวมอยู่ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes

รันไทม์ต้องแสดงผล XR_ERROR_SIZE_INSUFFICIENT จาก xrQuerySpatialComponentDataEXT หาก imageCount น้อยกว่า XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput

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

ข้อมูลคอมโพเนนต์

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

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

คำอธิบายพารามิเตอร์

  • imageTrackingDatabase คือ XrSpatialImageTrackingDatabaseEXT ที่ตรวจพบหรือติดตามรูปภาพ
  • referenceImageIndex คือดัชนีที่แมปกับอาร์เรย์ spatialReferenceImages ของรูปภาพอ้างอิงอินพุตที่สร้าง imageTrackingDatabase ขึ้นมาใน XrSpatialImageTrackingDatabaseCreateInfoEXT ::

แอปพลิเคชันสามารถใช้ imageTrackingDatabase เพื่อระบุว่า XrSpatialImageTrackingDatabaseEXT ที่สร้างไว้ก่อนหน้านี้มีรูปภาพอ้างอิงของโครงสร้าง XrSpatialImage2DDataEXT นี้หรือไม่ สำหรับ XrSpatialImageTrackingDatabaseEXT นั้น แอปพลิเคชันสามารถใช้ referenceImageIndex เพื่อระบุ XrSpatialReferenceImageEXT ของโครงสร้าง XrSpatialImage2DDataEXT นี้ได้โดยจับคู่กับลำดับอินพุตของอาร์เรย์ XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages

ชุดรูปภาพอ้างอิงที่กำหนดโดยชุดฐานข้อมูลที่ใช้งานอยู่ทั้งหมดไม่ควรมีรูปภาพที่ซ้ำกัน การใส่รูปภาพที่ซ้ำกันอาจทำให้เกิดการค้นพบหรือพฤติกรรมการติดตามที่ไม่พึงประสงค์ เช่น มีการแสดงผลดัชนีที่ไม่สอดคล้องกันหรือหลายรายการ

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

การกำหนดค่า

สามารถเปิดใช้ได้โดยใส่ค่า enum ในรายการ XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents หากมีการแจกแจง XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT ใน XrSpatialCapabilityComponentTypesEXT :: componentTypes สำหรับความสามารถบางอย่าง แอปพลิเคชัน คอมโพเนนต์นี้ไม่จำเป็นต้องมีการกำหนดค่าพิเศษใดๆ เพื่อรวมไว้ในเชนถัดไปของ XrSpatialCapabilityConfigurationBaseHeaderEXT

คอมโพเนนต์ 2 มิติแบบมีขอบเขต

คอมโพเนนต์ 2 มิติที่มีขอบเขตจะระบุจุดศูนย์กลางและขอบเขตของรูปภาพเชิงพื้นที่ที่แสดงโดยเอนทิตีที่อยู่บนรูปภาพนั้น ดูรายละเอียดเพิ่มเติมเกี่ยวกับคอมโพเนนต์ 2 มิติที่มีขอบเขตได้ที่คอมโพเนนต์ 2 มิติที่มีขอบเขต

โค้ดตัวอย่าง

สำรวจรูปภาพเชิงพื้นที่และค้นหาข้อมูลคอมโพเนนต์

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

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

ประเภทออบเจ็กต์ใหม่

คำสั่งใหม่

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

Enum ใหม่

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

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • การขยาย XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • การขยาย XrResult :

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • การขยาย XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

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

  • การขยาย XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

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

ปัญหา

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

  • ฉบับแก้ไข 1, 22-04-2025 (Daniel Guttenberg, Qualcomm)

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