XR_EXT_spatial_persistence

Name String

XR_EXT_spatial_persistence

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

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

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

764

การแก้ไข

1

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

ให้สัตยาบัน

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

XR_EXT_spatial_entity
และ
XR_EXT_future

ผู้เขียน

Nihav Jain, Google
Jared Finder, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

ภาพรวม

ส่วนขยายนี้ช่วยให้แอปพลิเคชันค้นพบและเชื่อมโยงเอนทิตีเชิงพื้นที่ในเซสชันแอปพลิเคชัน เซสชัน OpenXR และบริบทเชิงพื้นที่ OpenXR หลายรายการภายในเซสชันได้ ส่วนขยาย XR_EXT_spatial_entity กำหนดว่าเอนทิตีภายใน XrSpatialContextEXT จะแสดงด้วย XrSpatialEntityIdEXT ส่วนขยายนี้จะขยายแนวคิดดังกล่าวโดยกำหนดว่าเอนทิตี (หากยังคงอยู่) จะแสดงด้วย XrUuid ในแอปพลิเคชันและเซสชัน OpenXR กล่าวคือ แอปพลิเคชันสามารถใช้ XrUuid ที่ส่วนขยายนี้ให้มาเพื่อระบุเอนทิตีในเซสชันต่างๆ ได้ ส่วนขยายนี้ยังมีการทับซ้อนที่เป็นประโยชน์กับส่วนขยาย XR_EXT_spatial_entity เพื่อค้นหาเอนทิตีที่ยังคงอยู่ในสภาพแวดล้อมของผู้ใช้และความสามารถในการค้นหาข้อมูลคอมโพเนนต์

บริบทความต่อเนื่องเชิงพื้นที่

สร้างบริบทความต่อเนื่องเชิงพื้นที่

XR_DEFINE_HANDLE(XrSpatialPersistenceContextEXT)

แฮนเดิล XrSpatialPersistenceContextEXT แสดงถึงการเชื่อมต่อกับพื้นที่เก็บข้อมูลเอนทิตีเชิงพื้นที่แบบถาวร

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

XrResult xrCreateSpatialPersistenceContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialPersistenceContextCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

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

  • session คือ XrSession ซึ่งบริบทความคงอยู่เชิงพื้นที่จะทำงาน
  • createInfo คือ XrSpatialPersistenceContextCreateInfoEXT ที่ใช้ระบุพารามิเตอร์บริบทความคงอยู่เชิงพื้นที่
  • future เป็นตัวชี้ไปยัง XrFutureEXT

แอปพลิเคชันสามารถสร้างแฮนเดิล XrSpatialPersistenceContextEXT โดยใช้ฟังก์ชัน xrCreateSpatialPersistenceContextAsyncEXT และกำหนดค่าขอบเขตของบริบทความต่อเนื่องใน createInfo

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_UNSUPPORTED_EXT หาก XrSpatialPersistenceContextCreateInfoEXT :: scope ไม่ได้แจกแจงโดย xrEnumerateSpatialPersistenceScopesEXT

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

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

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_persistence ก่อนเรียกใช้ xrCreateSpatialPersistenceContextAsyncEXT
  • session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
  • createInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialPersistenceContextCreateInfoEXT ที่ถูกต้อง
  • 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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_UNSUPPORTED_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialPersistenceContextCreateInfoEXT {
    XrStructureType                 type;
    const void*                     next;
    XrSpatialPersistenceScopeEXT    scope;
} XrSpatialPersistenceContextCreateInfoEXT;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • scope คือ XrSpatialPersistenceScopeEXT ที่กำหนดขอบเขตพื้นที่เก็บข้อมูลของบริบทความต่อเนื่อง

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

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

