XR_EXT_spatial_persistence

String Nama

XR_EXT_spatial_persistence

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

764

Revisi

1

Status Ratifikasi

Diratifikasi

Dependensi Ekstensi dan Versi

XR_EXT_spatial_entity
dan
XR_EXT_future

Kontributor

Nihav Jain, Google
Jared Finder, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Ringkasan

Ekstensi ini memungkinkan aplikasi menemukan dan menghubungkan entity spasial di seluruh sesi aplikasi, sesi OpenXR, dan beberapa konteks spasial OpenXR dalam satu sesi. Ekstensi XR_EXT_spatial_entity menetapkan bahwa entity dalam XrSpatialContextEXT direpresentasikan oleh XrSpatialEntityIdEXT . Ekstensi ini memperluas konsep tersebut dengan menetapkan bahwa suatu entity, jika dipertahankan, akan direpresentasikan oleh XrUuid di seluruh sesi aplikasi dan OpenXR, yaitu aplikasi dapat menggunakan XrUuid yang disediakan oleh ekstensi ini untuk mengidentifikasi entity di seluruh sesi. Ekstensi ini juga memberikan tumpang-tindih yang berguna dengan ekstensi XR_EXT_spatial_entity untuk menemukan entity yang dipertahankan di lingkungan pengguna dan kemampuan untuk mengkueri data komponennya.

Konteks Persistensi Spasial

Membuat konteks persistensi spasial

XR_DEFINE_HANDLE(XrSpatialPersistenceContextEXT)

Handle XrSpatialPersistenceContextEXT mewakili koneksi ke penyimpanan entity spasial persisten.

Fungsi xrCreateSpatialPersistenceContextAsyncEXT didefinisikan sebagai:

XrResult xrCreateSpatialPersistenceContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialPersistenceContextCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Deskripsi Parameter

Aplikasi dapat membuat handle XrSpatialPersistenceContextEXT menggunakan fungsi xrCreateSpatialPersistenceContextAsyncEXT dan mengonfigurasi cakupan konteks persistensi di createInfo .

Runtime harus menampilkan XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_UNSUPPORTED_EXT jika XrSpatialPersistenceContextCreateInfoEXT :: scope tidak dihitung oleh xrEnumerateSpatialPersistenceScopesEXT .

Jika runtime menerapkan sistem izin untuk mengontrol akses aplikasi ke penyimpanan persistensi yang diwakili oleh XrSpatialPersistenceContextEXT , runtime harus menampilkan XR_ERROR_PERMISSION_INSUFFICIENT jika izin tersebut belum diberikan ke aplikasi ini.

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_PERSISTENCE_SCOPE_UNSUPPORTED_EXT
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrSpatialPersistenceContextCreateInfoEXT didefinisikan sebagai:

typedef struct XrSpatialPersistenceContextCreateInfoEXT {
    XrStructureType                 type;
    const void*                     next;
    XrSpatialPersistenceScopeEXT    scope;
} XrSpatialPersistenceContextCreateInfoEXT;

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.
  • scope adalah XrSpatialPersistenceScopeEXT yang menentukan cakupan penyimpanan konteks persistensi.

Struktur XrSpatialPersistenceContextCreateInfoEXT menjelaskan informasi untuk membuat handle XrSpatialPersistenceContextEXT.

Penggunaan yang Valid (Implisit)

typedef enum XrSpatialPersistenceScopeEXT {
    XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT = 1,
    XR_SPATIAL_PERSISTENCE_SCOPE_LOCAL_ANCHORS_EXT = 1000781000,
    XR_SPATIAL_PERSISTENCE_SCOPE_ANCHORS_FOR_CLOUD_SHARING_ANDROIDX1 = 1000808000,
    XR_SPATIAL_PERSISTENCE_SCOPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceScopeEXT;

Enumerasi XrSpatialPersistenceScopeEXT mengidentifikasi berbagai jenis cakupan konteks persistensi.

Enum memiliki arti berikut:

Deskripsi Enum

XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT

Memberikan akses hanya baca kepada aplikasi (yaitu, aplikasi tidak dapat mengubah penyimpanan yang terkait dengan cakupan ini) ke entity spasial yang dipertahankan dan dikelola oleh sistem. Aplikasi dapat menggunakan UUID dalam komponen persistensi untuk cakupan ini guna menghubungkan entity di seluruh konteks spasial dan mulai ulang perangkat.

XR_SPATIAL_PERSISTENCE_SCOPE_LOCAL_ANCHORS_EXT

Operasi persistensi dan akses data dibatasi untuk anchor spasial, di perangkat yang sama, untuk pengguna yang sama dan aplikasi yang sama (Ditambahkan oleh ekstensi XR_EXT_spatial_persistence_operations)

XR_SPATIAL_PERSISTENCE_SCOPE_ANCHORS_FOR_CLOUD_SHARING_ANDROIDX1

Operasi persistensi dan akses data dibatasi untuk anchor spasial, yang dimiliki dan dikelola oleh project cloud yang sama. (Ditambahkan oleh ekstensi XR_ANDROIDX1_spatial_anchor_cloud_sharing)

Fungsi xrEnumerateSpatialPersistenceScopesEXT didefinisikan sebagai:

XrResult xrEnumerateSpatialPersistenceScopesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    persistenceScopeCapacityInput,
    uint32_t*                                   persistenceScopeCountOutput,
    XrSpatialPersistenceScopeEXT*               persistenceScopes);

