XR_EXT_spatial_entity

String Nama

XR_EXT_spatial_entity

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

741

Revisi

1

Status Ratifikasi

Diratifikasi

Dependensi Ekstensi dan Versi

XR_EXT_future

Kontributor

Nihav Jain, Google
Jared Finder, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Karthik Kadappan, Magic Leap
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Ringkasan

Ekstensi ini memperkenalkan konsep dan fondasi untuk pemahaman scene dan penalaran spasial di OpenXR. Hal ini menyatukan beberapa area fungsi yang terkait tetapi berbeda, yang dihitung, dikonfigurasi, dan berinteraksi dengan cara yang seragam secara luas sebagaimana ditentukan oleh ekstensi ini. Karena ekstensi ini tidak memiliki definisi konkret untuk salah satu area fungsional ini, teks spesifikasi formal cenderung agak abstrak. Contoh yang disertakan dalam teks spesifikasi ekstensi ini terkadang merujuk pada fungsi yang ditentukan dalam ekstensi terkait yang akan datang atau hipotetis untuk tujuan ilustrasi, tanpa secara inheren membatasi atau menentukan fungsi tambahan tersebut.

Bagian luas dari ekstensi ini adalah sebagai berikut:

  • Entitas spasial : Fungsi ini berpusat pada entitas , yang hanya memberikan sedikit fungsi dengan sendirinya.
  • Komponen spasial : Entitas ini memiliki komponen yang terkait dengannya yang menyediakan data dan perilaku.
  • Jenis komponen spasial : Setiap komponen spasial memiliki jenis komponen tertentu , dan setiap entitas memiliki paling banyak satu komponen dari jenis komponen tertentu .
  • Konteks spasial : Semua interaksi entitas spasial terjadi dalam konteks setelah fase inisialisasi dan konfigurasi.
  • Kemampuan spasial : Manipulasi entity spasial secara luas disediakan oleh kemampuan . Kemampuan adalah beberapa unit fungsi, misalnya (tanpa batasan) anchor yang ditentukan aplikasi, deteksi bidang, atau pelacakan gambar. Setiap kemampuan biasanya ditentukan dalam ekstensi terpisah (diaktifkan saat pembuatan instance seperti biasa) dan diaktifkan untuk konteks tertentu pada saat pembuatan.
  • Setiap kemampuan dikaitkan dengan serangkaian jenis komponen yang komponennya ada di setiap entitas yang diekspos oleh kemampuan tersebut . Ekstensi yang menentukan kemampuan menentukan jenis komponen mana yang wajib ada untuk kemampuan ("dijamin"), sementara ekstensi yang sama atau ekstensi lainnya dapat menentukan jenis komponen opsional yang disediakan oleh beberapa kemungkinan penerapan. Sejumlah kemampuan dapat menyediakan entitas dengan komponen dari jenis komponen tertentu , yang dapat digunakan secara seragam terlepas dari kemampuan yang menghasilkannya.
  • Fitur kemampuan spasial : Selain itu, beberapa kemampuan memerlukan konfigurasi, sehingga diparameterkan oleh fitur kemampuan .

Ekstensi ini menyediakan mekanisme untuk menghitung komponen yang disediakan oleh setiap kemampuan yang didukung di sistem saat ini, baik yang wajib maupun komponen opsional .

Karena beberapa penerapan mungkin memerlukan tingkat parameterisasi yang berbeda untuk kemampuan , ekstensi ini menyediakan mekanisme untuk menghitung fitur kemampuan yang didukung yang terkait dengan kemampuan tertentu dalam sistem saat ini.

Ekstensi ini juga menentukan beberapa komponen umum yang diharapkan akan digunakan di berbagai kemampuan .

Entitas Spasial

Entitas spasial adalah entitas yang ada di beberapa ruang, yang memiliki berbagai data terkait yang disusun ke dalam komponen. Mungkin berupa salah satu dari berikut:

  • Fisik (misalnya, permukaan planar seperti dinding dan lantai, objek seperti kursi dan rak buku, dll.)
  • Virtual (misalnya, konten yang ditempatkan dan dibagikan oleh aplikasi atau pengguna lain),
  • Ditentukan aplikasi (misalnya, aplikasi menandai area sebagai "ruang keluarga" atau "dapur", atau menandai titik sebagai lokasi untuk menempatkan TV, dll.)

Hal-hal yang diekspos melalui sistem tindakan, seperti pengontrol atau tatapan mata, tidak dimaksudkan untuk dimodelkan sebagai entitas spasial.

Entitas spasial di OpenXR dimodelkan sebagai sistem Entity-Component . Setiap entitas spasial memiliki serangkaian komponen, dan setiap komponen menyediakan serangkaian data dan perilaku unik untuk entitas tersebut.

Entitas spasial direpresentasikan oleh atom XrSpatialEntityIdEXT atau handle XrSpatialEntityEXT, yang detailnya diberikan di bagian Representasi Entitas Spasial.

Jenis Komponen Spasial

Entitas spasial memiliki satu atau beberapa komponen yang menyediakan data atau perilaku untuk entitas tersebut. Lihat Komponen Umum untuk beberapa komponen umum yang ditentukan oleh ekstensi ini.

typedef enum XrSpatialComponentTypeEXT {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT = 1,
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT = 2,
    XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT = 3,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT = 4,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT = 1000741000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT = 1000741001,
    XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT = 1000741002,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT = 1000741003,
    XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT = 1000743000,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT = 1000744000,
    XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT = 1000744001,
    XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT = 1000744002,
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT = 1000763000,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT = 1000782000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT = 1000783000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT = 1000783001,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT = 1000783002,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID = 1000785000,
    XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID = 1000786000,
    XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID = 1000791000,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS = 1000792002,
    XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS = 1000792003,
    XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS = 1000792004,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS = 1000792005,
    XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1 = 1000793000,
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID = 1000794000,
    XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2 = 1000798000,
    XR_SPATIAL_COMPONENT_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

Enumerasi XrSpatialComponentTypeEXT mengidentifikasi berbagai jenis komponen yang mungkin didukung oleh runtime.

Tidak semua jenis komponen yang tercantum disediakan oleh ekstensi ini sendiri: beberapa memerlukan ekstensi tambahan untuk diaktifkan pada waktu pembuatan instance, seperti yang didokumentasikan.

Enumeran memiliki nilai berikut:

Deskripsi Enum

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Komponen yang menyediakan batas 2D untuk entity spasial. Struktur daftar yang sesuai adalah XrSpatialComponentBounded2DListEXT; Struktur data yang sesuai adalah XrSpatialBounded2DDataEXT

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

Komponen yang menyediakan batas 3D untuk entity spasial. Struktur daftar yang sesuai adalah XrSpatialComponentBounded3DListEXT; Struktur data yang sesuai adalah XrBoxf

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

Komponen yang menyediakan XrSpatialEntityIdEXT induk untuk entity spasial. Struktur daftar yang sesuai adalah XrSpatialComponentParentListEXT ; Struktur data yang sesuai adalah XrSpatialEntityIdEXT

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

Komponen yang menyediakan mesh 3D untuk entitas spasial. Struktur daftar yang sesuai adalah XrSpatialComponentMesh3DListEXT; Struktur data yang sesuai adalah XrSpatialMeshDataEXT

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

Komponen yang menyediakan enum penyelarasan bidang untuk entity spasial. Struktur daftar yang sesuai adalah XrSpatialComponentPlaneAlignmentListEXT; Struktur data yang sesuai adalah XrSpatialPlaneAlignmentEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

Komponen yang menyediakan mesh 2D untuk entitas spasial. Struktur daftar yang sesuai adalah XrSpatialComponentMesh2DListEXT; Struktur data yang sesuai adalah XrSpatialMeshDataEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

Komponen yang menyediakan poligon batas 2D untuk entity spasial. Struktur daftar yang sesuai adalah XrSpatialComponentPolygon2DListEXT; Struktur data yang sesuai adalah XrSpatialPolygon2DDataEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

Komponen yang memberikan label semantik untuk bidang. Struktur daftar yang sesuai adalah XrSpatialComponentPlaneSemanticLabelListEXT; Struktur data yang sesuai adalah XrSpatialPlaneSemanticLabelEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

Komponen yang menjelaskan jenis, ID, dan lokasi penanda. Struktur daftar yang sesuai adalah XrSpatialComponentMarkerListEXT; Struktur data yang sesuai adalah XrSpatialMarkerDataEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_marker_tracking)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

Komponen yang memberikan label semantik untuk adegan; Struktur daftar yang sesuai adalah XrSpatialComponentObjectSemanticLabelListEXT . Struktur data yang sesuai adalah XrSpatialObjectSemanticLabelEXT . (Ditambahkan oleh ekstensi XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

Komponen yang menyediakan label semantik untuk keyboard; Struktur daftar yang sesuai adalah XrSpatialComponentKeyboardSemanticLabelListEXT . Struktur data yang sesuai adalah XrSpatialKeyboardSemanticLabelEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

Komponen yang menyediakan label semantik untuk mouse; Struktur daftar yang sesuai adalah XrSpatialComponentMouseSemanticLabelListEXT . Struktur data yang sesuai adalah XrSpatialMouseSemanticLabelEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

Komponen yang menyediakan lokasi untuk penanda. Struktur daftar yang sesuai adalah XrSpatialComponentAnchorListEXT; Struktur data yang sesuai adalah XrPosef (Ditambahkan oleh ekstensi XR_EXT_spatial_anchor)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

Komponen yang menyediakan UUID persisten untuk entity spasial. Struktur daftar yang sesuai adalah XrSpatialComponentPersistenceListEXT; Struktur data yang sesuai adalah XrSpatialPersistenceDataEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_persistence)

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

