XR_EXT_spatial_container

String Nama

XR_EXT_spatial_container

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

811

Revisi

1

Status Ratifikasi

Belum diratifikasi

Dependensi Ekstensi dan Versi

OpenXR 1.0

Tanggal Terakhir Diubah

2026-08-06

Status IP

Tidak ada klaim kekayaan intelektual yang diketahui.

Kontributor

Jared Finder, Google
Andreas Loeve Selvik, Meta Platforms
Lachlan Ford, Google
Cass Everitt, Meta Platforms
Adam Gousetis, Meta Platforms
Ankur Agrawal, Unity Technologies
Bjorn Swenson, LÖVR
Denny Rönngren, Varjo Technologies
Fredia Huya-Kouadio, Godot Engine
Guodong Rong, Meta Platforms
Jakob Bornecrantz, NVIDIA
Jian Zhang, ByteDance
John Kearney, Meta Platforms
Jonathan Wright, Meta Platforms
Junfeng She, ByteDance
Kenny Vercaemer, Google
Kurtis Eveleigh, Qualcomm
Mauricio Narvaez, Meta Platforms
Nathan Nuber, Valve Corporation
Nihav Jain, Google
Nikita Lutsenko, Meta Platforms
Praveen Babu J D, ByteDance
Rylie Pavlik, Collabora
Salar Khan, Google
Shuai Liu, ByteDance
Walter Luh, Meta Platforms
Yin Li, Microsoft
Zhipeng Liu, ByteDance

Ringkasan

Ekstensi ini menentukan class baru entity yang dapat ditampilkan, yang disebut "penampung spasial" yang serupa dengan konsep "jendela" dalam sistem windowing 2D desktop.

Di OpenXR 1.x, aplikasi memiliki kontrol eksklusif atas semua yang dilihat pengguna dan cara hal tersebut dipadukan di atas lingkungan nyata atau virtual pengguna. Runtime hanya melakukan sedikit modifikasi pada apa yang ditampilkan untuk memastikan keamanan pengguna. Model aplikasi ini cocok untuk memberikan pengalaman tunggal yang imersif kepada pengguna, tetapi tidak dapat diperluas ke beberapa pengalaman simultan. Khususnya, di lingkungan AR dan mixed reality, pengguna sering kali ingin menikmati beberapa aplikasi berbeda secara bersamaan.

Penampung spasial seperti jendela yang diperluas ke 3D. Pengguna dapat melihat beberapa penampung spasial secara bersamaan dan memberikan input ke sebagian penampung tersebut. Penampung spasial yang terlihat dapat dimiliki oleh berbagai aplikasi dan runtime mengelola ukuran dan penempatannya atas nama pengguna.

Ekstensi ini mendukung jenis pengalaman baru yang dibatasi secara spasial selain pengalaman OpenXR imersif yang sudah ada. Pengalaman OpenXR Terbatas diizinkan memiliki konten yang sedikit 3D (panel datar dengan sedikit offset kedalaman) atau volume yang menghosting konten sepenuhnya 3D. Pengalaman OpenXR imersif adalah aplikasi imersif layar penuh yang sudah ada dan telah didukung sejak OpenXR 1.0. Aplikasi dapat beralih di antara dua jenis konten jika aplikasi memilih untuk melakukannya.

Ekstensi ini tidak menentukan metode apa pun bagi aplikasi untuk merender kontennya. Cara menggambar konten ditentukan dalam ekstensi lain: XR_EXT_spatial_container_self_rendering .

Menggunakan container spasial

XrSpatialContainerEXT adalah handle yang mewakili penampung spasial.

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

Aplikasi mulai merender melalui penampung spasial dengan langkah-langkah berikut:

  1. Buat penampung spasial dengan xrCreateSpatialContainerEXT .
  2. Ubah status apa pun pada penampung untuk presentasi awal, seperti mode batasnya.
  3. Minta runtime menampilkan penampung dengan xrRequestSpatialContainerVisibleEXT .
  4. Tunggu hingga runtime siap menampilkan container. Saat runtime siap, runtime akan mengantrekan peristiwa XrEventDataSpatialContainerVisibleChangedEXT dengan visible ditetapkan ke XR_TRUE .
  5. Mulai rendering untuk penampung spasial.

Dan penghancuran container spasial adalah sebagai berikut:

  1. Minta runtime menyembunyikan penampung dengan xrRequestSpatialContainerVisibleEXT .
  2. Tunggu hingga runtime selesai menyembunyikan penampung. Setelah runtime menyembunyikan penampung sepenuhnya, runtime akan mengantrekan peristiwa XrEventDataSpatialContainerVisibleChangedEXT dengan visible ditetapkan ke XR_FALSE .
  3. Mengakhiri rendering untuk penampung spasial.
  4. Hancurkan container dengan xrDestroySpatialContainerEXT .

Catatan

Secara desain, ekstensi ini mendelegasikan visibilitas dan pengelolaan fokus ke setiap penampung spasial. Karena sesi secara keseluruhan tidak lagi mewakili satu objek yang terlihat atau difokuskan, sesi tidak bertransisi melalui mesin status OpenXR standar (READY, SYNCHRONIZED, VISIBLE, FOCUSED). Sebagai gantinya, sesi tetap berada di XR_SESSION_STATE_IDLE selama masa aktifnya, dan aturan di Perubahan pada status sesi menentukan cara operasi OpenXR inti dipetakan ke mode ini.

Membuat penampung spasial

Fungsi xrCreateSpatialContainerEXT membuat penampung spasial baru.

XrResult xrCreateSpatialContainerEXT(
    XrSession                                   session,
    const XrSpatialContainerCreateInfoEXT*      createInfo,
    XrSpatialContainerEXT*                      spatialContainer);

Deskripsi Parameter

XrSpatialContainerEXT yang baru dibuat harus tidak terlihat, tidak dapat berinteraksi, dan dalam mode batas XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT . Aplikasi yang ingin memulai penampung spasial dalam mode imersif dapat meminta mode batas XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT sebelum meminta untuk menampilkan penampung spasial.

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika dimensi XrSpatialContainerCreateInfoEXT :: suggestedBounds negatif, tak terbatas, atau bukan angka. Runtime harus menampilkan XR_ERROR_LIMIT_REACHED jika aplikasi mencoba membuat lebih banyak penampung spasial daripada yang ditentukan dalam XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount . Jika penampung spasial tidak diaktifkan untuk sesi ini , runtime harus menampilkan XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT .

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerCreateInfoEXT diteruskan ke xrCreateSpatialContainerEXT untuk membuat penampung spasial.