Deskripsi Parameter

  • instance adalah handle ke XrInstance .
  • systemId adalah XrSystemId yang cakupan persistensi spasialnya akan dihitung.
  • persistenceScopeCapacityInput adalah kapasitas array persistenceScopes, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • persistenceScopeCountOutput adalah jumlah cakupan persistensi, atau kapasitas yang diperlukan jika persistenceScopeCapacityInput tidak mencukupi.
  • persistenceScopes adalah array XrSpatialPersistenceScopeEXT . Nilainya bisa NULL jika persistenceScopeCapacityInput adalah 0.
  • Lihat bab Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang cara mengambil ukuran persistenceScopes yang diperlukan.

Aplikasi dapat menghitung daftar cakupan persistensi spasial yang didukung oleh XrSystemId tertentu menggunakan xrEnumerateSpatialPersistenceScopesEXT .

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_EXT_spatial_persistence harus diaktifkan sebelum memanggil xrEnumerateSpatialPersistenceScopesEXT
  • instance harus berupa handle XrInstance yang valid
  • persistenceScopeCountOutput harus berupa pointer ke nilai uint32_t
  • Jika persistenceScopeCapacityInput bukan 0 , persistenceScopes harus berupa pointer ke array nilai persistenceScopeCapacityInput XrSpatialPersistenceScopeEXT

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Fungsi xrCreateSpatialPersistenceContextCompleteEXT didefinisikan sebagai:

XrResult xrCreateSpatialPersistenceContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialPersistenceContextCompletionEXT* completion);

Deskripsi Parameter

xrCreateSpatialPersistenceContextCompleteEXT menyelesaikan operasi asinkron yang dimulai oleh xrCreateSpatialPersistenceContextAsyncEXT . Runtime harus menampilkan XR_ERROR_FUTURE_PENDING_EXT jika future tidak dalam status siap. Runtime harus menampilkan XR_ERROR_FUTURE_INVALID_EXT jika future telah selesai atau dibatalkan.

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

Struktur XrCreateSpatialPersistenceContextCompletionEXT didefinisikan sebagai:

typedef struct XrCreateSpatialPersistenceContextCompletionEXT {
    XrStructureType                         type;
    void*                                   next;
    XrResult                                futureResult;
    XrSpatialPersistenceContextResultEXT    createResult;
    XrSpatialPersistenceContextEXT          persistenceContext;
} XrCreateSpatialPersistenceContextCompletionEXT;

Deskripsi Anggota

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_PERMISSION_INSUFFICIENT

Jika futureResult dan createResult adalah kode berhasil, persistenceContext harus valid. Jika persistenceContext valid, harus tetap demikian dalam siklus proses xrCreateSpatialPersistenceContextAsyncEXT :: session atau hingga aplikasi menggunakan xrDestroySpatialPersistenceContextEXT dengan persistenceContext , mana saja yang lebih dulu.

Runtime harus menetapkan createResult hanya jika futureResult adalah kode keberhasilan.

Penggunaan yang Valid (Implisit)

