XR_ANDROID_spatial_anchor_space

Name String

XR_ANDROID_spatial_anchor_space

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

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

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

796

การแก้ไข

1

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

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

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

XR_EXT_spatial_anchor

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

2025-09-15

สถานะ IP

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

ผู้เขียน

YuSheng Chang, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google

ภาพรวม

ฟังก์ชัน xrCreateSpatialAnchorEXT ที่กำหนดไว้ในส่วนขยาย XR_EXT_spatial_anchor ช่วยให้แอปพลิเคชันสร้าง Anchor เชิงพื้นที่ด้วยแฮนเดิล XrSpatialEntityEXT เพื่อแสดงแอปพลิเคชันได้ ในทางตรงกันข้าม ส่วนขยายนี้จะสร้าง Anchor เชิงพื้นที่ซึ่งแสดงด้วยแฮนเดิล XrSpace แทน ซึ่งจะเป็นประโยชน์ในกรณีที่แอปพลิเคชันต้องการทำสิ่งต่อไปนี้

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

Anchor ที่สร้างด้วยส่วนขยายนี้ไม่สามารถคงอยู่ได้โดยใช้ส่วนขยาย XR_ANDROID_device_anchor_persistence และแอปพลิเคชันต้องใช้ XR_EXT_spatial_persistence_operations แทน รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE จาก xrPersistAnchorANDROID หากสร้าง XrPersistedAnchorSpaceInfoANDROID :: anchor โดยใช้ xrCreateSpatialAnchorSpaceANDROID หรือ xrCreateSpatialAnchorSpaceFromIdANDROID

สร้าง XrSpace สำหรับ Anchor เชิงมิติพื้นที่

สร้างสมอเชิงพื้นที่และพื้นที่ทำงาน

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

XrResult xrCreateSpatialAnchorSpaceANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpace*                                    anchorSpace);

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

  • session คือแฮนเดิลของ XrSession ที่สร้างไว้ก่อนหน้านี้ด้วย xrCreateSession
  • spatialContext คือ XrSpatialContextEXT ที่สร้างขึ้นก่อนหน้านี้โดยใช้ xrCreateSpatialContextAsyncEXT
  • createInfo คือตัวชี้ไปยัง XrSpatialAnchorCreateInfoEXT
  • anchorEntityId เป็นตัวชี้ไปยัง XrSpatialEntityIdEXT
  • anchorSpace เป็นตัวชี้ไปยัง XrSpace

ฟังก์ชัน xrCreateSpatialAnchorSpaceANDROID จะสร้าง Anchor ที่แสดงผล XrSpatialEntityIdEXT และแฮนเดิล XrSpace โดย xrCreateSpatialAnchorSpaceANDROID มีข้อกำหนดด้านการตรวจสอบความถูกต้องเหมือนกับ xrCreateSpatialAnchorEXT

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE หาก XrSpatialContextEXT ที่ส่งไปยัง xrCreateSpatialAnchorSpaceANDROID ไม่ได้กำหนดค่าด้วย XR_SPATIAL_CAPABILITY_ANCHOR_EXT

ในส่วนของการค้นพบ Anchor ที่สร้างโดย xrCreateSpatialAnchorSpaceANDROID ย่อหน้าสุดท้ายของข้อกำหนด xrCreateSpatialAnchorEXT จะมีผล

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

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_spatial_anchor_space ก่อนเรียกใช้ xrCreateSpatialAnchorSpaceANDROID
  • session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
  • spatialContext ต้องเป็นแฮนเดิล XrSpatialContextEXT ที่ถูกต้อง
  • createInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialAnchorCreateInfoEXT ที่ถูกต้อง
  • anchorEntityId ต้องเป็นตัวชี้ไปยังค่า XrSpatialEntityIdEXT
  • anchorSpace ต้องเป็นตัวชี้ไปยังแฮนเดิล XrSpace
  • spatialContext ต้องสร้าง จัดสรร หรือดึงข้อมูลจาก session

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

สำเร็จ

  • 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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

สร้าง XrSpace จาก Anchor เชิงพื้นที่ที่มีอยู่

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

XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorSpace);

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

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

