XR_EXT_spatial_entity

Name String

XR_EXT_spatial_entity

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

741

المراجعة

1

حالة التصديق

تمت المصادقة عليه

الاعتماد على الإضافات والإصدارات

XR_EXT_future

المساهمون

"نيهاف جاين"، Google
"جاريد فايندر"، Google
"ناتالي فلوري"، Meta
"يويتشي تاغوتشي"، Meta
"رون بيسمز"، Meta
"يين لي"، Microsoft
"كارثيك كادابان"، Magic Leap
"جيمي ألامبارامبيل"، ByteDance
"تشيبينغ ليو"، ByteDance
"جون يان"، ByteDance

نظرة عامة

تقدّم هذه الإضافة المفاهيم والأسس اللازمة لفهم المشهد والاستدلال المكاني في OpenXR. يؤدي ذلك إلى توحيد العديد من مجالات الوظائف ذات الصلة ولكنها متميزة، والتي يتم تعدادها وتكوينها والتفاعل معها بطريقة موحدة على نطاق واسع على النحو المحدد في هذه الإضافة. بما أنّ هذه الإضافة تفتقر إلى تعريفات ملموسة لأي من هذه المجالات الوظيفية، يميل نص المواصفات الرسمية إلى أن يكون مجرّدًا إلى حدّ ما. تشير الأمثلة المضمّنة في نص مواصفات هذه الإضافة في بعض الأحيان إلى وظائف محدّدة في إضافة ذات صلة قادمة أو افتراضية لغرض التوضيح، بدون تقييد أو تحديد هذه الوظائف الإضافية بطبيعتها.

في ما يلي الأجزاء العامة لهذه الإضافة:

• الكيانات المكانية : تتمحور الوظيفة حول الكيانات ، والتي توفر وظائف قليلة جدًا بمفردها.
• المكوّنات المكانية : تحتوي هذه الكيانات على مكوّنات مرتبطة بها توفّر البيانات والسلوكيات.
• أنواع المكوّنات المكانية : كل مكوّن مكاني هو من نوع مكوّن معيّن، وأي كيان معيّن يحتوي على مكوّن واحد على الأكثر من أي نوع مكوّن معيّن.
• السياق المكاني : يحدث كل تفاعل للكيان المكاني في سياق بعد مرحلة الإعداد والضبط.
• الإمكانات المكانية : يتم توفير معالجة الكيانات المكانية على نطاق واسع من خلال الإمكانات . والإمكانية هي وحدة من الوظائف، على سبيل المثال (بدون قيد) نقاط الارتساء المحدّدة في التطبيق أو رصد السطح أو تتبُّع الصور. يتم عادةً تحديد كل إمكانية في إضافة منفصلة (يتم تفعيلها عند إنشاء مثيل كالمعتاد) ويتم تفعيلها لسياق معيّن في وقت الإنشاء.
• ترتبط كل إمكانية بمجموعة من أنواع المكوّنات التي تتوفّر لها مكوّنات في كل عنصر تعرضه هذه الإمكانية . تحدّد الإضافة التي تعرّف إمكانية معيّنة أنواع المكوّنات الإلزامية لهذه الإمكانية ("مضمونة")، في حين أنّ الإضافة نفسها أو غيرها قد تحدّد أنواع المكوّنات الاختيارية التي توفّرها بعض عمليات التنفيذ المحتملة. يمكن لأي عدد من الإمكانات أن يوفّر للكيانات مكوّنات من نوع مكوّن معيّن، والتي يمكن استخدامها بشكل موحّد بغض النظر عن الإمكانية التي أنتجتها.
• ميزات الإمكانات المكانية : تتطلّب بعض الإمكانات ضبط الإعدادات، وبالتالي يتم تحديدها من خلال ميزات الإمكانات .

توفّر هذه الإضافة آلية لتعداد المكوّنات التي توفّرها كل إمكانية متوافقة مع النظام الحالي، سواء كانت إلزامية أو أي مكوّنات اختيارية.

بما أنّ بعض عمليات التنفيذ قد تتطلّب درجات مختلفة من تحديد المَعلمات للإمكانات، توفّر هذه الإضافة آلية لتعداد ميزات الإمكانات المتوافقة المرتبطة بإمكانية معيّنة في النظام الحالي.

تحدّد هذه الإضافة أيضًا العديد من المكوّنات الشائعة التي من المتوقّع استخدامها في مجموعة واسعة من الإمكانات .

كيان مكاني

الكيانات المكانية هي كيانات موجودة في مساحة معيّنة، وتحتوي على بيانات مختلفة مرتبطة بها منظَّمة في مكوّنات. قد تكون أيًا مما يلي:

• مادية (مثل الأسطح المستوية كالجدران والأرضيات، والأجسام مثل الكراسي وخزائن الكتب وما إلى ذلك)
• افتراضية (مثل المحتوى الذي يضعه ويشاركه تطبيق أو مستخدم آخر)
• محدَّدة من خلال التطبيق (على سبيل المثال، يضع التطبيق علامة على منطقة باعتبارها "الشاشات الكبيرة" أو "المطبخ"، أو يضع علامة على نقطة باعتبارها مكان وضع التلفزيون وما إلى ذلك)

إنّ العناصر التي يتم عرضها من خلال نظام الإجراءات، مثل وحدات التحكّم أو تتبُّع حركة العين، ليست مخصّصة لتكون كيانات مكانية.

يتم تصميم الكيانات المكانية في OpenXR على شكل نظام Entity-Component . يحتوي كل كيان مكاني على مجموعة من المكوّنات، ويوفّر كل مكوّن مجموعة فريدة من البيانات والسلوكيات لهذا الكيان.

يتم تمثيل الكيانات المكانية إما من خلال عنصر XrSpatialEntityIdEXT أو مؤشر XrSpatialEntityEXT، ويتم توفير تفاصيلها في قسم تمثيلات الكيانات المكانية.

أنواع المكوّنات المكانية

يحتوي الكيان المكاني على مكوّن واحد أو أكثر يوفّر بيانات أو سلوكيات لهذا الكيان. يُرجى الاطّلاع على المكوّنات الشائعة للتعرّف على بعض المكوّنات الشائعة التي تحدّدها هذه الإضافة.

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

