XR_ANDROID_geospatial

String Nama

XR_ANDROID_geospatial

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

790

Revisi

1

Status Ratifikasi

Belum diratifikasi

Dependensi Ekstensi dan Versi

XR_EXT_future

Tanggal Terakhir Diubah

2025-12-18

Status IP

Tidak ada klaim kekayaan intelektual yang diketahui.

Kontributor

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

Ringkasan

Ekstensi ini menyediakan pelacakan Geospasial untuk Geospatial API Google, yang memberikan geolokasi dan orientasi yang akurat, serta memungkinkan aplikasi menempatkan konten sesuai dengan Bumi. Hal ini dilakukan menggunakan kombinasi pelacakan gerakan, GPS, dan sensor lainnya, serta Sistem Pemosisi Visual (VPS) Google. VPS membandingkan gambar dari kamera perangkat dengan gambar Street View untuk menentukan lokasi dan orientasi yang akurat. Geospatial API sering kali memberikan akurasi posisi sub-meter (urutan magnitudo yang lebih baik daripada GPS) dan akurasi orientasi sub-derajat.

Agar berhasil menggunakan API dalam ekstensi ini (selain memeriksa dukungan ekstensi), aplikasi harus berhasil menetapkan kredensial autentikasi melalui beberapa mekanisme, seperti XR_ANDROID_google_cloud_auth . Lihat dokumentasi ekstensi autentikasi untuk mengetahui detail selengkapnya tentang hasil penyiapan dan error.

Izin

Aplikasi Android harus memiliki izin android.permission.ACCESS_FINE_LOCATION yang tercantum dalam manifesnya untuk menggunakan ekstensi ini. Izin android.permission.ACCESS_FINE_LOCATION dianggap sebagai izin berbahaya. Aplikasi harus meminta izin saat runtime untuk menggunakan fungsi berikut:

• xrCreateGeospatialTrackerANDROID

(tingkat perlindungan: berbahaya)

Memeriksa kemampuan sistem

Struktur XrSystemGeospatialPropertiesANDROID didefinisikan sebagai:

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

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
• supportsGeospatial adalah XrBool32 , yang menunjukkan apakah sistem saat ini mendukung fitur geospasial.

Aplikasi dapat memeriksa apakah sistem mendukung fitur geospasial dengan merantai struktur XrSystemGeospatialPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties .

Jika runtime menampilkan XR_FALSE untuk supportsGeospatial , sistem tidak mendukung fitur geospasial, sehingga harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateGeospatialTrackerANDROID . Aplikasi sebaiknya menghindari penggunaan fungsi geospasial saat supportsGeospatial adalah XR_FALSE .

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum menggunakan XrSystemGeospatialPropertiesANDROID
• type harus berupa XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Membuat handle Pelacak Geospasial

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

Fungsi xrCreateGeospatialTrackerANDROID didefinisikan sebagai:

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

Deskripsi Parameter

• session adalah XrSession tempat pelacak geospasial akan aktif.
• createInfo adalah pointer ke struktur XrGeospatialTrackerCreateInfoANDROID yang menentukan parameter pelacak geospasial awal.
• geospatialTrackerOutput adalah pointer ke handle tempat XrGeospatialTrackerANDROID yang dibuat ditampilkan.

Aplikasi dapat membuat handle XrGeospatialTrackerANDROID dengan memanggil xrCreateGeospatialTrackerANDROID . Handle XrGeospatialTrackerANDROID yang ditampilkan dapat digunakan dalam panggilan API berikutnya. Jika aplikasi belum mendapatkan izin yang diperlukan, runtime harus menampilkan XR_ERROR_PERMISSION_INSUFFICIENT . Hanya satu XrGeospatialTrackerANDROID yang dapat ada pada satu waktu untuk XrSession tertentu. Aplikasi harus memastikan bahwa semua objek XrGeospatialTrackerANDROID sebelumnya telah dihancurkan sebelum memanggil fungsi ini lagi, jika tidak, runtime harus menampilkan XR_ERROR_LIMIT_REACHED . Jika pelacak berhasil dibuat, pelacak akan memasuki status XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , dan aplikasi harus menunggu hingga status berubah menjadi XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID sebelum menggunakan pelacak. Lihat XrEventDataGeospatialTrackerStateChangedANDROID . Jika aplikasi meneruskan XrGeospatialTrackerANDROID yang tidak dalam status XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID ke fungsi yang memerlukannya, runtime harus menampilkan XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

