XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

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

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

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

790

การแก้ไข

1

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

ยังไม่ให้สัตยาบัน

การขึ้นต่อกันของส่วนขยายและเวอร์ชัน

XR_EXT_future

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

2025-12-18

สถานะ IP

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

ผู้เขียน

John Ullman, Google
Ben King, Google
Nihav Jain, Google
Jared Finder, Google

ภาพรวม

ส่วนขยายนี้ให้การติดตามภูมิสารสนเทศเชิงพื้นที่สำหรับ Geospatial API ของ Google ซึ่งให้ตำแหน่งทางภูมิศาสตร์และการวางแนวที่แม่นยำ และช่วยให้แอปพลิเคชันวางเนื้อหาที่เกี่ยวข้องกับโลกได้ โดยจะใช้การติดตามการเคลื่อนไหว, GPS และเซ็นเซอร์อื่นๆ รวมถึงระบบกำหนดตำแหน่งด้วยภาพ (VPS) ของ Google VPS จะเปรียบเทียบรูปภาพจากกล้องของอุปกรณ์กับภาพ Street View เพื่อระบุตำแหน่งที่แน่นอนและทิศทาง Geospatial API มักจะให้ความแม่นยำของตำแหน่งในระดับต่ำกว่า 1 เมตร (ดีกว่า GPS หลายเท่า) และความแม่นยำของทิศทางในระดับต่ำกว่า 1 องศา

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

สิทธิ์

แอปพลิเคชัน Android ต้องมีสิทธิ์ android.permission.ACCESS_FINE_LOCATION แสดงอยู่ในไฟล์ Manifest เพื่อใช้ส่วนขยายนี้ สิทธิ์ android.permission.ACCESS_FINE_LOCATION ถือเป็นสิทธิ์ที่เป็นอันตราย แอปพลิเคชันต้องขอสิทธิ์ขณะรันไทม์เพื่อใช้ฟังก์ชันต่อไปนี้

(ระดับการป้องกัน: อันตราย)

ตรวจสอบความสามารถของระบบ

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

typedef struct XrSystemGeospatialPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGeospatial;
} XrSystemGeospatialPropertiesANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • supportsGeospatial คือ XrBool32 ที่ระบุว่าระบบปัจจุบันรองรับฟีเจอร์เชิงพื้นที่หรือไม่

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

หากรันไทม์แสดงผล XR_FALSE สำหรับ supportsGeospatial ระบบจะไม่รองรับฟีเจอร์เชิงพื้นที่ ดังนั้นจึงต้องแสดงผล XR_ERROR_FEATURE_UNSUPPORTED จาก xrCreateGeospatialTrackerANDROID แอปพลิเคชันควรหลีกเลี่ยงการใช้ฟังก์ชันการทำงานด้านข้อมูลเชิงพื้นที่เมื่อ supportsGeospatial เป็น XR_FALSE

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

สร้างแฮนเดิล Geospatial Tracker

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

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

XrResult xrCreateGeospatialTrackerANDROID(
    XrSession                                   session,
    const XrGeospatialTrackerCreateInfoANDROID* createInfo,
    XrGeospatialTrackerANDROID*                 geospatialTrackerOutput);

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

  • session คือ XrSession ที่ตัวติดตามตำแหน่งทางภูมิศาสตร์จะทำงาน
  • createInfo คือตัวชี้ไปยังโครงสร้าง XrGeospatialTrackerCreateInfoANDROID ที่ระบุพารามิเตอร์เริ่มต้นของเครื่องมือติดตามตำแหน่งทางภูมิศาสตร์
  • geospatialTrackerOutput คือตัวชี้ไปยังแฮนเดิลที่ส่งคืน XrGeospatialTrackerANDROID ที่สร้างขึ้น

