XR_ANDROID_depth_texture

String Nama

XR_ANDROID_depth_texture

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

703

Revisi

1

Status Ratifikasi

Belum diratifikasi

Dependensi Ekstensi dan Versi

OpenXR 1.0

Tanggal Terakhir Diubah

2024-09-11

Status IP

Tidak ada klaim kekayaan intelektual yang diketahui.

Kontributor

Sushant Kulkarni, Google
Cairn Overturf, Google
Spencer Quin, Google
Levana Chen, Google

Ringkasan

Ekstensi ini memungkinkan aplikasi meminta peta kedalaman lingkungan dunia nyata di sekitar headset dan mengkueri resolusi kedalaman yang didukung saat pembuatan.

Ekstensi ini dimaksudkan untuk mengekspos kedalaman mentah dan halus untuk oklusi, hit test, dan tugas spesifik lainnya yang memanfaatkan geometri scene yang akurat, misalnya, deteksi wajah palsu.

Catatan

Peta kedalaman dibuat oleh runtime dan dibagikan ke aplikasi menggunakan XrDepthSwapchainANDROID . Runtime tidak boleh mengubah resolusi gambar kedalaman yang ditampilkan melalui xrEnumerateDepthResolutionsANDROID selama masa aktif aplikasi.

Izin

Ekstensi ini mengekspos tekstur kedalaman yang di-downsample untuk mengurangi masalah Informasi Identitas Pribadi (PII). Aplikasi Android harus memiliki izin android.permission.SCENE_UNDERSTANDING_FINE yang tercantum dalam manifesnya karena ekstensi ini mengekspos geometri lingkungan. Izin android.permission.SCENE_UNDERSTANDING_FINE dianggap sebagai izin berbahaya. Aplikasi harus meminta izin saat runtime untuk menggunakan fungsi berikut:

• xrCreateDepthSwapchainANDROID

(tingkat perlindungan: berbahaya)

Memeriksa kemampuan sistem

Struktur XrSystemDepthTrackingPropertiesANDROID didefinisikan sebagai:

typedef struct XrSystemDepthTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsDepthTracking;
} XrSystemDepthTrackingPropertiesANDROID;

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.
• supportsDepthTracking adalah XrBool32 yang menunjukkan apakah sistem saat ini mendukung pelacakan kedalaman.

Aplikasi dapat memeriksa apakah sistem mampu melakukan pelacakan kedalaman dengan memperluas XrSystemProperties dengan struktur XrSystemDepthTrackingPropertiesANDROID saat memanggil xrGetSystemProperties .

Jika dan hanya jika runtime menampilkan XR_FALSE untuk supportsDepthTracking , runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateDepthSwapchainANDROID .

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_depth_texture harus diaktifkan sebelum menggunakan XrSystemDepthTrackingPropertiesANDROID
• type harus berupa XR_TYPE_SYSTEM_DEPTH_TRACKING_PROPERTIES_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Resolusi kedalaman kueri

Fungsi xrEnumerateDepthResolutionsANDROID didefinisikan sebagai:

XrResult xrEnumerateDepthResolutionsANDROID(
    XrSession                                   session,
    uint32_t                                    resolutionCapacityInput,
    uint32_t*                                   resolutionCountOutput,
    XrDepthCameraResolutionANDROID*             resolutions);

Deskripsi Parameter

• session adalah XrSession yang menghitung resolusi kedalaman yang didukung.
• resolutionCapacityInput adalah kapasitas resolutions , atau 0 untuk mengambil kapasitas yang diperlukan.
• resolutionCountOutput adalah pointer ke jumlah uint64_t resolutions yang ditulis, atau pointer ke kapasitas yang diperlukan jika resolutionCapacityInput tidak mencukupi.
• resolutions adalah pointer ke array XrDepthCameraResolutionANDROID , tetapi dapat berupa NULL jika resolutionCapacityInput adalah 0 .
• Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang cara mengambil ukuran resolutions yang diperlukan.

xrEnumerateDepthResolutionsANDROID menghitung resolusi kedalaman yang didukung oleh sesi saat ini. Resolusi kedalaman harus diurutkan dari preferensi runtime tertinggi hingga terendah. Aplikasi harus menggunakan preferensi tertinggi yang didukungnya untuk performa dan kualitas yang optimal.