Handle XrGeospatialTrackerANDROID harus akhirnya dikosongkan melalui fungsi xrDestroyGeospatialTrackerANDROID.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum memanggil xrCreateGeospatialTrackerANDROID
• session harus berupa handle XrSession yang valid
• createInfo harus berupa pointer ke struktur XrGeospatialTrackerCreateInfoANDROID yang valid
• geospatialTrackerOutput harus berupa pointer ke handle XrGeospatialTrackerANDROID

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• 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

Struktur XrGeospatialTrackerCreateInfoANDROID didefinisikan sebagai:

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

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum menggunakan XrGeospatialTrackerCreateInfoANDROID
• type harus berupa XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur . Lihat juga: XrGeospatialTrackerAnchorTrackingInfoANDROID

Fungsi xrDestroyGeospatialTrackerANDROID didefinisikan sebagai:

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

Deskripsi Parameter

• geospatialTracker adalah XrGeospatialTrackerANDROID yang akan dihancurkan.

Aplikasi dapat menggunakan fungsi xrDestroyGeospatialTrackerANDROID untuk merilis pelacak geospasial dan resource yang mendasarinya.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum memanggil xrDestroyGeospatialTrackerANDROID
• geospatialTracker harus berupa handle XrGeospatialTrackerANDROID yang valid

Keamanan Thread

• Akses ke geospatialTracker , dan handle turunan apa pun, harus disinkronkan secara eksternal

Kode Status

Berhasil

• XR_SUCCESS

Kegagalan

• XR_ERROR_CALL_ORDER_INVALID
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

Status Pelacak Geospasial

Enumerasi XrGeospatialTrackerStateANDROID didefinisikan sebagai:

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;

Enumerasi XrGeospatialTrackerStateANDROID mengidentifikasi berbagai status pelacak geospasial.

Enumeran memiliki nilai berikut:

Deskripsi Enum

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Pelacak Geospasial tidak berjalan.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Pelacak Geospasial berjalan dan dapat digunakan.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Pelacak Geospasial gagal diinisialisasi, dan tidak akan pernah dapat digunakan.

Struktur XrEventDataGeospatialTrackerStateChangedANDROID didefinisikan sebagai:

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

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
• geospatialTracker adalah XrGeospatialTrackerANDROID yang statusnya telah berubah.
• state adalah XrGeospatialTrackerStateANDROID baru.
• initializationResult adalah hasil error jika state adalah XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , jika tidak, XR_SUCCESS .
• time adalah XrTime saat perubahan status terjadi.

Struktur XrEventDataGeospatialTrackerStateChangedANDROID dikirim saat status pelacak geospasial berubah. Jika aplikasi memiliki XrGeospatialTrackerANDROID yang valid, aplikasi harus melakukan polling untuk peristiwa ini. Peristiwa pertama yang diterima untuk pelacak akan memiliki state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . Setelah jangka waktu yang ditentukan runtime, status harus berubah menjadi XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID atau XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID . Transisi ini akan memerlukan waktu yang bervariasi. Jika state berubah menjadi XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , peristiwa ini harus menjadi peristiwa terakhir yang diterima untuk pelacak ini, dan kolom initializationResult akan menyimpan kode error. Mungkin perlu waktu beberapa detik hingga error terjadi. Dalam hal ini, aplikasi harus menghancurkan pelacak. Jika state berubah menjadi XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , semua anchor geospasial yang dibuat sebelumnya harus berhenti melacak secara permanen dan harus dihancurkan oleh aplikasi. Status dapat berubah bolak-balik antara XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID dan XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID berkali-kali secara acak.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum menggunakan XrEventDataGeospatialTrackerStateChangedANDROID
• type harus berupa XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Pose Geospasial

