XR_EXT_spatial_image_tracking

String Nama

XR_EXT_spatial_image_tracking

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

783

Revisi

1

Status Ratifikasi

Belum diratifikasi

Dependensi Ekstensi dan Versi

XR_EXT_spatial_entity

Kontributor

Daniel Guttenberg, Qualcomm
Nihav Jain, Google
Jared Finder, Google
Zhipeng Liu, ByteDance

Ringkasan

Ekstensi ini menyediakan kemampuan pelacakan gambar untuk ekstensi XR_EXT_spatial_entity. Fitur ini memungkinkan aplikasi mendeteksi dan melacak gambar planar tertentu seperti yang ditentukan oleh kumpulan gambar referensi input.

Gambar yang dilacak direpresentasikan sebagai entity spasial dengan (atau "yang memiliki") komponen berikut:

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Aplikasi biasanya menggunakan ekstensi pelacakan gambar spasial dalam pola berikut:

  • Aplikasi pertama-tama membuat satu atau banyak handle XrSpatialImageTrackingDatabaseEXT berdasarkan set data gambar referensi yang telah dimuat sebelumnya.
  • Aplikasi kemudian membuat handle XrSpatialContextEXT berdasarkan handle XrSpatialImageTrackingDatabaseEXT yang dibuat sebelumnya.
  • Kemudian, aplikasi akan merilis data gambar referensi untuk mengurangi konsumsi memorinya.
  • Aplikasi menemukan dan mengkueri gambar sesuai dengan pola akses entity spasial.
  • Aplikasi dapat memuat kumpulan gambar referensi tambahan dan membuat XrSpatialImageTrackingDatabaseEXT tambahan, lalu XrSpatialContextEXT dari gambar tersebut untuk memperluas kumpulan gambar yang dapat dideteksi dan dilacak secara dinamis saat runtime.
  • Aplikasi dapat menghancurkan handle XrSpatialImageTrackingDatabaseEXT untuk mengurangi kumpulan gambar yang dapat dideteksi dan dilacak secara dinamis saat runtime.
  • Aplikasi dapat menghancurkan handle XrSpatialContextEXT untuk mengurangi kumpulan gambar yang dapat dideteksi dan dilacak secara dinamis saat runtime.

Dukungan Runtime

Runtime harus memberitahukan dukungannya untuk kemampuan pelacakan gambar menggunakan xrEnumerateSpatialCapabilitiesEXT dengan mencantumkan kemampuan berikut:

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Konfigurasi

Untuk mengaktifkan deteksi dan pelacakan gambar planar, aplikasi dapat meneruskan struktur XrSpatialCapabilityConfigurationImageTrackingEXT di XrSpatialContextCreateInfoEXT :: capabilityConfigs saat memanggil fungsi xrCreateSpatialContextAsyncEXT, dan meneruskan array struktur< XrSpatialImageTrackingDatabaseEXT di setiap XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases .

Pembuatan Set Gambar Input

Untuk menentukan gambar referensi yang akan dideteksi dan dilacak, aplikasi harus membuat setidaknya satu set gambar referensi input. Satu set gambar referensi input diwakili oleh handle XrSpatialImageTrackingDatabaseEXT dan berisi setidaknya satu gambar.

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

Handle XrSpatialImageTrackingDatabaseEXT mewakili resource untuk menemukan dan memperbarui sejumlah gambar spasial di lingkungan pengguna. Aplikasi dapat menggunakan handle ini untuk menemukan dan memperbarui gambar spasial menggunakan fungsi lain dalam ekstensi ini.

Membuat Database Pelacakan Gambar Spasial

Fungsi xrCreateSpatialImageTrackingDatabaseAsyncEXT didefinisikan sebagai:

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Deskripsi Parameter

Aplikasi dapat membuat handle XrSpatialImageTrackingDatabaseEXT menggunakan fungsi xrCreateSpatialImageTrackingDatabaseAsyncEXT dan mengonfigurasi kumpulan gambar referensi input database pelacakan gambar dengan createInfo .