ฟังก์ชัน xrCreateSpatialAnchorSpaceFromIdANDROID จะสร้างแฮนเดิล XrSpace โดยระบุ XrSpatialEntityIdEXT ในช่อง XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE หาก XrSpatialContextEXT ที่ส่งไปยัง xrCreateSpatialAnchorSpaceFromIdANDROID ไม่ได้กำหนดค่าด้วย XR_SPATIAL_CAPABILITY_ANCHOR_EXT

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

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_spatial_anchor_space ก่อนเรียกใช้ xrCreateSpatialAnchorSpaceFromIdANDROID
  • session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
  • spatialContext ต้องเป็นแฮนเดิล XrSpatialContextEXT ที่ถูกต้อง
  • createInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialAnchorSpaceFromIdCreateInfoANDROID ที่ถูกต้อง
  • anchorSpace ต้องเป็นตัวชี้ไปยังแฮนเดิล XrSpace
  • spatialContext ต้องสร้าง จัดสรร หรือดึงข้อมูลจาก session

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

สำเร็จ

  • 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_ANCHOR_ENTITY_ID_INVALID_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • anchorEntityId คือ XrSpatialEntityIdEXT ของ Anchor เชิงพื้นที่ที่มีอยู่ซึ่งใช้สร้าง XrSpace

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT หาก XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId ไม่ใช่รหัสที่ถูกต้องสำหรับ spatialContext

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID หาก XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId ไม่ใช่รหัสเอนทิตีที่ถูกต้องสำหรับ Anchor

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

วงจรของ Anchor

แฮนเดิลหลักของ XrSpace คือ XrSession ซึ่งหมายความว่าแฮนเดิล XrSpace ที่แสดงถึง Anchor จะยังคงใช้ได้แม้ว่าจะทำลาย xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext หรือ xrCreateSpatialAnchorSpaceANDROID :: spatialContext แล้วก็ตาม การสร้าง XrSpace เพื่อแสดง Anchor ของเอนทิตีเชิงพื้นที่ช่วยให้แอปพลิเคชันทำลาย XrSpatialContextEXT ที่กำหนดค่าด้วย XR_SPATIAL_CAPABILITY_ANCHOR_EXT ได้ ขณะที่ยังคงรับท่าทางล่าสุดของ Anchor โดยใช้ XrSpace กับ xrLocateSpaces ต่อไป กล่าวคือ รันไทม์ต้องติดตาม Anchor ต่อไปจนกว่าแฮนเดิล XrSpace ทั้งหมดที่แสดง Anchor นั้นจะถูกทำลาย

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

สร้าง Anchor เชิงพื้นที่เป็น XrSpace

โค้ดตัวอย่างต่อไปนี้แสดงวิธีสร้าง Anchor เชิงพื้นที่และแสดงผลเป็น XrSpace

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpace spatialAnchorSpace {XR_NULL_HANDLE}; // XrSpace handle of anchor

// Spatial anchor create info
XrSpatialAnchorCreateInfoEXT createInfo{
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

// Create spatial anchor using the new API
CHK_XR(xrCreateSpatialAnchorSpaceANDROID(session, spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorSpace));

// ...

สร้าง XrSpace จากรหัสเอนทิตี Anchor

โค้ดตัวอย่างต่อไปนี้แสดงวิธีสร้าง XrSpace จากรหัสเอนทิตี Anchor ที่มีอยู่แล้ว

XrSpace anchorSpace = XR_NULL_HANDLE;

// Spatial anchor from XrSpace create info
XrSpatialAnchorSpaceFromIdCreateInfoANDROID createInfoFromId{
  .type = XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID,
  .anchorEntityId = spatialAnchorEntityId,
};

// Create XrSpace handle from spatial anchor ID
CHK_XR(xrCreateSpatialAnchorSpaceFromIdANDROID(session, spatialContext, &createInfoFromId, &anchorSpace));

// ...

คำสั่งใหม่

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

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

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

  • การขยาย XrResult :

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

  • การขยาย XrStructureType :

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

ปัญหา

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

  • การแก้ไข 1, 15-09-2025 (YuSheng Chang, Kyle Chen)

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