موجودیت فضایی XR_EXT

رشته نام

XR_EXT_spatial_entity

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

۷۴۱

بازنگری

۱

وضعیت تصویب

تصویب شده

وابستگی‌های افزونه و نسخه

XR_EXT_future

مشارکت‌کنندگان

نیهاو جین، گوگل
جارد فایندر، گوگل
ناتالی فلوری، متا
یویچی تاگوچی، متا
ران بسمس، متا
یین لی، مایکروسافت
کارتیک کاداپان، جهش جادویی
جیمی آلمپارامبیل، بایت‌دنس
ژیپنگ لیو، ByteDance
جون یان، بایت‌دنس

نمای کلی

این افزونه مفاهیم و مبانی درک صحنه و استدلال مکانی را در OpenXR معرفی می‌کند. این افزونه چندین حوزه مرتبط اما متمایز از عملکرد را که به روشی کاملاً یکسان، همانطور که توسط این افزونه تعریف شده است، شمارش، پیکربندی و با آنها تعامل می‌شود، متحد می‌کند. از آنجایی که این افزونه فاقد تعاریف مشخصی از هر یک از این حوزه‌های عملکردی است، متن مشخصات رسمی تا حدودی انتزاعی است. مثال‌های موجود در متن مشخصات این افزونه، گاهی اوقات به عملکردهایی اشاره دارند که در یک افزونه مرتبط آینده یا فرضی برای توضیح تعریف شده‌اند، بدون اینکه ذاتاً چنین عملکردهای اضافی را محدود یا مشخص کنند.

بخش‌های کلی این افزونه به شرح زیر است:

  • موجودیت‌های مکانی : عملکرد حول موجودیت‌ها متمرکز شده است که به خودی خود عملکرد بسیار کمی ارائه می‌دهند.
  • اجزای مکانی : این موجودیت‌ها دارای اجزایی مرتبط با خود هستند که داده‌ها و رفتارها را ارائه می‌دهند.
  • انواع مؤلفه‌های مکانی : هر مؤلفه مکانی از یک نوع مؤلفه خاص است و هر موجودیت معین حداکثر یک مؤلفه از هر نوع مؤلفه معین دارد.
  • زمینه مکانی : تمام تعاملات موجودیت‌های مکانی پس از مرحله مقداردهی اولیه و پیکربندی، در یک زمینه رخ می‌دهد.
  • قابلیت‌های مکانی : دستکاری موجودیت‌های مکانی به طور گسترده توسط قابلیت‌ها ارائه می‌شود. یک قابلیت، واحدی از عملکرد است، به عنوان مثال (بدون محدودیت) لنگرهای تعریف شده توسط برنامه، تشخیص صفحه یا ردیابی تصویر. هر قابلیت معمولاً در یک افزونه جداگانه تعریف می‌شود (که طبق معمول در هنگام ایجاد نمونه فعال می‌شود) و در زمان ایجاد برای یک زمینه خاص فعال می‌شود.
  • هر قابلیت با مجموعه‌ای از انواع کامپوننت‌ها مرتبط است که کامپوننت‌های مربوط به آنها روی هر موجودیتی که توسط آن قابلیت نمایش داده می‌شود، وجود دارند. افزونه‌ای که یک قابلیت را تعریف می‌کند، مشخص می‌کند که کدام نوع کامپوننت برای آن قابلیت اجباری ("تضمین‌شده") است، در حالی که همان افزونه یا افزونه‌های دیگر ممکن است انواع کامپوننت‌های اختیاری ارائه شده توسط برخی پیاده‌سازی‌های بالقوه را مشخص کنند. هر تعداد قابلیت ممکن است کامپوننت‌هایی از یک نوع کامپوننت مشخص را در اختیار موجودیت‌ها قرار دهد که صرف نظر از قابلیتی که آن را تولید کرده است، به طور یکنواخت قابل استفاده هستند.
  • ویژگی‌های قابلیت مکانی : علاوه بر این، برخی از قابلیت‌ها نیاز به پیکربندی دارند و بنابراین توسط ویژگی‌های قابلیت پارامتربندی می‌شوند.

این افزونه مکانیزمی برای شمارش اجزای ارائه شده توسط هر قابلیت پشتیبانی شده در سیستم فعلی، چه اجزای اجباری و چه اجزای اختیاری ، ارائه می‌دهد.

از آنجایی که برخی پیاده‌سازی‌ها ممکن است به درجات مختلفی از پارامترسازی برای قابلیت‌ها نیاز داشته باشند، این افزونه مکانیزمی برای شمارش ویژگی‌های قابلیت پشتیبانی‌شده مرتبط با یک قابلیت مشخص در سیستم فعلی فراهم می‌کند.

این افزونه همچنین چندین مؤلفه مشترک را که انتظار می‌رود در طیف وسیعی از قابلیت‌ها مورد استفاده قرار گیرند، تعریف می‌کند.

موجودیت مکانی

موجودیت‌های مکانی، موجودیت‌هایی هستند که در فضایی وجود دارند و داده‌های مرتبط مختلفی را در قالب اجزایی سازماندهی کرده‌اند. آن‌ها می‌توانند هر یک از موارد زیر باشند:

  • فیزیکی (مثلاً سطوح مسطح مانند دیوارها و کف، اشیاء مانند صندلی‌ها و قفسه‌های کتاب و غیره)
  • مجازی (مثلاً محتوایی که توسط یک برنامه یا کاربر دیگر قرار داده شده و به اشتراک گذاشته شده است)،
  • تعریف‌شده توسط برنامه (مثلاً برنامه‌ای که یک منطقه را به عنوان "اتاق نشیمن" یا "آشپزخانه" علامت‌گذاری می‌کند، یا یک نقطه را به عنوان محل قرار دادن تلویزیون و غیره علامت‌گذاری می‌کند)

چیزهایی که از طریق سیستم اکشن در معرض دید قرار می‌گیرند، مانند کنترلرها یا نگاه چشم، قرار نیست به عنوان موجودیت‌های مکانی مدل‌سازی شوند.

موجودیت‌های مکانی در OpenXR به صورت یک سیستم Entity-Component مدل‌سازی می‌شوند. هر موجودیت مکانی مجموعه‌ای از اجزا دارد و هر جزء مجموعه‌ای منحصر به فرد از داده‌ها و رفتارها را برای آن موجودیت فراهم می‌کند.

موجودیت‌های مکانی توسط یک اتم XrSpatialEntityIdEXT یا یک هندل XrSpatialEntityEXT نمایش داده می‌شوند که جزئیات آن در بخش نمایش‌های موجودیت مکانی ارائه شده است.

انواع مؤلفه‌های مکانی

یک موجودیت مکانی دارای یک یا چند مؤلفه است که داده‌ها یا رفتارهایی را برای آن موجودیت فراهم می‌کنند. برای برخی از مؤلفه‌های مشترک تعریف شده توسط این افزونه، به مؤلفه‌های مشترک مراجعه کنید. 

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;

شمارش XrSpatialComponentTypeEXT انواع مختلف کامپوننت‌هایی را که زمان اجرا ممکن است پشتیبانی کند، شناسایی می‌کند.

همه انواع اجزای ذکر شده به خودی خود توسط این افزونه ارائه نمی‌شوند: برخی از آنها، همانطور که مستند شده است، نیاز به فعال کردن افزونه‌های اضافی در زمان ایجاد نمونه دارند.

شمارشگرها مقادیر زیر را دارند:

توضیحات شمارشی

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

مؤلفه‌ای که مرزهای دوبعدی را برای یک موجودیت مکانی فراهم می‌کند. ساختار لیست مربوطه XrSpatialComponentBounded2DListEXT است؛ ساختار داده مربوطه XrSpatialBounded2DDataEXT است.

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

کامپوننتی که مرزهای سه‌بعدی را برای یک موجودیت مکانی فراهم می‌کند. ساختار لیست مربوطه XrSpatialComponentBounded3DListEXT است؛ ساختار داده مربوطه XrBoxf است.

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

کامپوننتی که XrSpatialEntityIdEXT والد یک موجودیت مکانی را ارائه می‌دهد. ساختار لیست مربوطه XrSpatialComponentParentListEXT است؛ ساختار داده مربوطه XrSpatialEntityIdEXT است.

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

کامپوننتی که یک شبکه سه‌بعدی برای یک موجودیت مکانی ارائه می‌دهد. ساختار لیست مربوطه XrSpatialComponentMesh3DListEXT است؛ ساختار داده مربوطه XrSpatialMeshDataEXT است.

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