تتبُّع الشعاع في ذاكرة التخزين المؤقت للعمق (تمت إضافته من خلال إضافة XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

إمكانية تتبُّع غرفة (تمت إضافتها من خلال إضافة "XR_ANDROIDSYS_spatial_room_tracking")

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

إمكانية تتبُّع حدود الغرفة (تمت إضافتها من خلال إضافة "XR_ANDROIDSYS_spatial_room_tracking")

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

تتبُّع التعليقات التوضيحية (تمت إضافته من خلال إضافة "XR_ANDROID_spatial_annotation_tracking")

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

هندسة منظر الشارع (تمت إضافتها من خلال إضافة XR_ANDROIDX2_geospatial_streetscape)

يتم تعريف الدالة xrEnumerateSpatialCapabilitiesEXT على النحو التالي:

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

أوصاف المَعلمات

• ‫instance هو اسم حساب لـ XrInstance .
• ‫systemId هو XrSystemId الذي سيتم تعداد إمكاناته المكانية.
• ‫capabilityCapacityInput هي سعة مصفوفة capabilities، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫capabilityCountOutput هو عدد الإمكانات أو السعة المطلوبة في حال عدم كفاية capabilityCapacityInput.
• ‫capabilities هي مصفوفة من XrSpatialCapabilityEXT . يمكن أن تكون القيمة NULL إذا كانت قيمة capabilityCapacityInput هي 0.
• يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم capabilities المطلوب.

يمكن للتطبيق تعداد قائمة الإمكانات المكانية التي يتيحها XrSystemId معيّن باستخدام xrEnumerateSpatialCapabilitiesEXT .

يجب ألا يعدد وقت التشغيل الإمكانات المكانية التي لم يتم تفعيل إضافتها لـ instance .

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استدعاء xrEnumerateSpatialCapabilitiesEXT
• يجب أن يكون instance مقبض XrInstance صالحًا
• يجب أن يكون capabilityCountOutput مؤشرًا إلى قيمة uint32_t
• إذا لم تكن قيمة capabilityCapacityInput هي 0، capabilities يجب أن تكون مؤشرًا إلى مصفوفة من قيم capabilityCapacityInput XrSpatialCapabilityEXT

رموز الإرجاع

Success

• 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 له.

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT إذا لم يتم تعداد capability من خلال xrEnumerateSpatialCapabilitiesEXT .

يجب ألا يعدد وقت التشغيل أنواع المكوّنات المكانية التي لم يتم تفعيل إضافتها لـ instance .

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استدعاء xrEnumerateSpatialCapabilityComponentTypesEXT
• يجب أن يكون instance مقبض XrInstance صالحًا
• capability يجب أن تكون قيمة XrSpatialCapabilityEXT صالحة
• capabilityComponents يجب أن يكون مؤشرًا إلى بنية XrSpatialCapabilityComponentTypesEXT

رموز الإرجاع

Success

• XR_SUCCESS

تعذّر الإجراء

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

يتم تعريف بنية XrSpatialCapabilityComponentTypesEXT على النحو التالي:

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

أوصاف الأعضاء

• ‫type هو XrStructureType لهذه البنية.
• ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى. لا يتم تحديد مثل هذه البُنى في OpenXR الأساسية أو هذه الإضافة.
• ‫componentTypeCapacityInput هي سعة المصفوفة، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫componentTypeCountOutput هو عدد أنواع المكوّنات أو السعة المطلوبة في حال عدم كفاية componentTypeCapacityInput.
• ‫componentTypes هي مصفوفة من XrSpatialComponentTypeEXT . يمكن أن تكون القيمة NULL إذا كانت قيمة componentTypeCapacityInput هي 0.
• يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم componentTypes المطلوب.

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استخدام XrSpatialCapabilityComponentTypesEXT
• يجب أن يكون type XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية
• إذا لم تكن قيمة componentTypeCapacityInput هي 0، يجب أن تكون قيمة componentTypes مؤشرًا إلى مصفوفة من قيم componentTypeCapacityInput XrSpatialComponentTypeEXT

ميزات الإمكانات المكانية

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 هي سعة المصفوفة، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫capabilityFeatureCountOutput هو عدد الميزات أو السعة المطلوبة في حال عدم كفاية capabilityFeatureCapacityInput.
• ‫capabilityFeatures هي مصفوفة من XrSpatialCapabilityFeatureEXT . يمكن أن تكون القيمة NULL إذا كانت قيمة capabilityFeatureCapacityInput هي 0.
• يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم capabilityFeatures المطلوب.

يكتشف التطبيق الميزات التي يتيحها نظام معيّن لـ XrSpatialCapabilityEXT باستخدام xrEnumerateSpatialCapabilityFeaturesEXT .

بالنسبة إلى الإمكانات التي تتضمّن ميزات معروضة، يختار التطبيق الميزة أو الميزات التي يريد تفعيلها ويوفّر بنية الإعدادات المقابلة في السلسلة التالية من بنيات إعدادات الإمكانات في 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

رموز الإرجاع

Success

• 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 من خلال:

• توفير البُنى المشتقة من XrSpatialCapabilityConfigurationBaseHeaderEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs لتفعيل الإمكانات والمكوّنات الخاصة بها.
• ضبط الإمكانات نفسها باستخدام هياكل الضبط المقابلة لـ XrSpatialCapabilityFeatureEXT

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT إذا كانت قيمة XrSpatialContextCreateInfoEXT ::capabilityConfigCount هي 0. يجب أن يتضمّن مؤشر السياق المكاني إمكانية واحدة على الأقل.

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT إذا لم يتم تعداد أي إمكانية في مصفوفة XrSpatialContextCreateInfoEXT :: capabilityConfigs من خلال xrEnumerateSpatialCapabilitiesEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT إذا كانت قيمة أيّ من XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount في XrSpatialContextCreateInfoEXT :: capabilityConfigs هي 0. لا تكتمل إعدادات الميزة بدون قائمة بأنواع المكوّنات التي يجب تفعيلها لهذه الميزة.

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT إذا لم يتم تعداد أي نوع مكوّن مدرَج في XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents لـ XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability في xrEnumerateSpatialCapabilityComponentTypesEXT .

إذا كانت أي من البُنى في السلسلة التالية من XrSpatialContextCreateInfoEXT :: capabilityConfigs تتوافق مع XrSpatialCapabilityFeatureEXT غير مُدرَجة لهذه الإمكانية في xrEnumerateSpatialCapabilityFeaturesEXT، يجب أن يتجاهل وقت التشغيل بنية XrSpatialCapabilityFeatureEXT هذه.

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT إذا كان XrSpatialContextCreateInfoEXT :: capabilityConfigs يحتوي على بُنى متعددة لها نفس XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability .

لضمان الاستخدام الأمثل لموارد النظام، قد تستخدم بيئة التشغيل الإعدادات المقدَّمة في مصفوفة XrSpatialContextCreateInfoEXT للاستعداد للطلبات المكانية الواردة. على سبيل المثال، قد لا تبدأ بيئة التشغيل التي تتيح إمكانية تتبُّع السطح المستوي في مسار تتبُّع السطح المستوي إلا إذا أنشأ التطبيق مؤشر سياق مكاني يتضمّن إمكانية تتبُّع السطح المستوي. إذا كانت الإمكانات التي تم ضبطها تستغرق وقتًا طويلاً للإحماء، قد تؤدي طلبات xrCreateSpatialDiscoverySnapshotAsyncEXT إلى لقطة فارغة. يمكن للتطبيق انتظار XrEventDataSpatialDiscoveryRecommendedEXT قبل استخدام xrCreateSpatialDiscoverySnapshotAsyncEXT للتأكّد من أنّ خدمات التتبُّع الأساسية قد تم إعدادها.

إذا كان وقت التشغيل يفرض نظام أذونات للتحكّم في وصول التطبيق إلى الإمكانات المكانية التي يتم ضبطها لـ XrSpatialContextEXT، يجب أن يعرض وقت التشغيل XR_ERROR_PERMISSION_INSUFFICIENT إذا لم يتم منح هذه الأذونات لهذا التطبيق.

تبدأ هذه الدالة عملية غير متزامنة وتنشئ XrFutureEXT مقابلة، يمكن استخدامها مع xrPollFutureEXT والدوال ذات الصلة. تشير القيمة المعروضة لهذه الدالة فقط إلى ما إذا كانت المَعلمات مقبولة لجدولة العملية غير المتزامنة. دالة الإكمال المقابلة هي xrCreateSpatialContextCompleteEXT، ويمكن استخدامها عندما تكون القيمة المستقبلية من هذه الدالة في الحالة READY، مع تعبئة المخرجات بواسطة هذه الدالة في بنية الإكمال XrCreateSpatialContextCompletionEXT .

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل طلب xrCreateSpatialContextAsyncEXT
• يجب أن يكون session اسم معرِّف XrSession صالحًا
• createInfo يجب أن يكون مؤشرًا إلى بنية XrSpatialContextCreateInfoEXT صالحة
• يجب أن يكون future مؤشرًا إلى قيمة XrFutureEXT

رموز الإرجاع

Success

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

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrSpatialContextCreateInfoEXT
• يجب أن يكون type XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية . يُرجى الاطّلاع أيضًا على: XrSpatialContextPersistenceConfigEXT
• يجب أن يكون capabilityConfigs مؤشرًا إلى مصفوفة من capabilityConfigCount بنية صالحة مستندة إلى XrSpatialCapabilityConfigurationBaseHeaderEXT. يُرجى الاطّلاع أيضًا على: XrSpatialCapabilityConfigurationAnchorEXT وXrSpatialCapabilityConfigurationAnnotationTrackingANDROID وXrSpatialCapabilityConfigurationAprilTagEXT وXrSpatialCapabilityConfigurationArucoMarkerEXT وXrSpatialCapabilityConfigurationDepthRaycastANDROID وXrSpatialCapabilityConfigurationImageTrackingEXT وXrSpatialCapabilityConfigurationMeshTrackingEXT وXrSpatialCapabilityConfigurationMicroQrCodeEXT وXrSpatialCapabilityConfigurationObjectTrackingANDROID وXrSpatialCapabilityConfigurationObjectTrackingEXT وXrSpatialCapabilityConfigurationPlaneTrackingEXT وXrSpatialCapabilityConfigurationQrCodeEXT وXrSpatialCapabilityConfigurationRoomBoundaryTrackingANDROIDSYS وXrSpatialCapabilityConfigurationRoomTrackingANDROIDSYS وXrSpatialCapabilityConfigurationStreetscapeGeometryANDROIDX2
• يجب أن تكون المَعلمة capabilityConfigCount أكبر من 0

يتم تحديد بنية 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 .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT إذا لم يتم تعداد capability من خلال xrEnumerateSpatialCapabilitiesEXT . يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT إذا لم يتم تعداد أي نوع مكوّن مدرَج في enabledComponents لـ capability في xrEnumerateSpatialCapabilityComponentTypesEXT .

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrSpatialCapabilityConfigurationBaseHeaderEXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية
• capability يجب أن تكون قيمة XrSpatialCapabilityEXT صالحة
• enabledComponents يجب أن يكون مؤشرًا إلى مصفوفة من قيم enabledComponentCount صالحة من النوع XrSpatialComponentTypeEXT
• يجب أن تكون المَعلمة enabledComponentCount أكبر من 0

يتم تعريف الدالة xrCreateSpatialContextCompleteEXT على النحو التالي:

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

أوصاف المَعلمات

• ‫session هي XrSession التي تم تمريرها سابقًا إلى xrCreateSpatialContextAsyncEXT :: session .
• ‫future هو XrFutureEXT الذي تم تلقّيه من xrCreateSpatialContextAsyncEXT .
• ‫completion هو مؤشر إلى XrCreateSpatialContextCompletionEXT .

تُكمل الدالة xrCreateSpatialContextCompleteEXT العملية غير المتزامنة التي بدأتها الدالة xrCreateSpatialContextAsyncEXT . يجب أن يعرض وقت التشغيل XR_ERROR_FUTURE_PENDING_EXT إذا لم يكن future في حالة الاستعداد. يجب أن يعرض وقت التشغيل القيمة XR_ERROR_FUTURE_INVALID_EXT إذا سبق أن تم إكمال future أو إلغاؤه.

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استدعاء xrCreateSpatialContextCompleteEXT
• يجب أن يكون session اسم معرِّف XrSession صالحًا
• completion يجب أن يكون مؤشرًا إلى بنية XrCreateSpatialContextCompletionEXT

رموز الإرجاع

Success

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

Success

• 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، أيهما يحدث أولاً.

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrCreateSpatialContextCompletionEXT
• يجب أن يكون type XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية
• يجب أن تكون قيمة futureResult صالحة لـ XrResult
• إذا لم تكن قيمة spatialContext هي XR_NULL_HANDLE، spatialContext يجب أن تكون قيمة صالحة لـ XrSpatialContextEXT

تدمير السياق المكاني

يتم تعريف الدالة xrDestroySpatialContextEXT على النحو التالي:

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

أوصاف المَعلمات

• ‫spatialContext هو XrSpatialContextEXT تم إنشاؤه سابقًا بواسطة xrCreateSpatialContextAsyncEXT .

يمكن للتطبيق استدعاء الدالة xrDestroySpatialContextEXT لإلغاء المقبض spatialContext والموارد الأساسية عند الانتهاء من مهام اكتشاف الكيانات المكانية وتحديثها. إذا لم يكن هناك XrSpatialContextEXT صالح آخر تم إنشاؤه باستخدام الإمكانات المكانية نفسها مثل spatialContext، فإنّ هذا الاستدعاء يُعدّ اقتراحًا لبيئة التشغيل لإيقاف خدمات التتبُّع المطلوبة لهذه الإمكانات من أجل توفير موارد النظام.

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استدعاء xrDestroySpatialContextEXT
• يجب أن يكون spatialContext مؤشرًا صالحًا لـ XrSpatialContextEXT

أمان Thread

• يجب مزامنة الوصول إلى spatialContext وأي معرّفات فرعية خارجيًا

رموز الإرجاع

Success

• 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 غير صالح. وقد يتم تمريرها إلى دوال واجهة برمجة التطبيقات وإرجاعها منها فقط عندما يكون ذلك مسموحًا به تحديدًا.

مقبض الكيان المكاني

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

يمثّل المقبض XrSpatialEntityEXT كيانًا مكانيًا. يمكن للتطبيق إنشاء مثل هذا الاسم المعرِّف للتعبير عن اهتمامه بكيان معيّن في وقت التشغيل.

إنشاء مقبض كيان مكاني من المعرّف

يتم تعريف الدالة xrCreateSpatialEntityFromIdEXT على النحو التالي:

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

أوصاف المَعلمات

• ‫spatialContext هو XrSpatialContextEXT تم إنشاؤه سابقًا باستخدام xrCreateSpatialContextAsyncEXT .
• ‫createInfo هو مؤشر إلى بنية XrSpatialEntityFromIdCreateInfoEXT.
• ‫spatialEntity هو مؤشر XrSpatialEntityEXT الذي تم عرضه.

يمكن للتطبيق استخدام xrCreateSpatialEntityFromIdEXT لإنشاء مؤشر XrSpatialEntityEXT يشير إلى عنصر موجود في بيئة المستخدم.

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT إذا لم يكن XrSpatialEntityFromIdCreateInfoEXT :: entityId معرّفًا صالحًا لـ spatialContext .

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استدعاء xrCreateSpatialEntityFromIdEXT
• يجب أن يكون spatialContext مؤشرًا صالحًا لـ XrSpatialContextEXT
• createInfo يجب أن يكون مؤشرًا إلى بنية XrSpatialEntityFromIdCreateInfoEXT صالحة
• يجب أن يكون spatialEntity مؤشرًا إلى اسم معرِّف XrSpatialEntityEXT

رموز الإرجاع

Success

• 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 الكيان الذي يريد التطبيق إنشاء اسم معرِّف له.

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrSpatialEntityFromIdCreateInfoEXT
• يجب أن يكون type XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية

إتلاف مؤشر الكيان المكاني

يتم تعريف الدالة xrDestroySpatialEntityEXT على النحو التالي:

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

أوصاف المَعلمات

• ‫spatialEntity هو اسم معرِّف لـ XrSpatialEntityEXT تم إنشاؤه سابقًا بواسطة دالة مثل xrCreateSpatialEntityFromIdEXT .

يمكن للتطبيق استخدام xrDestroySpatialEntityEXT لإلغاء المقبض spatialEntity عندما لا يعود مهتمًا بالكيان الذي يشير إليه هذا المقبض.

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استدعاء xrDestroySpatialEntityEXT
• يجب أن يكون spatialEntity مؤشرًا صالحًا لـ XrSpatialEntityEXT

أمان Thread

• يجب مزامنة الوصول إلى spatialEntity وأي معرّفات فرعية خارجيًا

رموز الإرجاع

Success

• 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);