Komponen yang menjelaskan jenis gambar planar. Struktur daftar yang sesuai adalah XrSpatialComponentImage2DListEXT; Struktur data yang sesuai adalah XrSpatialImageSizeEXT . (Ditambahkan oleh ekstensi XR_EXT_spatial_image_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

Komponen yang menyediakan normal untuk mesh 3D entitas spasial. Struktur daftar yang sesuai adalah XrSpatialComponentMesh3DNormalsListEXT; Struktur data yang sesuai adalah XrSpatialBufferEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

Komponen yang menyediakan label semantik per-vertex untuk mesh 3D entitas spasial. Struktur daftar yang sesuai adalah XrSpatialComponentMesh3DVertexSemanticLabelsListEXT; Struktur data yang sesuai adalah XrSpatialBufferEXT; Data dalam buffer dipetakan ke XrSpatialMeshSemanticLabelEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

Komponen yang menyediakan label semantik per-segitiga-muka untuk mesh 3D entitas spasial. Struktur daftar yang sesuai adalah XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT; Struktur data yang sesuai adalah XrSpatialBufferEXT; Data dalam buffer dipetakan ke XrSpatialMeshSemanticLabelEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

Komponen yang menyediakan label semantik untuk objek; Struktur daftar yang sesuai adalah XrSpatialComponentObjectSemanticLabelListANDROID; Struktur data yang sesuai adalah XrSpatialObjectSemanticLabelANDROID (Ditambahkan oleh ekstensi XR_ANDROID_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Komponen yang menyediakan pose hit raycast pada entitas. Struktur daftar yang sesuai adalah XrSpatialComponentRaycastResultListANDROID; Struktur data yang sesuai adalah XrSpatialRaycastResultDataANDROID (Ditambahkan oleh ekstensi XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

Komponen yang menyediakan ID entitas dari entitas yang mencakup entitas terlampir. Struktur daftar yang sesuai adalah XrSpatialComponentSubsumedByListANDROID; Struktur data yang sesuai adalah XrSpatialEntityIdEXT (Ditambahkan oleh ekstensi XR_ANDROID_spatial_component_subsumed_by)

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

Komponen yang menyediakan dimensi dan jenis kamar shoebox; Struktur daftar yang sesuai adalah XrSpatialComponentRoomListANDROIDSYS; Struktur data yang sesuai adalah XrSpatialRoomDataANDROIDSYS (Ditambahkan oleh ekstensi XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

Komponen yang menyediakan jenis material permukaan batas; Struktur daftar yang sesuai adalah XrSpatialComponentMaterialTypeListANDROIDSYS; Struktur data yang sesuai adalah XrSpatialMaterialTypeANDROIDSYS (Ditambahkan oleh ekstensi XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

Komponen yang memberikan keyakinan dapat dilacak; Struktur daftar yang sesuai adalah XrSpatialComponentConfidenceListANDROIDSYS; Struktur data yang sesuai adalah float (Ditambahkan oleh ekstensi XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

Komponen yang menunjukkan kekosongan ruangan; Struktur daftar yang sesuai adalah XrSpatialComponentRoomEmptinessListANDROIDSYS; Struktur data yang sesuai adalah float (Ditambahkan oleh ekstensi XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

Komponen yang memberikan informasi petak hunian pada entity terlampir. Struktur daftar yang sesuai adalah XrSpatialComponentOccupancyGridListANDROIDX1 ; Struktur data yang sesuai adalah XrSpatialOccupancyGridDataANDROIDX1 (Ditambahkan oleh ekstensi XR_ANDROIDX1_spatial_occupancy_grid)

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Komponen yang menjelaskan anotasi quad. Struktur daftar yang sesuai adalah XrSpatialComponentAnnotationQuadListANDROID; Struktur data yang sesuai adalah XrSpatialAnnotationQuadDataANDROID (Ditambahkan oleh ekstensi XR_ANDROID_spatial_annotation_tracking)

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

Komponen yang menyediakan metadata untuk geometri streetscape; Struktur daftar yang sesuai adalah XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2; Struktur data yang sesuai adalah XrSpatialStreetscapeGeometryMetadataANDROIDX2 (Ditambahkan oleh ekstensi XR_ANDROIDX2_geospatial_streetscape)

Kemampuan Spasial dan Penyiapan

Kemampuan spasial menentukan kemampuan runtime untuk menemukan entitas yang memiliki kumpulan komponen yang dijamin. Aplikasi mengaktifkan komponen kemampuan spasial saat membuat XrSpatialContextEXT, dan runtime pada gilirannya harus menyediakan hanya komponen yang diaktifkan pada entity yang ditemukan. Misalnya, jika runtime melaporkan bahwa salah satu komponen untuk kemampuan tertentu adalah "label semantik", berarti aplikasi dapat mengaktifkan label semantik melalui konfigurasi untuk kemampuan tersebut dan runtime harus hanya menyediakan komponen label semantik jika dikonfigurasi.

typedef enum XrSpatialCapabilityEXT {
    XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT = 1000741000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT = 1000743002,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT = 1000743003,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID = 1000785000,
    XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID = 1000786000,
    XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS = 1000792000,
    XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS = 1000792001,
    XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID = 1000794000,
    XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2 = 1000798000,
    XR_SPATIAL_CAPABILITY_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityEXT;

Enumerasi XrSpatialCapabilityEXT mengidentifikasi berbagai jenis kemampuan yang mungkin didukung oleh runtime.

Enumeran memiliki nilai berikut:

Deskripsi Enum

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

Pelacakan pesawat (Ditambahkan oleh ekstensi XR_EXT_spatial_plane_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

Kemampuan untuk mendeteksi dan melacak kode QR. (Ditambahkan oleh ekstensi XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

Kemampuan untuk mendeteksi dan melacak kode QR Mikro. (Ditambahkan oleh ekstensi XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

Kemampuan untuk mendeteksi dan melacak Penanda Aruco. (Ditambahkan oleh ekstensi XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

Kemampuan untuk mendeteksi dan melacak AprilTag. (Ditambahkan oleh ekstensi XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

Pelacakan objek (Ditambahkan oleh ekstensi XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

Kemampuan untuk membuat anchor spasial (Ditambahkan oleh ekstensi XR_EXT_spatial_anchor)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Kemampuan untuk mendeteksi dan melacak gambar referensi planar. (Ditambahkan oleh ekstensi XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

Kemampuan untuk melacak mesh lingkungan. (Ditambahkan oleh ekstensi XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

Pelacakan objek (Ditambahkan oleh ekstensi XR_ANDROID_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

Raycast terhadap buffer kedalaman (Ditambahkan oleh ekstensi XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

Kemampuan untuk melacak ruangan (Ditambahkan oleh ekstensi XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

Kemampuan untuk melacak batas ruangan (Ditambahkan oleh ekstensi XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Pelacakan anotasi (Ditambahkan oleh ekstensi XR_ANDROID_spatial_annotation_tracking)

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

Streetscape geometry (Ditambahkan oleh ekstensi XR_ANDROIDX2_geospatial_streetscape)

Fungsi xrEnumerateSpatialCapabilitiesEXT ditentukan sebagai:

XrResult xrEnumerateSpatialCapabilitiesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    capabilityCapacityInput,
    uint32_t*                                   capabilityCountOutput,
    XrSpatialCapabilityEXT*                     capabilities);

Deskripsi Parameter

  • instance adalah tuas untuk XrInstance .
  • systemId adalah XrSystemId yang kemampuan spasialnya akan dihitung.
  • capabilityCapacityInput adalah kapasitas array capabilities, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • capabilityCountOutput adalah jumlah kemampuan, atau kapasitas yang diperlukan jika capabilityCapacityInput tidak mencukupi.
  • capabilities adalah array XrSpatialCapabilityEXT . Nilainya dapat berupa NULL jika capabilityCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran capabilities yang diperlukan.

Aplikasi dapat menghitung daftar kemampuan spasial yang didukung oleh XrSystemId tertentu menggunakan xrEnumerateSpatialCapabilitiesEXT .

Runtime tidak boleh menghitung kemampuan spasial yang ekstensinya tidak diaktifkan untuk instance .

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_EXT_spatial_entity harus diaktifkan sebelum memanggil xrEnumerateSpatialCapabilitiesEXT
  • instance harus berupa handle XrInstance yang valid
  • capabilityCountOutput harus berupa pointer ke nilai uint32_t
  • Jika capabilityCapacityInput bukan 0 , capabilities harus berupa pointer ke array nilai XrSpatialCapabilityEXT capabilityCapacityInput

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

Fungsi xrEnumerateSpatialCapabilityComponentTypesEXT ditentukan sebagai:

XrResult xrEnumerateSpatialCapabilityComponentTypesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    XrSpatialCapabilityComponentTypesEXT*       capabilityComponents);

Deskripsi Parameter

  • instance adalah tuas untuk XrInstance .
  • systemId adalah XrSystemId yang komponen kemampuan spasialnya akan dihitung.
  • capability adalah XrSpatialCapabilityEXT yang komponennya akan dihitung.
  • capabilityComponents adalah pointer ke XrSpatialCapabilityComponentTypesEXT , yang merupakan struktur input/output tempat array yang dialokasikan aplikasi diisi.

Fungsi ini mencantumkan jenis komponen yang disediakan oleh kemampuan tertentu pada entitasnya dalam sistem seperti yang dikonfigurasi.

Aplikasi dapat menggunakan jenis komponen yang tercantum dalam XrSpatialCapabilityComponentTypesEXT :: componentTypes untuk memahami kumpulan lengkap komponen yang didukung systemId untuk capability dan dapat menggunakan daftar ini untuk menentukan konfigurasi yang valid untuk capability saat membuat XrSpatialContextEXT untuknya.

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT jika capability tidak di-enum oleh xrEnumerateSpatialCapabilitiesEXT .

Runtime tidak boleh menghitung jenis komponen spasial yang ekstensinya tidak diaktifkan untuk instance .

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

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

Struktur XrSpatialCapabilityComponentTypesEXT ditentukan sebagai:

typedef struct XrSpatialCapabilityComponentTypesEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      componentTypeCapacityInput;
    uint32_t                      componentTypeCountOutput;
    XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialCapabilityComponentTypesEXT;

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.
  • componentTypeCapacityInput adalah kapasitas array, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • componentTypeCountOutput adalah jumlah jenis komponen, atau kapasitas yang diperlukan jika componentTypeCapacityInput tidak mencukupi.
  • componentTypes adalah array XrSpatialComponentTypeEXT . Nilainya dapat berupa NULL jika componentTypeCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran componentTypes yang diperlukan.

Penggunaan yang Valid (Implisit)

Fitur kemampuan spasial

typedef enum XrSpatialCapabilityFeatureEXT {
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID = 1000761000,
    XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID = 1000761001,
    XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID = 1000761002,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT = 1000782001,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT = 1000782002,
    XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_FEATURE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityFeatureEXT;

Beberapa kemampuan memiliki parameter yang diekspos ke aplikasi untuk mengonfigurasi cara data komponen dihitung oleh runtime. Dimensi parameterisasi/kemampuan konfigurasi ini dikenal sebagai fitur kemampuan. Misalnya, untuk kemampuan pelacakan gambar, runtime dapat mendukung fitur bagi aplikasi untuk menentukan apakah gambar yang dilacak statis atau tidak.

Memberikan informasi ini ke runtime melalui struktur konfigurasi tidak boleh mengubah kumpulan jenis komponen yang ada pada entitas terkait, misalnya pada gambar yang dilacak. Namun, runtime dapat mengoptimalkan, misalnya, kemampuan pelacakan dari kemampuan pelacakan gambar dan memberikan pengalaman yang lebih baik ke aplikasi.

Fitur tersebut direpresentasikan oleh XrSpatialCapabilityFeatureEXT dan aplikasi mencantumkannya menggunakan xrEnumerateSpatialCapabilityFeaturesEXT .

Setiap fitur kemampuan memiliki struktur konfigurasi yang sesuai untuk mengaktifkannya. Struktur konfigurasi tersebut harus dirantai ke XrSpatialCapabilityConfigurationBaseHeaderEXT :: next dari kemampuan yang sesuai.

Enumeran memiliki nilai berikut:

Deskripsi Enum

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

Fitur kemampuan untuk memungkinkan aplikasi menentukan ukuran penanda. Struktur konfigurasi yang sesuai adalah XrSpatialMarkerSizeEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

Fitur kemampuan untuk mengizinkan aplikasi menentukan apakah penanda bersifat statis. Struktur konfigurasi yang sesuai adalah XrSpatialMarkerStaticOptimizationEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

Fitur spasial yang memungkinkan aplikasi menentukan subset label dari XrSpatialObjectSemanticLabelEXT untuk dilacak oleh runtime. Struktur konfigurasi yang sesuai adalah XrSpatialFeatureObjectSemanticLabelSubsetEXT . (Ditambahkan oleh ekstensi XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

Runtime mendukung filter XrSpatialBoundsSpherefANDROID untuk XrSpatialDiscoverySnapshotCreateInfoEXT; Hal ini tidak memerlukan struktur konfigurasi apa pun untuk disertakan selama pembuatan konteks spasial. (Ditambahkan oleh ekstensi XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

Runtime mendukung filter XrSpatialBoundsBoxfANDROID untuk XrSpatialDiscoverySnapshotCreateInfoEXT; Hal ini tidak memerlukan struktur konfigurasi apa pun untuk disertakan selama pembuatan konteks spasial. (Ditambahkan oleh ekstensi XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

Runtime mendukung filter XrSpatialBoundsFrustumfANDROID untuk XrSpatialDiscoverySnapshotCreateInfoEXT; Hal ini tidak memerlukan struktur konfigurasi apa pun untuk disertakan selama pembuatan konteks spasial. (Ditambahkan oleh ekstensi XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

Runtime mendukung penyimpulan otomatis ukuran fisik gambar yang terdeteksi dan dilacak. Struktur konfigurasi yang sesuai adalah XrSpatialImageSizeEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

Runtime mendukung XrSpatialImageStaticOptimizationEXT . Struktur konfigurasi yang sesuai adalah XrSpatialImageStaticOptimizationEXT . (Ditambahkan oleh ekstensi XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

Runtime mendukung XrSpatialImageSizeEXT . Struktur konfigurasi yang sesuai adalah XrSpatialImageSizeEXT (Ditambahkan oleh ekstensi XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

Fitur kemampuan untuk melacak mesh lingkungan yang kedap air. Struktur konfigurasi yang sesuai adalah XrSpatialFeatureTrackWatertightMeshEXT . (Ditambahkan oleh ekstensi XR_EXT_spatial_mesh_tracking)

Fungsi xrEnumerateSpatialCapabilityFeaturesEXT ditentukan sebagai:

XrResult xrEnumerateSpatialCapabilityFeaturesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    capabilityFeatureCapacityInput,
    uint32_t*                                   capabilityFeatureCountOutput,
    XrSpatialCapabilityFeatureEXT*              capabilityFeatures);

Deskripsi Parameter

  • instance adalah tuas untuk XrInstance .
  • systemId adalah XrSystemId yang fitur kemampuan spasialnya akan dihitung.
  • capability adalah XrSpatialCapabilityEXT yang fiturnya akan dihitung.
  • capabilityFeatureCapacityInput adalah kapasitas array, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • capabilityFeatureCountOutput adalah jumlah fitur, atau kapasitas yang diperlukan jika capabilityFeatureCapacityInput tidak mencukupi.
  • capabilityFeatures adalah array XrSpatialCapabilityFeatureEXT . Nilainya dapat berupa NULL jika capabilityFeatureCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran capabilityFeatures yang diperlukan.

Aplikasi menemukan fitur yang didukung oleh sistem tertentu untuk XrSpatialCapabilityEXT menggunakan xrEnumerateSpatialCapabilityFeaturesEXT .

Untuk kemampuan yang memiliki fitur yang diekspos, aplikasi memilih fitur yang akan diaktifkan dan menyediakan struktur konfigurasi yang sesuai dalam rantai berikutnya dari struktur konfigurasi kemampuan di XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Jika capability bukan kemampuan yang di-enumerasi oleh xrEnumerateSpatialCapabilitiesEXT , runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

Runtime tidak boleh menghitung fitur kemampuan spasial yang ekstensinya tidak diaktifkan untuk instance .

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

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

Konteks Spasial

Membuat konteks spasial

XR_DEFINE_HANDLE(XrSpatialContextEXT)

Handle XrSpatialContextEXT merepresentasikan resource untuk menemukan dan memperbarui sejumlah entitas spasial di lingkungan pengguna. Aplikasi dapat menggunakan handle ini untuk menemukan dan memperbarui entitas spasial menggunakan fungsi lain dalam ekstensi ini.

Fungsi xrCreateSpatialContextAsyncEXT ditentukan sebagai:

XrResult xrCreateSpatialContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialContextCreateInfoEXT*        createInfo,
    XrFutureEXT*                                future);

Deskripsi Parameter

  • session adalah XrSession yang konteks spasialnya akan aktif.
  • createInfo adalah XrSpatialContextCreateInfoEXT yang digunakan untuk menentukan parameter konteks spasial.
  • future adalah pointer ke XrFutureEXT .

Aplikasi dapat membuat handle XrSpatialContextEXT dengan:

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT jika XrSpatialContextCreateInfoEXT ::capabilityConfigCount adalah 0. Handle konteks spasial memerlukan setidaknya satu kemampuan.

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT jika ada kemampuan dalam array XrSpatialContextCreateInfoEXT :: capabilityConfigs yang tidak di-enumerasi oleh xrEnumerateSpatialCapabilitiesEXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT jika ada XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount dalam XrSpatialContextCreateInfoEXT :: capabilityConfigs yang bernilai 0. Konfigurasi kemampuan tidak lengkap tanpa daftar jenis komponen yang akan diaktifkan untuk kemampuan tersebut.

Runtime harus menampilkan XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT jika ada jenis komponen yang tercantum dalam XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents yang tidak di-enum untuk XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability dalam xrEnumerateSpatialCapabilityComponentTypesEXT .

Jika ada struktur dalam rantai XrSpatialContextCreateInfoEXT :: capabilityConfigs berikutnya yang sesuai dengan XrSpatialCapabilityFeatureEXT yang tidak di-enum untuk kemampuan tersebut di xrEnumerateSpatialCapabilityFeaturesEXT , runtime harus mengabaikan struktur XrSpatialCapabilityFeatureEXT tersebut.

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT jika XrSpatialContextCreateInfoEXT :: capabilityConfigs berisi beberapa struktur dengan XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability yang sama .

Untuk memastikan penggunaan resource sistem yang optimal, runtime dapat menggunakan konfigurasi yang disediakan dalam array XrSpatialContextCreateInfoEXT untuk mempersiapkan diri menerima permintaan spasial yang akan masuk. Misalnya, runtime yang mendukung kemampuan pelacakan bidang mungkin hanya memulai pipeline pelacakan bidangnya jika handle konteks spasial yang berisi kemampuan pelacakan bidang dibuat oleh aplikasi. Jika kemampuan yang dikonfigurasi memiliki waktu pemanasan yang lama, panggilan ke xrCreateSpatialDiscoverySnapshotAsyncEXT dapat menghasilkan snapshot kosong. Aplikasi dapat menunggu XrEventDataSpatialDiscoveryRecommendedEXT sebelum menggunakan xrCreateSpatialDiscoverySnapshotAsyncEXT untuk memastikan bahwa layanan pelacakan yang mendasarinya telah siap.

Jika runtime menerapkan sistem izin untuk mengontrol akses aplikasi ke kemampuan spasial yang dikonfigurasi untuk XrSpatialContextEXT , maka runtime harus menampilkan XR_ERROR_PERMISSION_INSUFFICIENT jika izin tersebut belum diberikan ke aplikasi ini.

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

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrSpatialContextCreateInfoEXT ditentukan sebagai:

typedef struct XrSpatialContextCreateInfoEXT {
    XrStructureType                                                type;
    const void*                                                    next;
    uint32_t                                                       capabilityConfigCount;
    const XrSpatialCapabilityConfigurationBaseHeaderEXT* const*    capabilityConfigs;
} XrSpatialContextCreateInfoEXT;

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.
  • capabilityConfigCount adalah uint32_t yang menjelaskan jumlah elemen dalam array capabilityConfigs.
  • capabilityConfigs adalah pointer ke array pointer XrSpatialCapabilityConfigurationBaseHeaderEXT.

Struktur XrSpatialContextCreateInfoEXT menjelaskan informasi untuk membuat handle XrSpatialContextEXT.

Penggunaan yang Valid (Implisit)

Struktur XrSpatialCapabilityConfigurationBaseHeaderEXT ditentukan sebagai:

typedef struct XrSpatialCapabilityConfigurationBaseHeaderEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationBaseHeaderEXT;

Struktur ini tidak digunakan secara langsung di API, tetapi struktur turunannya dapat digunakan dengan XrSpatialContextCreateInfoEXT untuk mengonfigurasi kemampuan spasial.

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • capability adalah XrSpatialCapabilityEXT .
  • enabledComponentCount adalah uint32_t yang menjelaskan jumlah elemen dalam array enabledComponents.
  • enabledComponents adalah pointer ke array XrSpatialComponentTypeEXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT jika capability tidak di-enum oleh xrEnumerateSpatialCapabilitiesEXT . Runtime harus menampilkan XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT jika ada jenis komponen yang tercantum dalam enabledComponents tidak di-enum untuk capability di xrEnumerateSpatialCapabilityComponentTypesEXT .

Penggunaan yang Valid (Implisit)

Fungsi xrCreateSpatialContextCompleteEXT ditentukan sebagai:

XrResult xrCreateSpatialContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialContextCompletionEXT*        completion);

Deskripsi Parameter

xrCreateSpatialContextCompleteEXT menyelesaikan operasi asinkron yang dimulai oleh xrCreateSpatialContextAsyncEXT . Runtime harus menampilkan XR_ERROR_FUTURE_PENDING_EXT jika future tidak dalam status siap. Runtime harus menampilkan XR_ERROR_FUTURE_INVALID_EXT jika future telah selesai atau dibatalkan.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrCreateSpatialContextCompletionEXT ditentukan sebagai:

typedef struct XrCreateSpatialContextCompletionEXT {
    XrStructureType        type;
    void*                  next;
    XrResult               futureResult;
    XrSpatialContextEXT    spatialContext;
} XrCreateSpatialContextCompletionEXT;

Deskripsi Anggota

Kode Pengembalian Mendatang

Nilai futureResult:

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT

Jika futureResult adalah kode keberhasilan, spatialContext harus valid. Jika valid, spatialContext tetap valid hanya dalam siklus proses xrCreateSpatialContextAsyncEXT :: session atau hingga aplikasi menghancurkan spatialContext dengan xrDestroySpatialContextEXT , mana saja yang lebih dulu.

Penggunaan yang Valid (Implisit)

Menghancurkan konteks spasial

Fungsi xrDestroySpatialContextEXT ditentukan sebagai:

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

Deskripsi Parameter

Aplikasi dapat memanggil fungsi xrDestroySpatialContextEXT untuk melepaskan handle spatialContext dan resource pokok saat selesai melakukan tugas penemuan dan pembaruan entitas spasial. Jika tidak ada XrSpatialContextEXT valid lain yang dibuat dengan kemampuan spasial yang sama seperti spatialContext , panggilan ini berfungsi sebagai saran ke runtime untuk menonaktifkan layanan pelacakan yang diperlukan agar kemampuan tersebut dapat menghemat resource sistem.

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke spatialContext , dan semua handle turunan, harus disinkronkan secara eksternal

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Representasi Entitas Spasial

ID Entitas Spasial

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT digunakan untuk merepresentasikan semua jenis entity yang ditemukan oleh runtime di lingkungan spasial pengguna. XrSpatialEntityIdEXT valid untuk XrSpatialContextEXT tempat XrSpatialEntityIdEXT ditemukan, dan runtime tidak boleh menggunakan kembali XrSpatialEntityIdEXT yang sama untuk entitas yang berbeda dalam XrSpatialContextEXT yang sama . Selain itu, runtime tidak boleh menggunakan kembali XrSpatialEntityIdEXT yang sama di beberapa XrSpatialContextEXT dalam XrSession yang sama, terlepas dari apakah XrSpatialEntityIdEXT tersebut merepresentasikan entitas yang sama atau berbeda.

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT adalah nilai yang dicadangkan yang merepresentasikan XrSpatialEntityIdEXT yang tidak valid . Nilai ini dapat diteruskan ke dan ditampilkan dari fungsi API hanya jika diizinkan secara khusus.

Handle Entitas Spasial

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

Handle XrSpatialEntityEXT mewakili entitas spasial. Aplikasi dapat membuat handle tersebut untuk menyatakan minatnya pada entity tertentu ke runtime.

Membuat Spatial Entity Handle dari ID

Fungsi xrCreateSpatialEntityFromIdEXT ditentukan sebagai:

XrResult xrCreateSpatialEntityFromIdEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialEntityFromIdCreateInfoEXT*   createInfo,
    XrSpatialEntityEXT*                         spatialEntity);

Deskripsi Parameter

Aplikasi dapat menggunakan xrCreateSpatialEntityFromIdEXT untuk membuat handle XrSpatialEntityEXT yang merupakan referensi ke entity yang ada di lingkungan pengguna.

Runtime harus menampilkan XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT jika XrSpatialEntityFromIdCreateInfoEXT :: entityId bukan ID yang valid untuk spatialContext .

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_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrSpatialEntityFromIdCreateInfoEXT ditentukan sebagai:

typedef struct XrSpatialEntityFromIdCreateInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    entityId;
} XrSpatialEntityFromIdCreateInfoEXT;

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.
  • entityId adalah XrSpatialEntityIdEXT entity yang ingin dibuatkan handle-nya oleh aplikasi.

Penggunaan yang Valid (Implisit)

Menghancurkan Handle Entitas Spasial

Fungsi xrDestroySpatialEntityEXT ditentukan sebagai:

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

Deskripsi Parameter

Aplikasi dapat menggunakan xrDestroySpatialEntityEXT untuk melepaskan handle spatialEntity jika tidak lagi tertarik dengan entity yang dirujuk oleh handle ini.

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke spatialEntity , dan semua handle turunan, harus disinkronkan secara eksternal

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Snapshot Spasial

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

Aplikasi dapat membuat snapshot spasial untuk tujuan menemukan entity spasial atau untuk memperbarui informasinya tentang entity spasial yang diketahui. Handle XrSpatialSnapshotEXT merepresentasikan data yang tidak dapat diubah untuk entitas spasial yang ditemukan atau diperbarui dan subset komponennya seperti yang dipilih oleh aplikasi. Snapshot spasial merepresentasikan tampilan yang koheren dari entity dan data komponennya. Setelah snapshot dibuat, data snapshot harus tetap konstan selama snapshot valid.

Aplikasi dapat membuat sejumlah snapshot yang diinginkan, tetapi harus memperhatikan memori yang dialokasikan untuk setiap snapshot baru dan harus menghapus snapshot setelah tidak lagi diperlukan.

Membuat snapshot penemuan

Fungsi xrCreateSpatialDiscoverySnapshotAsyncEXT ditentukan sebagai:

XrResult xrCreateSpatialDiscoverySnapshotAsyncEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialDiscoverySnapshotCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Deskripsi Parameter

Aplikasi dapat menemukan entity spasial dengan membuat snapshot penemuan menggunakan xrCreateSpatialDiscoverySnapshotAsyncEXT .

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

Aplikasi dapat mengirimkan beberapa permintaan pembuatan snapshot penemuan tanpa perlu menunggu permintaan sebelumnya selesai. Proses dan penyelesaian pembuatan snapshot dapat dilakukan dalam urutan apa pun. Runtime dapat menunda penyelesaian pembuatan snapshot penemuan untuk membatasi aplikasi jika perlu mengurangi penggunaan resource sistem karena daya, termal, atau kebijakan perangkat lainnya.

Aplikasi dapat menggunakan XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes untuk memfilter daftar entitas dan komponen yang datanya harus disertakan dalam snapshot oleh runtime. Jika aplikasi menyediakan daftar jenis komponen spasial yang valid di XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , maka runtime harus hanya menyertakan entitas spasial dalam snapshot yang memiliki setidaknya salah satu komponen yang disediakan di XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . Selain itu, runtime harus hanya menyertakan data untuk komponen tersebut dalam snapshot.

Runtime harus menampilkan XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT jika ada XrSpatialComponentTypeEXT di XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes yang tidak diaktifkan untuk kemampuan spasial yang diteruskan ke XrSpatialContextCreateInfoEXT :: capabilityConfigs saat membuat spatialContext .

Jika aplikasi tidak menyediakan daftar jenis komponen spasial di XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , runtime harus menyertakan semua entitas spasial dalam snapshot yang memiliki kumpulan komponen yang tercantum di XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents untuk kemampuan yang dikonfigurasi untuk spatialContext . Runtime harus menyertakan data untuk semua komponen yang diaktifkan dari kemampuan yang dikonfigurasi untuk spatialContext .

Jika XrEventDataReferenceSpaceChangePending diantrekan sebelum penyelesaian future , dan XrEventDataReferenceSpaceChangePending :: poseValid salah (false), maka runtime dapat membuat XrSpatialSnapshotEXT yang tidak memiliki entitas di dalamnya atau menyetel XrSpatialEntityTrackingStateEXT dari entitas yang tidak lagi dapat dilokasikan di XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace pada XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time ke XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT atau XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . Runtime tidak boleh menetapkan XrCreateSpatialContextCompletionEXT :: futureResult ke kode error karena XrEventDataReferenceSpaceChangePending .

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_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrSpatialDiscoverySnapshotCreateInfoEXT ditentukan sebagai:

typedef struct XrSpatialDiscoverySnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialDiscoverySnapshotCreateInfoEXT;

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.
  • componentTypeCount adalah uint32_t yang menjelaskan jumlah elemen dalam array componentTypes.
  • componentTypes adalah array XrSpatialComponentTypeEXT .

Struktur XrSpatialDiscoverySnapshotCreateInfoEXT menjelaskan informasi untuk membuat handle XrSpatialSnapshotEXT saat menemukan entitas spasial.

Penggunaan yang Valid (Implisit)

Fungsi xrCreateSpatialDiscoverySnapshotCompleteEXT ditentukan sebagai:

XrResult xrCreateSpatialDiscoverySnapshotCompleteEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrCreateSpatialDiscoverySnapshotCompletionInfoEXT* createSnapshotCompletionInfo,
    XrCreateSpatialDiscoverySnapshotCompletionEXT* completion);

Deskripsi Parameter

xrCreateSpatialDiscoverySnapshotCompleteEXT menyelesaikan operasi asinkron yang dimulai oleh xrCreateSpatialDiscoverySnapshotAsyncEXT . Runtime harus menampilkan XR_ERROR_FUTURE_PENDING_EXT jika XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future tidak dalam status siap. Runtime harus menampilkan XR_ERROR_FUTURE_INVALID_EXT jika XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future telah selesai atau dibatalkan.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrCreateSpatialDiscoverySnapshotCompletionInfoEXT ditentukan sebagai:

typedef struct XrCreateSpatialDiscoverySnapshotCompletionInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrFutureEXT        future;
} XrCreateSpatialDiscoverySnapshotCompletionInfoEXT;

Deskripsi Anggota

Lokasi dalam berbagai data komponen yang disertakan dalam snapshot yang dibuat akan ditampilkan di baseSpace , yang berada di time .

Penggunaan yang Valid (Implisit)

Struktur XrCreateSpatialDiscoverySnapshotCompletionEXT ditentukan sebagai:

typedef struct XrCreateSpatialDiscoverySnapshotCompletionEXT {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialSnapshotEXT    snapshot;
} XrCreateSpatialDiscoverySnapshotCompletionEXT;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • futureResult adalah XrResult dari operasi pembuatan snapshot penemuan spasial.
  • snapshot adalah XrSpatialSnapshotEXT yang dapat digunakan untuk mengkueri data komponen entity spasial yang ditemukan.

Kode Pengembalian Mendatang

Nilai futureResult:

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Penggunaan yang Valid (Implisit)

Acara Rekomendasi Penemuan

Struktur XrEventDataSpatialDiscoveryRecommendedEXT ditentukan sebagai:

typedef struct XrEventDataSpatialDiscoveryRecommendedEXT {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
} XrEventDataSpatialDiscoveryRecommendedEXT;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • spatialContext adalah XrSpatialContextEXT yang penemuannya direkomendasikan oleh runtime.

Aplikasi dapat mengambil peristiwa ini menggunakan xrPollEvent . Aplikasi dapat menghindari panggilan berlebihan ke xrCreateSpatialDiscoverySnapshotAsyncEXT untuk menemukan entitas spasial dengan menunggu peristiwa ini. Jika aplikasi membuat beberapa snapshot penemuan dengan XrSpatialDiscoverySnapshotCreateInfoEXT yang sama di antara dua peristiwa XrEventDataSpatialDiscoveryRecommendedEXT, snapshot yang dihasilkan mungkin berisi entity yang sama sehingga pembuatan snapshot dan kueri data akan sia-sia.

Menunggu peristiwa ini untuk membuat snapshot penemuan baru memastikan bahwa aplikasi tidak membebani sistem dengan permintaan penemuan yang mungkin tidak menampilkan data baru dan membantu menghindari risiko penggunaan berlebihan sumber daya sistem, dan mengalami pembatasan karena kebijakan daya atau termal perangkat. Hal ini juga membantu menciptakan kesamaan antara runtime yang menemukan entitas spasial secara langsung dengan pelacakan langsung dan runtime yang menyediakan entitas spasial dari status yang direkam sebelumnya (tempat runtime dapat mengantrekan peristiwa rekomendasi penemuan hanya sekali untuk setiap XrSpatialContextEXT).

Runtime tidak boleh mengantrekan peristiwa ini untuk memberi tahu aplikasi tentang perubahan atau penyesuaian yang dilakukan pada data komponen entitas spasial yang ada. Aplikasi dapat menggunakan xrCreateSpatialUpdateSnapshotEXT untuk melacak pembaruan data komponen untuk entity spasial yang diminatinya.

Runtime dapat mengantrekan peristiwa rekomendasi penemuan tanpa menunggu aplikasi memanggil xrCreateSpatialDiscoverySnapshotAsyncEXT terlebih dahulu . Misalnya, runtime dapat mendasarkan keputusan untuk mengantrekan peristiwa rekomendasi penemuan pada konfigurasi XrSpatialContextEXT , pemahaman runtime sendiri tentang lingkungan di sekitar pengguna (penemuan entitas baru atau hilangnya entitas yang ada), atau untuk memberikan petunjuk tentang irama permintaan penemuan yang sesuai ke aplikasi agar tidak membebani sumber daya sistem. Runtime dapat memilih untuk tidak pernah mengantrekan peristiwa ini untuk XrSpatialContextEXT jika tidak ada entity yang ditemukan di lingkungan pengguna selama masa aktif XrSpatialContextEXT tersebut .

Runtime tidak boleh mengantrekan peristiwa ini untuk spatialContext tertentu hingga aplikasi menyelesaikan pembuatannya dengan menggunakan xrCreateSpatialContextCompleteEXT .

Setelah aplikasi memanggil xrDestroySpatialContextEXT, runtime tidak boleh mengantrekan peristiwa rekomendasi penemuan lebih lanjut untuk konteks spasial tersebut, atau menampilkan peristiwa tersebut untuk konteks tersebut dari xrPollEvent .

Penggunaan yang Valid (Implisit)

Membuat Kueri Data Komponen

Fungsi xrQuerySpatialComponentDataEXT ditentukan sebagai:

XrResult xrQuerySpatialComponentDataEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialComponentDataQueryConditionEXT* queryCondition,
    XrSpatialComponentDataQueryResultEXT*       queryResult);

Deskripsi Parameter

Aplikasi dapat menggunakan xrQuerySpatialComponentDataEXT untuk membuat kueri data komponen entitas dalam snapshot dengan melampirkan struktur daftar ke XrSpatialComponentDataQueryResultEXT :: next yang sesuai dengan setiap XrSpatialComponentTypeEXT dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Jika aplikasi melampirkan struktur daftar ke XrSpatialComponentDataQueryResultEXT :: next yang tidak sesuai dengan salah satu komponen yang tercantum dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes , runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .

Aplikasi dapat memilih untuk melampirkan struktur daftar yang sesuai dengan hanya sebagian kecil komponen yang tercantum dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes . Aplikasi dapat memilih untuk menghilangkan struktur daftar sepenuhnya jika hanya ingin mengetahui ID dan status pelacakan entitas spasial yang memenuhi queryCondition . Runtime tidak boleh memperlakukan tidak adanya struktur daftar dari rantai XrSpatialComponentDataQueryResultEXT :: next sebagai kegagalan.

Jika XrEventDataReferenceSpaceChangePending diantrekan dan XrEventDataReferenceSpaceChangePending :: changeTime berlalu saat aplikasi mengkueri data komponen dari XrSpatialSnapshotEXT , aplikasi dapat menggunakan data peristiwa untuk menyesuaikan pose yang sesuai.

Runtime harus mengisi XrSpatialComponentDataQueryResultEXT :: entityIds hanya dengan entity yang memiliki semua komponen yang ditentukan dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes . Jika XrSpatialComponentDataQueryConditionEXT :: componentTypeCount adalah 0, runtime harus mengisi queryResult dengan semua entity (dan status pelacakannya) yang ada dalam snapshot. Jika kondisi kueri tambahan ditambahkan ke XrSpatialComponentDataQueryConditionEXT :: next , runtime harus memperlakukannya sebagai "AND" dengan ketersediaan jenis komponen, yaitu runtime harus mengisi XrSpatialComponentDataQueryResultEXT ::entityIds hanya dengan entity yang memenuhi semua kondisi yang diberikan. Runtime harus mengisi data komponen dalam struktur daftar dalam urutan yang sama dengan entitas di XrSpatialComponentDataQueryResultEXT :: entityIds yaitu data komponen pada indeks tertentu dalam array struktur daftar harus sesuai dengan entitas pada indeks yang sama.

Jika status pelacakan untuk entity bukan XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT , runtime tidak boleh mengubah data pada indeks yang sesuai dengan entity tersebut dalam array yang terdapat dalam struktur daftar yang terlampir ke XrSpatialComponentDataQueryResultEXT .

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

Sebagai contoh, aplikasi membuat XrSpatialSnapshotEXT yang berisi 5 entitas, dengan -

  • Entitas 1 dan 2 memiliki komponen XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT dan XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
  • Entitas 3 dan 4 memiliki komponen XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT dan XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
  • Entitas 5 memiliki komponen XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT dan XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT .

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

3

3

4

4

5

5

Bounded2D

Bounded2D

Ya

Ya

Ya

Ya

Tidak

Tidak

Tidak

Tidak

Ya

Ya

Orang tua

Orang tua

Ya

Ya

Ya

Ya

Tidak

Tidak

Tidak

Tidak

Tidak

Tidak

Mesh3D

Mesh3D

Tidak

Tidak

Tidak

Tidak

Ya

Ya

Ya

Ya

Ya

Ya

Bounded3D

Bounded3D

Tidak

Tidak

Tidak

Tidak

Ya

Ya

Ya

Ya

Tidak

Tidak ada Teks bukan SVG - tidak dapat ditampilkan

Gambar 20. Contoh ringkasan

xrQuerySpatialComponentDataEXT pada snapshot di atas dengan XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT yang tercantum dalam kondisi kueri akan menghasilkan entity #1, #2, dan #5 yang ditampilkan ke aplikasi dan aplikasi dapat melampirkan array XrSpatialBounded2DDataEXT sebagai bagian dari struktur XrSpatialComponentBounded2DListEXT ke rantai XrSpatialComponentDataQueryResultEXT berikutnya untuk mendapatkan data bounded2D.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

5

5

Bounded2D

Bounded2D

Data untuk entityId #1

Data untuk entit...

Data untuk entityId #2

Data untuk entit...

Data untuk entityId #5

Data untuk entit...

entityIds

entityIds

berikutnya

berikutnya

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

batas

batas

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou... Teks bukan SVG - tidak dapat ditampilkan

Gambar 21. Contoh hasil kueri

xrQuerySpatialComponentDataEXT pada snapshot di atas dengan komponen XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT dan XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT yang tercantum dalam kondisi kueri akan menghasilkan entitas #3 dan #4 yang ditampilkan ke aplikasi dan aplikasi dapat melampirkan array XrBoxf dan XrSpatialMeshDataEXT sebagai bagian dari struktur XrSpatialComponentBounded3DListEXT dan XrSpatialComponentMesh3DListEXT masing-masing ke rantai XrSpatialComponentDataQueryResultEXT berikutnya untuk mendapatkan data komponen.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

Data untuk entityId #3

Data untuk entit...

Data untuk entityId #4

Data untuk entit...

Mesh3D

Mesh3D

Data untuk entityId #3

Data untuk entit...

Data untuk entityId #4

Data untuk entit...

entityIds

entityIds

berikutnya

berikutnya

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

batas

batas

berikutnya

berikutnya

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

mesh

meshes Text is not SVG - cannot display

Gambar 22. Contoh hasil kueri

Struktur XrSpatialComponentDataQueryConditionEXT ditentukan sebagai:

typedef struct XrSpatialComponentDataQueryConditionEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialComponentDataQueryConditionEXT;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • componentTypeCount adalah uint32_t yang menjelaskan jumlah elemen dalam array componentTypes.
  • componentTypes adalah array XrSpatialComponentTypeEXT yang datanya akan diambil dari snapshot.

Penggunaan yang Valid (Implisit)

Struktur XrSpatialComponentDataQueryResultEXT ditentukan sebagai:

typedef struct XrSpatialComponentDataQueryResultEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            entityIdCapacityInput;
    uint32_t                            entityIdCountOutput;
    XrSpatialEntityIdEXT*               entityIds;
    uint32_t                            entityStateCapacityInput;
    uint32_t                            entityStateCountOutput;
    XrSpatialEntityTrackingStateEXT*    entityStates;
} XrSpatialComponentDataQueryResultEXT;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • entityIdCapacityInput adalah kapasitas array entityIds, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • entityIdCountOutput adalah jumlah XrSpatialEntityIdEXT dalam entityIds , atau kapasitas yang diperlukan jika entityIdCapacityInput tidak mencukupi.
  • entityIds adalah array XrSpatialEntityIdEXT . Nilainya dapat berupa NULL jika entityIdCapacityInput adalah 0.
  • entityStateCapacityInput adalah kapasitas array entityStates, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • entityStateCountOutput adalah jumlah XrSpatialEntityTrackingStateEXT dalam entityStates , atau kapasitas yang diperlukan jika entityStateCapacityInput tidak mencukupi. Harus selalu sama dengan entityIdCountOutput .
  • entityStates adalah array XrSpatialEntityTrackingStateEXT . Nilainya dapat berupa NULL jika entityStateCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran entityIds yang diperlukan.

Aplikasi dapat menggunakan entityIds dengan xrCreateSpatialEntityFromIdEXT untuk membuat handle XrSpatialEntityEXT untuk entity yang ingin mendapatkan update rutinnya. Aplikasi dapat menggunakan handle XrSpatialEntityEXT ini dengan xrCreateSpatialUpdateSnapshotEXT untuk membuat snapshot update yang memiliki data komponen terbaru yang diketahui runtime untuk entitas yang disediakan.

Penggunaan yang Valid (Implisit)

typedef enum XrSpatialEntityTrackingStateEXT {
    XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT = 1,
    XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT = 2,
    XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT = 3,
    XR_SPATIAL_ENTITY_TRACKING_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialEntityTrackingStateEXT;

XrSpatialEntityTrackingStateEXT menghitung kemungkinan status pelacakan entity spasial:

Enum memiliki arti berikut:

Deskripsi Enum

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

Runtime telah berhenti melacak entitas ini dan tidak akan pernah melanjutkan pelacakannya.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

Runtime telah menjeda pelacakan entitas ini, tetapi dapat melanjutkan pelacakannya pada masa mendatang.

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

Runtime saat ini melacak entitas ini dan data komponennya valid.

PELACAKAN

DIJEDA

DIHENTIKAN

Gambar 23. XrSpatialEntityTrackingStateEXT

  • Runtime dapat mengubah status entitas spasial dari XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT menjadi XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT jika menangguhkan pelacakan entitas spasial tersebut, tetapi memiliki kemungkinan untuk melanjutkan pelacakannya pada masa mendatang. Beberapa contoh saat runtime dapat melakukan hal ini mencakup (tetapi tidak terbatas pada) jika aplikasi kehilangan fokus input; atau jika entitas spasial yang diberikan terlalu jauh dari pengguna untuk dilacak secara akurat; atau jika ada terlalu banyak entitas yang dilacak dan runtime ingin mengurangi biaya pelacakan. XrSpatialEntityTrackingStateEXT membantu aplikasi mengisolasi dirinya dari berbagai kebijakan pelacakan setiap runtime.
  • Runtime dapat mengubah status entitas dari XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT menjadi XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT atau XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT .
  • Runtime harus mengubah status entity spasial dari XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT atau XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT menjadi XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT jika entity spasial hilang dan pelacakannya tidak akan pernah dipulihkan atau dilanjutkan. Contoh kasus seperti ini adalah jika perangkat kehilangan pelacakan, memulai ulang sesi pelacakannya, tetapi tidak dapat melokalisasi ulang di lingkungannya, sehingga memperlakukan entity yang ditemukan dalam sesi pelacakan ini sebagai entity baru.
  • Setelah status pelacakan entity disetel ke XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , runtime tidak boleh mengubahnya ke status lain.
  • Saat membuat kueri data komponen entitas spasial menggunakan xrQuerySpatialComponentDataEXT , runtime harus menyetel data yang valid dalam konten buffer yang disediakan oleh aplikasi dalam rantai XrSpatialComponentDataQueryResultEXT berikutnya jika status entitas adalah XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . Jika status entitas adalah XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT atau XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT , runtime tidak boleh mengubah konten buffer.

Idiom dua panggilan untuk data komponen

Struktur XrSpatialBufferEXT ditentukan sebagai:

typedef struct XrSpatialBufferEXT {
    XrSpatialBufferIdEXT      bufferId;
    XrSpatialBufferTypeEXT    bufferType;
} XrSpatialBufferEXT;

Deskripsi Anggota

  • bufferId XrSpatialBufferIdEXT data buffer.
  • bufferType adalah XrSpatialBufferTypeEXT untuk menunjukkan jenis data di bufferId . Aplikasi dapat menggunakan bufferType untuk menentukan fungsi mana yang akan digunakan untuk mengambil data buffer yang sebenarnya.

Beberapa komponen spasial memiliki data berukuran variabel dan oleh karena itu memerlukan penggunaan idioma dua panggilan untuk mengambil datanya. Dalam kasus seperti itu, struktur data komponen spasial menyediakan XrSpatialBufferEXT untuk setiap buffer berukuran variabel yang diperlukan dalam data komponen tersebut.

Untuk bufferId yang sama , runtime harus memberikan data yang sama dari satu kueri data komponen ke kueri data komponen lainnya, bahkan dari satu snapshot ke snapshot lainnya. bufferId yang berbeda di antara panggilan kueri data komponen menunjukkan kepada aplikasi bahwa data untuk komponen tersebut mungkin telah berubah.

Penggunaan yang Valid (Implisit)

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT digunakan untuk merepresentasikan semua jenis data berukuran variabel untuk komponen spasial.

Runtime harus menyimpan XrSpatialBufferIdEXT dan datanya dalam memori setidaknya selama siklus proses XrSpatialSnapshotEXT yang memuatnya. Runtime dapat menyimpan XrSpatialBufferIdEXT dan datanya dalam memori lebih lama daripada siklus proses XrSpatialSnapshotEXT untuk menampilkan ID yang sama sebagai bagian dari snapshot yang dibuat nanti oleh aplikasi. Untuk XrSpatialBufferIdEXT yang sama , runtime harus selalu menampilkan data yang sama melalui fungsi xrGetSpatialBuffer* yang sesuai.

typedef enum XrSpatialBufferTypeEXT {
    XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT = 0,
    XR_SPATIAL_BUFFER_TYPE_STRING_EXT = 1,
    XR_SPATIAL_BUFFER_TYPE_UINT8_EXT = 2,
    XR_SPATIAL_BUFFER_TYPE_UINT16_EXT = 3,
    XR_SPATIAL_BUFFER_TYPE_UINT32_EXT = 4,
    XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT = 5,
    XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT = 6,
    XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT = 7,
    XR_SPATIAL_BUFFER_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialBufferTypeEXT;

Enumerasi XrSpatialBufferTypeEXT mengidentifikasi berbagai jenis data buffer yang direpresentasikan XrSpatialBufferIdEXT .

Deskripsi Enumeran

Fungsi xrGetSpatialBufferStringEXT ditentukan sebagai:

XrResult xrGetSpatialBufferStringEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Deskripsi Parameter

  • snapshot adalah handle ke XrSpatialSnapshotEXT .
  • info menyimpan informasi tentang buffer yang akan dikueri.
  • bufferCapacityInput adalah kapasitas array, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • bufferCountOutput adalah jumlah karakter, atau kapasitas yang diperlukan jika bufferCapacityInput tidak mencukupi.
  • buffer adalah array char . Nilainya dapat berupa NULL jika bufferCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran buffer yang diperlukan.

Aplikasi dapat mendapatkan data untuk XrSpatialBufferEXT yang disediakan oleh komponen, dengan XrSpatialBufferEXT :: bufferType adalah XR_SPATIAL_BUFFER_TYPE_STRING_EXT dengan menggunakan xrGetSpatialBufferStringEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika XrSpatialBufferTypeEXT untuk XrSpatialBufferGetInfoEXT :: bufferId bukan XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT jika XrSpatialBufferGetInfoEXT :: bufferId bukan milik snapshot .

buffer yang diisi oleh runtime harus berupa string UTF-8 yang diakhiri dengan null.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_EXT_spatial_entity harus diaktifkan sebelum memanggil xrGetSpatialBufferStringEXT
  • snapshot harus berupa handle XrSpatialSnapshotEXT yang valid
  • info harus berupa pointer ke struktur XrSpatialBufferGetInfoEXT yang valid
  • bufferCountOutput harus berupa pointer ke nilai uint32_t
  • Jika bufferCapacityInput bukan 0 , buffer harus berupa pointer ke array nilai char bufferCapacityInput

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

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

Fungsi xrGetSpatialBufferUint8EXT ditentukan sebagai:

XrResult xrGetSpatialBufferUint8EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

Deskripsi Parameter

  • snapshot adalah handle ke XrSpatialSnapshotEXT .
  • info menyimpan informasi tentang buffer yang akan dikueri.
  • bufferCapacityInput adalah kapasitas array, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • bufferCountOutput adalah jumlah elemen dalam array buffer, atau kapasitas yang diperlukan jika bufferCapacityInput tidak mencukupi.
  • buffer adalah array uint8_t . Nilainya dapat berupa NULL jika bufferCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran buffer yang diperlukan.

Aplikasi dapat mendapatkan data untuk XrSpatialBufferEXT yang disediakan oleh komponen, dengan XrSpatialBufferEXT :: bufferType adalah XR_SPATIAL_BUFFER_TYPE_UINT8_EXT dengan menggunakan xrGetSpatialBufferUint8EXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika XrSpatialBufferTypeEXT untuk XrSpatialBufferGetInfoEXT :: bufferId bukan XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT jika XrSpatialBufferGetInfoEXT :: bufferId bukan milik snapshot .

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_EXT_spatial_entity harus diaktifkan sebelum memanggil xrGetSpatialBufferUint8EXT
  • snapshot harus berupa handle XrSpatialSnapshotEXT yang valid
  • info harus berupa pointer ke struktur XrSpatialBufferGetInfoEXT yang valid
  • bufferCountOutput harus berupa pointer ke nilai uint32_t
  • Jika bufferCapacityInput bukan 0 , buffer harus berupa pointer ke array nilai bufferCapacityInput uint8_t

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

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

Fungsi xrGetSpatialBufferUint16EXT ditentukan sebagai:

XrResult xrGetSpatialBufferUint16EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint16_t*                                   buffer);

Deskripsi Parameter

  • snapshot adalah handle ke XrSpatialSnapshotEXT .
  • info menyimpan informasi tentang buffer yang akan dikueri.
  • bufferCapacityInput adalah kapasitas array, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • bufferCountOutput adalah jumlah elemen dalam array buffer, atau kapasitas yang diperlukan jika bufferCapacityInput tidak mencukupi.
  • buffer adalah array uint16_t . Nilainya dapat berupa NULL jika bufferCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran buffer yang diperlukan.

Aplikasi dapat mendapatkan data untuk XrSpatialBufferEXT yang disediakan oleh komponen, dengan XrSpatialBufferEXT :: bufferType adalah XR_SPATIAL_BUFFER_TYPE_UINT16_EXT menggunakan xrGetSpatialBufferUint16EXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika XrSpatialBufferTypeEXT untuk XrSpatialBufferGetInfoEXT :: bufferId bukan XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT jika XrSpatialBufferGetInfoEXT :: bufferId bukan milik snapshot .

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_EXT_spatial_entity harus diaktifkan sebelum memanggil xrGetSpatialBufferUint16EXT
  • snapshot harus berupa handle XrSpatialSnapshotEXT yang valid
  • info harus berupa pointer ke struktur XrSpatialBufferGetInfoEXT yang valid
  • bufferCountOutput harus berupa pointer ke nilai uint32_t
  • Jika bufferCapacityInput bukan 0 , buffer harus berupa pointer ke array nilai bufferCapacityInput uint16_t

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

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

Fungsi xrGetSpatialBufferUint32EXT ditentukan sebagai:

XrResult xrGetSpatialBufferUint32EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint32_t*                                   buffer);

Deskripsi Parameter

  • snapshot adalah handle ke XrSpatialSnapshotEXT .
  • info menyimpan informasi tentang buffer yang akan dikueri.
  • bufferCapacityInput adalah kapasitas array, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • bufferCountOutput adalah jumlah elemen dalam array buffer, atau kapasitas yang diperlukan jika bufferCapacityInput tidak mencukupi.
  • buffer adalah array uint32_t . Nilainya dapat berupa NULL jika bufferCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran buffer yang diperlukan.

Aplikasi dapat mendapatkan data untuk XrSpatialBufferEXT yang disediakan oleh komponen, dengan XrSpatialBufferEXT :: bufferType adalah XR_SPATIAL_BUFFER_TYPE_UINT32_EXT menggunakan xrGetSpatialBufferUint32EXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika XrSpatialBufferTypeEXT untuk XrSpatialBufferGetInfoEXT :: bufferId bukan XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT jika XrSpatialBufferGetInfoEXT :: bufferId bukan milik snapshot .

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_EXT_spatial_entity harus diaktifkan sebelum memanggil xrGetSpatialBufferUint32EXT
  • snapshot harus berupa handle XrSpatialSnapshotEXT yang valid
  • info harus berupa pointer ke struktur XrSpatialBufferGetInfoEXT yang valid
  • bufferCountOutput harus berupa pointer ke nilai uint32_t
  • Jika bufferCapacityInput bukan 0 , buffer harus berupa pointer ke array nilai bufferCapacityInput uint32_t

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

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

Fungsi xrGetSpatialBufferFloatEXT ditentukan sebagai:

XrResult xrGetSpatialBufferFloatEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    float*                                      buffer);

Deskripsi Parameter

  • snapshot adalah handle ke XrSpatialSnapshotEXT .
  • info menyimpan informasi tentang buffer yang akan dikueri.
  • bufferCapacityInput adalah kapasitas array, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • bufferCountOutput adalah jumlah elemen dalam array buffer, atau kapasitas yang diperlukan jika bufferCapacityInput tidak mencukupi.
  • buffer adalah array float . Nilainya dapat berupa NULL jika bufferCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran buffer yang diperlukan.

Aplikasi dapat mendapatkan data untuk XrSpatialBufferEXT yang disediakan oleh komponen, dengan XrSpatialBufferEXT :: bufferType adalah XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT menggunakan xrGetSpatialBufferFloatEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika XrSpatialBufferTypeEXT untuk XrSpatialBufferGetInfoEXT :: bufferId bukan XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT jika XrSpatialBufferGetInfoEXT :: bufferId bukan milik snapshot .

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_EXT_spatial_entity harus diaktifkan sebelum memanggil xrGetSpatialBufferFloatEXT
  • snapshot harus berupa handle XrSpatialSnapshotEXT yang valid
  • info harus berupa pointer ke struktur XrSpatialBufferGetInfoEXT yang valid
  • bufferCountOutput harus berupa pointer ke nilai uint32_t
  • Jika bufferCapacityInput bukan 0 , buffer harus berupa pointer ke array nilai bufferCapacityInput float

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

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

Fungsi xrGetSpatialBufferVector2fEXT ditentukan sebagai:

XrResult xrGetSpatialBufferVector2fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector2f*                                 buffer);

Deskripsi Parameter

  • snapshot adalah handle ke XrSpatialSnapshotEXT .
  • info menyimpan informasi tentang buffer yang akan dikueri.
  • bufferCapacityInput adalah kapasitas array, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • bufferCountOutput adalah jumlah elemen dalam array buffer, atau kapasitas yang diperlukan jika bufferCapacityInput tidak mencukupi.
  • buffer adalah array XrVector2f . Nilainya dapat berupa NULL jika bufferCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran buffer yang diperlukan.

Aplikasi dapat mendapatkan data untuk XrSpatialBufferEXT yang disediakan oleh komponen, dengan XrSpatialBufferEXT :: bufferType adalah XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT menggunakan xrGetSpatialBufferVector2fEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika XrSpatialBufferTypeEXT untuk XrSpatialBufferGetInfoEXT :: bufferId bukan XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT jika XrSpatialBufferGetInfoEXT :: bufferId bukan milik snapshot .

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

Fungsi xrGetSpatialBufferVector3fEXT ditentukan sebagai:

XrResult xrGetSpatialBufferVector3fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector3f*                                 buffer);

Deskripsi Parameter

  • snapshot adalah handle ke XrSpatialSnapshotEXT .
  • info menyimpan informasi tentang buffer yang akan dikueri.
  • bufferCapacityInput adalah kapasitas array, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • bufferCountOutput adalah jumlah elemen dalam array buffer, atau kapasitas yang diperlukan jika bufferCapacityInput tidak mencukupi.
  • buffer adalah array XrVector3f . Nilainya dapat berupa NULL jika bufferCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran buffer yang diperlukan.

Aplikasi dapat mendapatkan data untuk XrSpatialBufferEXT yang disediakan oleh komponen, dengan XrSpatialBufferEXT :: bufferType adalah XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT menggunakan xrGetSpatialBufferVector3fEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika XrSpatialBufferTypeEXT untuk XrSpatialBufferGetInfoEXT :: bufferId bukan XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

Runtime harus menampilkan XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT jika XrSpatialBufferGetInfoEXT :: bufferId bukan milik snapshot .

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrSpatialBufferGetInfoEXT ditentukan sebagai:

typedef struct XrSpatialBufferGetInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialBufferIdEXT    bufferId;
} XrSpatialBufferGetInfoEXT;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • bufferId XrSpatialBufferIdEXT untuk buffer yang datanya akan diambil.

Penggunaan yang Valid (Implisit)

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT adalah nilai yang dicadangkan yang merepresentasikan XrSpatialBufferIdEXT yang tidak valid . Nilai ini dapat diteruskan ke dan ditampilkan dari fungsi API hanya jika diizinkan secara khusus.

Buat Update Snapshot

Fungsi xrCreateSpatialUpdateSnapshotEXT ditentukan sebagai:

XrResult xrCreateSpatialUpdateSnapshotEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialUpdateSnapshotCreateInfoEXT* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

Deskripsi Parameter

Aplikasi dapat menggunakan xrCreateSpatialUpdateSnapshotEXT untuk membuat snapshot dan mendapatkan data komponen terbaru untuk entity tertentu seperti yang diketahui oleh runtime. Aplikasi dapat memberikan handle XrSpatialEntityEXT dan jenis komponen yang mereka minati saat membuat snapshot.

Aplikasi dapat menggunakan XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes untuk memfilter daftar komponen yang datanya harus disertakan dalam snapshot. Jika aplikasi menyediakan daftar jenis komponen spasial yang valid di XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , maka runtime harus hanya menyertakan entitas spasial dalam snapshot yang memiliki setidaknya salah satu komponen yang disediakan di XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Selain itu, runtime hanya boleh menyertakan data untuk komponen tersebut dalam snapshot.

Runtime harus menampilkan XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT jika ada XrSpatialComponentTypeEXT di XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes yang tidak diaktifkan untuk kemampuan spasial yang diteruskan ke XrSpatialContextCreateInfoEXT :: capabilityConfigs saat membuat spatialContext .

Jika aplikasi tidak menyediakan daftar jenis komponen spasial di XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , runtime harus menyertakan semua entitas spasial yang tercantum di XrSpatialUpdateSnapshotCreateInfoEXT :: entities dalam snapshot dan harus menyertakan data untuk semua komponen yang diaktifkan dari kemampuan yang dikonfigurasi untuk spatialContext .

Runtime tidak boleh menyertakan entitas spasial yang tidak tercantum dalam XrSpatialUpdateSnapshotCreateInfoEXT :: entities di snapshot .

Aplikasi dapat membuat sejumlah snapshot yang diinginkan, tetapi harus memperhatikan memori yang dialokasikan untuk setiap snapshot baru dan harus menghapus snapshot setelah tidak lagi diperlukan.

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_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrSpatialUpdateSnapshotCreateInfoEXT ditentukan sebagai:

typedef struct XrSpatialUpdateSnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            entityCount;
    const XrSpatialEntityEXT*           entities;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
    XrSpace                             baseSpace;
    XrTime                              time;
} XrSpatialUpdateSnapshotCreateInfoEXT;

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.
  • entityCount adalah uint32_t yang menjelaskan jumlah elemen dalam array entities.
  • entities adalah array XrSpatialEntityEXT yang komponen datanya harus disertakan dalam snapshot oleh runtime.
  • componentTypeCount adalah uint32_t yang menjelaskan jumlah elemen dalam array componentTypes.
  • componentTypes adalah array XrSpatialComponentTypeEXT yang datanya harus disertakan dalam snapshot oleh runtime.
  • baseSpace adalah XrSpace relatif terhadap semua lokasi XrSpatialSnapshotEXT yang diperbarui.
  • time adalah XrTime tempat semua lokasi update XrSpatialSnapshotEXT akan berada.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_EXT_spatial_entity harus diaktifkan sebelum menggunakan XrSpatialUpdateSnapshotCreateInfoEXT
  • type harus berupa XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
  • next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
  • entities harus berupa pointer ke array entityCount handle XrSpatialEntityEXT yang valid
  • Jika componentTypeCount bukan 0 , componentTypes harus berupa pointer ke array nilai XrSpatialComponentTypeEXT yang valid componentTypeCount
  • baseSpace harus berupa handle XrSpace yang valid
  • Parameter entityCount harus lebih besar dari 0
  • baseSpace dan elemen entities harus dibuat, dialokasikan, atau diambil dari XrSession yang sama

Menghancurkan snapshot

Fungsi xrDestroySpatialSnapshotEXT ditentukan sebagai:

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

Deskripsi Parameter

Aplikasi dapat memanggil xrDestroySpatialSnapshotEXT untuk menghancurkan handle XrSpatialSnapshotEXT dan resource yang terkait dengannya.

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke snapshot , dan semua handle turunan, harus disinkronkan secara eksternal

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Komponen Umum

2D Terikat

Data komponen

Struktur XrSpatialBounded2DDataEXT ditentukan sebagai:

typedef struct XrSpatialBounded2DDataEXT {
    XrPosef        center;
    XrExtent2Df    extents;
} XrSpatialBounded2DDataEXT;

Deskripsi Anggota

  • center adalah XrPosef yang menentukan pusat geometris komponen 2D yang dibatasi.
  • extents adalah rentang komponen 2D yang dibatasi di sepanjang sumbu x (extents.width), sumbu y (extents.height), yang berpusat pada center .

extents dari XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT mengacu pada ukuran entitas dalam bidang x-y dari sistem koordinat bidang. Bidang dengan posisi {0, 0, 0}, rotasi {0, 0, 0, 1} (tanpa rotasi), dan rentang {1, 1} mengacu pada bidang 1 meter x 1 meter yang berpusat di {0, 0, 0} dengan vektor normal permukaan depannya mengarah ke arah +Z dalam ruang komponen.

X X Y Y Z Z Tinggi Tinggi Y Y Z Z X X Bidang vertikal Bidang vertikal Bidang Horizontal Bidang Horizontal Lebar Lebar Lebar Lebar Tinggi Tinggi

Gambar 24. Sistem Koordinat Komponen Bounded2D

Catatan

OpenXR menggunakan bidang X-Y dengan +Z sebagai normal bidang, tetapi API lain dapat menggunakan bidang X-Z dengan +Y sebagai normal bidang. Bidang X-Y dapat dikonversi menjadi bidang X-Z dengan memutar -π/2 radian di sekitar sumbu +X.

Penggunaan yang Valid (Implisit)

Struktur daftar komponen untuk membuat kueri data

Struktur XrSpatialComponentBounded2DListEXT ditentukan sebagai:

typedef struct XrSpatialComponentBounded2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      boundCount;
    XrSpatialBounded2DDataEXT*    bounds;
} XrSpatialComponentBounded2DListEXT;

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.
  • boundCount adalah uint32_t yang menjelaskan jumlah elemen dalam array bounds.
  • bounds adalah array XrSpatialBounded2DDataEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrQuerySpatialComponentDataEXT jika XrSpatialComponentBounded2DListEXT ada di rantai XrSpatialComponentDataQueryResultEXT berikutnya :: next tetapi XrSpatialComponentDataQueryConditionEXT ::componentTypeCount tidak nol dan XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT tidak disertakan dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Jika xrQuerySpatialComponentDataEXT :: snapshot dibuat dari xrCreateSpatialDiscoverySnapshotCompleteEXT , maka runtime harus menyediakan XrSpatialBounded2DDataEXT :: center di XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace dan XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Jika xrQuerySpatialComponentDataEXT :: snapshot dibuat dari xrCreateSpatialUpdateSnapshotEXT , maka runtime harus menyediakan XrSpatialBounded2DDataEXT :: center di XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace dan XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Penggunaan yang Valid (Implisit)

Konfigurasi

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

3D yang dibatasi

Data komponen

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT menggunakan XrBoxf untuk datanya.

Struktur daftar komponen untuk membuat kueri data

Struktur XrSpatialComponentBounded3DListEXT ditentukan sebagai:

typedef struct XrSpatialComponentBounded3DListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           boundCount;
    XrBoxf*            bounds;
} XrSpatialComponentBounded3DListEXT;

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.
  • boundCount adalah uint32_t yang menjelaskan jumlah elemen dalam array bounds.
  • bounds adalah array XrBoxf .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrQuerySpatialComponentDataEXT jika XrSpatialComponentBounded3DListEXT ada di rantai XrSpatialComponentDataQueryResultEXT :: next berikutnya, tetapi XrSpatialComponentDataQueryConditionEXT ::componentTypeCount tidak nol dan XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT tidak disertakan dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Jika xrQuerySpatialComponentDataEXT :: snapshot dibuat dari xrCreateSpatialDiscoverySnapshotCompleteEXT , maka runtime harus menyediakan XrBoxf :: center di XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace pada XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Jika xrQuerySpatialComponentDataEXT :: snapshot dibuat dari xrCreateSpatialUpdateSnapshotEXT , maka runtime harus menyediakan XrBoxf :: center di XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace pada XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Penggunaan yang Valid (Implisit)

Konfigurasi

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

Orang tua

Data komponen

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT menggunakan XrSpatialEntityIdEXT untuk datanya.

Struktur daftar komponen untuk membuat kueri data

Struktur XrSpatialComponentParentListEXT ditentukan sebagai:

typedef struct XrSpatialComponentParentListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 parentCount;
    XrSpatialEntityIdEXT*    parents;
} XrSpatialComponentParentListEXT;

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.
  • parentCount adalah uint32_t yang menjelaskan jumlah elemen dalam array parents.
  • parents adalah array XrSpatialEntityIdEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrQuerySpatialComponentDataEXT jika XrSpatialComponentParentListEXT ada di rantai XrSpatialComponentDataQueryResultEXT berikutnya :: next, tetapi XrSpatialComponentDataQueryConditionEXT ::componentTypeCount bukan nol dan XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT tidak disertakan dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_EXT_spatial_entity harus diaktifkan sebelum menggunakan XrSpatialComponentParentListEXT
  • type harus berupa XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
  • next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
  • parents harus berupa pointer ke array nilai parentCount XrSpatialEntityIdEXT
  • Parameter parentCount harus lebih besar dari 0
Konfigurasi

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

Mesh 3D

Data komponen

Struktur XrSpatialMeshDataEXT ditentukan sebagai:

typedef struct XrSpatialMeshDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
    XrSpatialBufferEXT    indexBuffer;
} XrSpatialMeshDataEXT;

Deskripsi Anggota

  • origin adalah XrPosef yang menentukan asal mesh. Semua verteks mesh harus relatif terhadap asal ini.
  • vertexBuffer adalah XrSpatialBufferEXT yang menyediakan ID untuk buffer yang merepresentasikan buffer vertex entitas yang menggunakan komponen ini. Posisi verteks harus relatif terhadap origin .
  • indexBuffer adalah XrSpatialBufferEXT yang memberikan ID untuk buffer yang merepresentasikan array indeks segitiga, yang menentukan indeks verteks mesh di vertexBuffer . Indeks segitiga harus ditampilkan dalam urutan berlawanan arah jarum jam dan tiga indeks menunjukkan satu segitiga.

Jenis komponen yang menggunakan XrSpatialMeshDataEXT harus menentukan XrSpatialBufferTypeEXT dari vertexBuffer dan indexBuffer .

Penggunaan yang Valid (Implisit)

Struktur daftar komponen untuk membuat kueri data

Struktur XrSpatialComponentMesh3DListEXT ditentukan sebagai:

typedef struct XrSpatialComponentMesh3DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh3DListEXT;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • meshCount adalah uint32_t yang menjelaskan jumlah elemen dalam array meshes.
  • meshes adalah array XrSpatialMeshDataEXT .

Aplikasi dapat mengkueri komponen 3D mesh entitas spasial dalam XrSpatialSnapshotEXT dengan menambahkan XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT di XrSpatialComponentDataQueryConditionEXT :: componentTypes dan menambahkan XrSpatialComponentMesh3DListEXT ke rantai penunjuk berikutnya dari XrSpatialComponentDataQueryResultEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrQuerySpatialComponentDataEXT jika XrSpatialComponentMesh3DListEXT ada di rantai XrSpatialComponentDataQueryResultEXT :: next berikutnya, tetapi XrSpatialComponentDataQueryConditionEXT ::componentTypeCount tidak nol dan XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT tidak disertakan dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Untuk XrSpatialMeshDataEXT yang diisi oleh runtime dalam array meshes, XrSpatialBufferEXT :: bufferType untuk XrSpatialMeshDataEXT :: vertexBuffer harus berupa XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT dan XrSpatialBufferEXT :: bufferType untuk XrSpatialMeshDataEXT :: indexBuffer harus berupa XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Penggunaan yang Valid (Implisit)

Konfigurasi

Jika XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT tercantum dalam XrSpatialCapabilityComponentTypesEXT :: componentTypes untuk beberapa kemampuan, aplikasi dapat mengaktifkannya dengan menyertakan enum dalam daftar XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents dari kemampuan yang mendukung komponen ini dalam struktur turunan XrSpatialCapabilityConfigurationBaseHeaderEXT.

Komponen ini tidak memerlukan konfigurasi khusus untuk disertakan dalam rantai XrSpatialCapabilityConfigurationBaseHeaderEXT berikutnya .

Filter status pelacakan

Struktur XrSpatialFilterTrackingStateEXT ditentukan sebagai:

typedef struct XrSpatialFilterTrackingStateEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialEntityTrackingStateEXT    trackingState;
} XrSpatialFilterTrackingStateEXT;

Deskripsi Anggota

Aplikasi dapat menggunakan XrSpatialFilterTrackingStateEXT dalam rangkaian XrSpatialDiscoverySnapshotCreateInfoEXT berikutnya untuk mencakup penemuan hanya pada entitas yang status pelacakannya adalah trackingState .

Aplikasi dapat menggunakan XrSpatialFilterTrackingStateEXT dalam rantai XrSpatialComponentDataQueryConditionEXT berikutnya untuk mencakup kueri data komponen dari hanya snapshot ke entitas yang status pelacakannya adalah trackingState .

Penggunaan yang Valid (Implisit)

Kode contoh

Penggunaan Aplikasi

Aplikasi biasanya menggunakan ekstensi entitas spasial dengan pola berikut:

Menemukan entitas spasial & data komponen kueri

Contoh kode berikut menunjukkan cara menemukan entitas spasial untuk kemampuan "Foo" dan mengkueri data komponennya.

/****************************/
/* Capability definition    */
/****************************/
// Foo capability has the following components -
// - XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
#define XR_SPATIAL_CAPABILITY_FOO ((XrSpatialCapabilityEXT)1000740000U)

#define XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT ((XrStructureType)1000740000U)
// Derives from XrSpatialCapabilityConfigurationBaseHeaderEXT
typedef struct XrSpatialCapabilityConfigurationFooEXT {
  XrStructureType                     type;
  const void* XR_MAY_ALIAS            next;
  XrSpatialCapabilityEXT              capability;
  uint32_t                            enabledComponentCount;
  const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationFooEXT;

/******************************/
/* End capability definition  */
/******************************/

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

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  };

  // Configure Foo capability for the spatial context
  XrSpatialCapabilityConfigurationFooEXT fooConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT};
  fooConfig.capability = XR_SPATIAL_CAPABILITY_FOO;
  fooConfig.enabledComponentCount = enabledComponents.size();
  fooConfig.enabledComponents = enabledComponents.data();

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

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  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) {
    return;
  }

  spatialContext = completion.spatialContext;
}

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

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

  waitUntilReady(future);

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

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

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    queryResult.entityIdCapacityInput = 0;
    queryResult.entityIds = nullptr;
    queryResult.entityStateCapacityInput = 0;
    queryResult.entityStates = nullptr;
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

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

    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) {
        // 2D extents for entity entityIds[i] is bounded2d[i].extents.
      }
    }

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

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

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

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

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

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Mengkueri data buffer

Contoh kode berikut menunjukkan cara mendapatkan data komponen yang menyediakan XrSpatialBufferEXT .

/****************************/
/* Component definition     */
/****************************/
// Foo component that provides an XrVector3f buffer
#define XR_SPATIAL_COMPONENT_TYPE_FOO_EXT ((XrSpatialComponentTypeEXT)1000740000U)

#define XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT ((XrStructureType)1000740000U)

// XrSpatialComponentFooListEXT extends XrSpatialComponentDataQueryResultEXT
typedef struct XrSpatialComponentFooListEXT {
    XrStructureType                   type;
    void* XR_MAY_ALIAS                next;
    uint32_t                          fooCount;
    XrSpatialBufferEXT*               foo;
} XrSpatialComponentFooListEXT;

/******************************/
/* End Component definition  */
/******************************/

// Query for the foo component data
XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_FOO_EXT;
XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = &componentToQuery;

XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();

std::vector<XrSpatialBufferEXT> fooBuffers(queryResult.entityIdCountOutput);
XrSpatialComponentFooListEXT fooList{XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT};
fooList.fooCount = fooBuffers.size();
fooList.foo = fooBuffers.data();
queryResult.next = &fooList;

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

for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // foo component data for entity entityIds[i]
  if (fooBuffers[i].bufferType == XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT) {
    XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
    getInfo.bufferId = fooBuffers[i].bufferId;
    uint32_t bufferCountOutput;
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, 0, &bufferCountOutput, nullptr));
    std::vector<XrVector3f> vertexBuffer(bufferCountOutput);
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, bufferCountOutput, &bufferCountOutput, vertexBuffer.data()));

    // XrVertex3f buffer for entity entityIds[i] is now available in vertexBuffer vector.
  }
}