Runtime harus menampilkan XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT jika XrSpatialReferenceImageEXT :: format dari salah satu gambar referensi input tidak dihitung oleh xrEnumerateSpatialReferenceImageFormatsEXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_IMAGE_INVALID_EXT jika array XrSpatialReferenceImageEXT :: planes dari salah satu gambar referensi input tidak dapat dievaluasi sesuai dengan metadata gambar referensi XrSpatialReferenceImageEXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_IMAGE_INVALID_EXT jika array XrSpatialReferenceImageEXT :: planes dari salah satu gambar referensi input tidak menyediakan bidang yang sama persis dengan jumlah saluran warna yang dimiliki XrSpatialReferenceImageEXT :: format.

Jika runtime menerapkan sistem izin untuk mengontrol akses aplikasi ke kemampuan pelacakan gambar, runtime harus menampilkan XR_ERROR_PERMISSION_INSUFFICIENT jika izin tersebut belum diberikan ke aplikasi ini.

Fungsi ini memulai operasi asinkron dan membuat XrFutureEXT yang sesuai, yang dapat digunakan dengan xrPollFutureEXT dan fungsi terkait. Nilai yang ditampilkan dari fungsi ini hanya menunjukkan apakah parameter dapat diterima untuk menjadwalkan operasi asinkron. Fungsi penyelesaian yang sesuai adalah xrCreateSpatialImageTrackingDatabaseCompleteEXT , dapat digunakan saat future dari fungsi ini dalam status READY, dengan output yang diisi oleh fungsi tersebut dalam struktur penyelesaian XrCreateSpatialImageTrackingDatabaseCompletionEXT .

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_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrSpatialImageTrackingDatabaseCreateInfoEXT didefinisikan sebagai:

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • spatialReferenceImageCount adalah jumlah elemen dalam array spatialReferenceImages.
  • spatialReferenceImages adalah array XrSpatialReferenceImageEXT .

Struktur XrSpatialImageTrackingDatabaseCreateInfoEXT menjelaskan informasi untuk membuat handle XrSpatialImageTrackingDatabaseEXT.

Setiap XrSpatialImageTrackingDatabaseEXT harus dibuat dengan setidaknya satu XrSpatialReferenceImageEXT dalam array XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

Penggunaan yang Valid (Implisit)

Fungsi xrCreateSpatialImageTrackingDatabaseCompleteEXT didefinisikan sebagai:

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

Deskripsi Parameter

xrCreateSpatialImageTrackingDatabaseCompleteEXT menyelesaikan operasi asinkron yang dimulai oleh xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Runtime tidak boleh mengakses pointer XrSpatialReferenceImagePlaneEXT :: buffer yang disediakan oleh array input XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages untuk panggilan xrCreateSpatialImageTrackingDatabaseAsyncEXT ini setelah selesai. Aplikasi dapat mengosongkan data XrSpatialReferenceImagePlaneEXT :: buffer setelah xrCreateSpatialImageTrackingDatabaseAsyncEXT selesai untuk mengurangi jejak memorinya.

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 XrCreateSpatialImageTrackingDatabaseCompletionEXT didefinisikan sebagai:

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

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_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

Jika futureResult adalah kode keberhasilan, database harus berupa handle yang valid. Jika database valid, validitasnya hanya berlaku dalam siklus proses xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session atau hingga aplikasi menghancurkan database dengan xrDestroySpatialImageTrackingDatabaseEXT , mana saja yang terjadi lebih dulu.

Penggunaan yang Valid (Implisit)

Menghancurkan Database Pelacakan Gambar Spasial

Fungsi xrDestroySpatialImageTrackingDatabaseEXT didefinisikan sebagai:

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

Deskripsi Parameter

Aplikasi dapat memanggil fungsi xrDestroySpatialImageTrackingDatabaseEXT untuk merilis handle database dan resource yang mendasarinya setelah selesai dengan tugas penemuan dan update gambar spasial.

Aplikasi dapat memanggil fungsi xrDestroySpatialImageTrackingDatabaseEXT sebelum memanggil xrDestroySpatialContextEXT . Runtime tidak boleh lagi melaporkan gambar yang dikelola oleh XrSpatialImageTrackingDatabaseEXT yang dihancurkan ini. Runtime harus terus melaporkan image yang dikelola oleh database lain.