أوصاف المَعلمات

• ‫spatialContext هو XrSpatialContextEXT تم إنشاؤه سابقًا باستخدام xrCreateSpatialContextAsyncEXT .
• ‫createInfo هو مؤشر إلى XrSpatialDiscoverySnapshotCreateInfoEXT .
• ‫future هو مؤشر إلى XrFutureEXT .

يمكن للتطبيق اكتشاف الكيانات المكانية من خلال إنشاء لقطة اكتشاف باستخدام xrCreateSpatialDiscoverySnapshotAsyncEXT .

تبدأ هذه الدالة عملية غير متزامنة وتنشئ XrFutureEXT مقابلة، يمكن استخدامها مع xrPollFutureEXT والدوال ذات الصلة. تشير القيمة المعروضة لهذه الدالة فقط إلى ما إذا كانت المَعلمات مقبولة لجدولة العملية غير المتزامنة. دالة الإكمال المقابلة هي xrCreateSpatialDiscoverySnapshotCompleteEXT، ويمكن استخدامها عندما تكون الحالة المستقبلية من هذه الدالة هي READY، مع ملء المخرجات بواسطة هذه الدالة في بنية الإكمال XrCreateSpatialDiscoverySnapshotCompletionEXT .

يمكن للتطبيق إرسال طلبات متعددة لإنشاء لقطات من بيانات الاكتشاف بدون الحاجة إلى انتظار اكتمال الطلب السابق. قد تعالج بيئة التشغيل عملية إنشاء اللقطة وتكملها بأي ترتيب. قد يؤخّر وقت التشغيل إكمال إنشاء لقطة الاكتشاف لتقييد التطبيق إذا كان بحاجة إلى تقليل استخدام موارد النظام بسبب الطاقة أو الحرارة أو سياسات أخرى للجهاز.

يمكن للتطبيق استخدام XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes لفلترة قائمة الكيانات والمكوّنات التي يجب أن يتضمّنها وقت التشغيل في اللقطة. إذا قدّم التطبيق قائمة صالحة بأنواع المكوّنات المكانية في XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes، يجب أن يتضمّن وقت التشغيل فقط الكيانات المكانية في اللقطة التي تحتوي على مكوّن واحد على الأقل من المكوّنات المقدَّمة في XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . بالإضافة إلى ذلك، يجب أن يتضمّن وقت التشغيل بيانات المكوّنات المضمّنة في اللقطة فقط.

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT إذا لم يتم تفعيل أي من XrSpatialComponentTypeEXT في XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes للإمكانات المكانية التي تم تمريرها إلى XrSpatialContextCreateInfoEXT :: capabilityConfigs عند إنشاء spatialContext .

إذا لم يوفّر التطبيق قائمة بأنواع المكوّنات المكانية في 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_EXT_spatial_entity قبل استدعاء xrCreateSpatialDiscoverySnapshotAsyncEXT
• يجب أن يكون spatialContext مؤشرًا صالحًا لـ XrSpatialContextEXT
• createInfo يجب أن يكون مؤشرًا إلى بنية XrSpatialDiscoverySnapshotCreateInfoEXT صالحة
• يجب أن يكون future مؤشرًا إلى قيمة XrFutureEXT

رموز الإرجاع

Success

• 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 عند اكتشاف الكيانات المكانية.

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrSpatialDiscoverySnapshotCreateInfoEXT
• يجب أن يكون type XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية . يُرجى الاطّلاع أيضًا على: XrSpatialBoundsBoxfANDROID وXrSpatialBoundsFrustumfANDROID وXrSpatialBoundsSpherefANDROID وXrSpatialDiscoveryPersistenceContextFilterANDROIDX1 وXrSpatialDiscoveryPersistenceUuidFilterEXT وXrSpatialDiscoveryRoomBoundaryFilterANDROIDSYS وXrSpatialDiscoveryUniqueEntitiesFilterANDROID وXrSpatialFilterTrackingStateEXT وXrSpatialRaycastInfoANDROID
• إذا لم تكن قيمة componentTypeCount هي 0، يجب أن تكون قيمة componentTypes مؤشرًا إلى مصفوفة من قيم componentTypeCount صالحة لـ XrSpatialComponentTypeEXT