typedef enum XrSpatialPersistenceScopeEXT {
    XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT = 1,
    XR_SPATIAL_PERSISTENCE_SCOPE_LOCAL_ANCHORS_EXT = 1000781000,
    XR_SPATIAL_PERSISTENCE_SCOPE_ANCHORS_FOR_CLOUD_SHARING_ANDROIDX1 = 1000808000,
    XR_SPATIAL_PERSISTENCE_SCOPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceScopeEXT;

การแจงนับ XrSpatialPersistenceScopeEXT จะระบุขอบเขตบริบทความคงอยู่ประเภทต่างๆ

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

คำอธิบาย Enum

XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT

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

XR_SPATIAL_PERSISTENCE_SCOPE_LOCAL_ANCHORS_EXT

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

XR_SPATIAL_PERSISTENCE_SCOPE_ANCHORS_FOR_CLOUD_SHARING_ANDROIDX1

การดำเนินการด้านความต่อเนื่องและการเข้าถึงข้อมูลจะจำกัดไว้เฉพาะ Anchor เชิงพื้นที่ ซึ่งเป็นเจ้าของและจัดการโดยโปรเจ็กต์ที่อยู่ในระบบคลาวด์เดียวกัน (เพิ่มโดยส่วนขยาย XR_ANDROIDX1_spatial_anchor_cloud_sharing)

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

XrResult xrEnumerateSpatialPersistenceScopesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    persistenceScopeCapacityInput,
    uint32_t*                                   persistenceScopeCountOutput,
    XrSpatialPersistenceScopeEXT*               persistenceScopes);

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

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

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

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

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_persistence ก่อนเรียกใช้ xrEnumerateSpatialPersistenceScopesEXT
  • instance ต้องเป็นแฮนเดิล XrInstance ที่ถูกต้อง
  • persistenceScopeCountOutput ต้องเป็นตัวชี้ไปยังค่า uint32_t
  • หาก persistenceScopeCapacityInput ไม่ใช่ 0 persistenceScopes ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า persistenceScopeCapacityInput XrSpatialPersistenceScopeEXT

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

สำเร็จ

  • XR_SUCCESS

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCreateSpatialPersistenceContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialPersistenceContextCompletionEXT* completion);

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

xrCreateSpatialPersistenceContextCompleteEXT จะดำเนินการแบบอะซิงโครนัสที่เริ่มต้นโดย xrCreateSpatialPersistenceContextAsyncEXT ให้เสร็จสมบูรณ์ รันไทม์ต้องแสดงผล 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

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

typedef struct XrCreateSpatialPersistenceContextCompletionEXT {
    XrStructureType                         type;
    void*                                   next;
    XrResult                                futureResult;
    XrSpatialPersistenceContextResultEXT    createResult;
    XrSpatialPersistenceContextEXT          persistenceContext;
} XrCreateSpatialPersistenceContextCompletionEXT;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • futureResult คือ XrResult ของการดำเนินการสร้างบริบทความคงอยู่เชิงพื้นที่
  • createResult คือ XrSpatialPersistenceContextResultEXT ของการดำเนินการสร้างบริบทความคงอยู่เชิงพื้นที่
  • persistenceContext คือ XrSpatialPersistenceContextEXT ที่สร้างขึ้นโดยใช้ข้อมูลและการกำหนดค่าใน xrCreateSpatialPersistenceContextAsyncEXT :: 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_PERMISSION_INSUFFICIENT

หาก futureResult และ createResult เป็นโค้ดความสำเร็จทั้งคู่ persistenceContext ต้องถูกต้อง หาก persistenceContext ถูกต้อง ต้องยังคงถูกต้องภายในวงจรของ xrCreateSpatialPersistenceContextAsyncEXT :: session หรือจนกว่าแอปพลิเคชันจะใช้ xrDestroySpatialPersistenceContextEXT กับ persistenceContext แล้วแต่ว่ากรณีใดจะเกิดขึ้นก่อน

รันไทม์ต้องตั้งค่า createResult ก็ต่อเมื่อ futureResult เป็นรหัสที่แสดงความสำเร็จเท่านั้น

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