typedef struct XrSpatialContainerCreateInfoEXT {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialContainerGraphicsPresentationEXT    graphicsPresentation;
    XrExtent3Df                                  suggestedBounds;
} XrSpatialContainerCreateInfoEXT;

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.
  • graphicsPresentation adalah XrSpatialContainerGraphicsPresentationEXT yang menjelaskan cara penampung spasial ini menampilkan grafik.
  • suggestedBounds adalah XrExtent3Df yang menjelaskan dimensi yang diminta dari penampung spasial dalam meter.

Aplikasi yang tidak memiliki preferensi untuk ukurannya dapat menetapkan suggestedBounds ke {0, 0, 0}. Runtime dapat mengabaikan suggestedBounds yang diminta.

Runtime yang memungkinkan penampung spasial dibatasi oleh bentuk selain kotak berorientasi harus menggunakan suggestedBounds sebagai kotak pembatas di sekitar bentuk lainnya. Kotak berorientasi dimaksudkan untuk menjadi bentuk pembatas yang paling umum.

Penggunaan yang Valid (Implisit)

Jika penampung spasial tidak dapat digunakan lagi, runtime harus mengantrekan peristiwa XrEventDataSpatialContainerClosedEXT.

typedef struct XrEventDataSpatialContainerClosedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerClosedEXT;

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.
  • spatialContainer adalah XrSpatialContainerEXT yang menjadi tujuan peristiwa ini.

Menerima peristiwa XrEventDataSpatialContainerClosedEXT menunjukkan bahwa runtime tidak lagi dapat menampilkan penampung spasial, misalnya karena pengguna mengklik tombol "tutup" atau sesi memasuki status XR_SESSION_STATE_LOSS_PENDING.

Setelah menerima peristiwa XrEventDataSpatialContainerClosedEXT, aplikasi harus berhenti menggunakan penampung spasial tersebut, menghapus status terkait seperti loop render, dan menghancurkan penampung. Runtime harus menampilkan XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT dari semua fungsi yang beroperasi pada penampung tersebut selain xrDestroySpatialContainerEXT .

Jika penampung spasial terlihat saat runtime mengantrekan peristiwa penutupan, runtime harus terlebih dahulu mengubah penampung menjadi tidak terlihat dan mengantrekan peristiwa XrEventDataSpatialContainerVisibleChangedEXT.

Penggunaan yang Valid (Implisit)

Fungsi xrDestroySpatialContainerEXT menghancurkan penampung spasial yang ada.

XrResult xrDestroySpatialContainerEXT(
    XrSpatialContainerEXT                       spatialContainer);

Deskripsi Parameter

Setelah penampung spasial dihancurkan, runtime tidak boleh menampilkan konten penampung lagi dan tidak boleh mengantrekan peristiwa tambahan apa pun tentang penampung.

Aplikasi tidak boleh menghancurkan penampung spasial yang terlihat karena tindakan tersebut dapat menyebabkan artefak grafis. Sebagai gantinya, aplikasi harus meminta untuk menyembunyikan penampung spasial dengan xrRequestSpatialContainerVisibleEXT , menunggu peristiwa XrEventDataSpatialContainerVisibleChangedEXT, lalu menghancurkan penampung.

Penggunaan yang Valid (Implisit)

Keamanan Thread

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

Ruang penampung spasial

Fungsi xrCreateSpatialContainerSpaceEXT membuat handle XrSpace untuk ruang penampung spasial dari penampung spasial tertentu.

XrResult xrCreateSpatialContainerSpaceEXT(
    XrSession                                   session,
    const XrSpatialContainerSpaceCreateInfoEXT* createInfo,
    XrSpace*                                    space);

Deskripsi Parameter

"Ruang penampung spasial" untuk penampung spasial tertentu adalah sistem koordinat dengan titik pusat di tengah batas penampung spasial tersebut. Ruang ini biasanya digunakan sebagai ruang dasar untuk fungsi seperti xrLocateSpace .

+X mengarah ke sisi kanan penampung, +Y mengarah ke sisi atas penampung, dan +Z mengarah ke sisi depan penampung. Misalnya, jika penampung sejajar dengan gravitasi, berada di depan penampil, dan penampil berada pada pose identitas relatif terhadap ruang LOCAL , runtime harus mengorientasikan ruang penampung dengan orientasi identitas relatif terhadap ruang LOCAL . Runtime dapat menetapkan pose ruang penampung relatif terhadap ruang LOCAL ke pose arbitrer apa pun saat penampung tersebut terlihat.

konvensi ruang container spasial eksternal

Gambar 18. Konvensi sumbu ruang penampung spasial

Ruang penampung spasial adalah origin yang tidak dikunci ke dunia. Aplikasi yang menginginkan origin terkunci dunia saat dalam mode imersif dapat menggunakan ruang terkunci dunia seperti XR_REFERENCE_SPACE_TYPE_LOCAL .

Runtime dapat mengubah pose ruang penampung spasial kapan saja, biasanya untuk mendukung pengguna memindahkan penampung spasial ke posisi atau rotasi yang berbeda. Runtime juga dapat mengubah pose saat bertransisi antara mode batas XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT dan XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT.

Ruang penampung spasial harus terus menjadi handle yang valid meskipun penampung spasial yang dimaksud dihancurkan dengan xrDestroySpatialContainerEXT . Meskipun penampung spasial tidak terlihat atau dihancurkan, ruang penampung spasial harus tidak dapat ditemukan relatif terhadap ruang lain. XrSpaceLocation :: locationFlags dan XrViewState ::viewStateFlags akan bernilai 0.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerSpaceCreateInfoEXT digunakan dengan xrCreateSpatialContainerSpaceEXT untuk membuat handle XrSpace.

typedef struct XrSpatialContainerSpaceCreateInfoEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrSpatialContainerSpaceCreateInfoEXT;

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.
  • spatialContainer adalah XrSpatialContainerEXT yang akan dibuatkan ruang.

Penggunaan yang Valid (Implisit)

Menampilkan penampung spasial

Pengiriman konten penampung spasial ke OpenXR untuk ditampilkan ditangani oleh ekstensi lain: XR_EXT_spatial_container_self_rendering .

Untuk mengizinkan ekstensi lain menentukan metode presentasi grafis untuk penampung spasial, ekstensi ini menentukan enum XrSpatialContainerGraphicsPresentationEXT.