کامپوننتی که enum ترازبندی صفحه را برای یک موجودیت مکانی فراهم می‌کند. ساختار لیست مربوطه XrSpatialComponentPlaneAlignmentListEXT است؛ ساختار داده مربوطه XrSpatialPlaneAlignmentEXT است (توسط افزونه XR_EXT_spatial_plane_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

کامپوننتی که یک شبکه دوبعدی برای یک موجودیت مکانی ارائه می‌دهد. ساختار لیست مربوطه XrSpatialComponentMesh2DListEXT است؛ ساختار داده مربوطه XrSpatialMeshDataEXT است (توسط افزونه XR_EXT_spatial_plane_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

کامپوننتی که یک چندضلعی مرزی دوبعدی برای یک موجودیت مکانی ارائه می‌دهد. ساختار لیست مربوطه XrSpatialComponentPolygon2DListEXT است؛ ساختار داده مربوطه XrSpatialPolygon2DDataEXT است (توسط افزونه XR_EXT_spatial_plane_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

کامپوننتی که یک برچسب معنایی برای یک صفحه ارائه می‌دهد. ساختار لیست مربوطه XrSpatialComponentPlaneSemanticLabelListEXT است؛ ساختار داده مربوطه XrSpatialPlaneSemanticLabelEXT است (توسط افزونه XR_EXT_spatial_plane_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

کامپوننتی که نوع، شناسه و مکان نشانگر را توصیف می‌کند. ساختار لیست مربوطه XrSpatialComponentMarkerListEXT است؛ ساختار داده مربوطه XrSpatialMarkerDataEXT است (توسط افزونه XR_EXT_spatial_marker_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

کامپوننتی که یک برچسب معنایی برای یک صحنه ارائه می‌دهد؛ ساختار لیست مربوطه XrSpatialComponentObjectSemanticLabelListEXT است. ساختار داده مربوطه XrSpatialObjectSemanticLabelEXT است. (توسط افزونه XR_EXT_spatial_object_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

کامپوننتی که یک برچسب معنایی برای صفحه‌کلید ارائه می‌دهد؛ ساختار لیست مربوطه XrSpatialComponentKeyboardSemanticLabelListEXT است. ساختار داده مربوطه XrSpatialKeyboardSemanticLabelEXT است (توسط افزونه XR_EXT_spatial_object_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

کامپوننتی که یک برچسب معنایی برای ماوس ارائه می‌دهد؛ ساختار لیست مربوطه XrSpatialComponentMouseSemanticLabelListEXT است. ساختار داده مربوطه XrSpatialMouseSemanticLabelEXT است (توسط افزونه XR_EXT_spatial_object_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

کامپوننتی که مکان یک anchor را فراهم می‌کند. ساختار لیست مربوطه XrSpatialComponentAnchorListEXT است؛ ساختار داده مربوطه XrPosef است (توسط افزونه XR_EXT_spatial_anchor اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

کامپوننتی که UUID پایدار را برای یک موجودیت مکانی فراهم می‌کند. ساختار لیست مربوطه XrSpatialComponentPersistenceListEXT است؛ ساختار داده مربوطه XrSpatialPersistenceDataEXT است (توسط افزونه XR_EXT_spatial_persistence اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

یک کامپوننت که نوع تصویر مسطح را توصیف می‌کند. ساختار لیست مربوطه XrSpatialComponentImage2DListEXT است؛ ساختار داده مربوطه XrSpatialImageSizeEXT است. (توسط افزونه XR_EXT_spatial_image_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

کامپوننتی که نرمال‌های شبکه سه‌بعدی یک موجودیت مکانی را فراهم می‌کند. ساختار لیست مربوطه XrSpatialComponentMesh3DNormalsListEXT است؛ ساختار داده مربوطه XrSpatialBufferEXT است (توسط افزونه XR_EXT_spatial_mesh_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

مؤلفه‌ای که برچسب‌های معنایی هر رأس را برای مش سه‌بعدی یک موجودیت مکانی ارائه می‌دهد. ساختار لیست مربوطه XrSpatialComponentMesh3DVertexSemanticLabelsListEXT است؛ ساختار داده مربوطه XrSpatialBufferEXT است؛ داده‌های درون بافر به XrSpatialMeshSemanticLabelEXT نگاشت می‌شوند (توسط افزونه XR_EXT_spatial_mesh_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

کامپوننتی که برچسب‌های معنایی هر وجه مثلثی را برای مش سه‌بعدی یک موجودیت مکانی ارائه می‌دهد. ساختار لیست مربوطه XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT است؛ ساختار داده مربوطه XrSpatialBufferEXT است؛ داده‌های درون بافر به XrSpatialMeshSemanticLabelEXT نگاشت می‌شوند (توسط افزونه XR_EXT_spatial_mesh_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

کامپوننتی که یک برچسب معنایی برای یک شیء ارائه می‌دهد؛ ساختار لیست مربوطه XrSpatialComponentObjectSemanticLabelListANDROID است؛ ساختار داده مربوطه XrSpatialObjectSemanticLabelANDROID است (توسط افزونه XR_ANDROID_spatial_object_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

کامپوننتی که موقعیت برخورد raycast را روی یک موجودیت فراهم می‌کند. ساختار لیست مربوطه XrSpatialComponentRaycastResultListANDROID است؛ ساختار داده مربوطه XrSpatialRaycastResultDataANDROID است (توسط افزونه XR_ANDROID_spatial_discovery_raycast اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

کامپوننتی که شناسه موجودیت موجودیتی را که موجودیت پیوست شده را در بر می‌گیرد، ارائه می‌دهد. ساختار لیست مربوطه XrSpatialComponentSubsumedByListANDROID است؛ ساختار داده مربوطه XrSpatialEntityIdEXT است (توسط افزونه XR_ANDROID_spatial_component_subsumed_by اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

کامپوننتی که ابعاد و نوع اتاق یک جعبه کفش را ارائه می‌دهد؛ ساختار لیست مربوطه XrSpatialComponentRoomListANDROIDSYS است؛ ساختار داده مربوطه XrSpatialRoomDataANDROIDSYS است (توسط افزونه XR_ANDROIDSYS_spatial_room_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

کامپوننتی که نوع ماده یک سطح مرزی را ارائه می‌دهد؛ ساختار لیست مربوطه XrSpatialComponentMaterialTypeListANDROIDSYS است؛ ساختار داده مربوطه XrSpatialMaterialTypeANDROIDSYS است (توسط افزونه XR_ANDROIDSYS_spatial_room_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

کامپوننتی که اطمینان یک قابل ردیابی را فراهم می‌کند؛ ساختار لیست مربوطه XrSpatialComponentConfidenceListANDROIDSYS است؛ ساختار داده مربوطه float است (توسط افزونه XR_ANDROIDSYS_spatial_room_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

کامپوننتی که میزان خالی بودن یک اتاق را ارائه می‌دهد؛ ساختار لیست مربوطه XrSpatialComponentRoomEmptinessListANDROIDSYS است؛ ساختار داده مربوطه float است (توسط افزونه XR_ANDROIDSYS_spatial_room_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

کامپوننتی که اطلاعات شبکه اشغال را روی موجودیت پیوست شده ارائه می‌دهد. ساختار لیست مربوطه XrSpatialComponentOccupancyGridListANDROIDX1 است؛ ساختار داده مربوطه XrSpatialOccupancyGridDataANDROIDX1 است (توسط افزونه XR_ANDROIDX1_spatial_occupancy_grid اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

کامپوننتی که یک حاشیه‌نویسی چهارگانه را توصیف می‌کند. ساختار لیست مربوطه XrSpatialComponentAnnotationQuadListANDROID است؛ ساختار داده مربوطه XrSpatialAnnotationQuadDataANDROID است (توسط افزونه XR_ANDROID_spatial_annotation_tracking اضافه شده است)

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

کامپوننتی که فراداده‌های هندسه‌ی نمای خیابان را فراهم می‌کند؛ ساختار لیست مربوطه XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2 است؛ ساختار داده‌ی مربوطه XrSpatialStreetscapeGeometryMetadataANDROIDX2 است (توسط افزونه‌ی XR_ANDROIDX2_geospatial_streetscape اضافه شده است)

قابلیت‌ها و تنظیمات مکانی

قابلیت‌های مکانی، توانایی‌های یک زمان اجرا را برای کشف موجودیت‌هایی که مجموعه‌ای از اجزای تضمین‌شده روی آنها وجود دارد، تعریف می‌کنند. برنامه‌ها هنگام ایجاد XrSpatialContextEXT ، اجزای یک قابلیت مکانی را فعال می‌کنند و زمان اجرا به نوبه خود باید فقط اجزای فعال‌شده روی موجودیت‌های کشف‌شده را ارائه دهد. به عنوان مثال، اگر یک زمان اجرا گزارش دهد که یکی از اجزای یک قابلیت معین "برچسب‌های معنایی" است، به این معنی است که برنامه می‌تواند برچسب‌های معنایی را از طریق پیکربندی برای آن قابلیت فعال کند و زمان اجرا فقط باید در صورت پیکربندی، مؤلفه برچسب معنایی را ارائه دهد. 

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;

شمارش XrSpatialCapabilityEXT انواع مختلف قابلیت‌هایی را که زمان اجرا ممکن است پشتیبانی کند، شناسایی می‌کند.

شمارشگرها مقادیر زیر را دارند:

توضیحات شمارشی

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

ردیابی صفحه (اضافه شده توسط افزونه XR_EXT_spatial_plane_tracking )

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

قابلیت شناسایی و ردیابی کدهای QR. (اضافه شده توسط افزونه XR_EXT_spatial_marker_tracking )

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

قابلیت شناسایی و ردیابی کدهای QR میکرو. (اضافه شده توسط افزونه XR_EXT_spatial_marker_tracking )

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

قابلیت شناسایی و ردیابی نشانگرهای آروکو. (توسط افزونه XR_EXT_spatial_marker_tracking اضافه شده است)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

قابلیت شناسایی و ردیابی AprilTags. (اضافه شده توسط افزونه XR_EXT_spatial_marker_tracking )

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

ردیابی اشیا (اضافه شده توسط افزونه XR_EXT_spatial_object_tracking )

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

قابلیت ایجاد لنگرهای مکانی (اضافه شده توسط افزونه XR_EXT_spatial_anchor )

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

قابلیت تشخیص و ردیابی تصاویر مرجع مسطح. (توسط افزونه XR_EXT_spatial_image_tracking اضافه شده است)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

قابلیت ردیابی مش یک محیط. (توسط افزونه XR_EXT_spatial_mesh_tracking اضافه شده است)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

ردیابی اشیا (توسط افزونه XR_ANDROID_spatial_object_tracking اضافه شده است)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

پخش پرتو در برابر بافر عمق (توسط افزونه XR_ANDROID_spatial_discovery_raycast اضافه شده است)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

قابلیت ردیابی یک اتاق (اضافه شده توسط افزونه XR_ANDROIDSYS_spatial_room_tracking )

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

قابلیت ردیابی مرز اتاق (اضافه شده توسط افزونه XR_ANDROIDSYS_spatial_room_tracking )

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

ردیابی حاشیه‌نویسی (اضافه شده توسط افزونه XR_ANDROID_spatial_annotation_tracking )

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

هندسه نمای خیابان (توسط افزونه XR_ANDROIDX2_geospatial_streetscape اضافه شده است)

تابع xrEnumerateSpatialCapabilitiesEXT به صورت زیر تعریف می‌شود:

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

توضیحات پارامتر

  • instance یک هندل برای XrInstance است.
  • systemId همان XrSystemId است که قابلیت‌های مکانی آن شمارش خواهد شد.
  • capabilityCapacityInput ظرفیت آرایه capabilities است، یا 0 برای نشان دادن درخواست بازیابی ظرفیت مورد نیاز.
  • capabilityCountOutput تعداد قابلیت‌ها یا ظرفیت مورد نیاز در صورتی است که capabilityCapacityInput کافی نباشد.
  • capabilities آرایه‌ای از XrSpatialCapabilityEXT است. اگر capabilityCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای توضیحات مفصل در مورد بازیابی اندازه capabilities مورد نیاز، به بخش پارامترهای اندازه بافر مراجعه کنید.

برنامه می‌تواند فهرست قابلیت‌های مکانی پشتیبانی‌شده توسط یک XrSystemId مشخص را با استفاده از xrEnumerateSpatialCapabilitiesEXT فهرست کند.

زمان اجرا نباید قابلیت‌های مکانی را که instance پسوند آنها فعال نیست، بشمارد.

کاربرد معتبر (ضمنی)

  • افزونه‌ی XR_EXT_spatial_entity باید قبل از فراخوانی xrEnumerateSpatialCapabilitiesEXT فعال شود.
  • instance باید یک شناسه معتبر XrInstance باشد.
  • capabilityCountOutput باید یک اشاره‌گر به مقدار uint32_t باشد.
  • اگر capabilityCapacityInput برابر با 0 نباشد، capabilities باید یک اشاره‌گر به آرایه‌ای از مقادیر capabilityCapacityInput XrSpatialCapabilityEXT باشد.

کدهای بازگشت

موفقیت

  • XR_SUCCESS

شکست

  • 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

تابع xrEnumerateSpatialCapabilityComponentTypesEXT به صورت زیر تعریف شده است:

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

توضیحات پارامتر

  • instance یک هندل برای XrInstance است.
  • systemId همان XrSystemId است که اجزای قابلیت مکانی آن شمارش خواهند شد.
  • capability ، XrSpatialCapabilityEXT است که برای آن اجزا شمارش می‌شوند.
  • capabilityComponents یک اشاره‌گر به XrSpatialCapabilityComponentTypesEXT است که یک ساختار ورودی/خروجی است که در آن یک آرایه اختصاص داده شده توسط برنامه قرار می‌گیرد.

این تابع انواع کامپوننت‌هایی را که قابلیت داده شده روی موجودیت‌های خود در سیستم به صورت پیکربندی شده ارائه می‌دهد، فهرست می‌کند.

برنامه می‌تواند از انواع مؤلفه‌های برشمرده شده در XrSpatialCapabilityComponentTypesEXT :: componentTypes برای درک مجموعه کامل مؤلفه‌هایی که systemId برای capability پشتیبانی می‌کند، استفاده کند و می‌تواند از این لیست برای تعیین پیکربندی معتبر برای capability هنگام ایجاد XrSpatialContextEXT برای آن استفاده کند.

اگر capability توسط xrEnumerateSpatialCapabilitiesEXT شمارش نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT را برگرداند.

زمان اجرا نباید انواع مؤلفه‌های مکانی را که instance پسوند آنها فعال نیست، بشمارد.

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • XR_SUCCESS

شکست

  • 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

ساختار XrSpatialCapabilityComponentTypesEXT به صورت زیر تعریف می‌شود:

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

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • componentTypeCapacityInput ظرفیت آرایه است، یا 0 برای نشان دادن درخواست بازیابی ظرفیت مورد نیاز.
  • componentTypeCountOutput تعداد انواع کامپوننت یا ظرفیت مورد نیاز در صورتی است که componentTypeCapacityInput کافی نباشد.
  • componentTypes آرایه‌ای از XrSpatialComponentTypeEXT است. اگر componentTypeCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای توضیحات بیشتر در مورد بازیابی اندازه مورد نیاز componentTypes ، به بخش پارامترهای اندازه بافر مراجعه کنید.

کاربرد معتبر (ضمنی)

ویژگی‌های قابلیت مکانی 

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;

برخی از قابلیت‌ها پارامترهایی دارند که در معرض برنامه قرار می‌گیرند تا نحوه محاسبه داده‌های مؤلفه توسط زمان اجرا را پیکربندی کنند. این ابعاد پارامترسازی/قابلیت پیکربندی به عنوان ویژگی‌های قابلیت شناخته می‌شوند. به عنوان مثال، برای قابلیت ردیابی تصویر، یک زمان اجرا ممکن است از یک ویژگی برای برنامه پشتیبانی کند تا مشخص کند که آیا تصاویر ردیابی شده ثابت هستند یا خیر.

ارائه این اطلاعات به زمان اجرا از طریق یک ساختار پیکربندی نباید مجموعه انواع اجزای موجود در موجودیت‌های مرتبط، مثلاً در تصویر ردیابی شده، را تغییر دهد. با این حال، زمان اجرا ممکن است بتواند مثلاً توانایی‌های ردیابی قابلیت ردیابی تصویر را بهینه کند و تجربه بهتری را برای برنامه فراهم کند.

چنین ویژگی‌هایی توسط XrSpatialCapabilityFeatureEXT نمایش داده می‌شوند و برنامه آنها را با استفاده از xrEnumerateSpatialCapabilityFeaturesEXT شمارش می‌کند.

هر ویژگی قابلیت، یک ساختار پیکربندی متناظر برای فعال‌سازی دارد. چنین ساختارهای پیکربندی باید به XrSpatialCapabilityConfigurationBaseHeaderEXT :: next از قابلیت مربوطه زنجیر شوند.

شمارشگرها مقادیر زیر را دارند:

توضیحات شمارشی

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

قابلیتی که به برنامه‌ها اجازه می‌دهد اندازه نشانگرها را مشخص کنند. ساختار پیکربندی مربوطه XrSpatialMarkerSizeEXT است (توسط افزونه XR_EXT_spatial_marker_tracking اضافه شده است)

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

قابلیتی که به برنامه‌ها اجازه می‌دهد مشخص کنند آیا نشانگرها ایستا هستند یا خیر. ساختار پیکربندی مربوطه XrSpatialMarkerStaticOptimizationEXT است (توسط افزونه XR_EXT_spatial_marker_tracking اضافه شده است)

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

ویژگی مکانی که به برنامه‌ها اجازه می‌دهد زیرمجموعه‌ای از برچسب‌ها را از XrSpatialObjectSemanticLabelEXT برای ردیابی در زمان اجرا مشخص کنند. ساختار پیکربندی مربوطه XrSpatialFeatureObjectSemanticLabelSubsetEXT است. (توسط افزونه XR_EXT_spatial_object_tracking اضافه شده است)

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

زمان اجرا از فیلتر XrSpatialBoundsSpherefANDROID برای XrSpatialDiscoverySnapshotCreateInfoEXT پشتیبانی می‌کند؛ این امر نیازی به گنجاندن هیچ ساختار پیکربندی در طول ایجاد زمینه مکانی ندارد. (توسط افزونه XR_ANDROID_spatial_discovery_bounds اضافه شده است)

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

زمان اجرا از فیلتر XrSpatialBoundsBoxfANDROID برای XrSpatialDiscoverySnapshotCreateInfoEXT پشتیبانی می‌کند؛ این امر نیازی به گنجاندن هیچ ساختار پیکربندی در طول ایجاد زمینه مکانی ندارد. (توسط افزونه XR_ANDROID_spatial_discovery_bounds اضافه شده است)

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

زمان اجرا از فیلتر XrSpatialBoundsFrustumfANDROID برای XrSpatialDiscoverySnapshotCreateInfoEXT پشتیبانی می‌کند؛ این امر نیازی به گنجاندن هیچ ساختار پیکربندی در طول ایجاد زمینه مکانی ندارد. (توسط افزونه XR_ANDROID_spatial_discovery_bounds اضافه شده است)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

زمان اجرا از محاسبه خودکار اندازه فیزیکی تصاویر شناسایی و ردیابی شده پشتیبانی می‌کند. ساختار پیکربندی مربوطه XrSpatialImageSizeEXT است (توسط افزونه XR_EXT_spatial_image_tracking اضافه شده است)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

زمان اجرا از XrSpatialImageStaticOptimizationEXT پشتیبانی می‌کند. ساختار پیکربندی مربوطه XrSpatialImageStaticOptimizationEXT است. (توسط افزونه XR_EXT_spatial_image_tracking اضافه شده است)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

زمان اجرا از XrSpatialImageSizeEXT پشتیبانی می‌کند. ساختار پیکربندی مربوطه XrSpatialImageSizeEXT است (توسط افزونه XR_EXT_spatial_image_tracking اضافه شده است)

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

قابلیت ردیابی یک شبکه‌ی ضدآب از محیط. ساختار پیکربندی مربوطه XrSpatialFeatureTrackWatertightMeshEXT است. (توسط افزونه‌ی XR_EXT_spatial_mesh_tracking اضافه شده است)

تابع xrEnumerateSpatialCapabilityFeaturesEXT به صورت زیر تعریف می‌شود:

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

توضیحات پارامتر

  • instance یک هندل برای XrInstance است.
  • systemId همان XrSystemId است که ویژگی‌های قابلیت مکانی آن شمارش خواهد شد.
  • capability ، XrSpatialCapabilityEXT است که ویژگی‌ها برای آن شمارش خواهند شد.
  • capabilityFeatureCapacityInput آرایه است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت مورد نیاز.
  • capabilityFeatureCountOutput تعداد ویژگی‌ها یا ظرفیت مورد نیاز در صورتی است که capabilityFeatureCapacityInput کافی نباشد.
  • capabilityFeatures آرایه‌ای از XrSpatialCapabilityFeatureEXT است. اگر capabilityFeatureCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای توضیحات بیشتر در مورد بازیابی اندازه مورد نیاز capabilityFeatures ، به بخش پارامترهای اندازه بافر مراجعه کنید.

این برنامه با استفاده از xrEnumerateSpatialCapabilityFeaturesEXT، ویژگی‌های پشتیبانی‌شده توسط یک سیستم مشخص برای XrSpatialCapabilityEXT را کشف می‌کند.

برای قابلیت‌هایی که ویژگی‌هایشان در معرض نمایش قرار گرفته است، برنامه ویژگی یا ویژگی‌هایی را که باید فعال شوند انتخاب می‌کند و ساختار پیکربندی مربوطه را در زنجیره بعدی ساختارهای پیکربندی قابلیت در XrSpatialContextCreateInfoEXT :: capabilityConfigs ارائه می‌دهد.

اگر capability قابلیتی نباشد که توسط xrEnumerateSpatialCapabilitiesEXT شمارش شده باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT را برگرداند.

زمان اجرا نباید ویژگی‌های قابلیت مکانی را که instance پسوند آنها فعال نیست، بشمارد.

کاربرد معتبر (ضمنی)

  • قبل از فراخوانی xrEnumerateSpatialCapabilityFeaturesEXT، افزونه‌ی XR_EXT_spatial_entity باید فعال شود.
  • instance باید یک شناسه معتبر XrInstance باشد.
  • capability باید یک مقدار معتبر XrSpatialCapabilityEXT باشد.
  • capabilityFeatureCountOutput باید یک اشاره‌گر به مقدار uint32_t باشد.
  • اگر capabilityFeatureCapacityInput برابر با 0 نباشد، capabilityFeatures باید یک اشاره‌گر به آرایه‌ای از مقادیر capabilityFeatureCapacityInput XrSpatialCapabilityFeatureEXT باشد.

کدهای بازگشت

موفقیت

  • XR_SUCCESS

شکست

  • 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

زمینه مکانی

ایجاد زمینه مکانی 

XR_DEFINE_HANDLE(XrSpatialContextEXT)

هندل XrSpatialContextEXT منابعی را برای کشف و به‌روزرسانی تعدادی از موجودیت‌های مکانی در محیط کاربر نشان می‌دهد. برنامه می‌تواند از این هندل برای کشف و به‌روزرسانی موجودیت‌های مکانی با استفاده از توابع دیگر در این افزونه استفاده کند.

تابع xrCreateSpatialContextAsyncEXT به صورت زیر تعریف می‌شود:

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

توضیحات پارامتر

  • session یک XrSession است که در آن زمینه مکانی فعال خواهد بود.
  • createInfo همان XrSpatialContextCreateInfoEXT است که برای تعیین پارامترهای زمینه مکانی استفاده می‌شود.
  • future یک اشاره‌گر به XrFutureEXT است.

برنامه می‌تواند با استفاده از موارد زیر یک هندل XrSpatialContextEXT ایجاد کند:

اگر XrSpatialContextCreateInfoEXT ::capabilityConfigCount برابر با ۰ باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT را برگرداند. یک مدیریت زمینه مکانی حداقل به یک قابلیت نیاز دارد.

اگر هر قابلیتی در آرایه XrSpatialContextCreateInfoEXT :: capabilityConfigs توسط xrEnumerateSpatialCapabilitiesEXT شمارش نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT را برگرداند.

اگر مقدار XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount در XrSpatialContextCreateInfoEXT :: capabilityConfigs برابر با صفر باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT را برگرداند. پیکربندی یک قابلیت بدون فهرستی از انواع کامپوننت‌ها برای فعال‌سازی آن قابلیت، ناقص است.

اگر هر یک از انواع کامپوننت‌های فهرست‌شده در XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents برای capability XrSpatialCapabilityConfigurationBaseHeaderEXT :: در xrEnumerateSpatialCapabilityComponentTypesEXT شمارش نشده باشند، زمان اجرا باید XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT را برگرداند.

اگر هر یک از ساختارهای موجود در زنجیره بعدی XrSpatialContextCreateInfoEXT :: capabilityConfigs مربوط به یک XrSpatialCapabilityFeatureEXT باشد که برای آن قابلیت در xrEnumerateSpatialCapabilityFeaturesEXT شمارش نشده است، زمان اجرا باید آن ساختار XrSpatialCapabilityFeatureEXT را نادیده بگیرد.

اگر XrSpatialContextCreateInfoEXT :: capabilityConfigs شامل چندین ساختار با capability XrSpatialCapabilityConfigurationBaseHeaderEXT :: یکسان باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT را برگرداند.

برای اطمینان از استفاده بهینه از منابع سیستم، زمان اجرا ممکن است از پیکربندی‌های ارائه شده در آرایه XrSpatialContextCreateInfoEXT برای آماده‌سازی خود برای درخواست‌های مکانی استفاده کند. به عنوان مثال، یک زمان اجرا که از قابلیت ردیابی صفحه پشتیبانی می‌کند، ممکن است تنها در صورتی خط لوله ردیابی صفحه خود را آغاز کند که یک دسته زمینه مکانی حاوی قابلیت ردیابی صفحه توسط برنامه ایجاد شود. اگر قابلیت‌های پیکربندی شده زمان آماده‌سازی طولانی داشته باشند، فراخوانی‌های xrCreateSpatialDiscoverySnapshotAsyncEXT ممکن است منجر به یک تصویر لحظه‌ای خالی شود. برنامه می‌تواند قبل از استفاده از xrCreateSpatialDiscoveryRecommendedEXT منتظر XrEventDataSpatialDiscoveryRecommendedEXT بماند تا مطمئن شود که سرویس‌های ردیابی اساسی آماده‌سازی شده‌اند.

اگر یک زمان اجرا، یک سیستم مجوز را برای کنترل دسترسی برنامه به قابلیت‌های مکانی که برای XrSpatialContextEXT پیکربندی شده‌اند، اعمال کند، در صورتی که آن مجوزها به این برنامه اعطا نشده باشند، زمان اجرا باید XR_ERROR_PERMISSION_INSUFFICIENT برگرداند.

این تابع یک عملیات ناهمزمان را شروع می‌کند و یک XrFutureEXT متناظر ایجاد می‌کند که با xrPollFutureEXT و توابع مرتبط قابل استفاده است. مقدار بازگشتی این تابع فقط نشان می‌دهد که آیا پارامترها برای زمان‌بندی عملیات ناهمزمان قابل قبول بوده‌اند یا خیر. تابع تکمیل مربوطه xrCreateSpatialContextCompleteEXT است که زمانی قابل استفاده است که یک آینده از این تابع در حالت READY باشد و خروجی‌های آن تابع در ساختار تکمیل XrCreateSpatialContextCompletionEXT قرار گیرند.

کاربرد معتبر (ضمنی)

  • افزونه‌ی XR_EXT_spatial_entity باید قبل از فراخوانی xrCreateSpatialContextAsyncEXT فعال شود.
  • session باید یک دسته XrSession معتبر باشد
  • createInfo باید یک اشاره‌گر به ساختار معتبر XrSpatialContextCreateInfoEXT باشد.
  • future باید اشاره‌گری به مقدار XrFutureEXT باشد.

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

ساختار XrSpatialContextCreateInfoEXT به صورت زیر تعریف می‌شود: 

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

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • capabilityConfigCount یک uint32_t است که تعداد عناصر موجود در آرایه capabilityConfigs را توصیف می‌کند.
  • capabilityConfigs یک اشاره‌گر به آرایه‌ای از اشاره‌گرهای XrSpatialCapabilityConfigurationBaseHeaderEXT است.

ساختار XrSpatialContextCreateInfoEXT اطلاعات لازم برای ایجاد یک هندل XrSpatialContextEXT را توصیف می‌کند.

کاربرد معتبر (ضمنی)

ساختار XrSpatialCapabilityConfigurationBaseHeaderEXT به صورت زیر تعریف می‌شود: 

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

این ساختار مستقیماً در API استفاده نمی‌شود، اما در عوض می‌توان از ساختارهای فرزند آن به همراه XrSpatialContextCreateInfoEXT برای پیکربندی قابلیت‌های مکانی استفاده کرد.

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است.
  • capability یک XrSpatialCapabilityEXT است.
  • enabledComponentCount یک uint32_t است که تعداد عناصر موجود در آرایه enabledComponents را توصیف می‌کند.
  • enabledComponents یک اشاره‌گر به آرایه‌ای از XrSpatialComponentTypeEXT است.

اگر capability توسط xrEnumerateSpatialCapabilitiesEXT شمارش نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT را برگرداند. اگر هر نوع کامپوننتی که در enabledComponents فهرست شده است برای capability در xrEnumerateSpatialCapabilityComponentTypesEXT شمارش نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT را برگرداند.

کاربرد معتبر (ضمنی)

تابع xrCreateSpatialContextCompleteEXT به صورت زیر تعریف می‌شود: 

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

توضیحات پارامتر

xrCreateSpatialContextCompleteEXT completes the asynchronous operation started by xrCreateSpatialContextAsyncEXT . The runtime must return XR_ERROR_FUTURE_PENDING_EXT if future is not in ready state. The runtime must return XR_ERROR_FUTURE_INVALID_EXT if future has already been completed or cancelled.

Valid Usage (Implicit)

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

The XrCreateSpatialContextCompletionEXT structure is defined as: 

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

Member Descriptions

Future Return Codes

futureResult values:

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

If futureResult is a success code, spatialContext must be valid. If spatialContext is valid, it remains so only within the lifecycle of xrCreateSpatialContextAsyncEXT :: session or until the application destroys the spatialContext with xrDestroySpatialContextEXT , whichever comes first.

Valid Usage (Implicit)

Destroy the spatial context

The xrDestroySpatialContextEXT function is defined as: 

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

Parameter Descriptions

The application can call xrDestroySpatialContextEXT function to release the spatialContext handle and the underlying resources when finished with spatial entity discovery and update tasks. If there is no other valid XrSpatialContextEXT that was created with the same spatial capabilities as spatialContext , this call serves as a suggestion to the runtime to disable the tracking services required for those capabilities to save system resources.

Valid Usage (Implicit)

Thread Safety

  • Access to spatialContext , and any child handles, must be externally synchronized

Return Codes

موفقیت

  • XR_SUCCESS

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Spatial Entity Representations

Spatial Entity ID 

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT is used to represent any kind of entity discovered by the runtime in the spatial environment of the user. An XrSpatialEntityIdEXT is valid for the XrSpatialContextEXT in which it is discovered, and the runtime must not reuse the same XrSpatialEntityIdEXT for different entities within the same XrSpatialContextEXT . Also, the runtime must not reuse the same XrSpatialEntityIdEXT across multiple XrSpatialContextEXT within the same XrSession regardless of whether it represents the same entity or different ones. 

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT is a reserved value representing an invalid XrSpatialEntityIdEXT . It may be passed to and returned from API functions only when specifically allowed.

Spatial Entity Handle 

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

The XrSpatialEntityEXT handle represents a spatial entity. An application can create such a handle to express its interest in a specific entity to the runtime.

Create Spatial Entity Handle from ID

The xrCreateSpatialEntityFromIdEXT function is defined as: 

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

Parameter Descriptions

The application can use xrCreateSpatialEntityFromIdEXT to create an XrSpatialEntityEXT handle which is a reference to an entity that exists in the user's environment.

The runtime must return XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT if XrSpatialEntityFromIdCreateInfoEXT :: entityId is not a valid ID for spatialContext .

Valid Usage (Implicit)

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

The XrSpatialEntityFromIdCreateInfoEXT structure is defined as: 

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • entityId is the XrSpatialEntityIdEXT of the entity that the application wants to create a handle for.

Valid Usage (Implicit)

Destroy Spatial Entity Handle

The xrDestroySpatialEntityEXT function is defined as: 

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

Parameter Descriptions

The application can use xrDestroySpatialEntityEXT to release the spatialEntity handle when it is no longer interested in the entity referenced by this handle.

Valid Usage (Implicit)

Thread Safety

  • Access to spatialEntity , and any child handles, must be externally synchronized

Return Codes

موفقیت

  • XR_SUCCESS

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Spatial Snapshot 

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

The application can create spatial snapshots for the purpose of discovering spatial entities or for updating its information about known spatial entities. The XrSpatialSnapshotEXT handle represents the immutable data for the discovered or updated spatial entities and a subset of their components as selected by the application. The spatial snapshot represents a coherent view of the entities and their component data. Once a snapshot is created, the snapshot's data must remain constant while the snapshot is valid.

The application can create any number of snapshots it wants but must be mindful of the memory being allocated for each new snapshot and must destroy the snapshots once it no longer needs them.

Create discovery snapshot

The xrCreateSpatialDiscoverySnapshotAsyncEXT function is defined as: 

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

Parameter Descriptions

The application can discover spatial entities by creating a discovery snapshot by using xrCreateSpatialDiscoverySnapshotAsyncEXT .

This function starts an asynchronous operation and creates a corresponding XrFutureEXT , usable with xrPollFutureEXT and related functions. The return value of this function only indicates whether the parameters were acceptable to schedule the asynchronous operation. The corresponding completion function is xrCreateSpatialDiscoverySnapshotCompleteEXT , usable when a future from this function is in the READY state, with outputs populated by that function in the completion structure XrCreateSpatialDiscoverySnapshotCompletionEXT .

The application can submit multiple discovery snapshot creation requests without needing to wait for the previous one to be completed. The runtime may process and complete the snapshot creation in any order. The runtime may delay the completion of the discovery snapshot creation to throttle the application if it needs to reduce the use of system resources due to power, thermal or other policies of the device.

The application can use XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes to filter the list of entities and the components whose data the runtime must include in the snapshot. If the application provides a valid list of spatial component types in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , then the runtime must only include spatial entities in the snapshot that have at least one of the components provided in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . Also, the runtime must only include data for only those components in the snapshot.

The runtime must return XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT if any of the XrSpatialComponentTypeEXT in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes are not enabled for the spatial capabilities passed to XrSpatialContextCreateInfoEXT :: capabilityConfigs when creating spatialContext .

If the application does not provide a list of spatial component types in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , the runtime must include all the spatial entities in the snapshot that have the set of components which are enumerated in XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents for the capabilities configured for spatialContext . The runtime must include the data for all the enabled components of the capabilities configured for spatialContext .

If XrEventDataReferenceSpaceChangePending is queued before the completion of future , and XrEventDataReferenceSpaceChangePending :: poseValid is false, then the runtime may either create an XrSpatialSnapshotEXT that has no entities in it or set the XrSpatialEntityTrackingStateEXT of the entities that are no longer locatable in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace at XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time to XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . The runtime must not set XrCreateSpatialContextCompletionEXT :: futureResult to an error code because of XrEventDataReferenceSpaceChangePending .

Valid Usage (Implicit)

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

The XrSpatialDiscoverySnapshotCreateInfoEXT structure is defined as: 

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • componentTypeCount is a uint32_t describing the count of elements in the componentTypes array.
  • componentTypes is an array of XrSpatialComponentTypeEXT .

The XrSpatialDiscoverySnapshotCreateInfoEXT structure describes the information to create an XrSpatialSnapshotEXT handle when discovering spatial entities.

Valid Usage (Implicit)

The xrCreateSpatialDiscoverySnapshotCompleteEXT function is defined as: 

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

Parameter Descriptions

xrCreateSpatialDiscoverySnapshotCompleteEXT completes the asynchronous operation started by xrCreateSpatialDiscoverySnapshotAsyncEXT . The runtime must return XR_ERROR_FUTURE_PENDING_EXT if XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future is not in ready state. The runtime must return XR_ERROR_FUTURE_INVALID_EXT if XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future has already been completed or cancelled.

Valid Usage (Implicit)

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

The XrCreateSpatialDiscoverySnapshotCompletionInfoEXT structure is defined as: 

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

Member Descriptions

The locations in the various component data included in the created snapshot will be represented in baseSpace , located at time .

Valid Usage (Implicit)

The XrCreateSpatialDiscoverySnapshotCompletionEXT structure is defined as: 

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • futureResult is the XrResult of the spatial discovery snapshot creation operation.
  • snapshot is an XrSpatialSnapshotEXT which can be used to query the component data of the discovered spatial entities.

Future Return Codes

futureResult values:

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Valid Usage (Implicit)

Discovery Recommendation Event

The XrEventDataSpatialDiscoveryRecommendedEXT structure is defined as: 

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • spatialContext is the XrSpatialContextEXT for which discovery is being recommended by the runtime.

The application can retrieve this event by using xrPollEvent . The application can avoid excessive calls to xrCreateSpatialDiscoverySnapshotAsyncEXT to discover spatial entities by waiting for this event. If the application creates multiple discovery snapshots with the same XrSpatialDiscoverySnapshotCreateInfoEXT between two XrEventDataSpatialDiscoveryRecommendedEXT events, the resultant snapshots may contain the same entities and therefore the snapshot creation and data queries would be wasteful.

Waiting for this event to create a new discovery snapshot ensures that the application is not overloading the system with discovery requests for which the runtime may not return any new data and helps avoid the risk of overusing the system resources, and getting throttled due to power or thermal policies of the device. This also helps create parity between runtimes that are discovering spatial entities on the fly with live tracking and runtimes which are providing spatial entities off of a previously recorded state (where the runtime may queue the discovery recommendation event only once for each XrSpatialContextEXT ).

The runtime must not queue this event for notifying the application about changes or adjustments made to the component data of existing spatial entities. The application can use the xrCreateSpatialUpdateSnapshotEXT to keep track of component data updates for the spatial entities it is interested in.

A runtime may queue a discovery recommendation event without waiting for the application to first call xrCreateSpatialDiscoverySnapshotAsyncEXT . For example, a runtime may base the decision of queueing the discovery recommendation event on the configuration of the XrSpatialContextEXT , its own understanding of the environment around the user (discovery of new entities or loss of existing ones), or for hinting an appropriate discovery request cadence to the application so as not to overload the system resources. The runtime may choose to never queue this event for an XrSpatialContextEXT if no entities are found in the user's environment throughout the lifetime of that XrSpatialContextEXT .

The runtime must not queue this event for a given spatialContext until the application completes its creation by using xrCreateSpatialContextCompleteEXT .

After the application calls xrDestroySpatialContextEXT , the runtime must not queue any more discovery recommendation events for that spatial context nor return any such events for that context from xrPollEvent .

Valid Usage (Implicit)

Query Component Data

The xrQuerySpatialComponentDataEXT function is defined as: 

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

Parameter Descriptions

The application can use xrQuerySpatialComponentDataEXT to query the component data of the entities in the snapshot by attaching a list structure to XrSpatialComponentDataQueryResultEXT :: next corresponding to each XrSpatialComponentTypeEXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

If the application attaches a list structure to XrSpatialComponentDataQueryResultEXT :: next that does not correspond to any of the components listed in XrSpatialComponentDataQueryConditionEXT :: componentTypes , the runtime must return XR_ERROR_VALIDATION_FAILURE .

The application can choose to attach the list structures corresponding to only a subset of components listed in XrSpatialComponentDataQueryConditionEXT :: componentTypes . The application can choose to omit the list structures altogether if it only wishes to know the ids and tracking state of the spatial entities that satisfy the queryCondition . The runtime must not treat the absence of list structures from the XrSpatialComponentDataQueryResultEXT :: next chain as a failure.

If XrEventDataReferenceSpaceChangePending is queued and XrEventDataReferenceSpaceChangePending :: changeTime elapsed while the application is querying component data from an XrSpatialSnapshotEXT , the application may use the event data to adjust the poses accordingly.

The runtime must populate XrSpatialComponentDataQueryResultEXT :: entityIds only with entities that have all the components specified in XrSpatialComponentDataQueryConditionEXT :: componentTypes . If XrSpatialComponentDataQueryConditionEXT :: componentTypeCount is 0, the runtime must populate queryResult with all the entities (and their tracking states) that are in the snapshot. If additional query conditions are added to XrSpatialComponentDataQueryConditionEXT :: next , the runtime must treat those as an "AND" with the component types availability ie the runtime must populate XrSpatialComponentDataQueryResultEXT ::entityIds only with entities that satisfy all of the provided conditions. The runtime must populate the component data in the list structures in the same order as the entities in XrSpatialComponentDataQueryResultEXT :: entityIds ie the component data at a given index in the list structure array must correspond to the entity at the same index.

If the tracking state for an entity is not XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT , the runtime must not change the data at the index corresponding to that entity in the array contained in the list structures attached to XrSpatialComponentDataQueryResultEXT .

Valid Usage (Implicit)

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

As an example the application creates an XrSpatialSnapshotEXT which contains 5 entities, where -

  • Entity 1 and 2 have components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
  • Entity 3 and 4 have components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
  • Entity 5 has components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT .

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

۱

۱

۲

۲

۳

۳

۴

۴

۵

۵

Bounded2D

Bounded2D

بله

بله

بله

بله

خیر

خیر

خیر

خیر

بله

بله

والدین

والدین

بله

بله

بله

بله

خیر

خیر

خیر

خیر

خیر

خیر

Mesh3D

Mesh3D

خیر

خیر

خیر

خیر

بله

بله

بله

بله

بله

بله

Bounded3D

Bounded3D

خیر

خیر

خیر

خیر

بله

بله

بله

بله

خیر

No Text is not SVG - cannot display

Figure 20. Example snapshot

xrQuerySpatialComponentDataEXT on the above snapshot with XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT listed in the query condition will result in entity #1, #2, and #5 being returned to the application and the application can attach an array of XrSpatialBounded2DDataEXT as part of the XrSpatialComponentBounded2DListEXT structure to the next chain of XrSpatialComponentDataQueryResultEXT to get the bounded2D data.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

۱

۱

۲

۲

۵

۵

Bounded2D

Bounded2D

Data for entityId #1

Data for entit...

Data for entityId #2

Data for entit...

Data for entityId #5

Data for entit...

entityIds

entityIds

بعدی

بعدی

XrSpatialComponent DataQueryResultEXT

XrSpatialComponent Dat...

مرزها

مرزها

XrSpatialComponent Bounded2DListEXT

XrSpatialComponent Bou... Text is not SVG - cannot display

Figure 21. Example query result

xrQuerySpatialComponentDataEXT on the above snapshot with XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT components listed in the query condition will result in entity #3 and #4 being returned to the application and the application can attach arrays of XrBoxf and XrSpatialMeshDataEXT as part of the XrSpatialComponentBounded3DListEXT and XrSpatialComponentMesh3DListEXT structures respectively to the next chain of XrSpatialComponentDataQueryResultEXT to get the component data.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

۳

۳

۴

۴

Bounded3D

Bounded3D

Data for entityId #3

Data for entit...

Data for entityId #4

Data for entit...

Mesh3D

Mesh3D

Data for entityId #3

Data for entit...

Data for entityId #4

Data for entit...

entityIds

entityIds

بعدی

بعدی

XrSpatialComponent DataQueryResultEXT

XrSpatialComponent Da...

مرزها

مرزها

بعدی

بعدی

XrSpatialComponent Bounded3DListEXT

XrSpatialComponent Bo...

XrSpatialComponent Mesh3DListEXT

XrSpatialComponent Me...

مش ها

meshes Text is not SVG - cannot display

Figure 22. Example query result

The XrSpatialComponentDataQueryConditionEXT structure is defined as: 

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • componentTypeCount is a uint32_t describing the count of elements in the componentTypes array.
  • componentTypes is an array of XrSpatialComponentTypeEXT for which to get the data from the snapshot.

Valid Usage (Implicit)

The XrSpatialComponentDataQueryResultEXT structure is defined as: 

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • entityIdCapacityInput is the capacity of the entityIds array, or 0 to indicate a request to retrieve the required capacity.
  • entityIdCountOutput is the number of XrSpatialEntityIdEXT in entityIds , or the required capacity in the case that entityIdCapacityInput is insufficient.
  • entityIds is an array of XrSpatialEntityIdEXT . It can be NULL if entityIdCapacityInput is 0.
  • entityStateCapacityInput is the capacity of the entityStates array, or 0 to indicate a request to retrieve the required capacity.
  • entityStateCountOutput is the number of XrSpatialEntityTrackingStateEXT in entityStates , or the required capacity in the case that entityStateCapacityInput is insufficient. This must always be the same as entityIdCountOutput .
  • entityStates is an array of XrSpatialEntityTrackingStateEXT . It can be NULL if entityStateCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required entityIds size.

An application can use the entityIds with xrCreateSpatialEntityFromIdEXT to create XrSpatialEntityEXT handles for the entities it is interested in getting regular updates for. The application can then use these XrSpatialEntityEXT handles with xrCreateSpatialUpdateSnapshotEXT to create an update snapshot that has the runtime's latest known data of the components for the provided entities.

Valid Usage (Implicit)

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;

The XrSpatialEntityTrackingStateEXT enumerates the possible spatial entity tracking states:

The enums have the following meanings:

Enum Description

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

The runtime has stopped tracking this entity and will never resume tracking it.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

The runtime has paused tracking this entity but may resume tracking it in the future.

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

The runtime is currently tracking this entity and its component data is valid.

TRACKING

PAUSED

STOPPED

Figure 23. XrSpatialEntityTrackingStateEXT

  • The runtime may change the state of the spatial entity from XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT to XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT if it suspends the tracking of that spatial entity but has the possibility of resuming its tracking in the future. Some examples of when the runtime may do this include (but not limited to) if the application loses input focus; or if the given spatial entity is too far from the user to be accurately tracked; or if there are too many entities being tracked and the runtime wants to reduce the cost of tracking. XrSpatialEntityTrackingStateEXT helps the application insulate itself from the different tracking policies of each runtime.
  • The runtime may change the state of an entity from XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT to XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT .
  • The runtime must change the state of the spatial entity from XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT to XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT if the spatial entity is lost and its tracking will never be recovered or resumed. An example of such a case would be if the device loses tracking, restarts its tracking session but is unable to relocalize in its environment, and therefore treats discovered entities of this tracking session as new entities.
  • Once the tracking state of an entity is set to XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , the runtime must never change it any other state.
  • When querying the component data of a spatial entity using xrQuerySpatialComponentDataEXT , the runtime must set valid data in the contents of the buffers provided by the application in the next chain of XrSpatialComponentDataQueryResultEXT if the entity state is XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . If the entity state is XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT , the runtime must not change the content of the buffers.

Two-call idiom for component data

The XrSpatialBufferEXT structure is defined as: 

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

Member Descriptions

  • bufferId the XrSpatialBufferIdEXT of the buffer data.
  • bufferType is the XrSpatialBufferTypeEXT to indicate the type of data in bufferId . The application can use bufferType to determine which function to use to retrieve the actual data of the buffer.

Some spatial components have variable-sized data and therefore require using the two-call idiom to retrieve their data. In such cases, the spatial component data structure provides an XrSpatialBufferEXT for each variable sized buffer needed in that component's data.

For the same bufferId , the runtime must provide the same data from one component data query to another, even across one snapshot to another. A different bufferId between component data query calls indicates to the application that the data for that component may have changed.

Valid Usage (Implicit)

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT is used to represent any kind of variable sized data for a spatial component.

The runtime must keep the XrSpatialBufferIdEXT and its data in memory for at least the lifecycle of the XrSpatialSnapshotEXT that contains it. The runtime may keep the XrSpatialBufferIdEXT and its data in memory for longer than the lifecycle of the XrSpatialSnapshotEXT in order to return the same ID as part of snapshots created later on by the application. For the same XrSpatialBufferIdEXT , the runtime must always return the same data via the appropriate xrGetSpatialBuffer* function. 

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;

The XrSpatialBufferTypeEXT enumeration identifies the different data types of the buffer represented XrSpatialBufferIdEXT .

Enumerant Descriptions

The xrGetSpatialBufferStringEXT function is defined as: 

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

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of characters, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of char . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_STRING_EXT by using xrGetSpatialBufferStringEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

buffer filled by the runtime must be a null-terminated UTF-8 string.

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferStringEXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput char values

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

The xrGetSpatialBufferUint8EXT function is defined as: 

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

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of uint8_t . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_UINT8_EXT by using xrGetSpatialBufferUint8EXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferUint8EXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput uint8_t values

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

The xrGetSpatialBufferUint16EXT function is defined as: 

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

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of uint16_t . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_UINT16_EXT by using xrGetSpatialBufferUint16EXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferUint16EXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput uint16_t values

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

The xrGetSpatialBufferUint32EXT function is defined as: 

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

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of uint32_t . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_UINT32_EXT by using xrGetSpatialBufferUint32EXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferUint32EXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput uint32_t values

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

The xrGetSpatialBufferFloatEXT function is defined as: 

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

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of float . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT by using xrGetSpatialBufferFloatEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferFloatEXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput float values

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

The xrGetSpatialBufferVector2fEXT function is defined as: 

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

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of XrVector2f . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT by using xrGetSpatialBufferVector2fEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

The xrGetSpatialBufferVector3fEXT function is defined as: 

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

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of XrVector3f . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT by using xrGetSpatialBufferVector3fEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

The XrSpatialBufferGetInfoEXT structure is defined as: 

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • bufferId an XrSpatialBufferIdEXT for the buffer whose data to retrieve.

Valid Usage (Implicit)

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT is a reserved value representing an invalid XrSpatialBufferIdEXT . It may be passed to and returned from API functions only when specifically allowed.

Create Update Snapshot

The xrCreateSpatialUpdateSnapshotEXT function is defined as: 

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

Parameter Descriptions

The application can use xrCreateSpatialUpdateSnapshotEXT to create a snapshot and get the latest component data for specific entities as known by the runtime. Applications can provide the XrSpatialEntityEXT handles and the component types they are interested in when creating the snapshot.

The application can use XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes to filter the list of components whose data must be included in the snapshot. If the application provides a valid list of spatial component types in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , then the runtime must only include spatial entities in the snapshot that have at least one of the components provided in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Also, the runtime must only include data for those components in the snapshot.

The runtime must return XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT if any of the XrSpatialComponentTypeEXT in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes are not enabled for the spatial capabilities passed to XrSpatialContextCreateInfoEXT :: capabilityConfigs when creating spatialContext .

If the application does not provide a list of spatial component types in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , the runtime must include all the spatial entities listed in XrSpatialUpdateSnapshotCreateInfoEXT :: entities in the snapshot and it must include the data for all the enabled components of the capabilities configured for spatialContext .

The runtime must not include spatial entities that are not listed in XrSpatialUpdateSnapshotCreateInfoEXT :: entities in snapshot .

The application can create any number of snapshots it wants but must be mindful of the memory being allocated for each new snapshot and must destroy the snapshots once it no longer needs them.

Valid Usage (Implicit)

Return Codes

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

The XrSpatialUpdateSnapshotCreateInfoEXT structure is defined as: 

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;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • entityCount is a uint32_t describing the count of elements in the entities array.
  • entities is an array of XrSpatialEntityEXT for which the runtime must include the component data in the snapshot.
  • componentTypeCount is a uint32_t describing the count of elements in the componentTypes array.
  • componentTypes is an array of XrSpatialComponentTypeEXT for which the runtime must include the data in the snapshot.
  • baseSpace is the XrSpace relative to which all the locations of the update XrSpatialSnapshotEXT will be located.
  • time is the XrTime at which all the locations of the update XrSpatialSnapshotEXT will be located.

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialUpdateSnapshotCreateInfoEXT
  • type must be XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
  • next must be NULL or a valid pointer to the next structure in a structure chain
  • entities must be a pointer to an array of entityCount valid XrSpatialEntityEXT handles
  • If componentTypeCount is not 0 , componentTypes must be a pointer to an array of componentTypeCount valid XrSpatialComponentTypeEXT values
  • baseSpace must be a valid XrSpace handle
  • The entityCount parameter must be greater than 0
  • Both of baseSpace and the elements of entities must have been created, allocated, or retrieved from the same XrSession

Destroy snapshot

The xrDestroySpatialSnapshotEXT function is defined as: 

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

Parameter Descriptions

The application can call xrDestroySpatialSnapshotEXT to destroy the XrSpatialSnapshotEXT handle and the resources associated with it.

Valid Usage (Implicit)

Thread Safety

  • Access to snapshot , and any child handles, must be externally synchronized

Return Codes

موفقیت

  • XR_SUCCESS

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Common Components

Bounded 2D

Component data

The XrSpatialBounded2DDataEXT structure is defined as: 

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

Member Descriptions

  • center is an XrPosef defining the geometric center of the bounded 2D component.
  • extents is extents of the bounded 2D component along the x-axis (extents.width), y-axis (extents.height), centered on center .

The extents of the XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT refer to the entity's size in the xy plane of the plane's coordinate system. A plane with a position of {0, 0, 0}, rotation of {0, 0, 0, 1} (no rotation), and an extent of {1, 1} refers to a 1 meter x 1 meter plane centered at {0, 0, 0} with its front face normal vector pointing towards the +Z direction in the component's space.

XXYYZZ Height Height YYZZXX Vertical plane Vertical plane Horizontal Plane Horizontal Plane Width Width Width Width Height Height

Figure 24. Bounded2D Component Coordinate System

توجه داشته باشید

OpenXR uses an XY plane with +Z as the plane normal but other APIs may use an XZ plane with +Y as the plane normal. The XY plane can be converted to an XZ plane by rotating -π/2 radians around the +X axis.

Valid Usage (Implicit)

Component list structure to query data

The XrSpatialComponentBounded2DListEXT structure is defined as: 

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • boundCount is a uint32_t describing the count of elements in the bounds array.
  • bounds is an array of XrSpatialBounded2DDataEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentBounded2DListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if boundCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialDiscoverySnapshotCompleteEXT , then the runtime must provide XrSpatialBounded2DDataEXT :: center in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace and XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialUpdateSnapshotEXT , then the runtime must provide XrSpatialBounded2DDataEXT :: center in XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace and XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Valid Usage (Implicit)

پیکربندی

If XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum value in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list. This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Bounded 3D

Component data

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT uses XrBoxf for its data.

Component list structure to query data

The XrSpatialComponentBounded3DListEXT structure is defined as: 

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • boundCount is a uint32_t describing the count of elements in the bounds array.
  • bounds is an array of XrBoxf .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentBounded3DListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if boundCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialDiscoverySnapshotCompleteEXT , then the runtime must provide XrBoxf :: center in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace at XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialUpdateSnapshotEXT , then the runtime must provide XrBoxf :: center in XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace at XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Valid Usage (Implicit)

پیکربندی

If XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list. This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

والدین

Component data

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT uses XrSpatialEntityIdEXT for its data.

Component list structure to query data

The XrSpatialComponentParentListEXT structure is defined as: 

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • parentCount is a uint32_t describing the count of elements in the parents array.
  • parents is an array of XrSpatialEntityIdEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentParentListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if parentCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialComponentParentListEXT
  • type must be XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
  • next must be NULL or a valid pointer to the next structure in a structure chain
  • parents must be a pointer to an array of parentCount XrSpatialEntityIdEXT values
  • The parentCount parameter must be greater than 0
پیکربندی

If XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list. This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Mesh 3D

Component data

The XrSpatialMeshDataEXT structure is defined as: 

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

Member Descriptions

  • origin is an XrPosef defining the origin of the mesh. All vertices of the mesh must be relative to this origin.
  • vertexBuffer is an XrSpatialBufferEXT that provides the ID for a buffer that represents the vertex buffer of the entity this component is on. The position of vertices must be relative to origin .
  • indexBuffer is an XrSpatialBufferEXT that provides the ID for a buffer that represents an array of triangle indices, specifying the indices of the mesh vertices in the vertexBuffer . The triangle indices must be returned in counter-clockwise order and three indices denote one triangle.

The component type using XrSpatialMeshDataEXT must specify the XrSpatialBufferTypeEXT of the vertexBuffer and indexBuffer .

Valid Usage (Implicit)

Component list structure to query data

The XrSpatialComponentMesh3DListEXT structure is defined as: 

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • meshCount is a uint32_t describing the count of elements in the meshes array.
  • meshes is an array of XrSpatialMeshDataEXT .

The application can query the mesh 3D component of the spatial entities in an XrSpatialSnapshotEXT by adding XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes and adding XrSpatialComponentMesh3DListEXT to the next pointer chain of XrSpatialComponentDataQueryResultEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentMesh3DListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if meshCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

For the XrSpatialMeshDataEXT filled out by the runtime in the meshes array, the XrSpatialBufferEXT :: bufferType for XrSpatialMeshDataEXT :: vertexBuffer must be XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT and XrSpatialBufferEXT :: bufferType for XrSpatialMeshDataEXT :: indexBuffer must be XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Valid Usage (Implicit)

پیکربندی

If XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list of the XrSpatialCapabilityConfigurationBaseHeaderEXT derived structure of the capability that supports this component.

This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Tracking state filters

The XrSpatialFilterTrackingStateEXT structure is defined as: 

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

Member Descriptions

The application can use XrSpatialFilterTrackingStateEXT in the next chain of XrSpatialDiscoverySnapshotCreateInfoEXT to scope the discovery to only those entities whose tracking state is trackingState .

The application can use XrSpatialFilterTrackingStateEXT in the next chain of XrSpatialComponentDataQueryConditionEXT to scope the component data query from a snapshot only to entities whose tracking state is trackingState .

Valid Usage (Implicit)

Example code

Application Usage

Applications typically use the spatial entity extension in the following pattern:

Discover spatial entities & query component data

The following example code demonstrates how to discover spatial entities for capability "Foo" query its component data. 

/****************************/
/* 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));

Query buffer data

The following example code demonstrates how to get the data of a component that provides an 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.
  }
}

Extension guidelines

Semantic Label Design & Extension Guidelines

While this extension does not define any component for conveying the semantic label information of an entity, it lays down the design rules and guidelines for any extensions that do define such a component. In the following text, " should " and " must " constrain the authors of such functionality, rather than constraining a runtime implementation or an application using the API.

  • If an extension is defining semantic labels for any XrSpatialCapabilityEXT , it should do so by defining a new XrSpatialComponentTypeEXT as well as a new enumeration with a set of labels (a "semantic label set") to be the data for that component.
  • An enumeration representing a semantic label set must have a value to indicate that the entity is not categorized into any of the labels of this set. The name of this enumerant must include 'UNCATEGORIZED', eg XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT . This value indicates to applications that the runtime does recognize this entity, but that there are other semantic label sets where this entity is categorized.
  • Enumeration of this newly defined XrSpatialComponentTypeEXT in xrEnumerateSpatialCapabilityComponentTypesEXT implies that the runtime supports the semantic label set (and therefore the labels defined in the set) corresponding to that component type.
  • Applications express their desire to discover entities that have labels belonging to this semantic label set by including the corresponding XrSpatialComponentTypeEXT in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents array of the configuration struct for the capability that the component type is enumerated for.
  • It is possible that a single spatial entity has multiple components on it, each providing it with a label from their own semantic label set. Consider the following example with some hypothetical semantic label sets - XrSpatialObjectSemanticLabel , which might have values like chair, sofa, table etc., XrSpatialSofaBrand , which might have values like IKEA, Wayfair, etc., and XrSpatialIkeaSofa , which might have specific IKEA model names of sofas. In this scenario, the same sofa entity has all 3 components (labels from all 3 semantic label sets) on it, each giving a different granularity of information about the entity.
  • If an extension is defining a new XrSpatialComponentTypeEXT which provides a new semantic label set containing multiple labels in addition to the UNCATEGORIZED label, the extension should consider defining an XrSpatialCapabilityFeatureEXT which allows applications to activate only a subset of the labels defined in the semantic label set corresponding to that component type. This subset, provided in the next chain of the capability configuration, acts as a hint for runtimes to optimize their tracking pipelines and only track the subset provided. An example of such a feature struct is provided below .
  • Extensions must not add labels to existing semantic label set enumeration. They must instead define a new enumeration which contains equivalent enumerants with identical semantics and with values equal to those from the other set, in addition to the newly added enumerants. The specification of the newly defined semantic label set must also establish the mapping between the old label set and the new one. See example below .
Example Spatial Feature Definition for Semantic Label Subset 
// 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;
Example Spatial Semantic Label Extension 
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;

Consider the above example where an extension defines an enumeration XrSpatialExamplePlaneSemanticLabelExtensionEXT in order to extend the existing XrSpatialPlaneSemanticLabelEXT with values to represent doors and windows. The specification for the new enumeration must include text for the following form - 

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
|====

New Macros

New Base Types

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

New Object Types

New Commands

New Structures

New Enums

New Enum Constants

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • Extending XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • Extending 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

  • Extending 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

مسائل

  • Does a single entity always derive from solely a single capability?

    • حل شد
    • Answer: No. It is completely upto the runtime based on its own tracking capabilities and how it wants to represent a detected entity. The spec does not prescribe any particular representation of spatial entity except for the guaranteed components of a given capability to set a minimum expectation. A runtime may be able to merge entities detected by separate capabilities and represent them as a single entity with the guaranteed components of all the capabilities that helped identify it. An example of this could be that tables can be detected by both a plane tracking capability and an object tracking capability, with plane tracking providing the XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT component on the entity and object tracking providing XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT . A certain runtime may provide the table as 2 separate entities, each with their own set of guaranteed components, while certain runtimes may provide just 1 entity to represent the table, and have both XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT on the same entity. What is important to note here is that a given spatial entity can have at most a single component of any given component type . Therefore, if the component data produced by the different capabilities conflicts for a certain entity, the runtime must represent them as 2 separate entities.

تاریخچه نسخه

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

    • Initial extension description