XR_ANDROID_spatial_annotation_tracking

Name String

XR_ANDROID_spatial_annotation_tracking

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

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

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

795

การแก้ไข

1

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

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

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

XR_EXT_spatial_entity
และ
XR_EXT_spatial_image_tracking

วันที่แก้ไขล่าสุด

2026-01-12

สถานะ IP

ไม่มีการอ้างสิทธิ์ IP ที่ทราบ

ผู้เขียน

Levana Chen, Google
Christopher Feil, Google
Martin Sundermeyer, Google
David Joseph Tan, Google
Jared Finder, Google
Nihav Jain, Google

ภาพรวม

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

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

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

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

  • แอปพลิเคชันจะสร้างแฮนเดิลของ XrSpatialReferenceCacheANDROID ก่อน ซึ่งจะเริ่มบันทึกข้อมูลอ้างอิงรันไทม์จากแหล่งที่มาที่ระบุ
  • จากนั้นแอปพลิเคชันจะบันทึกการอ้างอิงรันไทม์ของ XrSpatialReferenceImageEXT และกำหนดคำอธิบายประกอบที่ต้องการภายในการอ้างอิงในช่วงเวลาของแคชอ้างอิง
  • จากนั้นแอปพลิเคชันจะสร้างแฮนเดิล XrSpatialContextEXT โดยอิงตาม XrSpatialReferenceImageEXT ที่ได้จาก XrSpatialCapabilityConfigurationAnnotationTrackingANDROID
  • แอปพลิเคชันสามารถทำลายแฮนเดิล XrSpatialReferenceCacheANDROID เพื่อหยุดบันทึกการอ้างอิงรันไทม์เพื่อลดการใช้งานหน่วยความจำ หรือรอเหตุการณ์ XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID เพื่อยืนยันผลลัพธ์การเริ่มต้น
  • จากนั้นแอปพลิเคชันจะดึงข้อมูลเหตุการณ์ XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID เพื่อยืนยันผลการเริ่มต้นของคำอธิบายประกอบ
  • หากการเริ่มต้นสำเร็จ แอปพลิเคชันจะสามารถดึงข้อมูลเหตุการณ์ XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT เพื่อติดตามคำอธิบายประกอบได้
  • หากการเริ่มต้นไม่สำเร็จ แอปพลิเคชันสามารถใช้รหัสข้อผิดพลาดที่แสดงในเหตุการณ์เพื่อระบุสาเหตุของความล้มเหลว และทำลายแฮนเดิล XrSpatialContextEXT ที่มีอยู่เพื่อเริ่มคำอธิบายประกอบใหม่
  • ไม่ว่าผลลัพธ์ของการเริ่มต้นจะเป็นอย่างไร แอปพลิเคชันสามารถปล่อยบัฟเฟอร์รูปภาพเพื่อลดการใช้งานหน่วยความจำหลังจากได้รับเหตุการณ์
  • แอปพลิเคชันจะค้นหาและค้นหาคำอธิบายประกอบตามรูปแบบการเข้าถึงเอนทิตีเชิงพื้นที่
  • แอปพลิเคชันสามารถสร้างแฮนเดิล XrSpatialContextEXT เพิ่มเติมเพื่อติดตามคำอธิบายประกอบภายในข้อมูลอ้างอิงใหม่ในช่วงเวลาของ XrSpatialReferenceCacheANDROID ที่ถูกต้อง
  • แอปพลิเคชันสามารถทำลายแฮนเดิล XrSpatialContextEXT เพื่อลดชุดคำอธิบายประกอบที่ตรวจจับและติดตามได้แบบไดนามิกขณะรันไทม์

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

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

  • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