แอปพลิเคชันสามารถสร้างแฮนเดิล XrGeospatialTrackerANDROID ได้โดยการเรียกใช้ xrCreateGeospatialTrackerANDROID จากนั้นXrGeospatialTrackerANDROID แฮนเดิลที่ส่งคืนจะใช้ในการเรียก API ได้ หากแอปพลิเคชันไม่ได้รับสิทธิ์ที่จำเป็น รันไทม์ต้องแสดงผล XR_ERROR_PERMISSION_INSUFFICIENT XrGeospatialTrackerANDROID can มีได้ครั้งละ 1 รายการเท่านั้นสำหรับ XrSession ที่เฉพาะเจาะจง แอปพลิเคชันต้องตรวจสอบว่าออบเจ็กต์ XrGeospatialTrackerANDROID ก่อนหน้าถูกทำลายแล้วก่อนที่จะเรียกใช้ฟังก์ชันนี้อีกครั้ง ไม่เช่นนั้นรันไทม์ต้องส่งคืน XR_ERROR_LIMIT_REACHED หากสร้างเครื่องมือติดตามสำเร็จ เครื่องมือติดตามจะเข้าสู่สถานะ XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID ในตอนแรก และแอปพลิเคชันต้องรอจนกว่าสถานะจะเปลี่ยนเป็น XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID ก่อนจึงจะใช้เครื่องมือติดตามได้ ดู XrEventDataGeospatialTrackerStateChangedANDROID หากแอปพลิเคชันส่ง XrGeospatialTrackerANDROID ที่ไม่ได้อยู่ในสถานะ XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID ไปยังฟังก์ชันที่ต้องใช้รันไทม์ ต้องแสดงผล XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

ในที่สุดจะต้องปล่อยแฮนเดิล XrGeospatialTrackerANDROID ผ่านฟังก์ชัน xrDestroyGeospatialTrackerANDROID

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

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_geospatial ก่อนที่จะเรียกใช้ xrCreateGeospatialTrackerANDROID
  • session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
  • createInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrGeospatialTrackerCreateInfoANDROID ที่ถูกต้อง
  • geospatialTrackerOutput ต้องเป็นตัวชี้ไปยังแฮนเดิล XrGeospatialTrackerANDROID

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

สำเร็จ

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

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

typedef struct XrGeospatialTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrGeospatialTrackerCreateInfoANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง

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

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

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

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

แอปพลิเคชันสามารถใช้ฟังก์ชัน xrDestroyGeospatialTrackerANDROID เพื่อปล่อยเครื่องมือติดตามตำแหน่งทางภูมิศาสตร์และทรัพยากรพื้นฐานได้

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

ความปลอดภัยของเธรด

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

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

สำเร็จ

  • XR_SUCCESS

ความล้มเหลว

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

สถานะเครื่องมือติดตามภูมิสารสนเทศ

การแจงนับ XrGeospatialTrackerStateANDROID มีคำจำกัดความดังนี้

typedef enum XrGeospatialTrackerStateANDROID {
    XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID = 0,
    XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID = 1,
    XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID = 2,
    XR_GEOSPATIAL_TRACKER_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGeospatialTrackerStateANDROID;

การแจงนับ XrGeospatialTrackerStateANDROID จะระบุสถานะต่างๆ ของเครื่องมือติดตามตำแหน่งทางภูมิศาสตร์

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

คำอธิบาย Enum

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Geospatial Tracker ไม่ทำงาน

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

เครื่องมือติดตามทางภูมิศาสตร์ทำงานอยู่และใช้งานได้

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

เริ่มต้น Geospatial Tracker ไม่สำเร็จและจะใช้ไม่ได้

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

typedef struct XrEventDataGeospatialTrackerStateChangedANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrGeospatialTrackerANDROID         geospatialTracker;
    XrGeospatialTrackerStateANDROID    state;
    XrResult                           initializationResult;
    XrTime                             time;
} XrEventDataGeospatialTrackerStateChangedANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • geospatialTracker คือ XrGeospatialTrackerANDROID ที่มีการเปลี่ยนแปลงสถานะ
  • state คือ XrGeospatialTrackerStateANDROID ใหม่
  • initializationResult คือผลลัพธ์ข้อผิดพลาดหาก state เป็น XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID หรือ XR_SUCCESS ในกรณีอื่นๆ
  • time คือ XrTime ที่เกิดการเปลี่ยนแปลงสถานะ

