XR_ANDROID_spatial_annotation_tracking

String Nama

XR_ANDROID_spatial_annotation_tracking

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

795

Revisi

1

Status Ratifikasi

Tidak diratifikasi

Dependensi Ekstensi dan Versi

XR_EXT_spatial_entity
dan
XR_EXT_spatial_image_tracking

Tanggal Terakhir Diubah

2026-01-12

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

Levana Chen, Google
Christopher Feil, Google
Martin Sundermeyer, Google
David Joseph Tan, Google
Jared Finder, Google
Nihav Jain, Google

Ringkasan

Ekstensi ini menyediakan kemampuan pelacakan anotasi untuk ekstensi XR_EXT_spatial_entity guna melacak berbagai anotasi dalam adegan. Hal ini memungkinkan aplikasi menempatkan overlay pada objek fisik atau virtual yang ditentukan oleh referensi runtime.

Ekstensi ini menyediakan jenis anotasi dasar "Quad", yaitu poligon yang memiliki tepat 4 sisi, yaitu segi empat cembung, yang merepresentasikan kotak pembatas 2D umum dalam referensi runtime. Anotasi quad yang dilacak direpresentasikan sebagai entitas spasial dengan (atau "yang memiliki") komponen berikut:

• XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Aplikasi dapat menggunakan ekstensi pelacakan anotasi spasial dalam pola berikut:

• Aplikasi pertama-tama membuat handle XrSpatialReferenceCacheANDROID yang mulai merekam referensi runtime dari sumber yang diberikan.
• Kemudian, aplikasi akan mengambil referensi runtime XrSpatialReferenceImageEXT dan menentukan anotasi yang diinginkan dalam referensi selama rentang waktu cache referensi.
• Aplikasi kemudian membuat handle XrSpatialContextEXT berdasarkan XrSpatialReferenceImageEXT yang diberikan oleh XrSpatialCapabilityConfigurationAnnotationTrackingANDROID .
• Aplikasi dapat menghancurkan handle XrSpatialReferenceCacheANDROID untuk menghentikan perekaman referensi runtime guna mengurangi penggunaan memori, atau menunggu peristiwa XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID untuk mengonfirmasi hasil inisialisasi.
• Kemudian, aplikasi menarik peristiwa XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID untuk mengonfirmasi hasil inisialisasi anotasi.
• Jika inisialisasi berhasil, aplikasi dapat menarik peristiwa XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT untuk melacak anotasi.
• Jika inisialisasi gagal, aplikasi dapat menggunakan kode error yang ditampilkan dalam peristiwa untuk menentukan alasan kegagalan, dan menghancurkan handle XrSpatialContextEXT yang ada untuk memulai anotasi baru.
• Terlepas dari hasil inisialisasi, aplikasi dapat melepaskan buffer gambar untuk mengurangi penggunaan memori setelah menerima peristiwa.
• Aplikasi menemukan dan membuat kueri anotasi sesuai dengan pola akses entity spasial.
• Aplikasi dapat membuat handle XrSpatialContextEXT tambahan untuk melacak anotasi dalam referensi baru selama rentang waktu XrSpatialReferenceCacheANDROID yang valid .
• Aplikasi dapat menghancurkan handle XrSpatialContextEXT untuk mengurangi set anotasi yang dapat dideteksi dan dilacak secara dinamis saat runtime.

Dukungan Runtime

Runtime harus mengiklankan dukungannya untuk kemampuan pelacakan anotasi menggunakan xrEnumerateSpatialCapabilitiesEXT dengan mencantumkan kemampuan berikut:

• XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Saat runtime mendukung kemampuan pelacakan anotasi:

• Fitur ini harus mendukung setidaknya satu komponen anotasi, dengan mencantumkan komponen anotasi yang didukung melalui xrEnumerateSpatialCapabilityComponentTypesEXT .
• Perangkat harus mendukung setidaknya salah satu dari XrSpatialReferenceImageFormatEXT , dengan mencantumkan format referensi yang didukung melalui xrEnumerateSpatialReferenceImageFormatsEXT dengan setelan capability ke XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .
• Harus mendukung setidaknya salah satu dari XrSpatialAnnotationReferenceSourceANDROID , dengan mencantumkan sumber referensi yang didukung melalui xrEnumerateSpatialAnnotationReferenceSourcesANDROID dengan setelan capability ke XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID.

Fungsi xrEnumerateSpatialAnnotationReferenceSourcesANDROID ditentukan sebagai:

XrResult xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    sourceCapacityInput,
    uint32_t*                                   sourceCountOutput,
    XrSpatialAnnotationReferenceSourceANDROID*  sources);

Deskripsi Parameter

