XR_ANDROID_spatial_anchor_space

String Nama

XR_ANDROID_spatial_anchor_space

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

796

Revisi

1

Status Ratifikasi

Belum diratifikasi

Dependensi Ekstensi dan Versi

XR_EXT_spatial_anchor

Tanggal Terakhir Diubah

2025-09-15

Status IP

Tidak ada klaim kekayaan intelektual yang diketahui.

Kontributor

YuSheng Chang, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Ringkasan

Fungsi xrCreateSpatialAnchorEXT yang ditentukan dalam ekstensi XR_EXT_spatial_anchor memungkinkan aplikasi membuat anchor spasial dengan handle XrSpatialEntityEXT untuk merepresentasikannya. Sebaliknya, ekstensi ini membuat anchor spasial yang diwakili oleh handle XrSpace. Hal ini berguna untuk kasus saat aplikasi ingin:

  • Gunakan xrLocateSpaces untuk mendapatkan lokasi anchor.
  • Menemukan ruang lain yang terkait dengan anchor.
  • Ekspor anchor menggunakan XR_ANDROID_anchor_sharing_export .
  • Aplikasi telah menempatkan anchor dan kini hanya mementingkan lokasi anchor (untuk melampirkan konten virtual), dan tidak mementingkan komponen lain dari entitas lain yang ditemukan melalui XrSpatialContextEXT yang digunakan untuk membuat anchor, sehingga memungkinkan aplikasi menghancurkan konteks spasial.

Anchor yang dibuat dengan ekstensi ini tidak dapat dipertahankan menggunakan ekstensi XR_ANDROID_device_anchor_persistence dan aplikasi harus menggunakan XR_EXT_spatial_persistence_operations . Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrPersistAnchorANDROID jika XrPersistedAnchorSpaceInfoANDROID :: anchor dibuat menggunakan xrCreateSpatialAnchorSpaceANDROID atau xrCreateSpatialAnchorSpaceFromIdANDROID .

Membuat XrSpace untuk Anchor Spasial

Membuat anchor spasial dan ruang

Fungsi xrCreateSpatialAnchorSpaceANDROID didefinisikan sebagai:

XrResult xrCreateSpatialAnchorSpaceANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpace*                                    anchorSpace);

Deskripsi Parameter

Fungsi xrCreateSpatialAnchorSpaceANDROID membuat anchor yang menghasilkan XrSpatialEntityIdEXT dan handle XrSpace. xrCreateSpatialAnchorSpaceANDROID memiliki persyaratan validasi yang sama dengan xrCreateSpatialAnchorEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika XrSpatialContextEXT yang diteruskan ke xrCreateSpatialAnchorSpaceANDROID tidak dikonfigurasi dengan XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

Sehubungan dengan visibilitas anchor yang dibuat oleh xrCreateSpatialAnchorSpaceANDROID , paragraf terakhir spesifikasi xrCreateSpatialAnchorEXT berlaku.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_spatial_anchor_space harus diaktifkan sebelum memanggil xrCreateSpatialAnchorSpaceANDROID
  • session harus berupa handle XrSession yang valid
  • spatialContext harus berupa handle XrSpatialContextEXT yang valid
  • createInfo harus berupa pointer ke struktur XrSpatialAnchorCreateInfoEXT yang valid
  • anchorEntityId harus berupa pointer ke nilai XrSpatialEntityIdEXT
  • anchorSpace harus berupa pointer ke handle XrSpace
  • spatialContext harus telah dibuat, dialokasikan, atau diambil dari session

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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Membuat XrSpace dari anchor spasial yang ada

Fungsi xrCreateSpatialAnchorSpaceFromIdANDROID didefinisikan sebagai:

XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorSpace);

Deskripsi Parameter

Dalam skenario saat entity anchor spasial sudah ada (misalnya, karena persistensi), aplikasi dapat membuat XrSpace dari anchor spasial ini dengan memberikan ID entity spasialnya.

Fungsi xrCreateSpatialAnchorSpaceFromIdANDROID membuat handle XrSpace dengan memberikan XrSpatialEntityIdEXT di kolom XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId.

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika XrSpatialContextEXT yang diteruskan ke xrCreateSpatialAnchorSpaceFromIdANDROID tidak dikonfigurasi dengan XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

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

Struktur XrSpatialAnchorSpaceFromIdCreateInfoANDROID didefinisikan sebagai:

typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • anchorEntityId adalah XrSpatialEntityIdEXT anchor spasial yang ada yang digunakan untuk membuat XrSpace .

Runtime harus menampilkan XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT jika XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId bukan ID yang valid untuk spatialContext .

Runtime harus menampilkan XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID jika XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId bukan ID entity yang valid untuk anchor.

Penggunaan yang Valid (Implisit)

Siklus Proses Anchor

Induk dari handle XrSpace adalah XrSession . Artinya, handle XrSpace yang mewakili anchor tetap valid bahkan setelah xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext atau xrCreateSpatialAnchorSpaceANDROID :: spatialContext dihancurkan. Membuat XrSpace untuk merepresentasikan anchor entity spasial memungkinkan aplikasi menghancurkan XrSpatialContextEXT yang dikonfigurasi dengan XR_SPATIAL_CAPABILITY_ANCHOR_EXT sambil terus mendapatkan pose terbaru anchor menggunakan XrSpace dengan xrLocateSpaces, yaitu runtime harus terus melacak anchor hingga semua handle XrSpace yang merepresentasikannya dihancurkan.

Kode contoh

Membuat anchor spasial sebagai XrSpace

Kode contoh berikut menunjukkan cara membuat anchor spasial dan menampilkannya sebagai XrSpace .

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpace spatialAnchorSpace {XR_NULL_HANDLE}; // XrSpace handle of anchor

// Spatial anchor create info
XrSpatialAnchorCreateInfoEXT createInfo{
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

// Create spatial anchor using the new API
CHK_XR(xrCreateSpatialAnchorSpaceANDROID(session, spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorSpace));

// ...

Membuat XrSpace dari ID entity anchor

Kode contoh berikut menunjukkan cara membuat XrSpace dari ID entity anchor yang sudah ada.

XrSpace anchorSpace = XR_NULL_HANDLE;

// Spatial anchor from XrSpace create info
XrSpatialAnchorSpaceFromIdCreateInfoANDROID createInfoFromId{
  .type = XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID,
  .anchorEntityId = spatialAnchorEntityId,
};

// Create XrSpace handle from spatial anchor ID
CHK_XR(xrCreateSpatialAnchorSpaceFromIdANDROID(session, spatialContext, &createInfoFromId, &anchorSpace));

// ...

Perintah Baru

Struktur Baru

Konstanta Enum Baru

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

  • Memperluas XrResult :

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

  • Memperluas XrStructureType :

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

Masalah

Riwayat Versi

  • Revisi 1, 15-09-2025 (YuSheng Chang, Kyle Chen)

    • Deskripsi ekstensi awal.