يتم تعريف الدالة xrCreateSpatialDiscoverySnapshotCompleteEXT على النحو التالي:

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

أوصاف المَعلمات

• ‫spatialContext هو XrSpatialContextEXT الذي تم تمريره سابقًا إلى xrCreateSpatialDiscoverySnapshotAsyncEXT :: spatialContext .
• ‫createSnapshotCompletionInfo هو مؤشر إلى XrCreateSpatialDiscoverySnapshotCompletionInfoEXT الذي يوفّر معلومات حول اكتمال طلب إنشاء لقطة الاكتشاف.
• completion هو مؤشر إلى XrCreateSpatialDiscoverySnapshotCompletionEXT .

تُكمل الدالة xrCreateSpatialDiscoverySnapshotCompleteEXT العملية غير المتزامنة التي بدأتها الدالة xrCreateSpatialDiscoverySnapshotAsyncEXT . يجب أن يعرض وقت التشغيل XR_ERROR_FUTURE_PENDING_EXT إذا لم تكن السمة XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future في حالة جاهزية. يجب أن تعرض بيئة التشغيل القيمة XR_ERROR_FUTURE_INVALID_EXT إذا سبق أن تم إكمال أو إلغاء XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future.

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استدعاء xrCreateSpatialDiscoverySnapshotCompleteEXT
• يجب أن يكون spatialContext مؤشرًا صالحًا لـ XrSpatialContextEXT
• يجب أن يكون createSnapshotCompletionInfo مؤشرًا إلى بنية XrCreateSpatialDiscoverySnapshotCompletionInfoEXT صالحة
• يجب أن يكون completion مؤشرًا إلى بنية XrCreateSpatialDiscoverySnapshotCompletionEXT

رموز الإرجاع

Success

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

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrCreateSpatialDiscoverySnapshotCompletionInfoEXT
• يجب أن يكون type XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية
• يجب أن يكون baseSpace اسم معرِّف صالحًا على XrSpace

يتم تعريف بنية XrCreateSpatialDiscoverySnapshotCompletionEXT على النحو التالي:

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

أوصاف الأعضاء

• ‫type هو XrStructureType لهذه البنية.
• ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
• ‫futureResult هي XrResult لعملية إنشاء لقطة من ميزة "اكتشاف الأماكن".
• ‫snapshot هو XrSpatialSnapshotEXT يمكن استخدامه لطلب بيانات المكوّنات للكيانات المكانية التي تم اكتشافها.

رموز الإرجاع المستقبلية

قيم futureResult:

Success

• 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_EXT_spatial_entity قبل استخدام XrCreateSpatialDiscoverySnapshotCompletionEXT
• يجب أن يكون type XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية
• يجب أن تكون قيمة futureResult صالحة لـ XrResult
• إذا لم تكن قيمة snapshot هي XR_NULL_HANDLE، يجب أن تكون قيمة snapshot صالحة لـ XrSpatialSnapshotEXT

حدث اقتراح 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 .

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrEventDataSpatialDiscoveryRecommendedEXT
• يجب أن يكون type XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية

بيانات مكوّن طلب البحث

يتم تعريف الدالة xrQuerySpatialComponentDataEXT على النحو التالي:

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

أوصاف المَعلمات

• ‫snapshot هو XrSpatialSnapshotEXT تم توفيره سابقًا من خلال xrCreateSpatialDiscoverySnapshotCompleteEXT أو xrCreateSpatialUpdateSnapshotEXT .
• ‫queryCondition هو مؤشر إلى بنية XrSpatialComponentDataQueryConditionEXT.
• ‫queryResult هو مؤشر إلى بنية XrSpatialComponentDataQueryResultEXT.

يمكن للتطبيق استخدام 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 هي 0، يجب أن يملأ وقت التشغيل queryResult بجميع الكيانات (وحالات تتبُّعها) الموجودة في اللقطة. في حال إضافة شروط طلب بحث أخرى إلى XrSpatialComponentDataQueryConditionEXT :: next، يجب أن يتعامل معها وقت التشغيل على أنّها "AND" مع توفّر أنواع المكوّنات، أي أنّ وقت التشغيل يجب أن يملأ XrSpatialComponentDataQueryResultEXT ::entityIds بالكيانات التي تستوفي جميع الشروط المقدَّمة فقط. يجب أن يملأ وقت التشغيل بيانات المكوّن في هياكل القائمة بالترتيب نفسه للكيانات في XrSpatialComponentDataQueryResultEXT :: entityIds، أي أنّ بيانات المكوّن في فهرس معيّن في مصفوفة بنية القائمة يجب أن تتوافق مع الكيان في الفهرس نفسه.

إذا لم تكن حالة التتبُّع لكيان معيّن هي XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT، يجب ألا يغيّر وقت التشغيل البيانات في الفهرس المقابل لهذا الكيان في المصفوفة المضمّنة في هياكل القائمة المرفقة بـ XrSpatialComponentDataQueryResultEXT .

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل طلب xrQuerySpatialComponentDataEXT
• يجب أن يكون snapshot اسمًا معرِّفًا صالحًا لـ XrSpatialSnapshotEXT
• queryCondition يجب أن يكون مؤشرًا إلى بنية XrSpatialComponentDataQueryConditionEXT صالحة
• queryResult يجب أن يكون مؤشرًا إلى بنية XrSpatialComponentDataQueryResultEXT

رموز الإرجاع

Success

• 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 يحتوي على 5 كيانات، حيث:

• يتضمّن الكيانان 1 و2 المكوّنَين XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT وXR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
• يتضمّن الكيانان 3 و4 المكوّنَين XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT وXR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
• يحتوي الكيان 5 على المكوّنَين 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

لا

لا

لا

لا

نعم

نعم

نعم

نعم

لا

لا النص ليس بتنسيق SVG، لذا لا يمكن عرضه

الشكل 20: مثال على عرض موجز

سيؤدي استخدام xrQuerySpatialComponentDataEXT في اللقطة أعلاه مع إدراج XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT في شرط طلب البحث إلى عرض الكيانات رقم 1 و2 و5 للتطبيق، ويمكن للتطبيق إرفاق مصفوفة من XrSpatialBounded2DDataEXT كجزء من بنية XrSpatialComponentBounded2DListEXT إلى السلسلة التالية من XrSpatialComponentDataQueryResultEXT للحصول على بيانات bounded2D.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

5

5

Bounded2D

Bounded2D

بيانات entityId #1

بيانات الكيان...

بيانات entityId رقم 2

بيانات الكيان...

بيانات entityId #5

بيانات الكيان...

entityIds

entityIds

التالي

التالي

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

bounds

bounds

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou... النص ليس بتنسيق SVG، لذا لا يمكن عرضه

الشكل 21: مثال على نتيجة طلب البحث

سيؤدي استخدام xrQuerySpatialComponentDataEXT في اللقطة أعلاه مع المكوّنَين XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT وXR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT المدرجَين في شرط طلب البحث إلى عرض الكيانَين رقم 3 و4 للتطبيق، ويمكن للتطبيق إرفاق مصفوفات من XrBoxf وXrSpatialMeshDataEXT كجزء من البنيتَين XrSpatialComponentBounded3DListEXT وXrSpatialComponentMesh3DListEXT على التوالي إلى السلسلة التالية من XrSpatialComponentDataQueryResultEXT للحصول على بيانات المكوّن.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

بيانات entityId رقم 3

بيانات الكيان...

بيانات entityId #4

بيانات الكيان...

Mesh3D

Mesh3D

بيانات entityId رقم 3

بيانات الكيان...

بيانات entityId #4

بيانات الكيان...

entityIds

entityIds

التالي

التالي

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

bounds

bounds

التالي

التالي

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

شبكات

meshes Text is not SVG - cannot display

الشكل 22: مثال على نتيجة طلب البحث

يتم تحديد بنية 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 للحصول على البيانات من اللقطة.

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استخدام XrSpatialComponentDataQueryConditionEXT
• يجب أن يكون type XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية . يُرجى الاطّلاع أيضًا على: XrSpatialDiscoveryPersistenceUuidFilterEXT وXrSpatialFilterArchetypeEXT وXrSpatialFilterTrackingStateEXT
• إذا لم تكن قيمة componentTypeCount هي 0، يجب أن تكون قيمة componentTypes مؤشرًا إلى مصفوفة من قيم componentTypeCount صالحة لـ 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، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫entityIdCountOutput هو عدد XrSpatialEntityIdEXT في entityIds، أو السعة المطلوبة في حال عدم كفاية entityIdCapacityInput.
• ‫entityIds هو مصفوفة من XrSpatialEntityIdEXT . يمكن أن تكون القيمة NULL إذا كانت قيمة entityIdCapacityInput هي 0.
• ‫entityStateCapacityInput هي سعة مصفوفة entityStates، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫entityStateCountOutput هو عدد XrSpatialEntityTrackingStateEXT في entityStates، أو السعة المطلوبة في حال عدم كفاية entityStateCapacityInput. يجب أن تكون هذه السمة دائمًا مماثلة لسمة entityIdCountOutput .
• ‫entityStates هو مصفوفة من XrSpatialEntityTrackingStateEXT . يمكن أن تكون القيمة NULL إذا كانت قيمة entityStateCapacityInput هي 0.
• يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم entityIds المطلوب.