Runtime harus memastikan bahwa snapshot penemuan yang ditampilkan oleh xrCreateSpatialDiscoverySnapshotCompleteEXT tidak berisi gambar yang berkaitan dengan handle XrSpatialImageTrackingDatabaseEXT yang dihancurkan atau tidak valid, meskipun handle tersebut dihancurkan setelah aplikasi memanggil xrCreateSpatialDiscoverySnapshotAsyncEXT . Mengingat data dalam snapshot spasial tidak dapat diubah, aplikasi harus menghancurkan semua handle XrSpatialSnapshotEXT yang dibuat sebelum menghancurkan database , jika tidak, aplikasi mungkin menerima handle XrSpatialImageTrackingDatabaseEXT yang tidak valid saat menggunakan xrQuerySpatialComponentDataEXT .

Aplikasi dapat memanggil fungsi xrDestroySpatialContextEXT untuk merilis handle XrSpatialContextEXT sebelum menghancurkan handle XrSpatialImageTrackingDatabaseEXT yang digunakan untuk membuat XrSpatialContextEXT. Runtime tidak boleh secara implisit menghancurkan handle XrSpatialImageTrackingDatabaseEXT ini saat XrSpatialContextEXT dihancurkan.

Mengelola masa aktif XrSpatialContextEXT dan XrSpatialImageTrackingDatabaseEXT secara independen memungkinkan aplikasi menggunakan kembali handle XrSpatialImageTrackingDatabaseEXT yang dibuat sebelumnya tanpa perlu melakukan prosedur pembuatan yang mahal.

Misalnya, menghancurkan XrSpatialContextEXT dan kemudian membuat ulang XrSpatialContextEXT lain dengan XrSpatialImageTrackingDatabaseEXT yang sama memungkinkan jeda dan melanjutkan pelacakan gambar tanpa perlu melakukan prosedur inisialisasi lain.

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke database , 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

Dukungan Format Gambar Input

Aplikasi harus memanggil xrEnumerateSpatialReferenceImageFormatsEXT untuk mendapatkan daftar format gambar referensi input yang didukung.

Fungsi xrEnumerateSpatialReferenceImageFormatsEXT didefinisikan sebagai:

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

Deskripsi Parameter

  • instance adalah handle ke XrInstance .
  • systemId adalah XrSystemId yang format gambar referensi inputnya akan dihitung.
  • capability adalah XrSpatialCapabilityEXT yang akan menghitung format gambar referensi input.
  • formatCapacityInput adalah kapasitas array formats, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • formatCountOutput adalah jumlah format, atau kapasitas yang diperlukan jika formatCapacityInput tidak mencukupi.
  • formats adalah array XrSpatialReferenceImageFormatEXT . Nilainya bisa NULL jika formatCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang cara mengambil ukuran formats yang diperlukan.

Aplikasi dapat menghitung daftar format gambar referensi input yang didukung oleh XrSystemId tertentu untuk XrSpatialCapabilityEXT tertentu menggunakan xrEnumerateSpatialReferenceImageFormatsEXT .

Runtime tidak boleh menghitung format ekstensi yang tidak diaktifkan untuk instance .

Penggunaan yang Valid (Implisit)

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_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Lihat XrSpatialReferenceImageFormatEXT untuk mengetahui daftar lengkap semua format gambar referensi yang didukung oleh ekstensi apa pun.

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

Enumerasi XrSpatialReferenceImageFormatEXT mengidentifikasi format gambar referensi input yang mungkin didukung runtime.

Setidaknya nilai XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT dan nilai XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT harus didukung.

Enumeran memiliki arti berikut:

Deskripsi Enumeran

  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT — Buffer RGBA. Format ini tidak menjamin tata letak data piksel dalam memori. Pixel harus diakses menggunakan metadata yang disediakan oleh struktur XrSpatialReferenceImagePlaneEXT yang sesuai. Setiap saluran warna piksel memiliki ukuran 8 bit, sehingga setiap piksel berukuran 32 bit.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT — Buffer RGB. Format ini tidak menjamin tata letak data piksel dalam memori. Pixel harus diakses menggunakan metadata yang disediakan oleh struktur XrSpatialReferenceImagePlaneEXT yang sesuai. Setiap saluran warna piksel memiliki ukuran 8 bit, sehingga setiap piksel berukuran 24 bit.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT — Buffer YUV yang merupakan sub-sampel chroma pola 4:2:0. Format ini tidak menjamin tata letak data piksel dalam memori. Pixel harus diakses menggunakan metadata yang disediakan oleh struktur XrSpatialReferenceImagePlaneEXT yang sesuai. Setiap saluran warna piksel RGB yang didekode memiliki ukuran 8 bit, sehingga setiap piksel berukuran 24 bit.