typedef enum XrSpatialContainerGraphicsPresentationEXT {
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT = 1000813000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT = 1000814000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1 = 1000815000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerGraphicsPresentationEXT;

Deskripsi Enum

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

Penampung spasial menggunakan lapisan komposisi OpenXR (Ditambahkan oleh ekstensi XR_EXT_spatial_container_self_rendering)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT

Penampung spasial dibuat untuk pengujian kesesuaian dan tidak memiliki jalur rendering (Ditambahkan oleh ekstensi XR_EXT_spatial_container_conformance_automation)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1

Penampung spasial menggunakan rendering sistem OpenXR (Ditambahkan oleh ekstensi XR_EXTX1_system_renderer)

Status penampung spasial

Status penampung spasial dikelola oleh runtime berdasarkan permintaan aplikasi dan kebutuhan pengguna. Oleh karena itu, setiap aspek status penampung spasial mendokumentasikan hal-hal berikut:

  • Saat runtime diizinkan untuk mengubah status penampung spasial. Untuk sebagian besar status penampung spasial, runtime dapat mengubah status kapan saja.
  • Cara aplikasi meminta perubahan pada status. Runtime dapat menunda permintaan apa pun hingga runtime menganggap permintaan tersebut sesuai. Runtime tidak mengantrekan peristiwa saat permintaan ditangguhkan, sehingga aplikasi sebaiknya tidak menunggu peristiwa tersebut untuk logika yang tidak terkait.
  • Runtime peristiwa yang diantrekan saat status penampung spasial berubah. Runtime mengantrekan peristiwa untuk semua perubahan, termasuk perubahan yang diminta aplikasi dan perubahan yang dimulai runtime. Runtime tidak boleh mengantrekan peristiwa perubahan status yang tidak menunjukkan perubahan, seperti jika aplikasi membuat dua permintaan untuk menyembunyikan penampung secara berurutan.
  • Runtime peristiwa yang diantrekan saat menolak permintaan perubahan aplikasi. Runtime dapat menolak permintaan karena alasan apa pun, biasanya karena kebijakan sistem yang terkait dengan mempertahankan pengalaman pengguna yang berkualitas tinggi.

Fungsi xrGetSpatialContainerStateEXT mengkueri status penampung spasial saat ini.

XrResult xrGetSpatialContainerStateEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerStateGetInfoEXT*    getInfo,
    XrSpatialContainerStateEXT*                 state);

Deskripsi Parameter

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerStateGetInfoEXT digunakan dengan xrGetSpatialContainerStateEXT untuk mengkueri XrSpatialContainerStateEXT .

typedef struct XrSpatialContainerStateGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerStateGetInfoEXT;

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.

Penggunaan yang Valid (Implisit)

typedef struct XrSpatialContainerStateEXT {
    XrStructureType                    type;
    void*                              next;
    XrBool32                           visible;
    XrBool32                           interactable;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerStateEXT;

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.
  • visible menunjukkan apakah penampung spasial terlihat.
  • interactable menunjukkan apakah penampung spasial saat ini dapat menerima jenis input apa pun. Hal ini mirip dengan "fokus" untuk sistem windowing 2D desktop, dengan perbedaan bahwa beberapa penampung spasial mungkin dapat berinteraksi sekaligus.
  • boundsMode adalah XrSpatialContainerBoundsModeEXT saat ini dari penampung spasial.

Perubahan pada status penampung spasial dikomunikasikan melalui peristiwa.

Peristiwa Kolom Diubah

visible

XrEventDataSpatialContainerVisibleChangedEXT

interactable

XrEventDataSpatialContainerInteractableChangedEXT

boundsMode

XrEventDataSpatialContainerBoundsChangedEXT

Penggunaan yang Valid (Implisit)

Visibilitas

Aplikasi meminta untuk menampilkan atau menyembunyikan penampung spasial dengan xrRequestSpatialContainerVisibleEXT .

XrResult xrRequestSpatialContainerVisibleEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerVisibleRequestInfoEXT* info);

Deskripsi Parameter

Menampilkan atau menyembunyikan penampung spasial adalah operasi asinkron.

Aplikasi harus meminta untuk menyembunyikan penampung spasial sebelum menghancurkannya, sehingga runtime dapat menampilkan transisi yang lancar. Runtime harus memenuhi permintaan untuk menyembunyikan penampung spasial.

Runtime dapat menolak permintaan untuk menampilkan penampung spasial, dalam hal ini runtime harus mengantrekan peristiwa XrEventDataSpatialContainerVisibleRequestDeniedEXT. Misalnya, beberapa runtime akan menolak permintaan untuk menampilkan penampung spasial yang disembunyikan pengguna dengan berinteraksi dengan tombol "minimalkan" yang disediakan sistem.

Runtime tidak boleh menampilkan penampung spasial sebelum aplikasi meminta untuk menampilkan penampung spasial tersebut setidaknya sekali. Setelah permintaan pertama aplikasi untuk menampilkan penampung spasial, runtime dapat mengubah visibilitas penampung spasial tersebut, terlepas dari permintaan aplikasi. Hal ini memungkinkan aplikasi mengontrol status awal dan konten penampung spasial serta memungkinkan runtime menyediakan UI sistem seperti taskbar yang memungkinkan pengguna memilih penampung spasial yang terlihat.

Runtime harus menolak permintaan untuk menampilkan penampung spasial dalam mode batas yang tidak didukung berdasarkan XrSystemSpatialContainerPropertiesEXT :: supportsBounded dan XrSystemSpatialContainerPropertiesEXT :: supportsImmersive . Hal ini dapat terjadi jika mode batas default, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT , tidak didukung untuk sistem tertentu.

Catatan

Pada beberapa implementasi, menampilkan atau menyembunyikan penampung spasial memerlukan komunikasi dengan layanan sistem dan mungkin ditangguhkan hingga setelah pengguna berinteraksi dengan dialog sistem. Desain asinkron untuk meminta perubahan status visibilitas dimaksudkan untuk memberi runtime waktu untuk menyelesaikan kedua operasi ini.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerVisibleRequestInfoEXT digunakan dengan xrRequestSpatialContainerVisibleEXT untuk mengubah visibilitas penampung spasial.

typedef struct XrSpatialContainerVisibleRequestInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           visible;
} XrSpatialContainerVisibleRequestInfoEXT;

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.
  • visible menunjukkan apakah penampung spasial diminta untuk ditampilkan atau disembunyikan.

Penggunaan yang Valid (Implisit)

Setiap kali runtime mengubah visibilitas penampung spasial, runtime harus mengantrekan peristiwa XrEventDataSpatialContainerVisibleChangedEXT dengan status baru.

typedef struct XrEventDataSpatialContainerVisibleChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 visible;
} XrEventDataSpatialContainerVisibleChangedEXT;

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.
  • spatialContainer adalah XrSpatialContainerEXT yang menjadi tujuan peristiwa ini.
  • visible adalah status terlihat baru untuk penampung spasial.