Struktur XrGeospatialPoseANDROID didefinisikan sebagai:

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

Deskripsi Anggota

• eastUpSouthOrientation adalah XrQuaternionf yang menentukan orientasi sehubungan dengan sistem koordinat dengan +X=Timur, +Y=Atas, dan +Z=Selatan.
• latitude adalah lintang dalam derajat, antara -90 dan +90.
• longitude adalah bujur dalam derajat, antara -180 dan +180.
• altitude adalah ketinggian dalam meter di atas elipsoid WGS84.

Struktur XrGeospatialPoseANDROID merepresentasikan posisi dan orientasi yang relatif terhadap Bumi menggunakan elipsoid WGS84.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum menggunakan XrGeospatialPoseANDROID
• latitude harus berupa nilai double yang valid
• longitude harus berupa nilai double yang valid
• altitude harus berupa nilai double yang valid

Enumerasi XrGeospatialPoseFlagBitsANDROID didefinisikan sebagai:

// 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;

Enumerasi XrGeospatialPoseFlagBitsANDROID menentukan flag untuk pose geospasial.

Bit flag memiliki arti berikut:

Deskripsi Flag

• XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID — Menunjukkan bahwa anggota orientasi berisi data yang valid
• XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID — Menunjukkan bahwa anggota posisi berisi data yang valid

Jenis XrGeospatialPoseFlagsANDROID adalah bitmask dari XrGeospatialPoseFlagBitsANDROID .

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

Mengonversi XrPosef menjadi Pose Geospasial

Fungsi xrLocateGeospatialPoseFromPoseANDROID didefinisikan sebagai:

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

Deskripsi Parameter

• geospatialTracker adalah XrGeospatialTrackerANDROID yang akan digunakan untuk konversi.
• locateInfo adalah pointer ke XrGeospatialPoseFromPoseLocateInfoANDROID yang berisi parameter kueri.
• geospatialPoseResult adalah pointer ke XrGeospatialPoseResultANDROID yang menerima hasil.

Fungsi xrLocateGeospatialPoseFromPoseANDROID mengonversi pose di XrGeospatialPoseFromPoseLocateInfoANDROID :: space menjadi pose geospasial. Jika status geospatialTracker bukan XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , runtime harus menampilkan XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Jika fungsi menampilkan XR_SUCCESS , kolom XrGeospatialPoseResultANDROID :: poseFlags dari geospatialPoseResult akan menentukan kolom output mana yang valid. Jika XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID tidak ditetapkan di XrGeospatialPoseResultANDROID :: poseFlags , aplikasi tidak boleh membaca kolom XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy atau XrGeospatialPoseResultANDROID :: verticalAccuracy di XrGeospatialPoseResultANDROID . Jika XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID tidak ditetapkan di XrGeospatialPoseResultANDROID :: poseFlags , aplikasi tidak boleh membaca XrGeospatialPoseANDROID :: eastUpSouthOrientation atau XrGeospatialPoseResultANDROID :: orientationYawAccuracy . Jika XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID tidak ditetapkan, XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID juga tidak boleh ditetapkan.

Jika akurasinya lebih rendah dari yang diharapkan, hal ini mungkin mengindikasikan bahwa perangkat tidak menggunakan pelokalan VPS. Aplikasi dapat menginstruksikan pengguna untuk mengarahkan perangkat mereka ke papan tanda dan bangunan untuk meningkatkan pelokalan.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum memanggil xrLocateGeospatialPoseFromPoseANDROID
• geospatialTracker harus berupa handle XrGeospatialTrackerANDROID yang valid
• locateInfo harus berupa pointer ke struktur XrGeospatialPoseFromPoseLocateInfoANDROID yang valid
• geospatialPoseResult harus berupa pointer ke struktur XrGeospatialPoseResultANDROID

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• 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

