XR_EXT_spatial_entity

سلسلة الاسم

XR_EXT_spatial_entity

نوع الإضافة

إضافة مثيل

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

741

المراجعة

1

حالة التصديق

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

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

XR_EXT_future

المساهمون

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

نظرة عامة

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

في ما يلي الأجزاء الرئيسية لهذه الإضافة:

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

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

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

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

كيان مكاني

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

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

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

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

يتم تمثيل الكيانات المكانية إما بذرة XrSpatialEntityIdEXT أو معرّف XrSpatialEntityEXT، ويتم تقديم تفاصيل ذلك في قسم تمثيلات الكيانات المكانية.

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

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

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

إمكانات "المساحة" وإعدادها

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

إمكانية رصد وتتبُّع علامات AprilTag (تمت الإضافة بواسطة إضافة XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

تتبُّع العناصر (تمت إضافته من خلال الإضافة XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

إمكانية إنشاء نقاط ارتساء مكانية (تمت إضافتها من خلال إضافة XR_EXT_spatial_anchor)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

إمكانية رصد وتتبُّع الصور المرجعية المستوية (تمت الإضافة بواسطة إضافة XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

إمكانية تتبُّع شبكة بيئة (تمت الإضافة بواسطة إضافة XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

تتبُّع العناصر (تمت إضافته من خلال الإضافة XR_ANDROID_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

Raycast against depth buffer (Added by the XR_ANDROID_spatial_discovery_raycast extension)

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

رموز الإرجاع

تم بنجاح

  • 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_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 المطلوب.

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

ميزات إمكانية الاستشعار المكاني

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

رموز الإرجاع

تم بنجاح

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

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

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

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

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

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

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

لضمان الاستخدام الأمثل لموارد النظام، يمكن لبيئة التشغيل استخدام عمليات الضبط المقدَّمة في مصفوفة 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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

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

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

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
  • ‫capabilityConfigCount هو uint32_t يصف عدد العناصر في مصفوفة capabilityConfigs.
  • ‫capabilityConfigs هو مؤشر إلى مصفوفة من مؤشرات XrSpatialCapabilityConfigurationBaseHeaderEXT.

يصف البنية XrSpatialContextCreateInfoEXT المعلومات اللازمة لإنشاء معرّف XrSpatialContextEXT.

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

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

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

لا يتم استخدام هذه البنية مباشرةً في واجهة برمجة التطبيقات، ولكن يمكن استخدام بنياتها الفرعية مع 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 .

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

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

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

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

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

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

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

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • ‫futureResult هو XrResult لعملية إنشاء السياق المكاني.
  • ‫spatialContext هو XrSpatialContextEXT تم إنشاؤه باستخدام البيانات والإعدادات في xrCreateSpatialContextAsyncEXT :: createInfo .

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

قيم futureResult:

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

إذا كان futureResult رمز نجاح، يجب أن يكون spatialContext صالحًا. إذا كان spatialContext صالحًا، سيظل كذلك فقط خلال دورة حياة xrCreateSpatialContextAsyncEXT :: session أو إلى أن يدمّر التطبيق spatialContext باستخدام xrDestroySpatialContextEXT، أيهما يحدث أولاً.

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

محو السياق المكاني

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

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

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

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

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

أمان سلاسل المحادثات

  • يجب مزامنة حساب spatialContext وأي أسماء مستخدمين للأطفال بشكل خارجي

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS

تعذُّر

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

تمثيلات الكيانات المكانية

رقم تعريف الكيان المكاني

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

يُستخدَم الرمز XrSpatialEntityIdEXT لتمثيل أي نوع من الكيانات التي يكتشفها وقت التشغيل في البيئة المكانية للمستخدم. يكون XrSpatialEntityIdEXT صالحًا في XrSpatialContextEXT الذي يتم اكتشافه فيه، ويجب ألا يعيد وقت التشغيل استخدام XrSpatialEntityIdEXT نفسه لكيانات مختلفة ضمن XrSpatialContextEXT نفسه . بالإضافة إلى ذلك، يجب ألا يعيد وقت التشغيل استخدام XrSpatialEntityIdEXT نفسه في عدة XrSpatialContextEXT ضمن XrSession نفسها، بغض النظر عمّا إذا كانت تمثّل الكيان نفسه أو كيانات مختلفة.

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

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

معرّف الكيان المكاني

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

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

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

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

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

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

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

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

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

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

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
  • entityId هو XrSpatialEntityIdEXT العنصر الذي يريد التطبيق إنشاء معرّف له.

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

Destroy Spatial Entity Handle

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

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

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

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

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

أمان سلاسل المحادثات

  • يجب مزامنة حساب spatialEntity وأي أسماء مستخدمين للأطفال بشكل خارجي

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS

تعذُّر

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Spatial Snapshot

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

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

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

إنشاء لقطة "اكتشاف"

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

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

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

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

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

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

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

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

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

إذا تم وضع XrEventDataReferenceSpaceChangePending في قائمة الانتظار قبل اكتمال future، وكانت قيمة XrEventDataReferenceSpaceChangePending :: poseValid هي false، يمكن لوقت التشغيل إما إنشاء XrSpatialSnapshotEXT لا يحتوي على أي عناصر، أو ضبط قيمة XrSpatialEntityTrackingStateEXT للعناصر التي لم يعُد من الممكن تحديد موقعها في XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace على XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time لتصبح XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT أو XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . يجب ألا يضبط وقت التشغيل قيمة XrCreateSpatialContextCompletionEXT :: futureResult على رمز خطأ بسبب XrEventDataReferenceSpaceChangePending.

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

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

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

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
  • ‫componentTypeCount هو uint32_t يصف عدد العناصر في مصفوفة componentTypes.
  • ‫componentTypes هي مصفوفة من XrSpatialComponentTypeEXT .

يصف البنية XrSpatialDiscoverySnapshotCreateInfoEXT المعلومات اللازمة لإنشاء معرّف XrSpatialSnapshotEXT عند اكتشاف الكيانات المكانية.

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

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

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

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

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

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

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

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • ‫baseSpace هو XrSpace الذي سيتم فيه تحديد جميع المواقع الجغرافية XrSpatialSnapshotEXT.
  • time هو XrTime الذي سيتم فيه تحديد جميع المواقع الجغرافية لبيانات الاستكشاف XrSpatialSnapshotEXT.
  • ‫future هو XrFutureEXT الذي تم استلامه من xrCreateSpatialDiscoverySnapshotAsyncEXT

سيتم تمثيل المواقع الجغرافية في بيانات المكوّنات المختلفة المضمَّنة في اللقطة التي تم إنشاؤها في baseSpace، والموجودة في time .

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

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

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

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

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

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

قيم futureResult:

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

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

حدث اقتراح الاكتشاف

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

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

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • ‫spatialContext هو XrSpatialContextEXT الذي يقترح وقت التشغيل إمكانية العثور عليه.

يمكن للتطبيق استرداد هذا الحدث باستخدام xrPollEvent . يمكن للتطبيق تجنُّب إجراء عدد كبير من طلبات البحث إلى xrCreateSpatialDiscoverySnapshotAsyncEXT لاكتشاف الكيانات المكانية من خلال انتظار هذا الحدث. إذا أنشأ التطبيق لقطات متعددة للبحث عن الأجهزة القريبة باستخدام XrSpatialDiscoverySnapshotCreateInfoEXT نفسها بين حدثَي XrEventDataSpatialDiscoveryRecommendedEXT، قد تحتوي اللقطات الناتجة على الكيانات نفسها، وبالتالي سيكون إنشاء اللقطات وطلبات البحث عن البيانات مضيعة للوقت.

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

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

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

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

بعد أن يستدعي التطبيق xrDestroySpatialContextEXT ، يجب ألا يضع وقت التشغيل أي أحداث اقتراحات اكتشاف أخرى في قائمة الانتظار لسياق المكان هذا، ولا يعرض أي أحداث من هذا النوع لهذا السياق من xrPollEvent .

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

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

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

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

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

يمكن للتطبيق استخدام xrQuerySpatialComponentDataEXT للاستعلام عن بيانات المكوّنات الخاصة بالعناصر في اللقطة من خلال إرفاق بنية قائمة بـ XrSpatialComponentDataQueryResultEXT :: next المقابلة لكل XrSpatialComponentTypeEXT في XrSpatialComponentDataQueryConditionEXT :: componentTypes .

إذا أرفق التطبيق بنية قائمة بـ XrSpatialComponentDataQueryResultEXT :: next لا تتوافق مع أي من المكوّنات المُدرَجة في XrSpatialComponentDataQueryConditionEXT :: componentTypes ، يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE.

يمكن للتطبيق اختيار إرفاق بنى القوائم التي تتوافق مع مجموعة فرعية فقط من المكوّنات المُدرَجة في XrSpatialComponentDataQueryConditionEXT :: componentTypes . يمكن للتطبيق اختيار إغفال بنى القوائم تمامًا إذا كان يريد فقط معرفة أرقام التعريف وحالة التتبُّع للكيانات المكانية التي تستوفي queryCondition . يجب ألا يتعامل وقت التشغيل مع عدم توفّر بنى القوائم من سلسلة XrSpatialComponentDataQueryResultEXT :: next على أنّه خطأ.

إذا تم وضع XrEventDataReferenceSpaceChangePending في قائمة الانتظار وانقضى XrEventDataReferenceSpaceChangePending :: changeTime أثناء استعلام التطبيق عن بيانات المكوّن من XrSpatialSnapshotEXT، يمكن للتطبيق استخدام بيانات الحدث لتعديل الوضعيات وفقًا لذلك.

يجب أن يملأ وقت التشغيل XrSpatialComponentDataQueryResultEXT :: entityIds فقط بالكيانات التي تحتوي على جميع المكوّنات المحدّدة في XrSpatialComponentDataQueryConditionEXT :: componentTypes . إذا كانت قيمة XrSpatialComponentDataQueryConditionEXT :: componentTypeCount هي 0، على وقت التشغيل ملء queryResult بجميع الكيانات (وحالات التتبُّع الخاصة بها) الموجودة في اللقطة. في حال إضافة شروط طلب بحث إضافية إلى XrSpatialComponentDataQueryConditionEXT :: next ، يجب أن يتعامل وقت التشغيل مع هذه الشروط على أنّها "و" مع توفّر أنواع المكوّنات، أي يجب أن يملأ وقت التشغيل XrSpatialComponentDataQueryResultEXT ::entityIds فقط بالكيانات التي تستوفي جميع الشروط المقدَّمة. يجب أن يملأ وقت التشغيل بيانات المكوّن في بنى القوائم بالترتيب نفسه الذي تظهر به العناصر في XrSpatialComponentDataQueryResultEXT :: entityIds أي أنّ بيانات المكوّن في فهرس معيّن في مصفوفة بنية القائمة يجب أن تتوافق مع العنصر في الفهرس نفسه.

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

على سبيل المثال، ينشئ التطبيق XrSpatialSnapshotEXT يحتوي على 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

بيانات entit...

بيانات entityId #2

بيانات entit...

بيانات entityId رقم 5

بيانات entit...

entityIds

entityIds

التالي

التالي

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

الحدود

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

بيانات entit...

بيانات entityId رقم 4

بيانات entit...

Mesh3D

Mesh3D

بيانات entityId رقم 3

بيانات entit...

بيانات entityId رقم 4

بيانات entit...

entityIds

entityIds

التالي

التالي

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

bounds

bounds

التالي

التالي

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

شبكات

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

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

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

يتم تعريف بنية 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 لإنشاء لقطة تحديث تتضمّن أحدث البيانات المعروفة في وقت التشغيل للمكوّنات الخاصة بالعناصر المقدَّمة.

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

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 في حال فقدان العنصر المكاني وعدم إمكانية استعادة تتبُّعه أو استئنافه. من الأمثلة على ذلك أن يفقد الجهاز إمكانية التتبُّع، ثم يعيد تشغيل جلسة التتبُّع ولكن يتعذّر عليه إعادة تحديد الموقع الجغرافي في بيئته، وبالتالي يتعامل مع الكيانات التي تم رصدها في جلسة التتبُّع هذه على أنّها كيانات جديدة.
  • بعد ضبط حالة التتبُّع لأحد العناصر على XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT ، يجب ألا يغيّر وقت التشغيل حالته إلى أي حالة أخرى أبدًا.
  • عند طلب بيانات المكوّنات الخاصة بعنصر مكاني باستخدام xrQuerySpatialComponentDataEXT ، يجب أن يضبط وقت التشغيل بيانات صالحة في محتويات المخازن المؤقتة التي يوفّرها التطبيق في السلسلة التالية من XrSpatialComponentDataQueryResultEXT إذا كانت حالة العنصر XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . إذا كانت حالة العنصر XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT أو XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT ، يجب ألا يغيّر وقت التشغيل محتوى المخازن المؤقتة.

عبارة تتضمّن استدعاءَين لبيانات المكوّن

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

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

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

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

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

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

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

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

يُستخدم النوع XrSpatialBufferIdEXT لتمثيل أي نوع من البيانات ذات الحجم المتغيّر لمكوّن مكاني.

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

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

يحدّد التعداد XrSpatialBufferTypeEXT أنواع البيانات المختلفة للمخزن المؤقت الممثَّل XrSpatialBufferIdEXT .

أوصاف القيم المُعدَّدة

  • XR_SPATIAL_BUFFER_TYPE_STRING_EXT . يمكن تمرير XrSpatialBufferIdEXT إلىxrGetSpatialBufferStringEXT لاسترداد مخزن مؤقت للسلسلة.
  • XR_SPATIAL_BUFFER_TYPE_UINT8_EXT . يمكن تمرير XrSpatialBufferIdEXT can إلى 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 can إلى 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 إذا لم يكن XrSpatialBufferGetInfoEXT :: bufferId تابعًا لـ snapshot .

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

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

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

رموز الإرجاع

تم بنجاح

  • 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 إذا لم يكن XrSpatialBufferGetInfoEXT :: bufferId تابعًا لـ snapshot .

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

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

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

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

  • ‫snapshot هو معرّف لكائن XrSpatialSnapshotEXT .
  • تحتوي info على معلومات حول المخزن المؤقت المطلوب البحث فيه.
  • bufferCapacityInput هي سعة المصفوفة، أو 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 إذا لم يكن XrSpatialBufferGetInfoEXT :: bufferId تابعًا لـ snapshot .

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

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

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

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

  • ‫snapshot هو معرّف لكائن XrSpatialSnapshotEXT .
  • تحتوي info على معلومات حول المخزن المؤقت المطلوب البحث فيه.
  • bufferCapacityInput هي سعة المصفوفة، أو 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 إذا لم يكن XrSpatialBufferGetInfoEXT :: bufferId تابعًا لـ snapshot .

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

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

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

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

  • ‫snapshot هو معرّف لكائن XrSpatialSnapshotEXT .
  • تحتوي info على معلومات حول المخزن المؤقت المطلوب البحث فيه.
  • bufferCapacityInput هي سعة المصفوفة، أو 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 إذا لم يكن XrSpatialBufferGetInfoEXT :: bufferId تابعًا لـ snapshot .

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

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

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

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

  • ‫snapshot هو معرّف لكائن XrSpatialSnapshotEXT .
  • تحتوي info على معلومات حول المخزن المؤقت المطلوب البحث فيه.
  • bufferCapacityInput هي سعة المصفوفة، أو 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 إذا لم يكن XrSpatialBufferGetInfoEXT :: bufferId تابعًا لـ snapshot .

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

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

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

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

  • ‫snapshot هو معرّف لكائن XrSpatialSnapshotEXT .
  • تحتوي info على معلومات حول المخزن المؤقت المطلوب البحث فيه.
  • bufferCapacityInput هي سعة المصفوفة، أو 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 إذا لم يكن XrSpatialBufferGetInfoEXT :: bufferId تابعًا لـ snapshot .

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

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

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

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

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • استبدِل bufferId بـ XrSpatialBufferIdEXT للمخزن المؤقت الذي تريد استرداد بياناته.

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

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

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

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

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

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

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

يمكن للتطبيق استخدام 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_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 يجب أن يكون مؤشرًا إلى مصفوفة من قيم XrSpatialComponentTypeEXT الصالحة componentTypeCount
  • يجب أن يكون baseSpace مقابض XrSpace صالحًا
  • يجب أن تكون قيمة المَعلمة entityCount أكبر من 0
  • يجب أن يكون كل من baseSpace وعناصر entities قد تم إنشاؤها أو تخصيصها أو استرجاعها من XrSession نفسه

إتلاف اللقطة

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

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

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

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

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

أمان سلاسل المحادثات

  • يجب مزامنة حساب snapshot وأي أسماء مستخدمين للأطفال بشكل خارجي

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS

تعذُّر

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

المكوّنات الشائعة

ثنائي الأبعاد محدود

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

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

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

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

  • ‫center هو XrPosef يحدّد المركز الهندسي للمكوّن الثنائي الأبعاد المحصور.
  • extents هي حدود المكوّن الثنائي الأبعاد المحصور على طول المحور x (extents.width) والمحور y (extents.height)، ويتم توسيطها على center .

يشير extents الخاص بـ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT إلى حجم العنصر في المستوى x-y لنظام الإحداثيات الخاص بالمستوى. يشير المستوى الذي يضم موضعًا {0, 0, 0} ودورانًا {0, 0, 0, 1} (بدون دوران) ومدى {1, 1} إلى مستوى يبلغ حجمه مترًا واحدًا × مترًا واحدًا ويتمركز عند {0, 0, 0} مع توجيه متجه عادي للوجه الأمامي نحو الاتجاه +Z في مساحة المكوّن.

X X Y Y Z Z Height Height Y Y Z Z X X Vertical plane Vertical plane Horizontal Plane Horizontal Plane Width Width Width Width Height Height

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

ملاحظة

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

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

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

يتم تعريف بنية 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_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 .

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

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

يتم تعريف بنية 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_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 فقط .

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

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

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

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

  • يُحصي التطبيق أولاً الإمكانات المكانية للنظام باستخدام 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 جديدًا يوفّر بيانات إضافية عن عنصر مكاني،

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

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

  • إذا كان أحد الإضافات يحدّد 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
|====

وحدات ماكرو جديدة

أنواع القواعد الجديدة

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

أنواع العناصر الجديدة

الأوامر الجديدة

بنى جديدة

عمليات التعداد الجديدة

ثوابت التعداد الجديدة

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • تمديد XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • تمديد XrResult :

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

  • تمديد XrStructureType :

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

المشاكل

  • هل يستند الكيان الفردي دائمًا إلى قدرة واحدة فقط؟

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

سجلّ الإصدارات

  • المراجعة 1، ‎12/04/2024 (نيهيف جاين، Google)

    • الوصف الأوّلي للإضافة