يمكن للتطبيق استخدام entityIds مع xrCreateSpatialEntityFromIdEXT لإنشاء مؤشرات XrSpatialEntityEXT للكيانات التي يريد الحصول على تحديثات منتظمة لها. يمكن للتطبيق بعد ذلك استخدام مؤشرات XrSpatialEntityEXT هذه مع xrCreateSpatialUpdateSnapshotEXT لإنشاء لقطة تحديث تحتوي على أحدث البيانات المعروفة لبيئة التشغيل الخاصة بالمكوّنات للعناصر المقدَّمة.

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrSpatialComponentDataQueryResultEXT
• يجب أن يكون type XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية . يُرجى الاطّلاع أيضًا على: XrSpatialComponentAnchorListEXT وXrSpatialComponentAnnotationQuadListANDROID وXrSpatialComponentBounded2DListEXT وXrSpatialComponentBounded3DListEXT وXrSpatialComponentConfidenceListANDROIDSYS وXrSpatialComponentImage2DListEXT وXrSpatialComponentKeyboardSemanticLabelListEXT وXrSpatialComponentMarkerListEXT وXrSpatialComponentMaterialTypeListANDROIDSYS وXrSpatialComponentMesh2DListEXT وXrSpatialComponentMesh3DListEXT وXrSpatialComponentMesh3DNormalsListEXT وXrSpatialComponentMesh3DTriangleSemanticLabelsListEXT وXrSpatialComponentMesh3DVertexSemanticLabelsListEXT وXrSpatialComponentMouseSemanticLabelListEXT وXrSpatialComponentObjectSemanticLabelListANDROID وXrSpatialComponentObjectSemanticLabelListEXT وXrSpatialComponentOccupancyGridListANDROIDX1 وXrSpatialComponentParentListEXT وXrSpatialComponentPersistenceListEXT وXrSpatialComponentPersistenceScopesListANDROIDX1 وXrSpatialComponentPlaneAlignmentListEXT وXrSpatialComponentPlaneSemanticLabelListEXT وXrSpatialComponentPolygon2DListEXT وXrSpatialComponentRaycastResultListANDROID وXrSpatialComponentRoomEmptinessListANDROIDSYS وXrSpatialComponentRoomListANDROIDSYS وXrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2 وXrSpatialComponentSubsumedByListANDROID
• إذا لم تكن قيمة entityIdCapacityInput هي 0، يجب أن تكون قيمة entityIds مؤشرًا إلى مصفوفة من قيم entityIdCapacityInput XrSpatialEntityIdEXT
• إذا لم تكن قيمة entityStateCapacityInput هي 0، يجب أن تكون قيمة entityStates مؤشرًا إلى مصفوفة من قيم entityStateCapacityInput XrSpatialEntityTrackingStateEXT

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

يتتبّع وقت التشغيل حاليًا هذا الكيان، وتكون بيانات المكوّنات الخاصة به صالحة.

التتبع

تم الإيقاف مؤقتًا

متوقّف

الشكل 23: 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 إذا تم فقدان الكيان المكاني ولن يتم استرداد عملية تتبُّعه أو استئنافها مطلقًا. على سبيل المثال، إذا فقد الجهاز إمكانية التتبُّع، وأعاد تشغيل جلسة التتبُّع ولكن تعذّر عليه إعادة تحديد موقعه في بيئته، وبالتالي يتعامل مع العناصر التي تم اكتشافها في جلسة التتبُّع هذه على أنّها عناصر جديدة.
• Once the tracking state of an entity is set to XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , the runtime must never change it any other state.
• عند طلب بيانات المكوّنات لكيان مكاني باستخدام xrQuerySpatialComponentDataEXT، يجب أن يضبط وقت التشغيل بيانات صالحة في محتوى المخازن المؤقتة التي يوفّرها التطبيق في السلسلة التالية من XrSpatialComponentDataQueryResultEXT إذا كانت حالة الكيان هي XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . إذا كانت حالة الكيان هي XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT أو XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT، يجب ألا يغيّر وقت التشغيل محتوى المخازن المؤقتة.

Two-call idiom for component data

يتم تعريف بنية XrSpatialBufferEXT على النحو التالي:

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

أوصاف الأعضاء

• bufferId XrSpatialBufferIdEXT بيانات المخزن المؤقت.
• ‫bufferType هو XrSpatialBufferTypeEXT للإشارة إلى نوع البيانات في bufferId . يمكن للتطبيق استخدام bufferType لتحديد الدالة التي يجب استخدامها لاسترداد البيانات الفعلية من المخزن المؤقت.

تحتوي بعض المكوّنات المكانية على بيانات متغيّرة الحجم، وبالتالي تتطلّب استخدام أسلوب الاستدعاء المزدوج لاسترداد بياناتها. في هذه الحالات، توفّر بنية بيانات المكوّن المكاني XrSpatialBufferEXT لكل مخزن مؤقت بحجم متغيّر مطلوب في بيانات هذا المكوّن.

بالنسبة إلى bufferId نفسه، يجب أن يوفّر وقت التشغيل البيانات نفسها من طلب بيانات مكوّن إلى آخر، حتى من لقطة إلى أخرى. يشير اختلاف bufferId بين طلبات البحث عن بيانات المكوّن إلى التطبيق بأنّ بيانات هذا المكوّن قد تكون قد تغيّرت.

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrSpatialBufferEXT
• يجب أن تكون قيمة bufferType صالحة لـ XrSpatialBufferTypeEXT

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 هي سعة المصفوفة، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫bufferCountOutput هو عدد الأحرف أو السعة المطلوبة في حال عدم كفاية bufferCapacityInput.
• ‫buffer هو مصفوفة من char . يمكن أن تكون القيمة NULL إذا كانت قيمة bufferCapacityInput هي 0.
• يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم buffer المطلوب.

يمكن للتطبيق الحصول على بيانات XrSpatialBufferEXT التي يوفّرها أحد المكوّنات، حيث تكون قيمة XrSpatialBufferEXT :: bufferType هي XR_SPATIAL_BUFFER_TYPE_STRING_EXT باستخدام xrGetSpatialBufferStringEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE إذا لم يكن XrSpatialBufferTypeEXT لـ XrSpatialBufferGetInfoEXT :: bufferId هو XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT إذا لم يكن bufferId في XrSpatialBufferGetInfoEXT تابعًا لـ snapshot .

يجب أن تكون السمة buffer التي يتم ملؤها من خلال وقت التشغيل عبارة عن سلسلة UTF-8 منتهية بقيمة فارغة.

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استدعاء xrGetSpatialBufferStringEXT
• يجب أن يكون snapshot اسمًا معرِّفًا صالحًا لـ XrSpatialSnapshotEXT
• يجب أن يكون info مؤشرًا إلى بنية XrSpatialBufferGetInfoEXT صالحة
• يجب أن يكون bufferCountOutput مؤشرًا إلى قيمة uint32_t
• إذا لم تكن السمة bufferCapacityInput هي 0، يجب أن تكون السمة buffer مؤشرًا إلى مصفوفة من قيم الأحرف bufferCapacityInput

رموز الإرجاع

Success

• 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 هي سعة المصفوفة، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫bufferCountOutput هو عدد العناصر في مصفوفة buffer، أو السعة المطلوبة في حال عدم كفاية bufferCapacityInput.
• ‫buffer هو مصفوفة من uint8_t . يمكن أن تكون القيمة NULL إذا كانت قيمة bufferCapacityInput هي 0.
• يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم buffer المطلوب.

يمكن للتطبيق الحصول على بيانات XrSpatialBufferEXT التي يوفّرها أحد المكوّنات، حيث تكون قيمة XrSpatialBufferEXT :: bufferType هي XR_SPATIAL_BUFFER_TYPE_UINT8_EXT باستخدام xrGetSpatialBufferUint8EXT .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE إذا لم يكن XrSpatialBufferTypeEXT لـ XrSpatialBufferGetInfoEXT :: bufferId هو XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT إذا لم يكن bufferId في XrSpatialBufferGetInfoEXT تابعًا لـ snapshot .

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استدعاء xrGetSpatialBufferUint8EXT
• يجب أن يكون snapshot اسمًا معرِّفًا صالحًا لـ XrSpatialSnapshotEXT
• info يجب أن يكون مؤشرًا إلى بنية XrSpatialBufferGetInfoEXT صالحة
• يجب أن يكون bufferCountOutput مؤشرًا إلى قيمة uint32_t
• إذا لم تكن قيمة bufferCapacityInput هي 0، يجب أن تكون قيمة buffer مؤشرًا إلى مصفوفة من قيم bufferCapacityInput uint8_t