เมื่อรันไทม์รองรับความสามารถในการติดตามคำอธิบายประกอบ ให้ทำดังนี้

  • ต้องรองรับคอมโพเนนต์คำอธิบายประกอบอย่างน้อย 1 รายการ โดยแสดงรายการคอมโพเนนต์คำอธิบายประกอบที่รองรับผ่าน xrEnumerateSpatialCapabilityComponentTypesEXT
  • ต้องรองรับ XrSpatialReferenceImageFormatEXT อย่างน้อย 1 รายการ โดยแสดงรายการรูปแบบอ้างอิงที่รองรับผ่าน xrEnumerateSpatialReferenceImageFormatsEXT โดยตั้งค่า capability เป็น XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID
  • โดยต้องรองรับ XrSpatialAnnotationReferenceSourceANDROID อย่างน้อย 1 รายการ โดยแสดงรายการแหล่งที่มาอ้างอิงที่รองรับผ่าน xrEnumerateSpatialAnnotationReferenceSourcesANDROID โดยตั้งค่า capability เป็น XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

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

XrResult xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    sourceCapacityInput,
    uint32_t*                                   sourceCountOutput,
    XrSpatialAnnotationReferenceSourceANDROID*  sources);

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

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

แอปพลิเคชันสามารถแจกแจงรายการแหล่งข้อมูลอ้างอิงที่ XrSystemId หนึ่งๆ รองรับได้โดยใช้ xrEnumerateSpatialAnnotationReferenceSourcesANDROID

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

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

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_spatial_annotation_tracking ก่อนเรียกใช้ xrEnumerateSpatialAnnotationReferenceSourcesANDROID
  • instance ต้องเป็นแฮนเดิล XrInstance ที่ถูกต้อง
  • capability ต้องเป็นค่า XrSpatialCapabilityEXT ที่ถูกต้อง
  • sourceCountOutput ต้องเป็นตัวชี้ไปยังค่า uint32_t
  • หาก sourceCapacityInput ไม่ใช่ 0 sources ต้องเป็นพอยเตอร์ไปยังอาร์เรย์ของค่า sourceCapacityInput XrSpatialAnnotationReferenceSourceANDROID

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

สำเร็จ

  • 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

typedef enum XrSpatialAnnotationReferenceSourceANDROID {
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationReferenceSourceANDROID;

การแจงนับ XrSpatialAnnotationReferenceSourceANDROID อธิบายแหล่งที่มาของการอ้างอิงซึ่งให้ข้อมูลเมตาสำหรับคำอธิบายประกอบ

Enum มีความหมายดังนี้

คำอธิบาย Enum

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID

รูปภาพอ้างอิงคือเอาต์พุตของรูปภาพที่ไม่ได้ครอบตัดจาก API กล้องของ Android เช่น รูปภาพจาก ImageReader ที่เชื่อมโยงกับ CameraDevice ของ Camera2 หรือ ImageProxy จาก ImageAnalysis ที่เชื่อมโยงกับ CameraX ซึ่งโดยปกติแล้วจะเป็นกล้อง RGB ตัวใดตัวหนึ่งที่หันไปข้างหน้า

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID

รูปภาพอ้างอิงคือเอาต์พุตรูปภาพที่ไม่ได้ครอบตัดจาก Android MediaProjection API เช่น รูปภาพจาก ImageReader ที่เชื่อมโยงกับจอแสดงผลเสมือน MediaProjection ซึ่งอาจรวมถึงเนื้อหาเสมือนจริงและเนื้อหาจริง

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

typedef struct XrSystemSpatialAnnotationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           referenceCacheTimespan;
    uint32_t           maxReferencePixelWidth;
    uint32_t           maxReferencePixelHeight;
    uint32_t           maxReferenceCount;
    uint32_t           maxAnnotationCount;
} XrSystemSpatialAnnotationPropertiesANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • referenceCacheTimespan ระบุช่วงเวลาเป็นวินาทีของแฮนเดิล XrSpatialReferenceCacheANDROID ที่ถูกต้อง
  • maxReferencePixelWidth ระบุความกว้างสูงสุดของขอบรูปภาพอ้างอิงในหน่วยพิกเซล
  • maxReferencePixelHeight ระบุความสูงสูงสุดของขอบรูปภาพอ้างอิงในหน่วยพิกเซล
  • maxReferenceCount ระบุจำนวนรูปภาพอ้างอิงสูงสุดที่จะจัดสรรพร้อมกัน
  • maxAnnotationCount ระบุจำนวนคำอธิบายประกอบสูงสุดที่จะติดตามพร้อมกัน

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