Struktur XrGeospatialPoseFromPoseLocateInfoANDROID didefinisikan sebagai:

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

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
• space adalah XrSpace tempat pose ditentukan.
• time adalah XrTime yang akan digunakan untuk mengevaluasi pose .
• pose adalah XrPosef di space yang akan dikonversi menjadi pose geospasial.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum menggunakan XrGeospatialPoseFromPoseLocateInfoANDROID
• type harus berupa XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• space harus berupa nama sebutan channel XrSpace yang valid

Struktur XrGeospatialPoseResultANDROID didefinisikan sebagai:

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

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
• poseFlags adalah bitmask XrGeospatialPoseFlagsANDROID yang menunjukkan validitas komponen pose.
• geospatialPose adalah XrGeospatialPoseANDROID yang dihasilkan.
• horizontalAccuracy adalah estimasi akurasi horizontal posisi pose Geospasial, yang didefinisikan sebagai radius dalam meter dari lingkaran tingkat keyakinan 68% di sekitar lintang dan bujur yang diberikan.
• verticalAccuracy adalah estimasi akurasi vertikal posisi pose Geospasial, yang didefinisikan sebagai jarak dalam meter dari tingkat keyakinan 68% di sekitar ketinggian yang diberikan. Dengan kata lain, ada peluang 68% bahwa ketinggian sebenarnya berada dalam rentang [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ].
• orientationYawAccuracy adalah estimasi akurasi yaw orientasi pose Geospasial, yang didefinisikan sebagai radius dalam derajat tingkat keyakinan 68% di sekitar orientasi yang diberikan.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum menggunakan XrGeospatialPoseResultANDROID
• type harus berupa XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Mengonversi Pose Geospasial menjadi XrPosef

Fungsi xrLocateGeospatialPoseANDROID didefinisikan sebagai:

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

Deskripsi Parameter

• geospatialTracker adalah XrGeospatialTrackerANDROID yang akan digunakan untuk konversi.
• locateInfo adalah pointer ke XrGeospatialPoseLocateInfoANDROID yang berisi parameter kueri.
• location adalah pointer ke XrSpaceLocation yang menerima pose yang dihasilkan.

Fungsi xrLocateGeospatialPoseANDROID mengonversi pose geospasial menjadi XrSpaceLocation . Jika XrGeospatialTrackerANDROID tidak berjalan, runtime harus menampilkan XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Jika fungsi menampilkan XR_SUCCESS , kolom XrSpaceLocation :: locationFlags dari location akan menentukan kolom output mana yang valid.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum memanggil xrLocateGeospatialPoseANDROID
• geospatialTracker harus berupa handle XrGeospatialTrackerANDROID yang valid
• locateInfo harus berupa pointer ke struktur XrGeospatialPoseLocateInfoANDROID yang valid
• location harus berupa pointer ke struktur XrSpaceLocation

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• 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

Struktur XrGeospatialPoseLocateInfoANDROID didefinisikan sebagai:

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

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
• space adalah XrSpace tempat pose yang dihasilkan akan direpresentasikan.
• time adalah XrTime untuk menemukan pose.
• geospatialPose adalah XrGeospatialPoseANDROID yang akan dikonversi.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum menggunakan XrGeospatialPoseLocateInfoANDROID
• type harus berupa XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• space harus berupa nama sebutan channel XrSpace yang valid
• geospatialPose harus berupa struktur XrGeospatialPoseANDROID yang valid

Ketersediaan VPS

Enumerasi XrVPSAvailabilityANDROID didefinisikan sebagai:

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

Enumerasi XrVPSAvailabilityANDROID menunjukkan ketersediaan VPS.

Enumeran memiliki nilai berikut:

Deskripsi Enum

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

VPS tidak tersedia di dekat lokasi yang ditentukan.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

VPS tersedia di dekat lokasi yang diberikan.

Fungsi xrCheckVpsAvailabilityAsyncANDROID didefinisikan sebagai:

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

Deskripsi Parameter

• session adalah XrSession yang akan digunakan untuk pemeriksaan.
• latitude adalah lintang dalam derajat.
• longitude adalah bujur dalam derajat.
• future adalah pointer ke XrFutureEXT yang akan menyimpan hasil operasi asinkron.