ระบบจะส่งโครงสร้าง XrEventDataGeospatialTrackerStateChangedANDROID เมื่อสถานะของเครื่องมือติดตามตำแหน่งเชิงพื้นที่เปลี่ยนแปลง หากแอปพลิเคชันมี XrGeospatialTrackerANDROID ที่ถูกต้อง ควรสำรวจเหตุการณ์นี้ เหตุการณ์แรกที่ได้รับสําหรับเครื่องมือติดตามจะมี state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID หลังจากผ่านไปเป็นระยะเวลาตามที่กำหนดในรันไทม์ สถานะต้องเปลี่ยนเป็น XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID หรือ XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID การเปลี่ยนผ่านนี้จะใช้เวลาตามที่กำหนด หาก state เปลี่ยนเป็น XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID ต้องเป็นเหตุการณ์สุดท้ายที่ได้รับสำหรับเครื่องมือติดตามนี้ และฟิลด์ initializationResult จะมีรหัสข้อผิดพลาด ข้อผิดพลาดอาจใช้เวลาหลายวินาทีจึงจะเกิดขึ้น แอปพลิเคชันควรทำลายเครื่องมือติดตามในกรณีนี้ หาก state เปลี่ยนเป็น XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID สมอแบบอิงตามพื้นที่ทางภูมิศาสตร์ทั้งหมดที่สร้างไว้ก่อนหน้านี้ต้องหยุดการติดตามอย่างถาวรและแอปพลิเคชันควรทำลายสมอเหล่านั้น สถานะอาจเปลี่ยนไปมาระหว่าง XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID กับ XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID หลายครั้งโดยไม่มีลำดับที่แน่นอน

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

ท่าทางภูมิสารสนเทศ

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

typedef struct XrGeospatialPoseANDROID {
    XrQuaternionf    eastUpSouthOrientation;
    double           latitude;
    double           longitude;
    double           altitude;
} XrGeospatialPoseANDROID;

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

  • eastUpSouthOrientation คือ XrQuaternionf ที่กำหนดการวางแนวเทียบกับระบบพิกัดที่ +X=ตะวันออก, +Y=ขึ้น และ +Z=ใต้
  • latitude คือละติจูดในหน่วยองศา ซึ่งอยู่ระหว่าง -90 ถึง +90
  • longitude คือลองจิจูดในหน่วยองศา ซึ่งอยู่ระหว่าง -180 ถึง +180
  • altitude คือระดับความสูงเป็นเมตรเหนือรูปทรงรี WGS84

โครงสร้าง XrGeospatialPoseANDROID แสดงถึงตำแหน่งและการวางแนวที่สัมพันธ์กับโลกโดยใช้รูปทรงรี WGS84

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

  • ต้องเปิดใช้XR_ANDROID_geospatialส่วนขยายก่อนจึงจะใช้ XrGeospatialPoseANDROID ได้
  • latitude ต้องเป็นค่า double ที่ถูกต้อง
  • longitude ต้องเป็นค่า double ที่ถูกต้อง
  • altitude ต้องเป็นค่า double ที่ถูกต้อง

การแจงนับ XrGeospatialPoseFlagBitsANDROID มีการกำหนดไว้ดังนี้

// Flag bits for XrGeospatialPoseFlagsANDROID
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID = 0x00000001;
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID = 0x00000002;

การแจงนับ XrGeospatialPoseFlagBitsANDROID จะระบุแฟล็กสำหรับท่าทางเชิงพื้นที่

บิตของแฟล็กมีความหมายดังนี้

คำอธิบายของแฟล็ก

  • XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID — ระบุว่าสมาชิกการวางแนวมีข้อมูลที่ถูกต้อง
  • XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID — ระบุว่าสมาชิกตำแหน่งมีข้อมูลที่ถูกต้อง

ประเภท XrGeospatialPoseFlagsANDROID คือบิตมาสก์ของ XrGeospatialPoseFlagBitsANDROID

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

การแปลง XrPosef เป็นท่าทางภูมิสารสนเทศ

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

XrResult xrLocateGeospatialPoseFromPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseFromPoseLocateInfoANDROID* locateInfo,
    XrGeospatialPoseResultANDROID*              geospatialPoseResult);

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