• instance adalah tuas untuk XrInstance .
• systemId adalah XrSystemId yang sumber referensinya akan dihitung.
• capability adalah XrSpatialCapabilityEXT yang sumber referensinya akan dihitung.
• sourceCapacityInput adalah kapasitas array sources, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
• sourceCountOutput adalah jumlah sumber, atau kapasitas yang diperlukan jika sourceCapacityInput tidak mencukupi.
• sources adalah array XrSpatialAnnotationReferenceSourceANDROID . Nilainya dapat berupa NULL jika sourceCapacityInput adalah 0.
• Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran sources yang diperlukan.

Aplikasi dapat menghitung daftar sumber referensi yang didukung oleh XrSystemId tertentu menggunakan xrEnumerateSpatialAnnotationReferenceSourcesANDROID .

Runtime tidak boleh menghitung sumber referensi yang ekstensinya tidak diaktifkan untuk instance .

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum memanggil xrEnumerateSpatialAnnotationReferenceSourcesANDROID
• instance harus berupa handle XrInstance yang valid
• capability must berupa nilai XrSpatialCapabilityEXT yang valid
• sourceCountOutput harus berupa pointer ke nilai uint32_t
• Jika sourceCapacityInput bukan 0 , sources harus berupa pointer ke array nilai XrSpatialAnnotationReferenceSourceANDROID sourceCapacityInput

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

typedef enum XrSpatialAnnotationReferenceSourceANDROID {
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationReferenceSourceANDROID;

Enumerasi XrSpatialAnnotationReferenceSourceANDROID menjelaskan sumber referensi yang menyediakan metadata untuk anotasi.

Enum memiliki arti berikut:

Deskripsi Enum

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID

Gambar referensi adalah output gambar yang tidak dipangkas dari Android Camera API, misalnya, Gambar dari ImageReader yang terkait dengan CameraDevice Camera2 atau ImageProxy dari ImageAnalysis yang terkait dengan CameraX. Biasanya, ini adalah salah satu kamera RGB yang menghadap ke depan.

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID

Gambar referensi adalah output gambar yang tidak dipangkas dari Android MediaProjection API, misalnya, Gambar dari ImageReader yang terkait dengan tampilan virtual MediaProjection. Konten ini dapat mencakup konten virtual dan nyata.

Struktur XrSystemSpatialAnnotationPropertiesANDROID ditentukan sebagai:

typedef struct XrSystemSpatialAnnotationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           referenceCacheTimespan;
    uint32_t           maxReferencePixelWidth;
    uint32_t           maxReferencePixelHeight;
    uint32_t           maxReferenceCount;
    uint32_t           maxAnnotationCount;
} XrSystemSpatialAnnotationPropertiesANDROID;

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
• referenceCacheTimespan menunjukkan rentang waktu dalam detik dari handle XrSpatialReferenceCacheANDROID yang valid.
• maxReferencePixelWidth menunjukkan lebar maksimum tepi gambar referensi dalam piksel.
• maxReferencePixelHeight menunjukkan tinggi maksimum tepi gambar referensi dalam piksel.
• maxReferenceCount menunjukkan jumlah maksimum gambar referensi yang akan dialokasikan secara bersamaan.
• maxAnnotationCount menunjukkan jumlah maksimum anotasi yang akan dilacak secara bersamaan.

Jika runtime mendukung kemampuan pelacakan anotasi, aplikasi dapat memeriksa properti sistem yang relevan dengan menggabungkan struktur XrSystemSpatialAnnotationPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties .

Jika XrSpatialReferenceImageEXT :: width dari XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference melebihi maxReferencePixelWidth , runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE saat memanggil xrCreateSpatialContextAsyncEXT .

Jika XrSpatialReferenceImageEXT :: height dari XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference melebihi maxReferencePixelHeight , runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE saat memanggil xrCreateSpatialContextAsyncEXT .

Jika XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: time berada di luar rentang waktu XrSpatialReferenceCacheANDROID :: cache , runtime harus menampilkan XR_ERROR_TIME_INVALID saat memanggil xrCreateSpatialContextAsyncEXT . Aplikasi dapat membuat ulang handle XrSpatialContextEXT dengan referensi baru selama rentang waktu XrSpatialReferenceCacheANDROID .

Jika jumlah gambar referensi yang dialokasikan melebihi maxReferenceCount , runtime harus menampilkan XR_ERROR_LIMIT_REACHED dan menunjukkan kegagalan inisialisasi melalui XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult . Aplikasi dapat menghancurkan handle XrSpatialContextEXT dan mencoba lagi setelah inisialisasi yang tertunda selesai.

Jika jumlah anotasi aktif melebihi maxAnnotationCount , runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE saat memanggil xrCreateSpatialContextAsyncEXT .

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum menggunakan XrSystemSpatialAnnotationPropertiesANDROID
• type harus XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Cache referensi runtime

XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)

