Android XR for OpenXR | Android Developers

Android Dev Summit kembali hadir dengan jalur khusus untuk Android XR. Ikuti, coba, dan kirimkan masukan Anda kepada kami.

Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

XR_ANDROID_geospatial_anchor

String Nama

XR_ANDROID_geospatial_anchor

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

798

Revisi

Status Ratifikasi

Belum diratifikasi

Dependensi Ekstensi dan Versi

XR_ANDROID_geospatial
dan
XR_EXT_future
dan
XR_EXT_spatial_entity
dan
XR_EXT_spatial_anchor

Tanggal Terakhir Diubah

30-10-2025

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 Anchor Geospasial dan Anchor Permukaan yang dibuat berdasarkan ekstensi Geospasial dasar. Anchor Geospasial adalah anchor yang diposisikan dalam ruang relatif terhadap Bumi pada lintang, bujur, dan ketinggian tertentu. Anchor Permukaan adalah anchor yang terkait dengan Bumi yang ditempatkan pada lintang, bujur, dan ketinggian tertentu yang terkait dengan permukaan seperti yang diketahui oleh Layanan Pemosisian Visual. Seiring meningkatnya akurasi posisi runtime relatif terhadap Bumi, pose Anchor akan menyesuaikan.

Kemampuan Sistem untuk Anchor Geospasial

Struktur XrSystemGeospatialAnchorPropertiesANDROID didefinisikan sebagai:

typedef struct XrSystemGeospatialAnchorPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSurfaceAnchorCount;
} XrSystemGeospatialAnchorPropertiesANDROID;

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.
maxSurfaceAnchorCount adalah uint32_t yang menunjukkan jumlah maksimum anchor permukaan yang dapat dibuat.

Aplikasi dapat memeriksa kemampuan anchor geospasial sistem dengan merantai struktur XrSystemGeospatialAnchorPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties .

Jika XrSystemGeospatialPropertiesANDROID :: supportsGeospatial adalah XR_TRUE , maxSurfaceAnchorCount menunjukkan jumlah maksimum anchor permukaan yang didukung runtime. Dalam hal ini, batas harus lebih besar dari 0.

Jika XrSystemGeospatialPropertiesANDROID :: supportsGeospatial bukan XR_TRUE , maka maxSurfaceAnchorCount harus 0.

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_geospatial_anchor harus diaktifkan sebelum menggunakan XrSystemGeospatialAnchorPropertiesANDROID
type harus berupa XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID
next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Pelacakan Bidang untuk Anchor

Struktur XrGeospatialTrackerAnchorTrackingInfoANDROID didefinisikan sebagai:

typedef struct XrGeospatialTrackerAnchorTrackingInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrBool32           shouldTrackPlanes;
} XrGeospatialTrackerAnchorTrackingInfoANDROID;

Deskripsi Anggota

type adalah XrStructureType dari struktur ini.
next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
shouldTrackPlanes adalah XrBool32 yang menunjukkan apakah pelacak geospasial akan melacak bidang untuk meningkatkan pemosisian anchor yang terkunci di permukaan.

Pelacakan bidang dapat diaktifkan untuk meningkatkan pemosisian anchor yang dikunci ke permukaan.

Jika aplikasi ingin mengaktifkan pelacakan bidang untuk meningkatkan pose anchor permukaan, aplikasi dapat merangkai struktur XrGeospatialTrackerAnchorTrackingInfoANDROID ke XrGeospatialTrackerCreateInfoANDROID saat memanggil xrCreateGeospatialTrackerANDROID .

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_geospatial_anchor harus diaktifkan sebelum menggunakan XrGeospatialTrackerAnchorTrackingInfoANDROID
type harus berupa XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Anchor Geospasial

Fungsi xrCreateGeospatialAnchorANDROID didefinisikan sebagai:

XrResult xrCreateGeospatialAnchorANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrGeospatialAnchorCreateInfoANDROID*  createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId);

Deskripsi Parameter

spatialContext adalah XrSpatialContextEXT untuk membuat anchor. Konteks harus dikonfigurasi untuk XR_SPATIAL_CAPABILITY_ANCHOR_EXT, jika tidak, runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .
createInfo adalah pointer ke XrGeospatialAnchorCreateInfoANDROID yang berisi parameter pembuatan anchor.
anchorEntityId adalah pointer ke XrSpatialEntityIdEXT tempat ID entity anchor ditampilkan.

Jika XrGeospatialTrackerANDROID yang ditentukan dalam XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker tidak dalam status XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, runtime harus menampilkan XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_geospatial_anchor harus diaktifkan sebelum memanggil xrCreateGeospatialAnchorANDROID
spatialContext harus berupa handle XrSpatialContextEXT yang valid
createInfo harus berupa pointer ke struktur XrGeospatialAnchorCreateInfoANDROID yang valid
anchorEntityId harus berupa pointer ke nilai XrSpatialEntityIdEXT

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_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_POSE_INVALID
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