ฟังก์ชัน xrLocateGeospatialPoseFromPoseANDROID จะแปลงท่าทางใน XrGeospatialPoseFromPoseLocateInfoANDROID :: space เป็นท่าทางเชิงพื้นที่ หากสถานะของ geospatialTracker ไม่ใช่ XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID รันไทม์ต้องแสดงผล XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID หากฟังก์ชันแสดงผล XR_SUCCESS ฟิลด์ XrGeospatialPoseResultANDROID :: poseFlags ของ geospatialPoseResult จะกำหนดว่าฟิลด์เอาต์พุตใดที่ถูกต้อง หากไม่ได้ตั้งค่า XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID ใน XrGeospatialPoseResultANDROID :: poseFlags แอปพลิเคชันต้องไม่อ่านฟิลด์ XrGeospatialPoseANDROID :: latitude, XrGeospatialPoseANDROID :: longitude, XrGeospatialPoseANDROID :: altitude, XrGeospatialPoseResultANDROID :: horizontalAccuracy หรือ XrGeospatialPoseResultANDROID :: verticalAccuracy ใน XrGeospatialPoseResultANDROID หากไม่ได้ตั้งค่า XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID ใน XrGeospatialPoseResultANDROID :: poseFlags แอปพลิเคชันต้องไม่อ่าน XrGeospatialPoseANDROID :: eastUpSouthOrientation หรือ XrGeospatialPoseResultANDROID :: orientationYawAccuracy หากไม่ได้ตั้งค่า XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID ก็ต้องไม่ได้ตั้งค่า XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID ด้วย

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

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

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialPoseFromPoseLocateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrPosef            pose;
} XrGeospatialPoseFromPoseLocateInfoANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • space คือ XrSpace ที่กำหนด pose
  • time คือ XrTime ที่ใช้ประเมิน pose
  • pose คือ XrPosef ใน space ที่จะแปลงเป็นท่าทางเชิงพื้นที่

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

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

typedef struct XrGeospatialPoseResultANDROID {
    XrStructureType                 type;
    void*                           next;
    XrGeospatialPoseFlagsANDROID    poseFlags;
    XrGeospatialPoseANDROID         geospatialPose;
    double                          horizontalAccuracy;
    double                          verticalAccuracy;
    double                          orientationYawAccuracy;
} XrGeospatialPoseResultANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • poseFlags คือบิตมาสก์ของ XrGeospatialPoseFlagsANDROID ที่ระบุความถูกต้องของคอมโพเนนต์ท่าทาง
  • geospatialPose คือ XrGeospatialPoseANDROID ที่ได้
  • horizontalAccuracy คือความแม่นยำในแนวนอนโดยประมาณของตำแหน่งท่าทางเชิงพื้นที่ ซึ่งกำหนดเป็นรัศมีในหน่วยเมตรของวงกลมที่มีระดับความเชื่อมั่น 68% รอบละติจูดและลองจิจูดที่ระบุ
  • verticalAccuracy คือความแม่นยำในแนวตั้งโดยประมาณของตำแหน่งท่าทางเชิงพื้นที่ ซึ่งกำหนดเป็นระยะทางในหน่วยเมตรที่ระดับความเชื่อมั่น 68% รอบระดับความสูงที่กำหนด กล่าวคือ มีโอกาส 68% ที่ระดับความสูงจริงจะอยู่ในช่วง [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ]
  • orientationYawAccuracy คือความแม่นยำของท่าทางเชิงพื้นที่ที่ประมาณค่าไว้ ซึ่งกำหนดเป็นรัศมีในหน่วยองศาของระดับความเชื่อมั่น 68% รอบๆ ท่าทางที่กำหนด

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

การแปลงท่าทางของภูมิสารสนเทศเป็น XrPosef

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

XrResult xrLocateGeospatialPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseLocateInfoANDROID*    locateInfo,
    XrSpaceLocation*                            location);

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

  • geospatialTracker คือ XrGeospatialTrackerANDROID ที่ใช้สำหรับการแปลง
  • locateInfo เป็น Pointer ไปยัง XrGeospatialPoseLocateInfoANDROID ที่มีพารามิเตอร์การค้นหา
  • location คือ Pointer ไปยัง XrSpaceLocation ที่ได้รับท่าทางที่ได้