Handle XrSpatialReferenceCacheANDROID merepresentasikan cache referensi runtime yang direkam dari sumber tertentu.

Fungsi xrCreateSpatialReferenceCacheAsyncANDROID ditentukan sebagai:

XrResult xrCreateSpatialReferenceCacheAsyncANDROID(
    XrSession                                   session,
    const XrSpatialReferenceCacheCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

Deskripsi Parameter

• session adalah XrSession tempat cache referensi akan aktif.
• createInfo adalah pointer ke XrSpatialReferenceCacheCreateInfoANDROID yang digunakan untuk menentukan parameter cache referensi.
• future adalah pointer ke handle output XrFutureEXT .

Aplikasi dapat membuat handle XrSpatialReferenceCacheANDROID dengan memanggil xrCreateSpatialReferenceCacheAsyncANDROID . Runtime mungkin memerlukan waktu beberapa saat untuk menginisialisasi layanan pelacakan. Aplikasi dapat memanggil xrCreateSpatialReferenceCacheCompleteANDROID berulang kali untuk memeriksa penyelesaian operasi asinkron ini.

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT jika XrSpatialReferenceCacheCreateInfoANDROID :: capability tidak tercantum oleh xrEnumerateSpatialCapabilitiesEXT .

Runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED jika XrSpatialReferenceCacheCreateInfoANDROID :: source tidak tercantum oleh xrEnumerateSpatialAnnotationReferenceSourcesANDROID untuk kemampuan tertentu.

Aplikasi hanya dapat membuat satu handle per sumber untuk kemampuan tertentu. Jika tidak, runtime harus menampilkan XR_ERROR_LIMIT_REACHED .

Aplikasi dapat merekam referensi runtime selama rentang waktu handle XrSpatialReferenceCacheANDROID untuk mengonfigurasi handle XrSpatialContextEXT baru.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum memanggil xrCreateSpatialReferenceCacheAsyncANDROID
• session harus berupa handle XrSession yang valid
• createInfo harus berupa pointer ke struktur XrSpatialReferenceCacheCreateInfoANDROID yang valid
• future harus berupa pointer ke nilai XrFutureEXT

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• XR_ERROR_FEATURE_UNSUPPORTED
• 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_CAPABILITY_UNSUPPORTED_EXT
• XR_ERROR_VALIDATION_FAILURE

Struktur XrSpatialReferenceCacheCreateInfoANDROID ditentukan sebagai:

typedef struct XrSpatialReferenceCacheCreateInfoANDROID {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialCapabilityEXT                       capability;
    XrSpatialAnnotationReferenceSourceANDROID    source;
} XrSpatialReferenceCacheCreateInfoANDROID;

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.
• capability adalah XrSpatialCapabilityEXT yang menjelaskan kemampuan mana yang dibuat cache referensinya.
• source adalah XrSpatialAnnotationReferenceSourceANDROID yang menjelaskan sumber cache referensi.

Struktur XrSpatialReferenceCacheCreateInfoANDROID menjelaskan informasi untuk membuat handle XrSpatialReferenceCacheANDROID.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum menggunakan XrSpatialReferenceCacheCreateInfoANDROID
• type harus XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• capability must berupa nilai XrSpatialCapabilityEXT yang valid
• source must berupa nilai XrSpatialAnnotationReferenceSourceANDROID yang valid

Fungsi xrCreateSpatialReferenceCacheCompleteANDROID ditentukan sebagai:

XrResult xrCreateSpatialReferenceCacheCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialReferenceCacheCompletionANDROID* completion);

Deskripsi Parameter

• session adalah XrSession yang sebelumnya diteruskan ke xrCreateSpatialReferenceCacheAsyncANDROID :: session .
• future adalah XrFutureEXT yang diterima dari xrCreateSpatialReferenceCacheAsyncANDROID :: future .
• completion adalah pointer ke XrCreateSpatialReferenceCacheCompletionANDROID .

Aplikasi dapat memanggil xrCreateSpatialReferenceCacheCompleteANDROID untuk menunggu penyelesaian operasi asinkron yang dimulai oleh xrCreateSpatialReferenceCacheAsyncANDROID .

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)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum memanggil xrCreateSpatialReferenceCacheCompleteANDROID
• session harus berupa handle XrSession yang valid
• completion harus berupa pointer ke struktur XrCreateSpatialReferenceCacheCompletionANDROID

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• XR_ERROR_FEATURE_UNSUPPORTED
• 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 XrCreateSpatialReferenceCacheCompletionANDROID ditentukan sebagai:

typedef struct XrCreateSpatialReferenceCacheCompletionANDROID {
    XrStructureType                   type;
    void*                             next;
    XrResult                          futureResult;
    XrSpatialReferenceCacheANDROID    referenceCache;
} XrCreateSpatialReferenceCacheCompletionANDROID;

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.
• futureResult adalah XrResult dari operasi pembuatan cache referensi.
• referenceCache adalah handle XrSpatialReferenceCacheANDROID jika operasi berhasil.

