XR_ANDROID_trackables_image
String Nama
XR_ANDROID_trackables_image
Jenis Ekstensi
Ekstensi instance
Nomor Ekstensi Terdaftar
710
Revisi
1
Status Ratifikasi
Belum diratifikasi
Dependensi Ekstensi dan Versi
XR_EXT_future
dan
XR_ANDROID_trackables
Tanggal Terakhir Diubah
2025-04-08
Status IP
Tidak ada klaim kekayaan intelektual yang diketahui.
Kontributor
Christopher Doer, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Diego Tipaldi, Google
Daniel Guttenberg, Qualcomm
Mark Vadasi, Qualcomm
Markus Birkner, Qualcomm
Maximilian Mayer, Qualcomm
Ringkasan
Ekstensi ini memungkinkan pelacakan gambar planar seperti yang ditentukan oleh kumpulan gambar referensi input.
Izin
Aplikasi Android harus memiliki izin android.permission.SCENE_UNDERSTANDING_COARSE yang tercantum dalam manifesnya karena ekstensi ini bergantung pada XR_ANDROID_trackables dan mengekspos geometri lingkungan. Izin android.permission.SCENE_UNDERSTANDING_COARSE dianggap sebagai izin berbahaya.
(tingkat perlindungan: berbahaya)
Memeriksa kemampuan sistem
Struktur XrSystemImageTrackingPropertiesANDROID didefinisikan sebagai:
typedef struct XrSystemImageTrackingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsImageTracking;
XrBool32 supportsPhysicalSizeEstimation;
uint32_t maxTrackedImageCount;
uint32_t maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;
Deskripsi Anggota
typeadalah XrStructureType dari struktur ini.nextadalahNULLatau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini. Untuk mengetahui detail selengkapnya tentang rantai struktur, lihat struktur yang diperluas ( XrSystemProperties ).supportsImageTrackingadalahXrBool32yang menunjukkan apakah sistem saat ini menyediakan kemampuan pelacakan gambar.supportsPhysicalSizeEstimationadalahXrBool32yang menunjukkan apakah sistem saat ini menyediakan estimasi ukuran gambar.maxTrackedImageCountadalah jumlah maksimum total gambar yang dapat dilacak secara bersamaan.maxLoadedImageCountadalah jumlah maksimum total gambar referensi yang dapat dimuat di semua database.
Aplikasi dapat memeriksa apakah sistem mampu melakukan pelacakan gambar dengan memperluas XrSystemProperties dengan struktur XrSystemImageTrackingPropertiesANDROID saat memanggil xrGetSystemProperties . Runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED untuk pembuatan pelacak gambar jika dan hanya jika supportsImageTracking adalah XR_FALSE .
Jika runtime mendukung pelacakan gambar, runtime tersebut harus mendukung maxTrackedImageCount gambar yang dilacak pada waktu tertentu.
Jika runtime mendukung pelacakan gambar, runtime tersebut harus mendukung maxLoadedImageCount gambar yang dimuat pada waktu tertentu.
Jika runtime mendukung estimasi ukuran gambar, aplikasi dapat menetapkan XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0 untuk menunjukkan penggunaan estimasi ukuran. Jika tidak, aplikasi harus menetapkan XrTrackableImageDatabaseEntryANDROID :: physicalWidth ke nilai positif atau XR_ERROR_VALIDATION_FAILURE akan ditampilkan.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum menggunakan XrSystemImageTrackingPropertiesANDROID -
typeharus berupaXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID -
nextharus berupaNULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur
Membuat database
Aplikasi dapat membuat handle XrTrackableImageDatabaseANDROID dengan membuat satu atau beberapa struktur XrTrackableImageDatabaseEntryANDROID dan meneruskannya ke fungsi xrCreateTrackableImageDatabaseAsyncANDROID melalui struktur XrTrackableImageDatabaseCreateInfoANDROID.
Aplikasi harus menyediakan setidaknya satu XrTrackableImageDatabaseEntryANDROID saat membuat handle XrTrackableImageDatabaseANDROID.
XrTrackableImageDatabaseANDROID adalah handle yang mewakili sekumpulan gambar referensi yang diproses yang dapat ditemukan dan dilacak di lingkungan.
XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)
Struktur XrTrackableImageDatabaseEntryANDROID didefinisikan sebagai:
typedef struct XrTrackableImageDatabaseEntryANDROID {
XrStructureType type;
const void* next;
XrTrackableImageTrackingModeANDROID trackingMode;
float physicalWidth;
uint32_t imageWidth;
uint32_t imageHeight;
XrTrackableImageFormatANDROID format;
uint32_t bufferSize;
const uint8_t* buffer;
} XrTrackableImageDatabaseEntryANDROID;
Deskripsi Anggota
typeadalah XrStructureType dari struktur ini.nextadalahNULLatau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.trackingModeadalah XrTrackableImageTrackingModeANDROID yang menunjukkan mode yang diinginkan untuk pelacakan.physicalWidthmenunjukkan lebar gambar dalam meter. Jika nol, ukuran gambar akan diperkirakan secara online.imageWidthmenunjukkan lebar gambar dalam piksel.imageHeightmenunjukkan tinggi gambar dalam piksel.formatadalah XrTrackableImageFormatANDROID yang menunjukkan format data gambar dibuffer.bufferSizemenunjukkan panjang bytebuffer.bufferadalah bufferinguint8_tyang berisi data piksel gambar referensi. Kontenbufferharus valid selama durasi operasi asinkron pembuatan database, yang dimulai oleh xrCreateTrackableImageDatabaseAsyncANDROID dan diselesaikan oleh xrCreateTrackableImageDatabaseCompleteANDROID .
Aplikasi dapat menetapkan physicalWidth ke 0 untuk meminta estimasi ukuran online jika XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation adalah XR_TRUE .
Runtime dapat menampilkan XR_ERROR_VALIDATION_FAILURE dari xrCreateTrackableImageDatabaseAsyncANDROID jika bufferSize tidak cocok dengan ukuran yang diharapkan berdasarkan imageWidth , imageHeight , dan format entri.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum menggunakan XrTrackableImageDatabaseEntryANDROID -
typeharus berupaXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID -
nextharus berupaNULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur -
trackingModeharus berupa nilai XrTrackableImageTrackingModeANDROID yang valid -
formatharus berupa nilai XrTrackableImageFormatANDROID yang valid -
bufferharus berupa pointer ke array nilaibufferSizeuint8_t - Parameter
bufferSizeharus lebih besar dari0
Struktur XrTrackableImageDatabaseCreateInfoANDROID didefinisikan sebagai:
typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
XrStructureType type;
const void* next;
uint32_t entryCount;
const XrTrackableImageDatabaseEntryANDROID* entries;
} XrTrackableImageDatabaseCreateInfoANDROID;
Deskripsi Anggota
typeadalah XrStructureType dari struktur ini.nextadalahNULLatau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.entryCountadalahuint32_tyang menentukan jumlah elemen dalam arrayentries.entriesadalah array struktur XrTrackableImageDatabaseEntryANDROID.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum menggunakan XrTrackableImageDatabaseCreateInfoANDROID -
typeharus berupaXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID -
nextharus berupaNULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur -
entriesharus berupa pointer ke array struktur XrTrackableImageDatabaseEntryANDROID yang validentryCount - Parameter
entryCountharus lebih besar dari0
Struktur XrCreateTrackableImageDatabaseCompletionANDROID didefinisikan sebagai:
typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrTrackableImageDatabaseANDROID database;
} XrCreateTrackableImageDatabaseCompletionANDROID;
Deskripsi Anggota
typeadalah XrStructureType dari struktur ini.nextadalahNULLatau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.futureResultadalah XrResult dari operasi asinkron.databaseadalah handle XrTrackableImageDatabaseANDROID yang dibuat.
Kode Status Mendatang
Nilai futureResult:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum menggunakan XrCreateTrackableImageDatabaseCompletionANDROID -
typeharus berupaXR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID -
nextharus berupaNULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur -
futureResultharus berupa nilai XrResult yang valid -
databaseharus berupa handle XrTrackableImageDatabaseANDROID yang valid
Fungsi xrCreateTrackableImageDatabaseAsyncANDROID didefinisikan sebagai:
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
Deskripsi Parameter
sessionadalah handle untuk XrSession yang sebelumnya dibuat dengan xrCreateSession .createInfoadalah pointer ke struktur XrTrackableImageDatabaseCreateInfoANDROID.futureadalah pointer keXrFutureEXTyang dibuat.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum memanggil xrCreateTrackableImageDatabaseAsyncANDROID -
sessionharus berupa handle XrSession yang valid -
createInfoharus berupa pointer ke struktur XrTrackableImageDatabaseCreateInfoANDROID yang valid -
futureharus berupa pointer ke nilaiXrFutureEXT
Kode Status
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Fungsi xrCreateTrackableImageDatabaseCompleteANDROID didefinisikan sebagai:
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
Deskripsi Parameter
sessionadalah handle untuk XrSession yang sebelumnya dibuat dengan xrCreateSession .futureadalahXrFutureEXTmasa depan yang harus diselesaikan.completionadalah pointer ke struktur XrCreateTrackableImageDatabaseCompletionANDROID yang berisi hasil operasi.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum memanggil xrCreateTrackableImageDatabaseCompleteANDROID -
sessionharus berupa handle XrSession yang valid -
completionharus berupa pointer ke struktur XrCreateTrackableImageDatabaseCompletionANDROID
Kode Status
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Fungsi xrDestroyTrackableImageDatabaseANDROID didefinisikan sebagai:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
Deskripsi Parameter
databaseadalah handle XrTrackableImageDatabaseANDROID yang akan dihancurkan.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum memanggil xrDestroyTrackableImageDatabaseANDROID -
databaseharus berupa handle XrTrackableImageDatabaseANDROID yang valid
Keamanan Thread
- Akses ke
database, dan handle turunan apa pun, harus disinkronkan secara eksternal
Kode Status
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
Gambar pelacakan
Ekstensi ini menambahkan XR_TRACKABLE_TYPE_IMAGE_ANDROID ke XrTrackableTypeANDROID .
Aplikasi dapat membuat XrTrackableTrackerANDROID dengan memanggil xrCreateTrackableTrackerANDROID dan menentukan XR_TRACKABLE_TYPE_IMAGE_ANDROID sebagai jenis yang dapat dilacak di XrTrackableTrackerCreateInfoANDROID :: trackableType untuk melacak gambar.
Runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED jika XrTrackableTrackerCreateInfoANDROID :: trackableType adalah XR_TRACKABLE_TYPE_IMAGE_ANDROID dan XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking menampilkan XR_FALSE melalui xrGetSystemProperties .
Struktur XrTrackableImageConfigurationANDROID didefinisikan sebagai:
typedef struct XrTrackableImageConfigurationANDROID {
XrStructureType type;
const void* next;
uint32_t databaseCount;
const XrTrackableImageDatabaseANDROID* databases;
} XrTrackableImageConfigurationANDROID;
Deskripsi Anggota
typeadalah XrStructureType dari struktur ini.nextadalahNULLatau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.databaseCountadalahuint32_tyang menentukan jumlah elemen dalamdatabasesdatabasesadalah array XrTrackableImageDatabaseANDROID yang menentukan database yang akan digunakan untuk membuat pelacak.
Aplikasi harus menetapkan konfigurasi yang valid dengan menambahkan XrTrackableImageConfigurationANDROID ke rantai next dari XrTrackableTrackerCreateInfoANDROID . Jika tidak, runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .
Aplikasi harus menyediakan setidaknya satu struktur XrTrackableImageDatabaseANDROID untuk membuat pelacak.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum menggunakan XrTrackableImageConfigurationANDROID -
typeharus berupaXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID -
nextharus berupaNULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur -
databasesharus berupa pointer ke array handle XrTrackableImageDatabaseANDROID yang validdatabaseCount - Parameter
databaseCountharus lebih besar dari0
Enum XrTrackableImageTrackingModeANDROID menjelaskan mode pelacakan gambar yang didukung.
typedef enum XrTrackableImageTrackingModeANDROID {
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;
Deskripsi Enumeran
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID— Mode ini memiliki akurasi tertinggi dan memungkinkan pelacakan gambar bergerak dengan latensi rendah. Mode ini juga memiliki konsumsi daya tertinggi.XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID— Mode ini harus digunakan untuk gambar yang diketahui statis atau semi-statis. Mode ini menghasilkan konsumsi daya yang lebih rendah dibandingkan dengan mode dinamis. Jika gambar statis dipindahkan, gambar tersebut akan diperbarui dengan latensi yang jauh lebih tinggi daripada menggunakan mode dinamis.
Enum XrTrackableImageFormatANDROID menjelaskan format gambar yang didukung.
typedef enum XrTrackableImageFormatANDROID {
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;
Deskripsi Enumeran
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID— Format gambar RGBA dengan data transparansi dan warna 8 bit per saluran.
Fungsi xrAddTrackableImageDatabaseANDROID didefinisikan sebagai:
XrResult xrAddTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Deskripsi Parameter
trackeradalah handle XrTrackableTrackerANDROID untuk menambahkandatabase.databaseadalah handle XrTrackableImageDatabaseANDROID yang akan ditambahkan ketracker.
Saat XrTrackableImageDatabaseANDROID ditambahkan ke pelacak, gambar referensi database tersebut harus dipertimbangkan untuk deteksi dan pelacakan, selain database lain yang telah ditambahkan sebelumnya dengan xrAddTrackableImageDatabaseANDROID atau melalui struktur XrTrackableImageConfigurationANDROID saat pertama kali membuat pelacak.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum memanggil xrAddTrackableImageDatabaseANDROID -
trackerharus berupa handle XrTrackableTrackerANDROID yang valid -
databaseharus berupa handle XrTrackableImageDatabaseANDROID yang valid -
databasedantrackerharus telah dibuat, dialokasikan, atau diambil dari XrSession yang sama
Kode Status
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Fungsi xrRemoveTrackableImageDatabaseANDROID didefinisikan sebagai:
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Deskripsi Parameter
trackeradalah handle XrTrackableTrackerANDROID untuk menghapusdatabase.databaseadalah pengendali XrTrackableImageDatabaseANDROID yang akan dihapus daritracker.
Saat XrTrackableImageDatabaseANDROID dihapus dari XrTrackableTrackerANDROID , struktur XrTrackableImageDatabaseEntryANDROID dari database tersebut tidak boleh lagi dipertimbangkan untuk deteksi dan pelacakan. Entri apa pun yang dilacak secara aktif dari database tersebut tidak boleh dilaporkan lagi. Handle XrTrackableImageDatabaseANDROID yang dihapus tidak boleh dihancurkan secara implisit sebagai bagian dari operasi ini.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum memanggil xrRemoveTrackableImageDatabaseANDROID -
trackerharus berupa handle XrTrackableTrackerANDROID yang valid -
databaseharus berupa handle XrTrackableImageDatabaseANDROID yang valid -
databasedantrackerharus telah dibuat, dialokasikan, atau diambil dari XrSession yang sama
Kode Status
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Mendapatkan gambar
Fungsi xrGetTrackableImageANDROID didefinisikan sebagai:
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
Deskripsi Parameter
trackeradalah XrTrackableTrackerANDROID yang akan dikueri.getInfoadalah XrTrackableGetInfoANDROID dengan informasi yang digunakan untuk mendapatkan kode QR yang dapat dilacak.trackableadalah pointer ke struktur XrTrackableImageANDROID tempat gambar yang dapat dilacak ditampilkan.
Runtime harus menampilkan XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID jika jenis yang dapat dilacak dari XrTrackableANDROID bukan XR_TRACKABLE_TYPE_IMAGE_ANDROID , atau jika jenis yang dapat dilacak dari XrTrackableTrackerANDROID bukan XR_TRACKABLE_TYPE_IMAGE_ANDROID .
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum memanggil xrGetTrackableImageANDROID -
trackerharus berupa handle XrTrackableTrackerANDROID yang valid -
getInfoharus berupa pointer ke struktur XrTrackableGetInfoANDROID yang valid -
trackableharus berupa pointer ke struktur XrTrackableImageANDROID
Kode Status
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_ERROR_VALIDATION_FAILURE
Struktur XrTrackableImageANDROID didefinisikan sebagai:
typedef struct XrTrackableImageANDROID {
XrStructureType type;
const void* next;
XrTrackingStateANDROID trackingState;
XrTime lastUpdatedTime;
XrTrackableImageDatabaseANDROID database;
uint32_t databaseEntryIndex;
XrPosef centerPose;
XrExtent2Df extents;
} XrTrackableImageANDROID;
Deskripsi Anggota
typeadalah XrStructureType dari struktur ini.nextadalahNULLatau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.trackingStateadalah XrTrackingStateANDROID gambar.lastUpdatedTimeadalahXrTimeupdate terakhir image.databaseadalah handle XrTrackableImageDatabaseANDROID tempat gambar ini dilacak.databaseEntryIndexadalah indeks yang dipetakan ke dalam array XrTrackableImageDatabaseCreateInfoANDROID ::entriesdaridatabase.centerPoseadalah XrPosef gambar yang terletak di XrTrackableGetInfoANDROID ::baseSpace. Gambar terletak di bidang XZ dengan X mengarah ke kanan gambar dan Z mengarah ke bawahnya.extentsadalah dimensi XrExtent2Df gambar. Batas kotak pembatas berada di titik:centerPose+/- (extents/ 2).
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum menggunakan XrTrackableImageANDROID -
typeharus berupaXR_TYPE_TRACKABLE_IMAGE_ANDROID -
nextharus berupaNULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur -
trackingStateharus berupa nilai XrTrackingStateANDROID yang valid -
databaseharus berupa handle XrTrackableImageDatabaseANDROID yang valid
Menangani kegagalan
Aplikasi harus melakukan polling untuk peristiwa XrEventDataImageTrackingLostANDROID menggunakan xrPollEvent dan tidak boleh mengabaikannya.
Struktur XrEventDataImageTrackingLostANDROID didefinisikan sebagai:
typedef struct XrEventDataImageTrackingLostANDROID {
XrStructureType type;
const void* next;
XrTime time;
} XrEventDataImageTrackingLostANDROID;
Deskripsi Anggota
typeadalah XrStructureType dari struktur ini.nextadalahNULLatau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.timeXrTime
Menerima peristiwa XrEventDataImageTrackingLostANDROID menunjukkan bahwa pelacakan gambar mengalami kegagalan internal yang menyebabkan resource yang ada menjadi tidak valid. Aplikasi harus menghancurkan semua handle XrTrackableImageDatabaseANDROID dan membuatnya kembali jika ingin melanjutkan pelacakan gambar. Aplikasi juga harus menghancurkan semua handle XrTrackableTrackerANDROID yang terkait dengan pelacakan gambar dan membuatnya kembali jika ingin melanjutkan pelacakan gambar.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_trackables_imageharus diaktifkan sebelum menggunakan XrEventDataImageTrackingLostANDROID -
typeharus berupaXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID -
nextharus berupaNULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur
Contoh kode untuk mendapatkan gambar yang dapat dilacak
Kode contoh berikut menunjukkan cara mendapatkan gambar yang dapat dilacak.
XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.
XrSystemId systemId; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties; // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT; // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID; // Previously initialized.
XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
// Inspect system capability
XrSystemImageTrackingPropertiesANDROID imageProperty {
.type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
.next = nullptr,
};
XrSystemProperties systemProperties {
.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
// image tracking is not supported.
return;
}
uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.
XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
{
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
.next = nullptr,
.trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
.physicalWidth = 0.1f, // The width of the image in meters.
.imageWidth = 640,
.imageHeight = 480,
.format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
.bufferSize = imageBufferSize, // RGBA buffer size in bytes.
.buffer = imageBuffer, // RGBA data.
}
};
XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
.next = nullptr,
.entryCount = 1,
.entries = imageDatabaseEntries
};
XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));
bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = imageDatabaseFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
futureReady = true;
keepLooping = false;
} else {
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
}
XrTrackableImageDatabaseANDROID imageDatabase;
if (futureReady) {
XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
.type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
.next = nullptr,
};
CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
CHK_XR(imageDatabaseCompletion.futureResult);
imageDatabase = imageDatabaseCompletion.database;
}
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &imageDatabase
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.
// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
while (1) {
uint32_t trackableCountOutput = 0;
CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));
std::vector<XrTrackableANDROID> allImageTrackables;
allImageTrackables.resize(trackableCountOutput);
CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));
for (XrTrackableANDROID trackable : allImageTrackables) {
XrTrackableGetInfoANDROID imageGetInfo {
.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
.next = nullptr,
.trackable = trackable,
.baseSpace = appSpace,
.time = updateTime
};
XrTrackableImageANDROID trackableImage{
.type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
};
CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));
// Use XrTrackableImageANDROID data.
(void)trackableImage.trackingState;
(void)trackableImage.lastUpdatedTime;
(void)trackableImage.centerPose;
(void)trackableImage.extents;
if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
// Knowing which image the index of 0 maps to, use the specific image database
// entry (e.g. rendering A for image A).
}
// indices 1+N comparisons for another specific image database entry.
}
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));
Contoh kode untuk mengelola database gambar saat runtime
Kode contoh berikut menunjukkan cara mengubah kumpulan gambar yang dilacak.
XrSession session; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID; // Previously initialized.
// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.
// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 2,
.databases = imageDatabases
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.
// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &anotherImageDatabase
};
XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &anotherImageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));
// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.
Contoh kode untuk bereaksi terhadap kegagalan pelacakan gambar
Contoh kode berikut menunjukkan cara menangani kegagalan dengan melakukan polling untuk peristiwa XrEventDataImageTrackingLostANDROID.
XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT; // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.
// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
.type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
switch (event.type) {
case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
const XrEventDataImageTrackingLostANDROID& eventdata =
*reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);
// All existing databases and trackers need to be destroyed.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));
// To resume image tracking, the database(s) and the tracker need to be re-created.
XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
.next = nullptr,
.entryCount = 1,
.entries = imageDatabaseEntries
};
XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));
while (true) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = imageDatabaseFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
break;
} else {
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
}
XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
.type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
.next = nullptr,
};
CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
CHK_XR(imageDatabaseCompletion.futureResult);
imageDatabase = imageDatabaseCompletion.database;
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &imageDatabase
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
break;
}
}
}
Jenis Objek Baru
Perintah Baru
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
Struktur Baru
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
Memperluas XrSystemProperties :
Enum Baru
Konstanta Enum Baru
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_ANDROID_trackables_image_SPEC_VERSIONMemperluas XrObjectType :
XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
Memperluas XrResult :
XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
Memperluas XrStructureType :
XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
Memperluas XrTrackableTypeANDROID :
XR_TRACKABLE_TYPE_IMAGE_ANDROID
Masalah
Riwayat Versi
Revisi 1, 08-04-2025 (Daniel Guttenberg)
- Deskripsi ekstensi awal.