بدء استخدام OpenXR في Android XR

أجهزة XR المشمولة

تساعدك هذه الإرشادات في إنشاء تجارب لهذه الأنواع من أجهزة XR.

مزيد من المعلومات حول أنواع أجهزة XR →

سماعات الرأس بنظام الواقع الممتد

نظارات سلكية بنظام الواقع الممتد

مزيد من المعلومات حول أنواع أجهزة XR →

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

ضبط ملف البيان الخاص بتطبيقك

كما هو الحال مع مشاريع تطبيقات Android الأخرى، يجب أن يتضمّن تطبيق Android XR ملف AndroidManifest.xml يتضمّن إعدادات بيان محدّدة. يصف ملف البيان المعلومات الأساسية عن تطبيقك لأدوات إصدار Android ونظام التشغيل Android وGoogle Play. لمزيد من المعلومات، يُرجى الاطّلاع على دليل نظرة عامة على بيان التطبيق.

ملاحظة: على الرغم من أنّ التطبيقات المصمَّمة باستخدام Unity أو Unreal Engine أو Godot لنظام التشغيل Android XR تستند إلى OpenXR، لن تحتاج إلى إضافة معظم عناصر أو سمات ملف البيان هذه يدويًا إذا كنت تستخدم المكوّنات الإضافية الرسمية لنظام التشغيل Android XR في هذه المحرّكات. تضبط المكوّنات الإضافية للمحرّك والإعدادات المسبقة للتصدير ملف البيان لتطبيقك استنادًا إلى إعدادات المشروع والإصدار.

بالنسبة إلى التطبيقات المميّزة في الواقع الممتد، يجب أن يحتوي ملف البيان على العناصر والسمات التالية:

سمة PROPERTY_XR_ACTIVITY_START_MODE

تتيح السمة android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" للنظام معرفة أنّه يجب تشغيل نشاط في وضع معيّن عند بدء النشاط.

تحتوي هذه السمة على القيم التالية:

• XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED (OpenXR فقط)

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

يتم تشغيل التطبيقات التي تم إنشاؤها باستخدام OpenXR في "المساحة الكاملة"، ويجب أن تستخدم وضع البدء XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED. تشير "المساحة الكاملة غير المُدارة" إلى Android XR بأنّ التطبيق يستخدم OpenXR.

ملاحظة: إذا كنت تستخدم إحدى حزم Android XR لمنصة Unity، فسيتم تشغيل تطبيقك أيضًا في المساحة الكاملة. ومع ذلك، لست بحاجة إلى إضافة هذا إلى ملف البيان يدويًا. تنشئ حِزم Unity ملف البيان لتطبيقك استنادًا إلى إعدادات المشروع والإصدار.

<manifest ... >

   <application ... >
       <property
           android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
           android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED" />
       <activity
           android:name="com.example.myapp.MainActivity" ... >

           <intent-filter>
               <action android:name="android.intent.action.MAIN" />

               <category android:name="android.intent.category.LAUNCHER" />
               <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />
           </intent-filter>
       </activity>
   </application>
</manifest>

سمة PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED

تشير السمة android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED" إلى أنّه يجب تشغيل التطبيق بنوع معيّن من الحدود. يجب أن يحدّد تطبيقك XR_BOUNDARY_TYPE_LARGE إذا كان مصمَّمًا للسماح للمستخدمين بالتنقّل في مساحتهم الفعلية. لا يقدّم تحديد XR_BOUNDARY_TYPE_NO_RECOMMENDATION أي اقتراحات لنوع حدود الأمان، لذا يستخدم النظام النوع المستخدَم حاليًا.

<manifest ... >

   <application ... >
       <property
           android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED"
           android:value="XR_BOUNDARY_TYPE_LARGE" />
   </application>
</manifest>

خصائص الحاوية المكانية