Struktur XrGeospatialAnchorCreateInfoANDROID didefinisikan sebagai:

typedef struct XrGeospatialAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrGeospatialPoseANDROID       geospatialPose;
} XrGeospatialAnchorCreateInfoANDROID;

Deskripsi Anggota

type adalah XrStructureType dari struktur ini.
next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
geospatialTracker adalah XrGeospatialTrackerANDROID yang akan digunakan untuk membuat anchor.
geospatialPose adalah pointer ke XrGeospatialPoseANDROID yang menentukan lokasi dan orientasi anchor.

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_geospatial_anchor harus diaktifkan sebelum menggunakan XrGeospatialAnchorCreateInfoANDROID
type harus berupa XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
geospatialTracker harus berupa handle XrGeospatialTrackerANDROID yang valid
geospatialPose harus berupa struktur XrGeospatialPoseANDROID yang valid

Anchor Permukaan

Anchor permukaan adalah anchor yang ditempatkan relatif terhadap permukaan, seperti medan atau atap.

Enumerasi XrSurfaceAnchorTypeANDROID didefinisikan sebagai:

typedef enum XrSurfaceAnchorTypeANDROID {
    XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID = 1,
    XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID = 2,
    XR_SURFACE_ANCHOR_TYPE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSurfaceAnchorTypeANDROID;

Enumerasi XrSurfaceAnchorTypeANDROID menentukan jenis platform yang terkait dengan anchor.

Enumeran memiliki nilai berikut:

Deskripsi Enum

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Jenis anchor yang ditempatkan relatif terhadap permukaan tanah.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Jenis anchor yang ditempatkan relatif terhadap atap, atau tanah jika tidak ada bangunan.

Fungsi xrCreateSurfaceAnchorAsyncANDROID didefinisikan sebagai:

XrResult xrCreateSurfaceAnchorAsyncANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSurfaceAnchorCreateInfoANDROID*     createInfo,
    XrFutureEXT*                                future);

Deskripsi Parameter

spatialContext adalah XrSpatialContextEXT untuk membuat anchor.
createInfo adalah pointer ke XrSurfaceAnchorCreateInfoANDROID yang berisi parameter pembuatan anchor.
future adalah pointer ke XrFutureEXT yang akan menyimpan hasil operasi asinkron.

Fungsi xrCreateSurfaceAnchorAsyncANDROID memulai operasi asinkron untuk membuat anchor platform. Tidak seperti anchor geospasial standar, runtime dapat mengambil data medan untuk menentukan ketinggian yang benar. Runtime harus menampilkan XR_ERROR_LIMIT_REACHED jika aplikasi mencoba membuat lebih dari XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount anchor permukaan sekaligus. Jika XrGeospatialTrackerANDROID yang ditentukan dalam XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker tidak dalam status XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, runtime harus menampilkan XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Operasi mungkin gagal secara asinkron dengan hasil XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID jika tidak ada data permukaan untuk lokasi yang ditentukan. Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika XR_SPATIAL_CAPABILITY_ANCHOR_EXT tidak dikonfigurasi untuk spatialContext .

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_geospatial_anchor harus diaktifkan sebelum memanggil xrCreateSurfaceAnchorAsyncANDROID
spatialContext harus berupa handle XrSpatialContextEXT yang valid
createInfo harus berupa pointer ke struktur XrSurfaceAnchorCreateInfoANDROID 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_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_POSE_INVALID
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

Struktur XrSurfaceAnchorCreateInfoANDROID didefinisikan sebagai:

typedef struct XrSurfaceAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrSurfaceAnchorTypeANDROID    surfaceAnchorType;
    XrQuaternionf                 eastUpSouthOrientation;
    double                        latitude;
    double                        longitude;
    double                        altitudeRelativeToSurface;
} XrSurfaceAnchorCreateInfoANDROID;

Deskripsi Anggota

type adalah XrStructureType dari struktur ini.
next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
geospatialTracker adalah XrGeospatialTrackerANDROID yang akan digunakan.
surfaceAnchorType adalah XrSurfaceAnchorTypeANDROID untuk anchor.
eastUpSouthOrientation adalah orientasi sehubungan dengan sistem koordinat dengan +X=Timur, +Y=Atas, dan +Z=Selatan.
latitude adalah lintang dalam derajat, antara -89,9 dan +89,9.
longitude adalah bujur dalam derajat, antara -180 dan +180.
altitudeRelativeToSurface adalah ketinggian dalam meter yang relatif terhadap permukaan yang ditentukan oleh surfaceAnchorType .

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_geospatial_anchor harus diaktifkan sebelum menggunakan XrSurfaceAnchorCreateInfoANDROID
type harus berupa XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
geospatialTracker harus berupa handle XrGeospatialTrackerANDROID yang valid
surfaceAnchorType harus berupa nilai XrSurfaceAnchorTypeANDROID yang valid
latitude harus berupa nilai double yang valid
longitude harus berupa nilai double yang valid
altitudeRelativeToSurface harus berupa nilai double yang valid