Peristiwa ini menggantikan XR_SESSION_STATE_VISIBLE , sehingga nilainya dapat berbeda per penampung. Peristiwa harus dimasukkan ke dalam antrean untuk semua perubahan, termasuk perubahan yang diminta aplikasi dan perubahan yang dimulai runtime.

Runtime dapat menunda rendering penampung selama beberapa frame setelah mengantrekan peristiwa ini dengan visible yang ditetapkan ke XR_TRUE untuk menghindari penayangan penampung kosong dan memberikan waktu kepada aplikasi untuk mengirimkan konten awalnya. Selama waktu ini, XrSpatialContainerStateEXT ::visible akan menjadi XR_TRUE . Runtime tidak boleh menunda rendering penampung selama lebih dari 0,5 detik.

Penggunaan yang Valid (Implisit)

Setiap kali runtime menolak permintaan untuk menampilkan penampung, runtime harus mengantrekan peristiwa XrEventDataSpatialContainerVisibleRequestDeniedEXT.

typedef struct XrEventDataSpatialContainerVisibleRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerVisibleRequestDeniedEXT;

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.
  • spatialContainer adalah XrSpatialContainerEXT yang menjadi tujuan peristiwa ini.

Penggunaan yang Valid (Implisit)

Dapat berinteraksi

Aplikasi tidak dapat meminta penampung spasial agar dapat berinteraksi. Container spasial yang dapat berinteraksi sepenuhnya dikontrol oleh runtime. Penampung spasial yang dapat berinteraksi harus juga terlihat.

Setiap kali runtime mengubah status interaktif penampung spasial, runtime harus mengantrekan peristiwa XrEventDataSpatialContainerInteractableChangedEXT dengan status baru.

typedef struct XrEventDataSpatialContainerInteractableChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 interactable;
} XrEventDataSpatialContainerInteractableChangedEXT;

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.
  • spatialContainer adalah XrSpatialContainerEXT yang menjadi tujuan peristiwa ini.
  • interactable adalah status baru yang dapat berinteraksi untuk penampung spasial.

Peristiwa ini menggantikan XR_SESSION_STATE_FOCUSED , sehingga nilainya dapat berbeda per penampung. Peristiwa ini diantrekan untuk semua perubahan, termasuk perubahan yang dimulai runtime.

Runtime dapat mengaktifkan atau menonaktifkan interaksi dengan penampung spasial kapan saja. Jika runtime hanya mendukung maksimal satu penampung spasial yang dapat berinteraksi pada satu waktu, saat runtime mengubah penampung spasial yang dapat berinteraksi, runtime harus mengantrekan peristiwa untuk penampung spasial yang berhenti dapat berinteraksi ( interactable ditetapkan ke false) sebelum peristiwa untuk penampung yang mulai dapat berinteraksi ( interactable ditetapkan ke true).

Penggunaan yang Valid (Implisit)

Batas

Penampung spasial memiliki mode batas dan kotak pembatas. Mode batas penampung spasial menjelaskan perilaku batas. Kotak pembatasnya adalah tempat container spasial digambar.

Enumerasi XrSpatialContainerBoundsModeEXT mengidentifikasi berbagai mode yang dapat digunakan untuk batas penampung spasial.

typedef enum XrSpatialContainerBoundsModeEXT {
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT = 1,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT = 2,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerBoundsModeEXT;

Deskripsi Enum

XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT

Penampung spasial dibatasi. Batasnya adalah kotak terbatas. Penampung spasial hanya akan muncul di region ini.

XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT

Penampung spasial bersifat imersif dan memiliki batas tak terbatas. Penampung spasial ditampilkan di seluruh layar.

Penampung spasial yang berada dalam mode batas XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT memiliki persyaratan tambahan:

  • Runtime harus memperlakukan penampung spasial ini sama seperti aplikasi layar penuh dan imersif yang dibuat tanpa penggunaan penampung spasial, kecuali untuk perubahan perilaku yang disebutkan dalam Perubahan pada status sesi .
  • Runtime dapat menyediakan ekstensi tambahan yang memungkinkan container spasial imersif berperilaku berbeda dari aplikasi layar penuh dan imersif yang dibuat tanpa ekstensi ini.
  • Runtime harus melaporkan batas tak terbatas untuk penampung spasial ini.
  • Runtime dapat menyembunyikan penampung spasial lainnya saat penampung spasial imersif terlihat. Karena hal ini mungkin berbeda per runtime, aplikasi sebaiknya tidak mengandalkan penampung spasial yang otomatis ditampilkan atau disembunyikan berdasarkan visibilitas penampung spasial imersif. Seperti semua transisi status terlihat lainnya, runtime harus mengantrekan peristiwa XrEventDataSpatialContainerVisibleChangedEXT saat penampung spasial disembunyikan karena penampung imersif terlihat.

Catatan

Persyaratan di atas menyiratkan bahwa semua runtime dapat mengimplementasikan jalur OpenXR 1.x tanpa ekstensi ini dengan membuat penampung spasial secara implisit, menetapkan mode batas penampung ke imersif, dan memintanya agar terlihat.

Aplikasi meminta untuk mengubah mode batas penampung spasial dengan xrRequestSpatialContainerBoundsModeEXT .

XrResult xrRequestSpatialContainerBoundsModeEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsModeRequestInfoEXT* info);

Deskripsi Parameter

Mengubah mode batas penampung spasial adalah operasi asinkron dan runtime dapat mengantrekan peristiwa yang diubah atau ditolak beberapa detik setelah aplikasi meminta perubahan. Hal ini memungkinkan runtime memunculkan UI yang diperlukan agar pengguna dapat memasuki mode imersif dengan aman.

Runtime harus memenuhi permintaan untuk mengubah mode batas penampung spasial yang tidak terlihat. Jika runtime menolak permintaan mode batas untuk penampung yang tidak terlihat, runtime dapat menolak atau menunda permintaan untuk menampilkan penampung spasial tersebut. Hal ini memungkinkan aplikasi memulai container sebagai container imersif. Runtime dapat menolak permintaan untuk mengubah mode batas penampung spasial yang terlihat, dalam hal ini runtime harus mengantrekan peristiwa XrEventDataSpatialContainerBoundsModeRequestDeniedEXT. Misalnya, beberapa runtime akan menolak permintaan untuk mengubah mode batas penampung spasial yang terlihat dan tidak sedang digunakan oleh pengguna.

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika aplikasi meminta mode batas yang tidak didukung berdasarkan XrSystemSpatialContainerPropertiesEXT :: supportsBounded dan XrSystemSpatialContainerPropertiesEXT :: supportsImmersive .

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerBoundsModeRequestInfoEXT digunakan dengan xrRequestSpatialContainerBoundsModeEXT untuk mengubah mode batas penampung spasial.