إذا كان تطبيقك يستخدم الإضافة XR_EXT_spatial_container (التي تم تقديمها في المستوى 4 من واجهة برمجة التطبيقات Spatial API) لعرض المحتوى في وحدات تخزين ثلاثية الأبعاد محدودة أو لوحات ثنائية الأبعاد بالإضافة إلى طرق العرض الشاملة، يمكنك الإعلان عن سمات البيان التالية على مستوى <activity> أو <application> لتقديم تلميحات حول التشغيل إلى وقت التشغيل:

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES: يحدّد أوضاع الحدود التي يستخدمها النشاط، مفصولة بـ |.

  القيم الصالحة هي:

  • "2d_panel"
  • "bounded"
  • "immersive"

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE: تحدّد هذه السمة وضع الحدود الأولية للنشاط عند تشغيله.

  القيم الصالحة هي:

  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED

ملاحظة: تحلّ هذه السمات محلّ فئة فلتر الأهداف <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> عند استخدام XR_EXT_spatial_container.

<manifest ... >

   <application ... >
       <activity
           android:name="com.example.myapp.MainActivity" ... >
           <property
               android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
               android:value="bounded|immersive" />
           <property
               android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
               android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED" />
       </activity>
   </application>
</manifest>

<يستخدم المكتبة الأصلية> OpenXR

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

<manifest ... >

    <application ... >

    <uses-native-library android:name="libopenxr.google.so" android:required="false" />

       <activity
           android:name="com.example.myapp.MainActivity" ... >

           <intent-filter>
               <action android:name="android.intent.action.MAIN" />

               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>
        </activity>
    </application>
</manifest>

ميزات PackageManager لتطبيقات الواقع الممتد

عند توزيع التطبيقات من خلال "متجر Google Play"، يمكنك تحديد ميزات الأجهزة أو البرامج المطلوبة في بيان التطبيق. يسمح عنصر uses-feature لـ "متجر Google Play" بفلترة التطبيقات التي تظهر للمستخدمين بشكل مناسب.

تتوفّر الميزات التالية في التطبيقات المميّزة للواقع الممتد.

android.software.xr.api.openxr

يجب أن تتضمّن التطبيقات التي تستهدف نظام التشغيل Android XR والتي تم إنشاؤها باستخدام OpenXR أو Unity هذه الميزة في بيان التطبيق مع ضبط السمة android:required على true.

بالنسبة إلى التطبيقات التي تستخدم حزمة Android XR Extensions for Unity بالإصدار 1.0.0 أو إصدار أحدث أو حزمة Unity OpenXR: Android XR بالإصدار 0.5.0-exp.1 أو إصدار أحدث، ليس من الضروري إضافة هذا العنصر يدويًا إلى ملف بيان التطبيق. ستُدخل هاتان الحزمتان هذا العنصر في بيان التطبيق نيابةً عنك.

قد تحدّد الأجهزة إصدارًا لهذه الميزة، وهو يشير إلى أعلى إصدار من OpenXR يتوافق مع الجهاز. وتمثّل وحدات البت الـ 16 الأعلى الرقم الرئيسي، بينما تمثّل وحدات البت الـ 16 الأدنى الرقم الثانوي. على سبيل المثال، لتحديد الإصدار 1.1 من OpenXR، يتم ضبط القيمة على "0x00010001".

يمكن للتطبيقات استخدام إصدار الميزة للإشارة إلى الحدّ الأدنى من إصدار OpenXR الذي يتطلّبه التطبيق. على سبيل المثال، إذا كان تطبيقك يتطلّب الإصدار 1.1 من OpenXR، يجب الإعلان عن الميزة التالية:

<uses-feature android:name="android.software.xr.api.openxr"
    android:version="0x00010001"
    android:required="true" />

android.software.xr.api.spatial

يمكن لتطبيقات OpenXR التي تتطلّب إضافات تم تقديمها في إصدار معيّن من واجهة برمجة التطبيقات Spatial API في Android XR الإعلان عن ميزة android.software.xr.api.spatial مع ضبط android:version على الحدّ الأدنى المطلوب لمستوى واجهة برمجة التطبيقات Spatial API (مثل "1" أو "2" أو "3" أو "4"). يُرجى الاطّلاع على إنشاء تطبيقات باستخدام إضافات OpenXR المتوافقة للتحقّق من إصدار واجهة برمجة التطبيقات Spatial API المطلوب لكل إضافة.

<!-- Indicates that the app requires Android XR Spatial API Level 4 or higher. -->
<uses-feature android:name="android.software.xr.api.spatial"
    android:version="4"
    android:required="true" />