Panduan ekstensi

Pedoman Desain & Ekstensi Label Semantik

Meskipun ekstensi ini tidak menentukan komponen apa pun untuk menyampaikan informasi label semantik suatu entitas, ekstensi ini menetapkan aturan dan panduan desain untuk ekstensi apa pun yang menentukan komponen tersebut. Dalam teks berikut, " sebaiknya " dan " harus " membatasi penulis fungsi tersebut, bukan membatasi penerapan runtime atau aplikasi yang menggunakan API.

  • Jika ekstensi menentukan label semantik untuk XrSpatialCapabilityEXT , ekstensi tersebut harus melakukannya dengan menentukan XrSpatialComponentTypeEXT baru serta enumerasi baru dengan sekumpulan label ("kumpulan label semantik") sebagai data untuk komponen tersebut.
  • Enumerasi yang merepresentasikan set label semantik harus memiliki nilai untuk menunjukkan bahwa entitas tidak dikategorikan ke dalam label apa pun dalam set ini. Nama enumerasi ini harus menyertakan 'UNCATEGORIZED', misalnya XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT . Nilai ini menunjukkan kepada aplikasi bahwa runtime mengenali entitas ini, tetapi ada kumpulan label semantik lain tempat entitas ini dikategorikan.
  • Pencacahan XrSpatialComponentTypeEXT yang baru ditentukan ini di xrEnumerateSpatialCapabilityComponentTypesEXT menyiratkan bahwa runtime mendukung set label semantik (dan oleh karena itu, label yang ditentukan dalam set) yang sesuai dengan jenis komponen tersebut.
  • Aplikasi menyatakan keinginannya untuk menemukan entitas yang memiliki label yang termasuk dalam set label semantik ini dengan menyertakan XrSpatialComponentTypeEXT yang sesuai dalam array XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents dari struct konfigurasi untuk kemampuan yang jenis komponennya di-enum.
  • Satu entity spasial dapat memiliki beberapa komponen, yang masing-masing memberikan label dari set label semantiknya sendiri. Pertimbangkan contoh berikut dengan beberapa set label semantik hipotetis - XrSpatialObjectSemanticLabel, yang mungkin memiliki nilai seperti kursi, sofa, meja, dll., XrSpatialSofaBrand , yang mungkin memiliki nilai seperti IKEA, Wayfair, dll., dan XrSpatialIkeaSofa , yang mungkin memiliki nama model sofa IKEA tertentu. Dalam skenario ini, entitas sofa yang sama memiliki ketiga komponen (label dari ketiga set label semantik) di dalamnya, yang masing-masing memberikan informasi dengan perincian yang berbeda tentang entitas tersebut.
  • Jika ekstensi menentukan XrSpatialComponentTypeEXT baru yang menyediakan set label semantik baru yang berisi beberapa label selain label UNCATEGORIZED, ekstensi harus mempertimbangkan untuk menentukan XrSpatialCapabilityFeatureEXT yang memungkinkan aplikasi mengaktifkan hanya subset label yang ditentukan dalam set label semantik yang sesuai dengan jenis komponen tersebut. Subkumpulan ini, yang disediakan dalam rantai konfigurasi kemampuan berikutnya, berfungsi sebagai petunjuk bagi runtime untuk mengoptimalkan pipeline pelacakan dan hanya melacak subkumpulan yang disediakan. Contoh struct fitur tersebut diberikan di bawah .
  • Ekstensi tidak boleh menambahkan label ke enumerasi set label semantik yang ada. Sebagai gantinya, mereka harus menentukan enumerasi baru yang berisi enumeran yang setara dengan semantik yang identik dan dengan nilai yang sama dengan yang ada di set lainnya, selain enumeran yang baru ditambahkan. Spesifikasi set label semantik yang baru ditentukan harus juga menetapkan pemetaan antara set label lama dan yang baru. Lihat contoh di bawah .
