XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

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

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

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

790

การแก้ไข

1

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

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

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

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 มักจะให้ความแม่นยำของตำแหน่งในระดับต่ำกว่าเมตร (ดีกว่า GPS หลายเท่า) และความแม่นยำในการวางแนวในระดับต่ำกว่าองศา

หากต้องการใช้ 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 หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน 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 สามารถมีได้ครั้งละ 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 หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง

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

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

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

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

แอปพลิเคชันสามารถใช้ฟังก์ชัน xrDestroyGeospatialTrackerANDROID เพื่อปล่อยเครื่องมือติดตามเชิงพื้นที่และทรัพยากรที่เกี่ยวข้องได้

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

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

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

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

สำเร็จ

  • XR_SUCCESS

ความล้มเหลว

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

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

การแจงนับ 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

เครื่องมือติดตามเชิงพื้นที่ไม่ได้ทำงานอยู่

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

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

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

เริ่มต้นใช้งานเครื่องมือติดตามเชิงพื้นที่ไม่สำเร็จ และจะใช้งานไม่ได้เลย

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

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

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

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

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

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

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

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

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

  • geospatialTracker คือ XrGeospatialTrackerANDROID ที่จะใช้สำหรับการแปลง
  • locateInfo เป็นตัวชี้ไปยัง XrGeospatialPoseLocateInfoANDROID ที่มีพารามิเตอร์การค้นหา
  • location คือตัวชี้ไปยัง 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_POSE_INVALID
  • 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 หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • 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 หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • 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

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

ตัวอย่าง

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

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

ปัญหา

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

  • Revision 1, 2025-12-18 (Ben King)

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