android.hardware.xr.input.controller

تشير هذه الميزة إلى أنّ التطبيق يتطلّب إدخالاً من وحدة تحكّم في الحركة عالية الدقة بست درجات حرية (6DoF) ليعمل بشكل صحيح. إذا كان تطبيقك يتوافق مع وحدات التحكّم ولا يمكنه العمل بدونها، اضبط القيمة على true. إذا كان تطبيقك يتيح استخدام وحدات التحكّم ولكن يمكن تشغيله بدونها، اضبطه على false.

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

<!-- Sets android:required to true, indicating that your app can't function on devices without controllers. -->
<uses-feature android:name="android.hardware.xr.input.controller" android:required="true" />

android.hardware.xr.input.hand_tracking

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

ملاحظة: لا يلزم استخدام هذه العلامة لرصد الإيماءات الأساسية، مثل التصغير أو التكبير بإصبعين، والنقر، والتوجيه، والقبض.

<!-- Sets android:required to true, indicating that your app can't function on devices without hand tracking. -->
<uses-feature android:name="android.hardware.xr.input.hand_tracking" android:required="true" />

android.hardware.xr.input.eye_tracking

تشير هذه العلامة إلى أنّ التطبيق يتطلّب تتبُّع العين بدقة عالية لكي تعمل ميزة الإدخال بشكل صحيح. إذا كان تطبيقك يتيح تتبُّع حركة العين للإدخال ولا يمكنه العمل بدونه، اضبط القيمة على true. إذا كان تطبيقك يتيح تتبُّع العين للإدخال، ولكن يمكن تشغيله بدون ذلك، اضبطه على false.

<!-- Sets android:required to true, indicating that your app can't function on devices without eye tracking. -->
<uses-feature android:name="android.hardware.xr.input.eye_tracking" android:required="true" />

android.hardware.xr.input.face_tracking

تشير هذه العلامة إلى أنّ التطبيق يتطلّب أجهزة تتبُّع تعابير الوجه ليعمل بشكل صحيح. إذا كان تطبيقك يتيح تتبُّع تعابير الوجه ولا يمكنه العمل بدونه، اضبط القيمة على true. إذا كان تطبيقك يتيح تتبُّع تعابير الوجه، ولكن يمكنه العمل بدونه، اضبطه على false.

<!-- Sets android:required to true, indicating that your app can't function on devices without face tracking. -->
<uses-feature android:name="android.hardware.xr.input.face_tracking" android:required="true" />

android.hardware.location.gps

تشير هذه العلامة إلى أنّ التطبيق يستخدم الموقع الجغرافي الدقيق لنظام تحديد المواقع العالمي (GPS) على الجهاز، مثل عند استخدام إضافات OpenXR الجغرافية المكانية (XR_ANDROID_geospatial وXR_ANDROID_geospatial_anchor). اضبط android:required على true إذا كان تطبيقك لا يعمل بدون أجهزة GPS، أو false إذا كان بإمكانه العمل بدونها.

<uses-feature android:name="android.hardware.location.gps" android:required="false" />

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

التعرّف على أذونات OpenXR

تصل العديد من إضافات OpenXR إلى بيانات أجهزة الاستشعار والإمكانات التي تتعلّق بالخصوصية. لاستخدام هذه الإضافات، يجب أن يصرّح تطبيقك عن عناصر <uses-permission> المطلوبة في ملف AndroidManifest.xml وأن يطلب الحصول على الأذونات الخطيرة في وقت التشغيل قبل استدعاء دوال OpenXR المقابلة.

<manifest ... >
    <!-- Example dangerous permissions required by specific OpenXR extensions -->
    <uses-permission android:name="android.permission.SCENE_UNDERSTANDING_COARSE" />
    <uses-permission android:name="android.permission.HAND_TRACKING" />
    ...
</manifest>

يلخّص الجدول التالي أذونات Android الخطيرة التي تتطلّبها إضافات OpenXR المتوافقة على Android XR. للحصول على تفاصيل كاملة حول أذونات الواقع الممتد في جميع حِزم تطوير البرامج (SDK)، يُرجى الاطّلاع على مقالة فهم أذونات الواقع الممتد.