typedef enum XrSpatialPersistenceContextResultEXT {
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT = 0,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT = -1000781001,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_PERSIST_UUID_NOT_FOUND_EXT = -1000781002,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_LOCALIZATION_FAILURE_ANDROIDX1 = -1000808000,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAP_FEATURE_INSUFFICIENT_ANDROIDX1 = -1000808001,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_FAILURE_ANDROIDX1 = -1000808002,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_TIMEOUT_ANDROIDX1 = -1000808003,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceContextResultEXT;

Enumerasi XrSpatialPersistenceContextResultEXT mengidentifikasi berbagai jenis kode hasil untuk operasi persistensi. Kegagalan selama operasi persistensi tidak selalu berada dalam kontrol aplikasi dan enumerasi ini digunakan untuk menyampaikan kasus tersebut. Serupa dengan XrResult , kode keberhasilan dalam enumerasi XrSpatialPersistenceContextResultEXT adalah nilai non-negatif, dan kode kegagalan adalah nilai negatif.

Enum memiliki arti berikut:

Deskripsi Enum

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT

Operasi konteks persistensi berhasil.

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT

Operasi persistensi gagal karena entitas tidak dapat dilacak oleh runtime. (Ditambahkan oleh ekstensi XR_EXT_spatial_persistence_operations)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_PERSIST_UUID_NOT_FOUND_EXT

UUID persist yang diberikan tidak ditemukan di penyimpanan. (Ditambahkan oleh ekstensi XR_EXT_spatial_persistence_operations)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_LOCALIZATION_FAILURE_ANDROIDX1

Operasi persistensi gagal karena pelokalan gagal. (Ditambahkan oleh ekstensi XR_ANDROIDX1_spatial_anchor_cloud_sharing)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAP_FEATURE_INSUFFICIENT_ANDROIDX1

Operasi persistensi gagal karena fitur peta pelokalan tidak memadai. (Ditambahkan oleh ekstensi XR_ANDROIDX1_spatial_anchor_cloud_sharing)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_FAILURE_ANDROIDX1

Operasi persistensi gagal karena koneksi jaringan gagal. (Ditambahkan oleh ekstensi XR_ANDROIDX1_spatial_anchor_cloud_sharing)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_TIMEOUT_ANDROIDX1

Operasi persistensi gagal karena waktu tunggu jaringan habis. (Ditambahkan oleh ekstensi XR_ANDROIDX1_spatial_anchor_cloud_sharing)

Menghancurkan konteks persistensi spasial

Fungsi xrDestroySpatialPersistenceContextEXT didefinisikan sebagai:

XrResult xrDestroySpatialPersistenceContextEXT(
    XrSpatialPersistenceContextEXT              persistenceContext);

Deskripsi Parameter

Aplikasi dapat menggunakan xrDestroySpatialPersistenceContextEXT untuk merilis handle persistenceContext setelah selesai dengan tugas persistensi spasial.

Runtime tidak boleh menghancurkan resource yang mendasari untuk persistenceContext saat xrDestroySpatialPersistenceContextEXT dipanggil jika ada handle XrSpatialContextEXT yang valid yang ditautkan ke persistenceContext melalui XrSpatialContextPersistenceConfigEXT . Hal ini karena resource konteks persistensi masih digunakan oleh konteks spasial untuk menemukan entity yang dipertahankan. Menghancurkan handle konteks persistensi dalam situasi seperti ini hanya akan menghapus akses aplikasi ke resource tersebut.

Resource untuk XrSpatialPersistenceContextEXT yang dihancurkan harus dikosongkan saat semua handle XrSpatialContextEXT yang ditautkan ke konteks persistensi dihancurkan.

Penggunaan yang Valid (Implisit)

Keamanan Thread

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

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Menemukan entity yang dipertahankan

Komponen persistensi

Entity spasial yang dipertahankan memiliki komponen persistensi yang harus disertakan oleh runtime dalam snapshot penemuan dan update jika XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT diaktifkan selama pembuatan XrSpatialContextEXT dan disertakan dalam XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes atau XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes .

Data Komponen

Struktur XrSpatialPersistenceDataEXT didefinisikan sebagai:

typedef struct XrSpatialPersistenceDataEXT {
    XrUuid                          persistUuid;
    XrSpatialPersistenceStateEXT    persistState;
} XrSpatialPersistenceDataEXT;

Deskripsi Anggota

Penggunaan yang Valid (Implisit)

typedef enum XrSpatialPersistenceStateEXT {
    XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT = 1,
    XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT = 2,
    XR_SPATIAL_PERSISTENCE_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceStateEXT;

Enumerasi XrSpatialPersistenceStateEXT mengidentifikasi berbagai status uuid yang dipertahankan.

Enum memiliki arti berikut:

Deskripsi Enum

XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT

UUID yang dipertahankan telah berhasil dimuat dari penyimpanan.

XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT

UUID yang dipertahankan tidak ditemukan di penyimpanan dan telah dihapus dari penyimpanan atau tidak pernah ada di dalamnya.

Struktur daftar komponen untuk mengkueri data

Struktur XrSpatialComponentPersistenceListEXT didefinisikan sebagai:

typedef struct XrSpatialComponentPersistenceListEXT {
    XrStructureType                 type;
    void*                           next;
    uint32_t                        persistDataCount;
    XrSpatialPersistenceDataEXT*    persistData;
} XrSpatialComponentPersistenceListEXT;

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.
  • persistDataCount adalah uint32_t yang menjelaskan jumlah elemen dalam array persistData.
  • persistData adalah array XrSpatialPersistenceDataEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrQuerySpatialComponentDataEXT jika XrSpatialComponentPersistenceListEXT berada dalam rantai berikutnya dari XrSpatialComponentDataQueryResultEXT :: next, tetapi XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT tidak disertakan dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Runtime harus menampilkan XR_ERROR_SIZE_INSUFFICIENT dari xrQuerySpatialComponentDataEXT jika persistDataCount kurang dari XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Tidak seperti komponen lainnya, runtime harus menetapkan data untuk XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT, terlepas dari XrSpatialEntityTrackingStateEXT .

Penggunaan yang Valid (Implisit)

Konfigurasi

Jika XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT dihitung dalam XrSpatialCapabilityComponentTypesEXT :: componentTypes untuk beberapa kemampuan, aplikasi dapat mengaktifkannya dengan menyertakan enum dalam daftar XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Komponen ini tidak memerlukan konfigurasi khusus untuk disertakan dalam rantai XrSpatialCapabilityConfigurationBaseHeaderEXT berikutnya. Jika aplikasi menyertakan XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT dalam daftar komponen yang diaktifkan, aplikasi harus menyertakan XrSpatialContextPersistenceConfigEXT dalam rantai XrSpatialContextCreateInfoEXT berikutnya. Jika tidak, runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT dari xrCreateSpatialContextAsyncEXT .

Mengonfigurasi konteks spasial dengan konteks persistensi

Struktur XrSpatialContextPersistenceConfigEXT didefinisikan sebagai:

typedef struct XrSpatialContextPersistenceConfigEXT {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 persistenceContextCount;
    const XrSpatialPersistenceContextEXT*    persistenceContexts;
} XrSpatialContextPersistenceConfigEXT;

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.
  • persistenceContextCount adalah uint32_t yang menjelaskan jumlah elemen dalam array persistenceContexts.
  • persistenceContexts adalah array XrSpatialPersistenceContextEXT .

Aplikasi dapat menambahkan XrSpatialContextPersistenceConfigEXT ke rantai XrSpatialContextCreateInfoEXT berikutnya. Tindakan ini akan mengonfigurasi XrSpatialContextEXT yang dibuat dengan persistenceContexts dan memungkinkan aplikasi menemukan entity spasial yang dipertahankan dalam penyimpanan yang diwakili oleh handle XrSpatialPersistenceContextEXT di persistenceContexts .

Penggunaan yang Valid (Implisit)

Membuat snapshot penemuan

Menemukan entity dengan UUID tertentu

Struktur XrSpatialDiscoveryPersistenceUuidFilterEXT didefinisikan sebagai:

typedef struct XrSpatialDiscoveryPersistenceUuidFilterEXT {
    XrStructureType    type;
    const void*        next;
    uint32_t           persistedUuidCount;
    const XrUuid*      persistedUuids;
} XrSpatialDiscoveryPersistenceUuidFilterEXT;

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.
  • persistedUuidCount adalah uint32_t yang menjelaskan jumlah elemen dalam array persistedUuids
  • persistedUuids adalah array XrUuid .

Aplikasi dapat menggunakan XrSpatialDiscoveryPersistenceUuidFilterEXT dalam rantai XrSpatialDiscoverySnapshotCreateInfoEXT berikutnya untuk mencakup operasi penemuan hanya ke entity yang UUID persistennya berada dalam kumpulan UUID yang disediakan di persistedUuids .

Jika aplikasi menambahkan XrSpatialDiscoveryPersistenceUuidFilterEXT dalam rantai XrSpatialDiscoverySnapshotCreateInfoEXT berikutnya, tetapi xrCreateSpatialDiscoverySnapshotAsyncEXT :: spatialContext tidak dikonfigurasi dengan XrSpatialPersistenceContextEXT apa pun menggunakan XrSpatialContextPersistenceConfigEXT , runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrCreateSpatialDiscoverySnapshotAsyncEXT .

Runtime harus memperlakukan filter XrSpatialDiscoveryPersistenceUuidFilterEXT sebagai kondisi 'AND' dengan filter lain yang disediakan di XrSpatialDiscoverySnapshotCreateInfoEXT atau rantai berikutnya. Runtime harus memperlakukan array persistedUuids itu sendiri sebagai kondisi 'OR', yaitu memfilter entity yang memiliki UUID yang disediakan dalam array tersebut.

Runtime harus menyertakan satu entri dalam snapshot yang dibuat untuk setiap UUID di persistedUuids yang dapat menentukan status XrSpatialPersistenceStateEXT saat ini.

  • Jika runtime berhasil menemukan UUID di penyimpanannya, -

  • Jika runtime telah menentukan bahwa UUID tidak ada dalam penyimpanannya (terlepas dari apakah UUID tersebut tidak pernah ada dalam penyimpanan atau pernah ada tetapi telah dihapus), maka -

  • Jika runtime tidak dapat menentukan apakah UUID ada dalam penyimpanannya atau tidak, runtime tidak boleh menyertakannya dalam snapshot.

Aplikasi juga dapat menggunakan XrSpatialDiscoveryPersistenceUuidFilterEXT dalam rantai XrSpatialComponentDataQueryConditionEXT berikutnya untuk mengkueri entity UUID tertentu dalam snapshot yang ada. Jika digunakan dengan XrSpatialComponentDataQueryConditionEXT , jika XrSpatialDiscoveryPersistenceUuidFilterEXT :: persistedUuids berisi XrUuid yang tidak ada dalam XrSpatialSnapshotEXT , runtime tidak boleh menyertakan entri untuk XrUuid tersebut dalam hasil kueri. Selain itu, urutan (urutan) entitas dalam hasil kueri mungkin tidak cocok dengan urutan UUID yang diberikan di XrSpatialDiscoveryPersistenceUuidFilterEXT :: persistedUuids . Aplikasi harus menyertakan XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT di XrSpatialComponentDataQueryConditionEXT :: componentTypes dan XrSpatialComponentPersistenceListEXT di rantai berikutnya dari XrSpatialComponentDataQueryResultEXT, lalu memeriksa XrSpatialPersistenceDataEXT :: persistUuid dari setiap indeks hasil kueri untuk memahami UUID mana yang sesuai dengan indeks hasil saat ini.

Penggunaan yang Valid (Implisit)

Menemukan semua entitas yang dipertahankan

Jika aplikasi menggunakan xrCreateSpatialDiscoverySnapshotAsyncEXT tanpa XrSpatialDiscoveryPersistenceUuidFilterEXT dan dengan XrSpatialContextEXT yang telah dikonfigurasi dengan XrSpatialPersistenceContextEXT , runtime harus menyertakan entitas tersebut dalam snapshot yang dibuat yang dipertahankan dalam penyimpanan yang diwakili oleh XrSpatialPersistenceContextEXT dan memenuhi filter yang disediakan di XrSpatialDiscoverySnapshotCreateInfoEXT . Untuk entitas tersebut -

Jenis Objek Baru

Perintah Baru

Struktur Baru

Enum Baru

Konstanta Enum Baru

  • XR_EXT_SPATIAL_PERSISTENCE_EXTENSION_NAME
  • XR_EXT_spatial_persistence_SPEC_VERSION

  • Memperluas XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_PERSISTENCE_CONTEXT_EXT

  • Memperluas XrResult :

    • XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_UNSUPPORTED_EXT

  • Memperluas XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

  • Memperluas XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_PERSISTENCE_CONTEXT_COMPLETION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_PERSISTENCE_CONFIG_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_PERSISTENCE_UUID_FILTER_EXT
    • XR_TYPE_SPATIAL_PERSISTENCE_CONTEXT_CREATE_INFO_EXT

Kode Contoh

Membuat Konteks Persistensi

// Check if the required persistence scope supported
uint32_t scopeCount;
CHK_XR(xrEnumerateSpatialPersistenceScopesEXT(instance, systemId, 0, &scopeCount, nullptr));
std::vector<XrSpatialPersistenceScopeEXT> persistenceScopes(scopeCount);
CHK_XR(xrEnumerateSpatialPersistenceScopesEXT(instance, systemId, scopeCount, &scopeCount, persistenceScopes.data()));

if (std::find(persistenceScopes.begin(), persistenceScopes.end(), XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT) == persistenceScopes.end()) {
  return;
}

XrSpatialPersistenceContextEXT persistenceContext{};

XrSpatialPersistenceContextCreateInfoEXT persistenceContextCreateInfo{XR_TYPE_SPATIAL_PERSISTENCE_CONTEXT_CREATE_INFO_EXT};
persistenceContextCreateInfo.scope = XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT;
XrFutureEXT createContextFuture;
CHK_XR(xrCreateSpatialPersistenceContextAsyncEXT(session, &persistenceContextCreateInfo, &createContextFuture));

waitUntilReady(createContextFuture);

XrCreateSpatialPersistenceContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_PERSISTENCE_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialPersistenceContextCompleteEXT(session, createContextFuture, &completion));
if (completion.futureResult != XR_SUCCESS || completion.createResult != XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT) {
  return;
}

persistenceContext = completion.persistenceContext;

// ...
// Connect persistence context to a spatial context and discover persisted entities.
// ...

CHK_XR(xrDestroySpatialPersistenceContextEXT(persistenceContext));

Menghubungkan Konteks Persistensi ke Konteks Spasial

// Note: Anchor capability is just used as an example here. Persistence can be
// supported by other capabilities too. xrEnumerateSpatialCapabilityComponentTypesEXT() can
// be used to check if a certain capability supports persistence.
if (!isSpatialCapabilitySupported(instance, systemId, XR_SPATIAL_CAPABILITY_ANCHOR_EXT)) {
  return;
}

const bool supportsPersistenceComponent = isSpatialComponentSupported(instance, systemId, XR_SPATIAL_CAPABILITY_ANCHOR_EXT, XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT);

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{

  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  if (supportsPersistenceComponent) {
    enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_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();

  XrSpatialContextPersistenceConfigEXT persistenceConfig{XR_TYPE_SPATIAL_CONTEXT_PERSISTENCE_CONFIG_EXT};
  persistenceConfig.persistenceContextCount = 1;
  persistenceConfig.persistenceContexts = &persistenceContext;

  if (supportsPersistenceComponent) {
    spatialContextCreateInfo.next = &persistenceConfig;
  }

  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

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

  spatialContext = completion.spatialContext;
}

// ...
// Discover persisted anchors.
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Menemukan semua entitas yang dipertahankan

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialPersistenceDataEXT> persistenceData(queryResult.entityIdCountOutput);
    XrSpatialComponentPersistenceListEXT persistenceDataList{XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT};
    persistenceDataList.persistDataCount = persistenceData.size();
    persistenceDataList.persistData = persistenceData.data();
    queryResult.next = &persistenceDataList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      // persistenceData[i].persistUuid is the UUID of the persisted entity whose entity ID is entityIds[i].
      // The persistenceData array is essentially the uuids persisted in the scope that the current
      // XrSpatialPersistenceContextEXT is configured with.
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

Menemukan entity dengan UUID tertentu

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// Load up the uuids that the app has stored on its own i.e. the uuids it is interested in.
std::vector<XrUuid> uuidsStoredByApp = loadPersistedUuids();

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoveryPersistenceUuidFilterEXT persistenceFilter{XR_TYPE_SPATIAL_DISCOVERY_PERSISTENCE_UUID_FILTER_EXT};
  persistenceFilter.persistedUuidCount = uuidsStoredByApp.size();
  persistenceFilter.persistedUuids = uuidsStoredByApp.data();

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  snapshotCreateInfo.next = &persistenceFilter;

  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialPersistenceDataEXT> persistenceData(queryResult.entityIdCountOutput);
    XrSpatialComponentPersistenceListEXT persistenceDataList{XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT};
    persistenceDataList.persistDataCount = persistenceData.size();
    persistenceDataList.persistData = persistenceData.data();
    queryResult.next = &persistenceDataList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (persistenceData[i].persistState == XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT) {
        // persistenceData[i].persistUuid, requested by the app, is present in the persistence scope
        // and its corresponding entity ID and state are entityIds[i] & entityStates[i] respectively.
      } else if (persistenceData[i].persistState == XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT) {
        // persistenceData[i].persistUuid, requested by the app, is NOT present in the persistence scope
        // and its corresponding entity ID (entityIds[i]) would be XR_NULL_SPATIAL_ENTITY_ID_EXT
        // and tracking state (entityStates[i]) would be XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT.
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

Masalah

Riwayat Versi

  • Revisi 1, 29-08-2024 (Nihav Jain, Google)

    • Deskripsi ekstensi awal