Android XR for OpenXR | Android Developers

Android XR SDK telah mencapai Pratinjau Developer 3, dan kami ingin mendengar masukan Anda. Coba fitur-fitur yang ada, dan buka halaman dukungan kami untuk menghubungi kami.

XR_ANDROID_geospatial_anchor

String Nama

XR_ANDROID_geospatial_anchor

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

798

Revisi

Status Ratifikasi

Tidak 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

2025-10-30

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 Geospatial Anchors dan Surface Anchors yang dibuat berdasarkan ekstensi Geospatial dasar. Geospatial Anchors adalah anchor yang diposisikan di ruang relatif terhadap Bumi pada lintang, bujur, dan ketinggian tertentu. Surface Anchors adalah anchor relatif terhadap Bumi yang ditempatkan pada lintang, bujur, dan ketinggian tertentu relatif terhadap permukaan seperti yang diketahui oleh Visual Positioning Service. Saat akurasi runtime dari posisinya relatif terhadap Bumi meningkat, pose Anchor akan disesuaikan.

Kemampuan Sistem untuk Geospatial Anchors

Struktur XrSystemGeospatialAnchorPropertiesANDROID ditentukan 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 geospatial anchor sistem dengan merangkai struktur XrSystemGeospatialAnchorPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties .

Jika XrSystemGeospatialPropertiesANDROID :: supportsGeospatial adalah XR_TRUE , maka 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 be XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID
next harus NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Pelacakan Bidang untuk Anchor

Struktur XrGeospatialTrackerAnchorTrackingInfoANDROID ditentukan 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 penentuan posisi anchor yang terkunci di permukaan.

Pelacakan bidang dapat diaktifkan untuk meningkatkan penentuan posisi anchor yang terkunci di 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 be XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
next harus NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Geospatial Anchors

Fungsi xrCreateGeospatialAnchorANDROID ditentukan 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 Retur

Berhasil

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Gagal

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

Struktur XrGeospatialAnchorCreateInfoANDROID ditentukan 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 XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
next harus 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

Surface Anchors

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

Enumerasi XrSurfaceAnchorTypeANDROID ditentukan 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 permukaan yang relatif terhadap anchor.

Enumeran memiliki nilai berikut:

Deskripsi Enum

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Jenis anchor yang ditempatkan relatif terhadap tanah.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

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

Fungsi xrCreateSurfaceAnchorAsyncANDROID ditentukan 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 permukaan. Tidak seperti geospatial anchors 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 dapat gagal secara asinkron dengan hasil XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID jika tidak ada data permukaan untuk lokasi yang diberikan. 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 Retur

Berhasil

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Gagal

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

Struktur XrSurfaceAnchorCreateInfoANDROID ditentukan 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 terkait 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 relatif terhadap permukaan yang ditentukan oleh surfaceAnchorType .

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_geospatial_anchor harus diaktifkan sebelum menggunakan XrSurfaceAnchorCreateInfoANDROID
type harus XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
next harus 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 ditentukan 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 Retur

Berhasil

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Gagal

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 permukaan 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 dapat memberikan informasi selengkapnya tentang kegagalan.
anchorEntityId adalah XrSpatialEntityIdEXT dari anchor yang dibuat, atau XR_NULL_SPATIAL_ENTITY_ID_EXT jika futureResult bukan XR_SUCCESS .

Kode Retur Masa Depan

Nilai futureResult:

Berhasil

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Gagal

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 XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
next harus 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

Issues

Histori Versi

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