Runtime harus selalu menampilkan konten buffer yang identik dari enumerasi ini selama masa aktif sesi.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_depth_texture harus diaktifkan sebelum memanggil xrEnumerateDepthResolutionsANDROID
• session harus berupa handle XrSession yang valid
• resolutionCountOutput harus berupa pointer ke nilai uint32_t
• Jika resolutionCapacityInput bukan 0 , resolutions harus berupa pointer ke array nilai resolutionCapacityInput XrDepthCameraResolutionANDROID

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_VALIDATION_FAILURE

Enum XrDepthCameraResolutionANDROID menjelaskan resolusi kedalaman yang didukung saat membuat XrDepthSwapchainANDROID .

typedef enum XrDepthCameraResolutionANDROID {
    XR_DEPTH_CAMERA_RESOLUTION_80x80_ANDROID = 0,
    XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID = 1,
    XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID = 2,
    XR_DEPTH_CAMERA_RESOLUTION_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrDepthCameraResolutionANDROID;

Deskripsi Enumeran

• XR_DEPTH_CAMERA_RESOLUTION_80x80_ANDROID — Resolusi gambar kedalaman dan keyakinan adalah 80x80.
• XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID — Resolusi gambar kedalaman dan keyakinan adalah 160x160.
• XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID — Resolusi gambar kedalaman dan keyakinan adalah 320x320.

Membuat swapchain kedalaman

XR_DEFINE_HANDLE(XrDepthSwapchainANDROID)

XrDepthSwapchainANDROID adalah handle swapchain kedalaman.

Fungsi xrCreateDepthSwapchainANDROID didefinisikan sebagai:

XrResult xrCreateDepthSwapchainANDROID(
    XrSession                                   session,
    const XrDepthSwapchainCreateInfoANDROID*    createInfo,
    XrDepthSwapchainANDROID*                    swapchain);

Deskripsi Parameter

• session adalah XrSession yang membuat swapchain kedalaman.
• createInfo adalah pointer ke struktur XrDepthSwapchainCreateInfoANDROID yang berisi parameter yang akan digunakan untuk membuat swapchain.
• swapchain adalah pointer ke handle tempat XrDepthSwapchainANDROID yang dibuat ditampilkan.

Aplikasi dapat menggunakan fungsi xrCreateDepthSwapchainANDROID untuk membuat swapchain kedalaman yang mengelola gambar kedalaman dan keyakinan.

• Runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED jika sistem tidak mendukung pelacakan kedalaman.
• Runtime harus menampilkan XR_ERROR_PERMISSION_INSUFFICIENT jika izin yang diperlukan belum diberikan ke aplikasi panggilan.
• Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika resolusi kedalaman yang ditentukan dalam XrDepthSwapchainCreateInfoANDROID tidak didukung.
• Runtime seharusnya hanya membuat gambar keyakinan kedalaman saat bit yang sesuai ditetapkan untuk createInfo pada pembuatan swapchain.

Handle swapchain kedalaman yang ditampilkan dapat digunakan selanjutnya dalam panggilan API. Handle XrDepthSwapchainANDROID harus akhirnya dikosongkan melalui fungsi xrDestroyDepthSwapchainANDROID.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_depth_texture harus diaktifkan sebelum memanggil xrCreateDepthSwapchainANDROID
• session harus berupa handle XrSession yang valid
• createInfo harus berupa pointer ke struktur XrDepthSwapchainCreateInfoANDROID yang valid
• swapchain harus berupa pointer ke handle XrDepthSwapchainANDROID

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_PERMISSION_INSUFFICIENT
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST

Struktur XrDepthSwapchainCreateInfoANDROID didefinisikan sebagai:

typedef struct XrDepthSwapchainCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrDepthCameraResolutionANDROID        resolution;
    XrDepthSwapchainCreateFlagsANDROID    createFlags;
} XrDepthSwapchainCreateInfoANDROID;

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.
• resolution adalah XrDepthCameraResolutionANDROID yang digunakan untuk membuat tekstur kedalaman dan keyakinan.
• createFlags adalah satu atau beberapa XrDepthSwapchainCreateFlagsANDROID .