หาก XrSpatialReferenceImageEXT :: width จาก XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference เกิน maxReferencePixelWidth รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE เมื่อเรียกใช้ xrCreateSpatialContextAsyncEXT

หาก XrSpatialReferenceImageEXT :: height จาก XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference เกิน maxReferencePixelHeight รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE เมื่อเรียกใช้ xrCreateSpatialContextAsyncEXT

หาก XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: time อยู่นอกช่วงเวลาของ XrSpatialReferenceCacheANDROID :: cache รันไทม์ต้องแสดงผล XR_ERROR_TIME_INVALID เมื่อเรียกใช้ xrCreateSpatialContextAsyncEXT แอปพลิเคชันสามารถสร้างแฮนเดิล XrSpatialContextEXT ขึ้นมาใหม่ด้วยข้อมูลอ้างอิงใหม่ในช่วงเวลาของ XrSpatialReferenceCacheANDROID

หากจำนวนรูปภาพอ้างอิงที่จัดสรรเกิน maxReferenceCount รันไทม์ต้องแสดงผล XR_ERROR_LIMIT_REACHED และระบุความล้มเหลวในการเริ่มต้นผ่าน XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult แอปพลิเคชันสามารถทำลายแฮนเดิล XrSpatialContextEXT และลองอีกครั้งหลังจากที่การเริ่มต้นที่รอดำเนินการเสร็จสมบูรณ์

หากจำนวนคำอธิบายประกอบที่ใช้งานอยู่เกิน maxAnnotationCount รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE เมื่อเรียกใช้ xrCreateSpatialContextAsyncEXT

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

แคชอ้างอิงรันไทม์

XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)

แฮนเดิล XrSpatialReferenceCacheANDROID แสดงแคชของการอ้างอิงรันไทม์ที่บันทึกจากแหล่งที่มาหนึ่งๆ

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

XrResult xrCreateSpatialReferenceCacheAsyncANDROID(
    XrSession                                   session,
    const XrSpatialReferenceCacheCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

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

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

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

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

รันไทม์ต้องแสดงผล XR_ERROR_FEATURE_UNSUPPORTED หาก XrSpatialReferenceCacheCreateInfoANDROID :: source ไม่แสดงโดย xrEnumerateSpatialAnnotationReferenceSourcesANDROID สำหรับความสามารถที่ระบุ

แอปพลิเคชันสามารถสร้างแฮนเดิลได้เพียง 1 รายการต่อแหล่งที่มาสำหรับความสามารถหนึ่งๆ ไม่เช่นนั้น รันไทม์ต้องแสดงผล XR_ERROR_LIMIT_REACHED

จากนั้นแอปพลิเคชันจะบันทึกการอ้างอิงรันไทม์ในช่วงเวลาของแฮนเดิล XrSpatialReferenceCacheANDROID เพื่อกำหนดค่าแฮนเดิล XrSpatialContextEXT ใหม่ได้

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

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

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • 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_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialReferenceCacheCreateInfoANDROID {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialCapabilityEXT                       capability;
    XrSpatialAnnotationReferenceSourceANDROID    source;
} XrSpatialReferenceCacheCreateInfoANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • capability คือ XrSpatialCapabilityEXT ที่อธิบายความสามารถที่สร้างแคชอ้างอิงขึ้นมา
  • source คือ XrSpatialAnnotationReferenceSourceANDROID ที่อธิบายแหล่งที่มาของแคชอ้างอิง

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

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

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

XrResult xrCreateSpatialReferenceCacheCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialReferenceCacheCompletionANDROID* completion);

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

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

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

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

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FEATURE_UNSUPPORTED
  • 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

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