Setelan Pelacakan Gambar Spasial

Ekstensi ini menyediakan struktur opsional yang dapat digunakan aplikasi untuk mengonfigurasi kemampuan pelacakan gambar.

Pengoptimalan Gambar Statis

Struktur XrSpatialImageStaticOptimizationEXT didefinisikan sebagai:

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • optimizeForStaticImage adalah XrBool32 yang menunjukkan apakah gambar bergerak atau tidak. Nilai XR_TRUE menunjukkan bahwa gambar tidak bergerak.

Jika XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT dihitung oleh xrEnumerateSpatialCapabilityFeaturesEXT untuk kemampuan XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, aplikasi dapat merantai XrSpatialImageStaticOptimizationEXT ke rantai XrSpatialImageTrackingDatabaseCreateInfoEXT :: next, atau XrSpatialReferenceImageEXT :: next .

Jika aplikasi merantai XrSpatialImageStaticOptimizationEXT ke struktur XrSpatialImageTrackingDatabaseCreateInfoEXT, runtime harus mengasumsikan bahwa semua gambar XrSpatialImageTrackingDatabaseEXT tersebut bersifat statis jika optimizeForStaticImage ditetapkan ke XR_TRUE . Dengan demikian, runtime harus mengasumsikan bahwa semua gambar XrSpatialImageTrackingDatabaseEXT tersebut tidak statis jika optimizeForStaticImage ditetapkan ke XR_FALSE .

Jika aplikasi merantai XrSpatialImageStaticOptimizationEXT ke struktur XrSpatialReferenceImageEXT, runtime harus mengasumsikan bahwa gambar referensi ini statis jika optimizeForStaticImage ditetapkan ke XR_TRUE . Dengan demikian, runtime harus mengasumsikan bahwa gambar referensi ini tidak statis jika optimizeForStaticImage ditetapkan ke XR_FALSE . Menghubungkan struktur XrSpatialImageStaticOptimizationEXT ke struktur XrSpatialReferenceImageEXT lebih diprioritaskan daripada menghubungkannya ke struktur XrSpatialImageTrackingDatabaseCreateInfoEXT.

Jika XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT tidak dihitung oleh xrEnumerateSpatialCapabilityFeaturesEXT untuk kemampuan XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT dan aplikasi merantai struktur XrSpatialImageStaticOptimizationEXT ke salah satu rantai berikutnya yang berlaku, runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Hal ini dapat memungkinkan runtime menghasilkan pose dan ukuran yang lebih akurat.

Hal ini dapat memungkinkan runtime mengurangi konsumsi daya.

Penggunaan yang Valid (Implisit)

Lebar Gambar Referensi

Struktur XrSpatialImageSizeEXT didefinisikan sebagai:

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • physicalWidth adalah nilai float yang mewakili lebar fisik dalam meter yang akan ditetapkan.

Jika XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT dihitung oleh xrEnumerateSpatialCapabilityFeaturesEXT untuk kemampuan XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, aplikasi dapat merantai XrSpatialImageSizeEXT ke XrSpatialImageTrackingDatabaseCreateInfoEXT :: next atau XrSpatialReferenceImageEXT :: next .

Jika aplikasi merantai XrSpatialImageSizeEXT ke struktur XrSpatialImageTrackingDatabaseCreateInfoEXT, runtime harus mengasumsikan bahwa semua gambar XrSpatialImageTrackingDatabaseEXT tersebut memiliki lebar physicalWidth meter dan tinggi sesuai dengan rasio aspek seperti yang disediakan secara implisit melalui XrSpatialReferenceImageEXT :: width dan XrSpatialReferenceImageEXT :: height .