Struktur XrDepthSwapchainCreateInfoANDROID menyediakan opsi pembuatan untuk XrDepthSwapchainANDROID saat diteruskan ke xrCreateDepthSwapchainANDROID .

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_depth_texture harus diaktifkan sebelum menggunakan XrDepthSwapchainCreateInfoANDROID
• type harus berupa XR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• resolution harus berupa nilai XrDepthCameraResolutionANDROID yang valid
• createFlags harus berupa kombinasi nilai XrDepthSwapchainCreateFlagBitsANDROID yang valid
• createFlags tidak boleh berupa 0

XrDepthSwapchainCreateFlagsANDROID menentukan opsi pembuatan untuk XrDepthSwapchainANDROID .

typedef XrFlags64 XrDepthSwapchainCreateFlagsANDROID;

Bit yang valid untuk XrDepthSwapchainCreateFlagsANDROID ditentukan oleh XrDepthSwapchainCreateFlagBitsANDROID , yang ditentukan sebagai:

// Flag bits for XrDepthSwapchainCreateFlagsANDROID
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID = 0x00000001;
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID = 0x00000002;
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID = 0x00000004;
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID = 0x00000008;

Deskripsi Flag

• XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID — Menunjukkan bahwa swapchain akan memberikan gambar kedalaman yang halus.
• XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID — Menunjukkan bahwa swapchain akan memberikan gambar keyakinan kedalaman yang halus.
• XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID — Menunjukkan bahwa swapchain akan memberikan gambar kedalaman mentah.
• XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID — Menunjukkan bahwa swapchain akan memberikan gambar keyakinan kedalaman mentah.

Fungsi xrDestroyDepthSwapchainANDROID didefinisikan sebagai:

XrResult xrDestroyDepthSwapchainANDROID(
    XrDepthSwapchainANDROID                     swapchain);

Deskripsi Parameter

• swapchain adalah handle XrDepthSwapchainANDROID yang sebelumnya dibuat oleh xrCreateDepthSwapchainANDROID .

Fungsi xrDestroyDepthSwapchainANDROID menghancurkan swapchain kedalaman. Setelah panggilan ini, runtime dapat mengosongkan semua memori dan resource terkait.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_depth_texture harus diaktifkan sebelum memanggil xrDestroyDepthSwapchainANDROID
• swapchain harus berupa handle XrDepthSwapchainANDROID yang valid

Keamanan Thread

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

Mengakses tekstur kedalaman

Fungsi xrEnumerateDepthSwapchainImagesANDROID didefinisikan sebagai:

XrResult xrEnumerateDepthSwapchainImagesANDROID(
    XrDepthSwapchainANDROID                     depthSwapchain,
    uint32_t                                    depthImageCapacityInput,
    uint32_t*                                   depthImageCountOutput,
    XrDepthSwapchainImageANDROID*               depthImages);

Deskripsi Parameter

• depthSwapchain adalah XrDepthSwapchainANDROID untuk mendapatkan gambar.
• depthImageCapacityInput adalah kapasitas array depthImages, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
• depthImageCountOutput adalah pointer ke jumlah depthImages yang ditulis, atau pointer ke kapasitas yang diperlukan jika depthImageCapacityInput tidak mencukupi.
• depthImages adalah pointer ke array struktur XrDepthSwapchainImageANDROID. Nilainya bisa NULL jika depthImageCapacityInput adalah 0.
• Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang cara mengambil ukuran depthImages yang diperlukan.

xrEnumerateDepthSwapchainImagesANDROID mengisi array struktur XrDepthSwapchainImageANDROID. Resource harus konstan dan valid selama masa aktif XrDepthSwapchainANDROID . Fungsi ini berperilaku serupa dengan xrEnumerateSwapchainImages .

Runtime harus selalu menampilkan konten buffer yang identik dari enumerasi ini selama masa aktif swapchain.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_depth_texture harus diaktifkan sebelum memanggil xrEnumerateDepthSwapchainImagesANDROID
• depthSwapchain harus berupa handle XrDepthSwapchainANDROID yang valid
• depthImageCountOutput harus berupa pointer ke nilai uint32_t
• Jika depthImageCapacityInput bukan 0 , depthImages harus berupa pointer ke array struktur depthImageCapacityInput XrDepthSwapchainImageANDROID

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_VALIDATION_FAILURE