ฟังก์ชัน xrLocateGeospatialPoseANDROID จะแปลงท่าทางเชิงพื้นที่เป็น XrSpaceLocation หาก XrGeospatialTrackerANDROID ไม่ได้ทำงาน รันไทม์ต้องแสดงผล XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID หากฟังก์ชันแสดงผล XR_SUCCESS ฟิลด์ XrSpaceLocation :: locationFlags ของ location จะกำหนดว่าฟิลด์เอาต์พุตใดที่ถูกต้อง

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

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_geospatial ก่อนที่จะเรียกใช้ xrLocateGeospatialPoseANDROID
  • geospatialTracker ต้องเป็นแฮนเดิล XrGeospatialTrackerANDROID ที่ถูกต้อง
  • locateInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrGeospatialPoseLocateInfoANDROID ที่ถูกต้อง
  • location ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpaceLocation

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialPoseLocateInfoANDROID {
    XrStructureType            type;
    const void*                next;
    XrSpace                    space;
    XrTime                     time;
    XrGeospatialPoseANDROID    geospatialPose;
} XrGeospatialPoseLocateInfoANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • space คือ XrSpace ที่จะใช้แสดงท่าทางที่ได้
  • time คือ XrTime ที่ใช้ระบุตำแหน่งท่าทาง
  • geospatialPose คือ XrGeospatialPoseANDROID ที่จะแปลง

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

ความพร้อมใช้งานของ VPS

การแจงนับ XrVPSAvailabilityANDROID มีคำจำกัดความดังนี้

typedef enum XrVPSAvailabilityANDROID {
    XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID = 1,
    XR_VPS_AVAILABILITY_AVAILABLE_ANDROID = 2,
    XR_VPSAVAILABILITY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrVPSAvailabilityANDROID;

การแจงนับ XrVPSAvailabilityANDROID จะระบุความพร้อมใช้งานของ VPS

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

คำอธิบาย Enum

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

VPS ไม่พร้อมให้บริการใกล้ตำแหน่งที่ระบุ

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

VPS พร้อมให้บริการในบริเวณใกล้เคียงกับสถานที่ที่ระบุ

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

XrResult xrCheckVpsAvailabilityAsyncANDROID(
    XrSession                                   session,
    double                                      latitude,
    double                                      longitude,
    XrFutureEXT*                                future);

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

  • session คือ XrSession ที่จะใช้ในการตรวจสอบ
  • latitude คือละติจูดในหน่วยองศา
  • longitude คือลองจิจูดในหน่วยองศา
  • future เป็นตัวชี้ไปยัง XrFutureEXT ซึ่งจะเก็บผลลัพธ์ของการดำเนินการแบบอะซิงโครนัส

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

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

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

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_geospatial ก่อนที่จะเรียกใช้ xrCheckVpsAvailabilityAsyncANDROID
  • session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
  • latitude ต้องเป็นค่า double ที่ถูกต้อง
  • longitude ต้องเป็นค่า double ที่ถูกต้อง
  • future ต้องเป็นตัวชี้ไปยังค่า XrFutureEXT

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCheckVpsAvailabilityCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrVPSAvailabilityCheckCompletionANDROID*    completion);

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

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

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

สำเร็จ

  • 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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrVPSAvailabilityCheckCompletionANDROID {
    XrStructureType             type;
    void*                       next;
    XrResult                    futureResult;
    XrVPSAvailabilityANDROID    availability;
} XrVPSAvailabilityCheckCompletionANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • futureResult คือ XrResult ของการดำเนินการตรวจสอบ หาก futureResult เป็น XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID โครงสร้างในเชน next อาจให้ข้อมูลเพิ่มเติมเกี่ยวกับความล้มเหลว
  • availability คือ XrVPSAvailabilityANDROID ที่ได้ แอปพลิเคชันต้องไม่อ่านฟิลด์นี้ เว้นแต่ futureResult จะเป็น XR_SUCCESS

รหัสการแสดงผลในอนาคต

ค่า futureResult

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

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

ตัวอย่าง

ตั้งค่า Geospatial Tracker

PFN_xrCheckVpsAvailabilityAsyncANDROID xrCheckVpsAvailabilityAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCheckVpsAvailabilityCompleteANDROID xrCheckVpsAvailabilityCompleteANDROID;
PFN_xrCreateGeospatialTrackerANDROID xrCreateGeospatialTrackerANDROID;
XrInstance instance = XR_NULL_HANDLE;
XrSystemId systemId = XR_NULL_SYSTEM_ID;
XrSession session = XR_NULL_HANDLE;
double lat = 37.422, lng = -122.084;