typedef struct XrCreateSpatialReferenceCacheCompletionANDROID {
    XrStructureType                   type;
    void*                             next;
    XrResult                          futureResult;
    XrSpatialReferenceCacheANDROID    referenceCache;
} XrCreateSpatialReferenceCacheCompletionANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • futureResult คือ XrResult ของการดำเนินการสร้างแคชอ้างอิง
  • referenceCache คือแฮนเดิล XrSpatialReferenceCacheANDROID หากการดำเนินการสำเร็จ

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

ค่า futureResult:

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

หาก futureResult เป็นรหัสความสำเร็จ รันไทม์ต้องแสดงผลแฮนเดิล referenceCache ที่ถูกต้อง หาก referenceCache ถูกต้อง จะยังคงถูกต้องภายในอายุการใช้งานของ xrCreateSpatialReferenceCacheAsyncANDROID :: session หรือจนกว่าแอปพลิเคชันจะทำลายแฮนเดิลด้วย xrDestroySpatialReferenceCacheANDROID แล้วแต่ว่ากรณีใดจะเกิดขึ้นก่อน

เมื่อ referenceCache ถูกต้อง ระบบจะบันทึกแคชภายใน XrSystemSpatialAnnotationPropertiesANDROID :: referenceCacheTimespan

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

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

XrResult xrDestroySpatialReferenceCacheANDROID(
    XrSpatialReferenceCacheANDROID              cacheHandle);

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

แอปพลิเคชันสามารถเรียกใช้ฟังก์ชัน xrDestroySpatialReferenceCacheANDROID เพื่อปล่อยแฮนเดิล cacheHandle และทรัพยากรที่เกี่ยวข้องเมื่อสร้างบริบทเชิงพื้นที่เสร็จแล้ว

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

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

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

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

สำเร็จ

  • XR_SUCCESS

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

การกำหนดค่า

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

typedef struct XrSpatialCapabilityConfigurationAnnotationTrackingANDROID {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialReferenceCacheANDROID      cache;
    XrTime                              time;
    XrSpatialReferenceImageEXT          reference;
} XrSpatialCapabilityConfigurationAnnotationTrackingANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • capability เป็น XrSpatialCapabilityEXT และต้องเป็น XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID
  • enabledComponentCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ enabledComponents
  • enabledComponents เป็นตัวชี้ไปยังอาร์เรย์ของ XrSpatialComponentTypeEXT
  • cache คือ XrSpatialReferenceCacheANDROID ที่สร้างไว้ก่อนหน้านี้เพื่อบันทึกการอ้างอิงรันไทม์สำหรับการกำหนดค่า reference
  • time คือ XrTime ที่บันทึก reference
  • reference คือ XrSpatialReferenceImageEXT ที่มีคำอธิบายประกอบเชื่อมโยงกับตัวชี้ถัดไป

แอปพลิเคชันสามารถเปิดใช้ความสามารถเชิงมิติพื้นที่ XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID โดยเพิ่มพอยน์เตอร์ไปยังโครงสร้าง XrSpatialCapabilityConfigurationAnnotationTrackingANDROID ใน XrSpatialContextCreateInfoEXT :: capabilityConfigs

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE หาก capability ไม่ใช่ XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT หาก reference ไม่มีคำอธิบายประกอบ

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

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE หาก cache ไม่ได้เป็นของ XrSession เดียวกันที่ส่งไปยัง xrCreateSpatialContextAsyncEXT

รันไทม์ต้องแสดงผล XR_ERROR_TIME_INVALID หาก time อยู่นอกช่วงเวลาของ cache

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

เหตุการณ์การติดตามคำอธิบายประกอบ

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

typedef struct XrEventDataSpatialAnnotationTrackingANDROID {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
    uint32_t               annotationIndex;
    XrResult               initializationResult;
} XrEventDataSpatialAnnotationTrackingANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • spatialContext คือ XrSpatialContextEXT ที่เปิดใช้งานการติดตามคำอธิบายประกอบ
  • annotationIndex แมปกับดัชนีจากอาร์เรย์คำอธิบายประกอบที่เชื่อมโยงกับ XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference
  • initializationResult บ่งบอกถึงผลลัพธ์การเริ่มต้นของคำอธิบายประกอบ หากไม่ใช่ XR_SUCCESS แอปพลิเคชันสามารถทำลายและสร้างแฮนเดิล XrSpatialContextEXT ขึ้นมาใหม่เพื่อเริ่มต้นคำอธิบายประกอบอีกครั้ง หรือใช้ spatialContext ต่อไปเพื่อติดตามคำอธิบายประกอบอื่นๆ

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

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