typedef enum XrSpatialPersistenceContextResultEXT {
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT = 0,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT = -1000781001,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_PERSIST_UUID_NOT_FOUND_EXT = -1000781002,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_LOCALIZATION_FAILURE_ANDROIDX1 = -1000808000,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAP_FEATURE_INSUFFICIENT_ANDROIDX1 = -1000808001,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_FAILURE_ANDROIDX1 = -1000808002,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_TIMEOUT_ANDROIDX1 = -1000808003,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceContextResultEXT;

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

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

คำอธิบาย Enum

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT

การดำเนินการบริบทความคงอยู่สำเร็จแล้ว

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT

การดำเนินการด้านความต่อเนื่องไม่สำเร็จเนื่องจากรันไทม์ติดตามเอนทิตีไม่ได้ (เพิ่มโดยส่วนขยาย XR_EXT_spatial_persistence_operations)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_PERSIST_UUID_NOT_FOUND_EXT

ไม่พบ UUID ที่คงอยู่ในพื้นที่เก็บข้อมูล (เพิ่มโดยส่วนขยาย XR_EXT_spatial_persistence_operations)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_LOCALIZATION_FAILURE_ANDROIDX1

การดำเนินการคงอยู่ไม่สำเร็จเนื่องจากการแปลไม่สำเร็จ (เพิ่มโดยส่วนขยาย XR_ANDROIDX1_spatial_anchor_cloud_sharing)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAP_FEATURE_INSUFFICIENT_ANDROIDX1

การดำเนินการแบบถาวรไม่สำเร็จเนื่องจากฟีเจอร์แผนที่การแปลภาษาไม่เพียงพอ (เพิ่มโดยส่วนขยาย XR_ANDROIDX1_spatial_anchor_cloud_sharing)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_FAILURE_ANDROIDX1

การดำเนินการคงอยู่ไม่สำเร็จเนื่องจากการเชื่อมต่อเครือข่ายล้มเหลว (เพิ่มโดยส่วนขยาย XR_ANDROIDX1_spatial_anchor_cloud_sharing)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_TIMEOUT_ANDROIDX1

การดำเนินการคงอยู่ไม่สำเร็จเนื่องจากเครือข่ายหมดเวลา (เพิ่มโดยส่วนขยาย XR_ANDROIDX1_spatial_anchor_cloud_sharing)

ทำลายบริบทความคงอยู่เชิงพื้นที่

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

XrResult xrDestroySpatialPersistenceContextEXT(
    XrSpatialPersistenceContextEXT              persistenceContext);

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

แอปพลิเคชันสามารถใช้ xrDestroySpatialPersistenceContextEXT เพื่อปล่อยแฮนเดิล persistenceContext เมื่อทำงานด้านความต่อเนื่องเชิงพื้นที่เสร็จแล้ว

รันไทม์ต้องไม่ทำลายทรัพยากรที่สำคัญสำหรับ persistenceContext เมื่อมีการเรียกใช้ xrDestroySpatialPersistenceContextEXT หากมีแฮนเดิล XrSpatialContextEXT ที่ถูกต้องซึ่ง persistenceContext ลิงก์อยู่ผ่าน XrSpatialContextPersistenceConfigEXT เนื่องจากบริบทเชิงพื้นที่ยังคงใช้ทรัพยากรของบริบทความต่อเนื่องเพื่อค้นหาเอนทิตีที่ยังคงอยู่ การทำลายแฮนเดิลบริบทความคงอยู่ (Persistence Context Handle) ในสถานการณ์เช่นนี้จะนำสิทธิ์เข้าถึงทรัพยากรเหล่านี้ของแอปพลิเคชันออกเท่านั้น

ต้องปล่อยทรัพยากรสำหรับ XrSpatialPersistenceContextEXT ที่ถูกทำลายเมื่อแฮนเดิล XrSpatialContextEXT ทั้งหมดที่บริบทการคงอยู่ลิงก์อยู่ถูกทำลาย

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

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

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

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

สำเร็จ

  • XR_SUCCESS

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

ค้นพบเอนทิตีที่ยังคงอยู่

องค์ประกอบความต่อเนื่อง

เอนทิตีเชิงพื้นที่ที่คงอยู่จะมีคอมโพเนนต์ความคงอยู่ซึ่งรันไทม์ต้องรวมไว้ในสแนปชอตการค้นพบและการอัปเดตหากเปิดใช้ XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT ระหว่างการสร้าง XrSpatialContextEXT และรวมไว้ใน XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes หรือ XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes

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

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

typedef struct XrSpatialPersistenceDataEXT {
    XrUuid                          persistUuid;
    XrSpatialPersistenceStateEXT    persistState;
} XrSpatialPersistenceDataEXT;

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

  • persistUuid เป็น XrUuid
  • persistState คือ XrSpatialPersistenceStateEXT ที่แสดงสถานะความคงอยู่ของ persistUuid

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

typedef enum XrSpatialPersistenceStateEXT {
    XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT = 1,
    XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT = 2,
    XR_SPATIAL_PERSISTENCE_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceStateEXT;

การแจงนับ XrSpatialPersistenceStateEXT จะระบุสถานะต่างๆ ของ UUID ที่คงอยู่

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

คำอธิบาย Enum

XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT

โหลด UUID ที่คงอยู่จากพื้นที่เก็บข้อมูลเรียบร้อยแล้ว

XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT

ไม่พบ UUID ที่คงอยู่ในพื้นที่เก็บข้อมูล และถูกนำออกจากพื้นที่เก็บข้อมูลหรือไม่ได้อยู่ในพื้นที่เก็บข้อมูลเลย

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

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

typedef struct XrSpatialComponentPersistenceListEXT {
    XrStructureType                 type;
    void*                           next;
    uint32_t                        persistDataCount;
    XrSpatialPersistenceDataEXT*    persistData;
} XrSpatialComponentPersistenceListEXT;

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

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

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

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

รันไทม์ต้องตั้งค่าข้อมูลสำหรับ XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT โดยไม่คำนึงถึง XrSpatialEntityTrackingStateEXT ซึ่งต่างจากคอมโพเนนต์อื่นๆ

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

การกำหนดค่า

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

กำหนดค่าบริบทเชิงพื้นที่ด้วยบริบทความต่อเนื่อง

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

typedef struct XrSpatialContextPersistenceConfigEXT {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 persistenceContextCount;
    const XrSpatialPersistenceContextEXT*    persistenceContexts;
} XrSpatialContextPersistenceConfigEXT;

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

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

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

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

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_persistence ก่อนใช้ XrSpatialContextPersistenceConfigEXT
  • type ต้องเป็น XR_TYPE_SPATIAL_CONTEXT_PERSISTENCE_CONFIG_EXT
  • next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • persistenceContexts ต้องเป็นตัวชี้ไปยังอาร์เรย์ของแฮนเดิล XrSpatialPersistenceContextEXT ที่ถูกต้อง persistenceContextCount รายการ
  • พารามิเตอร์ persistenceContextCount ต้องมากกว่า 0

สร้างภาพรวมการค้นพบ

ค้นหาเอนทิตีที่มี UUID ที่เฉพาะเจาะจง

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

typedef struct XrSpatialDiscoveryPersistenceUuidFilterEXT {
    XrStructureType    type;
    const void*        next;
    uint32_t           persistedUuidCount;
    const XrUuid*      persistedUuids;
} XrSpatialDiscoveryPersistenceUuidFilterEXT;

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

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

แอปพลิเคชันสามารถใช้ XrSpatialDiscoveryPersistenceUuidFilterEXT ในเชนถัดไปของ XrSpatialDiscoverySnapshotCreateInfoEXT เพื่อกำหนดขอบเขตการดำเนินการค้นหาให้เหลือเพียงเอนทิตีที่มี UUID ที่คงอยู่ซึ่งอยู่ในชุด UUID ที่ระบุใน persistedUuids

หากแอปพลิเคชันเพิ่ม XrSpatialDiscoveryPersistenceUuidFilterEXT ในเชนถัดไปของ XrSpatialDiscoverySnapshotCreateInfoEXT แต่ xrCreateSpatialDiscoverySnapshotAsyncEXT :: spatialContext ไม่ได้กำหนดค่าด้วย XrSpatialPersistenceContextEXT โดยใช้ XrSpatialContextPersistenceConfigEXT รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE จาก xrCreateSpatialDiscoverySnapshotAsyncEXT

รันไทม์ต้องถือว่าตัวกรอง XrSpatialDiscoveryPersistenceUuidFilterEXT เป็นเงื่อนไข "AND" ร่วมกับตัวกรองอื่นๆ ที่ระบุไว้ใน XrSpatialDiscoverySnapshotCreateInfoEXT หรือเชนถัดไป รันไทม์ต้องถือว่าอาร์เรย์ persistedUuids เป็นเงื่อนไข "OR" เช่น ตัวกรองสำหรับเอนทิตีที่มี UUID ใดๆ ที่ระบุไว้ในอาร์เรย์นั้น

รันไทม์ต้องมีรายการ 1 รายการในสแนปชอตที่สร้างขึ้นสำหรับ UUID แต่ละรายการใน persistedUuids ซึ่งสามารถระบุสถานะ XrSpatialPersistenceStateEXT ได้ในขณะนี้

  • หากรันไทม์พบ UUID ในพื้นที่เก็บข้อมูลเรียบร้อยแล้ว ระบบจะดำเนินการดังนี้

    • รันไทม์ต้องตั้งค่า XrSpatialPersistenceStateEXT ใน XrSpatialPersistenceDataEXT ของเอนทิตีนี้เป็น XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT
    • รันไทม์ต้องมี XrSpatialEntityIdEXT ที่ถูกต้องสำหรับเอนทิตีนี้ในสแนปชอตที่สร้างขึ้น
    • รันไทม์ต้องตั้งค่า XrSpatialEntityTrackingStateEXT ของเอนทิตีนั้นเป็น XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT หากกำลังติดตามเอนทิตีนั้นอยู่และมีข้อมูลที่ถูกต้องสำหรับคอมโพเนนต์ของเอนทิตี ไม่เช่นนั้น รันไทม์ต้องตั้งค่า XrSpatialEntityTrackingStateEXT เป็น XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

  • หากรันไทม์ระบุว่าไม่มี UUID อยู่ในพื้นที่เก็บข้อมูล (ไม่ว่า UUID นั้นจะไม่เคยอยู่ในพื้นที่เก็บข้อมูลหรือเคยอยู่แต่ถูกนำออกไปแล้ว) ระบบจะดำเนินการดังนี้

    • รันไทม์ต้องตั้งค่า XrSpatialPersistenceStateEXT ใน XrSpatialPersistenceDataEXT ของเอนทิตีนี้เป็น XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT เพื่อระบุให้แอปพลิเคชันทราบว่า UUID นี้ไม่อยู่ในพื้นที่เก็บข้อมูลอีกต่อไป
    • รันไทม์ต้องตั้งค่า XrSpatialEntityIdEXT สำหรับเอนทิตีนี้ในสแนปชอตที่สร้างขึ้นเป็น XR_NULL_SPATIAL_ENTITY_ID_EXT
    • รันไทม์ต้องตั้งค่า XrSpatialEntityTrackingStateEXT ของเอนทิตีนั้นเป็น XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT เพื่อระบุให้แอปพลิเคชันทราบว่าเอนทิตีนี้จะไม่ได้รับการติดตาม

  • หากรันไทม์ไม่สามารถระบุได้ว่า UUID อยู่ในพื้นที่เก็บข้อมูลหรือไม่ รันไทม์ต้องไม่รวม UUID ไว้ในสแนปชอต

แอปพลิเคชันยังสามารถใช้ XrSpatialDiscoveryPersistenceUuidFilterEXT ในเชนถัดไปของ XrSpatialComponentDataQueryConditionEXT เพื่อค้นหาเอนทิตีของ UUID ที่เฉพาะเจาะจงในสแนปชอตที่มีอยู่ได้ด้วย เมื่อใช้กับ XrSpatialComponentDataQueryConditionEXT หาก XrSpatialDiscoveryPersistenceUuidFilterEXT :: persistedUuids มี XrUuid ที่ไม่ได้อยู่ใน XrSpatialSnapshotEXT รันไทม์ต้องไม่รวมรายการสำหรับ XrUuid นั้นในผลการค้นหา นอกจากนี้ ลำดับ (ลําดับ) ของเอนทิตีในผลการค้นหาอาจไม่ตรงกับลําดับของ UUID ที่ระบุใน XrSpatialDiscoveryPersistenceUuidFilterEXT :: persistedUuids แอปพลิเคชันควรรวม XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT ไว้ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes และ XrSpatialComponentPersistenceListEXT ในเชนถัดไปของ XrSpatialComponentDataQueryResultEXT จากนั้นตรวจสอบ XrSpatialPersistenceDataEXT :: persistUuid ของดัชนีผลการค้นหาแต่ละรายการเพื่อทำความเข้าใจว่าดัชนีผลการค้นหาปัจจุบันสอดคล้องกับ UUID ใด

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

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_persistence ก่อนใช้ XrSpatialDiscoveryPersistenceUuidFilterEXT
  • type ต้องเป็น XR_TYPE_SPATIAL_DISCOVERY_PERSISTENCE_UUID_FILTER_EXT
  • next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • persistedUuids ต้องเป็นพอยเตอร์ไปยังอาร์เรย์ของโครงสร้าง persistedUuidCount XrUuid
  • พารามิเตอร์ persistedUuidCount ต้องมากกว่า 0
ค้นพบเอนทิตีที่ยังคงอยู่ทั้งหมด

หากแอปพลิเคชันใช้ xrCreateSpatialDiscoverySnapshotAsyncEXT โดยไม่มี XrSpatialDiscoveryPersistenceUuidFilterEXT และมี XrSpatialContextEXT ซึ่งกำหนดค่าด้วย XrSpatialPersistenceContextEXT รันไทม์ต้องรวมเอนทิตีเหล่านั้นไว้ในสแนปชอตที่สร้างขึ้นซึ่งคงอยู่ในพื้นที่เก็บข้อมูลที่แสดงโดย XrSpatialPersistenceContextEXT และเป็นไปตามตัวกรองที่ระบุใน XrSpatialDiscoverySnapshotCreateInfoEXT สำหรับเอนทิตีเหล่านั้น

  • รันไทม์ต้องตั้งค่า XrSpatialPersistenceStateEXT ใน XrSpatialPersistenceDataEXT ของเอนทิตีนี้เป็น XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT
  • รันไทม์ต้องมี XrSpatialEntityIdEXT ที่ถูกต้องสำหรับเอนทิตีนี้ในสแนปชอตที่สร้างขึ้น
  • รันไทม์ต้องตั้งค่า XrSpatialEntityTrackingStateEXT ของเอนทิตีนั้นเป็น XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT หากกำลังติดตามเอนทิตีนั้นอยู่และมีข้อมูลที่ถูกต้องสำหรับคอมโพเนนต์ของเอนทิตี ไม่เช่นนั้น รันไทม์ต้องตั้งค่า XrSpatialEntityTrackingStateEXT เป็น XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

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

คำสั่งใหม่

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

Enum ใหม่

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

  • XR_EXT_SPATIAL_PERSISTENCE_EXTENSION_NAME
  • XR_EXT_spatial_persistence_SPEC_VERSION

  • การขยาย XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_PERSISTENCE_CONTEXT_EXT

  • การขยาย XrResult :

    • XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_UNSUPPORTED_EXT

  • การขยาย XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

  • การขยาย XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_PERSISTENCE_CONTEXT_COMPLETION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_PERSISTENCE_CONFIG_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_PERSISTENCE_UUID_FILTER_EXT
    • XR_TYPE_SPATIAL_PERSISTENCE_CONTEXT_CREATE_INFO_EXT

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

สร้างบริบทความต่อเนื่อง

// Check if the required persistence scope supported
uint32_t scopeCount;
CHK_XR(xrEnumerateSpatialPersistenceScopesEXT(instance, systemId, 0, &scopeCount, nullptr));
std::vector<XrSpatialPersistenceScopeEXT> persistenceScopes(scopeCount);
CHK_XR(xrEnumerateSpatialPersistenceScopesEXT(instance, systemId, scopeCount, &scopeCount, persistenceScopes.data()));

if (std::find(persistenceScopes.begin(), persistenceScopes.end(), XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT) == persistenceScopes.end()) {
  return;
}

XrSpatialPersistenceContextEXT persistenceContext{};

XrSpatialPersistenceContextCreateInfoEXT persistenceContextCreateInfo{XR_TYPE_SPATIAL_PERSISTENCE_CONTEXT_CREATE_INFO_EXT};
persistenceContextCreateInfo.scope = XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT;
XrFutureEXT createContextFuture;
CHK_XR(xrCreateSpatialPersistenceContextAsyncEXT(session, &persistenceContextCreateInfo, &createContextFuture));

waitUntilReady(createContextFuture);

XrCreateSpatialPersistenceContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_PERSISTENCE_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialPersistenceContextCompleteEXT(session, createContextFuture, &completion));
if (completion.futureResult != XR_SUCCESS || completion.createResult != XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT) {
  return;
}

persistenceContext = completion.persistenceContext;

// ...
// Connect persistence context to a spatial context and discover persisted entities.
// ...

CHK_XR(xrDestroySpatialPersistenceContextEXT(persistenceContext));

เชื่อมต่อบริบทความต่อเนื่องกับบริบทเชิงพื้นที่

// Note: Anchor capability is just used as an example here. Persistence can be
// supported by other capabilities too. xrEnumerateSpatialCapabilityComponentTypesEXT() can
// be used to check if a certain capability supports persistence.
if (!isSpatialCapabilitySupported(instance, systemId, XR_SPATIAL_CAPABILITY_ANCHOR_EXT)) {
  return;
}

const bool supportsPersistenceComponent = isSpatialComponentSupported(instance, systemId, XR_SPATIAL_CAPABILITY_ANCHOR_EXT, XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT);

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{

  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  if (supportsPersistenceComponent) {
    enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT);
  }

  XrSpatialCapabilityConfigurationAnchorEXT anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrSpatialContextPersistenceConfigEXT persistenceConfig{XR_TYPE_SPATIAL_CONTEXT_PERSISTENCE_CONFIG_EXT};
  persistenceConfig.persistenceContextCount = 1;
  persistenceConfig.persistenceContexts = &persistenceContext;

  if (supportsPersistenceComponent) {
    spatialContextCreateInfo.next = &persistenceConfig;
  }

  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = completion.spatialContext;
}