Struktur XrDepthSwapchainImageANDROID didefinisikan sebagai:

typedef struct XrDepthSwapchainImageANDROID {
    XrStructureType    type;
    void*              next;
    const float*       rawDepthImage;
    const uint8_t*     rawDepthConfidenceImage;
    const float*       smoothDepthImage;
    const uint8_t*     smoothDepthConfidenceImage;
} XrDepthSwapchainImageANDROID;

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.
• rawDepthImage adalah NULL atau pointer ke gambar kedalaman mentah untuk tampilan kiri dan kanan yang dialokasikan oleh runtime. Nilainya memiliki satuan meter. Nilai khusus: 0.0 menunjukkan piksel kedalaman yang tidak valid atau kosong dalam kedalaman mentah, Inf menunjukkan kedalaman yang diketahui yang secara efektif sangat jauh,
• rawDepthConfidenceImage adalah NULL atau pointer ke gambar keyakinan kedalaman mentah untuk tampilan kiri dan kanan yang dialokasikan oleh runtime.
• smoothDepthImage adalah NULL atau pointer ke gambar kedalaman yang dihaluskan untuk tampilan kiri dan kanan yang dialokasikan oleh runtime. Nilainya memiliki satuan meter. Nilai khusus: 0.0 menunjukkan piksel kedalaman yang tidak valid atau kosong dalam kedalaman yang halus, Inf menunjukkan kedalaman yang diketahui dan secara efektif sangat jauh.
• smoothDepthConfidenceImage adalah NULL atau pointer ke gambar keyakinan kedalaman yang dihaluskan untuk tampilan kiri dan kanan yang dialokasikan oleh runtime.

Pointer buffering gambar hanya akan valid selama masa pakai swapchain. Setelah swapchain dihancurkan, pointer akan dianggap menggantung.

XrDepthSwapchainImageANDROID merepresentasikan gambar kedalaman dari XrDepthSwapchainANDROID yang dapat dibaca, yang dialokasikan seperti yang dijelaskan dalam XrDepthSwapchainCreateInfoANDROID :: resolution dan XrDepthSwapchainCreateInfoANDROID :: createFlags saat memanggil xrCreateDepthSwapchainANDROID . Untuk setiap gambar kedalaman:

• Nilai gambar disusun dalam memori dalam urutan baris utama, tanpa padding di antara baris.
• Nilai pertama adalah kiri atas dan nilai terakhir adalah kanan bawah.
• Ukuran memori yang ditunjuk ditentukan oleh nilai xrEnumerateDepthSwapchainImagesANDROID dan ditetapkan oleh XrDepthSwapchainCreateInfoANDROID :: resolution saat memanggil xrCreateDepthSwapchainANDROID . Misalnya, jika XrDepthSwapchainCreateInfoANDROID :: resolution adalah XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID , gambar kedalaman akan memiliki ukuran 2*160*160*sizeof(float) .
• Nilai rawDepthImage harus NULL jika XrDepthSwapchainCreateInfoANDROID :: createFlags tidak menyertakan XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID .
• Nilai rawDepthConfidenceImage harus NULL jika XrDepthSwapchainCreateInfoANDROID :: createFlags tidak menyertakan XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID .
• Nilai smoothDepthImage harus NULL jika XrDepthSwapchainCreateInfoANDROID :: createFlags tidak menyertakan XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID .
• Nilai smoothDepthImage harus NULL jika XrDepthSwapchainCreateInfoANDROID :: createFlags tidak menyertakan XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID .

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_depth_texture harus diaktifkan sebelum menggunakan XrDepthSwapchainImageANDROID
• type harus berupa XR_TYPE_DEPTH_SWAPCHAIN_IMAGE_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Fungsi xrAcquireDepthSwapchainImagesANDROID didefinisikan sebagai:

XrResult xrAcquireDepthSwapchainImagesANDROID(
    XrDepthSwapchainANDROID                     depthSwapchain,
    const XrDepthAcquireInfoANDROID*            acquireInfo,
    XrDepthAcquireResultANDROID*                acquireResult);