typedef struct XrSpatialContainerBoundsModeRequestInfoEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerBoundsModeRequestInfoEXT;

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.
  • boundsMode adalah XrSpatialContainerBoundsModeEXT yang diinginkan untuk penampung spasial.

Penggunaan yang Valid (Implisit)

Setiap kali runtime mengubah batas atau mode batas penampung spasial, runtime harus mengantrekan peristiwa XrEventDataSpatialContainerBoundsChangedEXT dengan informasi batas baru.

typedef struct XrEventDataSpatialContainerBoundsChangedEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerEXT              spatialContainer;
    XrExtent3Df                        bounds;
    XrBool32                           infiniteBounds;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrEventDataSpatialContainerBoundsChangedEXT;

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.
  • spatialContainer adalah XrSpatialContainerEXT yang menjadi tujuan peristiwa ini.
  • bounds adalah lebar, tinggi, dan kedalaman baru batas penampung spasial.
  • infiniteBounds bernilai benar jika penampung memiliki batas tak terbatas.
  • boundsMode adalah XrSpatialContainerBoundsModeEXT baru dari penampung spasial.

Peristiwa ini diantrekan untuk semua perubahan, termasuk perubahan yang diminta aplikasi dan perubahan yang dimulai runtime.

Saat pengguna mengubah ukuran penampung spasial secara interaktif, runtime harus berperilaku dengan salah satu cara berikut:

  • mengantrekan banyak peristiwa, kemungkinan pada kecepatan frame, saat pengguna mengubah ukuran penampung spasial
  • mengantrekan satu peristiwa di akhir pengubahan ukuran

Jika runtime hanya mengantrekan satu peristiwa di akhir pengubahan ukuran, runtime tersebut harus terus melaporkan batas lama dari xrGetSpatialContainerBoundsEXT hingga runtime mengantrekan peristiwa pengubahan ukuran. Runtime harus menggabungkan beberapa peristiwa perubahan batas yang tidak di-polling. Dengan kata lain, jika batas atau mode batas berubah saat peristiwa XrEventDataSpatialContainerBoundsChangedEXT masih dalam antrean, runtime harus melaporkan hanya satu peristiwa yang berisi perubahan batas terakhir yang terjadi. Karena aplikasi juga dapat melakukan polling batas penampung spasial secara langsung dengan xrGetSpatialContainerBoundsEXT , jumlah perubahan batas dari peristiwa dapat berbeda dengan jumlah perubahan dari polling berdasarkan waktu perubahan batas yang dihasilkan runtime, panggilan aplikasi ke xrPollEvent , dan panggilan aplikasi ke xrGetSpatialContainerBoundsEXT .

Saat batas penampung spasial berubah, origin lokal penampung spasial juga mungkin berubah. Misalnya, jika runtime memungkinkan pengguna mengubah ukuran batas penampung spasial dengan menarik salah satu tepi penampung, batas dan origin lokal untuk penampung tersebut akan berubah saat pengguna menarik satu tepi. Dalam situasi seperti ini, runtime harus mengubah batas dan origin lokal secara bersamaan.

Runtime harus menetapkan infiniteBounds ke XR_TRUE dan menetapkan lebar, tinggi, dan kedalaman ke 0,0 untuk merepresentasikan batas tak terbatas. Runtime harus menetapkan infiniteBounds ke XR_FALSE dan menetapkan lebar, tinggi, dan kedalaman ke angka positif terbatas untuk batas terbatas.

Runtime harus menetapkan bounds dan infiniteBounds mengikuti aturan yang sama seperti untuk XrSpatialContainerBoundsEXT .

Penggunaan yang Valid (Implisit)

Setiap kali runtime menolak permintaan untuk mengubah mode batas penampung, runtime harus mengantrekan peristiwa XrEventDataSpatialContainerBoundsModeRequestDeniedEXT.

typedef struct XrEventDataSpatialContainerBoundsModeRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerBoundsModeRequestDeniedEXT;

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.
  • spatialContainer adalah XrSpatialContainerEXT yang menjadi tujuan peristiwa ini.

Penggunaan yang Valid (Implisit)

Struktur XrSpatialContainerBoundsEXT mendeskripsikan kotak pembatas penampung spasial.

typedef struct XrSpatialContainerBoundsEXT {
    XrStructureType    type;
    void*              next;
    XrExtent3Df        bounds;
    XrBool32           infiniteBounds;
} XrSpatialContainerBoundsEXT;

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.
  • bounds adalah lebar, tinggi, dan kedalaman batas penampung spasial. Batasnya dalam meter.
  • infiniteBounds bernilai benar jika penampung memiliki batas tak terbatas.

Runtime harus menetapkan infiniteBounds ke XR_TRUE dan menetapkan lebar, tinggi, dan kedalaman ke 0,0 untuk merepresentasikan batas tak terbatas. Runtime harus menetapkan infiniteBounds ke XR_FALSE dan menetapkan lebar, tinggi, dan kedalaman ke angka positif terbatas untuk batas terbatas.

Penggunaan yang Valid (Implisit)

Fungsi xrGetSpatialContainerBoundsEXT mengkueri batas saat ini dari penampung spasial.

XrResult xrGetSpatialContainerBoundsEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsGetInfoEXT*   getInfo,
    XrSpatialContainerBoundsEXT*                bounds);

Deskripsi Parameter

Meskipun penampung spasial dibatasi, penampung tersebut tidak boleh memiliki batas tak terbatas, sedangkan penampung spasial imersif harus memiliki batas tak terbatas.

Runtime dapat mengubah batas penampung spasial menjadi nilai terbatas positif kapan saja saat penampung spasial dibatasi. Perubahan pada batas penampung spasial dikomunikasikan melalui XrEventDataSpatialContainerBoundsChangedEXT .

Dengan ekstensi ini, aplikasi tidak dapat meminta perubahan pada batas selain mengubah antara batas dan imersif dengan xrRequestSpatialContainerBoundsModeEXT . Ekstensi lain mungkin menyediakan cara tersebut pada masa mendatang.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrSpatialContainerBoundsGetInfoEXT adalah struktur input yang ada untuk tujuan ekstensi di masa mendatang.

typedef struct XrSpatialContainerBoundsGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerBoundsGetInfoEXT;

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.

Penggunaan yang Valid (Implisit)

Enumerasi XrSpatialContainerVolumeClippingEXT mengidentifikasi perilaku pemangkasan volume yang berbeda untuk penampung spasial.