Kode Pengembalian pada Masa Mendatang

Nilai futureResult:

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• XR_ERROR_FEATURE_UNSUPPORTED
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_LIMIT_REACHED

Jika futureResult adalah kode keberhasilan, runtime harus menampilkan handle referenceCache yang valid. Jika valid, referenceCache tetap valid hanya dalam masa aktif xrCreateSpatialReferenceCacheAsyncANDROID :: session atau hingga aplikasi menghancurkan handle dengan xrDestroySpatialReferenceCacheANDROID, mana saja yang lebih dulu.

Jika referenceCache valid, ia mencatat cache dalam XrSystemSpatialAnnotationPropertiesANDROID :: referenceCacheTimespan .

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum menggunakan XrCreateSpatialReferenceCacheCompletionANDROID
• type harus XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• futureResult harus berupa nilai XrResult yang valid
• referenceCache harus berupa handle XrSpatialReferenceCacheANDROID yang valid

Fungsi xrDestroySpatialReferenceCacheANDROID ditentukan sebagai:

XrResult xrDestroySpatialReferenceCacheANDROID(
    XrSpatialReferenceCacheANDROID              cacheHandle);

Deskripsi Parameter

• cacheHandle adalah XrSpatialReferenceCacheANDROID yang sebelumnya dibuat oleh xrCreateSpatialReferenceCacheAsyncANDROID .

Aplikasi dapat memanggil fungsi xrDestroySpatialReferenceCacheANDROID untuk melepaskan handle cacheHandle dan resource yang mendasarinya setelah selesai membuat konteks spasial.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum memanggil xrDestroySpatialReferenceCacheANDROID
• cacheHandle harus berupa handle XrSpatialReferenceCacheANDROID yang valid

Keamanan Thread

• Akses ke cacheHandle , dan semua handle turunannya, harus disinkronkan secara eksternal

Kode Status

Berhasil

• XR_SUCCESS

Kegagalan

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

Konfigurasi

Struktur XrSpatialCapabilityConfigurationAnnotationTrackingANDROID ditentukan sebagai:

typedef struct XrSpatialCapabilityConfigurationAnnotationTrackingANDROID {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialReferenceCacheANDROID      cache;
    XrTime                              time;
    XrSpatialReferenceImageEXT          reference;
} XrSpatialCapabilityConfigurationAnnotationTrackingANDROID;

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_ANNOTATION_TRACKING_ANDROID .
• enabledComponentCount adalah uint32_t yang menjelaskan jumlah elemen dalam array enabledComponents.
• enabledComponents adalah pointer ke array XrSpatialComponentTypeEXT .
• cache adalah XrSpatialReferenceCacheANDROID yang sebelumnya dibuat untuk merekam referensi runtime untuk konfigurasi reference.
• time adalah XrTime tempat reference diambil.
• reference adalah XrSpatialReferenceImageEXT dengan anotasi yang dirantai ke penunjuk berikutnya.

Aplikasi dapat mengaktifkan kemampuan spasial XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID dengan menambahkan penunjuk ke struktur XrSpatialCapabilityConfigurationAnnotationTrackingANDROID di XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika capability bukan XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT jika reference tidak berisi anotasi.

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT jika komponen anotasi tercantum dalam enabledComponents, tetapi tidak ada anotasi yang sesuai yang terkait dengan reference .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika cache tidak dimiliki oleh XrSession yang sama yang diteruskan ke xrCreateSpatialContextAsyncEXT .

Runtime harus menampilkan XR_ERROR_TIME_INVALID jika time berada di luar rentang waktu cache .

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum menggunakan XrSpatialCapabilityConfigurationAnnotationTrackingANDROID
• type harus XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• capability must berupa nilai XrSpatialCapabilityEXT yang valid
• enabledComponents harus berupa pointer ke array nilai enabledComponentCount XrSpatialComponentTypeEXT yang valid
• cache harus berupa handle XrSpatialReferenceCacheANDROID yang valid
• reference harus berupa struktur XrSpatialReferenceImageEXT yang valid
• Parameter enabledComponentCount harus lebih besar dari 0

Peristiwa Pelacakan Anotasi

Struktur XrEventDataSpatialAnnotationTrackingANDROID ditentukan sebagai:

typedef struct XrEventDataSpatialAnnotationTrackingANDROID {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
    uint32_t               annotationIndex;
    XrResult               initializationResult;
} XrEventDataSpatialAnnotationTrackingANDROID;

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
• spatialContext adalah XrSpatialContextEXT yang telah mengaktifkan pelacakan anotasi.
• annotationIndex memetakan ke indeks dari array anotasi yang terkait dengan XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference .
• initializationResult menunjukkan hasil inisialisasi anotasi. Jika tidak XR_SUCCESS , aplikasi dapat menghancurkan dan membuat ulang handle XrSpatialContextEXT untuk menginisialisasi ulang anotasi, atau terus menggunakan spatialContext untuk melacak anotasi lainnya.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum menggunakan XrEventDataSpatialAnnotationTrackingANDROID
• type harus XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Runtime harus mengisi XrEventDataSpatialAnnotationTrackingANDROID untuk setiap anotasi guna menunjukkan penyelesaian inisialisasinya. Terlepas dari hasil inisialisasi, aplikasi dapat melepaskan buffer gambar untuk mengurangi penggunaan memori setelah menerima peristiwa.

Runtime harus mengisi initializationResult dengan XR_SUCCESS jika anotasi berhasil diinisialisasi. Aplikasi dapat menarik peristiwa XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT untuk melacak anotasi.

Jika tidak, runtime harus mengisi initializationResult dengan kode error yang sesuai untuk menunjukkan alasan kegagalan. Aplikasi dapat menghancurkan handle XrSpatialContextEXT untuk memulai anotasi baru atau terus menggunakan spatialContext untuk melacak anotasi lainnya.

Anotasi Empat Bagian

Runtime harus mengiklankan dukungan untuk anotasi empat sisi menggunakan xrEnumerateSpatialCapabilityComponentTypesEXT dengan mencantumkan jenis komponen berikut:

• XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Referensi Quad

Struktur XrSpatialAnnotationQuadReferenceANDROID ditentukan sebagai:

typedef struct XrSpatialAnnotationQuadReferenceANDROID {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 quadCount;
    const XrSpatialAnnotationQuadANDROID*    quads;
} XrSpatialAnnotationQuadReferenceANDROID;

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
• quadCount adalah uint32_t yang menjelaskan jumlah elemen dalam array quads.
• quads adalah pointer ke array XrSpatialAnnotationQuadANDROID .

Jika runtime mendukung anotasi quad, aplikasi dapat mengonfigurasi anotasi dengan menggabungkan struktur XrSpatialAnnotationQuadReferenceANDROID ke XrSpatialReferenceImageEXT :: next , dan menetapkan referensi di XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference saat membuat handle XrSpatialContextEXT.

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT dari xrCreateSpatialContextAsyncEXT jika quadCount adalah 0.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum menggunakan XrSpatialAnnotationQuadReferenceANDROID
• type harus XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• quads harus berupa pointer ke array struktur XrSpatialAnnotationQuadANDROID yang valid quadCount
• Parameter quadCount harus lebih besar dari 0

Struktur XrSpatialAnnotationQuadANDROID ditentukan sebagai:

typedef struct XrSpatialAnnotationQuadANDROID {
    XrSpatialAnnotationQuadAlignmentANDROID    alignment;
    XrVector2f                                 upperLeft;
    XrVector2f                                 upperRight;
    XrVector2f                                 lowerRight;
    XrVector2f                                 lowerLeft;
} XrSpatialAnnotationQuadANDROID;

Deskripsi Anggota

• alignment adalah XrSpatialAnnotationQuadAlignmentANDROID dari quad.
• upperLeft adalah XrVector2f yang menjelaskan koordinat sudut kiri atas quad yang terkait dengan asal.
• upperRight adalah XrVector2f yang menjelaskan koordinat sudut kanan atas quad yang terkait dengan asal.
• lowerRight adalah XrVector2f yang menjelaskan koordinat sudut kanan bawah quad yang terkait dengan asal.
• lowerLeft adalah XrVector2f yang mendeskripsikan koordinat sudut kiri bawah quad yang terkait dengan asal.

Quad dalam ruang 2D adalah segi empat cembung dengan urutan searah jarum jam. Nilai 4 sudut terkait dengan asal (0, 0) tempat quad dikaitkan.

• Jika dikaitkan dengan XrSpatialReferenceImageEXT , asal adalah sudut kiri atas gambar tempat X dipetakan ke piksel pada lebar dan Y dipetakan ke piksel pada tinggi.
• Jika dikaitkan dengan XrSpatialAnnotationQuadDataANDROID , asal ditunjukkan oleh XrSpaceLocationData :: pose dari XrSpatialAnnotationQuadDataANDROID :: origin .

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum menggunakan XrSpatialAnnotationQuadANDROID
• alignment harus berupa nilai XrSpatialAnnotationQuadAlignmentANDROID yang valid