// ...
// Discover persisted anchors.
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

ค้นพบเอนทิตีที่ยังคงอยู่ทั้งหมด

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialPersistenceDataEXT> persistenceData(queryResult.entityIdCountOutput);
    XrSpatialComponentPersistenceListEXT persistenceDataList{XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT};
    persistenceDataList.persistDataCount = persistenceData.size();
    persistenceDataList.persistData = persistenceData.data();
    queryResult.next = &persistenceDataList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      // persistenceData[i].persistUuid is the UUID of the persisted entity whose entity ID is entityIds[i].
      // The persistenceData array is essentially the uuids persisted in the scope that the current
      // XrSpatialPersistenceContextEXT is configured with.
    }

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

ค้นหาเอนทิตีที่มี UUID ที่เฉพาะเจาะจง

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// Load up the uuids that the app has stored on its own i.e. the uuids it is interested in.
std::vector<XrUuid> uuidsStoredByApp = loadPersistedUuids();

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoveryPersistenceUuidFilterEXT persistenceFilter{XR_TYPE_SPATIAL_DISCOVERY_PERSISTENCE_UUID_FILTER_EXT};
  persistenceFilter.persistedUuidCount = uuidsStoredByApp.size();
  persistenceFilter.persistedUuids = uuidsStoredByApp.data();

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  snapshotCreateInfo.next = &persistenceFilter;

  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialPersistenceDataEXT> persistenceData(queryResult.entityIdCountOutput);
    XrSpatialComponentPersistenceListEXT persistenceDataList{XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT};
    persistenceDataList.persistDataCount = persistenceData.size();
    persistenceDataList.persistData = persistenceData.data();
    queryResult.next = &persistenceDataList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (persistenceData[i].persistState == XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT) {
        // persistenceData[i].persistUuid, requested by the app, is present in the persistence scope
        // and its corresponding entity ID and state are entityIds[i] & entityStates[i] respectively.
      } else if (persistenceData[i].persistState == XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT) {
        // persistenceData[i].persistUuid, requested by the app, is NOT present in the persistence scope
        // and its corresponding entity ID (entityIds[i]) would be XR_NULL_SPATIAL_ENTITY_ID_EXT
        // and tracking state (entityStates[i]) would be XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT.
      }
    }

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

ปัญหา

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

  • ฉบับแก้ไข 1, 29-08-2024 (Nihav Jain, Google)

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