رموز الإرجاع

Success

• 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 هي سعة المصفوفة، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫bufferCountOutput هو عدد العناصر في مصفوفة buffer، أو السعة المطلوبة في حال عدم كفاية bufferCapacityInput.
• ‫buffer هو مصفوفة من uint16_t . يمكن أن تكون القيمة NULL إذا كانت قيمة bufferCapacityInput هي 0.
• يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم buffer المطلوب.

يمكن للتطبيق الحصول على بيانات XrSpatialBufferEXT التي يوفّرها أحد المكوّنات، حيث يكون XrSpatialBufferEXT :: bufferType هو XR_SPATIAL_BUFFER_TYPE_UINT16_EXT باستخدام xrGetSpatialBufferUint16EXT .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE إذا لم يكن XrSpatialBufferTypeEXT لـ XrSpatialBufferGetInfoEXT :: bufferId هو XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT إذا لم يكن bufferId في XrSpatialBufferGetInfoEXT تابعًا لـ snapshot .

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استدعاء xrGetSpatialBufferUint16EXT
• يجب أن يكون snapshot اسمًا معرِّفًا صالحًا لـ XrSpatialSnapshotEXT
• يجب أن يكون info مؤشرًا إلى بنية XrSpatialBufferGetInfoEXT صالحة
• يجب أن يكون bufferCountOutput مؤشرًا إلى قيمة uint32_t
• إذا لم تكن قيمة bufferCapacityInput هي 0، يجب أن تكون قيمة buffer مؤشرًا إلى مصفوفة من قيم bufferCapacityInput uint16_t

رموز الإرجاع

Success

• 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 هي سعة المصفوفة، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫bufferCountOutput هو عدد العناصر في مصفوفة buffer، أو السعة المطلوبة في حال عدم كفاية bufferCapacityInput.
• ‫buffer هو مصفوفة من uint32_t . يمكن أن تكون القيمة NULL إذا كانت قيمة bufferCapacityInput هي 0.
• يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم buffer المطلوب.

يمكن للتطبيق الحصول على بيانات XrSpatialBufferEXT التي يوفّرها أحد المكوّنات، حيث تكون قيمة XrSpatialBufferEXT :: bufferType هي XR_SPATIAL_BUFFER_TYPE_UINT32_EXT باستخدام xrGetSpatialBufferUint32EXT .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE إذا لم يكن XrSpatialBufferTypeEXT لـ XrSpatialBufferGetInfoEXT :: bufferId هو XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT إذا لم يكن bufferId في XrSpatialBufferGetInfoEXT تابعًا لـ snapshot .

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استدعاء xrGetSpatialBufferUint32EXT
• يجب أن يكون snapshot اسمًا معرِّفًا صالحًا لـ XrSpatialSnapshotEXT
• يجب أن يكون info مؤشرًا إلى بنية XrSpatialBufferGetInfoEXT صالحة
• يجب أن يكون bufferCountOutput مؤشرًا إلى قيمة uint32_t
• إذا لم تكن قيمة bufferCapacityInput هي 0، يجب أن تكون قيمة buffer مؤشرًا إلى مصفوفة من قيم bufferCapacityInput uint32_t

رموز الإرجاع

Success

• 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 هي سعة المصفوفة، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫bufferCountOutput هو عدد العناصر في مصفوفة buffer، أو السعة المطلوبة في حال عدم كفاية bufferCapacityInput.
• ‫buffer هو مصفوفة من float . يمكن أن تكون القيمة NULL إذا كانت قيمة bufferCapacityInput هي 0.
• يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم buffer المطلوب.

يمكن للتطبيق الحصول على بيانات XrSpatialBufferEXT التي يوفّرها أحد المكوّنات، حيث تكون قيمة XrSpatialBufferEXT :: bufferType هي XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT باستخدام xrGetSpatialBufferFloatEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE إذا لم يكن XrSpatialBufferTypeEXT لـ XrSpatialBufferGetInfoEXT :: bufferId هو XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT إذا لم يكن bufferId في XrSpatialBufferGetInfoEXT تابعًا لـ snapshot .

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استدعاء xrGetSpatialBufferFloatEXT
• يجب أن يكون snapshot اسمًا معرِّفًا صالحًا لـ XrSpatialSnapshotEXT
• يجب أن يكون info مؤشرًا إلى بنية XrSpatialBufferGetInfoEXT صالحة
• يجب أن يكون bufferCountOutput مؤشرًا إلى قيمة uint32_t
• إذا لم تكن قيمة bufferCapacityInput هي 0، يجب أن تكون قيمة buffer مؤشرًا إلى مصفوفة من قيم bufferCapacityInput float

رموز الإرجاع

Success

• 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 هي سعة المصفوفة، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫bufferCountOutput هو عدد العناصر في مصفوفة buffer، أو السعة المطلوبة في حال عدم كفاية bufferCapacityInput.
• ‫buffer هي مصفوفة من XrVector2f . يمكن أن تكون القيمة NULL إذا كانت قيمة bufferCapacityInput هي 0.
• يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم buffer المطلوب.

يمكن للتطبيق الحصول على بيانات XrSpatialBufferEXT التي يوفّرها أحد المكوّنات، حيث تكون قيمة XrSpatialBufferEXT :: bufferType هي XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT باستخدام xrGetSpatialBufferVector2fEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE إذا لم يكن XrSpatialBufferTypeEXT لـ XrSpatialBufferGetInfoEXT :: bufferId هو XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT إذا لم يكن bufferId في XrSpatialBufferGetInfoEXT تابعًا لـ snapshot .

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استدعاء xrGetSpatialBufferVector2fEXT
• يجب أن يكون snapshot اسمًا معرِّفًا صالحًا لـ XrSpatialSnapshotEXT
• يجب أن يكون info مؤشرًا إلى بنية XrSpatialBufferGetInfoEXT صالحة
• يجب أن يكون bufferCountOutput مؤشرًا إلى قيمة uint32_t
• إذا لم تكن قيمة bufferCapacityInput هي 0، buffer يجب أن تكون مؤشرًا إلى مصفوفة من هياكل bufferCapacityInput XrVector2f

رموز الإرجاع

Success

• 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 هي سعة المصفوفة، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫bufferCountOutput هو عدد العناصر في مصفوفة buffer، أو السعة المطلوبة في حال عدم كفاية bufferCapacityInput.
• ‫buffer هي مصفوفة من XrVector3f . يمكن أن تكون القيمة NULL إذا كانت قيمة bufferCapacityInput هي 0.
• يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم buffer المطلوب.

يمكن للتطبيق الحصول على بيانات XrSpatialBufferEXT التي يوفّرها أحد المكوّنات، حيث تكون قيمة XrSpatialBufferEXT :: bufferType هي XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT باستخدام xrGetSpatialBufferVector3fEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE إذا لم يكن XrSpatialBufferTypeEXT لـ XrSpatialBufferGetInfoEXT :: bufferId هو XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT إذا لم يكن bufferId في XrSpatialBufferGetInfoEXT تابعًا لـ snapshot .

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل طلب xrGetSpatialBufferVector3fEXT
• يجب أن يكون snapshot اسمًا معرِّفًا صالحًا لـ XrSpatialSnapshotEXT
• يجب أن يكون info مؤشرًا إلى بنية XrSpatialBufferGetInfoEXT صالحة
• يجب أن يكون bufferCountOutput مؤشرًا إلى قيمة uint32_t
• إذا لم تكن قيمة bufferCapacityInput هي 0، يجب أن تكون قيمة buffer مؤشرًا إلى مصفوفة من هياكل bufferCapacityInput XrVector3f

رموز الإرجاع

Success

• 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 للمخزن المؤقت الذي سيتم استرداد بياناته.

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrSpatialBufferGetInfoEXT
• يجب أن يكون type XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT هي قيمة محجوزة تمثّل XrSpatialBufferIdEXT غير صالح. وقد يتم تمريرها إلى دوال واجهة برمجة التطبيقات وإرجاعها منها فقط عندما يكون ذلك مسموحًا به تحديدًا.

إنشاء لقطة تحديث

يتم تعريف الدالة xrCreateSpatialUpdateSnapshotEXT على النحو التالي:

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

أوصاف المَعلمات

• ‫spatialContext هو XrSpatialContextEXT تم إنشاؤه سابقًا باستخدام xrCreateSpatialContextAsyncEXT .
• createInfo هو مؤشر إلى XrSpatialUpdateSnapshotCreateInfoEXT .
• snapshot هو مؤشر إلى النتيجة XrSpatialSnapshotEXT .

يمكن للتطبيق استخدام xrCreateSpatialUpdateSnapshotEXT لإنشاء لقطة والحصول على أحدث بيانات المكوّنات لكيانات معيّنة كما يعرفها وقت التشغيل. يمكن للتطبيقات توفير مؤشرات XrSpatialEntityEXT وأنواع المكوّنات التي تهمّها عند إنشاء اللقطة.

