XR_EXT_spatial_entity

رشته نام

XR_EXT_spatial_entity

نوع افزونه

افزونه نمونه

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

741

بازبینی

1

وضعیت تصویب

تصویب‌شده

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

XR_EXT_future

همیاران

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

نمای کلی

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

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

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

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

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

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

نهاد فضایی

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

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

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

نهادهای فضایی در OpenXR به‌عنوان یک سیستم نهاد-مؤلفه مدل‌سازی می‌شوند. هر نهاد فضایی مجموعه‌ای از مؤلفه‌ها دارد و هر مؤلفه مجموعه یکتایی از داده‌ها و رفتارها را برای آن نهاد ارائه می‌دهد.

نهادهای فضایی با یک اتم 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_GEOMETRY_POINT_ANDROID = 1000803000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1 = 1000808000,
    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

مؤلفه‌ای که شمارش تراز صفحه را برای نهاد فضایی ارائه می‌دهد. ساختار فهرست متناظر 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

مؤلفه‌ای که مکان لنگر را ارائه می‌دهد. ساختار فهرست متناظر 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

مؤلفه‌ای که حالت برخورد پرتو به یک نهاد را ارائه می‌دهد. ساختار فهرست متناظر 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)

XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID

مؤلفه‌ای که نهاد را به‌عنوان نقطه هندسی شناسایی می‌کند. هیچ فهرست یا ساختار داده‌ای برای این نوع مؤلفه وجود ندارد. وجود این مؤلفه صرفاً نشان‌دهنده توانایی یک نهاد برای متصل شدن به یک لنگر است. (افزوده‌شده توسط افزونه XR_ANDROID_spatial_geometry_point)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1

مؤلفه‌ای که دامنه(های) پایداری را که نهاد در آن پایدار است توصیف می‌کند. اگر زمان اجرا از XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT پشتیبانی کند، باید از این مؤلفه نیز پشتیبانی کند. ساختار داده متناظر XrSpatialBufferEXT است. ساختار فهرست مربوطه XrSpatialComponentPersistenceScopeDataListANDROIDX1 است. (افزوده‌شده توسط افزونه XR_ANDROIDX1_spatial_anchor_cloud_sharing)

قابلیت‌های فضایی و راه‌اندازی

قابلیت‌های فضایی توانایی‌های زمان اجرا را برای کشف موجودیت‌هایی که دارای مجموعه‌ای تضمین‌شده از مؤلفه‌ها هستند تعریف می‌کند. برنامه‌ها هنگام ایجاد 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