Deskripsi Parameter

• depthSwapchain adalah handle XrDepthSwapchainANDROID untuk gambar kedalaman.
• acquireInfo adalah XrDepthAcquireInfoANDROID yang berisi informasi tentang cara memperoleh gambar kedalaman.
• acquireResult adalah XrDepthAcquireResultANDROID yang ditampilkan yang berisi informasi tentang gambar kedalaman yang diperoleh.

Aplikasi dapat menggunakan fungsi xrAcquireDepthSwapchainImagesANDROID untuk memperoleh indeks gambar swapchain terbaru yang tersedia, yaitu XrDepthAcquireResultANDROID :: acquiredIndex , ke dalam array XrDepthSwapchainImageANDROID yang dienumerasi oleh xrEnumerateDepthSwapchainImagesANDROID . XrDepthAcquireResultANDROID yang ditampilkan juga berisi informasi lain seperti ruang pandang dan pose yang diperlukan untuk menafsirkan data kedalaman. Membaca dari slot yang diperoleh dalam array gambar aman dilakukan hingga panggilan berikutnya ke xrAcquireDepthSwapchainImagesANDROID .

Tidak boleh ada lebih dari satu panggilan ke xrAcquireDepthSwapchainImagesANDROID di antara setiap pasangan panggilan xrBeginFrame dan xrEndFrame yang sesuai dalam satu sesi.

• Runtime dapat memblokir jika gambar swapchain yang diperoleh sebelumnya masih digunakan oleh runtime.
• Runtime harus menampilkan XR_ERROR_CALL_ORDER_INVALID jika xrAcquireDepthSwapchainImagesANDROID dipanggil sebelum xrBeginFrame atau setelah xrEndFrame .
• Runtime harus menampilkan XR_ERROR_LIMIT_REACHED jika xrAcquireDepthSwapchainImagesANDROID dipanggil lebih dari sekali per frame - yaitu dalam sesi yang berjalan, setelah panggilan ke xrBeginFrame yang tidak memiliki xrEndFrame terkait.
• Runtime mungkin menampilkan XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID jika data kedalaman lingkungan belum tersedia. Jika hal ini terjadi, aplikasi harus memanggil xrAcquireDepthSwapchainImagesANDROID lagi pada frame berikutnya.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_depth_texture harus diaktifkan sebelum memanggil xrAcquireDepthSwapchainImagesANDROID
• depthSwapchain harus berupa handle XrDepthSwapchainANDROID yang valid
• acquireInfo harus berupa pointer ke struktur XrDepthAcquireInfoANDROID yang valid
• acquireResult harus berupa pointer ke struktur XrDepthAcquireResultANDROID

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• XR_ERROR_CALL_ORDER_INVALID
• XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_TIME_INVALID
• XR_ERROR_VALIDATION_FAILURE

Struktur XrDepthAcquireInfoANDROID didefinisikan sebagai:

typedef struct XrDepthAcquireInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             displayTime;
} XrDepthAcquireInfoANDROID;

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.
• space adalah XrSpace yang menentukan frame referensi pose yang ditampilkan di XrDepthAcquireResultANDROID :: views .
• displayTime adalah XrTime yang menentukan waktu yang digunakan untuk menghitung pose untuk pose yang ditampilkan di XrDepthAcquireResultANDROID :: views . Aplikasi harus meneruskan perkiraan waktu tampilan untuk frame saat ini.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_depth_texture harus diaktifkan sebelum menggunakan XrDepthAcquireInfoANDROID
• type harus berupa XR_TYPE_DEPTH_ACQUIRE_INFO_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• space harus berupa nama sebutan channel XrSpace yang valid

Struktur XrDepthAcquireResultANDROID didefinisikan sebagai:

typedef struct XrDepthAcquireResultANDROID {
    XrStructureType       type;
    const void*           next;
    uint32_t              acquiredIndex;
    XrTime                exposureTimestamp;
    XrDepthViewANDROID    views[2];
} XrDepthAcquireResultANDROID;

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.
• acquiredIndex adalah indeks tekstur yang diperoleh ke dalam array XrDepthSwapchainImageANDROID yang dienumerasi oleh xrEnumerateDepthSwapchainImagesANDROID .
• exposureTimestamp adalah XrTime yang menentukan waktu pengambilan peta kedalaman.
• views adalah array dari dua XrDepthViewANDROID , satu untuk setiap mata, dengan indeks 0 adalah mata kiri dan indeks 1 adalah mata kanan.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_depth_texture harus diaktifkan sebelum menggunakan XrDepthAcquireResultANDROID
• type harus berupa XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• Elemen tertentu dari views harus berupa struktur XrDepthViewANDROID yang valid

Struktur XrDepthViewANDROID didefinisikan sebagai:

typedef struct XrDepthViewANDROID {
    XrStructureType    type;
    const void*        next;
    XrFovf             fov;
    XrPosef            pose;
} XrDepthViewANDROID;

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.
• fov adalah XrFovf yang menentukan ruang pandang yang digunakan untuk membuat tampilan ini. Tampilan tidak pernah dibalik secara horizontal atau vertikal.
• pose adalah XrPosef yang menentukan pose tempat peta kedalaman dirender. Frame referensi ditentukan dalam XrDepthAcquireInfoANDROID .

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_depth_texture harus diaktifkan sebelum menggunakan XrDepthViewANDROID
• type harus berupa XR_TYPE_DEPTH_VIEW_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Contoh kode untuk pelacakan kedalaman

Kode contoh berikut menunjukkan cara memperoleh gambar kedalaman dan menggunakan nilai kedalaman untuk memetakan koordinat gambar kedalaman ke ruang panggung.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session; // previously initialized
XrSpace stageSpace; // space created for XR_REFERENCE_SPACE_TYPE_STAGE.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateDepthSwapchainANDROID xrCreateDepthSwapchainANDROID; // previously initialized
PFN_xrDestroyDepthSwapchainANDROID xrDestroyDepthSwapchainANDROID; // previously initialized
PFN_xrEnumerateDepthSwapchainImagesANDROID xrEnumerateDepthSwapchainImagesANDROID; // previously initialized
PFN_xrEnumerateDepthResolutionsANDROID xrEnumerateDepthResolutionsANDROID; // previously initialized
PFN_xrAcquireDepthSwapchainImagesANDROID xrAcquireDepthSwapchainImagesANDROID; // previously initialized

float tanf(float);

// Inspect system capability
XrSystemProperties properties{XR_TYPE_SYSTEM_PROPERTIES};
XrSystemDepthTrackingPropertiesANDROID depthTrackingProperties{XR_TYPE_SYSTEM_DEPTH_TRACKING_PROPERTIES_ANDROID};
properties.next = &depthTrackingProperties;
CHK_XR(xrGetSystemProperties(instance, systemId, &properties));
if (!depthTrackingProperties.supportsDepthTracking) {
  // depth tracking is not supported.
  return;
}

// Query the supported depth resolution.
XrDepthCameraResolutionANDROID supportedDepthResolution;
uint32_t supportedResolutionCount = 0;
CHK_XR(xrEnumerateDepthResolutionsANDROID(
    session, 1, &supportedResolutionCount, &supportedDepthResolution));

// Define metadata to access the raw and smooth depth along with confidences.
XrDepthSwapchainCreateInfoANDROID swapchainCreateInfo = {
  .type = XR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROID,
  .next = nullptr,
  // Use the resolution supported by the runtime.
  .resolution = supportedDepthResolution,
  .createFlags =
    XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID |
    XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID |
    XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID |
    XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID,
};

XrDepthSwapchainANDROID depthSwapchain;
CHK_XR(xrCreateDepthSwapchainANDROID(
    session, &swapchainCreateInfo, &depthSwapchain));

// Enumerate depth images.
uint32_t imageCountOutput = 0;
CHK_XR(xrEnumerateDepthSwapchainImagesANDROID(
    depthSwapchain, 0, &imageCountOutput, nullptr));