يمكن للتطبيق استخدام XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes لفلترة قائمة المكوّنات التي يجب تضمين بياناتها في اللقطة. إذا قدّم التطبيق قائمة صالحة بأنواع المكوّنات المكانية في XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes ، يجب أن يتضمّن وقت التشغيل فقط الكيانات المكانية في اللقطة التي تحتوي على مكوّن واحد على الأقل من المكوّنات المقدَّمة في XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . بالإضافة إلى ذلك، يجب أن يتضمّن وقت التشغيل بيانات هذه المكوّنات فقط في اللقطة.

يجب أن تعرض بيئة التشغيل XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT إذا لم يتم تفعيل أي من XrSpatialComponentTypeEXT في XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes للإمكانات المكانية التي تم تمريرها إلى XrSpatialContextCreateInfoEXT :: capabilityConfigs عند إنشاء spatialContext .

إذا لم يوفّر التطبيق قائمة بأنواع المكوّنات المكانية في XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes، يجب أن يتضمّن وقت التشغيل جميع الكيانات المكانية المدرَجة في XrSpatialUpdateSnapshotCreateInfoEXT :: entities في اللقطة، ويجب أن يتضمّن بيانات جميع المكوّنات المفعَّلة للإمكانات التي تم ضبطها لـ spatialContext .

يجب ألّا يتضمّن وقت التشغيل كيانات مكانية غير مُدرَجة في XrSpatialUpdateSnapshotCreateInfoEXT :: entities في snapshot .

يمكن للتطبيق إنشاء أي عدد من اللقطات التي يريدها، ولكن يجب الانتباه إلى الذاكرة التي يتم تخصيصها لكل لقطة جديدة ويجب تدمير اللقطات عندما لا يعود بحاجة إليها.

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استدعاء xrCreateSpatialUpdateSnapshotEXT
• يجب أن يكون spatialContext مؤشرًا صالحًا لـ XrSpatialContextEXT
• createInfo يجب أن يكون مؤشرًا إلى بنية XrSpatialUpdateSnapshotCreateInfoEXT صالحة
• snapshot يجب أن يكون مؤشرًا إلى اسم معرِّف XrSpatialSnapshotEXT

رموز الإرجاع

Success

• 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);

أوصاف المَعلمات

• ‫snapshot هو XrSpatialSnapshotEXT تم توفيره سابقًا من خلال xrCreateSpatialDiscoverySnapshotCompleteEXT أو xrCreateSpatialUpdateSnapshotEXT .

يمكن للتطبيق استدعاء xrDestroySpatialSnapshotEXT لتدمير مؤشر XrSpatialSnapshotEXT والموارد المرتبطة به.

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استدعاء xrDestroySpatialSnapshotEXT
• يجب أن يكون snapshot اسمًا معرِّفًا صالحًا لـ XrSpatialSnapshotEXT

أمان Thread

• يجب مزامنة الوصول إلى snapshot وأي معرّفات فرعية خارجيًا

رموز الإرجاع

Success