รันไทม์ต้องป้อน initializationResult ด้วย XR_SUCCESS หากเริ่มต้นคำอธิบายประกอบสำเร็จ จากนั้นแอปพลิเคชันสามารถดึงเหตุการณ์ XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT เพื่อติดตามคำอธิบายประกอบได้

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

คำอธิบายประกอบรูปสี่เหลี่ยมด้านเท่า

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

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

การอ้างอิงแบบ 4 รายการ

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

typedef struct XrSpatialAnnotationQuadReferenceANDROID {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 quadCount;
    const XrSpatialAnnotationQuadANDROID*    quads;
} XrSpatialAnnotationQuadReferenceANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • quadCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ quads
  • quads คือตัวชี้ไปยังอาร์เรย์ของ XrSpatialAnnotationQuadANDROID

เมื่อรันไทม์รองรับคำอธิบายประกอบรูปสี่เหลี่ยม แอปพลิเคชันสามารถกำหนดค่าคำอธิบายประกอบได้โดยเชื่อมโยงโครงสร้าง XrSpatialAnnotationQuadReferenceANDROID กับ XrSpatialReferenceImageEXT :: next และตั้งค่าการอ้างอิงใน XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference เมื่อสร้างแฮนเดิล XrSpatialContextEXT

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT จาก xrCreateSpatialContextAsyncEXT หาก quadCount เป็น 0

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

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

typedef struct XrSpatialAnnotationQuadANDROID {
    XrSpatialAnnotationQuadAlignmentANDROID    alignment;
    XrVector2f                                 upperLeft;
    XrVector2f                                 upperRight;
    XrVector2f                                 lowerRight;
    XrVector2f                                 lowerLeft;
} XrSpatialAnnotationQuadANDROID;

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

  • alignment คือ XrSpatialAnnotationQuadAlignmentANDROID ของ Quad
  • upperLeft คือ XrVector2f ที่อธิบายพิกัดของมุมซ้ายบนของสี่เหลี่ยมด้านขนานที่เกี่ยวข้องกับจุดเริ่มต้น
  • upperRight คือ XrVector2f ที่อธิบายพิกัดของมุมขวาบนของสี่เหลี่ยมจัตุรัสที่เกี่ยวข้องกับจุดเริ่มต้น
  • lowerRight คือ XrVector2f ที่อธิบายพิกัดของมุมขวาล่างของสี่เหลี่ยมจัตุรัสที่เกี่ยวข้องกับจุดเริ่มต้น
  • lowerLeft คือ XrVector2f ที่อธิบายพิกัดของมุมซ้ายล่างของสี่เหลี่ยมจัตุรัสที่เกี่ยวข้องกับจุดเริ่มต้น

รูปสี่เหลี่ยมในพื้นที่ 2 มิติคือรูปสี่เหลี่ยมนูนที่มีลำดับตามเข็มนาฬิกา ค่าของมุมทั้ง 4 มุมจะสัมพันธ์กับจุดเริ่มต้น (0, 0) ที่เชื่อมโยงกับรูปสี่เหลี่ยมด้านเท่า

  • เมื่อเชื่อมโยงกับ XrSpatialReferenceImageEXT จุดเริ่มต้นคือมุมซ้ายบนของรูปภาพ โดยที่ X จะแมปกับพิกเซลตามความกว้าง และ Y จะแมปกับพิกเซลตามความสูง
  • เมื่อเชื่อมโยงกับ XrSpatialAnnotationQuadDataANDROID จุดเริ่มต้นจะระบุโดย XrSpaceLocationData :: pose ของ XrSpatialAnnotationQuadDataANDROID :: origin

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

