XR_ANDROID_geospatial

String Nama

XR_ANDROID_geospatial

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

790

Revisi

1

Status Ratifikasi

Tidak diratifikasi

Dependensi Ekstensi dan Versi

XR_EXT_future

Tanggal Terakhir Diubah

2025-12-18

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

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

Ringkasan

Ekstensi ini menyediakan pelacakan Geospatial untuk Geospatial API Google, yang memberikan geo-lokasi dan orientasi yang presisi, serta memungkinkan aplikasi menempatkan konten sehubungan dengan Bumi. Fitur ini melakukannya menggunakan kombinasi pelacakan gerakan, GPS, dan sensor lainnya, serta Sistem Pemosisian 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 (lebih baik daripada GPS) dan akurasi orientasi sub-derajat.

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

Izin

Aplikasi Android harus mencantumkan izin android.permission.ACCESS_FINE_LOCATION 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 ini:

(tingkat perlindungan: berbahaya)

Memeriksa kemampuan sistem

Struktur XrSystemGeospatialPropertiesANDROID ditentukan 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 merangkai 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 harus menghindari penggunaan fungsi geospasial saat supportsGeospatial adalah XR_FALSE .

Penggunaan yang Valid (Implisit)

Membuat nama sebutan Geospatial Tracker

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

Fungsi xrCreateGeospatialTrackerANDROID ditentukan sebagai:

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

Deskripsi Parameter

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 dalam 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 berhasil dibuat, pelacak akan memasuki status XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID pada awalnya , 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 dibebaskan pada akhirnya melalui fungsi xrDestroyGeospatialTrackerANDROID.

Penggunaan yang Valid (Implisit)

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 ditentukan 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)

Fungsi xrDestroyGeospatialTrackerANDROID ditentukan sebagai:

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

Deskripsi Parameter

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

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke geospatialTracker , dan semua handle turunannya, harus disinkronkan secara eksternal

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Status Pelacak Geospasial

Enumerasi XrGeospatialTrackerStateANDROID ditentukan 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 Geospatial tidak berjalan.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Pelacak Geospatial sedang berjalan dan dapat digunakan.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Geospatial Tracker gagal diinisialisasi, dan tidak akan pernah dapat digunakan.

Struktur XrEventDataGeospatialTrackerStateChangedANDROID ditentukan 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 , atau 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 saat 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 tidak ditentukan. Jika state berubah menjadi XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , harus menjadi peristiwa terakhir yang diterima untuk pelacak ini, dan kolom initializationResult akan menyimpan kode error. Mungkin perlu waktu beberapa detik hingga terjadi error. 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)

Pose Geospasial

Struktur XrGeospatialPoseANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • eastUpSouthOrientation adalah XrQuaternionf yang menentukan orientasi terhadap sistem koordinat dengan +X=Timur, +Y=Atas, dan +Z=Selatan.
  • latitude adalah garis 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 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 ditentukan 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 tanda 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 ke Pose Geospasial

Fungsi xrLocateGeospatialPoseFromPoseANDROID ditentukan sebagai:

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

Deskripsi Parameter

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 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 menunjukkan bahwa perangkat tidak menggunakan pelokalan VPS. Aplikasi dapat menginstruksikan pengguna untuk mengarahkan perangkat mereka ke papan tanda dan bangunan untuk meningkatkan kualitas pelokalan.

Penggunaan yang Valid (Implisit)

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 ditentukan 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)

Struktur XrGeospatialPoseResultANDROID ditentukan 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 postur.
  • geospatialPose adalah XrGeospatialPoseANDROID yang dihasilkan .
  • horizontalAccuracy adalah perkiraan akurasi horizontal posisi Pose geospasial, yang ditentukan sebagai radius dalam meter dari lingkaran tingkat keyakinan 68% di sekitar lintang dan bujur yang diberikan.
  • verticalAccuracy adalah perkiraan akurasi vertikal posisi postur Geospasial, yang ditentukan sebagai jarak dalam meter pada tingkat keyakinan 68% di sekitar ketinggian tertentu. Dengan kata lain, ada peluang 68% bahwa ketinggian sebenarnya berada dalam rentang [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ].
  • orientationYawAccuracy adalah perkiraan akurasi yaw orientasi Pose geospasial, yang ditentukan sebagai radius dalam derajat tingkat keyakinan 68% di sekitar orientasi yang diberikan.

Penggunaan yang Valid (Implisit)

Mengonversi Pose Geospasial menjadi XrPosef

Fungsi xrLocateGeospatialPoseANDROID ditentukan sebagai:

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

Deskripsi Parameter

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)

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

Struktur XrGeospatialPoseLocateInfoANDROID ditentukan 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 tempat untuk menemukan pose.
  • geospatialPose adalah XrGeospatialPoseANDROID yang akan dikonversi.

Penggunaan yang Valid (Implisit)

Ketersediaan VPS

Enumerasi XrVPSAvailabilityANDROID ditentukan 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 ditentukan 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 atau tidak. 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 ditentukan sebagai:

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

Deskripsi Parameter

Penggunaan yang Valid (Implisit)

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 ditentukan 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 dapat memberikan informasi selengkapnya tentang kegagalan tersebut.
  • availability adalah XrVPSAvailabilityANDROID yang dihasilkan . Aplikasi tidak boleh membaca kolom ini kecuali futureResult adalah XR_SUCCESS .

Kode Pengembalian pada Masa 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)

Contoh

Menyiapkan Pelacak Geospasial

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

Perintah Baru

Struktur Baru

Enum Baru

Bitmask Baru

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.