typedef enum XrSpatialAnnotationQuadAlignmentANDROID {
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationQuadAlignmentANDROID;

Enumerasi XrSpatialAnnotationQuadAlignmentANDROID menjelaskan perataan anotasi quad.

Enum memiliki arti berikut:

Deskripsi Enum

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID

Quad anotasi sejajar dengan bidang layar, sementara rotasi dalam bidangnya tetap terkunci ke gravitasi dunia. Output muncul sebagai kotak pembatas tegak biasa.

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID

Quad anotasi ditambatkan langsung ke objek, yang cocok dengan perataan yang ditentukan dalam gambar referensi. Outputnya adalah segi empat cembung, yang menyesuaikan bentuknya agar sesuai dengan perspektif objek.

Komponen Quad

Struktur XrSpatialAnnotationQuadDataANDROID ditentukan sebagai:

typedef struct XrSpatialAnnotationQuadDataANDROID {
    uint32_t                          annotationIndex;
    XrSpaceLocationData               origin;
    XrSpatialAnnotationQuadANDROID    quad;
} XrSpatialAnnotationQuadDataANDROID;

Deskripsi Anggota

• annotationIndex adalah pemetaan indeks ke array XrSpatialAnnotationQuadReferenceANDROID :: quads yang terkait dengan referensi yang diteruskan oleh XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference .
• origin adalah XrSpaceLocationData yang menjelaskan asal bidang 2D tempat quad berakar. Runtime harus menyetel XrSpaceLocationData :: locationFlags untuk menunjukkan bit pose asal yang valid.
• quad adalah XrSpatialAnnotationQuadANDROID yang merepresentasikan quad dalam ruang lokal. Gunakan origin untuk mengubah quad ke ruang pose.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum menggunakan XrSpatialAnnotationQuadDataANDROID
• origin harus berupa struktur XrSpaceLocationData yang valid
• quad harus berupa struktur XrSpatialAnnotationQuadANDROID yang valid

Struktur XrSpatialComponentAnnotationQuadListANDROID ditentukan sebagai:

typedef struct XrSpatialComponentAnnotationQuadListANDROID {
    XrStructureType                        type;
    void*                                  next;
    uint32_t                               quadCount;
    XrSpatialAnnotationQuadDataANDROID*    quads;
} XrSpatialComponentAnnotationQuadListANDROID;

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
• quadCount adalah uint32_t yang menjelaskan jumlah elemen dalam array quads.
• quads adalah array XrSpatialAnnotationQuadDataANDROID .

Aplikasi dapat mengkueri komponen anotasi quad entitas spasial dalam XrSpatialSnapshotEXT dengan menambahkan XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID di XrSpatialComponentDataQueryConditionEXT :: componentTypes dan menambahkan XrSpatialComponentAnnotationQuadListANDROID ke rantai penunjuk berikutnya dari XrSpatialComponentDataQueryResultEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrQuerySpatialComponentDataEXT jika XrSpatialComponentAnnotationQuadListANDROID ada di rantai XrSpatialComponentDataQueryResultEXT berikutnya :: next, tetapi XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID tidak disertakan dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_spatial_annotation_tracking harus diaktifkan sebelum menggunakan XrSpatialComponentAnnotationQuadListANDROID
• type harus XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• quads harus berupa pointer ke array struktur quadCount XrSpatialAnnotationQuadDataANDROID
• Parameter quadCount harus lebih besar dari 0

Kode Contoh

Memeriksa dukungan runtime

Contoh kode berikut menunjukkan cara memeriksa apakah runtime mendukung kemampuan pelacakan anotasi.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrEnumerateSpatialCapabilitiesEXT xrEnumerateSpatialCapabilitiesEXT;
PFN_xrEnumerateSpatialAnnotationReferenceSourcesANDROID xrEnumerateSpatialAnnotationReferenceSourcesANDROID;
PFN_xrEnumerateSpatialReferenceImageFormatsEXT xrEnumerateSpatialReferenceImageFormatsEXT;
PFN_xrEnumerateSpatialCapabilityComponentTypesEXT xrEnumerateSpatialCapabilityComponentTypesEXT;

// Check spatial annotation tracking capability
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0,
                                         &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount,
                                         &capabilityCount,
                                         capabilities.data()));
if (std::find(capabilities.begin(), capabilities.end(),
              XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID) ==
    capabilities.end()) {
  // System does not support spatial annotation tracking.
  return;
}

// Inspect system properties for annotation tracking variables
XrSystemSpatialAnnotationPropertiesANDROID annotationSystemProperties{
    XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{.type = XR_TYPE_SYSTEM_PROPERTIES,
                                    .next = &annotationSystemProperties,
                                    .systemId = systemId};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (annotationSystemProperties.maxAnnotationCount == 0) {
  // System does not support any active annotations.
  return;
}

// Enumerate supported reference sources
uint32_t sourceCountOutput = 0;
XrSpatialAnnotationReferenceSourceANDROID desiredSource =
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID;
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    0, &sourceCountOutput, nullptr));
std::vector<XrSpatialAnnotationReferenceSourceANDROID> sources(sourceCountOutput);
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    sourceCountOutput, &sourceCountOutput, sources.data()));
if (std::find(sources.begin(), sources.end(), desiredSource) == sources.end()) {
  // The desired source is not supported.
  return;
}