typedef enum XrSpatialAnnotationQuadAlignmentANDROID {
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SURFACE_ANDROID = 2,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationQuadAlignmentANDROID;

การแจงนับ XrSpatialAnnotationQuadAlignmentANDROID อธิบายการจัดแนวของคำอธิบายประกอบสี่เหลี่ยมจัตุรัส

Enum มีความหมายดังนี้

คำอธิบาย Enum

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID

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

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID

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

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SURFACE_ANDROID

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

คอมโพเนนต์ Quad

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

typedef struct XrSpatialAnnotationQuadDataANDROID {
    uint32_t                          annotationIndex;
    XrSpaceLocationData               origin;
    XrSpatialAnnotationQuadANDROID    quad;
} XrSpatialAnnotationQuadDataANDROID;

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

  • annotationIndex คือดัชนีที่แมปกับอาร์เรย์ XrSpatialAnnotationQuadReferenceANDROID :: quads ที่เชื่อมโยงกับการอ้างอิงที่ส่งโดย XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference
  • origin คือ XrSpaceLocationData ที่อธิบายจุดเริ่มต้นของระนาบ 2 มิติที่ Quad มีรากฐานอยู่ รันไทม์ต้องตั้งค่า XrSpaceLocationData :: locationFlags เพื่อระบุบิตที่ถูกต้องของท่าทางต้นทาง
  • quad คือ XrSpatialAnnotationQuadANDROID ที่แสดงถึงสี่เหลี่ยมจัตุรัสในพื้นที่ภายในเครื่อง ใช้ origin เพื่อเปลี่ยนรูปสี่เหลี่ยมขนมเปียกปูนเป็นพื้นที่ท่าทางสัมผัส

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

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

typedef struct XrSpatialComponentAnnotationQuadListANDROID {
    XrStructureType                        type;
    void*                                  next;
    uint32_t                               quadCount;
    XrSpatialAnnotationQuadDataANDROID*    quads;
} XrSpatialComponentAnnotationQuadListANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • quadCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ quads
  • quads คืออาร์เรย์ของ XrSpatialAnnotationQuadDataANDROID

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

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

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

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

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

ตรวจสอบการรองรับรันไทม์

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

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrEnumerateSpatialCapabilitiesEXT xrEnumerateSpatialCapabilitiesEXT;
PFN_xrEnumerateSpatialAnnotationReferenceSourcesANDROID xrEnumerateSpatialAnnotationReferenceSourcesANDROID;
PFN_xrEnumerateSpatialReferenceImageFormatsEXT xrEnumerateSpatialReferenceImageFormatsEXT;
PFN_xrEnumerateSpatialCapabilityComponentTypesEXT xrEnumerateSpatialCapabilityComponentTypesEXT;

// Check spatial annotation tracking capability
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_ANNOTATION_TRACKING_ANDROID) ==
    capabilities.end()) {
  // System does not support spatial annotation tracking.
  return;
}

// Inspect system properties for annotation tracking variables
XrSystemSpatialAnnotationPropertiesANDROID annotationSystemProperties{
    XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{.type = XR_TYPE_SYSTEM_PROPERTIES,
                                    .next = &annotationSystemProperties,
                                    .systemId = systemId};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (annotationSystemProperties.maxAnnotationCount == 0) {
  // System does not support any active annotations.
  return;
}

// Enumerate supported reference sources
uint32_t sourceCountOutput = 0;
XrSpatialAnnotationReferenceSourceANDROID desiredSource =
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID;
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    0, &sourceCountOutput, nullptr));
std::vector<XrSpatialAnnotationReferenceSourceANDROID> sources(sourceCountOutput);
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    sourceCountOutput, &sourceCountOutput, sources.data()));
if (std::find(sources.begin(), sources.end(), desiredSource) == sources.end()) {
  // The desired source is not supported.
  return;
}