std::vector<XrDepthSwapchainImageANDROID> depthImages(imageCountOutput);
for (int i = 0; i < imageCountOutput; i++) {
  depthImages[i].type = XR_TYPE_DEPTH_SWAPCHAIN_IMAGE_ANDROID;
}
CHK_XR(xrEnumerateDepthSwapchainImagesANDROID(
  depthSwapchain, imageCountOutput, &imageCountOutput, depthImages.data()));

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

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

    XrDepthAcquireInfoANDROID acquireInfo = {
        .type = XR_TYPE_DEPTH_ACQUIRE_INFO_ANDROID,
        .space = stageSpace,
        .displayTime = time
    };
    XrDepthAcquireResultANDROID acquireResult = {
        .type = XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID,
    };
    CHK_XR(xrAcquireDepthSwapchainImagesANDROID(
        depthSwapchain, &acquireInfo, &acquireResult));

    // Each value in a depth image corresponds to a point in the real world.
    // The sample code below shows how to find the stageSpace position of
    // the point corresponding to a particular value in the depth image.

    // For this sample code, assume we are using a right handed coordinate system
    // with +X to the right, +Y up and -Z forward.

    XrDepthSwapchainImageANDROID *image =
        &depthImages[acquireResult.acquiredIndex];

    // Assume supported resolution is XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID.
    const int imageResolution = 160;
    int imageY = 80; // value in [0, imageResolution)
    int imageX = 80; // value in [0, imageResolution)

    // Get depth value from left eye.
    // A right depth value is obtained with the following expression:
    // depthR = image->rawDepthImage[imageResolution*imageResolution+i*imageResolution+j]
    float depthL = image->rawDepthImage[imageY*imageResolution + imageX];
    XrDepthViewANDROID viewL = acquireResult.views[0];

    float tanL = tanf(viewL.fov.angleLeft);
    float tanR = tanf(viewL.fov.angleRight);
    float tanU = tanf(viewL.fov.angleUp);
    float tanD = tanf(viewL.fov.angleDown);

    float s = (imageX + 0.5f) / (float)imageResolution;
    float t = (imageY + 0.5f) / (float)imageResolution;

    // Calculate the depth camera space position of the point
    // corresponding to this depth value.
    XrVector3f posInCameraSpace;
    posInCameraSpace.z = -depthL;
    posInCameraSpace.x = (tanL + (tanR - tanL)*s)*depthL;
    posInCameraSpace.y = (tanD + (tanU - tanD)*t)*depthL;

    XrPosef depthCameraPoseL = viewL.pose;
    // Transform posInCameraSpace by depthCameraPoseL

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

Jenis Objek Baru

• XrDepthSwapchainANDROID

Perintah Baru

• xrAcquireDepthSwapchainImagesANDROID
• xrCreateDepthSwapchainANDROID
• xrDestroyDepthSwapchainANDROID
• xrEnumerateDepthResolutionsANDROID
• xrEnumerateDepthSwapchainImagesANDROID

Struktur Baru

• XrDepthAcquireInfoANDROID
• XrDepthAcquireResultANDROID
• XrDepthSwapchainCreateInfoANDROID
• XrDepthSwapchainImageANDROID
• XrDepthViewANDROID

• Memperluas XrSystemProperties :

  • XrSystemDepthTrackingPropertiesANDROID

Enum Baru

• XrDepthCameraResolutionANDROID
• XrDepthSwapchainCreateFlagBitsANDROID

Bitmask Baru

• XrDepthSwapchainCreateFlagsANDROID

Konstanta Enum Baru

• XR_ANDROID_DEPTH_TEXTURE_EXTENSION_NAME
• XR_ANDROID_depth_texture_SPEC_VERSION

• Memperluas XrObjectType :

  • XR_OBJECT_TYPE_DEPTH_SWAPCHAIN_ANDROID

• Memperluas XrResult :

  • XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID

• Memperluas XrStructureType :

  • XR_TYPE_DEPTH_ACQUIRE_INFO_ANDROID
  • XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID
  • XR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROID
  • XR_TYPE_DEPTH_SWAPCHAIN_IMAGE_ANDROID
  • XR_TYPE_DEPTH_VIEW_ANDROID
  • XR_TYPE_SYSTEM_DEPTH_TRACKING_PROPERTIES_ANDROID

Masalah

Riwayat Versi

• Revisi 1, 09-09-2024 (Levana Chen)

  • Deskripsi ekstensi awal