• 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 هو نطاق المكوّن الثنائي الأبعاد المحدود على طول المحور س (extents.width) والمحور ص (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 سطح عمودي سطح عمودي سطح أفقي سطح أفقي العرض العرض العرض العرض الارتفاع الارتفاع

الشكل 24: نظام إحداثيات المكوّنات Bounded2D

ملاحظة

يستخدم OpenXR مستوى X-Y مع +Z كالمستوى العمودي، ولكن قد تستخدم واجهات برمجة التطبيقات الأخرى مستوى X-Z مع +Y كالمستوى العمودي. يمكن تحويل المستوى س-ص إلى المستوى س-ع من خلال تدوير -π/2 راديان حول المحور +س.

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrSpatialBounded2DDataEXT

بنية قائمة المكوّنات لطلب البيانات

يتم تحديد بنية 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 .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE من xrQuerySpatialComponentDataEXT إذا كان XrSpatialComponentBounded2DListEXT في السلسلة التالية من XrSpatialComponentDataQueryResultEXT :: next ولكن XrSpatialComponentDataQueryConditionEXT ::componentTypeCount ليس صفرًا وXR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT غير مضمّن في XrSpatialComponentDataQueryConditionEXT :: componentTypes .

يجب أن يعرض وقت التشغيل XR_ERROR_SIZE_INSUFFICIENT من xrQuerySpatialComponentDataEXT إذا كان boundCount أقل من XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

إذا تم إنشاء xrQuerySpatialComponentDataEXT :: snapshot من xrCreateSpatialDiscoverySnapshotCompleteEXT، يجب أن يوفّر وقت التشغيل XrSpatialBounded2DDataEXT :: center في XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace وXrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

إذا تم إنشاء xrQuerySpatialComponentDataEXT :: snapshot من xrCreateSpatialUpdateSnapshotEXT، يجب أن يوفّر وقت التشغيل XrSpatialBounded2DDataEXT :: center في XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace وXrSpatialUpdateSnapshotCreateInfoEXT :: time .

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استخدام XrSpatialComponentBounded2DListEXT
• يجب أن يكون type XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية
• bounds يجب أن يكون مؤشرًا إلى مصفوفة من هياكل boundCount XrSpatialBounded2DDataEXT
• يجب أن تكون المَعلمة boundCount أكبر من 0

الإعداد

إذا تم تعداد XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT في XrSpatialCapabilityComponentTypesEXT :: componentTypes لبعض الإمكانات، يمكن للتطبيق تفعيلها من خلال تضمين قيمة التعداد في قائمة XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. لا يتطلّب هذا المكوّن أي إعدادات خاصة ليتم تضمينه في السلسلة التالية من XrSpatialCapabilityConfigurationBaseHeaderEXT .

Bounded 3D

بيانات المكوّنات

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 .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE من xrQuerySpatialComponentDataEXT إذا كان XrSpatialComponentBounded3DListEXT في السلسلة التالية من XrSpatialComponentDataQueryResultEXT :: next ولكن XrSpatialComponentDataQueryConditionEXT ::componentTypeCount ليس صفرًا وXR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT غير مضمّن في XrSpatialComponentDataQueryConditionEXT :: componentTypes .

يجب أن يعرض وقت التشغيل XR_ERROR_SIZE_INSUFFICIENT من xrQuerySpatialComponentDataEXT إذا كان boundCount أقل من XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

إذا تم إنشاء xrQuerySpatialComponentDataEXT :: snapshot من xrCreateSpatialDiscoverySnapshotCompleteEXT، يجب أن يوفّر وقت التشغيل XrBoxf :: center في XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace في 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 لبعض الإمكانات، يمكن للتطبيق تفعيلها من خلال تضمين التعداد في قائمة 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 .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE من xrQuerySpatialComponentDataEXT إذا كان XrSpatialComponentParentListEXT في السلسلة التالية من XrSpatialComponentDataQueryResultEXT :: next ولكن XrSpatialComponentDataQueryConditionEXT ::componentTypeCount ليس صفرًا وXR_SPATIAL_COMPONENT_TYPE_PARENT_EXT غير مضمّن في XrSpatialComponentDataQueryConditionEXT :: componentTypes .

يجب أن يعرض وقت التشغيل XR_ERROR_SIZE_INSUFFICIENT من xrQuerySpatialComponentDataEXT إذا كان parentCount أقل من XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة 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 لبعض الإمكانات، يمكن للتطبيق تفعيلها من خلال تضمين التعداد في قائمة 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 .

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrSpatialMeshDataEXT
• vertexBuffer يجب أن يكون بنية XrSpatialBufferEXT صالحة
• indexBuffer يجب أن يكون بنية XrSpatialBufferEXT صالحة

بنية قائمة المكوّنات لطلب البيانات

يتم تحديد بنية XrSpatialComponentMesh3DListEXT على النحو التالي:

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

أوصاف الأعضاء

• ‫type هو XrStructureType لهذه البنية.
• ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
• ‫meshCount هو uint32_t يصف عدد العناصر في مصفوفة meshes.
• ‫meshes هي مصفوفة من XrSpatialMeshDataEXT .

يمكن للتطبيق طلب البحث عن مكوّن الشبكة الثلاثية الأبعاد للكيانات المكانية في XrSpatialSnapshotEXT من خلال إضافة XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT في XrSpatialComponentDataQueryConditionEXT :: componentTypes وإضافة XrSpatialComponentMesh3DListEXT إلى سلسلة المؤشرات التالية من XrSpatialComponentDataQueryResultEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE من xrQuerySpatialComponentDataEXT إذا كان XrSpatialComponentMesh3DListEXT في السلسلة التالية من XrSpatialComponentDataQueryResultEXT :: next ولكن XrSpatialComponentDataQueryConditionEXT ::componentTypeCount ليس صفرًا وXR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT غير مضمّن في XrSpatialComponentDataQueryConditionEXT :: componentTypes .

يجب أن يعرض وقت التشغيل XR_ERROR_SIZE_INSUFFICIENT من xrQuerySpatialComponentDataEXT إذا كان meshCount أقل من XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

بالنسبة إلى XrSpatialMeshDataEXT التي يملأها وقت التشغيل في مصفوفة meshes، يجب أن تكون قيمة XrSpatialBufferEXT :: bufferType لـ XrSpatialMeshDataEXT :: vertexBuffer هي XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT ويجب أن تكون قيمة XrSpatialBufferEXT :: bufferType لـ XrSpatialMeshDataEXT :: indexBuffer هي XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

الاستخدام الصالح (ضمني)

• يجب تفعيل الإضافة XR_EXT_spatial_entity قبل استخدام XrSpatialComponentMesh3DListEXT
• يجب أن يكون type XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية
• يجب أن يكون meshes مؤشرًا إلى مصفوفة من هياكل meshCount XrSpatialMeshDataEXT
• يجب أن تكون المَعلمة meshCount أكبر من 0

الإعداد

إذا تم تعداد XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT في XrSpatialCapabilityComponentTypesEXT :: componentTypes لبعض الإمكانات، يمكن للتطبيق تفعيلها من خلال تضمين التعداد في قائمة 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 فقط.

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_EXT_spatial_entity قبل استخدام XrSpatialFilterTrackingStateEXT
• يجب أن يكون type XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية
• trackingState يجب أن تكون قيمة XrSpatialEntityTrackingStateEXT صالحة

مثال على الشفرة

استخدام التطبيق

تستخدم التطبيقات عادةً إضافة الكيان المكاني بالنمط التالي:

• يُعدّد التطبيق أولاً الإمكانات المكانية للنظام باستخدام xrEnumerateSpatialCapabilitiesEXT . بعد ذلك، تفحص الصفيفة المعروضة من XrSpatialCapabilityEXT وتعدّد المكوّنات والميزات المتوافقة مع كلّ من هذه الإمكانات باستخدام xrEnumerateSpatialCapabilityComponentTypesEXT وxrEnumerateSpatialCapabilityFeaturesEXT على التوالي. يمنح ذلك التطبيق صورة كاملة عن المكوّنات التي يمكنه تفعيلها والإعدادات التي تقبلها الميزة.
• بعد ذلك، ينشئ التطبيق معالجًا واحدًا أو أكثر من معالجات XrSpatialContextEXT بإعدادات إمكانات مكانية محدّدة، حيث تفعّل الإعدادات إمكانية معيّنة في السياق المكاني وتضبطها، وتفعّل المكوّنات لهذه الإمكانات وتضبطها.
• لكل XrSpatialContextEXT، ينتظر التطبيق تلقّي أحداث XrEventDataSpatialDiscoveryRecommendedEXT لهذا XrSpatialContextEXT قبل استخدام xrCreateSpatialDiscoverySnapshotAsyncEXT لاكتشاف الكيانات المكانية. بعد اكتمال هذه العملية غير المتزامنة، يتلقّى التطبيق مؤشر XrSpatialSnapshotEXT.
• يستعلم التطبيق عن الكيانات وبيانات المكوّنات المضمّنة في XrSpatialSnapshotEXT باستخدام xrQuerySpatialComponentDataEXT . يقرأ التطبيق أحدث بيانات المكوّنات للكيانات التي تم طلبها من البُنى المرفقة بالسلسلة التالية من XrSpatialComponentDataQueryResultEXT إذا كانت حالة الكيان هي XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT .
• إذا كانت هناك كيانات محدّدة يحدّدها التطبيق على أنّها مثيرة للاهتمام ويريد الحصول على تحديثات لها بمرور الوقت، فإنّه ينشئ عناصر تحكّم XrSpatialEntityEXT لهذه الكيانات باستخدام xrCreateSpatialEntityFromIdEXT . يحصل التطبيق على تحديثات لهذه الكيانات المهمة باستخدام 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 لكل مخزن مؤقت. يمكن للتطبيق بعد ذلك الاستعلام عن بيانات المخزن المؤقت باستخدام الدوال المحددة في Two-call idiom for component data . ومن الأمثلة على هذه البنية XrSpatialMeshDataEXT المضمّنة في XrSpatialComponentMesh3DListEXT .
  • يمكن أن توفّر الإضافة أيضًا هياكل يمكن للتطبيق ربطها بـ XrSpatialComponentDataQueryConditionEXT :: next لتوفير فلاتر إضافية لطلب البحث المتعلّق ببيانات هذا المكوّن.

• يمكن للإضافات تحديد البُنى التي توسّع XrSpatialDiscoverySnapshotCreateInfoEXT لتوفير فلاتر إضافية للاستكشاف. يجب ألا تؤثر فلاتر إنشاء اللقطة في إعدادات السياق المكاني، بل يجب استخدامها لتقديم تلميحات إلى وقت التشغيل حول الكيانات والبيانات التي يجب تضمينها في اللقطة كما يتم تتبُّعها من خلال الإعدادات الحالية للسياق المكاني (وبالتالي الإعدادات الحالية للخدمات الأساسية).

• إذا حدّدت الإضافة XrSpatialCapabilityEXT جديدة،

  • يجب أيضًا تحديد قائمة XrSpatialComponentTypeEXT التي يجب أن توفّرها بيئات التشغيل على الكيانات لهذه الميزة.
  • يجب أيضًا أن توفّر هياكل مشتقة من XrSpatialCapabilityConfigurationBaseHeaderEXT تتيح ضبط هذه الإمكانية.

• إذا حدّدت إحدى الإضافات ميزة XrSpatialCapabilityFeatureEXT جديدة، يجب أيضًا تحديد بنية ضبط مقابلة يمكن ربطها بالمؤشر التالي لـ XrSpatialCapabilityConfigurationBaseHeaderEXT، والتي يمكن للتطبيق استخدامها لتفعيل الميزة عند إنشاء XrSpatialContextEXT .

• يجب أن تتبع الإضافة التي تحدّد XrSpatialCapabilityEXT جديدة هذا النموذج للمواصفات -

  • نظرة عامة
  • دعم وقت التشغيل
  • الإعداد
  • المكوّنات المضمونة
  • مثال على الشفرة

• يجب أن تتبع الإضافة التي تحدد XrSpatialComponentTypeEXT جديدًا هذا النموذج للمواصفات -

  • بيانات المكوّنات
  • بنية قائمة المكوّنات لطلب البيانات
  • الإعداد

• عند كتابة واجهة برمجة تطبيقات تزوّد التطبيق بـ XrSpatialBufferIdEXT، يجب أن تكون مصحوبة بـ XrSpatialBufferTypeEXT لإعلام التطبيق بنوع بيانات المخزن المؤقت، ويمكن للتطبيق استخدام دالة xrGetSpatialBuffer* مناسبة لاسترداد المحتوى الفعلي للمخزن المؤقت.

إرشادات تصميم التصنيفات الدلالية والإضافات

على الرغم من أنّ هذه الإضافة لا تحدّد أي مكوّن لنقل معلومات التصنيف الدلالي لكيان معيّن، فإنّها تضع قواعد التصميم والإرشادات لأي إضافات تحدّد مثل هذا المكوّن. في النص التالي، يقيّد المصطلحان " ينبغي " و " يجب " مؤلفي هذه الوظيفة، بدلاً من تقييد تنفيذ وقت التشغيل أو تطبيق يستخدم واجهة برمجة التطبيقات.

• إذا كانت الإضافة تحدّد تصنيفات دلالية لأي XrSpatialCapabilityEXT، يجب أن تفعل ذلك من خلال تحديد XrSpatialComponentTypeEXT جديد بالإضافة إلى تعداد جديد مع مجموعة من التصنيفات ("مجموعة تصنيفات دلالية") لتكون البيانات لهذا المكوّن.
• يجب أن يكون للتعداد الذي يمثّل مجموعة تصنيفات دلالية قيمة تشير إلى أنّ الكيان غير مصنّف ضمن أي من تصنيفات هذه المجموعة. يجب أن يتضمّن اسم هذا التعداد "UNCATEGORIZED"، مثل XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT. تشير هذه القيمة للتطبيقات إلى أنّ بيئة التشغيل تتعرّف على هذا الكيان، ولكن هناك مجموعات تصنيفات دلالية أخرى يتم تصنيف هذا الكيان فيها.
• يشير تعداد XrSpatialComponentTypeEXT المحدّد حديثًا في xrEnumerateSpatialCapabilityComponentTypesEXT إلى أنّ وقت التشغيل يتيح استخدام مجموعة التصنيفات الدلالية (وبالتالي التصنيفات المحدّدة في المجموعة) التي تتوافق مع نوع المكوّن هذا.
• تعبّر التطبيقات عن رغبتها في اكتشاف الكيانات التي تحمل تصنيفات تنتمي إلى مجموعة التصنيفات الدلالية هذه من خلال تضمين XrSpatialComponentTypeEXT المقابل في مصفوفة XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents لبنية الإعدادات الخاصة بالميزة التي يتم تعداد نوع المكوّن لها.
• من الممكن أن يحتوي كيان مكاني واحد على مكوّنات متعددة، يوفّر كل منها تصنيفًا من مجموعة التصنيفات الدلالية الخاصة به. لنفترض المثال التالي مع بعض مجموعات التصنيفات الدلالية الافتراضية - 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
|====