// Enumerate supported reference image formats, provided by XR_EXT_spatial_image_tracking.
uint32_t formatCountOutput = 0;
XrSpatialReferenceImageFormatEXT desiredFormat =
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT; // Or XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT for screenshot.
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID, 0,
    &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    formats.size(), &formatCountOutput, formats.data()));
if (std::find(formats.begin(), formats.end(), desiredFormat) == formats.end()) {
  // The desired format is not supported
  return;
}

// Enumerate supported components for annotation tracking capability.
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes{
    XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));
std::vector<XrSpatialComponentTypeEXT>
    annotationTypes(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = annotationTypes.size();
capabilityComponentTypes.componentTypes = annotationTypes.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));

// Check supported annotation components.
XrSpatialComponentTypeEXT desiredComponent =
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID;
const auto supportedComponent = [&annotationTypes](
                                    XrSpatialComponentTypeEXT component) {
  return std::find(annotationTypes.begin(), annotationTypes.end(), component) !=
         annotationTypes.end();
};
if (!supportedComponent(desiredComponent)) {
  // The desired annotation is not supported.
  return;
}

กำหนดค่าคำอธิบายประกอบแบบ Quad

โค้ดตัวอย่างต่อไปนี้แสดงวิธีกำหนดค่าคำอธิบายประกอบสี่เหลี่ยมจัตุรัส

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrCreateSpatialReferenceCacheAsyncANDROID xrCreateSpatialReferenceCacheAsyncANDROID;
PFN_xrCreateSpatialReferenceCacheCompleteANDROID xrCreateSpatialReferenceCacheCompleteANDROID;
PFN_xrDestroySpatialReferenceCacheANDROID xrDestroySpatialReferenceCacheANDROID;
PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialReferenceImageFormatEXT desiredFormat;
XrSpatialAnnotationReferenceSourceANDROID desiredSource;
XrSpatialComponentTypeEXT desiredComponent;

// Create and start reference cache to prepare for capturing reference images.
XrSpatialReferenceCacheANDROID referenceCache;
XrSpatialReferenceCacheCreateInfoANDROID cacheCreateInfo{
  .type = XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
  .source = desiredSource,
};
XrFutureEXT cacheFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialReferenceCacheAsyncANDROID(session, &cacheCreateInfo, &cacheFuture));

waitUntilReady(cacheFuture);

XrCreateSpatialReferenceCacheCompletionANDROID cacheCompletion{
    XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID};
CHK_XR(xrCreateSpatialReferenceCacheCompleteANDROID(session, cacheFuture,
                                                     &cacheCompletion));
if (cacheCompletion.futureResult != XR_SUCCESS) {
  // Error, reference cache creation failed
  return;
}

referenceCache = cacheCompletion.referenceCache;

// Create the reference image with quad annotations

//  YUV 4:2:0 Planar:
// ----------------------
// |     Y      |Cb |Cr |
// ----------------------
XrSpatialReferenceImagePlaneEXT cameraImagePlanes[3];
// for each plane (0=Y, 1=U(cb), 2=V(Cr)) return by Image#getPlanes().
for (int i = 0; i < 3; ++i) {
  cameraImagePlanes[i].buffer; // read from Plane#getBuffer().
  cameraImagePlanes[i].bufferSize; // set each buffer size. Y = width * height (bytes); U = Y / 4 (bytes); V = Y / 4 (bytes).
  cameraImagePlanes[i].rowStride; // read from Plane#getRowStride().
  cameraImagePlanes[i].pixelStride; // read from Plane#getPixelStride().
}
XrSpatialReferenceImageEXT referenceImage{
      XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
referenceImage.width = 640;
referenceImage.height = 480;
referenceImage.format = desiredFormat;
referenceImage.planeCount = 3;
referenceImage.planes = cameraImagePlanes;

XrSpatialAnnotationQuadANDROID
    quad; // quad coordinates within the reference image.
quad.alignment = XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID;
// Set unnormalized pixel coordinates of 4 corners.
quad.upperLeft = {0.0, 0.0};
quad.upperRight = {0.0, 100.0};
quad.lowerRight = {100.0, 100.0};
quad.lowerLeft = {0.0, 100.0};

XrSpatialAnnotationQuadReferenceANDROID quadReference{
    XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID};
quadReference.quads = &quad;
quadReference.quadCount = 1;
referenceImage.next = &quadReference;

// Create the spatial context with annotation configuration.
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
      desiredComponent,
  };

  // Configure annotation tracking
  XrSpatialCapabilityConfigurationAnnotationTrackingANDROID annotationConfig{
      XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID};
  annotationConfig.capability =
      XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID;
  annotationConfig.enabledComponentCount = enabledComponents.size();
  annotationConfig.enabledComponents = enabledComponents.data();
  annotationConfig.cache = referenceCache;
  annotationConfig.time; // The time when this reference image is captured.
  annotationConfig.reference = referenceImage;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT *>
      capabilityConfigs;
  capabilityConfigs.push_back(
      reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT *>(
          &annotationConfig));

  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
    return;
  }

  spatialContext = completion.spatialContext;
  CHK_XR(xrDestroySpatialReferenceCacheANDROID(referenceCache));
}