الإذن	الإمكانات	إضافات OpenXR
android.permission.EYE_TRACKING_COARSE	وضعية العين وحالتها واتجاهها بدقة منخفضة (مثل الصور الرمزية)	XR_ANDROID_eye_tracking (xrGetCoarseTrackingEyesInfoANDROID)
android.permission.EYE_TRACKING_FINE	تتبُّع نظرات العين بدقة عالية لتحديد العناصر وإدخالها والتفاعل معها، بالإضافة إلى تقنية foveated rendering التي تعتمد على تتبُّع نظرات العين.	XR_ANDROID_eye_tracking (xrGetFineTrackingEyesInfoANDROID) XR_EXT_eye_gaze_interaction XR_META_foveation_eye_tracked XR_VARJO_foveated_rendering
android.permission.FACE_TRACKING	تتبُّع أشكال مزج الوجه وعرض تعابير الوجه	XR_ANDROID_face_tracking XR_ANDROID_face_tracking_data_source
android.permission.RECORD_AUDIO	يشير ذلك إلى الإدخال الصوتي لمصادر بيانات تتبُّع تعابير الوجه المستندة إلى الصوت.	XR_ANDROID_face_tracking_data_source
android.permission.HAND_TRACKING	تتبُّع أوضاع مفاصل اليد وسرعاتها وحالة التصويب وتمثيل شبكة اليد	XR_ANDROID_hand_mesh XR_EXT_hand_tracking XR_FB_hand_tracking_aim XR_FB_hand_tracking_mesh
android.permission.BODY_TRACKING	تتبُّع وضعيات مفاصل الجسم ونِسب الهيكل العظمي	XR_ANDROID_body_tracking
android.permission.SCENE_UNDERSTANDING_COARSE	تتبُّع الطائرات، وتتبُّع العناصر، وتتبُّع الصور/العلامات/رموز الاستجابة السريعة، والمثبّتات، والثبات، وتتبُّع الأشعة مقابل العناصر القابلة للتتبُّع، وتقدير الإضاءة، وشبكات العبور.	XR_ANDROID_anchor_sharing_export XR_ANDROID_composition_layer_passthrough_mesh XR_ANDROID_device_anchor_persistence XR_ANDROID_light_estimation XR_ANDROID_raycast XR_ANDROID_spatial_anchor_space XR_ANDROID_spatial_component_subsumed_by XR_ANDROID_spatial_discovery_bounds XR_ANDROID_spatial_entity_bound_anchor XR_ANDROID_spatial_object_tracking XR_ANDROID_trackables XR_ANDROID_trackables_image XR_ANDROID_trackables_marker XR_ANDROID_trackables_object XR_ANDROID_trackables_qr_code XR_EXT_spatial_anchor XR_EXT_spatial_image_tracking XR_EXT_spatial_marker_tracking XR_EXT_spatial_mesh_tracking XR_EXT_spatial_object_tracking XR_EXT_spatial_persistence XR_EXT_spatial_persistence_operations XR_EXT_spatial_plane_tracking
android.permission.SCENE_UNDERSTANDING_FINE	ميزات "تركيبات العمق" و"تداخل المشاهد" و"تقدير الإضاءة في الخريطة المكعبة" و"تتبُّع الأشعة في العمق" و"التعليقات التوضيحية المكانية".	XR_ANDROID_depth_texture XR_ANDROID_light_estimation_cubemap XR_ANDROID_scene_meshing XR_ANDROID_spatial_annotation_tracking XR_ANDROID_spatial_discovery_raycast
android.permission.ACCESS_FINE_LOCATION	الموقع الجغرافي والاتجاه الدقيقان بالنسبة إلى الأرض لتتبُّع المواقع الجغرافية والمثبّتات	XR_ANDROID_geospatial XR_ANDROID_geospatial_anchor

الخطوات التالية

بعد الانتهاء من ضبط ملف البيان الخاص بتطبيقك ومراجعة المعلومات المهمة، يمكنك استكشاف طرق إنشاء التطبيقات باستخدام OpenXR:

• الإنشاء باستخدام إضافات OpenXR المتوافقة
• الإنشاء باستخدام محرّكات البحث المتاحة