typedef enum XrSpatialContainerVolumeClippingEXT {
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT = 0,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT = 1,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerVolumeClippingEXT;

Deskripsi Enum

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT

Tidak ada konten yang dipotong ke volume pembatas penampung spasial. Konten dapat digambar di luar batas penampung spasial.

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT

Konten dipotong secara ketat sesuai volume pembatas penampung spasial.

Tidak ada penggunaan enumerasi ini dalam ekstensi ini. Hal ini ditentukan untuk memungkinkan ekstensi lain menentukan perilaku pemotongan volume yang diinginkan. Misalnya, aplikasi mungkin ingin menggambar latar belakang untuk penampung spasial yang dibatasi. Cubemap monokular adalah cara yang mudah untuk menentukan latar belakang, tetapi cubemap monokular secara konseptual diposisikan pada jarak tak terbatas yang berada di luar penampung.

Kemampuan sistem

Aplikasi dapat memeriksa kemampuan sistem dengan merantai struktur XrSystemSpatialContainerPropertiesEXT ke XrSystemProperties saat memanggil xrGetSystemProperties .

typedef struct XrSystemSpatialContainerPropertiesEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSpatialContainerCount;
    XrBool32           supportsBounded;
    XrBool32           supportsImmersive;
} XrSystemSpatialContainerPropertiesEXT;

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.
  • maxSpatialContainerCount adalah jumlah maksimum penampung spasial yang dapat dibuat.
  • supportsBounded bernilai benar (true) jika penampung spasial dapat dibatasi.
  • supportsImmersive bernilai benar jika penampung spasial diizinkan untuk imersif.

Runtime yang mendukung ekstensi ini harus mendukung aplikasi yang membuat banyak penampung spasial, yang hanya dibatasi oleh alokasi memori. Runtime mungkin memiliki batas yang berbeda untuk jumlah penampung spasial yang ditampilkan secara bersamaan. Tidak ada cara untuk mengkueri jumlah container yang ditampilkan secara bersamaan di ekstensi ini karena runtime dapat membatasi setiap aplikasi berdasarkan status di semua aplikasi yang berjalan. Asumsinya adalah perangkat yang sangat terbatas dan perangkat yang tidak terlalu terbatas akan memiliki batas yang berbeda untuk jumlah penampung yang ditampilkan secara bersamaan; perangkat yang sangat terbatas mungkin hanya mendukung satu penampung spasial yang ditampilkan dalam satu waktu dan perangkat yang tidak terlalu terbatas mungkin mendukung sejumlah besar penampung spasial yang ditampilkan secara bersamaan, bergantung pada batas komputasi rendering.

Runtime yang mendukung ekstensi ini harus mendukung setidaknya salah satu container spasial terbatas atau container spasial imersif.

Penggunaan yang Valid (Implisit)

Fungsi xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT menampilkan metode presentasi grafis yang didukung pada sistem.

XrResult xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    graphicsPresentationCapacityInput,
    uint32_t*                                   graphicsPresentationCountOutput,
    XrSpatialContainerGraphicsPresentationEXT*  graphicsPresentations);

Deskripsi Parameter

  • instance adalah XrInstance tempat systemId diambil.
  • systemId adalah XrSystemId yang sedang dikueri.
  • graphicsPresentationCapacityInput adalah kapasitas array graphicsPresentations, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • graphicsPresentationCountOutput adalah pointer ke jumlah presentasi grafis yang ditulis, atau pointer ke kapasitas yang diperlukan jika graphicsPresentationCapacityInput adalah 0.
  • graphicsPresentations adalah pointer ke array nilai XrSpatialContainerGraphicsPresentationEXT, tetapi bisa null jika graphicsPresentationCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang cara mengambil ukuran graphicsPresentations yang diperlukan.

Runtime harus selalu menampilkan konten buffer yang identik dari enumerasi ini untuk systemId yang diberikan dan selama masa aktif instance.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

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

Perubahan pada status sesi

Dukungan penampung spasial diaktifkan untuk sesi dengan merantai XrSessionCreateInfoSpatialContainersEXT saat memanggil xrCreateSession .

typedef struct XrSessionCreateInfoSpatialContainersEXT {
    XrStructureType    type;
    const void*        next;
} XrSessionCreateInfoSpatialContainersEXT;

Jika dukungan penampung spasial diaktifkan, XrSession akan berperilaku berbeda. Hal ini karena saat menggunakan penampung spasial, sesi tidak lagi menampilkan konten gambar di layar, melainkan penampung spasial yang melakukannya. Oleh karena itu, saat ekstensi ini diaktifkan, sesi akan menjadi "headless". Tidak seperti ekstensi headless lainnya, aplikasi dapat mengirimkan data gambar melalui penampung spasial.

Mengaktifkan dukungan penampung spasial akan mengubah API OpenXR inti dengan cara berikut.

runtime: kehilangan sistem atau perangkat

runtime: kehilangan sistem atau perangkat

xrDestroySession

xrDestroySession

IDLE
(running)

IDLE...

xrGetSystem
xrCreateSession

xrGetSystem...

xrCreateInstance

xrCreateIn...

xrDestroySession

xrDestroySession

LOSS_PENDING
(tidak berjalan)

LOSS_PENDING...

xrDestroyInstance

xrDestroyInstance

aplikasi: secara opsional
luncurkan kembali XR

app: opsional...

Gambar 19. Mesin status sesi baru

  • Sesi tidak pernah memasuki status XR_SESSION_STATE_VISIBLE , XR_SESSION_STATE_FOCUSED , atau XR_SESSION_STATE_EXITING . Runtime tidak boleh mengantrekan peristiwa untuk status ini. Status ini diganti dengan peristiwa per penampung spasial XrEventDataSpatialContainerVisibleChangedEXT , XrEventDataSpatialContainerInteractableChangedEXT , dan XrEventDataSpatialContainerClosedEXT .
  • Sesi juga tidak pernah memasuki status XR_SESSION_STATE_READY , XR_SESSION_STATE_SYNCHRONIZED , XR_SESSION_STATE_STOPPING . Runtime tidak boleh mengantrekan peristiwa untuk status ini. Tidak ada pengganti untuk status ini.
  • Runtime harus memperlakukan sesi sebagai berjalan saat berada dalam status XR_SESSION_STATE_IDLE .
  • Runtime harus memperlakukan sesi sebagai difokuskan saat berada dalam status XR_SESSION_STATE_IDLE dan setidaknya ada satu penampung spasial yang dapat berinteraksi.
  • Fungsi xrBeginSession dan xrEndSession tidak lagi diperlukan. Runtime harus menampilkan XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT saat fungsi ini dipanggil. Ekstensi lain mungkin menyediakan pengganti untuk fungsi ini.
  • Fungsi xrRequestExitSession juga tidak diperlukan lagi. Runtime harus menampilkan XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT saat fungsi ini dipanggil. Aplikasi yang ingin keluar dari sesi yang sedang berjalan dapat memanggil xrRequestSpatialContainerVisibleEXT untuk menyembunyikan penampungnya, dan menghancurkan sesi setelah semua penampung tidak lagi terlihat.

  • Ekstensi yang akan mengantrekan peristiwa tambahan saat sesi mulai berjalan sekarang harus mengantrekan peristiwa tersebut setelah pembuatan sesi. Ekstensi tersebut dijelaskan di bawah.

    Peristiwa Ekstensi