// Enumerate supported reference image formats, provided by XR_EXT_spatial_image_tracking.
uint32_t formatCountOutput = 0;
XrSpatialReferenceImageFormatEXT desiredFormat =
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT; // Or XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT for screenshot.
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID, 0,
    &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    formats.size(), &formatCountOutput, formats.data()));
if (std::find(formats.begin(), formats.end(), desiredFormat) == formats.end()) {
  // The desired format is not supported
  return;
}

// Enumerate supported components for annotation tracking capability.
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes{
    XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));
std::vector<XrSpatialComponentTypeEXT>
    annotationTypes(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = annotationTypes.size();
capabilityComponentTypes.componentTypes = annotationTypes.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));

// Check supported annotation components.
XrSpatialComponentTypeEXT desiredComponent =
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID;
const auto supportedComponent = [&annotationTypes](
                                    XrSpatialComponentTypeEXT component) {
  return std::find(annotationTypes.begin(), annotationTypes.end(), component) !=
         annotationTypes.end();
};
if (!supportedComponent(desiredComponent)) {
  // The desired annotation is not supported.
  return;
}

Mengonfigurasi anotasi empat sisi

Contoh kode berikut menunjukkan cara mengonfigurasi anotasi empat sisi.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrCreateSpatialReferenceCacheAsyncANDROID xrCreateSpatialReferenceCacheAsyncANDROID;
PFN_xrCreateSpatialReferenceCacheCompleteANDROID xrCreateSpatialReferenceCacheCompleteANDROID;
PFN_xrDestroySpatialReferenceCacheANDROID xrDestroySpatialReferenceCacheANDROID;
PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialReferenceImageFormatEXT desiredFormat;
XrSpatialAnnotationReferenceSourceANDROID desiredSource;
XrSpatialComponentTypeEXT desiredComponent;

// Create and start reference cache to prepare for capturing reference images.
XrSpatialReferenceCacheANDROID referenceCache;
XrSpatialReferenceCacheCreateInfoANDROID cacheCreateInfo{
  .type = XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
  .source = desiredSource,
};
XrFutureEXT cacheFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialReferenceCacheAsyncANDROID(session, &cacheCreateInfo, &cacheFuture));

waitUntilReady(cacheFuture);

XrCreateSpatialReferenceCacheCompletionANDROID cacheCompletion{
    XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID};
CHK_XR(xrCreateSpatialReferenceCacheCompleteANDROID(session, cacheFuture,
                                                     &cacheCompletion));
if (cacheCompletion.futureResult != XR_SUCCESS) {
  // Error, reference cache creation failed
  return;
}

referenceCache = cacheCompletion.referenceCache;

// Create the reference image with quad annotations

//  YUV 4:2:0 Planar:
// ----------------------
// |     Y      |Cb |Cr |
// ----------------------
XrSpatialReferenceImagePlaneEXT cameraImagePlanes[3];
// for each plane (0=Y, 1=U(cb), 2=V(Cr)) return by Image#getPlanes().
for (int i = 0; i < 3; ++i) {
  cameraImagePlanes[i].buffer; // read from Plane#getBuffer().
  cameraImagePlanes[i].bufferSize; // set each buffer size. Y = width * height (bytes); U = Y / 4 (bytes); V = Y / 4 (bytes).
  cameraImagePlanes[i].rowStride; // read from Plane#getRowStride().
  cameraImagePlanes[i].pixelStride; // read from Plane#getPixelStride().
}
XrSpatialReferenceImageEXT referenceImage{
      XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
referenceImage.width = 640;
referenceImage.height = 480;
referenceImage.format = desiredFormat;
referenceImage.planeCount = 3;
referenceImage.planes = cameraImagePlanes;

XrSpatialAnnotationQuadANDROID
    quad; // quad coordinates within the reference image.
quad.alignment = XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID;
// Set unnormalized pixel coordinates of 4 corners.
quad.upperLeft = {0.0, 0.0};
quad.upperRight = {0.0, 100.0};
quad.lowerRight = {100.0, 100.0};
quad.lowerLeft = {0.0, 100.0};

XrSpatialAnnotationQuadReferenceANDROID quadReference{
    XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID};
quadReference.quads = &quad;
quadReference.quadCount = 1;
referenceImage.next = &quadReference;

// Create the spatial context with annotation configuration.
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
      desiredComponent,
  };

  // Configure annotation tracking
  XrSpatialCapabilityConfigurationAnnotationTrackingANDROID annotationConfig{
      XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID};
  annotationConfig.capability =
      XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID;
  annotationConfig.enabledComponentCount = enabledComponents.size();
  annotationConfig.enabledComponents = enabledComponents.data();
  annotationConfig.cache = referenceCache;
  annotationConfig.time; // The time when this reference image is captured.
  annotationConfig.reference = referenceImage;

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

  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
    return;
  }

  spatialContext = completion.spatialContext;
  CHK_XR(xrDestroySpatialReferenceCacheANDROID(referenceCache));
}