Contoh Definisi Fitur Spasial untuk Subkumpulan Label Semantik
// New example semantic label set.
typedef enum XrSpatialExampleSemanticLabelEXT {
  // ... label values
} XrSpatialExampleSemanticLabelEXT;

/*
typedef enum XrSpatialCapabilityFeatureEXT {
  // .. existing values

  // new spatial feature value
  XR_SPATIAL_CAPABILITY_FEATURE_EXAMPLE_SEMANTIC_LABEL_SUBSET_EXT

  // .. existing values
} XrSpatialCapabilityFeatureEXT;
*/

// New spatial feaure configuration structure
typedef struct XrSpatialFeatureExampleSemanticLabelSubsetEXT {
    XrStructureType                             type;
    const void* XR_MAY_ALIAS                    next;
    uint32_t                                    semanticLabelCount;
    const XrSpatialExampleSemanticLabelEXT*     semanticLabels;
} XrSpatialFeatureExampleSemanticLabelSubsetEXT;
Contoh Ekstensi Label Semantik Spasial
typedef enum XrSpatialExamplePlaneSemanticLabelExtensionEXT {
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT = 2,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT = 3,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT = 4,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT = 5,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT = 6,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT = 7,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialExamplePlaneSemanticLabelExtensionEXT;

Pertimbangkan contoh di atas saat ekstensi menentukan enumerasi XrSpatialExamplePlaneSemanticLabelExtensionEXT untuk memperluas XrSpatialPlaneSemanticLabelEXT yang ada dengan nilai untuk merepresentasikan pintu dan jendela. Spesifikasi untuk enumerasi baru harus menyertakan teks untuk formulir berikut -

For all non-UNCATEGORIZED label enumerants in elink:XrSpatialPlaneSemanticLabelEXT,
the runtime must: return that enumerant if and only if it returns the corresponding
label enumerant from elink:XrSpatialExamplePlaneSemanticLabelExtensionEXT with the same value
i.e.
the ename:XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT value for that entity must:
correspond with the ename:XR_SPATIAL_COMPONENT_TYPE_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_EXT values
according to the following table -

[width="100%",options="header"]
|====
| XrSpatialExamplePlaneSemanticLabelExtensionEXT                | XrSpatialPlaneSemanticLabelEXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT | XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT  | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
|====

Makro Baru

Jenis Dudukan Baru

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

Jenis Objek Baru

Perintah Baru

Struktur Baru

Enum Baru

Konstanta Enum Baru

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • Memperluas XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • Memperluas XrResult :

    • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
    • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT

  • Memperluas XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
    • XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
    • XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT

Masalah

  • Apakah satu entitas selalu berasal dari satu kemampuan saja?

    • Selesai
    • Jawaban: Tidak. Hal ini sepenuhnya bergantung pada runtime berdasarkan kemampuan pelacakannya sendiri dan cara yang diinginkannya untuk merepresentasikan entitas yang terdeteksi. Spesifikasi tidak menetapkan representasi entitas spasial tertentu, kecuali untuk komponen terjamin dari kemampuan tertentu untuk menetapkan ekspektasi minimum. Runtime dapat menggabungkan entitas yang terdeteksi oleh kemampuan terpisah dan merepresentasikannya sebagai satu entitas dengan komponen terjamin dari semua kemampuan yang membantu mengidentifikasinya. Contohnya, meja dapat dideteksi oleh kemampuan pelacakan bidang dan kemampuan pelacakan objek, dengan pelacakan bidang menyediakan komponen XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT pada entity dan pelacakan objek menyediakan XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT . Runtime tertentu dapat menyediakan tabel sebagai 2 entitas terpisah, yang masing-masing memiliki serangkaian komponen yang dijamin, sementara runtime tertentu dapat menyediakan hanya 1 entitas untuk merepresentasikan tabel, dan memiliki XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT dan XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT pada entitas yang sama. Yang penting untuk diperhatikan di sini adalah bahwa entity spasial tertentu dapat memiliki paling banyak satu komponen dari jenis komponen tertentu . Oleh karena itu, jika data komponen yang dihasilkan oleh berbagai kemampuan bertentangan untuk entitas tertentu, runtime harus merepresentasikannya sebagai 2 entitas terpisah.

Riwayat Versi

  • Revisi 1, 12-04-2024 (Nihav Jain, Google)

    • Deskripsi ekstensi awal