Jika aplikasi merantai XrSpatialImageSizeEXT ke struktur XrSpatialReferenceImageEXT, runtime harus mengasumsikan bahwa gambar referensi ini memiliki lebar physicalWidth meter dan tinggi sesuai dengan rasio aspek seperti yang disediakan secara implisit melalui XrSpatialReferenceImageEXT :: width dan XrSpatialReferenceImageEXT :: height . Menghubungkan struktur XrSpatialImageSizeEXT ke struktur XrSpatialReferenceImageEXT lebih diprioritaskan daripada menghubungkannya ke struktur XrSpatialImageTrackingDatabaseCreateInfoEXT.

Hal ini dapat memungkinkan runtime menampilkan pose dan ukuran yang lebih akurat.

Runtime harus menghitung XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT atau XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT atau keduanya.

Jika XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT dihitung oleh xrEnumerateSpatialCapabilityFeaturesEXT, runtime harus menyediakan ukuran gambar secara otomatis untuk gambar yang tidak menyediakan struktur XrSpatialImageSizeEXT sebagai bagian dari rantai berikutnya yang berlaku.

Agar runtime dapat menghasilkan ukuran gambar secara otomatis dan akurat, kemampuan dan prasyarat perangkat tertentu mungkin diperlukan; yaitu kamera stereo, parameter ekstrinsik dan intrinsik kamera yang dikalibrasi secara akurat.

Jika XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT tidak dihitung oleh xrEnumerateSpatialCapabilityFeaturesEXT, aplikasi harus menautkan struktur XrSpatialImageSizeEXT ke rantai berikutnya yang berlaku sehingga semua gambar memiliki ukuran eksplisit yang disediakan untuknya, jika tidak, runtime harus menampilkan XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT dari xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Penggunaan yang Valid (Implisit)

Struktur XrSpatialCapabilityConfigurationImageTrackingEXT didefinisikan sebagai:

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • capability adalah XrSpatialCapabilityEXT dan harus berupa XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT .
  • enabledComponentCount adalah uint32_t yang menentukan jumlah elemen dalam enabledComponents .
  • enabledComponents adalah array XrSpatialComponentTypeEXT yang menentukan komponen yang akan diaktifkan untuk kemampuan ini.
  • imageTrackingDatabaseCount adalah unint32_t yang menentukan jumlah elemen dalam imageTrackingDatabases .
  • imageTrackingDatabases adalah array handle XrSpatialImageTrackingDatabaseEXT yang menentukan database pelacakan gambar yang akan diaktifkan untuk konteks spasial.

Jika pelacakan gambar didukung, runtime harus mengaktifkan pelacakan gambar jika struktur XrSpatialCapabilityConfigurationImageTrackingEXT diteruskan di XrSpatialContextCreateInfoEXT :: capabilityConfigs saat memanggil xrCreateSpatialContextAsyncEXT .

Struktur XrSpatialCapabilityConfigurationImageTrackingEXT memungkinkan aplikasi menemukan gambar referensi yang diwakili oleh handle XrSpatialImageTrackingDatabaseEXT di imageTrackingDatabases .

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT jika XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT tidak dihitung oleh xrEnumerateSpatialCapabilitiesEXT .

Penggunaan yang Valid (Implisit)

Gambar Referensi Spasial

Struktur XrSpatialReferenceImagePlaneEXT didefinisikan sebagai:

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

Deskripsi Parameter

  • bufferSize adalah ukuran array buffer.
  • buffer adalah array data uint8_t yang mewakili data bidang.
  • rowStride adalah jarak byte antara dua posisi awal baris data piksel yang berurutan.
  • pixelStride adalah jarak byte antara dua piksel yang berurutan.

Runtime harus mengakses buffer sesuai dengan pola yang disediakan parameter rowStride dan pixelStride.

Aplikasi harus menetapkan rowStride dan pixelStride sehingga hanya piksel yang bermakna dari XrSpatialReferenceImagePlaneEXT ini yang diekstrak oleh runtime.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_EXT_spatial_image_tracking harus diaktifkan sebelum menggunakan XrSpatialReferenceImagePlaneEXT
  • buffer harus berupa pointer ke array nilai bufferSize uint8_t
  • Parameter bufferSize harus lebih besar dari 0

Struktur XrSpatialReferenceImageEXT didefinisikan sebagai:

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