XR_EXT_user_presence

XrEventDataUserPresenceChangedEXT

XR_META_boundary_visibility

XrEventDataBoundaryVisibilityChangedMETA

  • Fungsi xrLocateViews tidak valid untuk dipanggil selama sesi. Runtime harus menampilkan XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT dari xrLocateViews . Ekstensi lain mungkin menyediakan cara untuk menemukan tampilan untuk penampung spasial tertentu.
  • Fungsi xrWaitFrame harus selalu menetapkan XrFrameState :: shouldRender ke false. Ekstensi lain mungkin menyediakan cara untuk mengetahui apakah penampung spasial tertentu harus memperbarui lapisan komposisinya.
  • Fungsi xrEndFrame bukan cara yang valid untuk mengirimkan lapisan komposisi. Jika aplikasi menetapkan XrFrameEndInfo :: layerCount ke nilai bukan nol, runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE . Ekstensi lain mungkin menyediakan cara untuk mengirimkan lapisan komposisi untuk penampung spasial tertentu.
  • Memasuki status XR_SESSION_STATE_LOSS_PENDING juga akan menutup semua penampung spasial. Runtime harus mengantrekan peristiwa XrEventDataSpatialContainerClosedEXT untuk setiap penampung spasial aktif sebelum mengantrekan perubahan status sesi untuk XR_SESSION_STATE_LOSS_PENDING .
  • Fungsi xrCreateSession tidak lagi memerlukan struktur binding API grafis. Ekstensi lain mungkin memerlukan binding grafis, misalnya untuk penampung spasial yang akan dirender menggunakan API grafis.

Perilaku di atas sedikit berbeda dengan perilaku di XR_MND_headless . Runtime tidak boleh mengaktifkan perilaku sesi headless dari XR_MND_headless saat dukungan penampung spasial diaktifkan untuk sesi tersebut.

Catatan

Jika penampung spasial diaktifkan, sesi hanya akan bertransisi di antara dua status: XR_SESSION_STATE_IDLE (berjalan) dan XR_SESSION_STATE_LOSS_PENDING (tidak berjalan). Akibatnya, runtime tidak lagi menampilkan XR_ERROR_SESSION_RUNNING atau XR_ERROR_SESSION_NOT_RUNNING . Sebagai gantinya, saat sesi tidak berjalan, runtime akan menampilkan XR_ERROR_SESSION_LOST atau XR_SESSION_LOSS_PENDING sesuai aturan di inti OpenXR. Selain itu, xrBeginSession , satu-satunya fungsi yang menampilkan XR_ERROR_SESSION_RUNNING , kini akan selalu menampilkan XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT .

Penggunaan yang Valid (Implisit)

Entri Manifes Android

Runtime berbasis AOSP mungkin memiliki perilaku kustom berdasarkan status penampung spasial awal yang dimulai sebelum menjalankan kode aplikasi apa pun. Misalnya, runtime dapat mengubah resource yang dialokasikan untuk aktivitas, animasi peluncuran, atau tampilan layar pembuka. Properti berikut disediakan untuk tujuan ini. Tag ini menggantikan tag <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />, yang tidak boleh ditentukan oleh aplikasi berbasis penampung spasial, kecuali untuk kompatibilitas dengan runtime berbasis AOSP yang lebih lama.

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
          android:value="list of modes" />

Properti ini memberi petunjuk kepada runtime bahwa mode batas digunakan oleh aktivitas. Secara default, daftar ini kosong, yang berarti tidak ada petunjuk.

String berikut valid untuk atribut ini. Beberapa nilai dipisahkan oleh | , seperti "bounded|immersive" .

Nilai

Deskripsi

"2d_panel"

Aktivitas ditampilkan menggunakan framework tampilan 2D Android.

"bounded"

Aktivitas ini menggunakan XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT .

"immersive"

Aktivitas ini menggunakan XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT .

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
          android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED" />

Properti ini memberikan petunjuk kepada runtime tentang XrSpatialContainerBoundsModeEXT awal aktivitas saat pertama kali dibuat. Secara default, string ini adalah XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED, yang berarti tidak ada petunjuk.

Runtime tidak boleh mengharuskan aplikasi memiliki properti ini agar berperilaku sesuai dengan spesifikasi ini. Runtime tidak boleh mengubah perilaku aplikasi yang terlihat berdasarkan properti ini. Semua metadata tersebut harus dapat ditentukan di tingkat <activity> atau tingkat <application>. Jika ditentukan di tingkat <application>, atribut ini akan berlaku untuk semua aktivitas dalam aplikasi yang tidak menentukan nilainya sendiri.

Kode contoh

Kode berikut menunjukkan cara menggunakan ekstensi ini untuk kasus penggunaan khusus persepsi tanpa rendering apa pun.

XrInstance instance;    // Already initialized


// Create the session with spatial containers enabled
XrSession session;

XrSessionCreateInfoSpatialContainersEXT spatialContainerCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT,
};
XrSessionCreateInfo sessionCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO,
  .next = &spatialContainerCreateInfo,   // Enable spatial containers
};
(void)sessionCreateInfo.systemId;                             // Other create fields set in usual way

CHK_XR(xrCreateSession(instance, &sessionCreateInfo, &session));


// Because spatial containers are enabled, the session is considered
// running. App is able to query perception data such as head poses and hand
// poses.


// Based on app logic or when a system lost event happens, destroy the
// session
CHK_XR(xrDestroySession(session));

Jenis Objek Baru

Perintah Baru

Struktur Baru

Enum Baru