// Check for support.
XrSystemGeospatialPropertiesANDROID geospatialSystemProperties{
    XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{XR_TYPE_SYSTEM_PROPERTIES,
                                    &geospatialSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!geospatialSystemProperties.supportsGeospatial) {
  return;
}

// Check VPS Availability.
XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCheckVpsAvailabilityAsyncANDROID(session, lat, lng, &future));

XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
pollInfo.future = future;
pollResult.state = XR_FUTURE_STATE_PENDING_EXT;
while (pollResult.state == XR_FUTURE_STATE_PENDING_EXT) {
  // Do in render loop/state loop.
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
}

XrVPSAvailabilityCheckCompletionANDROID vpsCompletion{
    XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID};
CHK_XR(xrCheckVpsAvailabilityCompleteANDROID(session, future, &vpsCompletion));
if (vpsCompletion.futureResult == XR_SUCCESS) {
  if (vpsCompletion.availability == XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID) {
    // Visual Positioning Service is not available. Accuracy of positions and
    // orientations from Geospatial APIs are expected to be lower at this location.
  } else {
    // Visual Positioning Service is available. Higher accuracy of position and
    // orientation is achievable at this location.
  }
}

// Create Geospatial Tracker.
XrGeospatialTrackerCreateInfoANDROID createInfo{
    XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID};
XrGeospatialTrackerANDROID geospatialTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateGeospatialTrackerANDROID(session, &createInfo, &geospatialTracker));

// In application main event loop:
while (true) {
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  if (xrPollEvent(instance, &event) != XR_SUCCESS) {
    continue;
  }
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID:
      const XrEventDataGeospatialTrackerStateChangedANDROID& eventData =
          *reinterpret_cast<XrEventDataGeospatialTrackerStateChangedANDROID*>(&event);
      switch (eventData.state) {
        case XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID:
          // Destroy existing anchors, if any.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID:
          // Start adding content.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID:
          // Handle eventData.initializationResult error result.
          break;
      }
  }
}

เรียกใช้ Geospatial Pose API

PFN_xrLocateGeospatialPoseFromPoseANDROID xrLocateGeospatialPoseFromPoseANDROID;
PFN_xrLocateGeospatialPoseANDROID xrLocateGeospatialPoseANDROID;

XrGeospatialTrackerANDROID geospatialTracker;

// Get pose from view space.
XrSpace viewSpace;
XrPosef identityPose = {{0,0,0,1},{0,0,0}};
XrGeospatialPoseFromPoseLocateInfoANDROID poseGetInfo{
    XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID};
XrGeospatialPoseResultANDROID poseResult{
    XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID};
poseGetInfo.space = viewSpace;
poseGetInfo.pose = identityPose;
poseGetInfo.time = 0;  // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseFromPoseANDROID(geospatialTracker, &poseGetInfo, &poseResult));
if ((poseResult.poseFlags & XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID) &&
    (poseResult.poseFlags & XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID)) {
  // poseResult.geospatialPose is valid.
}

// Convert Geospatial pose to an XrSpaceLocation.
XrGeospatialPoseLocateInfoANDROID poseLocateInfo{
    XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID};
XrSpaceLocation location{XR_TYPE_SPACE_LOCATION};
poseLocateInfo.space = viewSpace;
poseLocateInfo.geospatialPose = poseResult.geospatialPose;
poseLocateInfo.time = 0; // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseANDROID(geospatialTracker, &poseLocateInfo, &location));
if ((location.locationFlags & XR_SPACE_LOCATION_ORIENTATION_VALID_BIT) &&
    (location.locationFlags & XR_SPACE_LOCATION_POSITION_VALID_BIT)) {
  // location.pose is valid.
}

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

คำสั่งใหม่

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

Enum ใหม่

บิตแมสก์ใหม่

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

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • การขยาย XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • การขยาย XrResult :

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • การขยาย XrStructureType :

    • XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID
    • XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID

ปัญหา

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

  • การแก้ไขครั้งที่ 1, 2025-12-18 (Ben King)

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