Deskripsi Parameter

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • width adalah lebar piksel gambar referensi.
  • height adalah tinggi piksel gambar referensi.
  • format adalah XrSpatialReferenceImageFormatEXT yang mewakili format gambar.
  • planeCount adalah jumlah elemen dalam array planes.
  • planes adalah array struktur XrSpatialReferenceImagePlaneEXT yang mewakili bidang data gambar.

Aplikasi dapat membuat satu atau beberapa struktur XrSpatialReferenceImageEXT yang masing-masing mewakili satu gambar referensi input untuk diteruskan ke fungsi xrCreateSpatialImageTrackingDatabaseAsyncEXT melalui XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages saat membuat handle XrSpatialImageTrackingDatabaseEXT.

Data XrSpatialReferenceImagePlaneEXT :: buffer harus disediakan dalam urutan piksel dari kiri ke kanan dan dari atas ke bawah oleh aplikasi.

Aplikasi harus menyediakan struktur XrSpatialReferenceImagePlaneEXT dalam array XrSpatialReferenceImageEXT :: planes untuk setiap saluran warna XrSpatialReferenceImageEXT :: format .

Penggunaan yang Valid (Implisit)

Komponen Dijamin

Runtime yang mendukung XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT harus menyediakan komponen spasial berikut sebagai komponen yang dijamin dari semua entity yang ditemukan oleh kemampuan tersebut, dan harus menghitungnya dalam xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Komponen Gambar 2D

Struct Daftar Komponen untuk Mengkueri Data

Struktur XrSpatialComponentImage2DListEXT didefinisikan sebagai:

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

Deskripsi Parameter

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • imageCount adalah jumlah elemen dalam array images.
  • images adalah array XrSpatialImage2DDataEXT .

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

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

Penggunaan yang Valid (Implisit)

Data Komponen

Struktur XrSpatialImage2DDataEXT didefinisikan sebagai:

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

Deskripsi Parameter

Aplikasi dapat menggunakan imageTrackingDatabase untuk mengidentifikasi XrSpatialImageTrackingDatabaseEXT yang dibuat sebelumnya yang berisi gambar referensi struktur XrSpatialImage2DDataEXT ini. Untuk XrSpatialImageTrackingDatabaseEXT tersebut, aplikasi dapat menggunakan referenceImageIndex untuk mengidentifikasi XrSpatialReferenceImageEXT dari struktur XrSpatialImage2DDataEXT ini dengan mencocokkannya dengan urutan input array XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

Kumpulan gambar referensi yang ditentukan oleh kumpulan semua database aktif tidak boleh menyertakan gambar duplikat. Menyertakan gambar duplikat dapat menyebabkan perilaku penemuan atau pelacakan yang merugikan; yaitu indeks yang tidak konsisten atau beberapa indeks yang ditampilkan.

Penggunaan yang Valid (Implisit)

Konfigurasi

Jika XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT dihitung dalam XrSpatialCapabilityComponentTypesEXT :: componentTypes untuk beberapa kemampuan, aplikasi dapat mengaktifkannya dengan menyertakan nilai enum dalam daftar XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Komponen ini tidak memerlukan konfigurasi khusus untuk disertakan dalam rantai XrSpatialCapabilityConfigurationBaseHeaderEXT berikutnya.

Komponen 2D Terikat

Komponen 2D yang dibatasi menyediakan pusat dan jangkauan gambar spasial yang diwakili oleh entity tempatnya berada. Lihat 2D Terbatas untuk mengetahui detail selengkapnya tentang komponen 2D terbatas.

Kode Contoh

Menemukan Gambar Spasial & Data Komponen Kueri

Contoh kode berikut menunjukkan cara menemukan entity spasial untuk kemampuan pelacakan gambar dan mengkueri data komponennya.

XrInstance instance; // Previously initialized
XrSystemId systemId; // Previously initialized
XrSession session; // Previously initialized

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  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) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components
  std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

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

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

    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.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

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

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

    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
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

Jenis Objek Baru

Perintah Baru

Struktur Baru

Enum Baru

Konstanta Enum Baru

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • Memperluas XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • Memperluas XrResult :

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • Memperluas XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

  • Memperluas XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

  • Memperluas XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

  • Memperluas XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
    • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
    • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
    • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

Masalah

Riwayat Versi

  • Revisi 1, 22-04-2025 (Daniel Guttenberg, Qualcomm)

    • Deskripsi ekstensi awal