Konstanta Enum Baru

  • XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME
  • XR_EXT_spatial_container_SPEC_VERSION

  • Memperluas XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTAINER_EXT

  • Memperluas XrResult :

    • XR_ERROR_COMPATIBLE_SPATIAL_CONTAINER_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT
    • XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT

  • Memperluas XrStructureType :

    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_DENIED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_CLOSED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_INTERACTABLE_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_REQUEST_DENIED_EXT
    • XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_SPACE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_STATE_EXT
    • XR_TYPE_SPATIAL_CONTAINER_STATE_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VISIBLE_REQUEST_INFO_EXT
    • XR_TYPE_SYSTEM_SPATIAL_CONTAINER_PROPERTIES_EXT

Masalah

  • Bagaimana cara menangani beberapa permintaan terlihat yang belum terselesaikan? Should the app get one change / denied back or multiple? Jawabannya mungkin berbeda jika panggilan dilakukan di beberapa frame. Jawabannya mungkin juga berbeda jika beberapa permintaan menghasilkan noop, yaitu meminta penampung spasial agar terlihat, lalu tidak terlihat untuk penampung yang awalnya tidak terlihat.

    • Terselesaikan. Pilihan yang berbeda untuk peristiwa perubahan dan peristiwa yang ditolak. Permintaan noop tidak mengantrekan peristiwa perubahan, hal ini hanya menghasilkan gangguan bagi developer aplikasi dan mudah difilter oleh runtime. Jika beberapa permintaan yang terlihat ditolak, runtime harus menghasilkan peristiwa penolakan yang sesuai untuk setiap permintaan.

  • Bagaimana ekstensi otomatisasi kesesuaian diharapkan untuk ditentukan sehingga semua teks spesifikasi opsional untuk perilaku kebijakan masih dapat diuji oleh CTS?

    • Terselesaikan. Ekstensi pengujian terpisah. Akan ada runtime ekstensi pengujian yang diterapkan hanya untuk CTS, sehingga CTS dapat mengontrol semua kebijakan sistem.

  • Apakah kita memerlukan peristiwa saat posisi penampung spasial berubah?

    • Terselesaikan. Tidak. Ruang penampung spasial tidak dikunci dunia dan ruang lain semacam itu, seperti XR_REFERENCE_SPACE_TYPE_VIEW , tidak memiliki peristiwa saat berubah.

  • Bagaimana cara kerja xrSyncActions jika ada beberapa penampung spasial?

    • Terselesaikan. Tidak perlu ada perubahan. xrSyncActions akan berlaku untuk semua penampung spasial dalam sesi. Jika aplikasi ingin mengarahkan tindakan input ke penampung spasial tertentu, aplikasi dapat melihat status per penampung yang dapat berinteraksi untuk memilih penampung yang merupakan target yang valid. Jika aplikasi hanya ingin menyinkronkan status tindakan input untuk satu penampung spasial, ekstensi tambahan akan diperlukan. Namun, kami berencana untuk berfokus pada ekstensi yang memungkinkan aplikasi sepenuhnya berbasis peristiwa dan menghindari perlunya panggilan xrSyncActions dalam loop frame.

  • Bagaimana aplikasi yang jarang diupdate menangani input?

    • Terselesaikan. Tidak perlu diubah. Meskipun berguna untuk EXT_spatial_container, ekstensi ini juga berguna di luar penampung spasial. Hal ini dapat ditangani melalui ekstensi saluran peristiwa dan berfungsi dalam kedua kasus. Untuk penampung spasial, kami akan menambahkan cara lain untuk memfilter peristiwa untuk satu penampung spasial.

  • Apakah kita perlu menunggu untuk membatasi/mengontrol pengaturan waktu loop input untuk aplikasi dengan loop input dan rendering yang dipisahkan?

    • Terselesaikan. Tidak perlu diubah. Hal ini diharapkan akan ditangani melalui saluran peristiwa dan ekstensi permintaan saat ini. Ekstensi permintaan present memungkinkan rendering berbasis peristiwa dan dipisahkan dari loop frame.

  • Dapatkah penampung spasial mendapatkan posenya secara relatif terhadap penampung spasial lainnya? Pertimbangan utama di sini: Apakah kita memiliki kasus penggunaan untuk ini? Jika ya, bagaimana ruang penampung spasial terhubung ke LOCAL?

    • Terselesaikan. Ya. Hal ini sudah dapat dilakukan untuk penampung spasial dalam sesi yang sama dengan menggunakan XR_REFERENCE_SPACE_TYPE_VIEW dan mendukung konten yang bergantung pada tampilan. Untuk membagikan pose penampung spasial di seluruh sesi (seperti ke proses lain), jalur yang diharapkan adalah memanfaatkan XR_EXT_spatial_anchor serta pola persistensi dan berbagi yang ada.

  • Apakah ruang penampung spasial dapat ditemukan jika tidak terlihat?

    • Terselesaikan. Tidak. Ruang penampung spasial tidak dapat ditemukan jika penampung spasial tidak terlihat. Artinya, aplikasi tidak memiliki audio spasial dan tidak dapat "menyiapkan" konten yang bergantung pada tampilan saat spatial_container tidak terlihat. Keduanya tidak masalah karena saat penampung spasial tidak terlihat, aplikasi diharapkan menghentikan beban CPU/GPU yang digunakan untuk penampung spasial tersebut.

  • Di mana ruang container spasial diperkirakan akan ditempatkan dalam container spasial? Saran telah menjadi pusat atau titik minimal (minX, minY, minZ).

    • Terselesaikan. Di tengah. Tidak ada lokasi yang tidak bergerak dalam sebagian besar cara UX pengubahan ukuran penampung spasial diharapkan (tepi bergerak). Center umum digunakan di bagian lain OpenXR. Kami tidak menyelaraskan dengan jendela dalam komputasi 2D, yang menggunakan koordinat minimum, karena penampil model 3D sering kali tidak mengikuti konvensi ini.

  • Kapan runtime diharapkan membuat resource yang mendasari container spasial? Hal ini terkadang melibatkan IPC dengan layanan sistem.

    • Terselesaikan. Secara sinkron sebagai bagian dari xrCreateSpatialContainerEXT . Meskipun mungkin ada IPC yang terlibat, pembuatan container yang sebenarnya umumnya diperkirakan akan murah. Beberapa vendor memiliki mutex global seputar pengelolaan container, tetapi biasanya tidak memerlukan waktu tunggu yang lama. Masalah terkait pertentangan mutex adalah bug khusus vendor yang diharapkan akan diatasi oleh setiap vendor.

  • Apakah kita memerlukan sinyal bahwa XrSession akan membuat penampung spasial sehingga tidak mendukung jalur rendering lama?

    • Terselesaikan. Ya. Kami mengubah mesin status sesi secara mendasar.

Riwayat Versi

  • Revisi 1, 06-08-2026 (Jared Finder, Google)

    • Deskripsi ekstensi awal