Ketersediaan Visual Positioning Service (VPS) menunjukkan apakah VPS dapat digunakan untuk meningkatkan akurasi geospasial di lokasi tertentu.

Fungsi xrCheckVpsAvailabilityAsyncANDROID memulai pemeriksaan asinkron untuk ketersediaan VPS di lokasi tertentu. Aplikasi tidak memerlukan XrGeospatialTrackerANDROID untuk memanggil fungsi ini, dan dapat menggunakan hasil operasi ini untuk memutuskan apakah akan membuatnya. Jika aplikasi belum mendapatkan izin yang diperlukan, runtime harus menampilkan XR_ERROR_PERMISSION_INSUFFICIENT .

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum memanggil xrCheckVpsAvailabilityAsyncANDROID
• session harus berupa handle XrSession yang valid
• latitude harus berupa nilai double yang valid
• longitude harus berupa nilai double yang valid
• future harus berupa pointer ke nilai XrFutureEXT

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• 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

Fungsi xrCheckVpsAvailabilityCompleteANDROID didefinisikan sebagai:

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

Deskripsi Parameter

• session adalah XrSession yang digunakan untuk pemeriksaan.
• future adalah XrFutureEXT yang ditampilkan oleh xrCheckVpsAvailabilityAsyncANDROID .
• completion adalah pointer ke XrVPSAvailabilityCheckCompletionANDROID yang menerima hasilnya.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum memanggil xrCheckVpsAvailabilityCompleteANDROID
• session harus berupa handle XrSession yang valid
• completion harus berupa pointer ke struktur XrVPSAvailabilityCheckCompletionANDROID

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• 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

Struktur XrVPSAvailabilityCheckCompletionANDROID didefinisikan sebagai:

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

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
• futureResult adalah XrResult dari operasi pemeriksaan. Jika futureResult adalah XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , struktur dalam rantai next mungkin memberikan informasi selengkapnya tentang kegagalan tersebut.
• availability adalah XrVPSAvailabilityANDROID yang dihasilkan. Aplikasi tidak boleh membaca kolom ini kecuali jika futureResult adalah XR_SUCCESS .

Kode Status Mendatang

Nilai futureResult:

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_geospatial harus diaktifkan sebelum menggunakan XrVPSAvailabilityCheckCompletionANDROID
• type harus berupa XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• futureResult harus berupa nilai XrResult yang valid
• availability harus berupa nilai XrVPSAvailabilityANDROID yang valid

Contoh

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

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

Jenis Objek Baru

• XrGeospatialTrackerANDROID

Perintah Baru

• xrCheckVpsAvailabilityAsyncANDROID
• xrCheckVpsAvailabilityCompleteANDROID
• xrCreateGeospatialTrackerANDROID
• xrDestroyGeospatialTrackerANDROID
• xrLocateGeospatialPoseANDROID
• xrLocateGeospatialPoseFromPoseANDROID

Struktur Baru

• XrEventDataGeospatialTrackerStateChangedANDROID
• XrGeospatialPoseANDROID
• XrGeospatialPoseFromPoseLocateInfoANDROID
• XrGeospatialPoseLocateInfoANDROID
• XrGeospatialPoseResultANDROID
• XrGeospatialTrackerCreateInfoANDROID
• XrVPSAvailabilityCheckCompletionANDROID

• Memperluas XrSystemProperties :

  • XrSystemGeospatialPropertiesANDROID

Enum Baru

• XrGeospatialPoseFlagBitsANDROID
• XrGeospatialTrackerStateANDROID
• XrVPSAvailabilityANDROID

Bitmask Baru

• XrGeospatialPoseFlagsANDROID

Konstanta Enum Baru

• XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
• XR_ANDROID_geospatial_SPEC_VERSION

• Memperluas XrObjectType :

  • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

• Memperluas XrResult :

  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

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

Masalah

Histori Versi

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

  • Deskripsi ekstensi awal.