Menemukan anotasi aktif

Contoh kode berikut menunjukkan cara menemukan dan membuat kueri anotasi.

XrInstance instance;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL
XrSpatialContextEXT spatialContext; // previously created

PFN_xrCreateSpatialDiscoverySnapshotAsyncEXT xrCreateSpatialDiscoverySnapshotAsyncEXT;
PFN_xrCreateSpatialDiscoverySnapshotCompleteEXT xrCreateSpatialDiscoverySnapshotCompleteEXT;
PFN_xrQuerySpatialComponentDataEXT xrQuerySpatialComponentDataEXT;
PFN_xrDestroySpatialSnapshotEXT xrDestroySpatialSnapshotEXT;
PFN_xrPollEvent xrPollEvent;
PFN_xrDestroySpatialContextEXT xrDestroySpatialContextEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialComponentTypeEXT desiredComponent; // e.g. XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

auto discoverAnnotations = [&](XrSpatialContextEXT spatialContext, XrTime time,
                               XrSpace baseSpace) {
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{desiredComponent};
  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 = baseSpace;
  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 desired annotation data, e.g. quad.
    XrSpatialComponentTypeEXT componentsToQuery[] = {
        XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID};
    XrSpatialComponentDataQueryConditionEXT queryCond{
        XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = 1;
    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<XrSpatialAnnotationQuadDataANDROID> quads(
        queryResult.entityIdCountOutput);
    XrSpatialComponentAnnotationQuadListANDROID quadList{
        XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID};
    quadList.quadCount = quads.size();
    quadList.quads = quads.data();
    queryResult.next = &quadList;

    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 XrSpatialAnnotationQuadDataANDROID &currentQuad = quads[i];
        // Rendering quad in the view.
      }
    }

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

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

  XrSpace space;           // Application's play space.
  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_ANNOTATION_TRACKING_ANDROID: {
      const XrEventDataSpatialAnnotationTrackingANDROID &eventdata =
          *reinterpret_cast<XrEventDataSpatialAnnotationTrackingANDROID *>(
              &event);
      if (eventdata.initializationResult != XR_SUCCESS) {
        // handle initialization failure.
        // e.g. CHK_XR(xrDestroySpatialContextEXT(spatialContext));
      }
      break;
    }
    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, space);
      break;
    }
    }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Jenis Objek Baru

• XrSpatialReferenceCacheANDROID

Perintah Baru

• xrCreateSpatialReferenceCacheAsyncANDROID
• xrCreateSpatialReferenceCacheCompleteANDROID
• xrDestroySpatialReferenceCacheANDROID
• xrEnumerateSpatialAnnotationReferenceSourcesANDROID

Struktur Baru

• XrCreateSpatialReferenceCacheCompletionANDROID
• XrEventDataSpatialAnnotationTrackingANDROID
• XrSpatialAnnotationQuadANDROID
• XrSpatialAnnotationQuadDataANDROID
• XrSpatialCapabilityConfigurationAnnotationTrackingANDROID
• XrSpatialReferenceCacheCreateInfoANDROID

• Memperluas XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentAnnotationQuadListANDROID

• Memperluas XrSpatialReferenceImageEXT :

  • XrSpatialAnnotationQuadReferenceANDROID

• Memperluas XrSystemProperties :

  • XrSystemSpatialAnnotationPropertiesANDROID

Enum Baru

• XrSpatialAnnotationQuadAlignmentANDROID
• XrSpatialAnnotationReferenceSourceANDROID

Konstanta Enum Baru

• XR_ANDROID_SPATIAL_ANNOTATION_TRACKING_EXTENSION_NAME
• XR_ANDROID_spatial_annotation_tracking_SPEC_VERSION

• Memperluas XrObjectType :

  • XR_OBJECT_TYPE_SPATIAL_REFERENCE_CACHE_ANDROID

• Memperluas XrSpatialCapabilityEXT :

  • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

• Memperluas XrSpatialComponentTypeEXT :

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

• Memperluas XrStructureType :

  • XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID
  • XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID
  • XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID
  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID
  • XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID
  • XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID
  • XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID

Masalah

Histori Versi

• Revisi 1, 17-09-2025 (Levana Chen)

  • Deskripsi ekstensi awal.