Fungsi xrCreateSurfaceAnchorCompleteANDROID didefinisikan sebagai:

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     completion);

Deskripsi Parameter

spatialContext adalah XrSpatialContextEXT yang digunakan untuk pembuatan.
future adalah XrFutureEXT yang ditampilkan oleh xrCreateSurfaceAnchorAsyncANDROID .
completion adalah pointer ke XrSurfaceAnchorCreateCompletionANDROID yang menerima hasilnya.

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_geospatial_anchor harus diaktifkan sebelum memanggil xrCreateSurfaceAnchorCompleteANDROID
spatialContext harus berupa handle XrSpatialContextEXT yang valid
completion harus berupa pointer ke struktur XrSurfaceAnchorCreateCompletionANDROID

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_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

Struktur XrSurfaceAnchorCreateCompletionANDROID menyimpan hasil pembuatan anchor platform asinkron.

typedef struct XrSurfaceAnchorCreateCompletionANDROID {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSurfaceAnchorCreateCompletionANDROID;

Deskripsi Anggota

type adalah XrStructureType dari struktur ini.
next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
futureResult adalah XrResult dari operasi pembuatan. Jika futureResult adalah XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , struktur dalam rantai next mungkin memberikan informasi selengkapnya tentang kegagalan tersebut.
anchorEntityId adalah XrSpatialEntityIdEXT dari anchor yang dibuat, atau XR_NULL_SPATIAL_ENTITY_ID_EXT jika futureResult bukan 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_OUT_OF_MEMORY
XR_ERROR_LIMIT_REACHED
XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_geospatial_anchor harus diaktifkan sebelum menggunakan XrSurfaceAnchorCreateCompletionANDROID
type harus berupa XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
futureResult harus berupa nilai XrResult yang valid

Contoh

Membuat Anchor Medan

PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
PFN_xrCreateSurfaceAnchorAsyncANDROID xrCreateSurfaceAnchorAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCreateSurfaceAnchorCompleteANDROID xrCreateSurfaceAnchorCompleteANDROID;
XrInstance instance;
XrSession session;
XrGeospatialTrackerANDROID geospatialTracker;

// Create a spatial context
XrSpatialContextEXT spatialContext{};
{
  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  XrSpatialCapabilityConfigurationAnchorEXT
       anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  // ... wait until future is ready ...

  XrCreateSpatialContextCompletionEXT contextCompletion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &contextCompletion));
  if (contextCompletion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = contextCompletion.spatialContext;
}

XrSurfaceAnchorCreateInfoANDROID anchorCreateInfo{
    XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID};
anchorCreateInfo.surfaceAnchorType = XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID;
anchorCreateInfo.eastUpSouthOrientation = {0, 0, 0, 1};
anchorCreateInfo.latitude = 37.7749;
anchorCreateInfo.longitude = -122.4194;
anchorCreateInfo.altitudeRelativeToSurface = 0;
anchorCreateInfo.geospatialTracker = geospatialTracker;
XrFutureEXT anchorFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSurfaceAnchorAsyncANDROID(spatialContext, &anchorCreateInfo, &anchorFuture));

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

XrSurfaceAnchorCreateCompletionANDROID anchorCompletion{
    XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID};
CHK_XR(xrCreateSurfaceAnchorCompleteANDROID(spatialContext, anchorFuture, &anchorCompletion));
if (anchorCompletion.futureResult == XR_SUCCESS) {
  // Use completion.anchorEntityId.
  XrSpatialEntityIdEXT anchorId = anchorCompletion.anchorEntityId;

  // Query in UpdateSnapshot.
}

Struktur Baru

XrGeospatialAnchorCreateInfoANDROID
XrSurfaceAnchorCreateCompletionANDROID
XrSurfaceAnchorCreateInfoANDROID
Memperluas XrGeospatialTrackerCreateInfoANDROID :
- XrGeospatialTrackerAnchorTrackingInfoANDROID
Memperluas XrSystemProperties :
- XrSystemGeospatialAnchorPropertiesANDROID

Enum Baru

XrSurfaceAnchorTypeANDROID

Konstanta Enum Baru

XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
XR_ANDROID_geospatial_anchor_SPEC_VERSION
Memperluas XrResult :
- XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
Memperluas XrStructureType :
- XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
- XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
- XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
- XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
- XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID

Masalah

Histori Versi

Revisi 1, 30-10-2025 (Ben King)
- Draf awal.