איך מתחילים להשתמש ב-OpenXR ל-Android XR

מכשירי XR רלוונטיים

ההנחיות האלה יעזרו לכם ליצור חוויות למכשירי XR מהסוגים הבאים.

מידע ולמידה על סוגי מכשירי XR ←

מידע ולמידה על סוגי מכשירי XR ←

לפני שמתחילים לפתח באמצעות תוספי OpenXR נתמכים או מנוע נתמך, חשוב לעיין בדרישות לגבי הגדרת המניפסט וההרשאות שמפורטות בקטעים הבאים כדי לוודא שהאפליקציה מוגדרת לפיתוח XR.

הגדרת קובץ המניפסט של האפליקציה

כמו בפרויקטים אחרים של אפליקציות ל-Android, לאפליקציה ל-Android XR צריך להיות קובץ AndroidManifest.xml עם הגדרות מניפסט ספציפיות. קובץ המניפסט מתאר מידע חיוני על האפליקציה לכלי ה-build של Android, למערכת ההפעלה Android ול-Google Play. מידע נוסף זמין במדריך הסקירה הכללית של קובץ המניפסט של האפליקציה.

באפליקציות 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.

<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 (שהוצג ברמת Spatial API‏ 4) כדי להציג תוכן בנפחים תלת-ממדיים מוגבלים או בלוחות דו-ממדיים בנוסף לתצוגות סוחפות מלאות, אתם יכולים להצהיר על מאפייני המניפסט הבאים ברמה <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

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

<uses-native-library> 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 לאפליקציות XR

כשאתם מפיצים אפליקציות דרך חנות Google Play, אתם יכולים לציין את תכונות החומרה או התוכנה הנדרשות בקובץ המניפסט של האפליקציה. הרכיב uses-feature מאפשר לחנות Play לסנן בצורה מתאימה את האפליקציות שמוצגות למשתמשים.

התכונות הבאות ספציפיות לאפליקציות שמותאמות ל-XR.

android.software.xr.api.openxr

אפליקציות שמטרגטות את פלטפורמת Android XR ונוצרו באמצעות OpenXR או Unity חייבות לכלול את התכונה הזו בקובץ מניפסט של אפליקציה, כשהמאפיין android:required מוגדר לערך true.

באפליקציות שמשתמשות בגרסה 1.0.0 ומעלה של Android XR Extensions Package for Unity או בגרסה 0.5.0-exp.1 ומעלה של Unity OpenXR: Android XR Package, לא צריך להוסיף את הרכיב הזה באופן ידני למניפסט של האפליקציה. שתי החבילות האלה יוסיפו את הרכיב הזה לקובץ המניפסט של האפליקציה בשבילכם.

במכשירים אפשר לציין גרסה לתכונה הזו, שמציינת את הגרסה הגבוהה ביותר של OpenXR שנתמכת במכשיר. ‫16 הביטים הגבוהים יותר מייצגים את המספר הראשי, ו-16 הביטים הנמוכים יותר מייצגים את המספר המשני. לדוגמה, כדי לציין את גרסה 1.1 של OpenXR, הערך יהיה "0x00010001".

אפליקציות יכולות להשתמש בגרסת התכונה כדי לציין את הגרסה המינימלית של OpenXR שהאפליקציה דורשת. לדוגמה, אם האפליקציה דורשת תמיכה ב-OpenXR בגרסה 1.1, צריך להצהיר על התכונה הבאה:

<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

התכונה הזו מציינת שהאפליקציה דורשת קלט מבקר תנועה מדויק עם 6 דרגות חופש (6DoF) כדי לפעול כמו שצריך. אם האפליקציה תומכת בבקרים ולא יכולה לפעול בלעדיהם, צריך להגדיר את הערך ל-true. אם האפליקציה תומכת בבקרים אבל יכולה לפעול בלעדיהם, צריך להגדיר אותה לערך false.

<!-- 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. פרטים מלאים על הרשאות XR בכל ערכות ה-SDK זמינים במאמר הסבר על הרשאות ל-XR.

השלבים הבאים

אחרי שסיימתם להגדיר את המניפסט של האפליקציה ולקרוא את המידע החשוב, אתם יכולים לבדוק איך אפשר לפתח באמצעות OpenXR:

• פיתוח באמצעות תוספי OpenXR נתמכים
• יצירת קמפיינים במנועים נתמכים