قابلیت شناسایی و ردیابی رمزینه‌های پاسخ‌سریع. (افزوده‌شده توسط افزونه XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

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

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

قابلیت شناسایی و ردیابی نشانگرهای Aruco. (افزوده‌شده توسط افزونه 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

Raycast دربرابر میان‌گیر عمق (افزوده‌شده توسط افزونه 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 است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • 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 ظرفیت آرایه است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • 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 فعال نشده است فهرست کند.

استفاده معتبر (ضمنی)

  • افزونه XR_EXT_spatial_entity باید قبل‌از فراخوانی xrEnumerateSpatialCapabilityFeaturesEXT فعال شود
  • 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 برای XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability در xrEnumerateSpatialCapabilityComponentTypesEXT شمارش نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT را برگرداند.

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

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

برای اطمینان از استفاده بهینه از منابع سیستم، زمان اجرا ممکن است از پیکربندی‌های ارائه‌شده در آرایه XrSpatialContextCreateInfoEXT استفاده کند تا خود را برای درخواست‌های فضایی آینده آماده کند. برای مثال، یک زمان اجرا که از قابلیت ردیابی صفحه پشتیبانی می‌کند، ممکن است تنها زمانی خط لوله ردیابی صفحه خود را آغاز کند که یک دسته بافتار فضایی حاوی قابلیت ردیابی صفحه توسط برنامه ایجاد شده باشد. اگر قابلیت‌های پیکربندی‌شده زمان آماده‌سازی طولانی داشته باشند، تماس با xrCreateSpatialDiscoverySnapshotAsyncEXT ممکن است منجر به عکس آنی خالی شود. برنامه می‌تواند قبل‌از استفاده از xrCreateSpatialDiscoverySnapshotAsyncEXT منتظر 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
  • ‫XR_ERROR_TIME_INVALID (اگر XR_ANDROID_spatial_annotation_tracking فعال باشد)

ساختار 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;

این ساختار مستقیماً در میانای برنامه‌سازی کاربردی استفاده نمی‌شود، اما ساختارهای فرزند آن می‌توانند با 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 عملیات ناهمگام شروع‌شده توسط xrCreateSpatialContextAsyncEXT را تکمیل می‌کند. اگر future در وضعیت آماده نباشد، زمان اجرا باید XR_ERROR_FUTURE_PENDING_EXT را برگرداند. اگر future قبلاً تکمیل یا لغو شده باشد، زمان اجرا باید XR_ERROR_FUTURE_INVALID_EXT را برگرداند.

استفاده معتبر (ضمنی)

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫futureResult XrResult عملیات ایجاد بافت فضایی است.
  • spatialContext یک XrSpatialContextEXT است که بااستفاده از داده‌ها و پیکربندی در xrCreateSpatialContextAsyncEXT :: createInfo ایجاد شده است.

کدهای برگشتی آتی

مقادیر futureResult:

موفقیت‌آمیز بود

  • 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

اگر futureResult کد موفقیت باشد، spatialContext باید معتبر باشد. اگر spatialContext معتبر باشد، فقط در چرخه حیات xrCreateSpatialContextAsyncEXT :: session یا تا زمانی که برنامه spatialContext را با xrDestroySpatialContextEXT ازبین ببرد (هرکدام که زودتر اتفاق بیفتد) معتبر باقی می‌ماند.

استفاده معتبر (ضمنی)

ازبین بردن بافت فضایی

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

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

شرح پارامترها

برنامه می‌تواند تابع xrDestroySpatialContextEXT را فراخوانی کند تا پس‌از اتمام تکالیف به‌روزرسانی و کاوش نهاد فضایی، دسته spatialContext و منابع زیربنایی را آزاد کند. اگر XrSpatialContextEXT معتبر دیگری وجود نداشته باشد که با همان قابلیت‌های فضایی spatialContext ایجاد شده باشد، این فراخوانی به‌عنوان پیشنهادی به زمان اجرا برای غیرفعال کردن سرویس‌های ردیابی موردنیاز برای آن قابلیت‌ها به‌منظور صرفه‌جویی در منابع سیستم عمل می‌کند.

استفاده معتبر (ضمنی)

ایمنی رشته‌ای

  • دسترسی به spatialContext و هرگونه دسته فرزند باید به‌صورت خارجی همگام‌سازی شود

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS

ناموفق

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

نمایش‌های نهاد فضایی

شناسه نهاد فضایی

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

از XrSpatialEntityIdEXT برای نمایش هر نوع موجودیتی که توسط زمان اجرا در محیط فضایی کاربر کشف شده است استفاده می‌شود. ‫XrSpatialEntityIdEXT برای XrSpatialContextEXT که در آن کشف شده است معتبر است و زمان اجرا نباید از همان XrSpatialEntityIdEXT برای نهادهای مختلف در همان XrSpatialContextEXT استفاده مجدد کند. همچنین، زمان اجرا نباید از همان XrSpatialEntityIdEXT در چندین XrSpatialContextEXT در همان XrSession استفاده مجدد کند، صرف‌نظر از اینکه همان نهاد را نشان می‌دهد یا نهادهای مختلف را.

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

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

دستگیره نهاد فضایی

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

دستگیره XrSpatialEntityEXT نشان‌دهنده یک موجودیت فضایی است. برنامه می‌تواند چنین دسته‌ای را برای بیان علاقه خود به یک نهاد خاص در زمان اجرا ایجاد کند.

ایجاد دسته موجودیت فضایی از شناسه

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

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

شرح پارامترها

برنامه می‌تواند از xrCreateSpatialEntityFromIdEXT برای ایجاد دسته XrSpatialEntityEXT استفاده کند که مرجعی به موجودیتی است که در محیط کاربر وجود دارد.

اگر XrSpatialEntityFromIdCreateInfoEXT :: entityId شناسه معتبری برای spatialContext نباشد، زمان اجرا باید XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT را برگرداند.

استفاده معتبر (ضمنی)

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
  • entityId عبارت است از XrSpatialEntityIdEXT نهادی که برنامه می‌خواهد برای آن نام کاربری ایجاد کند.

استفاده معتبر (ضمنی)

Destroy Spatial Entity Handle

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

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

شرح پارامترها

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

استفاده معتبر (ضمنی)

ایمنی رشته‌ای

  • دسترسی به spatialEntity و هرگونه دسته فرزند باید به‌صورت خارجی همگام‌سازی شود

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS

ناموفق

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

عکس آنی فضایی

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

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

برنامه می‌تواند هر تعداد عکس آنی که می‌خواهد ایجاد کند اما باید به حافظه‌ای که برای هر عکس آنی جدید اختصاص داده می‌شود توجه داشته باشد و وقتی دیگر به عکس‌های آنی نیاز ندارد باید آن‌ها را ازبین ببرد.

ایجاد عکس آنی کاوش

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

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

شرح پارامترها

برنامه می‌تواند با ایجاد عکس آنی کاوش بااستفاده از xrCreateSpatialDiscoverySnapshotAsyncEXT، موجودیت‌های فضایی را کاوش کند.

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

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

برنامه می‌تواند از XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes برای فیلتر کردن فهرست نهادها و مؤلفه‌هایی که زمان اجرا باید داده‌های آن‌ها را در عکس آنی بگنجاند استفاده کند. اگر برنامه فهرست معتبری از انواع مؤلفه‌های فضایی را در XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes ارائه دهد، زمان اجرا باید فقط موجودیت‌های فضایی را در عکس آنی لحاظ کند که حداقل یکی از مؤلفه‌های ارائه‌شده در XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes را داشته باشند. همچنین، زمان اجرا باید فقط شامل داده‌های مربوط به مؤلفه‌های موجود در عکس آنی باشد.

اگر هرکدام از XrSpatialComponentTypeEXT در XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes برای قابلیت‌های فضایی ارسال‌شده به XrSpatialContextCreateInfoEXT :: capabilityConfigs هنگام ایجاد spatialContext فعال نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT را برگرداند.

اگر برنامه فهرست انواع مؤلفه‌های فضایی را در XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes ارائه نکند، زمان اجرا باید همه موجودیت‌های فضایی را در عکس آنی که دارای مجموعه مؤلفه‌هایی هستند که در XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents برای قابلیت‌های پیکربندی‌شده برای spatialContext فهرست شده‌اند، لحاظ کند. زمان اجرا باید شامل داده‌های مربوط به همه مؤلفه‌های فعال‌شده قابلیت‌های پیکربندی‌شده برای spatialContext باشد.

اگر XrEventDataReferenceSpaceChangePending قبل‌از تکمیل future در صف قرار گیرد و XrEventDataReferenceSpaceChangePending :: poseValid نادرست باشد، زمان اجرا ممکن است یا XrSpatialSnapshotEXT ایجاد کند که هیچ موجودیتی در آن وجود ندارد یا XrSpatialEntityTrackingStateEXT موجودیت‌هایی را که دیگر در XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace در XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time قابل‌مکان‌یابی نیستند روی XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT یا XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT تنظیم کند. زمان اجرا نباید XrCreateSpatialContextCompletionEXT :: futureResult را به‌دلیل XrEventDataReferenceSpaceChangePending روی کد خطا تنظیم کند.

استفاده معتبر (ضمنی)

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
  • componentTypeCount یک uint32_t است که تعداد عناصر را در آرایه componentTypes توصیف می‌کند.
  • ‫componentTypes آرایه‌ای از XrSpatialComponentTypeEXT است.

ساختار XrSpatialDiscoverySnapshotCreateInfoEXT اطلاعات لازم برای ایجاد دسته XrSpatialSnapshotEXT را هنگام کشف نهادهای فضایی شرح می‌دهد.

استفاده معتبر (ضمنی)

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

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

شرح پارامترها

xrCreateSpatialDiscoverySnapshotCompleteEXT عملیات ناهمگام شروع‌شده توسط xrCreateSpatialDiscoverySnapshotAsyncEXT را تکمیل می‌کند. اگر XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future در وضعیت آماده نباشد، زمان اجرا باید XR_ERROR_FUTURE_PENDING_EXT را برگرداند. اگر XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future قبلاً تکمیل یا لغو شده باشد، زمان اجرا باید XR_ERROR_FUTURE_INVALID_EXT را برگرداند.

استفاده معتبر (ضمنی)

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫baseSpace عبارت است از XrSpace که همه مکان‌های XrSpatialSnapshotEXT اکتشاف در آن قرار خواهد گرفت.
  • time XrTime است که همه مکان‌های XrSpatialSnapshotEXT کشف‌شده در آن قرار خواهند گرفت.
  • future همان XrFutureEXT است که از xrCreateSpatialDiscoverySnapshotAsyncEXT دریافت شده است

مکان‌های موجود در داده‌های مؤلفه‌های مختلف که در عکس آنی ایجادشده گنجانده شده‌اند در baseSpace واقع در time نشان داده خواهند شد.

استفاده معتبر (ضمنی)

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫futureResult عبارت است از XrResult عملیات ایجاد عکس آنی کاوش فضایی.
  • ‫snapshot یک XrSpatialSnapshotEXT است که می‌توان از آن برای پُرسمان داده‌های مؤلفه موجودیت‌های فضایی کشف‌شده استفاده کرد.

کدهای برگشتی آتی

مقادیر futureResult:

موفقیت‌آمیز بود

  • 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

استفاده معتبر (ضمنی)

رویداد توصیه Discovery

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫spatialContext همان XrSpatialContextEXT است که زمان اجرا برای آن شناسایی را توصیه می‌کند.

برنامه می‌تواند این رویداد را بااستفاده از xrPollEvent بازیابی کند. برنامه می‌تواند با منتظر ماندن برای این رویداد، از تماس‌های بیش‌ازحد به xrCreateSpatialDiscoverySnapshotAsyncEXT برای کشف نهادهای فضایی جلوگیری کند. اگر برنامه چندین عکس آنی اکتشاف با XrSpatialDiscoverySnapshotCreateInfoEXT یکسان بین دو رویداد XrEventDataSpatialDiscoveryRecommendedEXT ایجاد کند، عکس‌های آنی حاصل ممکن است حاوی نهادهای یکسان باشند و بنابراین ایجاد عکس آنی و پُرسمان‌های داده بی‌فایده خواهد بود.

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

زمان اجرا نباید این رویداد را برای اطلاع‌رسانی به برنامه درباره تغییرات یا اصلاحات انجام‌شده در داده‌های مؤلفه نهادهای فضایی موجود در صف قرار دهد. برنامه می‌تواند از xrCreateSpatialUpdateSnapshotEXT برای پیگیری به‌روزرسانی‌های داده‌های مؤلفه برای موجودیت‌های فضایی موردعلاقه‌اش استفاده کند.

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

زمان اجرا نباید این رویداد را برای spatialContext مشخصی در صف قرار دهد تا زمانی که برنامه ایجاد آن را بااستفاده از xrCreateSpatialContextCompleteEXT تکمیل کند.

پس‌از اینکه برنامه xrDestroySpatialContextEXT را فراخوانی کرد، زمان اجرا نباید رویدادهای توصیه کاوش بیشتری را برای آن بافت فضایی در صف قرار دهد یا چنین رویدادهایی را برای آن بافت از xrPollEvent برگرداند.

استفاده معتبر (ضمنی)

داده‌های مؤلفه پُرسمان

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

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

شرح پارامترها

برنامه می‌تواند از xrQuerySpatialComponentDataEXT برای پرسمان داده‌های مؤلفه موجودیت‌ها در عکس آنی با پیوست کردن ساختار فهرست به XrSpatialComponentDataQueryResultEXT :: next مربوط به هر XrSpatialComponentTypeEXT در XrSpatialComponentDataQueryConditionEXT :: componentTypes استفاده کند.

اگر برنامه ساختار فهرستی را به XrSpatialComponentDataQueryResultEXT :: next پیوست کند که با هیچ‌یک از مؤلفه‌های فهرست‌شده در XrSpatialComponentDataQueryConditionEXT :: componentTypes مطابقت نداشته باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند.

برنامه می‌تواند انتخاب کند که ساختارهای فهرست مربوط به فقط زیرمجموعه‌ای از مؤلفه‌های فهرست‌شده در XrSpatialComponentDataQueryConditionEXT :: componentTypes را پیوست کند. اگر برنامه فقط بخواهد شناسه‌ها و وضعیت ردیابی موجودیت‌های فضایی را که با queryCondition مطابقت دارند بداند، می‌تواند انتخاب کند که ساختارهای فهرست را به‌طور کامل حذف کند. زمان اجرا نباید عدم وجود ساختارهای فهرست از زنجیره XrSpatialComponentDataQueryResultEXT :: next را به‌عنوان شکست تلقی کند.

اگر XrEventDataReferenceSpaceChangePending در صف باشد و XrEventDataReferenceSpaceChangePending :: changeTime درحالی‌که برنامه درحال پرسمان داده‌های مؤلفه از XrSpatialSnapshotEXT است منقضی شود، برنامه می‌تواند از داده‌های رویداد برای تنظیم کردن حالت‌ها استفاده کند.

زمان اجرا باید XrSpatialComponentDataQueryResultEXT :: entityIds را فقط با موجودیت‌هایی پر کند که همه مؤلفه‌های مشخص‌شده در XrSpatialComponentDataQueryConditionEXT :: componentTypes را داشته باشند. اگر XrSpatialComponentDataQueryConditionEXT :: componentTypeCount برابر با ۰ باشد، زمان اجرا باید queryResult را با همه موجودیت‌ها (و وضعیت‌های ردیابی آن‌ها) که در عکس آنی هستند پر کند. اگر شرایط پُرسمان بیشتری به XrSpatialComponentDataQueryConditionEXT :: next اضافه شود، زمان اجرا باید آن‌ها را به‌عنوان «AND» با دردسترس بودن انواع مؤلفه درنظر بگیرد، یعنی زمان اجرا باید XrSpatialComponentDataQueryResultEXT ::entityIds را فقط با نهادهایی که همه شرایط ارائه‌شده را برآورده می‌کنند پُر کند. زمان اجرا باید داده‌های مؤلفه را در ساختارهای فهرست با همان ترتیبی که موجودیت‌ها در XrSpatialComponentDataQueryResultEXT :: entityIds قرار دارند پر کند، یعنی داده‌های مؤلفه در یک نمایه مشخص در آرایه ساختار فهرست باید با موجودیت در همان نمایه مطابقت داشته باشد.

اگر وضعیت ردیابی برای موجودیتی XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT نباشد، زمان اجرا نباید داده‌ها را در نمایه مربوط به آن موجودیت در آرایه موجود در ساختارهای فهرست پیوست‌شده به XrSpatialComponentDataQueryResultEXT تغییر دهد.

استفاده معتبر (ضمنی)

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

به‌عنوان مثال، برنامه یک XrSpatialSnapshotEXT ایجاد می‌کند که حاوی ۵ نهاد است، که در آن -

  • نهاد ۱ و ۲ دارای مؤلفه‌های XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT و XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT هستند
  • نهاد ۳ و ۴ دارای مؤلفه‌های XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT و XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT هستند
  • نهاد ۵ دارای مؤلفه‌های XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT و XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT است.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

3

3

4

4

5

5

Bounded2D

Bounded2D

بله

بله

بله

بله

نه

نه

نه

نه

بله

بله

ولی

ولی

بله

بله

بله

بله

نه

نه

نه

نه

نه

نه

Mesh3D

Mesh3D

نه

نه

نه

نه

بله

بله

بله

بله

بله

بله

Bounded3D

Bounded3D

نه

نه

نه

نه

بله

بله

بله

بله

نه

No Text is not SVG - cannot display

شکل ۲۰. عکس آنی نمونه

xrQuerySpatialComponentDataEXT در عکس آنی بالا با XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT فهرست‌شده در شرایط پُرسمان منجر به برگرداندن موجودیت‌های ۱، ۲، و ۵ به برنامه می‌شود و برنامه می‌تواند آرایه‌ای از XrSpatialBounded2DDataEXT را به‌عنوان بخشی از ساختار XrSpatialComponentBounded2DListEXT به زنجیره بعدی XrSpatialComponentDataQueryResultEXT پیوست کند تا داده‌های bounded2D را دریافت کند.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

۵

5

Bounded2D

Bounded2D

داده‌های شناسه نهاد #۱

داده‌های نهاد...

داده‌های شناسه نهاد شماره ۲

داده‌های نهاد...

Data for entityId #5

داده‌های نهاد...

entityIds

entityIds

بعدی

بعدی

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

حدود

حدود

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou... نوشتار SVG نیست - نمایش داده نمی‌شود

شکل ۲۱. نمونه نتیجه پُرسمان

xrQuerySpatialComponentDataEXT در عکس آنی بالا با مؤلفه‌های XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT و XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT فهرست‌شده در شرایط پُرسمان منجر به برگرداندن موجودیت‌های شماره ۳ و ۴ به برنامه می‌شود و برنامه می‌تواند آرایه‌های XrBoxf و XrSpatialMeshDataEXT را به‌عنوان بخشی از ساختارهای XrSpatialComponentBounded3DListEXT و XrSpatialComponentMesh3DListEXT به‌ترتیب به زنجیره بعدی XrSpatialComponentDataQueryResultEXT پیوست کند تا داده‌های مؤلفه را دریافت کند.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

داده‌های شناسه نهاد شماره ۳

داده‌های نهاد...

داده‌های شناسه نهاد شماره ۴

داده‌های نهاد...

Mesh3D

Mesh3D

داده‌های شناسه نهاد شماره ۳

داده‌های نهاد...

داده‌های شناسه نهاد شماره ۴

داده‌های نهاد...

entityIds

entityIds

بعدی

بعدی

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

حدود

حدود

بعدی

بعدی

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

توری‌ها

meshes Text is not SVG - cannot display

شکل ۲۲. نمونه نتیجه پُرسمان

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

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

توضیحات عضو

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

استفاده معتبر (ضمنی)

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • entityIdCapacityInput ظرفیت آرایه entityIds است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • entityIdCountOutput تعداد XrSpatialEntityIdEXT در entityIds است، یا ظرفیت موردنیاز درصورتی‌که entityIdCapacityInput کافی نباشد.
  • ‫entityIds آرایه‌ای از XrSpatialEntityIdEXT است. اگر entityIdCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • entityStateCapacityInput ظرفیت آرایه entityStates است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • ‫entityStateCountOutput تعداد XrSpatialEntityTrackingStateEXT در entityStates است، یا ظرفیت موردنیاز درصورتی‌که entityStateCapacityInput کافی نباشد. این باید همیشه با entityIdCountOutput یکسان باشد.
  • ‫entityStates آرایه‌ای از XrSpatialEntityTrackingStateEXT است. اگر entityStateCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای شرح مفصل بازیابی اندازه entityIds موردنیاز، بخش پارامترهای اندازه میان‌گیر را ببینید.

برنامه می‌تواند از entityIds با xrCreateSpatialEntityFromIdEXT برای ایجاد دسته‌های XrSpatialEntityEXT برای نهادهایی که می‌خواهد به‌روزرسانی‌های منظم برای آن‌ها دریافت کند استفاده کند. سپس برنامه می‌تواند از این دسته‌های XrSpatialEntityEXT با xrCreateSpatialUpdateSnapshotEXT برای ایجاد یک عکس آنی به‌روزرسانی استفاده کند که دارای جدیدترین داده‌های شناخته‌شده زمان اجرا از مؤلفه‌ها برای موجودیت‌های ارائه‌شده است.

استفاده معتبر (ضمنی)

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

XrSpatialEntityTrackingStateEXT حالت‌های ممکن ردیابی موجودیت فضایی را برمی‌شمارد:

مقادیر شمارشی معانی زیر را دارند:

شرح شمارشی

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

زمان اجرا ردیابی این نهاد را متوقف کرده است و هرگز ردیابی آن را ازسر نخواهد گرفت.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

زمان اجرا ردیابی این نهاد را موقتاً متوقف کرده است اما ممکن است در آینده ردیابی آن را ازسر بگیرد.

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

زمان اجرا درحال‌حاضر این نهاد را ردیابی می‌کند و داده‌های مؤلفه آن معتبر است.

پیگیری

موقتاً متوقف

متوقف شده است

شکل ۲۳. XrSpatialEntityTrackingStateEXT

  • اگر زمان اجرا ردیابی موجودیت فضایی را تعلیق کند اما امکان ازسرگیری ردیابی آن در آینده وجود داشته باشد، زمان اجرا ممکن است وضعیت موجودیت فضایی را از XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT به XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT تغییر دهد. برخی‌از نمونه‌هایی که زمان اجرا ممکن است این کار را انجام دهد شامل (اما نه محدود به) موارد زیر است: اگر برنامه تمرکز ورودی را ازدست بدهد؛ یا اگر موجودیت فضایی داده‌شده خیلی از کاربر دور باشد و نتوان آن را به‌طور دقیق ردیابی کرد؛ یا اگر موجودیت‌های زیادی درحال ردیابی باشند و زمان اجرا بخواهد هزینه ردیابی را کاهش دهد. XrSpatialEntityTrackingStateEXT به برنامه کمک می‌کند تا خود را از خط‌مشی‌های ردگیری متفاوت هر زمان اجرا جدا کند.
  • زمان اجرا ممکن است وضعیت نهاد را از XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT به XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT یا XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT تغییر دهد.
  • اگر نهاد فضایی گم شود و ردیابی آن هرگز بازیابی یا ازسر گرفته نشود، زمان اجرا باید وضعیت نهاد فضایی را از XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT یا XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT به XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT تغییر دهد. نمونه‌ای از چنین موردی زمانی است که دستگاه ردیابی را ازدست می‌دهد، جلسه ردیابی خود را بازراه‌اندازی می‌کند اما نمی‌تواند دوباره در محیط خود مکان‌یابی کند، و بنابراین با نهادهای کشف‌شده این جلسه ردیابی به‌عنوان نهادهای جدید رفتار می‌کند.
  • وقتی وضعیت ردیابی یک موجودیت روی XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT تنظیم می‌شود، زمان اجرا باید هرگز آن را به وضعیت دیگری تغییر ندهد.
  • هنگام پرسمان داده‌های مؤلفه یک موجودیت فضایی بااستفاده از xrQuerySpatialComponentDataEXT، زمان اجرا باید داده‌های معتبر را در محتوای میان‌گیرهای ارائه‌شده توسط برنامه در زنجیره بعدی XrSpatialComponentDataQueryResultEXT تنظیم کند، اگر وضعیت موجودیت XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT باشد. اگر وضعیت نهاد XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT یا XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT باشد، زمان اجرا نباید محتوای میان‌گیرها را تغییر دهد.

اصطلاح دو تماسی برای داده‌های مؤلفه

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

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

توضیحات عضو

  • bufferId XrSpatialBufferIdEXT داده‌های میان‌گیر.
  • bufferType XrSpatialBufferTypeEXT است تا نوع داده را در bufferId نشان دهد. برنامه می‌تواند از bufferType استفاده کند تا تعیین کند از کدام تابع برای بازیابی داده‌های واقعی میان‌گیر استفاده کند.

برخی‌از مؤلفه‌های فضایی داده‌هایی با اندازه متغیر دارند و بنابراین برای بازیابی داده‌هایشان باید از اصطلاح دو فراخوانی استفاده شود. در چنین مواردی، ساختار داده مؤلفه فضایی یک XrSpatialBufferEXT برای هر میان‌گیر با اندازه متغیر موردنیاز در داده‌های آن مؤلفه ارائه می‌دهد.

برای همان bufferId ، زمان اجرا باید داده‌های یکسانی را از یک پُرسمان داده مؤلفه به پُرسمان دیگر ارائه دهد، حتی در بین یک عکس آنی به عکس آنی دیگر. وجود تفاوت bufferId بین فراخوانی‌های پرسمان داده مؤلفه به برنامه نشان می‌دهد که داده‌های آن مؤلفه ممکن است تغییر کرده باشد.

استفاده معتبر (ضمنی)

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT برای نمایش هر نوع داده با اندازه متغیر برای مؤلفه فضایی استفاده می‌شود.

زمان اجرا باید XrSpatialBufferIdEXT و داده‌های آن را حداقل برای چرخه حیات XrSpatialSnapshotEXT که حاوی آن است در حافظه نگه دارد. زمان اجرا ممکن است XrSpatialBufferIdEXT و داده‌های آن را برای مدت طولانی‌تری نسبت‌به چرخه حیات XrSpatialSnapshotEXT در حافظه نگه دارد تا همان شناسه را به‌عنوان بخشی از عکس‌های آنی که بعداً توسط برنامه ایجاد می‌شود برگرداند. برای همان XrSpatialBufferIdEXT ، زمان اجرا باید همیشه همان داده‌ها را ازطریق تابع xrGetSpatialBuffer* مناسب برگرداند.

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;

شمارش XrSpatialBufferTypeEXT انواع مختلف داده‌های میان‌گیر نشان‌داده‌شده XrSpatialBufferIdEXT را شناسایی می‌کند.

شرح‌های شمارشی

  • XR_SPATIAL_BUFFER_TYPE_STRING_EXT . XrSpatialBufferIdEXT می‌تواند به xrGetSpatialBufferStringEXT منتقل شود تا میان‌گیر رشته‌ای را بازیابی کند.
  • XR_SPATIAL_BUFFER_TYPE_UINT8_EXT . XrSpatialBufferIdEXT می‌تواند به xrGetSpatialBufferUint8EXT منتقل شود تا میان‌گیر uint8_t را بازیابی کند.
  • XR_SPATIAL_BUFFER_TYPE_UINT16_EXT . XrSpatialBufferIdEXT می‌تواند به xrGetSpatialBufferUint16EXT منتقل شود تا میان‌گیر uint16_t را بازیابی کند.
  • XR_SPATIAL_BUFFER_TYPE_UINT32_EXT . XrSpatialBufferIdEXT می‌تواند به xrGetSpatialBufferUint32EXT منتقل شود تا میان‌گیر uint32_t را بازیابی کند.
  • XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT . XrSpatialBufferIdEXT می‌تواند به xrGetSpatialBufferFloatEXT منتقل شود تا میان‌گیر float را بازیابی کند.
  • XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT . XrSpatialBufferIdEXT می‌تواند به xrGetSpatialBufferVector2fEXT منتقل شود تا میان‌گیر XrVector2f را بازیابی کند.
  • XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT . XrSpatialBufferIdEXT می‌تواند به xrGetSpatialBufferVector3fEXT منتقل شود تا میان‌گیر XrVector3f را بازیابی کند.

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

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

شرح پارامترها

  • ‫snapshot یک دسته برای XrSpatialSnapshotEXT است.
  • info اطلاعات مربوط به میان‌گیر را برای پُرسمان نگه می‌دارد.
  • bufferCapacityInput ظرفیت آرایه است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • bufferCountOutput تعداد نویسه‌ها یا ظرفیت موردنیاز درصورتی است که bufferCapacityInput کافی نباشد.
  • ‫buffer آرایه‌ای از char است. اگر bufferCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای شرح مفصل بازیابی اندازه buffer موردنیاز، بخش پارامترهای اندازه میان‌گیر را ببینید.

برنامه می‌تواند داده‌های XrSpatialBufferEXT ارائه‌شده توسط یک مؤلفه را دریافت کند، جایی که XrSpatialBufferEXT :: bufferType بااستفاده از xrGetSpatialBufferStringEXT XR_SPATIAL_BUFFER_TYPE_STRING_EXT است.

اگر XrSpatialBufferTypeEXT برای XrSpatialBufferGetInfoEXT :: bufferId برابر با XR_SPATIAL_BUFFER_TYPE_STRING_EXT نباشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند.

اگر XrSpatialBufferGetInfoEXT :: bufferId به snapshot تعلق نداشته باشد، زمان اجرا باید XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT را برگرداند.

buffer که توسط زمان اجرا تکمیل شده است باید رشته UTF-8 با پایان تهی باشد.

استفاده معتبر (ضمنی)

  • افزونه XR_EXT_spatial_entity باید قبل‌از فراخوانی xrGetSpatialBufferStringEXT فعال شود
  • snapshot باید یک شناسه XrSpatialSnapshotEXT معتبر باشد
  • info باید اشاره‌گری به ساختار معتبر XrSpatialBufferGetInfoEXT باشد
  • bufferCountOutput باید اشاره‌گری به مقدار uint32_t باشد
  • اگر bufferCapacityInput برابر با 0 نباشد، buffer باید اشاره‌گری به آرایه‌ای از مقادیر نویسه bufferCapacityInput باشد

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

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

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

شرح پارامترها

  • ‫snapshot یک دسته برای XrSpatialSnapshotEXT است.
  • info اطلاعات مربوط به میان‌گیر را برای پُرسمان نگه می‌دارد.
  • bufferCapacityInput ظرفیت آرایه است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • bufferCountOutput تعداد عناصر در آرایه buffer است، یا ظرفیت موردنیاز درصورتی‌که bufferCapacityInput کافی نباشد.
  • ‫buffer آرایه‌ای از uint8_t است. اگر bufferCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای شرح مفصل بازیابی اندازه buffer موردنیاز، بخش پارامترهای اندازه میان‌گیر را ببینید.

برنامه می‌تواند داده‌های XrSpatialBufferEXT ارائه‌شده توسط یک مؤلفه را دریافت کند، که در آن XrSpatialBufferEXT :: bufferType بااستفاده از xrGetSpatialBufferUint8EXT XR_SPATIAL_BUFFER_TYPE_UINT8_EXT است.

اگر XrSpatialBufferTypeEXT برای XrSpatialBufferGetInfoEXT :: bufferId برابر با XR_SPATIAL_BUFFER_TYPE_UINT8_EXT نباشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند.

اگر XrSpatialBufferGetInfoEXT :: bufferId به snapshot تعلق نداشته باشد، زمان اجرا باید XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT را برگرداند.

استفاده معتبر (ضمنی)

  • افزونه XR_EXT_spatial_entity باید قبل‌از فراخوانی xrGetSpatialBufferUint8EXT فعال شود
  • snapshot باید یک شناسه XrSpatialSnapshotEXT معتبر باشد
  • info باید اشاره‌گری به ساختار معتبر XrSpatialBufferGetInfoEXT باشد
  • bufferCountOutput باید اشاره‌گری به مقدار uint32_t باشد
  • اگر bufferCapacityInput 0 نباشد، buffer باید اشاره‌گری به آرایه‌ای از مقادیر bufferCapacityInput uint8_t باشد

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

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

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

شرح پارامترها

  • ‫snapshot یک دسته برای XrSpatialSnapshotEXT است.
  • info اطلاعات مربوط به میان‌گیر را برای پُرسمان نگه می‌دارد.
  • bufferCapacityInput ظرفیت آرایه است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • bufferCountOutput تعداد عناصر در آرایه buffer است، یا ظرفیت موردنیاز درصورتی‌که bufferCapacityInput کافی نباشد.
  • ‫buffer آرایه‌ای از uint16_t است. اگر bufferCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای شرح مفصل بازیابی اندازه buffer موردنیاز، بخش پارامترهای اندازه میان‌گیر را ببینید.

برنامه می‌تواند داده‌های XrSpatialBufferEXT ارائه‌شده توسط یک مؤلفه را دریافت کند، که در آن XrSpatialBufferEXT :: bufferType بااستفاده از xrGetSpatialBufferUint16EXT XR_SPATIAL_BUFFER_TYPE_UINT16_EXT است.

اگر XrSpatialBufferTypeEXT برای XrSpatialBufferGetInfoEXT :: bufferId برابر با XR_SPATIAL_BUFFER_TYPE_UINT16_EXT نباشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند.

اگر XrSpatialBufferGetInfoEXT :: bufferId به snapshot تعلق نداشته باشد، زمان اجرا باید XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT را برگرداند.

استفاده معتبر (ضمنی)

  • افزونه XR_EXT_spatial_entity باید قبل‌از فراخوانی xrGetSpatialBufferUint16EXT فعال شود
  • snapshot باید یک شناسه XrSpatialSnapshotEXT معتبر باشد
  • info باید اشاره‌گری به ساختار معتبر XrSpatialBufferGetInfoEXT باشد
  • bufferCountOutput باید اشاره‌گری به مقدار uint32_t باشد
  • اگر bufferCapacityInput 0 نباشد، buffer باید اشاره‌گری به آرایه‌ای از مقادیر bufferCapacityInput uint16_t باشد

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

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

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

شرح پارامترها

  • ‫snapshot یک دسته برای XrSpatialSnapshotEXT است.
  • info اطلاعات مربوط به میان‌گیر را برای پُرسمان نگه می‌دارد.
  • bufferCapacityInput ظرفیت آرایه است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • bufferCountOutput تعداد عناصر در آرایه buffer است، یا ظرفیت موردنیاز درصورتی‌که bufferCapacityInput کافی نباشد.
  • ‫buffer آرایه‌ای از uint32_t است. اگر bufferCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای شرح مفصل بازیابی اندازه buffer موردنیاز، بخش پارامترهای اندازه میان‌گیر را ببینید.

برنامه می‌تواند داده‌های XrSpatialBufferEXT ارائه‌شده توسط یک مؤلفه را دریافت کند، جایی که XrSpatialBufferEXT :: bufferType XR_SPATIAL_BUFFER_TYPE_UINT32_EXT است بااستفاده از xrGetSpatialBufferUint32EXT .

اگر XrSpatialBufferTypeEXT برای XrSpatialBufferGetInfoEXT :: bufferId برابر با XR_SPATIAL_BUFFER_TYPE_UINT32_EXT نباشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند.

اگر XrSpatialBufferGetInfoEXT :: bufferId به snapshot تعلق نداشته باشد، زمان اجرا باید XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT را برگرداند.

استفاده معتبر (ضمنی)

  • افزونه XR_EXT_spatial_entity باید قبل‌از فراخوانی xrGetSpatialBufferUint32EXT فعال شود
  • snapshot باید یک شناسه XrSpatialSnapshotEXT معتبر باشد
  • info باید اشاره‌گری به ساختار معتبر XrSpatialBufferGetInfoEXT باشد
  • bufferCountOutput باید اشاره‌گری به مقدار uint32_t باشد
  • اگر bufferCapacityInput 0 نباشد، buffer باید اشاره‌گری به آرایه‌ای از مقادیر bufferCapacityInput uint32_t باشد

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

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

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

شرح پارامترها

  • ‫snapshot یک دسته برای XrSpatialSnapshotEXT است.
  • info اطلاعات مربوط به میان‌گیر را برای پُرسمان نگه می‌دارد.
  • bufferCapacityInput ظرفیت آرایه است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • bufferCountOutput تعداد عناصر در آرایه buffer است، یا ظرفیت موردنیاز درصورتی‌که bufferCapacityInput کافی نباشد.
  • ‫buffer آرایه‌ای از float است. اگر bufferCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای شرح مفصل بازیابی اندازه buffer موردنیاز، بخش پارامترهای اندازه میان‌گیر را ببینید.

برنامه می‌تواند داده‌های XrSpatialBufferEXT ارائه‌شده توسط مؤلفه را دریافت کند، که در آن XrSpatialBufferEXT :: bufferType بااستفاده از xrGetSpatialBufferFloatEXT XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT است.

اگر XrSpatialBufferTypeEXT برای XrSpatialBufferGetInfoEXT :: bufferId برابر با XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT نباشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند.

اگر XrSpatialBufferGetInfoEXT :: bufferId به snapshot تعلق نداشته باشد، زمان اجرا باید XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT را برگرداند.

استفاده معتبر (ضمنی)

  • افزونه XR_EXT_spatial_entity باید قبل‌از فراخوانی xrGetSpatialBufferFloatEXT فعال شود
  • snapshot باید یک شناسه XrSpatialSnapshotEXT معتبر باشد
  • info باید اشاره‌گری به ساختار معتبر XrSpatialBufferGetInfoEXT باشد
  • bufferCountOutput باید اشاره‌گری به مقدار uint32_t باشد
  • اگر bufferCapacityInput 0 نباشد، buffer باید اشاره‌گری به آرایه‌ای از مقادیر bufferCapacityInput float باشد

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

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

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

شرح پارامترها

  • ‫snapshot یک دسته برای XrSpatialSnapshotEXT است.
  • info اطلاعات مربوط به میان‌گیر را برای پُرسمان نگه می‌دارد.
  • bufferCapacityInput ظرفیت آرایه است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • bufferCountOutput تعداد عناصر در آرایه buffer است، یا ظرفیت موردنیاز درصورتی‌که bufferCapacityInput کافی نباشد.
  • ‫buffer آرایه‌ای از XrVector2f است. اگر bufferCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای شرح مفصل بازیابی اندازه buffer موردنیاز، بخش پارامترهای اندازه میان‌گیر را ببینید.

برنامه می‌تواند داده‌های XrSpatialBufferEXT ارائه‌شده توسط مؤلفه را دریافت کند، که در آن XrSpatialBufferEXT :: bufferType بااستفاده از xrGetSpatialBufferVector2fEXT XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT است.

اگر XrSpatialBufferTypeEXT برای XrSpatialBufferGetInfoEXT :: bufferId برابر با XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT نباشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند.

اگر XrSpatialBufferGetInfoEXT :: bufferId به snapshot تعلق نداشته باشد، زمان اجرا باید XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT را برگرداند.

استفاده معتبر (ضمنی)

  • افزونه XR_EXT_spatial_entity باید قبل‌از فراخوانی xrGetSpatialBufferVector2fEXT فعال شود
  • snapshot باید یک شناسه XrSpatialSnapshotEXT معتبر باشد
  • info باید اشاره‌گری به ساختار معتبر XrSpatialBufferGetInfoEXT باشد
  • bufferCountOutput باید اشاره‌گری به مقدار uint32_t باشد
  • اگر bufferCapacityInput 0 نباشد، buffer باید اشاره‌گری به آرایه‌ای از ساختارهای bufferCapacityInput XrVector2f باشد

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

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

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

شرح پارامترها

  • ‫snapshot یک دسته برای XrSpatialSnapshotEXT است.
  • info اطلاعات مربوط به میان‌گیر را برای پُرسمان نگه می‌دارد.
  • bufferCapacityInput ظرفیت آرایه است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • bufferCountOutput تعداد عناصر در آرایه buffer است، یا ظرفیت موردنیاز درصورتی‌که bufferCapacityInput کافی نباشد.
  • ‫buffer آرایه‌ای از XrVector3f است. اگر bufferCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای شرح مفصل بازیابی اندازه buffer موردنیاز، بخش پارامترهای اندازه میان‌گیر را ببینید.

برنامه می‌تواند داده‌های XrSpatialBufferEXT ارائه‌شده توسط مؤلفه را دریافت کند، که در آن XrSpatialBufferEXT :: bufferType بااستفاده از xrGetSpatialBufferVector3fEXT XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT است.

اگر XrSpatialBufferTypeEXT برای XrSpatialBufferGetInfoEXT :: bufferId برابر با XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT نباشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند.

اگر XrSpatialBufferGetInfoEXT :: bufferId به snapshot تعلق نداشته باشد، زمان اجرا باید XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT را برگرداند.

استفاده معتبر (ضمنی)

  • افزونه XR_EXT_spatial_entity باید قبل‌از فراخوانی xrGetSpatialBufferVector3fEXT فعال شود
  • snapshot باید یک شناسه XrSpatialSnapshotEXT معتبر باشد
  • info باید اشاره‌گری به ساختار معتبر XrSpatialBufferGetInfoEXT باشد
  • bufferCountOutput باید اشاره‌گری به مقدار uint32_t باشد
  • اگر bufferCapacityInput 0 نباشد، buffer باید اشاره‌گری به آرایه‌ای از ساختارهای bufferCapacityInput XrVector3f باشد

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • bufferId XrSpatialBufferIdEXT برای میان‌گیری که داده‌های آن بازیابی می‌شود.

استفاده معتبر (ضمنی)

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

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

ایجاد عکس آنی به‌روزرسانی

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

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

شرح پارامترها

برنامه می‌تواند از xrCreateSpatialUpdateSnapshotEXT برای ایجاد عکس آنی و دریافت جدیدترین داده‌های مؤلفه برای نهادهای خاصی که برای زمان اجرا شناخته‌شده هستند استفاده کند. برنامه‌ها می‌توانند دسته‌های XrSpatialEntityEXT و انواع مؤلفه‌هایی را که به آن‌ها علاقه‌مند هستند هنگام ایجاد عکس آنی ارائه دهند.

برنامه می‌تواند از XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes برای فیلتر کردن فهرست مؤلفه‌هایی که داده‌های آن‌ها باید در عکس آنی گنجانده شود استفاده کند. اگر برنامه فهرست معتبری از انواع مؤلفه‌های فضایی را در XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes ارائه دهد، زمان اجرا باید فقط موجودیت‌های فضایی را در عکس آنی لحاظ کند که حداقل یکی از مؤلفه‌های ارائه‌شده در XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes را داشته باشند. همچنین، زمان اجرا باید فقط شامل داده‌های مربوط به آن مؤلفه‌ها در عکس آنی باشد.

اگر هرکدام از XrSpatialComponentTypeEXT در XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes برای قابلیت‌های فضایی ارسال‌شده به XrSpatialContextCreateInfoEXT :: capabilityConfigs هنگام ایجاد spatialContext فعال نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT را برگرداند.

اگر برنامه فهرستی از انواع مؤلفه‌های فضایی را در XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes ارائه نکند، زمان اجرا باید همه موجودیت‌های فضایی فهرست‌شده در XrSpatialUpdateSnapshotCreateInfoEXT :: entities را در عکس آنی لحاظ کند و باید داده‌های مربوط به همه مؤلفه‌های فعال‌شده قابلیت‌های پیکربندی‌شده برای spatialContext را لحاظ کند.

زمان اجرا نباید شامل موجودیت‌های فضایی باشد که در XrSpatialUpdateSnapshotCreateInfoEXT :: entities در snapshot فهرست نشده‌اند.

برنامه می‌تواند هر تعداد عکس آنی که می‌خواهد ایجاد کند اما باید به حافظه‌ای که برای هر عکس آنی جدید اختصاص داده می‌شود توجه داشته باشد و وقتی دیگر به عکس‌های آنی نیاز ندارد باید آن‌ها را ازبین ببرد.

استفاده معتبر (ضمنی)

کدهای برگشتی

موفقیت‌آمیز بود

  • 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

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

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;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
  • entityCount یک uint32_t است که تعداد عناصر را در آرایه entities توصیف می‌کند.
  • entities آرایه‌ای از XrSpatialEntityEXT است که زمان اجرا باید داده‌های مؤلفه را در عکس آنی لحاظ کند.
  • componentTypeCount یک uint32_t است که تعداد عناصر را در آرایه componentTypes توصیف می‌کند.
  • componentTypes آرایه‌ای از XrSpatialComponentTypeEXT است که زمان اجرا باید داده‌ها را در عکس آنی لحاظ کند.
  • ‫baseSpace XrSpace است که همه مکان‌های به‌روزرسانی XrSpatialSnapshotEXT نسبت به آن قرار خواهند گرفت.
  • time XrTime است که همه مکان‌های به‌روزرسانی XrSpatialSnapshotEXT در آن قرار خواهند گرفت.

استفاده معتبر (ضمنی)

  • افزونه XR_EXT_spatial_entity باید قبل‌از استفاده از XrSpatialUpdateSnapshotCreateInfoEXT فعال شود
  • type باید XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT باشد
  • ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد
  • entities باید اشاره‌گری به آرایه‌ای از entityCount دسته XrSpatialEntityEXT معتبر باشد
  • اگر componentTypeCount برابر با 0 نباشد، componentTypes باید اشاره‌گری به آرایه‌ای از مقادیر معتبر componentTypeCount XrSpatialComponentTypeEXT باشد
  • baseSpace باید شناسه مجازی XrSpace معتبر باشد
  • پارامتر entityCount باید بزرگ‌تر از 0 باشد
  • هر دو baseSpace و عناصر entities باید از همان XrSession ایجاد، اختصاص، یا بازیابی شده باشند

ازبین بردن عکس آنی

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

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

شرح پارامترها

برنامه می‌تواند xrDestroySpatialSnapshotEXT را فراخوانی کند تا دسته XrSpatialSnapshotEXT و منابع مرتبط با آن را ازبین ببرد.

استفاده معتبر (ضمنی)

ایمنی رشته‌ای

  • دسترسی به snapshot و هرگونه دسته فرزند باید به‌صورت خارجی همگام‌سازی شود

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS

ناموفق

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

اجزای مشترک

دوبعدی محدودشده

داده‌های مؤلفه

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

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

توضیحات عضو

  • center یک XrPosef است که مرکز هندسی مؤلفه دوبعدی محدودشده را تعریف می‌کند.
  • extents حدود مؤلفه دوبعدی محدودشده در امتداد محور x (extents.width)، محور y (extents.height)، با مرکزیت center است.

extents XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT به اندازه نهاد در صفحه x-y سیستم مختصات صفحه اشاره دارد. صفحه‌ای با موقعیت {0, 0, 0}، چرخش {0, 0, 0, 1} (بدون چرخش)، و وسعت {1, 1} به صفحه‌ای ۱ متر در ۱ متر اشاره دارد که مرکز آن در {0, 0, 0} قرار دارد و بردار نرمال وجه جلویی آن به‌سمت جهت +Z در فضای مؤلفه اشاره می‌کند.

X X Y Y Z Z ارتفاع ارتفاع Y Y Z Z X X صفحه عمودی صفحه عمودی صفحه افقی صفحه افقی عرض عرض عرض عرض ارتفاع ارتفاع

شکل ۲۴. Bounded2D Component Coordinate System

توجه

OpenXR از صفحه X-Y با +Z به‌عنوان صفحه نرمال استفاده می‌کند، اما میاناهای برنامه‌سازی کاربردی دیگر ممکن است از صفحه X-Z با +Y به‌عنوان صفحه نرمال استفاده کنند. صفحه X-Y می‌تواند با چرخش π/2- رادیان حول محور X+ به صفحه X-Z تبدیل شود.

استفاده معتبر (ضمنی)

ساختار فهرست مؤلفه برای پرسمان داده‌ها

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
  • boundCount یک uint32_t است که تعداد عناصر را در آرایه bounds توصیف می‌کند.
  • ‫bounds آرایه‌ای از XrSpatialBounded2DDataEXT است.

اگر XrSpatialComponentBounded2DListEXT در زنجیره بعدی XrSpatialComponentDataQueryResultEXT :: next باشد اما XrSpatialComponentDataQueryConditionEXT ::componentTypeCount صفر نباشد و XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT در XrSpatialComponentDataQueryConditionEXT :: componentTypes گنجانده نشده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را از xrQuerySpatialComponentDataEXT برگرداند.

اگر boundCount کمتر از XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput باشد، زمان اجرا باید XR_ERROR_SIZE_INSUFFICIENT را از xrQuerySpatialComponentDataEXT برگرداند.

اگر xrQuerySpatialComponentDataEXT :: snapshot از xrCreateSpatialDiscoverySnapshotCompleteEXT ایجاد شده باشد، زمان اجرا باید XrSpatialBounded2DDataEXT :: center را در XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace و XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time ارائه دهد.

اگر xrQuerySpatialComponentDataEXT :: snapshot از xrCreateSpatialUpdateSnapshotEXT ایجاد شده باشد، زمان اجرا باید XrSpatialBounded2DDataEXT :: center را در XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace و XrSpatialUpdateSnapshotCreateInfoEXT :: time ارائه دهد.

استفاده معتبر (ضمنی)

پیکربندی

اگر XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT در XrSpatialCapabilityComponentTypesEXT :: componentTypes برای برخی قابلیت‌ها شمارش شده باشد، برنامه می‌تواند با گنجاندن مقدار شمارشی در فهرست XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents آن را فعال کند. این مؤلفه برای گنجانده شدن در زنجیره بعدی XrSpatialCapabilityConfigurationBaseHeaderEXT به پیکربندی خاصی نیاز ندارد.

سه‌بعدی محدودشده

داده‌های مؤلفه

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT از XrBoxf برای داده‌هایش استفاده می‌کند.

ساختار فهرست مؤلفه برای پرسمان داده‌ها

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
  • boundCount یک uint32_t است که تعداد عناصر را در آرایه bounds توصیف می‌کند.
  • ‫bounds آرایه‌ای از XrBoxf است.

اگر XrSpatialComponentBounded3DListEXT در زنجیره بعدی XrSpatialComponentDataQueryResultEXT :: next باشد اما XrSpatialComponentDataQueryConditionEXT ::componentTypeCount صفر نباشد و XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT در XrSpatialComponentDataQueryConditionEXT :: componentTypes گنجانده نشده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را از xrQuerySpatialComponentDataEXT برگرداند.

اگر boundCount کمتر از XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput باشد، زمان اجرا باید XR_ERROR_SIZE_INSUFFICIENT را از xrQuerySpatialComponentDataEXT برگرداند.

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

اگر xrQuerySpatialComponentDataEXT :: snapshot از xrCreateSpatialUpdateSnapshotEXT ایجاد شده باشد، زمان اجرا باید XrBoxf :: center را در XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace در XrSpatialUpdateSnapshotCreateInfoEXT :: time ارائه دهد.

استفاده معتبر (ضمنی)

  • افزونه XR_EXT_spatial_entity باید قبل‌از استفاده از XrSpatialComponentBounded3DListEXT فعال شود
  • type باید XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT باشد
  • ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد
  • bounds باید اشاره‌گری به آرایه‌ای از ساختارهای boundCount XrBoxf باشد
  • پارامتر boundCount باید بزرگ‌تر از 0 باشد
پیکربندی

اگر XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT در XrSpatialCapabilityComponentTypesEXT :: componentTypes برای برخی قابلیت‌ها شمارش شده باشد، برنامه می‌تواند آن را با گنجاندن enum در فهرست XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents فعال کند. این مؤلفه برای گنجانده شدن در زنجیره بعدی XrSpatialCapabilityConfigurationBaseHeaderEXT به پیکربندی خاصی نیاز ندارد.

ولی

داده‌های مؤلفه

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT از XrSpatialEntityIdEXT برای داده‌هایش استفاده می‌کند.

ساختار فهرست مؤلفه برای پرسمان داده‌ها

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
  • parentCount یک uint32_t است که تعداد عناصر را در آرایه parents توصیف می‌کند.
  • ‫parents آرایه‌ای از XrSpatialEntityIdEXT است.

اگر XrSpatialComponentParentListEXT در زنجیره بعدی XrSpatialComponentDataQueryResultEXT :: next باشد اما XrSpatialComponentDataQueryConditionEXT ::componentTypeCount صفر نباشد و XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT در XrSpatialComponentDataQueryConditionEXT :: componentTypes گنجانده نشده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را از xrQuerySpatialComponentDataEXT برگرداند.

اگر parentCount کمتر از XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput باشد، زمان اجرا باید XR_ERROR_SIZE_INSUFFICIENT را از xrQuerySpatialComponentDataEXT برگرداند.

استفاده معتبر (ضمنی)

  • افزونه XR_EXT_spatial_entity باید پیش‌از استفاده از XrSpatialComponentParentListEXT فعال شود
  • type باید XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT باشد
  • ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد
  • parents باید اشاره‌گری به آرایه‌ای از مقادیر parentCount XrSpatialEntityIdEXT باشد
  • پارامتر parentCount باید بزرگ‌تر از 0 باشد
پیکربندی

اگر XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT در XrSpatialCapabilityComponentTypesEXT :: componentTypes برای برخی قابلیت‌ها شمارش شده باشد، برنامه می‌تواند آن را با گنجاندن enum در فهرست XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents فعال کند. این مؤلفه برای گنجانده شدن در زنجیره بعدی XrSpatialCapabilityConfigurationBaseHeaderEXT به پیکربندی خاصی نیاز ندارد.

سه‌بعدی توری

داده‌های مؤلفه

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

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

توضیحات عضو

  • ‫origin یک XrPosef است که مبدأ مش را تعریف می‌کند. همه رأس‌های مش باید نسبت به این مبدأ باشند.
  • ‫vertexBuffer یک XrSpatialBufferEXT است که شناسه میان‌گیری را ارائه می‌دهد که نشان‌دهنده میان‌گیر رأس نهادی است که این مؤلفه روی آن قرار دارد. موقعیت رأس‌ها باید نسبت به origin باشد.
  • ‫indexBuffer یک XrSpatialBufferEXT است که شناسه میان‌گیری را ارائه می‌دهد که نشان‌دهنده آرایه‌ای از شاخص‌های مثلثی است و شاخص‌های رئوس مش را در vertexBuffer مشخص می‌کند. شاخص‌های مثلث باید به‌ترتیب پادساعتگرد برگردانده شوند و سه شاخص نشان‌دهنده یک مثلث است.

نوع مؤلفه‌ای که از XrSpatialMeshDataEXT استفاده می‌کند باید XrSpatialBufferTypeEXT مربوط به vertexBuffer و indexBuffer را مشخص کند.

استفاده معتبر (ضمنی)

ساختار فهرست مؤلفه برای پرسمان داده‌ها

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • meshCount یک uint32_t است که تعداد عناصر را در آرایه meshes توصیف می‌کند.
  • ‫meshes آرایه‌ای از XrSpatialMeshDataEXT است.

برنامه می‌تواند با افزودن XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT در XrSpatialComponentDataQueryConditionEXT :: componentTypes و افزودن XrSpatialComponentMesh3DListEXT به زنجیره اشاره‌گر بعدی XrSpatialComponentDataQueryResultEXT، مؤلفه سه‌بعدی مش موجودیت‌های فضایی را در XrSpatialSnapshotEXT پُرسمان کند.

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 .

اگر meshCount کمتر از XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput باشد، زمان اجرا باید XR_ERROR_SIZE_INSUFFICIENT را از xrQuerySpatialComponentDataEXT برگرداند.

برای XrSpatialMeshDataEXT که توسط زمان اجرا در آرایه meshes تکمیل شده است، XrSpatialBufferEXT :: bufferType برای XrSpatialMeshDataEXT :: vertexBuffer باید XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT باشد و XrSpatialBufferEXT :: bufferType برای XrSpatialMeshDataEXT :: indexBuffer باید XR_SPATIAL_BUFFER_TYPE_UINT32_EXT باشد.

استفاده معتبر (ضمنی)

پیکربندی

اگر XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT در XrSpatialCapabilityComponentTypesEXT :: componentTypes برای قابلیتی شمارش شده باشد، برنامه می‌تواند آن را با گنجاندن enum در فهرست XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents از ساختار مشتق‌شده XrSpatialCapabilityConfigurationBaseHeaderEXT مربوط به قابلیتی که از این مؤلفه پشتیبانی می‌کند فعال کند.

این مؤلفه برای گنجانده شدن در زنجیره بعدی XrSpatialCapabilityConfigurationBaseHeaderEXT به پیکربندی خاصی نیاز ندارد.

فیلترهای وضعیت ردیابی

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

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

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫trackingState همان XrSpatialEntityTrackingStateEXT است که برنامه می‌خواهد فیلتر را برای آن اعمال کند.

برنامه می‌تواند از XrSpatialFilterTrackingStateEXT در زنجیره بعدی XrSpatialDiscoverySnapshotCreateInfoEXT استفاده کند تا دامنه کاوش را فقط به آن دسته از نهادهایی محدود کند که وضعیت ردیابی آن‌ها trackingState است.

برنامه می‌تواند از XrSpatialFilterTrackingStateEXT در زنجیره بعدی XrSpatialComponentDataQueryConditionEXT استفاده کند تا پرس‌وجوی داده‌های مؤلفه را از یک عکس آنی فقط به موجودیت‌هایی محدود کند که وضعیت ردیابی آن‌ها trackingState است.

استفاده معتبر (ضمنی)

کد نمونه

استفاده از برنامه

برنامه‌ها معمولاً از افزونه نهاد فضایی در الگوی زیر استفاده می‌کنند:

  • برنامه ابتدا قابلیت‌های فضایی سیستم را بااستفاده از xrEnumerateSpatialCapabilitiesEXT برمی‌شمارد. سپس آرایه برگردانده‌شده XrSpatialCapabilityEXT را بررسی می‌کند و مؤلفه‌ها و ویژگی‌های پشتیبانی‌شده برای هریک از آن قابلیت‌ها را به‌ترتیب بااستفاده از xrEnumerateSpatialCapabilityComponentTypesEXT و xrEnumerateSpatialCapabilityFeaturesEXT برمی‌شمارد. این کار به برنامه تصویر کاملی از مؤلفه‌هایی که می‌تواند فعال کند و پیکربندی‌هایی که این قابلیت می‌پذیرد ارائه می‌دهد.
  • سپس برنامه یک یا چند دسته XrSpatialContextEXT با پیکربندی‌های قابلیت فضایی خاص ایجاد می‌کند، که در آن پیکربندی‌ها قابلیت خاصی را در بافت فضایی فعال و پیکربندی می‌کنند، و مؤلفه‌هایی را برای آن قابلیت‌ها فعال و پیکربندی می‌کنند.
  • برای هر XrSpatialContextEXT، برنامه قبل‌از استفاده از xrCreateSpatialDiscoverySnapshotAsyncEXT برای کشف نهادهای فضایی، منتظر دریافت رویدادهای XrEventDataSpatialDiscoveryRecommendedEXT برای آن XrSpatialContextEXT می‌ماند. پس‌از تکمیل این عملیات ناهمگام، برنامه یک دسته XrSpatialSnapshotEXT دریافت می‌کند.
  • برنامه بااستفاده از xrQuerySpatialComponentDataEXT، موجودیت‌ها و داده‌های مؤلفه موجود در این XrSpatialSnapshotEXT را جستجو می‌کند. اگر وضعیت نهاد XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT باشد، برنامه جدیدترین داده‌های مؤلفه نهادهای پُرسمان‌شده را از ساختارهای پیوست‌شده به زنجیره بعدی XrSpatialComponentDataQueryResultEXT می‌خواند.
  • اگر نهادهای خاصی وجود داشته باشد که برنامه آن‌ها را به‌عنوان نهادهای جالب شناسایی کند و بخواهد به‌روزرسانی‌های آن‌ها را درطول زمان دریافت کند، بااستفاده از xrCreateSpatialEntityFromIdEXT دسته‌های XrSpatialEntityEXT را برای آن نهادها ایجاد می‌کند. برنامه بااستفاده از xrCreateSpatialUpdateSnapshotEXT به‌روزرسانی‌های این نهادهای جالب را دریافت می‌کند و از همان تابع xrQuerySpatialComponentDataEXT در XrSpatialSnapshotEXT تازه ایجادشده استفاده می‌کند تا جدیدترین داده‌های مؤلفه را برای آن نهادها دریافت کند.

کاوش نهادهای فضایی و داده‌های مؤلفه پُرسمان

کد نمونه زیر نشان می‌دهد چگونه می‌توان موجودیت‌های فضایی را برای قابلیت «Foo» پیدا کرد و داده‌های مؤلفه آن را پُرسمان کرد.

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

داده‌های میان‌گیر پُرسمان

کد نمونه زیر نشان می‌دهد که چگونه داده‌های مؤلفه‌ای را که 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.
  }
}

رهنمودهای افزونه

  • اگر افزونه‌ای XrSpatialComponentTypeEXT جدیدی را تعریف کند که داده‌های بیشتری درباره موجودیت فضایی ارائه می‌دهد،

    • افزونه باید همچنین یک ساختار فهرست برای آن مؤلفه تعریف کند که به برنامه اجازه می‌دهد آرایه‌ای را به زمان اجرا ارسال کند تا با داده‌های مربوط به هریک از موجودیت‌های فضایی که xrQuerySpatialComponentDataEXT :: queryCondition را برآورده می‌کنند، پر شود. برخی‌از نمونه‌های چنین ساختارهای فهرستی عبارت‌اند از XrSpatialComponentParentListEXT و XrSpatialComponentBounded2DListEXT . اگر اندازه داده‌های مؤلفه متغیر باشد و برنامه را ملزم کند که از اصطلاح دو-فراخوانی برای پرسمان آن استفاده کند، داده‌های مؤلفه باید یک XrSpatialBufferEXT برای هر داده با اندازه متغیر در ساختار فهرست ارائه دهد و باید XrSpatialBufferTypeEXT را برای هر میان‌گیر مشخص کند. سپس برنامه می‌تواند بااستفاده از توابع تعریف‌شده در اصطلاح دو فراخوانی برای داده‌های مؤلفه، داده‌های میان‌گیر را پرسمان کند. نمونه‌ای از چنین ساختاری XrSpatialMeshDataEXT است که در XrSpatialComponentMesh3DListEXT گنجانده شده است.
    • افزونه می‌تواند ساختارهایی را نیز ارائه دهد که برنامه می‌تواند به XrSpatialComponentDataQueryConditionEXT :: next زنجیر کند تا فیلترهای بیشتری برای پُرسمان مربوط به داده‌های این مؤلفه ارائه دهد.

  • افزونه‌ها می‌توانند ساختارهایی را تعریف کنند که XrSpatialDiscoverySnapshotCreateInfoEXT را گسترش می‌دهند تا فیلترهای بیشتری برای کاوش ارائه دهند. فیلترهای ایجاد عکس آنی نباید بر پیکربندی بافت فضایی تأثیر بگذارند، بلکه باید برای ارائه نکته‌هایی به زمان اجرا درباره اینکه چه نهادها و داده‌هایی باید در عکس آنی گنجانده شوند، همان‌طور که توسط پیکربندی فعلی بافت فضایی (و بنابراین پیکربندی فعلی سرویس‌های زیربنایی) ردیابی می‌شود، استفاده شوند.

  • اگر افزونه‌ای XrSpatialCapabilityEXT جدیدی را تعریف کند،

    • همچنین باید فهرست XrSpatialComponentTypeEXT را که زمان‌های اجرا باید برای آن قابلیت در نهادها ارائه دهند مشخص کند.
    • همچنین باید ساختارهای مشتق‌شده از XrSpatialCapabilityConfigurationBaseHeaderEXT را ارائه دهد که امکان پیکربندی آن قابلیت را فراهم می‌کند.

  • اگر افزونه‌ای XrSpatialCapabilityFeatureEXT جدیدی تعریف کند، باید ساختار پیکربندی متناظری نیز تعریف کند که بتواند به اشاره‌گر بعدی XrSpatialCapabilityConfigurationBaseHeaderEXT زنجیر شود، که برنامه بتواند از آن برای فعال کردن ویژگی هنگام ایجاد XrSpatialContextEXT استفاده کند.

  • افزونه‌ای که XrSpatialCapabilityEXT جدیدی را تعریف می‌کند باید از این الگو برای مشخصات پیروی کند -

    • نمای کلی
    • پشتیبانی زمان اجرا
    • پیکربندی
    • قطعات تضمین‌شده
    • کد نمونه

  • افزونه‌ای که XrSpatialComponentTypeEXT جدیدی را تعریف می‌کند باید از این الگو برای مشخصات پیروی کند -

    • داده‌های مؤلفه
    • ساختار فهرست مؤلفه برای پرسمان داده‌ها
    • پیکربندی

  • When writing an api that provides the application with a XrSpatialBufferIdEXT , it must be accompanied with a XrSpatialBufferTypeEXT to inform the application what the data type of the buffer is and the application can use an appropriate xrGetSpatialBuffer* function to retrieve the actual contents of the buffer.

دستورالعمل‌های طراحی و افزونه برچسب معنایی

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

  • اگر افزونه‌ای برچسب‌های معنایی را برای هر XrSpatialCapabilityEXT تعریف می‌کند، باید این کار را با تعریف یک XrSpatialComponentTypeEXT جدید و همچنین یک شمارش جدید با مجموعه‌ای از برچسب‌ها («مجموعه برچسب معنایی») به‌عنوان داده‌های آن مؤلفه انجام دهد.
  • شمارشی که نشان‌دهنده مجموعه برچسب معنایی است باید مقداری داشته باشد که نشان دهد نهاد در هیچ‌یک از برچسب‌های این مجموعه دسته‌بندی نشده است. نام این شمارنده باید شامل «UNCATEGORIZED» باشد، مثلاً XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT . این مقدار به برنامه‌ها نشان می‌دهد که زمان اجرا این نهاد را تشخیص می‌دهد، اما مجموعه‌های برچسب معنایی دیگری وجود دارد که این نهاد در آن‌ها دسته‌بندی شده است.
  • شمارش این XrSpatialComponentTypeEXT جدید تعریف‌شده در xrEnumerateSpatialCapabilityComponentTypesEXT به این معنی است که زمان اجرا از مجموعه برچسب معنایی (و بنابراین برچسب‌های تعریف‌شده در مجموعه) مربوط به آن نوع مؤلفه پشتیبانی می‌کند.
  • برنامه‌ها تمایل خود را برای کشف نهادهایی که برچسب‌های متعلق به این مجموعه برچسب معنایی را دارند با گنجاندن XrSpatialComponentTypeEXT مربوطه در آرایه enabledComponents :: XrSpatialCapabilityConfigurationBaseHeaderEXT از ساختار پیکربندی برای قابلیتی که نوع مؤلفه برای آن شمارش شده است، بیان می‌کنند.
  • ممکن است یک موجودیت فضایی واحد دارای چندین مؤلفه باشد که هرکدام برچسبی از مجموعه برچسب‌های معنایی خود به آن ارائه می‌دهند. مثال زیر را با چند مجموعه برچسب معنایی فرضی درنظر بگیرید - XrSpatialObjectSemanticLabel ، که ممکن است مقادیری مانند صندلی، مبل، میز و غیره داشته باشد، XrSpatialSofaBrand ، که ممکن است مقادیری مانند IKEA،‏ Wayfair، و غیره داشته باشد، و XrSpatialIkeaSofa ، که ممکن است نام مدل‌های خاص مبل IKEA را داشته باشد. در این سناریو، همان نهاد مبل هر ۳ مؤلفه (برچسب‌های هر ۳ مجموعه برچسب معنایی) را روی خود دارد که هرکدام جزئیات متفاوتی از اطلاعات مربوط به نهاد را ارائه می‌دهند.
  • اگر افزونه‌ای درحال تعریف XrSpatialComponentTypeEXT جدیدی باشد که مجموعه برچسب معنایی جدیدی حاوی چند برچسب علاوه‌بر برچسب UNCATEGORIZED ارائه می‌دهد، افزونه باید تعریف XrSpatialCapabilityFeatureEXT را درنظر بگیرد که به برنامه‌ها اجازه می‌دهد فقط زیرمجموعه‌ای از برچسب‌های تعریف‌شده در مجموعه برچسب معنایی مربوط به آن نوع مؤلفه را فعال کنند. این زیرمجموعه، که در زنجیره بعدی پیکربندی قابلیت ارائه شده است، به‌عنوان راهنمایی برای زمان‌های اجرا عمل می‌کند تا خطوط لوله ردیابی خود را بهینه‌سازی کنند و فقط زیرمجموعه ارائه‌شده را ردیابی کنند. نمونه‌ای از چنین ساختار ویژگی‌ای در زیر ارائه شده است.
  • افزونه‌ها نباید به شمارش مجموعه برچسب‌های معنایی موجود برچسب اضافه کنند. آن‌ها باید به‌جای آن، شمارش جدیدی تعریف کنند که حاوی شمارنده‌های معادل با معناشناسی یکسان و با مقادیر برابر با مقادیر مجموعه دیگر، علاوه‌بر شمارنده‌های جدید اضافه‌شده باشد. مشخصات مجموعه برچسب معنایی جدید تعریف‌شده باید نگاشت بین مجموعه برچسب قدیمی و جدید را نیز ایجاد کند. نمونه زیر را ببینید.
نمونه تعریف ویژگی فضایی برای زیرمجموعه برچسب معنایی
// 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;
نمونه افزونه برچسب معنایی فضایی
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;

مثال بالا را درنظر بگیرید که در آن یک افزونه شمارش XrSpatialExamplePlaneSemanticLabelExtensionEXT را تعریف می‌کند تا XrSpatialPlaneSemanticLabelEXT موجود را با مقادیری برای نمایش درها و پنجره‌ها گسترش دهد. مشخصات شمارش جدید باید شامل نوشتار برای فرم زیر باشد -

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

ماکروهای جدید

انواع پایه جدید

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

انواع شیء جدید

فرمان‌های جدید

سازه‌های جدید

Enums جدید

ثابت‌های شمارشی جدید

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • درحال گسترش دادن XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • درحال گسترش دادن 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

  • درحال گسترش دادن 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

مشکلات

  • آیا یک نهاد همیشه فقط از یک قابلیت مشتق می‌شود؟

    • حل و فصل شده
    • پاسخ: نه. این موضوع کاملاً به زمان اجرا براساس قابلیت‌های ردیابی خودش و نحوه نمایش نهاد شناسایی‌شده بستگی دارد. این مشخصات هیچ نمایش خاصی از موجودیت فضایی را تجویز نمی‌کند، به‌جز مؤلفه‌های تضمین‌شده از یک قابلیت معین برای تعیین حداقل انتظار. زمان اجرا ممکن است بتواند نهادهای شناسایی‌شده توسط قابلیت‌های جداگانه را ادغام کند و آن‌ها را به‌عنوان یک نهاد واحد با مؤلفه‌های تضمین‌شده همه قابلیت‌هایی که به شناسایی آن کمک کرده‌اند نشان دهد. برای مثال، میزها را می‌توان هم با قابلیت ردیابی صفحه و هم با قابلیت ردیابی شیء شناسایی کرد، به‌طوری‌که ردیابی صفحه مؤلفه XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT را در موجودیت ارائه می‌دهد و ردیابی شیء مؤلفه XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT را ارائه می‌دهد. یک زمان اجرای خاص ممکن است جدول را به‌عنوان ۲ موجودیت جداگانه ارائه دهد که هرکدام مجموعه مؤلفه‌های تضمین‌شده خود را دارند، درحالی‌که برخی زمان‌های اجرای خاص ممکن است فقط ۱ موجودیت را برای نمایش جدول ارائه دهند و هر دو XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT و XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT را در همان موجودیت داشته باشند. نکته مهمی که باید در اینجا به آن توجه کرد این است که یک نهاد فضایی معین می‌تواند حداکثر یک مؤلفه از هر نوع مؤلفه معین داشته باشد. بنابراین، اگر داده‌های مؤلفه تولیدشده توسط قابلیت‌های مختلف برای نهاد خاصی تداخل داشته باشد، زمان اجرا باید آن‌ها را به‌عنوان ۲ نهاد جداگانه نشان دهد.

سابقه نسخه

  • بازبینی ۱، ۲۰۲۴/۰۴/۱۲ (نیهاو جین، Google)

    • شرح اولیه افزونه