สำรวจคำอธิบายประกอบที่ใช้งานอยู่

โค้ดตัวอย่างต่อไปนี้แสดงวิธีค้นหาและค้นหาคำอธิบายประกอบ

XrInstance instance;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL
XrSpatialContextEXT spatialContext; // previously created

PFN_xrCreateSpatialDiscoverySnapshotAsyncEXT xrCreateSpatialDiscoverySnapshotAsyncEXT;
PFN_xrCreateSpatialDiscoverySnapshotCompleteEXT xrCreateSpatialDiscoverySnapshotCompleteEXT;
PFN_xrQuerySpatialComponentDataEXT xrQuerySpatialComponentDataEXT;
PFN_xrDestroySpatialSnapshotEXT xrDestroySpatialSnapshotEXT;
PFN_xrPollEvent xrPollEvent;
PFN_xrDestroySpatialContextEXT xrDestroySpatialContextEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialComponentTypeEXT desiredComponent; // e.g. XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

auto discoverAnnotations = [&](XrSpatialContextEXT spatialContext, XrTime time,
                               XrSpace baseSpace) {
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{desiredComponent};
  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 = baseSpace;
  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 desired annotation data, e.g. quad.
    XrSpatialComponentTypeEXT componentsToQuery[] = {
        XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID};
    XrSpatialComponentDataQueryConditionEXT queryCond{
        XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = 1;
    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<XrSpatialAnnotationQuadDataANDROID> quads(
        queryResult.entityIdCountOutput);
    XrSpatialComponentAnnotationQuadListANDROID quadList{
        XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID};
    quadList.quadCount = quads.size();
    quadList.quads = quads.data();
    queryResult.next = &quadList;

    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 XrSpatialAnnotationQuadDataANDROID &currentQuad = quads[i];
        // Rendering quad in the view.
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // For every frame in frame loop

  XrSpace space;           // Application's play space.
  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_ANNOTATION_TRACKING_ANDROID: {
      const XrEventDataSpatialAnnotationTrackingANDROID &eventdata =
          *reinterpret_cast<XrEventDataSpatialAnnotationTrackingANDROID *>(
              &event);
      if (eventdata.initializationResult != XR_SUCCESS) {
        // handle initialization failure.
        // e.g. CHK_XR(xrDestroySpatialContextEXT(spatialContext));
      }
      break;
    }
    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, space);
      break;
    }
    }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

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

คำสั่งใหม่

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

Enum ใหม่

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

  • XR_ANDROID_SPATIAL_ANNOTATION_TRACKING_EXTENSION_NAME
  • XR_ANDROID_spatial_annotation_tracking_SPEC_VERSION
  • การขยาย XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_REFERENCE_CACHE_ANDROID
  • การขยาย XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID
  • การขยาย XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
  • การขยาย XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID
    • XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID
    • XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID
    • XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID

ปัญหา

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

  • ฉบับแก้ไข 1, 17-09-2025 (Levana Chen)

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